pyc-revive 1.0.0__tar.gz

pyc_revive-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: pyc-revive
+Version: 1.0.0
+Summary: Stdlib-only .pyc -> .py reconstructor with native and pycdas backends
+Author: opsecalyzer
+License: MIT
+Project-URL: Homepage, https://github.com/opsecalyzer/pyc_revive
+Project-URL: Source, https://github.com/opsecalyzer/pyc_revive
+Keywords: pyc,decompiler,bytecode,reverse-engineering,malware-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Disassemblers
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pyc_revive
+
+`.pyc` -> `.py` reconstructor. no uncompyle6. no pycdc. no xdis.
+
+## use
+
+```bash
+python -m pyc_revive my file.pyc
+python -m pyc_revive ./dist/app.pyc --out ./revived.py
+```
+
+input handling: exact path, spaces with no quotes, basename search in
+cwd + all subfolders + parent folder.
+
+## versions
+
+every CPython from 2.0 through 3.15 resolves by magic number
+(`pymagic.py`, full table + nearest fallback + header sizes).
+
+two backends, one pipeline:
+
+- native: `.pyc` matches the running interpreter. stdlib marshal loads
+  the code object, stdlib dis disassembles. zero dependencies.
+- pycdas: anything else. the bundled `pycdas.exe` disassembles the
+  foreign version, `pycdas_parser.py` parses the dump into code trees,
+  `shim.py` adapts them to the pipeline. everything downstream
+  (normalize, segment, translate, CFG, emit, verify x3) runs unchanged.
+
+## pipeline
+
+1. find file (`finder.py`)
+2. detect version via magic (`pymagic.py`)
+3. load: native marshal, else pycdas backend (`loader.py`,
+   `pycdas_parser.py`, `shim.py`)
+4. disassemble + abstract (`bytecode.py`: `Inst`, `EditableBytecode`,
+   opcode/oparg/value-stack/metadata tables)
+5. normalize / mask consts + names (`normalizer.py`)
+6. opcode-aware B/I/E segmentation (`segmenter.py`)
+7. statement translation (`translator.py`: stack machine, defaults
+   recovery, lambdas inline, 2.x print/exec/class ops)
+8. control-flow graph from jumps (`cfg.py`: if/for/while/try/except-as
+   (bare `except:` too)/with/finally, clauses + clusters, 3.11+
+   exception table, SETUP-region splits)
+9. emit + repairs (`emitter.py`: source-order splicing onto def/class
+   stub lines, bases recovery, `@decorator` restore, `global` decls,
+   cond chains, ternaries, nested if/else, loop ranges, break/continue
+   recovery, indent + suite-guard passes)
+10. equivalence verify, 3 sweeps (`verifier.py`: recompile revived source,
+    compare opcode structure, repair, repeat x3)
+
+## layout
+
+```
+pyc_revive/
+  finder.py  pymagic.py  loader.py  pycdas_parser.py  shim.py
+  bytecode.py  normalizer.py  segmenter.py  translator.py  cfg.py
+  emitter.py  verifier.py  reconstructor.py  cli.py  __main__.py
+  pycdas.exe  README.md  requirements.txt
+```
+
+## known limits
+
+- inline comprehensions/genexps render as `func(...)` placeholders.
+- `try` bodies that fall through into always-run handlers keep flat
+  order instead of guarded flow.
+- exotic decorators reduce to bare defs; exotic call shapes degrade to
+  commented disassembly rather than failing.
+- pre-3.8 default-argument recovery is best-effort (flag-style MAKE
+  from 3.8+ recovers exactly).
+- verifier scores dip across versions: opcode sets drift between
+  releases, so cross-version similarity reads lower than same-version.

pyc_revive-1.0.0/README.md

