Categoría de Verificación	Detalles
Información del Servidor	Divulgación de versión de Apache/Nginx/IIS a través de cabeceras y páginas de error
Archivos Sensibles	.env, .git, phpinfo.php, server-status, copias de seguridad, archivos de configuración (más de 70 rutas)
Métodos HTTP	Métodos no seguros (PUT, DELETE, TRACE, OPTIONS)
Cabeceras de Seguridad	HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
Configuración TLS/SSL	Análisis profundo: suites de cifrado, versiones de protocolo, validez del certificado, correlación CVE
Listado de Directorios	Autoíndice de Apache/Nginx habilitado en directorios sensibles
Detección CORS	Pruebas de comodín, origen nulo, reflexión (COR-001 a COR-006)
Robots.txt	Análisis de rutas deshabilitadas, pruebas de accesibilidad en vivo en modo agresivo
Detección WAF	13 firmas que incluyen Cloudflare, Sucuri, ModSecurity, AWS WAF, Imperva
Descubrimiento de API	Exposición de especificaciones Swagger/OpenAPI, introspección GraphQL, endpoints no autenticados
Seguridad de Cookies	Análisis por cookie HttpOnly/Secure/SameSite en rutas autenticadas
Análisis de phpinfo()	9 configuraciones peligrosas de PHP: display_errors, allow_url_include, open_basedir y más
Analizador de Archivos de Configuración	Análisis offline de httpd.conf / nginx.conf para configuraciones incorrectas
Escáner de Puertos	37 puertos comunes con captura de banner y enriquecimiento CVE

- **Soporte para múltiples servidores**: detección y endurecimiento de Apache, Nginx, IIS
- **Escaneo concurrente**: Pool de hilos + limitación de velocidad para escaneos rápidos y respetuosos
- **Recolección de evidencia**: Respuestas HTTP, encabezados, contenidos de archivos preservados
- **Manejo elegante de errores**: Tiempos de espera, fallos de DNS, conexión rechazada manejados de manera robusta

### 🤖 Guías de endurecimiento impulsadas por IA

Elige tu proveedor de IA según tus necesidades:

| Proveedor         | Mejor para              | Velocidad        | Costo              | Privacidad          |
| ----------------- | ----------------------- | ---------------- | ------------------ | ------------------- |
| **OpenAI GPT-4**  | Calidad de producción   | ⚡ Rápido (35s)  | 💰 $0.25/escaneo   | 🔒 Estándar         |
| **Anthropic Claude** | Centrado en privacidad | ⚡ Rápido (45s)  | 💰 $0.30/escaneo   | 🔒 Mejorada         |
| **Ollama (Local)**   | Privacidad completa     | 🐢 Lento (28min) | 💰 Gratuito        | 🔐 100% Fuera de línea |

**Dos modos de análisis:**

- **Técnico**: Fragmentos de configuración de Apache/Nginx, comandos CLI, endurecimiento paso a paso
- **Ejecutivo**: Evaluación de riesgos en lenguaje sencillo para partes interesadas y dirección

### 📊 Informes profesionales

**Informes JSON** (Legibles por máquina)```json
{
  "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": {...}
}

### 💾 Persistencia de base de datos

Base de datos SQLite **COMPARTIDA con la suite Argos** (`~/.argos/argos.db`):

- **Historial de escaneo**: Fecha, duración, recuento de hallazgos, desglose de gravedad
- **Repositorio de hallazgos**: Base de datos de vulnerabilidades buscable (más de 1159 hallazgos almacenados)
- **Dominios verificados**: Seguimiento de tokens de consentimiento con vencimiento
- **Integración entre herramientas**: Funciona sin problemas con Argus, Pythia y herramientas futuras```bash
# Query recent scans
sqlite3 ~/.argos/argos.db "SELECT * FROM scans WHERE tool='hephaestus' ORDER BY scan_id DESC LIMIT 10"

