reverse-skills-max: initial public release (restored, redacted, hardened)

vendor-new/analyst-ai-pack/skills/analyzing-compiled-python-malware/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: analyzing-compiled-python-malware
+description: 'Analyzes Python-based malware packaged as PyInstaller/py2exe executables by detecting
+  the packer, locating the embedded archive, and identifying bundled .pyc modules for extraction and
+  decompilation. Activates for requests to analyze compiled Python malware, unpack a PyInstaller
+  binary, or extract pyc modules from a frozen Python executable.'
+domain: cybersecurity
+subdomain: reverse-engineering
+tags:
+  - reverse-engineering
+  - python
+  - pyinstaller
+  - pyc
+  - unpacking
+version: 1.0.0
+author: analyst-ai-pack
+license: Apache-2.0
+mitre_attack:
+  - T1027
+  - T1059.006
+  - T1587.001
+d3fend:
+  - D3-SDA
+  - D3-DA
+references:
+  - 'PyInstaller archive format (CArchive/PKG) — https://pyinstaller.org/en/stable/advanced-topics.html'
+  - 'Python bytecode (dis module / .pyc magic) — https://docs.python.org/3/library/dis.html'
+---
+
+# Analyzing Compiled Python Malware
+
+## When to Use
+
+- You have an executable that is actually a frozen Python app (PyInstaller, py2exe, cx_Freeze) and
+  need to identify the packer and locate the embedded Python modules.
+- You want to extract `.pyc` files for decompilation.
+
+**Do not use** this to run the executable — it identifies and locates the embedded archive
+statically. Decompile extracted `.pyc` in an isolated environment.
+
+## Prerequisites
+
+- The frozen executable (read inertly).
+
+## Safety & Handling
+
+- Read bytes statically; treat extracted modules as malicious until reviewed.
+
+## Workflow
+
+### Step 1: Detect the packer
+
+```bash
+python scripts/analyst.py detect sample.exe
+```
+
+Looks for PyInstaller markers (`pyi-`, `PYZ-00.pyz`, the `MEI` CArchive cookie `MEI\014\013\012\013\016`),
+py2exe (`PYTHONSCRIPT`, `zipfile.zip`), and embedded `python3x.dll` references.
+
+### Step 2: Locate the embedded archive
+
+Find the CArchive cookie near the end of the file and report the offset and the embedded Python
+version string (`python3.x`).
+
+### Step 3: Extract and decompile
+
+Use a PyInstaller extractor to dump the archive, then decompile `.pyc` (matching the detected
+Python version) for source recovery.
+
+### Step 4: Analyze the source
+
+Review the recovered Python for C2, persistence, and capability; map to ATT&CK.
+
+## Validation
+
+- The packer is identified by its specific marker, not just the presence of Python strings.
+- The CArchive cookie offset and Python version are reported when PyInstaller is present.
+- Findings distinguish the bootloader stub from the embedded Python payload.
+
+## Pitfalls
+
+- `.pyc` version mismatch breaking decompilation — match the interpreter version.
+- Stripped/obfuscated bytecode (e.g., custom magic) needing header repair before decompiling.
+- Encrypted PYZ archives (PyInstaller `--key`) requiring the key.
+
+## References
+
+- See [`references/api-reference.md`](references/api-reference.md) for the detector.
+- PyInstaller archive and Python bytecode references (linked in frontmatter).