snakecharm 0.1.0__py3-none-any.whl

snakecharm/__init__.py

@@ -0,0 +1,385 @@
+"""snakecharm -- deobfuscate Python without executing it.
+
+    >>> import snakecharm
+    >>> result = snakecharm.crack(open("sample.py", "rb").read())
+    >>> print(result.code)
+    >>> result.complete
+    False
+
+The library API is the primary interface and the CLI is a thin shell over it,
+because the audiences that most need this -- registry scanners, triage
+pipelines, CI gates -- consume it as a library and need deterministic, gradable
+output.
+
+Nothing in the default path executes the sample. See :mod:`snakecharm.evalx`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import (
+    BudgetExceeded,
+    MalformedInput,
+    Opaque,
+    PathTraversal,
+    SnakecharmError,
+    UnsupportedFormat,
+)
+from .evalx.budgets import Budget
+from .ingest.registry import Registry, Unit, default_registry
+from .peel.driver import PeelOptions, PeelResult, peel
+from .peel.layer import Layer, LayerKind
+from .report.emit import write_text
+from .triage.detect import TriageReport, detect
+from .triage.signatures import Detection
+from .unresolved import EXIT_COMPLETE, EXIT_INCOMPLETE, Reason, Unresolved
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "crack",
+    "Options",
+    "Result",
+    "Budget",
+    "Unresolved",
+    "Reason",
+    "Detection",
+    "Layer",
+    "SnakecharmError",
+    "Opaque",
+    "BudgetExceeded",
+    "UnsupportedFormat",
+    "MalformedInput",
+    "PathTraversal",
+    "__version__",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Options:
+    """Knobs for :func:`crack`. Defaults are the safe, deterministic path."""
+
+    budget: Budget = field(default_factory=Budget)
+    max_layers: int | None = 512
+    max_depth: int | None = 128
+    peel_enabled: bool = True
+    detect_enabled: bool = True
+    target_python: tuple[int, int] | None = None
+    """Version to assume when unmarshalling. None means the host version."""
+
+    load_plugins: bool = False
+    """Off by default: third-party adapters run in-process next to malware."""
+
+    decompiler: str | None = None
+    """Force a specific decompiler backend by name, or None to route by version.
+
+    Backends are GPL and are never imported -- they are optional subprocesses
+    discovered on PATH. With none installed, output is annotated disassembly.
+    """
+
+    clean: bool = False
+    """Run the source-cleanup tier over the recovered payload.
+
+    Off by default, and that is a considered position rather than caution. On a
+    sample that peels cleanly the deepest layer *is* the original source, so
+    cleanup has nothing to remove and would only strip its formatting. Cleanup
+    earns its place when the payload is still mangled after the layers come
+    off -- which the caller knows and we do not.
+    """
+
+
+@dataclass(slots=True)
+class Result:
+    """Everything crack() learned, and the artifacts it produced."""
+
+    code: str = ""
+    """Best-effort readable source: the deepest recovered layer."""
+
+    layers: list[Layer] = field(default_factory=list[Layer])
+    detections: list[Detection] = field(default_factory=list[Detection])
+    unresolved: list[Unresolved] = field(default_factory=list[Unresolved])
+    triage: TriageReport | None = None
+    stats: dict[str, Any] = field(default_factory=dict[str, Any])
+    plugins: list[str] = field(default_factory=list[str])
+
+    cleaned: str | None = None
+    """Cleanup output, when requested. A derived view, never the evidence.
+
+    `code` and `layers` remain byte-exact regardless: a layer's header carries
+    a SHA-256 of its own text, and rewriting it would break that contract."""
+
+    clean_report: dict[str, Any] = field(default_factory=dict[str, Any])
+
+    decompiled_by: str | None = None
+    """Which backend produced `code`, for compiled input."""
+
+    is_source: bool = True
+    """False when `code` is disassembly rather than recovered source.
+
+    The two are never conflated: disassembly is real output, but presenting it
+    as source would mislead an analyst about what they are reading.
+    """
+
+    @property
+    def complete(self) -> bool:
+        """True when nothing was left unresolved.
+
+        This is the whole verdict. A deobfuscator either answered the question
+        or it did not; there is no severity ladder, and recognising the
+        obfuscator is not something to report as a problem.
+        """
+        return not self.unresolved
+
+    @property
+    def exit_code(self) -> int:
+        """0 complete, 1 incomplete. (2 is reserved for unusable input, which
+        never produces a Result at all.)"""
+        return EXIT_COMPLETE if self.complete else EXIT_INCOMPLETE
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "version": __version__,
+            "complete": self.complete,
+            "stats": self.stats,
+            "triage": self.triage.to_json() if self.triage else None,
+            "detections": [d.to_json() for d in self.detections],
+            "layers": [
+                {
+                    "index": layer.index,
+                    "kind": layer.kind,
+                    "depth": layer.depth,
+                    "parent": layer.parent,
+                    "provenance": layer.provenance,
+                    "sha256": layer.digest,
+                    "bytes": layer.size(),
+                    "terminal": layer.terminal,
+                    "site": layer.site,
+                }
+                for layer in self.layers
+            ],
+            "unresolved": [u.to_json() for u in self.unresolved],
+            "plugins": self.plugins,
+            "clean": self.clean_report or None,
+            "decompiled_by": self.decompiled_by,
+            "is_source": self.is_source,
+        }
+
+    def save(self, outdir: str | Path) -> Path:
+        """Write the full artifact tree, guarding every path.
+
+        Produces ``deobfuscated.py``, ``report.json``, and ``layers/NN_*`` with
+        a provenance header on each -- so any single file can be traced back to
+        the input without re-running the tool.
+        """
+        outdir = Path(outdir)
+        outdir.mkdir(parents=True, exist_ok=True)
+
+        if self.code:
+            write_text(outdir, "deobfuscated.py", self.code)
+        if self.cleaned is not None:
+            write_text(outdir, "cleaned.py", self.cleaned)
+        write_text(outdir, "report.json", json.dumps(self.to_json(), indent=2) + "\n")
+
+        for layer in self.layers:
+            if layer.kind == LayerKind.CODE and layer.code is not None:
+                from .ir.disasm import format_tree
+
+                body = format_tree(layer.code)
+                suffix = "dis.txt"
+            elif layer.text:
+                body, suffix = layer.text, "py"
+            elif layer.raw is not None:
+                body = f"# {len(layer.raw)} bytes of non-UTF-8 data; not rendered as source\n"
+                suffix = "txt"
+            else:
+                continue
+            write_text(
+                outdir,
+                f"layers/{layer.index:02d}_depth{layer.depth}.{suffix}",
+                f"{layer.header()}\n\n{body}",
+            )
+
+        return outdir
+
+
+def _crack_bytecode(
+    units: list[Unit],
+    data: bytes,
+    result: Result,
+    options: Options,
+    filename: str | None = None,
+) -> Result:
+    """Handle compiled input: one terminal layer per recovered code object.
+
+    There is no decompiler in v0.1, so the output is annotated disassembly. That
+    is stated in a finding rather than implied -- disassembly is not source, and
+    a report that blurred the two would be worse than useless to an analyst.
+    """
+    for index, unit in enumerate(units):
+        layer = Layer(
+            index=index,
+            kind=LayerKind.CODE,
+            code=unit.code,
+            depth=0,
+            chain=list(unit.provenance),
+            terminal=True,
+        )
+        result.layers.append(layer)
+
+    version = units[0].metadata.get("python_version", "unknown") if units else "unknown"
+    if units and units[0].metadata.get("header_repaired"):
+        result.unresolved.append(
+            Unresolved(
+                reason=Reason.DECODE_ERROR,
+                message=(
+                    "no .pyc header was present; the Python version was assumed "
+                    "rather than read, so field decoding may be wrong if it is incorrect"
+                ),
+            )
+        )
+
+    if options.detect_enabled:
+        result.triage = detect(data, None, filename=filename)
+        result.detections = result.triage.detections
+
+    # Try to recover source. Falls through to annotated disassembly, which never
+    # fails -- and which the header labels as disassembly, not source.
+    from .decompile import decompile
+
+    renderings: list[str] = []
+    for index, unit in enumerate(units):
+        rendered = decompile(unit.code, raw_pyc=unit.raw, prefer=options.decompiler)
+        result.unresolved.extend(rendered.unresolved)
+        renderings.append(rendered.header() + rendered.text)
+        if index == 0:
+            result.decompiled_by = rendered.backend
+            result.is_source = rendered.is_source
+    result.code = "\n\n".join(renderings)
+    result.stats = {
+        "layers": len(result.layers),
+        "code_objects": sum(len(list(layer.code.walk())) for layer in result.layers if layer.code),
+        "python_version": version,
+    }
+
+    return result
+
+
+def _run_cleanup(result: Result, options: Options) -> None:
+    """Attach a cleaned view of the recovered source, if asked."""
+    from .clean import CleanOptions, Session
+
+    # No target version here on purpose: the gate ends in `compile()`, which
+    # only ever targets the host, so accepting one would imply a guarantee that
+    # cannot be kept. `CleanOptions` has never had the field -- passing it made
+    # every `--clean` run raise TypeError.
+    session = Session(CleanOptions(budget=options.budget))
+    outcome = session.run(result.code)
+    result.cleaned = outcome.code
+    result.clean_report = {
+        "changed": outcome.changed,
+        "rounds": outcome.rounds,
+        "applied": outcome.applied,
+        "refused": outcome.refused,
+        "rolled_back": outcome.rolled_back,
+        "summary": outcome.summary(),
+    }
+
+
+def crack(
+    data: bytes | str,
+    options: Options | None = None,
+    *,
+    filename: str | None = None,
+) -> Result:
+    """Deobfuscate `data`, executing nothing.
+
+    Accepts raw bytes (preferred -- byte-level detection and PEP 263 handling
+    both need them) or a ``str`` for convenience. `filename` is an optional hint
+    used only by detection; analysis never depends on it.
+    """
+    options = options or Options()
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+
+    result = Result()
+    assume = None
+    if options.target_python is not None:
+        from .ir.codeunit import PyVersion
+
+        assume = PyVersion(*options.target_python)
+
+    registry: Registry = default_registry(load_plugins=options.load_plugins, assume_version=assume)
+    result.plugins = list(registry.loaded_plugins)
+
+    try:
+        units: list[Unit] = registry.extract(data)
+    except UnsupportedFormat:
+        # Detection is byte-level pattern matching -- it needs no adapter, and
+        # gating it behind one refuses exactly when the answer is worth most.
+        # For a packed executable, naming the packer *is* the whole deliverable:
+        # the PyInstaller and Nuitka signatures exist to say "reach for this
+        # tool next", which they can only do on input we cannot ingest.
+        if options.peel_enabled or not options.detect_enabled:
+            raise
+        result.triage = detect(data, None, filename=filename)
+        result.detections = result.triage.detections
+        result.unresolved.append(
+            Unresolved(
+                reason=Reason.PARSE_ERROR,
+                message=(
+                    "no ingest adapter recognised this input, so only byte-level "
+                    "detection ran; nothing was unwrapped"
+                ),
+            )
+        )
+        return result
+
+    unit = units[0] if units else Unit(name="<input>", source="")
+    source = unit.source or ""
+
+    # Bytecode input: no decompiler in this version, so the unit becomes a
+    # single terminal layer rendered as annotated disassembly.
+    if unit.code is not None and unit.source is None:
+        return _crack_bytecode(units, data, result, options, filename)
+
+    result.unresolved.extend(unit.metadata.get("problems", []))
+
+    if options.detect_enabled:
+        result.triage = detect(data, source, filename=filename)
+        result.detections = result.triage.detections
+
+    if options.peel_enabled:
+        peeled: PeelResult = peel(
+            source,
+            PeelOptions(
+                max_layers=options.max_layers,
+                max_depth=options.max_depth,
+                budget=options.budget,
+                target_version=options.target_python,
+                # An ingest-time decode (PEP 263) is the first link of the chain.
+                root_chain=tuple(unit.metadata.get("chain", ())),
+            ),
+        )
+        result.layers = peeled.layers
+        result.unresolved.extend(peeled.unresolved)
+        result.code = peeled.code or source
+        if peeled.tracker is not None:
+            result.stats = {
+                "layers": len(peeled.layers),
+                "max_depth": max((layer.depth for layer in peeled.layers), default=0),
+                "bytes_folded": peeled.tracker.total_output,
+                "eval_steps": peeled.tracker.iterations,
+                "seconds": round(peeled.tracker.elapsed, 3),
+            }
+    else:
+        result.code = source
+        result.layers = [Layer(index=0, text=source, terminal=True)]
+
+    if options.clean and result.code:
+        _run_cleanup(result, options)
+
+    return result

snakecharm/clean/__init__.py

@@ -0,0 +1,26 @@
+"""Source cleanup: make a peeled payload readable.
+
+Opt-in and off by default. On a sample that peels cleanly there is nothing to
+clean, and running anyway would only strip formatting from the analyst's prize.
+Cleanup is for payloads that are still mangled once the layers come off.
+
+Output is a *derived view* written to ``cleaned.py``. The ``layers/`` tree stays
+byte-exact -- each file's header carries a SHA-256 of its own contents, and that
+is the evidence artifact.
+"""
+
+from __future__ import annotations
+
+# The import itself is the point -- it runs the @register decorators -- so the
+# bound name is never read and no annotation can make it look used.
+from . import (
+    passes as _passes,  # noqa: F401  (registers the passes)  # pyright: ignore[reportUnusedImport]
+)
+from .session import PASSES, CleanOptions, CleanResult, Pass, Refusal, Session
+
+__all__ = ["Session", "CleanOptions", "CleanResult", "Pass", "Refusal", "PASSES", "clean"]
+
+
+def clean(source: str, options: CleanOptions | None = None) -> CleanResult:
+    """Run the cleanup pipeline over `source`."""
+    return Session(options).run(source)