# Find critical issues
sqlite3 ~/.argos/argos.db "SELECT * FROM findings WHERE severity='critical' AND tool='hephaestus'"

Métrica	Resultado
Suite de pruebas	55/55 pruebas exitosas (13 fases)
Detección Apache	42 hallazgos en las 13 fases de escaneo
Detección Nginx	25 hallazgos en las 13 fases de escaneo
Precisión	100% (cero falsos positivos)
Exhaustividad	100% (cero falsos negativos)
Puntuación F1	100% (equilibrio perfecto)
Duración promedio de escaneo	30-35 segundos
Operaciones de base de datos	80 escaneos rastreados, 1159+ hallazgos almacenados

**2. (Opcional) Instalar `venv` si no está ya disponible**```bash
# Debian/Ubuntu
sudo apt update && sudo apt install -y python3-venv

# Fedora/RHEL
sudo dnf install python3-virtualenv

# macOS (via Homebrew)
brew install [email protected]

### Tu primer escaneo```bash
# Basic scan (safe mode, no consent required)
python -m heph --target https://example.com

# With HTML report
python -m heph --target https://example.com --html

# With AI hardening guide (requires consent)
python -m heph --target https://example.com --use-ai --html

### Escaneo Avanzado```bash
# Control scan speed (1-20 req/s)
python -m heph --target https://example.com --rate 10

# Control concurrency (1-20 threads)
python -m heph --target https://example.com --threads 8

# Custom timeout (useful for slow servers)
python -m heph --target https://example.com --timeout 60

# Custom output directory
python -m heph --target https://example.com --report-dir ./my-reports

# Custom User-Agent
python -m heph --target https://example.com --user-agent "MyBot/1.0"

# Disable SSL verification (testing only)
python -m heph --target https://self-signed.badssl.com --no-verify-ssl

### Modo Agresivo (Requiere Consentimiento)```bash
# Step 1: Generate consent token
python -m heph --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 heph --verify-consent http \
  --domain example.com \
  --token verify-a3f9b2c1d8e4

# Step 4: Run aggressive scan (deeper checks, higher rate limit)
python -m heph --target https://example.com --aggressive

#### Anthropic Claude

**Mejor para: Privacidad mejorada**

- ⭐ Calidad: Excelente (5/5)
- ⚡ Velocidad: ~45 segundos
- 💰 Costo: ~$0.30 por escaneo
- 🔒 Privacidad: Mejorada (enfoque de privacidad primero de Anthropic)```bash
export ANTHROPIC_API_KEY="sk-ant-..."
python -m pip install langchain-anthropic==1.0.0

### Privacidad y Seguridad

**Sanitización automática**

Antes de enviar a proveedores de IA, Hephaestus elimina automáticamente:

- ✅ Tokens de consentimiento
- ✅ Claves API y credenciales
- ✅ Claves privadas y certificados
- ✅ Direcciones IP internas
- ✅ Credenciales de base de datos

**Solo con adhesión explícita**

- El análisis con IA requiere la bandera explícita `--use-ai`
- El escaneo agresivo requiere un token de consentimiento verificado
- Tú controlas qué proveedor ve tus datos

**Para máxima privacidad**: usa Ollama localmente.

---

## 🧪 Laboratorios de pruebas seguros

**⚠️ NUNCA escanee sitios de producción sin permiso por escrito.**

Use nuestros laboratorios Docker para practicar de forma segura:

### Configurar el entorno de prueba

### Opción 1: Script interactivo (Recomendado)```bash
# Run the interactive deployment script
cd docker && ./deploy.sh

**Escáner de Producción:**```bash
# Start Hephaestus scanner service
docker compose -f docker/compose.yml up -d

# Run a scan
docker compose -f docker/compose.yml exec hephaestus heph --target https://example.com

# View reports
ls -lh docker/reports/

### Escanea los Laboratorios```bash
# Scan Apache lab (from host)
python -m heph --target http://localhost:8080 --html

# Scan Nginx lab (from host)
python -m heph --target http://localhost:8081 --html

