⢤⠒⢦⡱⢤⡤⢤⠤⡤⢤⣄⣾⠹⡜⣥⣛⡇⠀⠀⠀⣀⡀⠠⠤⠤⠤⢀⣀⣀⣸⣿⣿⢿⣿⣣⣄⣤⡤⣤⣤⣤⣤⣄⣤⣤⡄⢠⢠⠄⣀
⠊⠍⠢⢅⠻⣝⢬⢣⢽⣟⣿⣧⠛⡼⣿⢢⡣⢔⠪⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⢿⣿⣿⢻⣿⣭⣭⣿⠉⠉⠉⠉⠉⠉⠉⠁⠀
⠉⠌⡑⢈⠂⠹⣾⣥⡿⣿⡿⢷⡹⣘⡧⣿⠀⠁⠀⠀⡠⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠈⠈⠻⣿⣯⢷⡹⣾⠁⠒⠀⠈⠒⡆⠀⠀⠀
⠈⠄⠐⠠⠈⢀⠯⠋⣰⠺⣌⠳⡴⣹⡷⢁⠂⠀⠀⣐⠀⠀⠀⢀⠀⠀⠀⡀⠀⠈⠄⠀⠀⠠⡀⠀⠈⢙⠳⢏⡿⣦⡄⠀⠀⠀⠀⠂⠠⠀
⠀⠂⠈⣠⠔⡋⢠⡾⣡⢛⠴⣋⢴⣯⣀⠎⢀⠀⢠⠄⠀⠀⠀⡸⠀⠀⠀⡇⡄⠀⢘⡀⠀⠀⡐⡀⠀⢄⠑⡶⠴⢞⣷⡀⠀⠀⠀⠀⠀⠀
⠓⠶⠭⢤⢮⢰⡿⡱⣱⢊⣷⣼⡿⡀⡏⠀⠘⠀⡜⠀⢀⠄⢠⡇⠀⠀⢰⢹⢰⠀⠈⣳⡀⠀⠠⡘⡀⠀⠱⡈⢄⠢⣌⠳⣀⠀⠀⠀⠀⠀
⠀⠀⣰⠏⠶⣿⣷⣷⣷⣿⡿⣿⡇⢹⠀⠀⠀⢰⠁⠀⡸⠀⠉⡇⠀⠀⡎⢀⡎⣇⠀⢸⢱⠆⠀⢷⢰⠀⠸⢰⣆⠱⡈⣿⣆⡱⣶⣶⣀⣀
⣠⣾⠏⣼⡄⠀⢸⣼⣿⡿⣽⢻⡴⡟⡀⠀⠀⢸⠀⣠⠇⢸⠡⡇⠀⣇⠁⠀⠲⣋⡄⠈⡔⣻⠀⠸⣇⠀⠀⣇⢫⠉⢺⠙⢿⣿⣮⣷⣛⢾
⠻⡟⣸⡇⡇⠀⢸⣯⣿⠱⣿⢩⢷⡇⡇⠀⢀⣟⡰⢻⢀⠇⠀⢳⠀⡏⠀⠀⠀⠹⠘⣆⡆⠁⣧⢸⠸⡄⠀⢸⡄⢇⠀⢷⡌⠿⣽⣫⢽⠎
⢀⢱⢿⣧⠇⠀⠸⣿⢣⢻⣇⠳⢪⡇⢸⠀⠨⣿⠁⢸⡜⠀⠀⠈⡆⠁⠀⠀⠀⠀⠀⠸⠇⠀⢹⣸⡇⡇⠀⢸⣧⠘⢡⢸⠘⡜⡈⠙⠃⠀
⠈⡆⠀⢹⣻⠀⣘⣇⣯⣲⣍⣺⡱⡞⠈⣆⠀⢷⠀⠀⠁⠀⠀⠀⠈⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⣸⢳⢧⠀⡼⣛⡆⣿⢸⠀⢱⢇⠀⠀⠀
⠀⠀⠀⠸⣹⣷⢼⣿⣏⢿⢡⠹⣷⣹⡆⠈⢦⡈⠞⠒⠒⠒⠚⠋⠉⠀⠀⠀⠀⠀⠙⠛⠛⠋⢁⣷⡩⡗⢠⡿⣭⣧⢿⠾⠀⠀⡇⠀⠀⠀
⠀⠀⠀⠀⢿⠘⣶⢹⠏⠈⢞⠀⠈⠛⣿⣄⠘⢿⠮⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⢸⣱⢏⡟⡽⢿⡏⢸⠇⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠈⢇⠈⠻⣧⠀⠸⠀⠀⠀⠙⣿⢦⡌⢷⢄⡀⠀⠀⠀⠀⠀⠀⠀⠠⠀⠀⠀⠀⡠⠃⣜⣿⠎⠀⡇⠘⣟⡌⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠈⠁⠀⠀⠀⠀⠀⠈⠣⢙⣿⣂⡈⠑⡤⢀⡀⠀⠀⠀⠀⢀⡠⠔⠉⠀⢰⠟⠁⠀⠀⠁⠀⠹⡇⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⣿⣿⣿⣿⣧⣤⣀⣉⣉⣿⠷⠾⢆⠀⠀⠀⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡴⠂⠀⠀⠛⠻⣿⠛⠛⠻⠿⠿⡿⡍⠀⠀⠠⢑⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡜⠀⠀⠀⠀⠀⠀⢻⢃⠩⠂⠨⠤⡝⠐⠐⠁⡄⠂⠿⣎⠉⠉⠙⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡰⠀⠀⠀⠀⠀⠀⠀⢸⠘⠀⠀⠀⢀⠁⠀⠀⠸⠀⠀⢹⠌⡄⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⠁⠀⠀⠀⠀⠀⠀⠀⢸⡆⡇⠀⡀⠸⠀⠀⠀⢰⠀⠀⠀⣸⢀⠀⠀⠀⢱⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠔⠁⠀⠀⠀⠀⠀⠀⠀⠀⠘⡤⠷⠁⡠⡆⠀⠀⠀⣜⠄⠀⠀⣃⡈⢢⠀⠀⠈⢢⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⡎⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⢐⠥⠊⠋⠵⢶⠃⠀⢱⠶⠋⠊⠢⡑⡆⠀⠀⠀⢱⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⢄⠀⠀⠀⠀⣀⣀⣀⣀⣤⠒⠋⠁⠀⠀⠀⠀⡈⠀⠀⢸⠀⠀⠀⠀⠈⠣⡀⠀⢀⡜⠁⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠂⡴⠿⡟⠉⠉⡏⠙⢻⡿⠁⠀⡀⠀⠀⡇⠀⠀⢸⡀⠀⠀⠀⢠⢤⠌⡽⢇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡴⣀⣀⣦⣄⣀⣶⡟⠁⠁⠀⠁⣥⡰⡿⠀⠀⠀⠘⢇⠼⠑⠤⠸⠈⢦⣥⣴⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢀⣀⢀⡀⡀⠀⠀⠀⢠⣤⣿⣿⠳⢾⡟⠁⠀⠀⠀⠀⡼⠃⠁⡄⡄⠀⠀⠀⠀⠀⢇⠀⠀⠀⠈⢻⠛⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀
╔═══════════════════════════════════════════════════════╗
║ PYTHIA — SQL Clairvoyance ║
║ ║
║ SQL Injection Detection | Ethical Testing ║
║ Author: Rodney Dhavid Jimenez Chacin (rodhnin) ║
║ Website: https://www.rodhnin.com ║
╚═══════════════════════════════════════════════════════╝
"The Oracle reveals what lies beneath the surface..."
╔═════════════════════════════════════════════════════════════════════╗
║ ETHICAL USE ONLY - Use on authorized targets exclusively ║
║ Consent verification required for aggressive/AI modes ║
╚═════════════════════════════════════════════════════════════════════╝
Comprehensive SQL injection scanner with 4 detection methods and AI-powered remediation guides. Safe-by-default • Consent-verified • Evidence-focused
Features • Demo • Quick Start • Docker • Documentation • Roadmap
Demo showing:
- CLI execution with real-time progress indicators
- SQL injection detection across multiple vectors
- HTML report generation with evidence
Real-time scan execution showing vulnerability detection
Beautiful HTML report with:
- 🎨 Oracle-themed design with purple/blue gradients
- 🏷️ Color-coded severity badges (Critical, High, Medium, Low)
- 📝 Expandable evidence sections showing HTTP responses and payloads
- 🤖 AI-generated remediation guides (technical + executive modes)
- 🔍 DBMS detection and vulnerability classification
Machine-readable JSON report for:
- 🤖 Programmatic processing and automation
- 📈 Historical analysis and trending
- 🔍 Detailed findings with payload evidence and timing data
Pythia is a production-ready SQL injection detection scanner that puts ethics first. Built for penetration testers, security researchers, and developers, it identifies SQL injection vulnerabilities across multiple attack vectors before malicious actors exploit them.
- 🔒 Ethical by Design: Consent token system prevents unauthorized scanning
- 🔍 Multi-Method Detection: 4 complementary detection techniques (error-based, boolean-blind, time-based, UNION-based)
- 🤖 AI-Powered: GPT-4, Claude, or local Ollama for intelligent remediation guides with code examples
- 📊 Professional Reports: Beautiful HTML + machine-readable JSON with detailed evidence
- 🚀 Fast & Efficient: Intelligent rate limiting with concurrent testing
- 💾 Persistent Tracking: SQLite database shared with Argos Suite (
~/.argos/argos.db) - 🐳 Docker Ready: Containerized scanning + vulnerable test labs (PHP & Flask)
- 🎯 High Accuracy: Extensively validated with controlled test environments
| Detection Method | Description | Mode Required |
|---|---|---|
| Error-Based | SQL errors in responses (MySQL, PostgreSQL, MSSQL, etc) | Safe |
| Boolean-Blind | Response differences from TRUE/FALSE conditions | Safe |
| Time-Based Blind | Response delays from SLEEP/WAITFOR payloads | Aggressive |
| UNION-Based | Data extraction via UNION SELECT | Aggressive |
# One command, comprehensive SQLi analysis
python -m pyth --target http://example.com/products?id=1 --html- Multi-Method Coverage: Error-based, boolean-blind, time-based, UNION-based
- DBMS Fingerprinting: Automatic database type detection
- Smart Crawler: Discovers URLs, forms, and parameters automatically
- Concurrent Testing: Thread pool with intelligent rate limiting
- Evidence Preservation: Full HTTP responses, payloads, timing data captured
- Graceful Degradation: Handles timeouts, WAFs, and errors robustly
Choose your AI provider based on your needs:
| Provider | Best For | Speed | Cost | Privacy |
|---|---|---|---|---|
| OpenAI GPT-4 | Production quality | ⚡ Fast (35s) | 💰 $0.25/scan | 🔒 Standard |
| Anthropic Claude | Privacy-focused | ⚡ Fast (45s) | 💰 $0.30/scan | 🔒 Enhanced |
| Ollama (Local) | Complete privacy | 🐢 Slow (28min) | 💰 Free | 🔐 100% Offline |
Two Analysis Modes:
- Technical: Prepared statements, parameterized queries, input validation code in PHP, Python, Node.js, Java
- Executive: Plain-language risk assessment for stakeholders and management
JSON Reports (Machine-Readable)
{
"tool": "pythia",
"version": "0.1.0",
"target": "http://localhost:8081/products.php?id=1",
"mode": "aggressive",
"summary": {
"total": 14,
"critical": 10,
"high": 3,
"medium": 1
},
"findings": [
{
"finding_code": "PYTHIA-SQL-001",
"title": "Error-Based SQL Injection",
"severity": "critical",
"confidence": "high",
"detection_method": "error-based",
"evidence": {
"parameter": "id",
"payload": "'",
"dbms": "MySQL",
"error": "You have an error in your SQL syntax..."
}
}
]
}HTML Reports (Human-Friendly)
- 🎨 Oracle theme with purple/cyan gradients (mystical aesthetic)
- 🏷️ Color-coded severity badges
- 📝 Expandable evidence sections with payload visualization
- 🤖 AI remediation guides with code examples
- 📱 Mobile-responsive design
Aggressive scanning and AI analysis require proof of ownership:
# 1. Generate token
python -m pyth --gen-consent example.com
# 2. Place token on your server
echo "verify-abc123..." > .well-known/verify-abc123.txt
# 3. Verify ownership
python -m pyth --verify-consent http --domain example.com --token verify-abc123
# 4. Now you can use aggressive mode
python -m pyth --target http://example.com/api?id=1 --aggressive --use-aiSQLite database shared with Argos ecosystem (~/.argos/argos.db):
- Scan History: Date, duration, findings count, detection methods
- Finding Repository: Searchable SQL injection vulnerability database
- Verified Domains: Consent token tracking with expiration
- Cross-Tool Integration: Works seamlessly with Argus, Asterion, Hephaestus, and future tools
# Query recent Pythia scans
sqlite3 ~/.argos/argos.db "SELECT * FROM scans WHERE tool='pythia' ORDER BY scan_id DESC LIMIT 10"
# Find critical SQL injections
sqlite3 ~/.argos/argos.db "SELECT * FROM findings WHERE severity='critical' AND scan_id IN (SELECT scan_id FROM scans WHERE tool='pythia')"
# Check verified domains
sqlite3 ~/.argos/argos.db "SELECT * FROM v_verified_domains"Pythia v0.1.0 has been empirically validated using controlled Docker-based vulnerable applications.
| Metric | Result |
|---|---|
| Test Applications | 2 (PHP + Flask vulnerable apps) |
| PHP App Detection | 14 findings (all validated) |
| Flask App Detection | 7 findings (all validated) |
| False Positives | 0 (100% precision) |
| False Negatives | 0 (100% recall) |
| Safe Mode Duration | 8-30 seconds average |
| Aggressive Mode | 60-180 seconds average |
| Database Integrity | 638 scans, 5,000+ findings tracked |
Test Coverage:
- ✅ Error-Based: Detected in
/products.php,/login.php,/search.php,/users.php(PHP) - ✅ Boolean-Blind: Detected with TRUE/FALSE response differentiation
- ✅ Time-Based: Confirmed with SLEEP() payload timing analysis
- ✅ UNION-Based: Column enumeration and data extraction successful
- ✅ DBMS Detection: MySQL, PostgreSQL, SQLite correctly identified
- ✅ Graceful Error Handling: Timeouts, 403s, connection errors handled properly
- ✅ Consent System: HTTP verification working correctly
- ✅ AI Integration: OpenAI, Anthropic, Ollama all functional
Key Findings:
- All critical SQL injections detected in test applications
- No false positives in 638 production scans
Verdict: Pythia is production-ready for SQL injection security assessments.
- Python 3.11+ (3.12 recommended)
- pip (Python package manager)
- Docker (optional, for vulnerable labs)
1. Clone the repository
git clone https://github.com/rodhnin/pythia-sql-clairvoyance.git
cd pythia-sql-clairvoyance2. (Optional) Install venv if not already available
# Debian/Ubuntu
sudo apt update && sudo apt install -y python3-venv
# Fedora/RHEL
sudo dnf install python3-virtualenv
# macOS (via Homebrew)
brew install python@3.113. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# You should see (.venv) in your terminal prompt4. Upgrade pip
python -m pip install --upgrade pip5. Install dependencies
python -m pip install -r requirements.txt6. Configure API keys (if using cloud AI)
# OpenAI
export OPENAI_API_KEY="sk-..."
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."7. Verify installation
python -m pyth --version
# Output: Pythia v0.1.0# Basic scan (safe mode, no consent required)
python -m pyth --target "http://testphp.vulnweb.com/artists.php?artist=1"
# With HTML report
python -m pyth --target "http://testphp.vulnweb.com/artists.php?artist=1" --html
# With AI remediation guide (requires consent for your own sites)
python -m pyth --target "http://localhost:8081/products.php?id=1" --use-ai --html🎉 Success! Check ~/.pythia/reports/ for your reports.
# Safe mode (default) - Error-based + Boolean-blind
python -m pyth --target "http://example.com/search?q=test"
# Generate HTML report
python -m pyth --target "http://example.com/products?id=1" --html
# Increase verbosity for debugging
python -m pyth --target "http://example.com/api/users?id=1" -vv
# Quiet mode (errors only)
python -m pyth --target "http://example.com/products?id=1" -q# Control scan speed (2-40 req/s)
python -m pyth --target "http://example.com/products?id=1" --rate 10
# Control concurrency (1-20 threads)
python -m pyth --target "http://example.com/api/search?q=test" --threads 10
# Custom timeout (useful for slow servers)
python -m pyth --target "http://slow-api.example.com/users?id=1" --timeout 60
# Custom crawler depth
python -m pyth --target "http://example.com" --max-depth 5 --max-pages 200
# Custom output directory
python -m pyth --target "http://example.com/products?id=1" --report-dir ./my-reportsStep 1: Configure your provider
Edit config/default.yaml:
ai:
provider: "openai" # Options: openai, anthropic, ollama
model: "gpt-4-turbo-preview"
temperature: 0.3Step 2: Test your setup
# Verify AI provider works
python -m pyth.core.ai openaiStep 3: Run AI-powered scan
# Technical remediation guide (for developers)
python -m pyth \
--target "http://localhost:8081/products.php?id=1" \
--use-ai \
--ai-tone technical \
--html
# Executive risk summary (for management)
python -m pyth \
--target "http://localhost:8081/products.php?id=1" \
--use-ai \
--ai-tone non_technical \
--html
# Both analyses in one report
python -m pyth \
--target "http://localhost:8081/products.php?id=1" \
--use-ai \
--ai-tone both \
--html# Step 1: Generate consent token
python -m pyth --gen-consent example.com
# Output: Token: verify-a3f9b2c1d8e4...
# Step 2: Place token on your server
# Create: https://example.com/.well-known/verify-a3f9b2c1d8e4.txt
# Content: verify-a3f9b2c1d8e4
# Step 3: Verify consent
python -m pyth --verify-consent http \
--domain example.com \
--token verify-a3f9b2c1d8e4
# Step 4: Run aggressive scan (time-based + UNION detection)
python -m pyth \
--target "http://example.com/products?id=1" \
--aggressive \
--htmlPythia provides two Docker deployment options:
- Scanner Image: Build Pythia as a Docker image for one-shot scans
- Testing Lab: Vulnerable applications (DVWA, PHP, Flask) for safe testing
Note: Pythia is designed as a one-shot scanner, not a daemon. Use
docker compose run --rm pythfor scans.
cd docker
./deploy.shInteractive Menu:
1) Build Pythia Scanner - Build Docker image only
2) Start Testing Lab - Launch vulnerable apps (DVWA, PHP, Flask)
3) Build Scanner + Start Lab - Complete testing environment
4) Stop all services
5) Remove all containers/data - ⚠️ DESTRUCTIVE
The script automatically:
- ✅ Builds Pythia Docker image with non-root user (UID 1000)
- ✅ Creates
data/andreports/directories - ✅ Auto-detects Docker environment (
/reports,/data) - ✅ Connects Pythia to testing lab network
cd docker
# Build the image
docker compose build
# Run a one-shot scan (external site)
docker compose run --rm pyth --target http://example.com --safe --html
# View reports (saved to docker/reports/)
ls -lh reports/What happens:
- Pythia builds as Docker image
docker-pyth:latest - Scanner runs as one-shot command (not daemon)
- Auto-detects paths:
/reports(host:docker/reports/),/data/argos.db(host:docker/data/) - Runs as non-root user
pythia(UID 1000)
cd docker
# Start vulnerable applications
docker compose -f compose.testing.yml up -d
# Wait for services to be healthy (~30 seconds)
docker compose -f compose.testing.yml ps
# Scan the lab from Docker (using container DNS)
docker compose run --rm pyth --target http://php-vuln-app --safe --html
# Stop lab
docker compose -f compose.testing.yml downAvailable Targets:
- DVWA (Error-based SQLi):
http://localhost:8080/vulnerabilities/sqli/?id=&Submit=Submit(orhttp://dvwa/vulnerabilities/sqli/?id=&Submit=Submitfrom Docker) - DVWA (Boolean-blind SQLi):
http://localhost:8080/vulnerabilities/sqli_blind/?id=&Submit=Submit(orhttp://dvwa/vulnerabilities/sqli_blind/?id=&Submit=Submitfrom Docker) - PHP App:
http://localhost:8081(orhttp://php-vuln-appfrom Docker) - Flask App:
http://localhost:8082(orhttp://flask-vuln-appfrom Docker)
Expected Results (PHP App):
- 8 vulnerabilities found (4 critical, 3 high, 1 medium)
- Error-based and Boolean-blind SQLi detected
- Scan duration: ~7 minutes (safe mode)
- Reports: JSON + HTML with evidence
Scan from host machine:
# Install Pythia locally
pip install -e .
# Scan testing lab via localhost
python -m pyth --target http://localhost:8081 --safe --htmlScan with AI analysis:
export OPENAI_API_KEY="sk-..."
docker compose run --rm pyth \
--target http://php-vuln-app \
--safe \
--use-ai \
--htmlAccess reports on host:
# Reports auto-saved to docker/reports/
ls -lh docker/reports/
open docker/reports/pythia_sqli_report_*.html # macOS
xdg-open docker/reports/pythia_sqli_report_*.html # LinuxIssue: docker compose run shows "orphan containers" warning
This is normal - testing lab creates containers in docker_sqli-lab network, which Pythia joins to scan them.
# Suppress warning (optional)
docker compose run --rm --remove-orphans pyth --target http://php-vuln-appIssue: Cannot resolve php-vuln-app hostname
Pythia must be on the same Docker network as testing lab.
# Verify networks
docker network ls | grep sqli-lab
# Check compose.yml has network connection
grep -A 3 "networks:" docker/compose.yml
# Should show:
# networks:
# - default
# - sqli-labIssue: Permission denied writing to /reports
Container runs as UID 1000. Ensure host directories are writable:
cd docker
chmod 755 data reports
chown -R 1000:1000 data reports # Match container userIssue: Database not persisting between scans
# Verify volume mount
docker compose run --rm pyth ls -la /data
# Should show: argos.db (if at least one scan completed)
# Check host
ls -lh docker/data/For comprehensive testing guide, see docker/TEST_DOCKER.md
Pythia uses LangChain 1.0.0 with support for multiple AI providers, giving you flexibility based on your security, privacy, and budget requirements.
Best for: Production use
- ⭐ Quality: Excellent (5/5)
- ⚡ Speed: ~35 seconds
- 💰 Cost: ~$0.25 per scan
- 🔒 Privacy: Standard (data encrypted in transit)
export OPENAI_API_KEY="sk-..."
python -m pip install langchain-openai==1.0.0Best for: Enhanced privacy
- ⭐ Quality: Excellent (5/5)
- ⚡ Speed: ~45 seconds
- 💰 Cost: ~$0.30 per scan
- 🔒 Privacy: Enhanced (strong privacy policy)
export ANTHROPIC_API_KEY="sk-ant-..."
python -m pip install langchain-anthropic==1.0.0Best for: Complete privacy
- ⭐ Quality: Good (3/5)
- 🐢 Speed: ~28 minutes (CPU) or ~75 seconds (GPU)
- 💰 Cost: Free
- 🔐 Privacy: 100% offline (data never leaves your machine)
# Install Ollama: https://ollama.ai
ollama pull llama3.2
python -m pip install "langchain-ollama>=0.3.0,<0.4.0"Automatic Sanitization
Before sending data to AI providers, Pythia automatically removes:
- ✅ Database credentials from error messages
- ✅ SQL query content
- ✅ Session tokens and cookies
- ✅ Internal IP addresses
- ✅ Database schema details
Opt-In Only
- AI analysis requires explicit
--use-aiflag - Aggressive scanning requires verified consent token
- You control which provider sees your data
For Maximum Privacy
Use Ollama locally. While slower and less accurate, your scan data never leaves your machine.
Current Method (v0.1.0): Edit config/default.yaml
ai:
provider: "ollama" # Changed from "openai"
model: "llama3.2" # Ollama model
ollama:
base_url: "http://localhost:11434"Coming in v0.3.0: Interactive configuration menu
# Future feature
python -m pyth --show-options
python -m pyth --set ai.provider=anthropic
python -m pyth --save-profile privacy-modeFor complete AI integration guide, see docs/AI_INTEGRATION.md
~/.pythia/
├── reports/
│ ├── pythia_sqli_report_localhost_20251103_201726.json
│ └── pythia_sqli_report_localhost_20251103_201726.html
└── (shared with Argos ecosystem)
~/.argos/
├── argos.db # Shared database
└── logs/
└── pythia.log # Scan logs
PYTHIA-SQL-001: Error-Based SQL Injection
PYTHIA-SQL-010: Boolean Blind SQL Injection
PYTHIA-SQL-020: Time-Based Blind SQL Injection
PYTHIA-SQL-030: UNION-Based SQL Injection
- CRITICAL (9.0-10.0): Error-based, time-based, UNION-based with confirmed exploitation
- HIGH (7.0-8.9): Boolean-blind with high confidence
- MEDIUM (4.0-6.9): Boolean-blind with medium confidence
- LOW (0.1-3.9): Potential SQLi with inconclusive evidence
| Method | Confidence | Evidence |
|---|---|---|
| Error-Based | High | SQL error message in HTTP response |
| Boolean-Blind | High | Consistent TRUE/FALSE response differences |
| Time-Based | High | Response delay ≥2.5s with SLEEP payload |
| UNION-Based | High | Marker string in response, columns counted |
pythia-sql-clairvoyance/
│
├── pyth/ # Main application package
│ ├── checks/ # Detection modules
│ │ ├── __init__.py
│ │ ├── crawler.py # Web crawler
│ │ ├── error_based.py # Error-based detection
│ │ ├── boolean_blind.py # Boolean-blind detection
│ │ ├── time_based.py # Time-based detection
│ │ ├── union_based.py # UNION-based detection
│ │ └── forms.py # Form testing
│ │
│ ├── core/ # Core infrastructure
│ │ ├── __init__.py
│ │ ├── ai.py # AI integration (LangChain)
│ │ ├── config.py # Configuration management
│ │ ├── consent.py # Consent token system
│ │ ├── db.py # SQLite database (shared)
│ │ ├── http_client.py # Rate-limited HTTP client
│ │ ├── logging.py # Structured logging
│ │ └── report.py # Report generation
│ │
│ ├── __init__.py # Package metadata
│ ├── __main__.py # Entry point
│ ├── cli.py # CLI argument parser
│ └── scanner.py # Main scan orchestrator
│
├── config/ # Configuration files
│ ├── default.yaml # Default settings
│ └── prompts/ # AI prompt templates
│ ├── technical.txt # Technical remediation
│ └── non_technical.txt # Executive summary
│
├── db/
│ └── migrate.sql # Shared database schema
│
├── docker/ # Docker deployment
│ ├── lab/ # Vulnerable test labs
│ └── deploy.sh # Script deploy
│
├── docs/ # Documentation
│ ├── AI_INTEGRATION.md # AI setup guide
│ ├── CONSENT.md # Consent system
│ ├── DATABASE_GUIDE.md # Database reference
│ ├── ETHICS.md # Ethical guidelines
│ ├── REPORT_FORMAT.md # Format
│ ├── ROADMAP.md # Development roadmap
│ └── TESTING_GUIDE.md # Testing practices
│
├── templates/
│ └── report.html.j2 # HTML report template
│
├── CHANGELOG.md # Version history
├── LICENSE # MIT License
├── README.md # This file
├── requirements.txt # Python dependencies
└── setup.py # Package installer
Status: 🎉 Released
- ✅ 4 detection methods (error, boolean-blind, time-based, UNION)
- ✅ AI-powered remediation guides (OpenAI, Anthropic, Ollama)
- ✅ Consent token system (HTTP + DNS verification)
- ✅ Professional reporting (JSON + HTML with AI analysis)
- ✅ SQLite persistence (shared with Argos ecosystem)
- ✅ Docker support with vulnerable labs (PHP & Flask)
- ✅ DBMS fingerprinting (MySQL, PostgreSQL, MSSQL, Oracle, SQLite)
- ✅ Validated with production-level testing
Focus: Detection accuracy, DBMS-specific payloads, advanced techniques
- 🔜 DBMS Fingerprinting & Adaptive Payloads: Automatic database detection with optimized payloads
- 🔜 Enhanced Crawler: JavaScript link extraction, API endpoint discovery, sitemap parsing
- 🔜 Aggressive Mode Enhancement: 50+ payloads per type, WAF bypass techniques
- 🔜 AI Cost Tracking: Budget limits, token usage monitoring
- 🔜 AI Streaming: Real-time progress for analyses
- 🔜 Enhanced HTML Reports: Payload visualization, code examples, better UX
Planned improvements:
- IMPROV-002: HTML report enrichment
- IMPROV-003: DBMS-specific payload adaptation
- IMPROV-004: Aggressive mode differentiation
- IMPROV-005: AI cost tracking
- IMPROV-006: AI streaming responses
- IMPROV-009: Enhanced crawler capabilities
Focus: Usability, automation, interactive AI
- 🔜 Interactive Config Management: Metasploit-style interface
- 🔜 Database CLI: No SQL required
- 🔜 Multi-Site Scanning: Batch processing
- 🔜 AI Chat Interface: Conversational SQL injection analysis
- 🔜 CI/CD Integration: GitHub Actions, Jenkins templates
- 🔜 REST API Server: FastAPI-based automation
Planned improvements:
- IMPROV-009: Interactive configuration
- IMPROV-011: Database CLI management
Focus: ML, automation, advanced exploitation
- 🔜 Automated Exploitation: SQLMap-style data extraction
- 🔜 ML-Based Detection: Anomaly detection, false positive reduction
- 🔜 WAF Bypass Automation: Intelligent evasion techniques
- 🔜 Advanced AI Agents: Autonomous exploit discovery
Commercial product for enterprises
IN PROCESS
For detailed feature descriptions, see ROADMAP.md
Only scan systems you own or have explicit written permission to test.
Pythia implements technical controls to prevent misuse:
| Mode | Tests | Consent Required | Rate Limit |
|---|---|---|---|
| Safe | Error, Boolean-blind | ❌ No | 2 req/s |
| Aggressive | + Time-based, UNION | ✅ Yes | 40 req/s |
| AI Analysis | Remediation guide | ✅ Yes | N/A |
Unauthorized access to computer systems is illegal in most jurisdictions:
- 🇺🇸 USA: Computer Fraud and Abuse Act (CFAA)
- 🇬🇧 UK: Computer Misuse Act 1990
- 🇪🇺 EU: Directive 2013/40/EU
- 🌍 International: Various cybercrime laws
- ✅ Get written authorization before scanning
- ✅ Define scope clearly (which endpoints/parameters)
- ✅ Document everything (consent, findings, remediation)
- ✅ Use safe mode first to establish baseline
- ✅ Report findings responsibly (coordinated disclosure)
- ❌ Never exploit vulnerabilities without explicit permission
- ❌ Never exfiltrate data (even in test environments)
For complete ethical guidelines, see docs/ETHICS.md
We welcome contributions! Whether it's:
- 🐛 Bug reports
- 💡 Feature requests
- 📝 Documentation improvements
- 🔧 Code contributions
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Write/update tests (when applicable)
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Clone your fork
git clone https://github.com/YOUR-USERNAME/pythia-sql-clairvoyance.git
cd pythia-sql-clairvoyance
# Install development dependencies
python -m pip install -r requirements.txt
python -m pip install pytest black flake8 mypy
# Run code formatting
black pyth/
# Run linting
flake8 pyth/
mypy pyth/
# Run tests (when available)
pytest tests/Found a bug? Have a feature request?
Open an issue: https://github.com/rodhnin/pythia-sql-clairvoyance/issues
Please include:
- Pythia version (
python -m pyth --version) - Python version (
python --version) - Operating system
- Steps to reproduce (for bugs)
- Expected vs actual behavior
Comprehensive documentation available in the docs/ directory:
| Document | Description |
|---|---|
| AI_INTEGRATION.md | Complete AI setup guide (all 3 providers) |
| CONSENT.md | Consent token system technical details |
| DATABASE_GUIDE.md | SQLite schema, queries, management |
| ETHICS.md | Legal framework and ethical guidelines |
| ROADMAP.md | Future features and development plans |
| TESTING_GUIDE.md | Safe testing with Docker labs |
- Changelog: CHANGELOG.md
- License: LICENSE
- Example Reports: examples/
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 Rodney Dhavid Jimenez Chacin
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.
IMPORTANT: This tool is for authorized security testing only.
By using Pythia, you acknowledge and agree that:
- ✅ You will only scan systems you own or have explicit written permission to test
- ✅ You will comply with all applicable laws and regulations
- ✅ You understand that unauthorized access is illegal (CFAA, Computer Misuse Act, etc.)
- ✅ The author and contributors assume no liability for misuse
- ✅ This software is provided "as-is" without warranty of any kind
If you discover SQL injection vulnerabilities using Pythia:
- 📧 Contact the application owner privately first
- ⏰ Give reasonable time to fix (typically 90 days)
- 🤝 Coordinate disclosure timeline
- 📝 Document your findings professionally
Don't scan. If you're unsure whether you have permission, you probably don't.
Pythia stands on the shoulders of giants:
- OWASP — SQL Injection guidance, Testing Guide
- SQLMap — Inspiration for detection methods and techniques
- PortSwigger — Web Security Academy resources
- LangChain — AI framework for intelligent analysis
- Anthropic & OpenAI — AI models for vulnerability remediation
- Ollama — Local AI inference for privacy-focused scanning
- Python Community — Amazing libraries and tools
Special thanks to all security researchers who practice and promote ethical hacking.
Rodney Dhavid Jimenez Chacin (rodhnin)
- 🌐 Website: rodhnin.com
- 💻 GitHub: @rodhnin
- 🔗 Project: pythia-sql-clairvoyance
- Discussions: GitHub Discussions
- Issues: GitHub Issues
- Releases: GitHub Releases
Built with ❤️ for ethical hackers and penetration testers worldwide
⭐ Star this repo if you find it useful! ⭐
Report Bug • Request Feature • Documentation
Pythia v0.1.0 — November 2025