Em Ação

_{Varredura ao vivo · Apache 2.4.54 · 11 descobertas · 44.17s · varredura #518 · modo seguro}

Relatório HTML — detalhamento de gravidade, mapeamento OWASP, barra de filtro

Tabela de descobertas — badges CVE/CWE, evidências expansíveis, trechos de configuração

🎯 O que é o Hephaestus?

Hephaestus é um auditor de segurança de servidores pronto para produção que coloca a ética em primeiro lugar. Construído para administradores de sistemas, engenheiros DevOps e testadores de penetração, ele varre configurações de servidores web (Apache, Nginx, IIS) para identificar configurações incorretas críticas antes que atacantes as explorem.

Por que Hephaestus?

• 🔒 Ético por Design: Sistema de token de consentimento impede varreduras não autorizadas
• 🤖 Impulsionado por IA: GPT-4, Claude ou Ollama local para guias de fortalecimento inteligentes
• 📊 Relatórios Profissionais: HTML bonito + JSON legível por máquina
• 🚀 Rápido e Eficiente: Varredura concorrente com limitação de taxa inteligente
• 💾 Rastreamento Persistente: Banco de dados SQLite COMPARTILHADO com a suíte Argos (~/.argos/argos.db)
• 🐳 Pronto para Docker: Varredura containerizada + laboratórios de teste vulneráveis (Apache e Nginx)
• 🎯 Zero Falsos Positivos: Extensivamente testado com 55+ testes de validação

O que ele varre

✨ Funcionalidades

🛡️ Auditoria Central de Segurança```bash

One command, comprehensive server analysis

python -m heph --target https://example.com --html

- **Suporte para Múltiplos Servidores**: Detecção e fortalecimento de Apache, Nginx e IIS
- **Varredura Concorrente**: Pool de threads + limitação de taxa para varreduras rápidas e respeitosas
- **Coleta de Evidências**: Respostas HTTP, cabeçalhos, conteúdos de arquivos preservados
- **Tratamento Elegante de Erros**: Timeouts, falhas de DNS, conexão recusada tratados de forma robusta

### 🤖 Guias de Fortalecimento com IA

Escolha seu provedor de IA de acordo com suas necessidades:

| Provedor         | Melhor Para          | Velocidade       | Custo           | Privacidade      |
| ---------------- | -------------------- | ---------------- | --------------- | ---------------- |
| **OpenAI GPT-4**   | Qualidade de produção | ⚡ Rápido (35s) | 💰 $0,25/varredura | 🔒 Padrão      |
| **Anthropic Claude** | Focado em privacidade | ⚡ Rápido (45s) | 💰 $0,30/varredura | 🔒 Reforçada   |
| **Ollama (Local)**  | Privacidade completa  | 🐢 Lento (28min) | 💰 Gratuito    | 🔐 100% Offline |

**Dois Modos de Análise:**

- **Técnico**: Trechos de configuração do Apache/Nginx, comandos CLI, fortalecimento passo a passo
- **Executivo**: Avaliação de risco em linguagem simples para partes interessadas e gerência

### 📊 Relatórios Profissionais

**Relatórios JSON** (Legíveis 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": {...}
}

Relatórios HTML (Amigável)

• 🎨 Tema Forge com gradientes laranja/vermelho (⚒️ estética de ferreiro)
• 🏷️ Distintivos de gravidade codificados por cores
• 📝 Seções de evidência expansíveis
• 🤖 Guias de endurecimento de IA lindamente formatados
• 📱 Design responsivo para dispositivos móveis

🔐 Sistema de Token de Consentimento

Escaneamento agressivo e análise de IA exigem prova de propriedade:```bash

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

### 💾 Persistência do Banco de Dados

Banco de dados SQLite **COMPARTILHADO com a suíte Argos** (`~/.argos/argos.db`):

- **Histórico de Varreduras**: Data, duração, contagem de descobertas, detalhamento de gravidade
- **Repositório de Descobertas**: Banco de dados de vulnerabilidades pesquisável (1159+ descobertas armazenadas)
- **Domínios Verificados**: Rastreamento de token de consentimento com expiração
- **Integração entre Ferramentas**: Funciona perfeitamente com Argus, Pythia e futuras ferramentas```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'"

✅ Validação e Testes

Hephaestus v0.2.0 foi validado empiricamente usando laboratórios vulneráveis controlados baseados em Docker (Apache e Nginx).

Resumo da Validação (Maio de 2026)

Cobertura de Testes (13 fases):

• ✅ Fase 1: CLI básico (códigos de saída, tratamento de erros)
• ✅ Fase 2: Tokens de consentimento (verificação HTTP, modo agressivo)
• ✅ Fase 3: Integração de IA (OpenAI, Anthropic, Ollama)
• ✅ Fase 4: Geração de relatórios (JSON, HTML, análise de IA)
• ✅ Fase 5: Opções avançadas (limitação de taxa, threads, timeouts)
• ✅ Fase 6: Módulos de verificação (70+ códigos de descoberta validados)
• ✅ Fase 7: Registro de logs (texto, JSON, níveis de verbosidade)
• ✅ Fase 8: Banco de dados (esquema, integridade, chaves estrangeiras)
• ✅ Fase 9: Tratamento de erros (casos extremos, permissões)
• ✅ Fase 10: Integração (compatibilidade com o conjunto Argos)
• ✅ Fase 11: Detecção de CORS, Robots.txt, WAF
• ✅ Fase 12: Descoberta de API, segurança de cookies, análise de phpinfo
• ✅ Fase 13: Analisador de arquivos de configuração, relatórios de diff, rastreamento de custos de IA

Principais Descobertas:

• ✅ Todas as vulnerabilidades críticas detectadas (.env, .git, server-status, phpinfo)
• ✅ Todas as versões de servidor identificadas (Apache 2.4.54, Nginx 1.18.0)
• ✅ Todos os cabeçalhos de segurança analisados corretamente (6 cabeçalhos verificados)
• ✅ Todos os problemas de listagem de diretórios identificados
• ✅ Módulos CORS, WAF, API, Cookie, phpinfo totalmente operacionais
• ✅ Relatórios de diff (--diff last) funcionando no histórico de varreduras
• ✅ Tratamento de erros resiliente (timeouts, falhas de DNS, conexão recusada)

Veredito: Hephaestus está pronto para produção para avaliações de segurança de servidores.

🚀 Início Rápido

Pré-requisitos

• Python 3.11+ (3.12 recomendado)
• pip (gerenciador de pacotes Python)
• Docker (opcional, para laboratórios vulneráveis)

Instalação

1. Clone o repositório```bash git clone https://github.com/rodhnin/hephaestus-server-forger.git cd hephaestus-server-forger

**2. (Opcional) Instale o `venv` se ainda não estiver disponível**```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]

3. Criar e ativar ambiente virtual```bash python3 -m venv .venv source .venv/bin/activate

You should see (.venv) in your terminal prompt

**4. Atualizar pip**```bash
python -m pip install --upgrade pip

5. Instalar dependências```bash python -m pip install -r requirements.txt

**6. Configure as chaves de API (se estiver usando IA na nuvem)**```bash
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

7. Verificar instalação```bash python -m heph --version

Output: heph 0.2.0

### Sua Primeira Varredura```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

🐳 Início Rápido com Docker

cd docker && ./deploy.sh

Selecione a opção 3 para teste (Ambos)

docker compose exec hephaestus python -m heph --target http://vulnerable-apache

🎉 Sucesso! Verifique ~/.hephaestus/reports/ para seus relatórios.

📘 Guia de Uso

Varredura Básica```bash

Safe mode (default) - Non-intrusive checks

python -m heph --target https://example.com

Generate HTML report

python -m heph --target https://example.com --html

Increase verbosity for debugging

python -m heph --target https://example.com -vv

Quiet mode (errors only)

python -m heph --target https://example.com -q

### Varredura Avançada```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

Guias de Fortalecimento com IA

Passo 1: Configure seu provedor

Edite config/defaults.yaml:```yaml ai: langchain: provider: "openai" # Options: openai, anthropic, ollama model: "gpt-4o-mini-2024-07-18" temperature: 0.3

**Passo 2: Teste sua configuração**```bash
# Verify AI provider works
python -m heph.core.ai openai

Passo 3: Executar verificação com IA```bash

Technical hardening guide (for sysadmins)

python -m heph --target https://example.com
--use-ai
--ai-tone technical
--html

Executive risk summary (for management)

python -m heph --target https://example.com
--use-ai
--ai-tone non_technical
--html

Both analyses in one report

python -m heph --target https://example.com
--use-ai
--ai-tone both
--html

Stream AI output token-by-token

python -m heph --target https://example.com
--use-ai
--ai-stream
--html

Compare two AI providers in parallel

python -m heph --target https://example.com
--use-ai
--ai-compare openai,anthropic
--html

Agent mode with live NVD CVE lookup

python -m heph --target https://example.com
--use-ai
--ai-agent
--html

Set a cost budget cap (USD)

python -m heph --target https://example.com
--use-ai
--ai-budget 0.50
--html

### Modo Agressivo (Requer Consentimento)```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

🤖 Análise Impulsionada por IA

O Hephaestus usa LangChain 1.0.0 com suporte para múltiplos provedores de IA.

Provedores Suportados

OpenAI GPT-4 Turbo

Melhor para: Uso em produção

• ⭐ Qualidade: Excelente (5/5)
• ⚡ Velocidade: ~35 segundos
• 💰 Custo: ~$0.25 por varredura
• 🔒 Privacidade: Padrão (dados criptografados em trânsito)```bash export OPENAI_API_KEY="sk-..." python -m pip install langchain-openai==1.0.0

#### Anthropic Claude

**Melhor para: Privacidade aprimorada**

- ⭐ Qualidade: Excelente (5/5)
- ⚡ Velocidade: ~45 segundos
- 💰 Custo: ~$0,30 por varredura
- 🔒 Privacidade: Aprimorada (abordagem de privacidade em primeiro lugar da Anthropic)```bash
export ANTHROPIC_API_KEY="sk-ant-..."
python -m pip install langchain-anthropic==1.0.0

Ollama (Modelos Locais)

Melhor para: Privacidade total

• ⭐ Qualidade: Boa (3/5)
• 🐢 Velocidade: ~28 minutos (CPU) ou ~75 segundos (GPU)
• 💰 Custo: Grátis
• 🔐 Privacidade: 100% offline (os dados nunca saem da sua máquina)```bash

Install Ollama: https://ollama.ai

ollama pull llama3.2 python -m pip install "langchain-ollama>=0.3.0,<0.4.0"

### Privacidade & Segurança

**Sanitização Automática**

Antes de enviar para provedores de IA, o Hephaestus remove automaticamente:

- ✅ Tokens de consentimento
- ✅ Chaves de API e credenciais
- ✅ Chaves privadas e certificados
- ✅ Endereços IP internos
- ✅ Credenciais de banco de dados

**Apenas Opt-In**

- Análise de IA requer a flag explícita `--use-ai`
- Varredura agressiva requer token de consentimento verificado
- Você controla qual provedor vê seus dados

**Para Máxima Privacidade**: Use o Ollama localmente.

---

## 🧪 Laboratórios de Teste Seguros

**⚠️ NUNCA escaneie sites de produção sem permissão por escrito!**

Use nossos laboratórios Docker para praticar com segurança:

### Configurar Ambiente de Teste

### Opção 1: Script Interativo (Recomendado)```bash
# Run the interactive deployment script
cd docker && ./deploy.sh

O script oferece 5 opções:

1. Produção → Implantar o serviço de scanner Hephaestus
2. Laboratório de Testes → Implantar servidores web vulneráveis (Apache + Nginx)
3. Ambos → Implantar ambos os ambientes
4. Parar Tudo → Parar todos os serviços em execução
5. Remover Tudo → Remover contêineres, volumes e dados (requer confirmação)

Opção 2: Docker Compose Manual

Apenas Laboratório de Testes:```bash

Start vulnerable servers (Apache + Nginx)

docker compose -f docker/compose.testing.yml up -d

Wait for initialization (~15 seconds)

sleep 15

Verify services

docker compose -f docker/compose.testing.yml ps curl -I http://localhost:8080 # Apache curl -I http://localhost:8081 # Nginx

**Scanner de Produção:**```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/

Ambos os ambientes:```bash

Start both production and testing

docker compose -f docker/compose.yml up -d docker compose -f docker/compose.testing.yml up -d

Scan the testing labs from host

python -m heph --target http://localhost:8080 --html python -m heph --target http://localhost:8081 --html

### Digitalizar os Laboratórios```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

Resultados Esperados

Apache Lab (localhost:8080):

• 42 achados no total (em todas as 13 fases de varredura)
• Inclui achados de CORS, WAF, API, Cookie, phpinfo, mapeados pelo OWASP

Nginx Lab (localhost:8081):

• 25 achados no total (em todas as 13 fases de varredura)
• Inclui achados de CORS, WAF, API, Cookie, mapeados pelo OWASP

Limpeza

Parar serviços:```bash

Using script

cd docker && ./deploy.sh # Choose option 4 (Stop All)

OR manually

docker compose -f docker/compose.yml down docker compose -f docker/compose.testing.yml down

**Remover tudo (AVISO: exclui dados e relatórios):**```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

🐳 Implantação com Docker

O Hephaestus oferece duas opções de implantação com Docker:

Opção 1: Docker Compose (Recomendado)

Serviço de Scanner de Produção:```bash

Start long-running scanner service

docker compose -f docker/compose.yml up -d

Run scans

docker compose -f docker/compose.yml exec hephaestus heph --target https://example.com --html

View reports

ls -lh docker/reports/

Stop service

docker compose -f docker/compose.yml down

**Laboratório de Testes (Servidores Vulneráveis):**```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

Script de Implantação Interativo:```bash

Use the interactive menu

cd docker && ./deploy.sh

### Opção 2: Execução Direta do Docker

**Construir a imagem:**```bash
docker build -f docker/Dockerfile -t hephaestus:0.2.0 .

Executar uma varredura avulsa:```bash docker run --rm
-v $(pwd)/docker/reports:/reports
-v $(pwd)/docker/data:/data
hephaestus:0.2.0
--target https://example.com
--html

**Com análise 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

Escaneie o laboratório de testes local:```bash

Start testing lab first

docker compose -f docker/compose.testing.yml up -d

Scan from container (join the testing lab network)

docker run --rm
--network hephaestus-lab
hephaestus:0.2.0
--target http://hephaestus-vulnerable-apache

---

## 📊 Entendendo Relatórios

### Estrutura do Relatório```
~/.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

Encontrando IDs (Padrão, 70+ total)```

HEPH-SRV-001: Server version disclosed (Apache/Nginx/IIS) HEPH-SRV-004: Server disclosed in error page HEPH-SRV-016: PHP version disclosed in Server header HEPH-SRV-017: OpenSSL version disclosed in Server header HEPH-FILE-001: Environment file exposed (.env) HEPH-FILE-002: Git repository exposed HEPH-FILE-003: PHP information page exposed HEPH-FILE-004: Apache server-status exposed HEPH-HTTP-003: Unsafe HTTP method in OPTIONS (TRACE) HEPH-HTTP-008: TRACE method enabled (XST vulnerability) HEPH-HDR-001: Missing security header: HSTS HEPH-HDR-002: Missing security header: CSP HEPH-HDR-003: Missing security header: X-Frame-Options HEPH-HDR-004: Missing security header: X-Content-Type-Options HEPH-HDR-005: Missing security header: Referrer-Policy HEPH-HDR-006: Missing security header: Permissions-Policy HEPH-CFG-001: Directory listing enabled HEPH-TLS-000: TLS not enabled HEPH-TLS-001: Weak TLS protocol (SSLv3, TLS 1.0) HEPH-TLS-002: Weak cipher suite enabled COR-001 to COR-006: CORS misconfiguration findings ROB-001/002/003: Robots.txt intelligence findings WAF-001/002: WAF detection findings API-001 to API-005: API discovery findings COO-001 to COO-005: Cookie security findings PHP-001 to PHP-009: phpinfo() dangerous settings

### Mapeamento de Severidade

- **CRITICAL**: .env exposto, .git acessível, phpinfo, server-status, dumps SQL
- **HIGH**: Versão do servidor divulgada, TLS fraco, TLS ausente, métodos HTTP inseguros
- **MEDIUM**: Cabeçalhos importantes ausentes (HSTS, CSP, X-Frame-Options), listagem de diretório, divulgação de página de erro
- **LOW**: Cabeçalhos menores (X-Content-Type-Options, Referrer-Policy, Permissions-Policy)
- **INFO**: Achados informativos (servidor detectado, TLS 1.2 OK)

---

## 📁 Estrutura do Projeto```
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

🗺️ Roteiro

v0.1.0 — Lançamento Inicial ✅ (Janeiro de 2026)

Status: 🎉 Lançado (substituído por v0.2.0)

• ✅ 6 módulos de verificação de segurança (servidor, arquivos, métodos, cabeçalhos, TLS, configuração)
• ✅ Guias de endurecimento com IA (OpenAI, Anthropic, Ollama)
• ✅ Sistema de token de consentimento (verificação HTTP + DNS)
• ✅ Relatórios profissionais (JSON + HTML com análise de IA)
• ✅ Persistência SQLite (COMPARTILHADO com o conjunto Argos: ~/.argos/argos.db)
• ✅ Suporte a Docker com laboratórios vulneráveis (Apache & Nginx)
• ✅ Tratamento abrangente de erros e resiliência
• ✅ 55+ testes de validação (10 fases, 100% aprovados)

v0.2.0 — Detecção Aprimorada ✅ (Maio de 2026)

Status: 🎉 Lançado

• ✅ 13 fases de escaneamento (7 novas fases adicionadas em relação à v0.1.0)
• ✅ Análise TLS Profunda: Integração SSLyze, suítes de cifra, correlação de CVEs, classificação A+/F
• ✅ Detecção de Frameworks e Módulos: Laravel, Django, Rails, mod_security, detecção de WAF
• ✅ Analisador de Configuração Apache/Nginx (--config-file): Análise offline de httpd.conf/nginx.conf
• ✅ Detecção CORS: Wildcard, origem nula, sondas de reflexão (COR-001 a COR-006)
• ✅ Inteligência Robots.txt: Análise de caminhos proibidos, sondas de acessibilidade ao vivo (ROB-001/002/003)
• ✅ Detecção de WAF: 13 assinaturas incluindo Cloudflare, Sucuri, ModSecurity, AWS WAF (WAF-001/002)
• ✅ Descoberta de API: Swagger/OpenAPI, introspecção GraphQL, endpoints não autenticados (API-001 a API-005)
• ✅ Segurança de Cookies: Análise por cookie HttpOnly/Secure/SameSite (COO-001 a COO-005)
• ✅ Análise Profunda phpinfo(): 9 configurações perigosas do PHP (PHP-001 a PHP-009)
• ✅ Mapeamento OWASP Top 10 2021 em cada achado
• ✅ Consulta de CVE ao Vivo via NVD API v2 (Apache, Nginx, PHP, OpenSSL)
• ✅ Scanner de Portas: 37 portas com captura de banner
• ✅ Rastreamento de Custos de IA (--ai-budget): Limites de orçamento, costs.json, tabela ai_costs
• ✅ Streaming de IA (--ai-stream): Saída token por token em tempo real
• ✅ Comparação de IA (--ai-compare): Executar dois provedores em paralelo
• ✅ Agente de IA (--ai-agent): Agente LangChain com consulta NVD CVE

v0.3.0 — Funcionalidades Empresariais (T3 2026)

Foco: Usabilidade, escala, IA interativa

• 🔜 Gerenciamento Interativo de Configuração: Interface estilo Metasploit (heph --show-options, heph --set)
• 🔜 CLI de Banco de Dados: Sem necessidade de SQL (heph db scans list, heph db findings search)
• 🔜 Escaneamento Multi-Site: Processamento em lote a partir de arquivo
• 🔜 Interface de Chat com IA: Orientação conversacional de endurecimento
• 🔜 Integração CI/CD: Modelos para GitHub Actions, Jenkins, GitLab
• 🔜 Servidor de API REST: API baseada em FastAPI para automação
• 🔜 Integração Nmap: Escaneamento de portas para avaliação abrangente

v0.4.0 — Inteligência e Automação (T4 2026)

Foco: ML, automação, IA avançada

• 🔜 Remediação Automatizada: Playbooks Ansible/Puppet para correção automática
• 🔜 Detecção Baseada em ML: Detecção de anomalias, redução de falsos positivos
• 🔜 Escaneamento Distribuído: Nós de trabalho para operações em larga escala
• 🔜 Agentes de IA Avançados: Planejamento autônomo de escaneamento, geração de exploits

Pro Track (T1 2027)

Produto comercial para empresas

EM ANDAMENTO

Para descrições detalhadas das funcionalidades, veja ROADMAP.md

🔒 Ética e Legal

A Regra de Ouro

Escaneie apenas sistemas que você possui ou para os quais tem permissão explícita por escrito para testar.

Aplicação de Consentimento

Hephaestus implementa controles técnicos para prevenir uso indevido:

Estrutura Legal

O acesso não autorizado a sistemas de computador é ilegal na maioria das jurisdições:

• 🇺🇸 EUA: Computer Fraud and Abuse Act (CFAA)
• 🇬🇧 Reino Unido: Computer Misuse Act 1990
• 🇪🇺 UE: Diretiva 2013/40/EU
• 🌍 Internacional: Várias leis de crimes cibernéticos

Melhores Práticas

1. ✅ Obtenha autorização por escrito antes de escanear
2. ✅ Defina o escopo claramente (quais domínios/IPs)
3. ✅ Documente tudo (consentimento, achados, remediação)
4. ✅ Use o modo seguro primeiro para estabelecer uma linha de base
5. ✅ Relate os achados responsavelmente (divulgação coordenada)
6. ❌ Nunca explore vulnerabilidades sem permissão explícita
7. ❌ Nunca escaneie sites de terceiros (ex.: apache.org, nginx.com)

Para diretrizes éticas completas, veja docs/ETHICS.md

🤝 Contribuindo

Aceitamos contribuições! Seja:

• 🐛 Relatórios de bugs
• 💡 Solicitações de funcionalidades
• 📝 Melhorias na documentação
• 🔧 Contribuições de código

Como Contribuir

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça suas alterações
4. Escreva/atualize testes (quando aplicável)
5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
6. Envie para o branch (git push origin feature/amazing-feature)
7. Abra um Pull Request

Configuração de Desenvolvimento```bash

Clone your fork

git clone https://github.com/YOUR-USERNAME/hephaestus-server-forger.git cd hephaestus-server-forger

Install development dependencies

python -m pip install -r requirements.txt python -m pip install pytest black flake8 mypy

Run code formatting

black heph/

Run linting

flake8 heph/ mypy heph/

Run tests (when available)

pytest tests/

### Reportando Problemas

Encontrou um bug? Tem uma solicitação de funcionalidade?

**Abra uma issue**: https://github.com/rodhnin/hephaestus-server-forger/issues

Por favor, inclua:

- Versão do Hephaestus (`python -m heph --version`)
- Versão do Python (`python --version`)
- Sistema operacional
- Passos para reproduzir (para bugs)
- Comportamento esperado vs real

---

## 📚 Documentação

Documentação abrangente disponível no diretório `docs/`:

| Document                                    | Description                               |
| ------------------------------------------- | ----------------------------------------- |
| [AI_INTEGRATION.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/AI_INTEGRATION.md) | Guia completo de configuração de IA (todos os 3 provedores) |
| [CONSENT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/CONSENT.md)               | Detalhes técnicos do sistema de token de consentimento    |
| [DATABASE_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/DATABASE_GUIDE.md) | Esquema SQLite, consultas, gerenciamento        |
| [ETHICS.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/ETHICS.md)                 | Estrutura legal e diretrizes éticas    |
| [REPORT_FORMAT.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/REPORT_FORMAT.md)   | Esquema JSON e especificações HTML       |
| [TESTING_GUIDE.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/TESTING_GUIDE.md)   | Testes seguros com laboratórios Docker             |
| [ROADMAP.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/docs/ROADMAP.md)               | Funcionalidades futuras e planos de desenvolvimento     |

### Links Rápidos

- **Registro de alterações**: [CHANGELOG.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/CHANGELOG.md)
- **Licença**: [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/LICENSE)
- **Exemplos de CLI**: [scripts/cli-examples.md](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/scripts/cli-examples.md)

---

## ⚖️ Licença

Este projeto está licenciado sob a **Licença MIT** - veja o arquivo [LICENSE](https://github.com/rodhnin/hephaestus-server-forger/blob/HEAD/LICENSE) para detalhes.```
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.

⚠️ Aviso Legal

IMPORTANTE: Esta ferramenta é para testes de segurança autorizados apenas.

Aviso Legal

Ao usar o Hephaestus, você reconhece e concorda que:

1. ✅ Você apenas escaneará sistemas próprios ou com permissão explícita por escrito para testar
2. ✅ Você cumprirá todas as leis e regulamentos aplicáveis
3. ✅ Você entende que acesso não autorizado é ilegal (CFAA, Computer Misuse Act, etc.)
4. ✅ O autor e os colaboradores não assumem responsabilidade por uso indevido
5. ✅ Este software é fornecido "como está" sem garantia de qualquer tipo

Divulgação Responsável

Se você descobrir vulnerabilidades usando o Hephaestus:

• 📧 Contate o proprietário do site em particular primeiro
• ⏰ Dê tempo razoável para corrigir (normalmente 90 dias)
• 🤝 Coordene o cronograma de divulgação
• 📝 Documente suas descobertas profissionalmente

Em Caso de Dúvida

Não escaneie. Se você não tem certeza se tem permissão, provavelmente não tem.

🙏 Agradecimentos

Hephaestus está sobre os ombros de gigantes:

• Apache & Nginx — Documentação e guias de endurecimento (hardening)
• OWASP — Padrões de segurança (Top 10, Guia de Testes, Projeto Secure Headers)
• CIS Benchmarks — Melhores práticas de endurecimento de servidores
• LangChain — Framework de IA para análise inteligente
• Anthropic & OpenAI — Modelos de IA para análise de vulnerabilidades
• Ollama — Inferência de IA local para escaneamento focado em privacidade
• Python Community — Bibliotecas e ferramentas incríveis

Agradecimentos especiais a todos os pesquisadores de segurança que praticam e promovem hacking ético.

👤 Autor

Rodney Dhavid Jimenez Chacin (rodhnin)

• 🌐 Site e Contato: rodhnin.com
• 💼 GitHub: @rodhnin
• 🔗 Projeto: hephaestus-server-forger

Para perguntas, feedback ou consultas de colaboração, visite rodhnin.com para me contatar.

💬 Comunidade

• Discussões: GitHub Discussions
• Issues: GitHub Issues
• Lançamentos: GitHub Releases