{"id":22096079,"url":"https://github.com/HumanSecurity/obfuscation-detector","last_synced_at":"2025-07-24T22:31:38.236Z","repository":{"id":58340618,"uuid":"510385392","full_name":"PerimeterX/obfuscation-detector","owner":"PerimeterX","description":"Detect different types of JS obfuscation by their AST structure","archived":false,"fork":false,"pushed_at":"2023-09-10T11:19:31.000Z","size":399,"stargazers_count":38,"open_issues_count":1,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-04-14T14:59:36.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PerimeterX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-04T14:11:23.000Z","updated_at":"2024-06-19T13:33:10.447Z","dependencies_parsed_at":"2024-06-19T13:33:03.819Z","dependency_job_id":"7d038839-4ea7-469e-8e73-323e72537961","html_url":"https://github.com/PerimeterX/obfuscation-detector","commit_stats":{"total_commits":20,"total_committers":3,"mean_commits":6.666666666666667,"dds":0.4,"last_synced_commit":"8f59816e4fe049495ad161699d46ddcf7e6ec937"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fobfuscation-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fobfuscation-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fobfuscation-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fobfuscation-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PerimeterX","download_url":"https://codeload.github.com/PerimeterX/obfuscation-detector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227482496,"owners_count":17779968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-01T04:09:38.127Z","updated_at":"2025-07-24T22:31:38.223Z","avatar_url":"https://github.com/PerimeterX.png","language":"JavaScript","funding_links":[],"categories":["others","JavaScript"],"sub_categories":[],"readme":"# Obfuscation Detector\n[![Node.js CI](https://github.com/PerimeterX/obfuscation-detector/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/PerimeterX/obfuscation-detector/actions/workflows/node.js.yml)\n[![Downloads](https://img.shields.io/npm/dm/obfuscation-detector.svg?maxAge=43200)](https://www.npmjs.com/package/obfuscation-detector)\n\n## Overview\nObfuscation 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.\n\n**Use Cases:**\n- Automated analysis of suspicious or third-party JavaScript\n- Security auditing and malware research\n- Integration into CI/CD pipelines to flag obfuscated code\n- Educational purposes for understanding obfuscation techniques\n\n## How it Works\nObfuscation Detector parses JavaScript code into an AST using [flAST](https://www.npmjs.com/package/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.\n\n## Installation\n```shell\nnpm install obfuscation-detector\n```\n\n## Usage\n### As a Module\n```javascript\nimport fs from 'node:fs';\nimport detectObfuscation from 'obfuscation-detector';\n\nconst code = fs.readFileSync('obfuscated.js', 'utf-8');\nconst bestMatch = detectObfuscation(code); // returns [bestMatch] or []\nconst allMatches = detectObfuscation(code, false); // returns all matches as an array\nconsole.log(`Obfuscation type(s): ${allMatches.join(', ')}`);\n```\n\n### CLI\n```shell\nobfuscation-detector /path/to/obfuscated.js [--bestMatch|-b]\ncat /path/to/obfuscated.js | obfuscation-detector [--bestMatch|-b]\nobfuscation-detector --help\n```\n\n#### CLI Options\n- `--bestMatch`, `-b`: Return only the first (most likely) detected obfuscation type.\n- `--help`, `-h`: Show usage instructions.\n- Unknown flags will result in an error and print the usage.\n\n#### Examples\n- **All matches:**\n  ```shell\n  $ obfuscation-detector /path/to/obfuscated.js\n  [+] function_to_array_replacements, augmented_proxied_array_function_replacements\n  ```\n- **Best match only:**\n  ```shell\n  $ obfuscation-detector /path/to/obfuscated.js --bestMatch\n  [+] function_to_array_replacements\n  ```\n- **From stdin:**\n  ```shell\n  $ cat obfuscated.js | obfuscation-detector -b\n  [+] function_to_array_replacements\n  ```\n\n## API Reference\n### `detectObfuscation(code: string, stopAfterFirst: boolean = true): string[]`\n- **code**: JavaScript source code as a string.\n- **stopAfterFirst**: If `true`, returns after the first positive detection (default). If `false`, returns all detected types.\n- **Returns**: An array of detected obfuscation type names. Returns an empty array if no known type is detected.\n\n## Supported Obfuscation Types\nDescriptions and technical details for each type are available in [src/detectors/README.md](src/detectors/README.md):\n- [Array Replacements](src/detectors/arrayReplacements.js)\n- [Augmented Array Replacements](src/detectors/augmentedArrayReplacements.js)\n- [Array Function Replacements](src/detectors/arrayFunctionReplacements.js)\n- [Augmented Array Function Replacements](src/detectors/augmentedArrayFunctionReplacements.js)\n- [Function To Array Replacements](src/detectors/functionToArrayReplacements.js)\n- [Obfuscator.io](src/detectors/obfuscator-io.js)\n- [Caesar Plus](src/detectors/caesarp.js)\n\n## Troubleshooting\n- **No obfuscation detected:** The code may not be obfuscated, or it uses an unknown technique. Consider contributing a new detector!\n- **Error: File not found:** Check the file path and try again.\n- **Unknown flag:** Run with only `--help` to see what options are available.\n- **Performance issues:** For very large files, detection may take longer. Consider running with only the detectors you need (advanced usage).\n\n## Contribution\nTo contribute to this project, see our [contribution guide](CONTRIBUTING.md).\n\n---\nFor technical details on each obfuscation type and how to add new detectors, see [src/detectors/README.md](src/detectors/README.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSecurity%2Fobfuscation-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHumanSecurity%2Fobfuscation-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSecurity%2Fobfuscation-detector/lists"}