Skip to content

v0.2.0 — 13 Scan Phases, Deep TLS/SSL & CVE Correlation

Latest
Latest

Choose a tag to compare

View all tags
@rodhnin rodhnin released this 01 May 16:27
v0.2.0
158c199
hephaestus-hero

Hephaestus v0.2.0 is a major feature release. Three months after v0.1.0, this version expands the scanner from 5 to 13 parallel scan phases, adds real-time CVE correlation via NVD API v2, centralized OWASP Top 10 2021 mapping, offline configuration file analysis, scan diff reports, and a significantly enhanced AI subsystem with cost tracking, streaming, tool-calling agents, and multi-provider comparison.

What's New

13 Parallel Scan Phases (up from 5)

Eight new phases run in parallel alongside the original five:

Phase Module Summary
6 tls.py (enhanced) SSLyze cipher suite analysis, SSL Labs-style A+/F grading, POODLE / DROWN / BEAST / CRIME / Heartbleed / ROBOT / FREAK / Logjam detection
7 ports.py 37-port scanner with banner grabbing, service fingerprinting, and CVE enrichment for detected versions
8 cors.py Wildcard origins, credentialed requests, null-origin probes — 6 finding codes (COR-001 to COR-006)
9 robots.py Parses robots.txt, cross-references disallowed paths against live accessibility, user-agent-aware — 3 finding codes (ROB-001 to ROB-003)
10 waf.py 13 WAF signatures (Cloudflare, AWS WAF, ModSecurity, Imperva, Akamai, F5 BIG-IP, Sucuri, and more) via header fingerprinting and behavioral probing
11 api_discovery.py Swagger/OpenAPI spec exposure, GraphQL introspection, unauthenticated API root access — 5 finding codes (API-001 to API-005)
12 cookies.py Secure / HttpOnly / SameSite flags across 7 authenticated paths, context-aware Secure check for HTTPS-only targets — 5 finding codes (COO-001 to COO-005)
13 phpinfo.py Parses live phpinfo() output for 9 dangerous PHP settings — expose_php, display_errors, allow_url_include, open_basedir, disable_functions, session cookie flags — codes PHP-001 to PHP-009

Deep TLS/SSL Analysis (IMPROV-002)

  • Full cipher suite enumeration via SSLyze integration
  • SSL Labs-style grading: A+ / A / B / C / D / F per endpoint
  • Protocol detection: TLS 1.3, 1.2, 1.1, 1.0, SSLv3, SSLv2
  • Certificate validation: expiry, self-signed, hostname mismatch, SHA-1/MD5 signatures
  • Forward secrecy detection (ECDHE/DHE)
  • CVE enrichment per cipher/protocol finding with CVSS scores
  • New finding codes: HEPH-TLS-002 to HEPH-TLS-010

Framework and Module Detection (IMPROV-003)

  • Web framework detection: Laravel, Django, Ruby on Rails, Node.js/Express, ASP.NET, Spring
  • Application server detection: Tomcat, Gunicorn, uWSGI, Phusion Passenger
  • Reverse proxy detection: Cloudflare, AWS CloudFront, Nginx proxy cache
  • Apache module hints from server-info and response headers
  • Zero extra requests in safe mode — detection reuses responses already fetched by Phase 1

Live CVE Lookup

  • heph/core/cve_lookup.py: NVD API v2 as primary source, CIRCL.lu as fallback
  • CPE vendor normalization for common components (nginx → f5, mysql → oracle, etc.)
  • Empty version guard — no false CVE matches when no version is detected
  • Called automatically during server fingerprinting, TLS analysis, and port scanning
  • Each server-version finding carries its applicable CVEs with CVSS score, CWE, and NVD link

OWASP Top 10 2021 Mapping

  • heph/core/owasp.py: all HEPH-* finding codes mapped centrally to A01–A10
  • owasp field (id + name) on every finding in JSON output
  • HTML report: OWASP badge per finding with link to the relevant OWASP Top 10 page

Scan Diff Reports (--diff)

  • --diff last — compare current scan against the most recent prior scan for the same target
  • --diff <scan_id> — reference any specific scan by database ID
  • heph/core/diff.py: categorizes findings as new / fixed / persisting (matched by HEPH-* code)
  • Cross-tool protection: rejects diffs against Argus or other tool scan IDs with a clear error
  • New top-level diff object in the JSON report schema

Config File Parser (--config-file)

Offline analysis of httpd.conf or nginx.conf without any HTTP requests:

# Offline only
python -m heph --config-file /etc/apache2/httpd.conf

# Combined: live scan + offline config
python -m heph --target http://example.com --config-file /etc/nginx/nginx.conf --html

Apache checks (CFG-011 to CFG-024): ServerTokens, ServerSignature, TraceEnable, Options Indexes, expose_php, weak SSLProtocol, weak SSLCipherSuite, AllowOverride All, missing LimitRequestBody, missing security headers via mod_headers.

