Home /Modules/antivirus/NATIVE-ENGINE.md

NATIVE-ENGINE.md

antivirus/NATIVE-ENGINE.md · 202 line(s) · markdown

Sleelavirin™ Native Engine (C / C++)

Author: Max Rupplin — MEARVK LLC — 2026 Companion to: CLAMAV-REFERENCE-ANALYSIS.md, SCANNING-CONCEPTS-GLOSSARY.md, DEFINITIONS-SOURCING.md

A self-contained, portable, license-clean antivirus scanning engine for SLeeLa users (and anyone who wants a bona fide, auditable AV core). It is original MEARVK code: it copies no code from ClamAV or any other engine, has no third-party runtime dependency, and builds with any C11 + C++17 compiler.

Honesty clause. A CLEAN / NO_MATCH result is never proof that a file is safe. The native engine detects what its definitions describe; for broad coverage, pair it with an external provider (see SCANNERS.md).


What it does

Two independent, composable detection methods over a file's bytes:

  1. Whole-file hash matching — SHA-256 of the whole file vs. a hash index (exact match; zero false positives for that exact file).
  2. Content (byte-pattern) matching — the native Aho–Corasick automaton finds any of many literal byte signatures in a single pass, so it catches known content even when the surrounding file differs (the capability pure hashing lacks).

Plus a fuzzy similarity check (feature fingerprint + Hamming distance) and a Trap-2 heuristic scorer, both already present in the core.


Components (antivirus/src/)

FileLanguageRole
sleelavirin_native.{c,h}C11SHA-256 (file + buffer), hash-index file scan
sleelavirin_scan.{c,h}C11known-file hash map, exact + fuzzy match, fingerprint
sleelavirin_heuristic.{c,h}C11Trap-2 indicator scoring
sleelavirin_ac.{c,h}C11Aho–Corasick multi-pattern content matcher
sleelavirin_sig.{c,h}C11content-signature file format + loader
sleelavirin_bridge.{c,h}C11stable C ABI: request → validate → verdict
sleelavirin_cpp.{cpp,hpp}C++17ergonomic C++ wrapper (RAII, std::optional)
sleelavirin_native_main.cC11the sleelavirin-scan CLI

Artifacts produced by make:


Build & test

cd antivirus
make           # build C lib, C++ lib, tests, and the scanner (POSIX GNU Make)
make test      # build + run all C, C++, native, content, and Python tests
make cpp-test  # just the C++ library test
CC=clang CXX=clang++ make   # use Clang

The engine builds warning-clean under -O2 -Wall -Wextra -Wpedantic (C11 and C++17).

Cross-platform

The engine compiles from one source tree on Windows XP+/7+/10+, macOS (Intel & Apple Silicon), and Linux/Unix. OS differences live only in src/sleelavirin_compat.h. Build options:

See PLATFORMS.md for the full matrix and the Windows XP toolchain notes.


Using the CLI

# Whole-file hash scan:
build/sleelavirin-scan --database signatures/native-sha256.txt file1 file2

# Content (byte-pattern) scan:
build/sleelavirin-scan --content-db tests/content-signatures.slv suspect.bin

# Both at once (each pass reported independently):
build/sleelavirin-scan --database H.txt --content-db C.slv target

Exit codes: 0 = no match for any target, 1 = at least one detection, 2 = a usage error or an unreadable file/database. Output lines are DETECTED <path> : <detail> or NO_MATCH <path>.


Content-signature format (.slv)

A Sleelavirin-specified text format — a deliberately small literal-byte subset (Tier 3 of DEFINITIONS-SOURCING.md), not copied from ClamAV's .ndb:

# comment; blank lines ignored
<name>:<severity>:<flags>:<hex-bytes>

Example (tests/content-signatures.slv): matches a fragment of the EICAR standard AV test string — a safe, industry-standard detection-pipeline marker, not real malware.


Using the C library

#include "sleelavirin_bridge.h"

sleelavirin_bridge_request_t req; sleelavirin_bridge_result_t res;
memset(&req, 0, sizeof req);
snprintf(req.target_path,   sizeof req.target_path,   "%s", path);
snprintf(req.database_path, sizeof req.database_path, "%s", hash_index);
snprintf(req.engine_name,   sizeof req.engine_name,   "native");
req.scope = SLEELAVIRIN_SCOPE_LOCAL;
req.max_file_size_bytes = 256ull * 1024 * 1024;

if (sleelavirin_bridge_validate_request(&req) == 0 &&
    sleelavirin_bridge_scan_native(&req, &res) == 0) {
    printf("%s (%u detections): %s\n", res.verdict, res.detections, res.detail);
}

Direct Aho–Corasick use:

#include "sleelavirin_sig.h"
sleelavirin_sig_stats_t st;
sleelavirin_ac_t *ac = sleelavirin_sig_load_file("defs.slv", &st);   /* compiled */
long n = sleelavirin_ac_scan(ac, buffer, length, on_match, userdata);
sleelavirin_ac_destroy(ac);

Link against build/libsleelavirin.a.


Using the C++ library

#include "sleelavirin_cpp.hpp"

sleelavirin::HashMap map(1024);
sleelavirin::KnownFile k;
k.name = "Demo"; k.provider = "native"; k.rule_id = "R-1"; k.severity = 8;
k.fingerprint = *sleelavirin::FileFingerprint::from_file("known_bad.bin");
map.add(k);

if (auto fp = sleelavirin::FileFingerprint::from_file("suspect.bin"))
    if (auto m = map.scan(*fp))
        std::cout << static_cast<int>(m->confidence) << " " << m->known_name << "\n";

Link against build/libsleelavirin_cpp.a and build/libsleelavirin.a.


Design notes & algorithms


Scope & limits (honest boundaries)