Metadata-Version: 2.4
Name: afl-overseer
Version: 0.1.0
Summary: Monitoring and visualization tool for AFL/AFL++ fuzzing campaigns
Author-email: kirit1193 <kirit1193@users.noreply.github.com>
Maintainer-email: kirit1193 <kirit1193@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2024 kirit1193
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        This project was inspired by and evolved from the original afl-monitor tool.
        
        Original afl-monitor:
        Copyright (c) 2017 Paul S. Ziegler, Reflare Ltd.
        Licensed under the Apache License, Version 2.0
        
Project-URL: Homepage, https://github.com/kirit1193/afl-overseer
Project-URL: Repository, https://github.com/kirit1193/afl-overseer
Project-URL: Bug Tracker, https://github.com/kirit1193/afl-overseer/issues
Project-URL: Documentation, https://github.com/kirit1193/afl-overseer#readme
Keywords: afl,afl++,fuzzing,monitoring,visualization,security,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: textual>=0.40.0
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Dynamic: license-file

# AFL Overseer

Monitoring and visualization tool for AFL/AFL++ fuzzing campaigns.

[![PyPI version](https://img.shields.io/pypi/v/afl-overseer.svg)](https://pypi.org/project/afl-overseer/)
[![Python](https://img.shields.io/pypi/pyversions/afl-overseer.svg)](https://pypi.org/project/afl-overseer/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)

## Overview

AFL Overseer monitors AFL and AFL++ fuzzing campaigns, providing real-time statistics and performance metrics. It combines features from the original afl-monitor and AFLplusplus/afl-whatsup with additional capabilities.

### Features

- **Interactive TUI** - Terminal interface with live updates, sortable columns, and multiple detail levels
- **Web Dashboard** - Browser-based UI with real-time graphs and REST API
- **Process Detection** - Identifies alive, dead, and starting fuzzer instances
- **Resource Monitoring** - CPU and memory usage per fuzzer
- **Performance Warnings** - Detects dead fuzzers, low stability, high timeouts, and stalled campaigns
- **Crash Notifications** - Execute custom commands when new crashes are found
- **Comprehensive Stats** - Parses all fuzzer_stats fields including AFL++ 4.x extensions

### Tracked Metrics

Standard AFL metrics plus AFL++ extensions:
- `testcache_size`, `testcache_count`, `testcache_evict`
- `cpu_affinity`, `peak_rss_mb`
- `edges_found`, `total_edges`
- `var_byte_count`, `havoc_expansion`, `auto_dict_entries`
- `afl_version`, `target_mode`
- `slowest_exec_ms`, `execs_since_crash`
- Per-fuzzer CPU and memory usage
- Time without finds and comprehensive timing metrics

## Installation

### Requirements

- Python 3.8+
- Linux, macOS, or WSL2

### From PyPI (Recommended)

```bash
# Install from PyPI
pip install afl-overseer

# Run directly
afl-overseer /path/to/sync_dir
```

### From Source

#### Using a Virtual Environment

```bash
git clone https://github.com/kirit1193/afl-overseer.git
cd afl-overseer

python3 -m venv venv
source venv/bin/activate

pip3 install -r requirements.txt
chmod +x afl-overseer

./afl-overseer /path/to/sync_dir
```

### User Installation

```bash
git clone https://github.com/kirit1193/afl-overseer.git
cd afl-overseer

pip3 install --user -r requirements.txt
chmod +x afl-overseer

# Optional: Install globally
sudo ln -s $(pwd)/afl-overseer /usr/local/bin/
```

### Dependencies

```
click>=8.1.0      # CLI framework
rich>=13.0.0      # Terminal output
psutil>=5.9.0     # Process monitoring
textual>=0.40.0   # Interactive TUI
aiohttp>=3.8.0    # Web server
```

## Usage

### Interactive TUI

```bash
# Launch TUI (default mode)
afl-overseer /path/to/sync_dir

# Keyboard controls:
#   q - Quit
#   r - Refresh now
#   1/2/3 - Compact/Normal/Detailed view
#   n/s/c/e/r - Sort by Name/Speed/Coverage/Execs/Crashes
#   d - Toggle dead fuzzers
#   p - Pause/Resume auto-refresh
```

### Web Dashboard

```bash
# Start web server with TUI
afl-overseer -w /path/to/sync_dir

# Headless mode (no TUI)
afl-overseer -w --headless /path/to/sync_dir

# Custom port
afl-overseer -w -p 3000 /path/to/sync_dir

# Access at http://localhost:8080
```

### Static Output

```bash
# One-time output
afl-overseer -s /path/to/sync_dir

# Detailed per-fuzzer stats
afl-overseer -s -v /path/to/sync_dir

# Execute command on new crash
afl-overseer -s -e './send_alert.sh' /path/to/sync_dir
```

## Command-Line Options

| Option | Description |
|--------|-------------|
| `-t`, `--tui` | Interactive TUI mode (default) |
| `-s`, `--static` | Static terminal output |
| `-w`, `--web` | Start web server |
| `-p`, `--port PORT` | Web server port (default: 8080) |
| `--headless` | Run web server without TUI |
| `-v`, `--verbose` | Show detailed per-fuzzer statistics |
| `-n`, `--no-color` | Disable colored output |
| `-i`, `--interval SEC` | Refresh interval in seconds (default: 5) |
| `-d`, `--show-dead` | Include dead fuzzers in output |
| `-m`, `--minimal` | Minimal output mode |
| `-e`, `--execute CMD` | Execute command on new crash |
| `--version` | Show version |
| `--help` | Show help message |

## Architecture

```
afl-overseer/
├── afl-overseer            # Main executable
├── src/
│   ├── cli.py              # Command-line interface
│   ├── tui.py              # Interactive TUI
│   ├── webserver.py        # Web server and dashboard
│   ├── models.py           # Data models
│   ├── parser.py           # Stats and plot data parsers
│   ├── process.py          # Process detection and monitoring
│   ├── monitor.py          # Core monitoring logic
│   ├── utils.py            # Utility functions
│   └── output_terminal.py  # Terminal output formatter
├── requirements.txt        # Python dependencies
└── testing/                # Test utilities and benchmarks
```

### Process Detection

Fuzzer status is determined by:

- **Alive**: Process exists and responds to signals
- **Dead**: Process PID not found or no recent activity
- **Starting**: `fuzzer_setup` newer than `fuzzer_stats` with recent modification

### Performance Warnings

Automatic detection of:
- Dead fuzzer instances
- High timeout ratio (≥10%)
- Slow execution (<100 execs/sec)
- Cycles without finds (>10 cycles warning, >50 cycles critical)
- Low stability (<80%)
- High slowest execution time (>100ms)

## Web Dashboard

The web interface provides:
- Real-time graphs for speed, coverage, and paths/crashes
- Live fuzzer status table with warnings
- System resource monitoring
- Light/Dark theme toggle
- Mobile-responsive design
- REST API endpoint at `/api/stats`

Example API response:
```json
{
  "summary": {
    "alive_fuzzers": 3,
    "total_fuzzers": 3,
    "total_execs": 1000000,
    "current_speed": 500.0,
    "max_coverage": 45.2,
    "total_crashes": 5,
    "corpus_count": 250
  },
  "fuzzers": [...],
  "system": {...}
}
```

## Crash Notifications

Execute custom commands when new crashes are detected:

```bash
afl-overseer -s -e './notify.sh' /path/to/sync_dir
```

The command receives summary information via stdin:
```
AFL Overseer - New Crash Detected!

Timestamp: 2024-01-15 14:30:00
Total Crashes: 5
New Crashes: 2
Active Fuzzers: 8/10
Coverage: 12.34%
```

Example notification script:
```bash
#!/bin/bash
MESSAGE=$(cat)
curl -X POST https://hooks.slack.com/... -d "{\"text\": \"$MESSAGE\"}"
```

## Integration Examples

### Systemd Service

```ini
[Unit]
Description=AFL Overseer Web Dashboard
After=network.target

[Service]
Type=simple
User=fuzzer
WorkingDirectory=/home/fuzzer
ExecStart=/usr/local/bin/afl-overseer -w --headless -i 60 /fuzzing/sync_dir
Restart=always

[Install]
WantedBy=multi-user.target
```

### Remote Access

```bash
# Start headless web server
afl-overseer -w --headless -p 8080 /sync_dir

# SSH tunnel from local machine
ssh -L 8080:localhost:8080 user@remote-server

# Access at http://localhost:8080
```

## Performance

Optimized for scanning large fuzzing campaigns:
- **4 fuzzers**: ~7ms per scan
- **20 fuzzers**: ~28ms per scan
- **100 fuzzers**: ~111ms per scan

Achieves ~600-900 fuzzers/sec throughput through:
- Parallel processing with ThreadPoolExecutor
- Non-blocking CPU monitoring
- Efficient file parsing
- Optimized process detection

See `testing/benchmark.py` for performance testing.

## Troubleshooting

### Permission Denied

If you see warnings about process access:
```bash
# Add user to fuzzer's group
sudo usermod -a -G fuzzer $USER
```

### No Fuzzers Found

Check directory structure:
```
/sync_dir/
  ├── fuzzer01/
  │   └── fuzzer_stats
  ├── fuzzer02/
  │   └── fuzzer_stats
  └── ...
```

Use: `afl-overseer /sync_dir` (not `/sync_dir/fuzzer01`)

## Security

AFL Overseer is designed with security as a primary consideration and is **safe to expose to the internet** with proper network controls.

### Security Features

- ✅ **Read-Only Design** - Zero user input, no forms, no file uploads
- ✅ **GET Requests Only** - All HTTP endpoints are read-only
- ✅ **No Attack Surface** - No POST/PUT/DELETE, no query parameters processed
- ✅ **Static Content** - No XSS, CSRF, SQL injection, or command injection vectors
- ✅ **Thread-Safe** - Proper locking mechanisms prevent race conditions
- ✅ **Secure Dependencies** - Well-maintained, popular libraries only
- ✅ **No Authentication Needed** - Stateless, read-only monitoring

### Security Audits

The codebase undergoes automated security scanning:
- **Static Analysis**: pylint, flake8, mypy
- **Security Scanning**: bandit (SAST), Trivy (vulnerability scanner)
- **Dependency Checking**: safety, automated updates

See [SECURITY.md](SECURITY.md) for detailed security information and best practices.

### Recommended Deployment

While designed to be secure, we recommend:
1. **Network Controls**: Limit access via firewall/VPN
2. **Reverse Proxy**: Use nginx with rate limiting and SSL
3. **Monitoring**: Log access patterns
4. **Updates**: Keep dependencies current

## Project History

AFL Overseer is a rewrite of the original [afl-monitor](https://github.com/reflare/afl-monitor) tool by Paul S. Ziegler. This version addresses security issues in the Python 2.7 codebase (unsafe pickle usage, deprecated modules) and adds support for AFL++ 4.x features, interactive TUI, and web dashboard capabilities.

**Key differences from the original:**
- Python 3.8+ with type hints (vs Python 2.7)
- Interactive TUI and web dashboard (vs static output only)
- Secure implementation without pickle or command injection
- AFL++ 4.x field support with 50+ metrics
- Real-time resource monitoring per fuzzer
- Parallel processing for improved performance

Thanks to Paul S. Ziegler for the original afl-monitor.

## License

Copyright (c) 2024 kirit1193. Licensed under the MIT License.

Original afl-monitor: Copyright (c) 2017 Paul S. Ziegler, Reflare Ltd. (Apache License 2.0)

See [LICENSE](LICENSE) for details.

## Acknowledgments

- Original afl-monitor by Paul S. Ziegler
- AFLplusplus project and afl-whatsup
- AFL by Michal Zalewski

## Support

- Issues: [GitHub Issues](https://github.com/kirit1193/afl-overseer/issues)
- Discussions: [GitHub Discussions](https://github.com/kirit1193/afl-overseer/discussions)
