hephaestus-server-forger

---

In Action

HTML report — severity breakdown, OWASP mapping, filter bar

Findings table — CVE/CWE badges, expandable evidence, config snippets

---

🎯 What is Hephaestus?

Hephaestus is a production-ready server security auditor that puts ethics first. Built for system administrators, DevOps engineers, and penetration testers, it scans web server configurations (Apache, Nginx, IIS) to identify critical misconfigurations before attackers exploit them.

Why Hephaestus?

• 🔒 Ethical by Design: Consent token system prevents unauthorized scanning
• 🤖 AI-Powered: GPT-4, Claude, or local Ollama for intelligent hardening guides
• 📊 Professional Reports: Beautiful HTML + machine-readable JSON
• 🚀 Fast & Efficient: Concurrent scanning with intelligent rate limiting
• 💾 Persistent Tracking: SQLite database SHARED with Argos suite (~/.argos/argos.db)
• 🐳 Docker Ready: Containerized scanning + vulnerable test labs (Apache & Nginx)
• 🎯 Zero False Positives: Extensively tested with 55+ validation tests

What It Scans

Check Category	Details
Server Information	Apache/Nginx/IIS version disclosure via headers & error pages
Sensitive Files	.env, .git, phpinfo.php, server-status, backups, config files (70+ paths)
HTTP Methods	Unsafe methods (PUT, DELETE, TRACE, OPTIONS)
Security Headers	HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
TLS/SSL Configuration	Deep analysis: cipher suites, protocol versions, certificate validity, CVE correlation
Directory Listing	Apache/Nginx autoindex enabled on sensitive directories
CORS Detection	Wildcard, null-origin, reflection probes (COR-001 to COR-006)
Robots.txt	Disallowed path analysis, live accessibility probes in aggressive mode
WAF Detection	13 signatures including Cloudflare, Sucuri, ModSecurity, AWS WAF, Imperva
API Discovery	Swagger/OpenAPI spec exposure, GraphQL introspection, unauthenticated endpoints
Cookie Security	Per-cookie HttpOnly/Secure/SameSite analysis across authenticated paths
phpinfo() Analysis	9 dangerous PHP settings: display_errors, allow_url_include, open_basedir, and more
Config File Parser	Offline analysis of httpd.conf / nginx.conf for misconfigurations
Port Scanner	37 common ports with banner grabbing and CVE enrichment

---

✨ Features

🛡️ Core Security Auditing

# One command, comprehensive server analysis
python -m heph --target https://example.com --html

• Multi-Server Support: Apache, Nginx, IIS detection and hardening
• Concurrent Scanning: Thread pool + rate limiting for fast, respectful scans
• Evidence Collection: HTTP responses, headers, file contents preserved
• Graceful Error Handling: Timeouts, DNS failures, connection refused handled robustly

🤖 AI-Powered Hardening Guides

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: Apache/Nginx config snippets, CLI commands, step-by-step hardening
• Executive: Plain-language risk assessment for stakeholders and management

📊 Professional Reporting

JSON Reports (Machine-Readable)

{
  "tool": "hephaestus",
  "version": "0.2.0",
  "target": "https://example.com",
  "mode": "safe",
  "summary": {
    "critical": 3,
    "high": 2,
    "medium": 5,
    "low": 3,
    "info": 0
  },
  "findings": [...],
  "diff": {...}
}

HTML Reports (Human-Friendly)

• 🎨 Forge theme with orange/red gradients (⚒️ blacksmith aesthetic)
• 🏷️ Color-coded severity badges
• 📝 Expandable evidence sections
• 🤖 AI hardening guides beautifully formatted
• 📱 Mobile-responsive design

🔐 Consent Token System

Aggressive scanning and AI analysis require proof of ownership:

# 1. Generate token
python -m heph --gen-consent example.com

# 2. Place token on your server
echo "verify-abc123..." > .well-known/verify-abc123.txt

# 3. Verify ownership
python -m heph --verify-consent http --domain example.com --token verify-abc123

# 4. Now you can use aggressive mode
python -m heph --target https://example.com --aggressive --use-ai

💾 Database Persistence