# AI-powered analysis (requires OPENAI_API_KEY)
python -m heph --target http://localhost:8080 --use-ai --html

# OR from inside production container (using container name)
docker compose -f docker/compose.yml exec hephaestus python -m heph --target http://hephaestus-vulnerable-apache --html

**Eliminar todo (ADVERTENCIA: elimina datos e informes):**```bash
# Using script (with confirmation)
cd docker && ./deploy.sh  # Choose option 5 (Remove All)

# OR manually
docker compose -f docker/compose.yml down -v
docker compose -f docker/compose.testing.yml down -v
rm -rf docker/data docker/reports

**Laboratorio de pruebas (Servidores vulnerables):**```bash
# Start Apache + Nginx vulnerable servers
docker compose -f docker/compose.testing.yml up -d

# Scan from host
python -m heph --target http://localhost:8080 --html

# Stop lab
docker compose -f docker/compose.testing.yml down

**Con análisis de IA:**```bash
docker run --rm \
  -v $(pwd)/docker/reports:/reports \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  hephaestus:0.2.0 \
  --target https://example.com \
  --use-ai \
  --ai-tone both \
  --html

---

## 📊 Entendiendo los Informes

### Estructura del Informe```
~/.hephaestus/
├── reports/
│   ├── hephaestus_report_example_20251021_143022.json
│   └── hephaestus_report_example_20251021_143022.html
└── (shared with Argos)
    ~/.argos/
    ├── argos.db          # Shared database
    └── logs/
        └── hephaestus.log

### Mapeo de Severidad

- **CRITICAL**: .env expuesto, .git accesible, phpinfo, server-status, volcados SQL
- **HIGH**: Versión del servidor revelada, TLS débil, TLS ausente, métodos HTTP no seguros
- **MEDIUM**: Faltan encabezados importantes (HSTS, CSP, X-Frame-Options), listado de directorios, revelación de páginas de error
- **LOW**: Encabezados menores (X-Content-Type-Options, Referrer-Policy, Permissions-Policy)
- **INFO**: Hallazgos informativos (servidor detectado, TLS 1.2 OK)

---