@@ -0,0 +1,71 @@
+# pyc_revive
+
+`.pyc` -> `.py` reconstructor. no uncompyle6. no pycdc. no xdis.
+
+## use
+
+```bash
+python -m pyc_revive my file.pyc
+python -m pyc_revive ./dist/app.pyc --out ./revived.py
+```
+
+input handling: exact path, spaces with no quotes, basename search in
+cwd + all subfolders + parent folder.
+
+## versions
+
+every CPython from 2.0 through 3.15 resolves by magic number
+(`pymagic.py`, full table + nearest fallback + header sizes).
+
+two backends, one pipeline:
+
+- native: `.pyc` matches the running interpreter. stdlib marshal loads
+  the code object, stdlib dis disassembles. zero dependencies.
+- pycdas: anything else. the bundled `pycdas.exe` disassembles the
+  foreign version, `pycdas_parser.py` parses the dump into code trees,
+  `shim.py` adapts them to the pipeline. everything downstream
+  (normalize, segment, translate, CFG, emit, verify x3) runs unchanged.
+
+## pipeline
+
+1. find file (`finder.py`)
+2. detect version via magic (`pymagic.py`)
+3. load: native marshal, else pycdas backend (`loader.py`,
+   `pycdas_parser.py`, `shim.py`)
+4. disassemble + abstract (`bytecode.py`: `Inst`, `EditableBytecode`,
+   opcode/oparg/value-stack/metadata tables)
+5. normalize / mask consts + names (`normalizer.py`)
+6. opcode-aware B/I/E segmentation (`segmenter.py`)
+7. statement translation (`translator.py`: stack machine, defaults
+   recovery, lambdas inline, 2.x print/exec/class ops)
+8. control-flow graph from jumps (`cfg.py`: if/for/while/try/except-as
+   (bare `except:` too)/with/finally, clauses + clusters, 3.11+
+   exception table, SETUP-region splits)
+9. emit + repairs (`emitter.py`: source-order splicing onto def/class
+   stub lines, bases recovery, `@decorator` restore, `global` decls,
+   cond chains, ternaries, nested if/else, loop ranges, break/continue
+   recovery, indent + suite-guard passes)
+10. equivalence verify, 3 sweeps (`verifier.py`: recompile revived source,
+    compare opcode structure, repair, repeat x3)
+
+## layout
+
+```
+pyc_revive/
+  finder.py  pymagic.py  loader.py  pycdas_parser.py  shim.py
+  bytecode.py  normalizer.py  segmenter.py  translator.py  cfg.py
+  emitter.py  verifier.py  reconstructor.py  cli.py  __main__.py
+  pycdas.exe  README.md  requirements.txt
+```
+
+## known limits
+
+- inline comprehensions/genexps render as `func(...)` placeholders.
+- `try` bodies that fall through into always-run handlers keep flat
+  order instead of guarded flow.
+- exotic decorators reduce to bare defs; exotic call shapes degrade to
+  commented disassembly rather than failing.
+- pre-3.8 default-argument recovery is best-effort (flag-style MAKE
+  from 3.8+ recovers exactly).
+- verifier scores dip across versions: opcode sets drift between
+  releases, so cross-version similarity reads lower than same-version.

pyc_revive-1.0.0/pyc_revive/__init__.py

@@ -0,0 +1,6 @@
+"""pyc_revive — stdlib-only .pyc -> .py reconstructor."""
+from .reconstructor import reconstruct_file, reconstruct_code
+from .finder import resolve_target
+
+__all__ = ["reconstruct_file", "reconstruct_code", "resolve_target"]
+__version__ = "1.0.0"

pyc_revive-1.0.0/pyc_revive/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+if __name__ == "__main__":
+    raise SystemExit(main())

pyc_revive-1.0.0/pyc_revive/autofix.py

