WRAITH

Features

Architecture

wraith/
├── src/
│ ├── main.py # CLI entry point
│ ├── cli/commands.py # Click command group
│ ├── core/
│ │ ├── aggregator.py # Async multi-feed orchestration
│ │ ├── config.py # YAML + env-var configuration loader
│ │ ├── database.py # SQLAlchemy models + session management
│ │ ├── monitor.py # Continuous monitoring daemon
│ │ └── reporter.py # Rich table / JSON / CSV output
│ ├── feeds/
│ │ ├── base.py # BaseFeed with retry, rate-limit handling
│ │ ├── hibp.py # HaveIBeenPwned v3
│ │ ├── dehashed.py # DeHashed API
│ │ ├── intelx.py # Intelligence X
│ │ ├── pastebin.py # Pastebin scrape API
│ │ └── github.py # GitHub code search + secret detection
│ └── alerting/notifier.py # Slack / Discord / SMTP alerting
├── dashboard/
│ ├── backend/app.py # Flask REST API
│ └── frontend/index.html # Single-file SPA dashboard
├── tests/ # pytest test suite
├── docs/ # Architecture, API, deployment docs
├── config.yaml # Default configuration
└── .env.example # Environment variable template

Screenshots

Quick Start

Prerequisites

Installation

git clone https://github.com/xdrew87/wraith.git
cd wraith
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys
py src/main.py init

First Scan

# Scan a domain once
py src/main.py scan example.com
# Scan a specific email
py src/main.py scan user@example.com
# Scan with specific feeds only
py src/main.py scan example.com --feeds hibp,dehashed
# Output as JSON
py src/main.py scan example.com --format json --output results.json

Continuous Monitoring

# Add targets to the watch list
py src/main.py watch example.com
py src/main.py watch admin@example.com
# Start the monitor daemon (scans all watch targets on configured interval)
py src/main.py monitor
# Remove a target
py src/main.py unwatch example.com

Web Dashboard

py src/main.py dashboard --port 5050
# Open http://localhost:5050

Configuration

Environment Variables

config.yaml Reference

database:
 sqlite_path: "wraith.db" # SQLite file path (ignored if DATABASE_URL is set)
feeds:
 hibp:
 enabled: true
 rate_limit: 1 # Requests per second (free tier limit)
monitor:
 interval_seconds: 3600 # How often to re-scan watch targets
alerting:
 enabled: true
 min_severity: "MEDIUM" # Only alert on findings at or above this severity
logging:
 level: "INFO"
 file: "logs/wraith.log"
 max_bytes: 10485760 # 10 MB per file
 backup_count: 5

Docker

# Build and run
docker compose up -d
# View logs
docker compose logs -f
# Run a scan inside the container
docker compose exec wraith py src/main.py scan example.com

CLI Reference

Commands:
 init Initialize the WRAITH database
 scan Scan a domain or email for credential exposures
 watch Add a target to the continuous watch list
 unwatch Remove a target from the watch list
 report Display credential exposure findings from the database
 alerts Display recent alerts
 monitor Run the continuous monitoring daemon
 dashboard Launch the web dashboard
Options (all commands):
 --config PATH Path to config.yaml (default: auto-detected)
scan options:
 --feeds TEXT Comma-separated list of feeds (hibp,dehashed,intelx,pastebin,github)
 --format TEXT Output format: table | json | csv (default: table)
 --output PATH Write output to file
report options:
 --target TEXT Filter by target
 --severity TEXT Filter by severity: LOW | MEDIUM | HIGH | CRITICAL
 --format TEXT Output format: table | json | csv
 --limit INT Maximum results (default: 100)
dashboard options:
 --port INT Port to listen on (default: 5050)
 --host TEXT Bind address (default: 127.0.0.1)

Dashboard API

Output Example

 ██╗ ██╗██████╗ █████╗ ██╗████████╗██╗ ██╗
 ...
Scanning: example.com (type: domain)
╭─────────────────────────────────────────────────────────────────────╮
│ WRAITH — 5 Finding(s) │
├───────────────┬──────────┬───────────────────┬────────────┬─────────┤
│ Target │ Source │ Type │ Severity │ Breach │
├───────────────┼──────────┼───────────────────┼────────────┼─────────┤
│ example.com │ HIBP │ domain_breach │ HIGH │ Test │
│ example.com │ DeHashed │ plaintext_password│ CRITICAL │ TestDB │
│ example.com │ IntelX │ paste_hit │ HIGH │ pastes │
│ example.com │ GitHub │ aws_access_key │ CRITICAL │ user/r │
│ example.com │ Pastebin │ paste_email │ HIGH │ pb:xyz │
╰───────────────┴──────────┴───────────────────┴────────────┴─────────╯
Summary: 5 findings — 2 CRITICAL | 3 HIGH

Roadmap

Contributing

⚠️ Authorized Use Only

License

FAQ

Troubleshooting