Nginx checks (CFG-030 to CFG-044): server_tokens on, autoindex on (deduplicated by location block with line numbers), weak ssl_protocols, weak ssl_ciphers (negated parts correctly stripped), missing client_max_body_size, missing security headers via add_header.

Generic (both types): hardcoded credentials detection — passwords, secrets, and API keys in config (HEPH-CFG-050).

Report mode field set to "offline" for standalone config analysis.

Enhanced HTML Report (IMPROV-004)

  • Severity filter bar: All / Critical / High / Medium / Low / Info buttons with live counts
  • CVE and CWE badges: inline pills per finding linking to NVD
  • OWASP Top 10 2021 badges: A01–A10 tag per finding with link to OWASP
  • AI analysis tabs: Standard / Agent / Compare rendered as independent tabs
  • Diff section: New / Fixed / Persisting summary badges at the top of the report
  • Config snippets: ready-to-paste Apache (httpd.conf) and Nginx (nginx.conf) blocks per finding
  • Markdown to HTML conversion: agent analysis and compare results render with proper formatting
  • Self-contained — all CSS and JS inline, no external dependencies

AI Enhancements (IMPROV-006, 007, 008)

Cost Tracking (--ai-budget)

python -m heph --target http://example.com --use-ai --ai-budget 0.10
  • AICostTracker records input/output tokens per call with per-provider pricing
  • Warning at 80% of budget; scan aborts at 100%
  • Costs written to ~/.argos/costs.json with tool: "hephaestus" field
  • Costs stored in ai_costs table in shared ~/.argos/argos.db

Streaming (--ai-stream)

python -m heph --target http://example.com --use-ai --ai-stream
  • Token-by-token output to console during generation — no more waiting 30+ seconds blind

Agent Mode (--ai-agent)

python -m heph --target http://example.com --use-ai --ai-agent
  • LangChain agent with NVD CVE lookup tool
  • Agent makes real NVD API v2 calls during analysis — typically 7 tool calls per scan
  • Agent analysis stored in ai_analysis.agent_analysis and rendered as a dedicated HTML tab

Multi-Provider Comparison (--ai-compare)

python -m heph --target http://example.com --use-ai --ai-compare openai:gpt-4o-mini,anthropic:claude-haiku-3-5
  • Two providers run in parallel; results stored per-provider in JSON
  • Rendered as a tabbed comparison section in the HTML report

Default model changed: gpt-4o-mini-2024-07-18 (replaces gpt-4-turbo-preview — significantly lower cost, equivalent quality for security analysis)

Bug Fixes

  • compute_diff() ran before findings were finalized — diff was always empty; fixed in scanner.py
  • lookup_cves('apache', '') returned results for empty version strings — now guarded
  • Missing OWASP mapping for HEPH-HTTP-008, HEPH-FILE-999, HEPH-FILE-403
  • Nginx ssl_ciphers ALL:!aNULL:!eNULL incorrectly flagged as weak — negated cipher parts now stripped before pattern matching
  • autoindex on reported multiple times (once per location block) — deduplicated into a single finding with all line numbers listed

Testing Results (2026-04-01)

Target Mode Findings Notes
Apache 2.4.54 lab HTTP :8080 safe 42 5 critical · 6 high · 16 medium · 11 low · 1 info · 19 CVEs via NVD
Apache 2.4.54 lab HTTP :8080 aggressive 44 +2 ROB-003 findings (disallowed paths confirmed blocked)
Apache 2.4.54 lab HTTPS :8443 safe 45 TLS-004 self-signed + TLS-011/012 weak protocols + grade B
Nginx 1.24 lab HTTP :8081 safe 25 2 critical · 3 high · 11 medium · 9 low
Nginx 1.24 lab HTTP :8081 aggressive 29 +ROB-002 x3 (accessible: /api/, /backup/, /.git/) + ROB-003 x1
nginx.conf offline config-file 9 server_tokens on · autoindex 4 locations · weak TLS 1.0/1.1 · missing headers
False positive tests — 0 X-Security-Guard not flagged as WAF · disabled GraphQL introspection not flagged · OPTIONS-only CORS not flagged

Migration from v0.1.0

Fully backward compatible. No database migration required.

The only change to note: the default AI model is now gpt-4o-mini-2024-07-18. If you rely on the previous model, pass --ai-model gpt-4-turbo-preview or set it in config/defaults.yaml.

Quick Start

git clone https://github.com/rodhnin/hephaestus-server-forger.git
cd hephaestus-server-forger
pip install -r requirements.txt

# Safe scan
python -m heph --target http://your-server.com --html -v

# Scan with diff
python -m heph --target http://your-server.com --diff last --html

# Offline config analysis
python -m heph --config-file /etc/apache2/httpd.conf

# AI scan with budget cap
python -m heph --target http://your-server.com --use-ai --ai-budget 0.05 --ai-stream --html

Docker test lab:

docker compose -f docker/compose.testing.yml up -d
python -m heph --target http://localhost:8080 --html -v   # Apache 2.4.54
python -m heph --target http://localhost:8081 --html -v   # Nginx 1.24

Documentation

Assets 2
Loading