@@ -0,0 +1,247 @@
+"""Self-validation loop: compile the revived source, diagnose failures,
+apply targeted structural repairs, repeat until clean or out of budget.
+
+This is the last gate before a build ships: it proves the artifact parses,
+and when it does not, it fixes what it can (orphan handlers, bad indents,
+empty suites) and reports what it could not. Returns the best source found
+plus a repair log for the report.
+"""
+from __future__ import annotations
+
+
+def _compile_errors(src: str) -> list[dict]:
+    try:
+        compile(src, "<revived>", "exec")
+        return []
+    except SyntaxError as e:
+        return [{"line": e.lineno or 0, "msg": str(e.msg or e), "text": (e.text or "").rstrip()}]
+    except Exception as e:
+        return [{"line": 0, "msg": str(e), "text": ""}]
+
+
+def _indent_of(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def _is_header(s: str) -> bool:
+    t = s.strip()
+    if not t or t.startswith("#"):
+        return False
+    head = t.split(":")[0].split()
+    if not head:
+        return False
+    if not t.rstrip().endswith(":"):
+        return False
+    return head[0] in (
+        "if", "elif", "else", "for", "while", "try", "except", "finally",
+        "with", "def", "class", "match", "case")
+
+
+def _fix_empty_suite(lines: list[str], err: dict) -> list[str] | None:
+    if "expected an indented block" not in err["msg"]:
+        return None
+    n = (err["line"] or 1) - 1
+    if n < 0 or n >= len(lines):
+        return None
+    hdr = lines[n]
+    if not _is_header(hdr):
+        return None
+    lvl = _indent_of(hdr)
+    nxt = next((k for k in range(n + 1, len(lines)) if lines[k].strip()), None)
+    if nxt is not None and _indent_of(lines[nxt]) > lvl:
+        return None  # suite exists; different problem
+    out = list(lines)
+    out.insert(n + 1, " " * (lvl + 4) + "pass")
+    return out
+
+
+def _fix_orphan(lines: list[str], err: dict) -> list[str] | None:
+    msg = err["msg"]
+    n = (err["line"] or 1) - 1
+    if n < 0 or n >= len(lines):
+        return None
+    s = lines[n].strip()
+    if msg == "expected 'except' or 'finally' block" and not (s.startswith("except") or s.startswith("finally") or s == "try:"):
+        # try suite broke early (stray flat line closed it): find the
+        # enclosing try and either drop a stray pass or reindent the line in
+        for k in range(n - 1, -1, -1):
+            if not lines[k].strip():
+                continue
+            if _indent_of(lines[k]) > _indent_of(lines[n]):
+                continue
+            if lines[k].strip() == "try:" and _indent_of(lines[k]) <= _indent_of(lines[n]):
+                out = list(lines)
+                if s == "pass":
+                    del out[n]
+                    return out
+                lvl = _indent_of(lines[k]) + 4
+                delta = _indent_of(lines[n]) - lvl
+                if delta == 0:
+                    return None
+                end = n
+                for m in range(n + 1, len(lines)):
+                    if not lines[m].strip():
+                        continue
+                    if _indent_of(lines[m]) > _indent_of(lines[n]):
+                        end = m
+                    else:
+                        break
+                if delta > 0:
+                    for m in range(n, end + 1):
+                        if lines[m].strip() and len(lines[m]) - len(lines[m].lstrip(" ")) >= delta:
+                            out[m] = lines[m][delta:]
+                else:
+                    for m in range(n, end + 1):
+                        if lines[m].strip():
+                            out[m] = " " * (-delta) + lines[m].lstrip(" ")
+                return out
+            break
+        return None
+    want: str | None = None
+    if s.startswith("except") or s.startswith("finally"):
+        want = "try"
+    elif s.startswith("else:"):
+        want = "if/for/while"
+    elif s.startswith("elif"):
+        want = "if"
+    if want is None:
+        if s == "try:":
+            out = list(lines)
+            out.insert(n + 1, " " * (_indent_of(lines[n]) + 4) + "pass")
+            return out
+        if "expected 'except' or 'finally'" not in msg:
+            return None
+        want = "body"  # try suite ran dry; just needs any suite
+    lvl = _indent_of(lines[n])
+    # nearest shallower line decides: a matching opener reindents us to it
+    for k in range(n - 1, -1, -1):
+        if not lines[k].strip():
+            continue
+        ilk = _indent_of(lines[k])
+        if ilk > lvl:
+            continue
+        if ilk == lvl:
+            continue
+        t = lines[k].strip()
+        ok = ((want == "try" and t == "try:") or
+              (want == "if/for/while" and (t.startswith("if ") or t.startswith("if(") or t.startswith("for ") or t.startswith("while ") or t == "try:")) or
+              (want == "if" and (t.startswith("if ") or t.startswith("if("))) or
+              (want == "body"))
+        if ok:
+            delta = lvl - ilk
+            if delta <= 0:
+                return None
+            out = list(lines)
+            end = n
+            for m in range(n + 1, len(lines)):
+                if not lines[m].strip():
+                    continue
+                if _indent_of(lines[m]) > lvl:
+                    end = m
+                else:
+                    break
+            for m in range(n, end + 1):
+                if lines[m].strip() and len(lines[m]) - len(lines[m].lstrip(" ")) >= delta:
+                    out[m] = lines[m][delta:]
+            return out
+        break
+    # no partner: neutralize the orphan so the file parses; body stays visible
+    out = list(lines)
+    if s.startswith("except") or s.startswith("finally"):
+        out[n] = " " * lvl + "if False:  # unattached handler kept visible"
+    elif s.startswith("else:") or s.startswith("elif"):
+        out[n] = " " * lvl + "if True:  # unattached else kept visible"
+    else:
+        return None
+    return out
+
+
+def _fix_indent(lines: list[str], err: dict) -> list[str] | None:
+    if "unexpected indent" not in err["msg"] and "unindent" not in err["msg"]:
+        return None
+    n = (err["line"] or 1) - 1
+    if n <= 0 or n >= len(lines):
+        return None
+    p = n - 1
+    while p >= 0 and not lines[p].strip():
+        p -= 1
+    if p < 0:
+        return None
+    plvl = _indent_of(lines[p])
+    cur = _indent_of(lines[n])
+    target = plvl + 4 if lines[p].rstrip().endswith(":") else plvl
+    if cur == target:
+        return None
+    if "unindent" in err["msg"] and cur in (plvl, plvl + 4) and target in (plvl, plvl + 4):
+        return None
+    delta = cur - target
+    if delta <= 0:
+        # needs indenting up (rare); shift line and suite right
+        out = list(lines)
+        end = n
+        for m in range(n + 1, len(lines)):
+            if not lines[m].strip():
+                continue
+            if _indent_of(lines[m]) > cur:
+                end = m
+            else:
+                break
+        for m in range(n, end + 1):
+            if lines[m].strip():
+                out[m] = " " * (-delta) + lines[m].lstrip(" ")
+        return out
+    out = list(lines)
+    end = n
+    for k in range(n + 1, len(lines)):
+        if not lines[k].strip():
+            continue
+        if _indent_of(lines[k]) > cur:
+            end = k
+        else:
+            break
+    for k in range(n, end + 1):
+        if lines[k].strip() and len(lines[k]) - len(lines[k].lstrip(" ")) >= delta:
+            out[k] = lines[k][delta:]
+    return out
+
+
+_REPAIRS = (_fix_empty_suite, _fix_orphan, _fix_indent)
+
+
+def autovalidate(src: str, budget: int = 8) -> tuple[str, dict]:
+    """Compile-repair loop. Returns (best_src, log). Never raises."""
+    rounds: list[dict] = []
+    cur = src
+    errs = _compile_errors(cur)
+    if not errs:
+        return cur, {"compiles": True, "rounds": rounds, "repairs": 0}
+    best, best_key = cur, (len(errs) and -errs[0]["line"] or 0)
+    for _ in range(budget):
+        errs = _compile_errors(cur)
+        if not errs:
+            return cur, {"compiles": True, "rounds": rounds, "repairs": len(rounds)}
+        err = errs[0]
+        fixed = None
+        used = None
+        for fn in _REPAIRS:
+            try:
+                fixed = fn(cur.splitlines(), err)
+            except Exception:
+                fixed = None
+            if fixed is not None:
+                used = fn.__name__
+                break
+        if fixed is None:
+            rounds.append({"error": err, "repair": None})
+            break
+        cur = "\n".join(fixed).rstrip() + "\n"
+        rounds.append({"error": err, "repair": used})
+        key = 0
+        errs2 = _compile_errors(cur)
+        if not errs2:
+            return cur, {"compiles": True, "rounds": rounds, "repairs": len(rounds)}
+        key = -errs2[0]["line"]
+        if key >= best_key:
+            best, best_key = cur, key
+    return best, {"compiles": False, "rounds": rounds, "repairs": len(rounds),
+                  "note": "budget spent; shipping closest parse"}

pyc_revive-1.0.0/pyc_revive/bytecode.py

@@ -0,0 +1,166 @@
+"""Version-agnostic bytecode model: Inst + EditableBytecode.
+
+Wraps stdlib `dis` into mutable instruction objects so the rest of the
+pipeline (normalize / segment / cfg) never touches raw bytes directly.
+Tracks opcode, oparg, value-stack depth, metadata tables.
+"""
+from __future__ import annotations
+import dis
+from dataclasses import dataclass, field
+from types import CodeType
+from typing import Any
+
+# opnames that transfer control — used by CFG, version-agnostic superset
+_JUMP_OPS = {
+    "POP_JUMP_IF_FALSE", "POP_JUMP_IF_TRUE",
+    "POP_JUMP_FORWARD_IF_FALSE", "POP_JUMP_FORWARD_IF_TRUE",
+    "POP_JUMP_BACKWARD_IF_FALSE", "POP_JUMP_BACKWARD_IF_TRUE",
+    "JUMP_IF_FALSE_OR_POP", "JUMP_IF_TRUE_OR_POP",
+    "JUMP_IF_TRUE", "JUMP_IF_FALSE", "JUMP_IF_NOT_EXC_MATCH",
+    "CONTINUE_LOOP", "BREAK_LOOP",
+    "JUMP_FORWARD", "JUMP_BACKWARD", "JUMP_ABSOLUTE", "JUMP",
+    "JUMP_BACKWARD_NO_INTERRUPT", "JUMP_NO_INTERRUPT",
+    "FOR_ITER", "SEND",
+    "SETUP_FINALLY", "SETUP_EXCEPT", "SETUP_WITH", "SETUP_LOOP",
+    "SETUP_FINALLY_PRE", "BEFORE_WITH",
+    "RERAISE", "RAISE_VARARGS",
+    "RETURN_VALUE", "RETURN_CONST", "RETURN_GENERATOR",
+}
+_HASJUMP = set(dis.hasjump) if hasattr(dis, "hasjump") else set()
+_COND_JUMPS = {
+    "POP_JUMP_IF_FALSE", "POP_JUMP_IF_TRUE",
+    "POP_JUMP_FORWARD_IF_FALSE", "POP_JUMP_FORWARD_IF_TRUE",
+    "POP_JUMP_BACKWARD_IF_FALSE", "POP_JUMP_BACKWARD_IF_TRUE",
+    "JUMP_IF_FALSE_OR_POP", "JUMP_IF_TRUE_OR_POP",
+    "JUMP_IF_TRUE", "JUMP_IF_FALSE", "JUMP_IF_NOT_EXC_MATCH",
+    "FOR_ITER", "SEND",
+}
+
+# cross-version aliases: canonical -> set of spellings
+ALIASES = {
+    "BINARY_ADD": {"BINARY_ADD", "BINARY_OP"},
+    "LOAD_METHOD": {"LOAD_METHOD", "LOAD_ATTR"},
+    "CALL": {"CALL", "CALL_FUNCTION", "CALL_FUNCTION_EX", "CALL_METHOD", "CALL_KW", "PRECALL"},
+    "RETURN": {"RETURN_VALUE", "RETURN_CONST", "RETURN_GENERATOR"},
+}
+
+
+@dataclass
+class Inst:
+    offset: int
+    opname: str
+    opcode: int
+    arg: Any = None
+    argval: Any = None
+    argrepr: str = ""
+    starts_line: Any = None
+    is_jump_target: bool = False
+    positions: Any = None
+    index: int = 0
+    stack_depth_before: int = 0
+    stack_effect: int = 0
+
+    @property
+    def is_jump(self) -> bool:
+        return self.opname in _JUMP_OPS or self.opcode in _HASJUMP
+
+    @property
+    def is_cond_jump(self) -> bool:
+        return self.opname in _COND_JUMPS
+
+    @property
+    def is_uncond_jump(self) -> bool:
+        return self.is_jump and not self.is_cond_jump and self.opname not in (
+            "FOR_ITER", "SEND", "SETUP_FINALLY", "SETUP_EXCEPT", "SETUP_WITH",
+            "SETUP_LOOP", "BEFORE_WITH", "RERAISE", "RAISE_VARARGS",
+            "RETURN_VALUE", "RETURN_CONST", "RETURN_GENERATOR",
+        )
+
+    @property
+    def is_return(self) -> bool:
+        return self.opname in ("RETURN_VALUE", "RETURN_CONST", "RETURN_GENERATOR")
+
+    @property
+    def jump_target(self):
+        return self.argval if self.is_jump and isinstance(self.argval, int) else None
+
+    def canonical(self) -> str:
+        for canon, spellings in ALIASES.items():
+            if self.opname in spellings:
+                return canon
+        return self.opname
+
+
+@dataclass
+class EditableBytecode:
+    code: CodeType
+    insts: list = field(default_factory=list)
+    consts: tuple = ()
+    names: tuple = ()
+    varnames: tuple = ()
+    cellvars: tuple = ()
+    freevars: tuple = ()
+
+    @classmethod
+    def from_code(cls, code: CodeType) -> "EditableBytecode":
+        raw = list(dis.get_instructions(code))
+        insts: list[Inst] = []
+        depth = 0
+        for i, ins in enumerate(raw):
+            try:
+                eff = dis.stack_effect(ins.opcode, ins.arg if ins.arg is not None else 0)
+            except Exception:
+                eff = 0
+            insts.append(Inst(
+                offset=ins.offset, opname=ins.opname, opcode=ins.opcode,
+                arg=ins.arg, argval=ins.argval, argrepr=ins.argrepr or "",
+                starts_line=ins.starts_line, is_jump_target=bool(ins.is_jump_target),
+                positions=getattr(ins, "positions", None),
+                index=i, stack_depth_before=depth, stack_effect=eff,
+            ))
+            depth = max(0, depth + eff)
+        # 3.11+ KW_NAMES references co_consts by index; resolve the tuple now
+        # so calls below can pair keyword arguments (dis leaves it unknown)
+        for _ins in insts:
+            if _ins.opname == "KW_NAMES" and isinstance(_ins.arg, int):
+                try:
+                    _kc = code.co_consts[_ins.arg]
+                except Exception:
+                    _kc = None
+                if isinstance(_kc, tuple):
+                    _ins.argval = _kc
+        return cls(code=code, insts=insts, consts=code.co_consts,
+                   names=code.co_names, varnames=code.co_varnames,
+                   cellvars=getattr(code, "co_cellvars", ()),
+                   freevars=getattr(code, "co_freevars", ()))
+
+    def __len__(self):
+        return len(self.insts)
+
+    def opnames(self) -> list[str]:
+        return [ins.canonical() for ins in self.insts]
+
+    def jump_map(self) -> dict[int, int]:
+        """offset -> index for jump resolution."""
+        return {ins.offset: ins.index for ins in self.insts}
+
+    def targets(self) -> set[int]:
+        out: set[int] = set()
+        m = self.jump_map()
+        for ins in self.insts:
+            t = ins.jump_target
+            if t is not None and t in m:
+                out.add(m[t])
+        return out
+
+    def metadata_table(self) -> dict:
+        c = self.code
+        return {
+            "co_name": c.co_name, "co_filename": c.co_filename,
+            "co_firstlineno": c.co_firstlineno, "co_argcount": c.co_argcount,
+            "co_posonlyargcount": getattr(c, "co_posonlyargcount", 0),
+            "co_kwonlyargcount": c.co_kwonlyargcount,
+            "co_nlocals": c.co_nlocals, "co_flags": c.co_flags,
+            "co_consts": [type(x).__name__ for x in c.co_consts],
+            "co_names": list(c.co_names), "co_varnames": list(c.co_varnames),
+        }