ast-deobfuscation

AST deobfuscation

Prefer layered entry points instead of continuing to pile site-specific logic into generic scripts.

Workflow

1. First run scripts/detect-patterns.js <input.js> [hint] to perform pattern detection.
2. Only read the rule documentation for the sites or obfuscation families that are hit.
3. Run scripts/run-pipeline.js <input.js> <output-dir> [hint] to execute the selected pipeline.
4. Compare against reference artifacts or the original obfuscation symptoms to determine whether a new dedicated adapter script is still needed.

Design rules

• Generic scripts should only retain low-risk, reusable rewrites, such as structural normalization, fake branch cleanup, dispatcher inlining, control flow flattening, and if -> switch。
• Once a pattern is clearly site-specific, complete all four parts at the same time: rule documentation, detector hit entries, dedicated adapter script, and pipeline configuration entry.
• For high-cost steps, prefer skipping or reordering by family rather than forcing all samples through the same sequence. For large samples like reese84 , if inline-literalsis executed too late, it is very easy to get stuck.
• Dedicated adapter scripts should stay narrow and precise. If a rule has not been reused across multiple unrelated samples, do not rush to feed it back into the generic scripts.
• After structural rewrites, re-parse, and ensure that each stage can run and be troubleshooted independently.

Entry scripts

• scripts/detect-patterns.js Determine the most likely site or obfuscation family hit based on the file path, optional hint, and source symptoms.
• scripts/run-pipeline.js Copy the sample to the test directory, execute the selected steps, record elapsed time, and output a pipeline report.
• scripts/collect-residue-metrics.js Count symptoms that are still unresolved, such as split('|'), direct loop/switch flattening, opcode if chains, dispatcher wrapper, and _0x identifiers.
• scripts/compare-with-reference.js Compare the latest pipeline output with decode.js and summarize the remaining gaps.

Reference documentation

• When adding or adjusting an adapter, first read references/pattern-layering.md。
• Before putting any logic into generic scripts, first read references/safe-rewrite-rules.md。
• When handling string tables, decode stubs, and minimal runtime evaluation, read references/string-array-and-minimal-eval.md。
• When handling control flow flattening, opcode dispatchers, and VM-like handlers, read references/control-flow-and-opcode-patterns.md。
• When handling comma expressions, IIFEs, and statement hoisting, read references/sequence-normalization.md。
• After a detector hit, read only the corresponding site rule document:
  • references/patterns/reese84.md
  • references/patterns/dingxiang.md
  • references/patterns/geetest4.md
  • references/patterns/tonghuashun.md
  • references/patterns/yidun.md
  • references/patterns/xiaohongshu.md
  • references/patterns/cn-bidding-ob.md
  • references/patterns/mps-ob.md

Validation

• Every newly added or modified JavaScript helper script must pass at least one node --check or equivalent load validation before being integrated into the pipeline.
• After modifying the skill, run C:\Users\25198\.codex\skills\.system\skill-creator\scripts\quick_validate.py C:\Users\25198\.codex\skills\ast-deobfuscation。
• When testing cases, keep intermediate artifacts, detection results, comparison results, and pipeline elapsed time in the case directory to make it easier to locate slow steps and failed steps.