# Obfuscation Detectors

## Overview

This directory contains all the detection logic for identifying different types of JavaScript obfuscation. Each **detector** is a self-contained module that analyzes the AST (Abstract Syntax Tree) of JavaScript code for patterns characteristic of a specific obfuscation technique.

Detectors are modular and easy to extend.

---

## List of Detectors

| Detector Name                                 | What It Detects                                      | Implementation File                                      |
|-----------------------------------------------|------------------------------------------------------|----------------------------------------------------------|
| **Array Replacements**                        | Large arrays of strings used as lookup tables         | [arrayReplacements.js](arrayReplacements.js)             |
| **Augmented Array Replacements**              | Array replacements with IIFE wrappers                 | [augmentedArrayReplacements.js](augmentedArrayReplacements.js) |
| **Array Function Replacements**               | Functions that return values from obfuscated arrays   | [arrayFunctionReplacements.js](arrayFunctionReplacements.js)   |
| **Augmented Array Function Replacements**     | Array function replacements with IIFE wrappers        | [augmentedArrayFunctionReplacements.js](augmentedArrayFunctionReplacements.js) |
| **Augmented Proxied Array Function Replacements** | Obfuscation using proxies and function arrays         | [augmentedProxiedArrayFunctionReplacements.js](augmentedProxiedArrayFunctionReplacements.js) |
| **Function To Array Replacements**            | Variables assigned to function calls, used as objects | [functionToArrayReplacements.js](functionToArrayReplacements.js) |
| **Obfuscator.io**                             | Patterns from the obfuscator.io tool                  | [obfuscatorIo.js](obfuscatorIo.js)                       |
| **Caesar Plus**                               | Caesar cipher-like obfuscation with 3-letter IDs      | [caesarPlus.js](caesarPlus.js)                           |

---

## Detector Details

### Array Replacements
- **File:** [arrayReplacements.js](arrayReplacements.js)
- **Description:** Detects large arrays of strings used as lookup tables for obfuscated code.

### Augmented Array Replacements
- **File:** [augmentedArrayReplacements.js](augmentedArrayReplacements.js)
- **Description:** Like array replacements, but the array is passed to an IIFE (Immediately Invoked Function Expression).

### Array Function Replacements
- **File:** [arrayFunctionReplacements.js](arrayFunctionReplacements.js)
- **Description:** Detects functions that return values from an obfuscated array, often used to hide string literals.

### Augmented Array Function Replacements
- **File:** [augmentedArrayFunctionReplacements.js](augmentedArrayFunctionReplacements.js)
- **Description:** Like array function replacements, but with IIFE wrappers for added obfuscation.

### Augmented Proxied Array Function Replacements
- **File:** [augmentedProxiedArrayFunctionReplacements.js](augmentedProxiedArrayFunctionReplacements.js)
- **Description:** Uses proxies and function arrays to further complicate deobfuscation.

### Function To Array Replacements
- **File:** [functionToArrayReplacements.js](functionToArrayReplacements.js)
- **Description:** Variables assigned to function calls, then used as objects of member expressions.

### Obfuscator.io
- **File:** [obfuscatorIo.js](obfuscatorIo.js)
- **Description:** Detects patterns generated by the [obfuscator.io](https://obfuscator.io/) tool, including debug protection and trap functions.
- **Example:** See the detailed explanation and code sample below.

### Caesar Plus
- **File:** [caesarPlus.js](caesarPlus.js)
- **Description:** Detects Caesar cipher-like obfuscation, typically with 3-letter function names and specific identifier usage.

---

## How to Add a New Detector

1. **Create a new file** in this directory, e.g., `myNewDetector.js`.
2. **Export a function** named `detectMyNewDetector` that takes the AST (flatTree) as input and returns the obfuscation name (or `''` if not detected).
3. **Add your detector** to `index.js` using `export * from './myNewDetector.js';`.
4. **Document your detector** in this README (add a row to the table above and a short description).
5. **Add tests** in the `tests/` directory to ensure your detector works as expected.

---

## References & Further Reading
- [obfuscator.io](https://obfuscator.io/)
- [AST Explorer](https://astexplorer.net/)

---

For questions or contributions, see the main [README](../README.md) and [CONTRIBUTING.md](../CONTRIBUTING.md).