snakecharm 0.1.1__tar.gz

snakecharm-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.egg-info/
+
+# The fixture corpus is a build artifact of tests/make_corpus.py, regenerated
+# on demand by conftest. Half-committing it is how a fresh clone ended up with
+# a corpus that looked complete and was missing real.pyc.
+tests/corpus/
+dist/
+build/
+
+# Research area: obfuscator tools, generated fixtures, and live malware samples.
+# Nothing in here is ever committed. Samples are third-party code we have no
+# right to redistribute, and `git add -A` would put them in history permanently.
+research/

snakecharm-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snakecharm
+
+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.

snakecharm-0.1.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: snakecharm
+Version: 0.1.1
+Summary: Deobfuscate Python without executing it. A webcrack for Python.
+Project-URL: Homepage, https://veryserious.systems
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deobfuscation,malware-analysis,obfuscation,python,reverse-engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# snakecharm
+
+**Python De-Obfuscation**
+
+Unwraps obfuscated Python — `exec`/`eval`/`compile` chains over base64, hex,
+zlib/gzip/bz2/lzma, XOR, `marshal`, reversal and `chr`/`ord` reconstruction —
+without executing the sample.
+
+Requires Python 3.11+. Pure Python; depends on `typer`, `rich`, `pyyaml`.
+
+## Install
+
+```console
+pip install snakecharm
+uv tool install snakecharm     # isolated, puts snakecharm on PATH
+```
+
+## Commands
+
+```console
+snakecharm crack FILE [-o DIR] [--json] [--clean]
+snakecharm detect FILE [--json]
+snakecharm inspect FILE [--target-python X.Y]
+snakecharm version
+```
+
+| | |
+|---|---|
+| `crack` | Unwrap. Recovered source to stdout, diagnostics to stderr. |
+| `detect` | Fingerprint the obfuscator family; do not unwrap. |
+| `inspect` | Disassemble a `.pyc` or bare marshal stream. |
+| `version` | Print the version. |
+
+`FILE` may be `-` to read from stdin.
+
+Cleanup is a flag on `crack` (`--clean`), not a separate command.
+
+### `crack` options
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `-o, --output DIR` | — | Write the full artifact tree instead of stdout. |
+| `--json` | off | Emit `report.json` to stdout. |
+| `--clean` | off | Also emit a cleaned view (see [Cleanup](#cleanup)). |
+| `--target-python X.Y` | host | Version to assume for marshal payloads. |
+| `--decompiler NAME` | auto | Force a backend instead of routing by version. |
+| `--max-layers N` | 512 | Layer cap; `0` for no limit. |
+| `--max-memory MiB` | 1024 | Total decoded output; `0` for no limit. |
+| `--max-fold MiB` | 256 | Largest single decoded value; `0` for no limit. |
+| `--timeout SEC` | 300 | Wall clock; `0` for no limit. |
+| `--no-peel` | off | Skip unwrapping; report detection only. |
+| `--no-detect` | off | Skip fingerprinting. |
+| `--plugins` | off | Load third-party ingest adapters. |
+| `-q, --quiet` | off | Suppress the stderr summary. |
+
+Exit codes: `0` complete, `1` incomplete, `2` input could not be processed.
+Identifying the obfuscator does not affect the exit code.
+
+## Output
+
+```console
+$ snakecharm crack sample.py
+import os
+import sys
+
+MESSAGE = "recovered exactly"
+LIMIT = 42
+...
+
+31 layers, depth 30, 431,204 bytes folded in 0.006s
+detected: freecodingtools (100%)
+```
+
+With `-o`:
+
+```console
+$ snakecharm crack sample.py -o out/
+wrote out/
+2 layers, depth 1, 1,966 bytes folded in 0.001s
+detected: hyperion (100%), freecodingtools (67%)
+
+$ find out -type f
+out/deobfuscated.py
+out/layers/00_depth0.py
+out/layers/01_depth1.py
+out/report.json
+```
+
+`--clean` adds `out/cleaned.py`. `layers/` stays byte-exact.
+
+Each layer file carries its derivation:
+
+```python
+# ---------------------------------------------------------------
+# snakecharm layer 1  (depth 1, source)
+# provenance : zlib <- b64decode
+# from       : exec() at line 13, col 0 of layer 0
+# sha256     : 58dda7518dfd60b35d3b522a654ad6c8532b076846f3a37d98340b05f2131acd
+# ---------------------------------------------------------------
+```
+
+When a site cannot be resolved it is reported, not skipped:
+
+```console
+$ snakecharm crack script.py
+not_reached : could not fold the argument of exec(): not reached during
+interpretation, and folding it in isolation also failed: unbound name 'handle'
+incomplete: 1 site(s) could not be resolved statically
+```
+
+## Library
+
+```python
+import snakecharm
+
+result = snakecharm.crack(open("sample.py", "rb").read())
+
+result.code  # deepest recovered source
+result.complete  # bool
+result.unresolved  # [Unresolved(reason, message, layer, line, col)]
+result.layers  # [Layer(...)], each with .provenance and .digest
+result.detections  # [Detection(family, confidence, evidence)]
+result.stats  # {'layers': 31, 'max_depth': 30, 'bytes_folded': 431204, ...}
+result.cleaned  # str | None, when Options(clean=True)
+result.save("out/")  # writes the tree above
+```
+
+`snakecharm.Options` mirrors the CLI flags. `snakecharm.Budget` holds the
+resource limits.
+
+To run the cleanup passes on their own, without peeling:
+
+```python
+from snakecharm.clean import clean
+
+result = clean("X = 1 + 2\n")
+result.code  # 'X = 3'
+result.changed, result.refused, result.rolled_back
+```
+
+## Handles
+
+- `exec`/`eval`/`compile` chains nested to arbitrary depth (default cap 512).
+- Wrappers: `try`/`except`, `with`, class bodies, `if __name__ == "__main__"`,
+  `async def`, decorators.
+- `.pyc` files and bare marshal streams, Python 3.8–3.14, from any host version.
+- PEP 263 source encodings, decoded before analysis and recorded in the
+  provenance chain.
+- Family fingerprinting: freecodingtools/pyobfuscate.com, Hyperion, Berserker,
+  Kramer, BlankOBF, Jawbreaker, PlusOBF, Vare, Anubis, Mr.X, PyArmor, Intensio,
+  Nuitka, PyInstaller, python-minifier. Detection is additive — an unrecognised
+  sample is still unwrapped. Signatures not confirmed against real output are
+  marked `[unvalidated signature]`.
+
+Nothing in the default path executes sample code. Analysing live malware in a
+disposable VM is still advisable.
+
+### Cleanup
+
+`--clean` runs, in order: constant folding, `getattr(o, "lit")` → `o.lit`,
+removal of branches whose condition folds to a constant, and removal of unused
+function locals.
+
+Module-level globals and uncalled functions are never removed. A round that
+fails to parse or compile is rolled back whole.
+
+## Does not handle
+
+| | |
+|---|---|
+| Accurate 3.11+ decompilation | No released decompiler handles it. Falls back to annotated disassembly, labelled as such. |
+| Identifier renaming | Mangled names are returned unchanged. |
+| Packed executables | PyInstaller / cx_Freeze / py2exe are not unpacked. `detect` still names the packer. |
+| Nuitka | Native machine code; no `.pyc` exists in the binary. Named, not recovered. |
+| PyArmor BCC / RFT | Native C, and one-way identifier destruction, respectively. |
+| MBA obfuscation | Arithmetic seeded with live in-scope variables defeats static folding. |
+| Runtime-fetched payloads | Not present in the file. |
+
+Decompiler backends (`uncompyle6`, `decompyle3`, `pycdc`) are used if found on
+`PATH`. They are GPL, so they are never bundled, never imported, and invoked
+only as subprocesses; without them, `.pyc` input renders as disassembly.
+
+MIT. Created and provided by veryserious.systems.

snakecharm-0.1.1/README.md

@@ -0,0 +1,183 @@
+# snakecharm
+
+**Python De-Obfuscation**
+
+Unwraps obfuscated Python — `exec`/`eval`/`compile` chains over base64, hex,
+zlib/gzip/bz2/lzma, XOR, `marshal`, reversal and `chr`/`ord` reconstruction —
+without executing the sample.
+
+Requires Python 3.11+. Pure Python; depends on `typer`, `rich`, `pyyaml`.
+
+## Install
+
+```console
+pip install snakecharm
+uv tool install snakecharm     # isolated, puts snakecharm on PATH
+```
+
+## Commands
+
+```console
+snakecharm crack FILE [-o DIR] [--json] [--clean]
+snakecharm detect FILE [--json]
+snakecharm inspect FILE [--target-python X.Y]
+snakecharm version
+```
+
+| | |
+|---|---|
+| `crack` | Unwrap. Recovered source to stdout, diagnostics to stderr. |
+| `detect` | Fingerprint the obfuscator family; do not unwrap. |
+| `inspect` | Disassemble a `.pyc` or bare marshal stream. |
+| `version` | Print the version. |
+
+`FILE` may be `-` to read from stdin.
+
+Cleanup is a flag on `crack` (`--clean`), not a separate command.
+
+### `crack` options
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `-o, --output DIR` | — | Write the full artifact tree instead of stdout. |
+| `--json` | off | Emit `report.json` to stdout. |
+| `--clean` | off | Also emit a cleaned view (see [Cleanup](#cleanup)). |
+| `--target-python X.Y` | host | Version to assume for marshal payloads. |
+| `--decompiler NAME` | auto | Force a backend instead of routing by version. |
+| `--max-layers N` | 512 | Layer cap; `0` for no limit. |
+| `--max-memory MiB` | 1024 | Total decoded output; `0` for no limit. |
+| `--max-fold MiB` | 256 | Largest single decoded value; `0` for no limit. |
+| `--timeout SEC` | 300 | Wall clock; `0` for no limit. |
+| `--no-peel` | off | Skip unwrapping; report detection only. |
+| `--no-detect` | off | Skip fingerprinting. |
+| `--plugins` | off | Load third-party ingest adapters. |
+| `-q, --quiet` | off | Suppress the stderr summary. |
+
+Exit codes: `0` complete, `1` incomplete, `2` input could not be processed.
+Identifying the obfuscator does not affect the exit code.
+
+## Output
+
+```console
+$ snakecharm crack sample.py
+import os
+import sys
+
+MESSAGE = "recovered exactly"
+LIMIT = 42
+...
+
+31 layers, depth 30, 431,204 bytes folded in 0.006s
+detected: freecodingtools (100%)
+```
+
+With `-o`:
+
+```console
+$ snakecharm crack sample.py -o out/
+wrote out/
+2 layers, depth 1, 1,966 bytes folded in 0.001s
+detected: hyperion (100%), freecodingtools (67%)
+
+$ find out -type f
+out/deobfuscated.py
+out/layers/00_depth0.py
+out/layers/01_depth1.py
+out/report.json
+```
+
+`--clean` adds `out/cleaned.py`. `layers/` stays byte-exact.
+
+Each layer file carries its derivation:
+
+```python
+# ---------------------------------------------------------------
+# snakecharm layer 1  (depth 1, source)
+# provenance : zlib <- b64decode
+# from       : exec() at line 13, col 0 of layer 0
+# sha256     : 58dda7518dfd60b35d3b522a654ad6c8532b076846f3a37d98340b05f2131acd
+# ---------------------------------------------------------------
+```
+
+When a site cannot be resolved it is reported, not skipped:
+
+```console
+$ snakecharm crack script.py
+not_reached : could not fold the argument of exec(): not reached during
+interpretation, and folding it in isolation also failed: unbound name 'handle'
+incomplete: 1 site(s) could not be resolved statically
+```
+
+## Library
+
+```python
+import snakecharm
+
+result = snakecharm.crack(open("sample.py", "rb").read())
+
+result.code  # deepest recovered source
+result.complete  # bool
+result.unresolved  # [Unresolved(reason, message, layer, line, col)]
+result.layers  # [Layer(...)], each with .provenance and .digest
+result.detections  # [Detection(family, confidence, evidence)]
+result.stats  # {'layers': 31, 'max_depth': 30, 'bytes_folded': 431204, ...}
+result.cleaned  # str | None, when Options(clean=True)
+result.save("out/")  # writes the tree above
+```
+
+`snakecharm.Options` mirrors the CLI flags. `snakecharm.Budget` holds the
+resource limits.
+
+To run the cleanup passes on their own, without peeling:
+
+```python
+from snakecharm.clean import clean
+
+result = clean("X = 1 + 2\n")
+result.code  # 'X = 3'
+result.changed, result.refused, result.rolled_back
+```
+
+## Handles
+
+- `exec`/`eval`/`compile` chains nested to arbitrary depth (default cap 512).
+- Wrappers: `try`/`except`, `with`, class bodies, `if __name__ == "__main__"`,
+  `async def`, decorators.
+- `.pyc` files and bare marshal streams, Python 3.8–3.14, from any host version.
+- PEP 263 source encodings, decoded before analysis and recorded in the
+  provenance chain.
+- Family fingerprinting: freecodingtools/pyobfuscate.com, Hyperion, Berserker,
+  Kramer, BlankOBF, Jawbreaker, PlusOBF, Vare, Anubis, Mr.X, PyArmor, Intensio,
+  Nuitka, PyInstaller, python-minifier. Detection is additive — an unrecognised
+  sample is still unwrapped. Signatures not confirmed against real output are
+  marked `[unvalidated signature]`.
+
+Nothing in the default path executes sample code. Analysing live malware in a
+disposable VM is still advisable.
+
+### Cleanup
+
+`--clean` runs, in order: constant folding, `getattr(o, "lit")` → `o.lit`,
+removal of branches whose condition folds to a constant, and removal of unused
+function locals.
+
+Module-level globals and uncalled functions are never removed. A round that
+fails to parse or compile is rolled back whole.
+
+## Does not handle
+
+| | |
+|---|---|
+| Accurate 3.11+ decompilation | No released decompiler handles it. Falls back to annotated disassembly, labelled as such. |
+| Identifier renaming | Mangled names are returned unchanged. |
+| Packed executables | PyInstaller / cx_Freeze / py2exe are not unpacked. `detect` still names the packer. |
+| Nuitka | Native machine code; no `.pyc` exists in the binary. Named, not recovered. |
+| PyArmor BCC / RFT | Native C, and one-way identifier destruction, respectively. |
+| MBA obfuscation | Arithmetic seeded with live in-scope variables defeats static folding. |
+| Runtime-fetched payloads | Not present in the file. |
+
+Decompiler backends (`uncompyle6`, `decompyle3`, `pycdc`) are used if found on
+`PATH`. They are GPL, so they are never bundled, never imported, and invoked
+only as subprocesses; without them, `.pyc` input renders as disassembly.
+
+MIT. Created and provided by veryserious.systems.

snakecharm-0.1.1/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snakecharm"
+dynamic = ["version"]
+description = "Deobfuscate Python without executing it. A webcrack for Python."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["deobfuscation", "malware-analysis", "reverse-engineering", "python", "obfuscation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Information Technology",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+
+# Core stays deliberately small. libcst is not needed until the v0.2 CST tier.
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.0",
+    "pyyaml>=6.0",
+]
+
+# No optional extras. `ast-grep-py` and `libcst` were both declared here and
+# never imported -- a dependency you do not use is a claim you cannot back.
+# Structural detection uses stdlib `ast`; the v0.2 cleanup tier uses `ast` +
+# `ast.unparse` by design.
+
+# Must stay below every `[project]` key: a TOML sub-table claims everything
+# after it, so putting this higher silently swallowed `dependencies`.
+[project.urls]
+Homepage = "https://veryserious.systems"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "hypothesis>=6.100"]
+# Real obfuscators, used to generate the Tier-2 ground-truth corpus. Both MIT.
+# Not needed to run snakecharm -- only to regenerate tests/corpus_real/.
+obfuscators = ["python-minifier>=2.11", "intensio-obfuscator>=1.0.10"]
+
+[project.scripts]
+snakecharm = "snakecharm.cli:main"
+snakecharm-gen-tables = "snakecharm.ir.gen_tables:main"
+
+[tool.hatch.version]
+path = "snakecharm/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["snakecharm"]
+
+[tool.hatch.build.targets.sdist]
+# Allowlist, not denylist. The previous exclude-list shipped a 53 KB .coverage
+# database full of this machine's absolute paths, because it was untracked and
+# therefore not something anyone had thought to exclude.
+#
+# `/tests` is deliberately absent. PyPI rejects the sdist with "PyArmor-
+# encrypted content is not allowed" because tests/test_packers.py holds a real
+# two-line PyArmor stub -- the exact shape a protected file has, which is the
+# whole reason it is a useful fixture for testing that we detect PyArmor. The
+# fixture is not reshaped to get past the scanner: that would be evading a
+# security control, and a fixture that no longer looks like the thing it stands
+# for tests nothing. Tests are not needed to install or use the package, so they
+# stay in the repository and out of the distribution.
+include = [
+    "/snakecharm",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+exclude = ["*.pyc", "__pycache__"]
+
+[tool.ruff]
+line-length = 100
+# The corpus is deliberately malformed, obfuscated, or not text at all.
+# Linting it is meaningless and its failures drown out real ones.
+# Both corpora are deliberately obfuscated or malformed. Linting them is
+# meaningless and their errors drown out real ones.
+extend-exclude = ["tests/corpus", "tests/corpus_real"]
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "B", "SIM"]
+ignore = [
+    "E501",    # long lines: the signature tables and opcode maps read better wide
+    "B008",    # typer's Option()-in-default is the documented idiom
+    "SIM105",  # contextlib.suppress is not clearer in tight interpreter loops
+    "SIM905",  # a wrapped "a b c".split() reads better than a 30-element list literal
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+markers = [
+    "slow: bomb/fuzz cases that allocate real memory",
+]
+filterwarnings = ["error::DeprecationWarning"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+include = ["snakecharm", "tests"]
+# Third-party samples and obfuscator tools, never ours to type-check.
+exclude = ["research", "**/__pycache__", "tests/corpus", "tests/corpus_real"]
+# Without this the CLI resolves an ephemeral interpreter instead of the project
+# venv, so typer/rich/pytest go unresolved and every value derived from them
+# degrades to Unknown -- 1,219 diagnostics, most of them that one cascade.
+venvPath = "."
+venv = ".venv"
+# Every module-private function in this codebase that looks unused is reached
+# through a registration decorator -- @primitive in the whitelist, @register in
+# the cleanup passes -- and is never named again after its definition. All 28
+# reports were that pattern, so the rule cannot tell dead code from the central
+# idiom here.
+reportUnusedFunction = false