# ffuf-automation

> **Professional ffuf Web Directory Discovery Automation Tool**
>

---

## ⚠️ Legal Warning

**This tool is for authorized security testing only.**

You must only scan domains you **own** or have **explicit written authorization** to test.  
Unauthorized use is illegal under CFAA, the Computer Misuse Act, and equivalent laws worldwide.  
The author bears zero liability for misuse.

---

## Features

| Feature | Details |
|---|---|
| Multi-domain automation | Reads `domains.txt`, normalizes, deduplicates |
| Full ffuf options | Recursion, extensions, match/filter codes, word/size/line filters |
| Interesting path detection | Flags `/api`, `/admin`, `/login`, `/.env`, `/.git`, and more |
| Structured output | Raw JSON per domain + consolidated reports |
| HTML report | Dark-themed, table-of-contents, color-coded status codes |
| CSV report | Flat export, importable into Excel / Google Sheets |
| JSON report | Machine-readable full scan data |
| Scope enforcement | Optional `--scope` whitelist file |
| Safety controls | Confirmation prompt, delay option, max-results cap |
| Scan deduplication | Skips domains already scanned in the same run |
| Error resilience | Failed domains logged separately; scan continues |

---

## Requirements

- Python 3.9+
- `ffuf` installed and in `$PATH`
- (Optional but recommended) `jinja2` for full HTML report

### Install Python dependencies

```bash
pip install -r requirements.txt
```

### Install ffuf

```bash
# Kali Linux / Debian
sudo apt install ffuf

# Go (any platform)
go install github.com/ffuf/ffuf/v2@latest

# Verify
ffuf -V
```

---

## Installation

```bash
git clone https://github.com/your-repo/ffuf-automation.git
cd ffuf-automation
pip install -r requirements.txt
chmod +x ffuf_automation.py
```

---

## Usage

### Basic

```bash
python3 ffuf_automation.py \
  --domains domains.txt \
  --wordlist /usr/share/wordlists/dirb/common.txt \
  --output results
```

### Full Options

```bash
python3 ffuf_automation.py \
  --domains domains.txt \
  --wordlist /root/SecLists/Discovery/Web-Content/directory-list-2.3-small.txt \
  --depth 2 \
  --extensions .php,.txt,.bak,.json,.asp,.aspx,.js \
  --match-codes 200,204,301,302,401,403 \
  --filter-codes 404 \
  --filter-words 10,20 \
  --filter-sizes 1234,5678 \
  --filter-lines 0 \
  --threads 50 \
  --timeout 10 \
  --rate 100 \
  --delay 2 \
  --max-results 500 \
  --output results
```

### With Scope File

```bash
python3 ffuf_automation.py \
  --domains domains.txt \
  --wordlist wordlist.txt \
  --scope scope.txt \
  --output results
```

---

## All CLI Arguments

| Argument | Default | Description |
|---|---|---|
| `--domains` | *(required)* | Path to domains file |
| `--wordlist` | *(required)* | Path to ffuf wordlist |
| `--output` | `results` | Output directory |
| `--depth` | `1` | Recursion depth (0 = disabled) |
| `--extensions` | *(none)* | Extensions e.g. `.php,.txt,.bak` |
| `--match-codes` | `200,204,301,302,403,401` | HTTP codes to include |
| `--filter-codes` | `404` | HTTP codes to exclude |
| `--filter-words` | *(none)* | Filter by word count e.g. `10,20` |
| `--filter-sizes` | *(none)* | Filter by response size e.g. `1234` |
| `--filter-lines` | *(none)* | Filter by line count e.g. `0` |
| `--threads` | `40` | Concurrent ffuf threads |
| `--timeout` | `10` | Per-request timeout (seconds) |
| `--rate` | `0` | Max requests/sec (0 = unlimited) |
| `--delay` | `0` | Delay between domains (seconds) |
| `--max-results` | `0` | Max results per domain (0 = unlimited) |
| `--scope` | *(none)* | Optional scope whitelist file |

---

## Output Structure

```
results/
├── raw/
│   ├── example.com.json          ← raw ffuf output per domain
│   └── staging.myapp.io.json
├── reports/
│   ├── report_20250522_143000.html   ← full styled HTML report
│   ├── report_20250522_143000.csv    ← flat CSV export
│   └── report_20250522_143000.json  ← machine-readable JSON
└── logs/
    └── scan_20250522_143000.log      ← full debug log
```

---

## Report Sections

### HTML Report
- Scan summary statistics
- Configuration used
- Domain index (table of contents)
- Per-domain results table with color-coded status codes:
  - 🟢 200 OK
  - 🔵 301/302 Redirect
  - 🟡 401 Unauthorized
  - 🟠 403 Forbidden
  - 🔴 500 Server Error
- Interesting findings highlighted
- Failed domains list

### CSV Report
Columns: `domain, url, path, status, length, words, lines, redirect, interesting`

### JSON Report
Full structured data including scan config, per-domain results, interesting paths, failed domains.

---

## Interesting Paths Detected

The tool automatically flags paths matching:

```
/api     /admin    /login    /dashboard  /backup
/config  /core     /uploads  /dev        /test
/.env    /.git     /wp-admin /phpmyadmin /swagger
/graphql /internal /debug    /secret
```

---

## Example ffuf Command (generated internally)

```bash
ffuf \
  -w /root/SecLists/.../common.txt:FUZZ \
  -u https://example.com/FUZZ \
  -recursion \
  -recursion-depth 2 \
  -e .php,.txt,.bak \
  -mc 200,204,301,302,401,403 \
  -fc 404 \
  -t 50 \
  -timeout 10 \
  -noninteractive \
  -of json \
  -o results/raw/example.com.json
```

---

## Tips

- Use **SecLists** for best wordlists: `apt install seclists` on Kali
- Start with `--depth 1` and `--threads 40`; increase carefully
- Use `--delay 2` between domains when testing multiple targets
- Always verify `--scope` enforcement for bug bounty programs
- Check `results/logs/` for detailed per-domain debug info

---

## Disclaimer

This tool automates ffuf — a legitimate open-source security testing tool.
**It must only be used on systems you are authorized to test.**
By using this tool, you accept full legal responsibility for your actions.