## 📁 Estructura del Proyecto```
hephaestus-server-forger/
│
├── heph/                       # Main application package
│   ├── checks/                 # Security check modules (13 phases)
│   │   ├── __init__.py
│   │   ├── api_discovery.py    # Phase 11: Swagger/OpenAPI/GraphQL exposure
│   │   ├── config.py           # Phase 5: Directory listing detection
│   │   ├── config_file.py      # Phase 14: Offline httpd.conf/nginx.conf parser
│   │   ├── cookies.py          # Phase 12: HttpOnly/Secure/SameSite analysis
│   │   ├── cors.py             # Phase 8: CORS wildcard & reflection probes
│   │   ├── files.py            # Phase 2: 70+ sensitive file paths
│   │   ├── headers.py          # Phase 4: Security headers analysis
│   │   ├── http_methods.py     # Phase 3: Unsafe HTTP methods (PUT/DELETE/TRACE)
│   │   ├── phpinfo.py          # Phase 13: phpinfo() dangerous settings
│   │   ├── ports.py            # Phase 7: 37-port scanner with banner grabbing
│   │   ├── robots.py           # Phase 9: robots.txt disallowed path analysis
│   │   ├── server_info.py      # Phase 1: Apache/Nginx/IIS fingerprinting
│   │   ├── tls.py              # Phase 6: Deep TLS/SSL + CVE correlation
│   │   └── waf.py              # Phase 10: 13 WAF signatures detection
│   │
│   ├── core/                   # Core infrastructure
│   │   ├── __init__.py
│   │   ├── ai.py               # LangChain AI (GPT-4/Claude/Ollama) + cost tracking
│   │   ├── config.py           # Configuration loader
│   │   ├── consent.py          # Consent token system (HTTP + DNS)
│   │   ├── cve_lookup.py       # NVD CVE API integration
│   │   ├── db.py               # SQLite — shared with Argos suite (~/.argos/argos.db)
│   │   ├── diff.py             # Scan diff engine (--diff last / --diff <id>)
│   │   ├── http_client.py      # Token-bucket rate-limited HTTP client
│   │   ├── logging.py          # Structured logging
│   │   ├── owasp.py            # HEPH-* code → OWASP Top 10 2021 mapper
│   │   └── report.py           # JSON + HTML report generation
│   │
│   ├── __init__.py             # Package metadata
│   ├── __main__.py             # Entry point
│   ├── cli.py                  # CLI (30+ flags incl. --use-ai, --diff, --config-file)
│   └── scanner.py              # Orchestrator — 13 parallel phases
│
├── assets/
│   └── ascii.txt               # Hephaestus braille ASCII art
│
├── config/                     # Configuration files
│   ├── defaults.yaml           # Default settings
│   └── prompts/                # AI prompt templates
│       ├── technical.txt       # Technical hardening prompt
│       └── non_technical.txt   # Executive summary prompt
│
├── db/
│   └── migrate.sql             # Shared database schema (Argos suite)
│
├── docker/                     # Docker deployment
│   ├── vulnerable-apache/      # Vulnerable Apache lab (port 8080/8443)
│   │   └── docker-entrypoint.sh
│   ├── vulnerable-nginx/       # Vulnerable Nginx lab (port 8081/8444)
│   │   └── docker-entrypoint.sh
│   ├── compose.yml             # Production stack
│   ├── compose.testing.yml     # Vulnerable lab stack
│   ├── deploy.sh               # Interactive deployment script
│   └── Dockerfile              # Production image
│
├── docs/                       # Documentation
│   ├── media/                  # README visual assets
│   │   ├── hephaestus-banner.webp  # Banner 1280×400
│   │   ├── hephaestus-hero.webp    # Hero 1600×640
│   │   ├── console.webp            # Terminal scan output
│   │   ├── report_html.webp        # HTML report header
│   │   └── report_findings.webp    # Findings table with CVE badges
│   ├── AI_INTEGRATION.md       # AI providers setup guide
│   ├── CONSENT.md              # Consent system details
│   ├── DATABASE_GUIDE.md       # Shared database reference
│   ├── ETHICS.md               # Ethical use guidelines
│   ├── REPORT_FORMAT.md        # JSON/HTML report specification
│   ├── ROADMAP.md              # v0.3.0 tickets and priorities
│   └── TESTING_GUIDE.md        # Safe testing practices
│
├── schema/
│   └── report.schema.json      # JSON report schema (OWASP + CVE fields)
│
├── scripts/
│   └── cli-examples.md         # CLI usage examples
│
├── templates/
│   └── report.html.j2          # HTML report template — forge theme
│
├── CHANGELOG.md                # Version history
├── CODE_OF_CONDUCT.md          # Community guidelines
├── CONTRIBUTING.md             # Contribution guide
├── LICENSE                     # MIT License
├── README.md                   # This file
├── requirements.txt            # Python dependencies
└── setup.py                    # Package installer

### Reporte de Problemas

¿Encontraste un error? ¿Tienes una solicitud de funcionalidad?

**Abre un issue**: https://github.com/rodhnin/hephaestus-server-forger/issues

Por favor incluye:

- Versión de Hephaestus (`python -m heph --version`)
- Versión de Python (`python --version`)
- Sistema operativo
- Pasos para reproducir (para errores)
- Comportamiento esperado vs real

---

## 📚 Documentación

Documentación completa disponible en el directorio `docs/`:

| Documento                                    | Descripción                               |
| ------------------------------------------- | ----------------------------------------- |
| [AI_INTEGRATION.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/AI_INTEGRATION.md) | Guía completa de configuración de IA (los 3 proveedores) |
| [CONSENT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/CONSENT.md)               | Detalles técnicos del sistema de tokens de consentimiento |
| [DATABASE_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/DATABASE_GUIDE.md) | Esquema SQLite, consultas, gestión        |
| [ETHICS.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/ETHICS.md)                 | Marco legal y pautas éticas               |
| [REPORT_FORMAT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/REPORT_FORMAT.md)   | Especificaciones de esquema JSON y HTML   |
| [TESTING_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/TESTING_GUIDE.md)   | Pruebas seguras con laboratorios Docker   |
| [ROADMAP.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/docs/ROADMAP.md)               | Funcionalidades futuras y planes de desarrollo |

### Enlaces Rápidos

- **Registro de cambios**: [CHANGELOG.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/CHANGELOG.md)
- **Licencia**: [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/main/LICENSE)
- **Ejemplos CLI**: [scripts/cli-examples.md](https://github.com/rodhnin/hephaestus-server-forger/blob/main/scripts/cli-examples.md)

---

## ⚖️ Licencia

Este proyecto está licenciado bajo la **Licencia MIT** - consulte el archivo [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/main/LICENSE) para más detalles.```
MIT License

Copyright (c) 2026 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.

Modo	Verificaciones	Consentimiento requerido	Límite de tasa
Seguro	No intrusivo	❌ No	5 solic/s
Agresivo	Sondeo profundo	✅ Sí	12 solic/s
Análisis de IA	Guía de endurecimiento	✅ Sí	N/A

hephaestus-server-forger

Más Populares

En Acción

🎯 ¿Qué es Hephaestus?

¿Por qué Hephaestus?

Qué Escanea

✨ Características

🛡️ Auditoría de Seguridad Principal```bash

One command, comprehensive server analysis

🔐 Sistema de Token de Consentimiento

1. Generate token

2. Place token on your server

3. Verify ownership

4. Now you can use aggressive mode

✅ Validación y Pruebas

Resumen de Validación (Mayo 2026)

🚀 Inicio Rápido

Requisitos previos

Instalación

You should see (.venv) in your terminal prompt

Output: heph 0.2.0

🐳 Inicio rápido con Docker

Selecciona la opción 3 para pruebas (Ambos)

📘 Guía de uso

Escaneo básico```bash

Safe mode (default) - Non-intrusive checks

Generate HTML report

Increase verbosity for debugging

Quiet mode (errors only)

Guías de endurecimiento impulsadas por IA

Technical hardening guide (for sysadmins)

Executive risk summary (for management)

Both analyses in one report

Stream AI output token-by-token

Compare two AI providers in parallel

Agent mode with live NVD CVE lookup

Set a cost budget cap (USD)

🤖 Análisis impulsado por IA

Proveedores compatibles

OpenAI GPT-4 Turbo

Ollama (Modelos Locales)

Install Ollama: https://ollama.ai

Opción 2: Docker Compose Manual

Start vulnerable servers (Apache + Nginx)

Wait for initialization (~15 seconds)

Verify services

Start both production and testing

Scan the testing labs from host

Resultados Esperados

Limpieza

Using script

OR manually

🐳 Despliegue con Docker

Opción 1: Docker Compose (Recomendado)

Start long-running scanner service

Run scans

View reports

Stop service

Use the interactive menu

Start testing lab first

Scan from container (join the testing lab network)

ID de hallazgos (Patrón, más de 70 en total)```

🗺️ Roadmap

v0.1.0 — Lanzamiento inicial ✅ (Enero 2026)

v0.2.0 — Detección mejorada ✅ (Mayo 2026)

v0.3.0 — Características empresariales (Q3 2026)

v0.4.0 — Inteligencia y Automatización (Q4 2026)

Pro Track (Q1 2027)

🔒 Ética y Legal

La Regla de Oro

Aplicación del consentimiento

Marco Legal

Mejores Prácticas

🤝 Contribuciones

Cómo contribuir

Configuración de desarrollo```bash

Clone your fork

Install development dependencies

Run code formatting

Run linting