sleelavirin_scan.py
antivirus/tools/sleelavirin_scan.py · 430 line(s) · py
#!/usr/bin/env python3
"""Native-first Sleelavirin coordinator with bounded, explicit ClamAV workers."""
import argparse
import fnmatch
import hashlib
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
from datetime import datetime, timezone
from concurrent.futures import ThreadPoolExecutor, as_completed
def size_arg(value):
value = value.strip().lower()
scale = 1
if value.endswith("k"):
scale, value = 1024, value[:-1]
elif value.endswith("m"):
scale, value = 1024 ** 2, value[:-1]
elif value.endswith("g"):
scale, value = 1024 ** 3, value[:-1]
try:
number = int(value)
if number < 0:
raise ValueError()
return number * scale
except ValueError as exc:
raise argparse.ArgumentTypeError("use a non-negative byte count or K/M/G suffix") from exc
def stamp_from_stat(stat):
return (
stat.st_size,
getattr(stat, "st_mtime_ns", int(stat.st_mtime * 1e9)),
getattr(stat, "st_ctime_ns", int(stat.st_ctime * 1e9)),
getattr(stat, "st_ino", 0),
stat.st_mode,
)
def file_stamp(path):
# Include ctime and file mode as extra mutation signals. These do not eliminate
# filesystem races, but catch more changes than size/mtime/inode alone.
return stamp_from_stat(path.stat())
def enumerate_files(inputs, depth_limit, follow, excludes, extensions, size_limit):
output, seen_files, seen_dirs = [], set(), set()
incomplete = False
for item in inputs:
root = Path(item).expanduser()
try:
if not root.exists():
print(f"ERROR path does not exist: {root}", file=sys.stderr)
incomplete = True
continue
if root.is_file():
candidates = [root]
elif root.is_dir():
candidates = []
root_depth = len(root.resolve().parts)
def walk_error(exc):
nonlocal incomplete
print(f"ERROR directory walk: {exc}", file=sys.stderr)
incomplete = True
for current, dirs, names in os.walk(root, followlinks=follow, onerror=walk_error):
here = Path(current)
try:
real_dir = str(here.resolve())
if real_dir in seen_dirs:
dirs[:] = []
continue
seen_dirs.add(real_dir)
depth = len(here.resolve().parts) - root_depth
except OSError as exc:
print(f"ERROR directory {here}: {exc}", file=sys.stderr)
incomplete = True
dirs[:] = []
continue
dirs[:] = sorted(
d for d in dirs
if (follow or not (here / d).is_symlink())
and not any(fnmatch.fnmatch(str(here / d), pattern) or fnmatch.fnmatch(d, pattern) for pattern in excludes)
)
if depth_limit and depth >= depth_limit:
dirs[:] = []
candidates.extend(here / name for name in sorted(names))
else:
print(f"ERROR unsupported path: {root}", file=sys.stderr)
incomplete = True
continue
for path in candidates:
try:
if path.is_symlink() and not follow:
continue
if not path.is_file():
continue
resolved = str(path.resolve())
if resolved in seen_files:
continue
if any(fnmatch.fnmatch(str(path), pattern) or fnmatch.fnmatch(path.name, pattern) for pattern in excludes):
continue
if extensions and path.suffix.lower() not in extensions:
continue
if path.stat().st_size > size_limit:
print(f"SKIPPED_TOO_LARGE {path}")
incomplete = True
continue
seen_files.add(resolved)
output.append(path)
except OSError as exc:
print(f"ERROR file {path}: {exc}", file=sys.stderr)
incomplete = True
except OSError as exc:
print(f"ERROR path {root}: {exc}", file=sys.stderr)
incomplete = True
return output, incomplete
def native_scan(executable, database, path, initial_stamp=None, timeout=120):
try:
before = file_stamp(path)
if initial_stamp is not None and before != initial_stamp:
return "ERROR", path, f"ERROR_CHANGED_BEFORE_SCAN {path}"
result = subprocess.run(
[str(executable), "--database", str(database), str(path)],
capture_output=True, text=True, check=False, timeout=timeout
)
output = (result.stdout + result.stderr).strip()
try:
after = file_stamp(path)
except OSError as exc:
return "ERROR", path, f"ERROR_AFTER_SCAN {path}: {exc}"
if before != after:
return "ERROR", path, f"ERROR_CHANGED_DURING_SCAN {path}"
if result.returncode == 0:
return "NO_MATCH", path, output or f"NO_MATCH {path}"
if result.returncode == 1 and "DETECTED " in output:
return "DETECTED", path, output
return "ERROR", path, output or f"ERROR {path} exit={result.returncode}"
except subprocess.TimeoutExpired:
return "ERROR", path, f"ERROR_SCAN_TIMEOUT {path} after {timeout}s"
except OSError as exc:
return "ERROR", path, f"ERROR {path}: {exc}"
def clamav_scan_one(executable, path, size_limit, scan_limit, recursion_limit, initial_stamp=None, timeout=120):
try:
before = file_stamp(path)
if initial_stamp is not None and before != initial_stamp:
return "ERROR", path, f"ERROR_CHANGED_BEFORE_SCAN {path}"
command = [
executable, "--infected", "--no-summary",
f"--max-filesize={size_limit}", f"--max-scansize={scan_limit}",
f"--max-recursion={recursion_limit}", "--", str(path)
]
result = subprocess.run(command, capture_output=True, text=True, check=False, timeout=timeout)
output = (result.stdout + result.stderr).strip()
try:
after = file_stamp(path)
except OSError as exc:
return "ERROR", path, f"ERROR_AFTER_SCAN {path}: {exc}"
if before != after:
return "ERROR", path, f"ERROR_CHANGED_DURING_SCAN {path}"
if result.returncode == 0:
return "NO_MATCH", path, output or f"CLAMAV_NO_MATCH {path}"
if result.returncode == 1:
detected_lines = [line for line in result.stdout.splitlines() if " FOUND" in line]
if detected_lines:
return "DETECTED", path, "\n".join(detected_lines)
return "ERROR", path, f"CLAMAV_ERROR detection exit without a parseable file verdict: {path}"
return "ERROR", path, output or f"CLAMAV_ERROR {path} exit={result.returncode}"
except subprocess.TimeoutExpired:
return "ERROR", path, f"ERROR_CLAMAV_TIMEOUT {path} after {timeout}s"
except OSError as exc:
return "ERROR", path, f"ERROR starting ClamAV for {path}: {exc}"
def safe_quarantine(path, destination, scanned_roots, expected_stamp):
"""Copy detections without overwriting a destination, then remove the unchanged source.
O_NOFOLLOW is used where supported. Exclusive destination creation prevents a
pre-existing or racing filename from being overwritten. This narrows filesystem
races but is not a substitute for snapshot-based scanning on hostile filesystems.
"""
if path.is_symlink():
raise ValueError("refusing to quarantine a symbolic link; scan and quarantine its target explicitly")
source = path.resolve(strict=True)
dest = destination.resolve()
if source == dest or dest in source.parents:
raise ValueError("quarantine destination is the scanned file or an ancestor of it")
for root in scanned_roots:
root_path = Path(root).expanduser()
try:
if root_path.is_dir() and (dest == root_path.resolve() or root_path.resolve() in dest.parents):
raise ValueError("quarantine directory must not be inside a scanned directory")
except OSError as exc:
raise ValueError(f"cannot validate scan root {root_path}: {exc}") from exc
if file_stamp(path) != expected_stamp:
raise ValueError("file changed after detection; refusing to quarantine a changed file")
destination.mkdir(parents=True, exist_ok=True)
source_flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
source_fd = os.open(path, source_flags)
target = None
target_fd = None
try:
if stamp_from_stat(os.fstat(source_fd)) != expected_stamp:
raise ValueError("opened file differs from the detected file; refusing quarantine")
index = 0
while True:
name = path.name if index == 0 else f"{path.stem}.{index}{path.suffix}"
candidate = destination / name
try:
target_fd = os.open(candidate, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
target = candidate
break
except FileExistsError:
index += 1
source_hash = hashlib.sha256()
with os.fdopen(source_fd, "rb") as source_handle:
source_fd = -1
with os.fdopen(target_fd, "wb") as target_handle:
target_fd = -1
while True:
chunk = source_handle.read(1024 * 1024)
if not chunk:
break
source_hash.update(chunk)
target_handle.write(chunk)
target_handle.flush()
os.fsync(target_handle.fileno())
if stamp_from_stat(os.fstat(source_handle.fileno())) != expected_stamp:
raise ValueError("opened source changed during quarantine copy")
if file_stamp(path) != expected_stamp:
raise ValueError("source path changed during quarantine copy; original was retained")
target_hash = hashlib.sha256()
with target.open("rb") as check_handle:
for chunk in iter(lambda: check_handle.read(1024 * 1024), b""):
target_hash.update(chunk)
if target_hash.digest() != source_hash.digest():
raise OSError("quarantine copy integrity check failed")
# Recheck before removal. A tiny path replacement race can remain on filesystems
# without stronger directory-handle primitives, so high-assurance deployments
# should quiesce the source tree or scan a snapshot.
if file_stamp(path) != expected_stamp:
raise ValueError("source changed before removal; original was retained")
path.unlink()
return target
except Exception:
if target is not None:
try:
target.unlink()
except OSError:
pass
raise
finally:
if source_fd >= 0:
os.close(source_fd)
if target_fd is not None and target_fd >= 0:
os.close(target_fd)
def safe_console(value):
"""Escape control characters in untrusted paths and engine output."""
return "".join(ch if ch.isprintable() else "\\u%04x" % ord(ch) for ch in str(value))
def unique_paths(paths):
"""Keep first occurrence of each path while preserving order."""
return list(dict.fromkeys(paths))
def main():
frozen = bool(getattr(sys, "frozen", False))
package = Path(sys.executable).resolve().parent if frozen else Path(__file__).resolve().parent.parent
parser = argparse.ArgumentParser(description="Native-first Sleelavirin scanner with optional ClamAV secondary engine.")
parser.add_argument("--engine", choices=("native", "clamav", "both"), default="native")
native_name = "sleelavirin-native.exe" if os.name == "nt" else "sleelavirin-native"
native_default = package / native_name if frozen else package / "build" / ("sleelavirin-scan.exe" if os.name == "nt" else "sleelavirin-scan")
parser.add_argument("--native-scanner", default=str(native_default))
parser.add_argument("--database", default=str(package / "signatures" / "native-sha256.txt"))
parser.add_argument("--clamscan", default="clamscan")
parser.add_argument("--max-depth", type=int, default=8, help="directory depth; 0 means unlimited")
parser.add_argument("--jobs", type=int, default=1, help="concurrent native workers")
parser.add_argument("--clamav-jobs", type=int, default=1, help="concurrent ClamAV processes (CPU/resource limit)")
parser.add_argument("--max-file-size", type=size_arg, default=100 * 1024 * 1024, help="bytes or K/M/G; default 100M")
parser.add_argument("--clamav-max-scansize", type=size_arg, default=400 * 1024 * 1024, help="ClamAV total bytes scanned per file; default 400M")
parser.add_argument("--clamav-max-recursion", type=int, default=8, help="maximum nested archive recursion for ClamAV")
parser.add_argument("--scan-timeout", type=int, default=120, help="per-file engine timeout in seconds; 0 disables timeout")
parser.add_argument("--exclude", action="append", default=[], metavar="GLOB")
parser.add_argument("--extension", action="append", default=[], metavar=".EXT")
parser.add_argument("--follow-symlinks", action="store_true")
parser.add_argument("--action", choices=("report", "quarantine", "stop"), default="report")
parser.add_argument("--report-json", help="write an atomic JSON scan report to this path")
parser.add_argument("--quarantine-dir", default=str(package / "quarantine"))
parser.add_argument("paths", nargs="+")
args = parser.parse_args()
if args.max_depth < 0 or args.jobs < 1 or args.clamav_jobs < 1 or args.clamav_max_recursion < 0 or args.scan_timeout < 0:
parser.error("depth/recursion must be >= 0 and worker counts must be >= 1")
if args.clamav_max_scansize < args.max_file_size:
parser.error("--clamav-max-scansize should be >= --max-file-size")
extensions = {x.lower() if x.startswith(".") else "." + x.lower() for x in args.extension}
paths, incomplete = enumerate_files(args.paths, args.max_depth, args.follow_symlinks, args.exclude, extensions, args.max_file_size)
if not paths:
print("ERROR: no eligible files found; scan is incomplete", file=sys.stderr)
return 2
initial_stamps = {}
for path in paths:
try:
initial_stamps[path] = file_stamp(path)
except OSError as exc:
print(f"ERROR stat {path}: {exc}", file=sys.stderr)
incomplete = True
# Prevent a quarantine directory from being scanned and then recursively
# receiving files while the same run is in progress.
if args.action == "quarantine":
destination = Path(args.quarantine_dir).expanduser()
try:
resolved_dest = destination.resolve()
for root in args.paths:
candidate = Path(root).expanduser()
if candidate.is_dir() and (resolved_dest == candidate.resolve() or candidate.resolve() in resolved_dest.parents):
print("ERROR quarantine directory must be outside every scanned directory", file=sys.stderr)
return 2
except OSError as exc:
print(f"ERROR validating quarantine directory: {exc}", file=sys.stderr)
return 2
native_exe = Path(args.native_scanner).expanduser()
found, errors = [], 0
records = []
interrupted = False
if args.engine in ("native", "both"):
database = Path(args.database).expanduser()
if not native_exe.is_file() or not database.is_file():
print("ERROR: native scanner or database missing; build with make -C antivirus and check --database/--native-scanner", file=sys.stderr)
return 2
workers = 1 if args.action == "stop" else args.jobs
with ThreadPoolExecutor(max_workers=workers) as pool:
futures = {pool.submit(native_scan, native_exe, database, path, initial_stamps.get(path), args.scan_timeout or None): path for path in paths}
for future in as_completed(futures):
try:
verdict, path, message = future.result()
except Exception as exc:
path = futures[future]
verdict, message = "ERROR", f"ERROR native worker failure for {path}: {type(exc).__name__}: {exc}"
print(safe_console(message))
records.append({"engine": "native", "path": str(path), "verdict": verdict, "message": message})
if verdict == "DETECTED":
found.append(path)
if args.action == "stop":
for pending in futures:
pending.cancel()
interrupted = True
break
elif verdict == "ERROR":
errors += 1
if args.engine in ("clamav", "both") and not (args.action == "stop" and found):
clam = shutil.which(args.clamscan)
if not clam:
print(f"ERROR: ClamAV not found: {args.clamscan}", file=sys.stderr)
return 2
workers = 1 if args.action == "stop" else args.clamav_jobs
with ThreadPoolExecutor(max_workers=workers) as pool:
futures = {pool.submit(clamav_scan_one, clam, path, args.max_file_size, args.clamav_max_scansize, args.clamav_max_recursion, initial_stamps.get(path), args.scan_timeout or None): path for path in paths}
for future in as_completed(futures):
try:
verdict, path, message = future.result()
except Exception as exc:
path = futures[future]
verdict, message = "ERROR", f"ERROR ClamAV worker failure for {path}: {type(exc).__name__}: {exc}"
print(safe_console(message))
records.append({"engine": "clamav", "path": str(path), "verdict": verdict, "message": message})
if verdict == "DETECTED":
found.append(path)
if args.action == "stop":
for pending in futures:
pending.cancel()
break
elif verdict == "ERROR":
errors += 1
unique = unique_paths(found)
if args.action == "quarantine" and unique:
destination = Path(args.quarantine_dir).expanduser()
for path in unique:
try:
target = safe_quarantine(path, destination, args.paths, initial_stamps[path])
print(f"QUARANTINED {path} -> {target}")
except (OSError, ValueError) as exc:
print(f"ERROR quarantine failed for {path}: {exc}", file=sys.stderr)
errors += 1
if interrupted:
incomplete = True
print("INCOMPLETE_SCAN: stopped early after a detection; remaining files were not fully checked", file=sys.stderr)
if incomplete:
print("INCOMPLETE_SCAN: one or more paths/files were skipped or could not be enumerated", file=sys.stderr)
status = "DETECTED" if unique else ("INCOMPLETE" if errors or incomplete else "CLEAN_NO_MATCH")
summary = {"schema": "sleelavirin-scan-report-v1", "finished_at_utc": datetime.now(timezone.utc).isoformat(), "engines": args.engine, "status": status, "complete": not (errors or incomplete), "eligible_file_count": len(paths), "detection_count": len(unique), "error_count": errors, "records": records, "limitations": "CLEAN_NO_MATCH means no enabled engine matched; it is not proof that files are harmless. Native signatures are a limited subset."}
print(f"SCAN_SUMMARY status={status} eligible={len(paths)} detections={len(unique)} errors={errors} complete={str(summary['complete']).lower()}")
if args.report_json:
report_path = Path(args.report_json).expanduser()
try:
report_path.parent.mkdir(parents=True, exist_ok=True)
fd, temp_name = tempfile.mkstemp(prefix=report_path.name + ".", suffix=".tmp", dir=str(report_path.parent))
try:
with os.fdopen(fd, "w", encoding="utf-8") as report:
json.dump(summary, report, indent=2, sort_keys=True)
report.write(chr(10))
report.flush()
os.fsync(report.fileno())
os.replace(temp_name, report_path)
finally:
try:
os.unlink(temp_name)
except OSError:
pass
except OSError as exc:
print(f"ERROR writing scan report: {exc}", file=sys.stderr)
errors += 1
return 1 if unique else (2 if errors or incomplete else 0)
if __name__ == "__main__":
raise SystemExit(main())