unk-scanner 0.1.0__tar.gz

unk_scanner-0.1.0/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-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/unk_scanner/_engine *

unk_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: unk-scanner
+Version: 0.1.0
+Summary: Python CLI and API for static UNK_DeadDrop JavaScript triage (requires Node.js 22+)
+Author: Ilja Krasnjanski
+License-Expression: MIT
+Project-URL: Homepage, https://krasforge.github.io/UNK_DeadDrop/
+Project-URL: Repository, https://github.com/KrasForge/unk-deaddrop-companion
+Project-URL: Research, https://doi.org/10.5281/zenodo.23652298
+Keywords: security,static-analysis,javascript,unk-deaddrop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# unk-scanner for Python
+
+Python CLI and API for the static JavaScript scanner from the [UNK_DeadDrop investigation](https://krasforge.github.io/UNK_DeadDrop/).
+
+Requires Python 3.10+ and **Node.js 22+ on PATH**. The wheel bundles the same JavaScript engine as the npm distribution, plus Acorn 8.17.0. It does not require npm, execute submitted JavaScript, or download code during analysis.
+
+## Installation and usage
+
+Once published:
+
+```sh
+pip install unk-scanner
+python -m unk_scanner suspect.js > findings.json
+python -m unk_scanner --gzip captured-response.js > findings.json
+```
+
+The distribution also installs an `unk-scanner` command. Prefer `python -m unk_scanner` if both npm and Python versions are installed, to make the selected installation explicit.
+
+```python
+from unk_scanner import scan, ScannerError
+
+try:
+    report = scan("suspect.js")
+    print(report["findings"])
+except ScannerError as error:
+    print(error)
+```
+
+## Scope
+
+Reports contain original SHA-256 hashes, byte counts, source locations, findings, limitations, and separate artifact identity records. With `--gzip`, `decoded` records the decompressed hash and size. `artifactMatches` can identify ordinary login code or a shared polyfill; these are context, not malware alerts.
+
+The scanner recognizes literal and selected identifier markers, clipboard writes, and one linked AES-GCM loader pattern. It does not decrypt payloads, resolve general aliases or obfuscated string tables, prove execution, or determine whether a file is safe. Exact identity matches cover only the listed bytes.
+
+Input and decompressed sizes are limited to 8 MiB. Parsing uses a worker with a 10-second deadline and V8 heap limits; reports are capped at 10,000 findings. The Python wrapper applies an additional process timeout. Limit failures return an error rather than a partial report. These controls are not an OS security sandbox. Output can contain input strings and should be handled accordingly.
+
+The CLI returns 0 for completed analysis, including findings, and 2 for errors. The Python API raises `ScannerError` when analysis fails.
+
+Original code is MIT licensed. Bundled Acorn includes its MIT license. No malware samples or active credentials are distributed. See the [companion repository](https://github.com/KrasForge/unk-deaddrop-companion) and [preprint](https://doi.org/10.5281/zenodo.23652298).

unk_scanner-0.1.0/README.md

@@ -0,0 +1,39 @@
+# unk-scanner for Python
+
+Python CLI and API for the static JavaScript scanner from the [UNK_DeadDrop investigation](https://krasforge.github.io/UNK_DeadDrop/).
+
+Requires Python 3.10+ and **Node.js 22+ on PATH**. The wheel bundles the same JavaScript engine as the npm distribution, plus Acorn 8.17.0. It does not require npm, execute submitted JavaScript, or download code during analysis.
+
+## Installation and usage
+
+Once published:
+
+```sh
+pip install unk-scanner
+python -m unk_scanner suspect.js > findings.json
+python -m unk_scanner --gzip captured-response.js > findings.json
+```
+
+The distribution also installs an `unk-scanner` command. Prefer `python -m unk_scanner` if both npm and Python versions are installed, to make the selected installation explicit.
+
+```python
+from unk_scanner import scan, ScannerError
+
+try:
+    report = scan("suspect.js")
+    print(report["findings"])
+except ScannerError as error:
+    print(error)
+```
+
+## Scope
+
+Reports contain original SHA-256 hashes, byte counts, source locations, findings, limitations, and separate artifact identity records. With `--gzip`, `decoded` records the decompressed hash and size. `artifactMatches` can identify ordinary login code or a shared polyfill; these are context, not malware alerts.
+
+The scanner recognizes literal and selected identifier markers, clipboard writes, and one linked AES-GCM loader pattern. It does not decrypt payloads, resolve general aliases or obfuscated string tables, prove execution, or determine whether a file is safe. Exact identity matches cover only the listed bytes.
+
+Input and decompressed sizes are limited to 8 MiB. Parsing uses a worker with a 10-second deadline and V8 heap limits; reports are capped at 10,000 findings. The Python wrapper applies an additional process timeout. Limit failures return an error rather than a partial report. These controls are not an OS security sandbox. Output can contain input strings and should be handled accordingly.
+
+The CLI returns 0 for completed analysis, including findings, and 2 for errors. The Python API raises `ScannerError` when analysis fails.
+
+Original code is MIT licensed. Bundled Acorn includes its MIT license. No malware samples or active credentials are distributed. See the [companion repository](https://github.com/KrasForge/unk-deaddrop-companion) and [preprint](https://doi.org/10.5281/zenodo.23652298).

unk_scanner-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unk-scanner"
+version = "0.1.0"
+description = "Python CLI and API for static UNK_DeadDrop JavaScript triage (requires Node.js 22+)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Ilja Krasnjanski"}]
+keywords = ["security", "static-analysis", "javascript", "unk-deaddrop"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://krasforge.github.io/UNK_DeadDrop/"
+Repository = "https://github.com/KrasForge/unk-deaddrop-companion"
+Research = "https://doi.org/10.5281/zenodo.23652298"
+
+[project.scripts]
+unk-scanner = "unk_scanner:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+unk_scanner = ["_engine/**/*"]

unk_scanner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unk_scanner-0.1.0/src/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-0.1.0/src/unk_scanner/__main__.py

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

unk_scanner-0.1.0/src/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-0.1.0/src/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;
+});