unk-scanner 0.1.0__py3-none-any.whl

unk_scanner/__init__.py

@@ -0,0 +1,65 @@
+"""Python interface to the bundled static JavaScript scanner.
+
+Requires Node.js >=22. Submitted source is parsed, never executed.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+
+__version__ = "0.1.0"
+
+
+class ScannerError(RuntimeError):
+    """The scanner could not produce a complete analysis."""
+
+
+def _command() -> list[str]:
+    node = shutil.which("node")
+    if node is None:
+        raise ScannerError("Node.js 22 or later is required; install Node.js and put node on PATH")
+    try:
+        version = subprocess.run(
+            [node, "--version"], capture_output=True, text=True, timeout=5, check=True
+        ).stdout.strip()
+    except (OSError, subprocess.SubprocessError) as error:
+        raise ScannerError("Could not check the installed Node.js version") from error
+    match = re.fullmatch(r"v(\d+)\.\d+\.\d+(?:[-+].*)?", version)
+    if not match or int(match[1]) < 22:
+        raise ScannerError(f"Node.js 22 or later is required; found {version!r}")
+    return [node, str(Path(__file__).parent / "_engine" / "bin" / "unk-scanner.mjs")]
+
+
+def scan(path: str | Path, *, gzip: bool = False, timeout: float = 30) -> dict:
+    """Return the scanner's JSON result for one file.
+
+    gzip explicitly enables bounded gzip decoding. Findings are review leads;
+    artifactMatches are separate identity records, not malware verdicts.
+    """
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    args = _command() + (["--gzip"] if gzip else []) + ["--", str(path)]
+    try:
+        result = subprocess.run(args, capture_output=True, text=True, encoding="utf-8", timeout=timeout)
+    except (OSError, subprocess.SubprocessError) as error:
+        raise ScannerError(f"Scanner process failed: {error}") from error
+    if result.returncode:
+        raise ScannerError(result.stderr.strip() or f"Scanner exited with code {result.returncode}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise ScannerError("Scanner returned invalid JSON") from error
+
+
+def main() -> int:
+    try:
+        return subprocess.run(_command() + sys.argv[1:], timeout=30).returncode
+    except (ScannerError, OSError, subprocess.SubprocessError) as error:
+        print(f"unk-scanner: {error}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130

unk_scanner/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+raise SystemExit(main())

unk_scanner/_engine/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 UNK_DeadDrop research contributors
+
+This license applies only to original code, tests, configuration and detection
+rules in this companion repository. It does not cover research prose or any
+third-party evidence.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unk_scanner/_engine/bin/unk-scanner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+main(process.argv.slice(2)).catch(error => {
+  process.stderr.write('unk-scanner: ' + error.message + '\n');
+  process.exitCode = 2;
+});