Obfuscation Detector

Overview
Obfuscation Detector is a tool for identifying different types of JavaScript obfuscation by analyzing the code's Abstract Syntax Tree (AST). It is designed for security researchers, reverse engineers, and developers who need to quickly determine if and how a JavaScript file has been obfuscated.
Use Cases:
- Automated analysis of suspicious or third-party JavaScript
- Security auditing and malware research
- Integration into CI/CD pipelines to flag obfuscated code
- Educational purposes for understanding obfuscation techniques
How it Works
Obfuscation Detector parses JavaScript code into an AST using flAST and applies a series of modular detectors. Each detector looks for specific patterns or structures that are characteristic of known obfuscation techniques. The tool can return all matching types or just the most likely (best) match.
Installation
npm install obfuscation-detector
Usage
As a Module
import fs from 'node:fs';
import detectObfuscation from 'obfuscation-detector';
const code = fs.readFileSync('obfuscated.js', 'utf-8');
const bestMatch = detectObfuscation(code);
const allMatches = detectObfuscation(code, false);
console.log(`Obfuscation type(s): ${allMatches.join(', ')}`);
CLI
obfuscation-detector /path/to/obfuscated.js [--bestMatch|-b]
cat /path/to/obfuscated.js | obfuscation-detector [--bestMatch|-b]
obfuscation-detector --help
CLI Options
--bestMatch
, -b
: Return only the first (most likely) detected obfuscation type.
--help
, -h
: Show usage instructions.
- Unknown flags will result in an error and print the usage.
Examples
- All matches:
$ obfuscation-detector /path/to/obfuscated.js
[+] function_to_array_replacements, augmented_proxied_array_function_replacements
- Best match only:
$ obfuscation-detector /path/to/obfuscated.js --bestMatch
[+] function_to_array_replacements
- From stdin:
$ cat obfuscated.js | obfuscation-detector -b
[+] function_to_array_replacements
API Reference
detectObfuscation(code: string, stopAfterFirst: boolean = true): string[]
- code: JavaScript source code as a string.
- stopAfterFirst: If
true
, returns after the first positive detection (default). If false
, returns all detected types.
- Returns: An array of detected obfuscation type names. Returns an empty array if no known type is detected.
Supported Obfuscation Types
Descriptions and technical details for each type are available in src/detectors/README.md:
Troubleshooting
- No obfuscation detected: The code may not be obfuscated, or it uses an unknown technique. Consider contributing a new detector!
- Error: File not found: Check the file path and try again.
- Unknown flag: Run with only
--help
to see what options are available.
- Performance issues: For very large files, detection may take longer. Consider running with only the detectors you need (advanced usage).
Contribution
To contribute to this project, see our contribution guide.
For technical details on each obfuscation type and how to add new detectors, see src/detectors/README.md.