# Ferruccio - WordPress Plugin Analysis Tool

Ferruccio is a static analysis tool designed to scan WordPress plugins (directories or zip files) and generate security reports for developers and security auditors. It prioritizes high-confidence detections while offering a "suspicious" mode for deeper manual review.

## Features

- **Smarter PHP Analysis**:
    - Tracks function scopes to accurately verify AJAX handlers (nonce/capability checks).
    - Detects SQL injection (unprepared `$wpdb` calls).
    - Detects XSS (unscaped `echo`/`print`).
    - Detects insecure file uploads and object injection (`unserialize`).
- **JavaScript Analysis**:
    - Detects DOM XSS (`innerHTML`, `document.write`).
    - Flags dangerous functions (`eval`, `setTimeout` with strings).
    - Checks for hardcoded secrets.
- **Attack Surface Mapping**: Lists actions, filters, REST routes, and shortcodes.
- **Multiple Formats**: Outputs reports in Text, Markdown, or JSON.
- **Extensible**: Supports custom config files and offline vulnerability databases.

## Installation

Requires Python 3.8+.

```bash
pip install ferruccio
```

## Usage

### CLI

```bash
# Check version
ferruccio --version

# Scan a single plugin (zip or directory)
ferruccio scan plugin.zip --wp-version 6.7 --php-version 8.2 --format text

# Scan all plugins in a directory (parallel execution)
ferruccio scan --all ./wp-content/plugins --threads 6 --format markdown > report.md

# Include low-confidence hints
ferruccio scan plugin.zip --include-suspicious --format json

# Use a config file and vulnerability DB
ferruccio scan plugin.zip --config .ferruccio.yml --vuln-db advisories.json
```

### Library

```python
from pathlib import Path
from ferruccio import scan_path, Scanner

# Simple scan
report = scan_path("plugin.zip", strict=True)
print(report.metadata.name, len(report.findings))

# Advanced usage
scanner = Scanner(strict=False, include_suspicious=True)
project = scanner.scan_plugins_dir(Path("./wp-content/plugins"))
print(project.summary)
```

## Configuration

You can customize the scanner using a `.ferruccio.yml` file:

```yaml
strict: true
include_suspicious: false
ignore_paths:
  - "tests/*"
  - "vendor/*"
deny_sinks:
  "system": "Command injection risk"
```

## License

MIT License. See [LICENSE](LICENSE) for details.
