NetLogic is an advanced network analysis and cybersecurity toolkit for traffic inspection, packet analysis, and threat detection
Mapeador de Superfície de Ataque Nativo em Nuvem e Correlacionador de Vulnerabilidades — v3.0
NetLogic é uma plataforma de segurança de rede que combina varredura ativa de portas, correlação de CVEs (API NVD ao vivo), análise SSL/TLS, auditoria de segurança HTTP, avaliação de segurança DNS/email, detecção de takeover de subdomínio, OSINT passivo, sondagem ativa de vulnerabilidades, um mecanismo de raciocínio orientado por IA, descoberta de cadeia de ataque entre hosts e arquitetura de agente de sondagem profunda — entregue como um app web (painel React + FastAPI). O mecanismo de varredura principal é Python puro 3.9+ stdlib sem dependências de terceiros.
| Módulo | Descrição |
|---|---|
| Scanner de Portas | Varredura TCP connect com 43/58 portas, 22 sondas de serviço, captura de banner |
| Correlacionador de CVEs | API NVD v2.0 ao vivo + enriquecimento EPSS via FIRST.org |
| Analisador TLS | Versões de protocolo, cifras fracas, POODLE/BEAST/CRIME/DROWN, expiração de certificado |
| Auditoria de Cabeçalhos HTTP | HSTS, CSP, X-Frame-Options, CORS, flags de cookies; pontuação 0–100 |
| Impressão Digital de Stack | Detecção de CMS, framework, provedor de nuvem, CDN, WAF a partir de banner/cabeçalho/corpo |
| Segurança DNS | SPF, DKIM, DMARC, DNSSEC, transferência de zona, pontuação de falsificabilidade |
| OSINT Passivo | Logs de Transparência de Certificados, DNS DoH, consulta ASN — sem contato direto com o alvo |
| Sonda de Serviços | Sondagens não autenticadas Redis/Mongo/ES/Docker/K8s/etcd, 33 caminhos administrativos |
| Detector de Takeover | Descoberta de subdomínios via CT log + 25 impressões digitais CNAME de provedores de nuvem |
| Integração Nuclei | Invólucro para 13k+ modelos da comunidade (CVE, tecnologia, exposição, má configuração) — licença MIT |
| Pipeline de Fusão | Portão multissensor → acordo determinístico → adjudicação por IA → grafo de ataque → relatório de 6 seções |
| Impressão Digital Web | Hash de favicon (mmh3 compatível com Shodan), segredos em JS, marcadores de versão, arquivos expostos, detecção de página inicial padrão |
| Análise de IA | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — streaming SSE de tokens |
| Mecanismo de Raciocínio | Ciclo adaptativo observar→raciocinar→agir com EvidenceGraph, mecanismo de hipóteses, decaimento de confiança, proveniência, agendador, playbooks, detecção de alterações, validação ativa |
| Sonda Profunda | Arquitetura de agente por serviço: ScoutAgent (recon), ProbeAgent (verificações de CVE direcionadas), Coordenador, Sandbox |
| Agente de Investigação de IA | Loop estilo ReAct: após sensores de base, a IA conduz uma superfície de ferramentas curada, com escopo limitado e auditada (~35 ferramentas) para verificar leads e construir cadeias de ataque — com ferramentas agressivas opcionais (sondas de falha, prova livre de forma, exploit livre) para alvos autorizados |
Existem exatamente duas formas de executar o NetLogic:
| Modo | Comando | O que faz |
|---|---|---|
| App web | netlogic --gui | Inicia FastAPI + serve o SPA React + agente de varredura em processo, gera segredos automaticamente e abre o painel no seu navegador. Esta é a única maneira de executar o app web. |
| CLI |
A superfície do produto é o app web (painel React + FastAPI). O mecanismo de varredura em src/ alimenta trabalhos iniciados a partir da interface.
pip install -r requirements-api.txt pip install -e .
netlogic --gui
netlogic scanme.nmap.org --full
---
## Referência da CLI```
netlogic [target] [flags]
O ponto de entrada é api.cli:main (definido em pyproject.toml), que delega para netlogic.py:main(). Toda a lógica de varredura está em src/.
netlogic example.com
netlogic example.com --full
netlogic example.com --tls --headers
netlogic example.com --takeover
netlogic example.com --osint
netlogic example.com --stack
netlogic example.com --dns
netlogic 10.0.0.5 --probe
netlogic example.com --full --probe
### Seleção de portas```
# Quick — 43 common ports (default)
netlogic example.com --ports quick
# Full — 58 extended ports
netlogic example.com --ports full
# Custom list
netlogic example.com --ports custom=22,80,443,8080,9200
netlogic example.com --ai --ai-key $KEY
netlogic example.com --ai --ai-provider openai --ai-key $KEY --ai-model gpt-4o-mini
netlogic example.com --ai --ai-provider anthropic --ai-key $KEY
netlogic example.com --ai --ai-provider gemini --ai-key $KEY --ai-model gemini-2.0-flash
netlogic example.com --ai --ai-provider ollama
netlogic example.com --ai --ai-provider custom --ai-base-url https://... --ai-model model-name
### Provedores de IA suportados
| Provider | Modelo padrão | Estilo de API |
|---|---|---|
| `openrouter` | `anthropic/claude-sonnet-4` | OpenAI |
| `openai` | `gpt-4o-mini` | OpenAI |
| `anthropic` | `claude-3-5-sonnet-20241022` | Anthropic Messages |
| `kimi` (Moonshot) | `kimi-k2.6` | OpenAI |
| `qwen` (Alibaba) | `qwen-plus` | OpenAI |
| `groq` | `llama-3.3-70b-versatile` | OpenAI |
| `gemini` (Google) | `gemini-2.0-flash` | OpenAI |
| `ollama` | `llama3` | OpenAI |
| `custom` | especificado pelo utilizador | OpenAI |
### Motor de raciocínio```
# Adaptive observe→reason→act loop (deterministic by default; AI-augmented with --ai)
netlogic example.com --reason
# Multi-host world modeling — discovers in-scope neighbours, reasons per host
netlogic example.com --reason --multi-host
# Change detection — diffs against prior saved report
netlogic example.com --since-last
# Active validation — confirms hypotheses with safe non-destructive GETs
netlogic example.com --reason --active-validate
# Deep probe — per-service agent architecture with context isolation
netlogic example.com --deep-probe
Após a execução dos sensores de base, um agente opcional no estilo ReAct permite que a IA utilize suas próprias ferramentas para verificar pistas e construir cadeias de ataque, em vez de deixar os hits de CVE de versão/banner como pistas não verificadas. A IA propõe chamadas de ferramentas; um ambiente de execução determinístico as executa — cada ferramenta tem escopo delimitado ao alvo, é sanitizada e registrada como uma observação. A IA nunca toca diretamente na rede.```
netlogic example.com --ai --ai-agent
netlogic example.com --ai --agent-depth --agent-max-steps 24 --agent-max-requests 80
The agent has ~35 read-only/safe-active tools by default: HTTP/TLS/DNS probes, `dir_enum`, `confirm_tech`,
`timing_probe`, `cve_probe` (curated known-CVE marker checks), `sqli_boolean`/`sqli_time`, `ssrf_canary`,
`idor_diff`, `file_disclosure`, `browser_get` (headless, passes JS challenges), plus HackerOne bookkeeping
(`record_poc`, `severity_suggest`, `submit_readiness`).
**Ferramentas agressivas opcionais** — desativadas por padrão, **apenas para alvos AUTORIZADOS / próprios no escopo** (nunca em um
alvo público ou de estranhos). Cada uma requer `--ai-agent`:
| Flag | Ferramenta | O que ela desbloqueia | Rails mantidos |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | Verificações curadas de CVE de crash/DoS (http.sys, MS15-034) que PODEM travar o host | Catálogo fixo de 3 CVEs — não livre |
| `--allow-freeform-proof` | `http_proof` | Nível C: GET/HEAD/OPTIONS livres (+ POST em caminhos tipo search/login/graphql) | Padrões destrutivos + PUT/PATCH/DELETE bloqueados; prova, não mutação |
| `--allow-exploit-requests` | `exploit_request` | Nível E: **qualquer método** (incl. PUT/PATCH/DELETE) + caminho/cabeçalhos/corpo arbitrários contra o alvo | Escopo limitado; fechamento falha em padrões massivamente destrutivos (DROP/TRUNCATE TABLE, `rm -rf`) e injeção de cabeçalho CR/LF; toda requisição auditada |
O ActionGate determinístico mantém o núcleo em `safe_active`; essas três flags são as opções explícitas e auditadas
acima dele. Exemplo (caixa de laboratório própria + modelo local):```
netlogic YOUR_LAB_HOST --full --ai --ai-agent --agent-depth \
--allow-crash-probes --allow-exploit-requests \
--ai-provider ollama --ai-model gemma4:31b-cloud \
--ai-base-url http://localhost:11434/v1 --ai-key ollama
netlogic example.com --ssh-user admin --ssh-key ~/.ssh/id_rsa
netlogic example.com --ssh-user admin --ssh-pass SECRET
netlogic example.com --ssh-user admin --ssh-key ~/.ssh/id_rsa --ssh-port 2222
### Benchmark```
# Fusion pipeline benchmark against recorded cassettes (oracle mode — perfect AI upper bound)
netlogic --benchmark
# With real AI model
netlogic --benchmark --benchmark-ai
# Export report
netlogic --benchmark --benchmark-export report.md
# Verbose per-subject output
netlogic --benchmark --benchmark-verbose
netlogic example.com --report terminal # terminal output (default) netlogic example.com --report json # JSON file netlogic example.com --report html # HTML report netlogic example.com --report all # terminal + JSON + HTML
netlogic example.com --out ./reports
netlogic example.com --min-cvss 7.0
netlogic example.com --no-color
### Gerenciamento de cache NVD```
netlogic --cache-stats
netlogic example.com --nvd-key YOUR_NVD_KEY
netlogic --version # Show version and exit netlogic --gui # Start web dashboard
---
## Fusion Pipeline
The fusion pipeline is a **sensors → gate → AI adjudication → synthesis** funnel that replaces monolithic AI calls with a precision gate. It lives in `src/fusion/` (12 files).
### Signal schema (`src/fusion/signals.py`)
Evidence-bearing data contract. Every sensor emits `Signal` objects:
- `source`: `probe`/`banner`/`nuclei`/`wappalyzer`/`nvd`/`osv`/`tls`/`dns`
- `kind`: `vuln`/`tech`/`exposure`/`misconfig`/`service`
- `claim`: normalised subject (e.g. `"CVE-2021-44228"`, `"nginx"`)
- `host`, `port`, `service`, `evidence` (capped 600 chars)
- `confidence` (0..1), `reliability` (`high`/`medium`/`low`)
- `kev`, `epss` (0..1), `cvss` (0..10), `exploit_available`, `version_matched`, `probe_confirmed`
- `exposure` dict (reachability, WAF, vantage)
- `observed_data` (raw bytes sent to AI — NOT sensor names or severities to prevent label bias)
- `ai_view()` strips sensor metadata, returns only observed facts
### Gate (`src/fusion/gate.py`)
Deterministic agreement — given `list[Signal]`, groups by subject and returns `list[Verdict]`:
| Condition | Verdict |
|---|---|
| KEV-listed OR probe-confirmed OR critical+exploit/high-EPSS | **Confirmed** (pinned — un-droppable) |
| ≥2 independent sources agree, ≥1 high-reliability | **Confirmed** (unless all are version-matched → gray) |
| Solo low-reliability, low/medium impact, no corroboration | **Discarded** |
| Everything else | **Gray** (costs an AI token) |
### AI Adjudication (`src/fusion/adjudicator.py`)
Only touches the gray band. Safety constraints enforced in code (not prompt):
- High/critical gray items can NEVER be discarded — at worst demoted to `potential`
- Version-only matches capped at `potential` (distros backport without version bumps)
- AI also discovers new findings from full host context
- Fail-soft: AI outage leaves gray band as `potential` — no silent data loss
### Synthesis (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → deterministic reachability graph from CONFIRMED findings.
`full_synthesize(...)` → 6-section AI report:
1. Executive Summary
2. Key Findings (table)
3. Attack Chains (graph-based, LLM narrates real edges)
4. Beyond Known CVEs
5. False Positives & Noise
6. Remediation
### Sensors
| Sensor | File | What it produces |
|---|---|---|
| Engine bridge | `engine_bridge.py` | Converts scan artifacts → Signals from NVD, probes, stack, Nuclei, verifier |
| Wappalyzer | `sensors/wappalyzer.py` | Zero-dependency Wappalyzer-compatible fingerprinting of HTTP responses |
| Nuclei | `sensors/nuclei.py` | Runs YAML templates against responses (subset of Nuclei syntax) |
| Cassette | `cassette.py` | Record/replay from HTTP cassettes (offline benchmark data) |
### Cross-host (`src/fusion/cross_host.py`)
Post-adjudication grouping of verdicts across hosts by shared service+version for multi-hop attack chain narration in synthesis.
### Pipeline Flow```
Engine artifacts / Cassette data
↓
engine_bridge.py / cassette.py → Signal list
↓
gate.py::adjudicate() → Verdict list (confirmed/discarded/gray)
↓
adjudicator.py::run_adjudication() → AI on gray band only
↓
synthesis.py::full_synthesize() → 6-section report + attack graph
Localizado em src/reasoning/ (~58 ficheiros). Ciclo de fases múltiplas, com gate de segurança, observar→raciocinar→agir. Ativado com --reason.
src/reasoning/director.py — ReconDirector.run())StrategyManager seleciona persona → Scheduler escolhe ação → SensorStep executa → EvidenceGraph dobra observações → ConfidenceEngine atualiza crençasProposal tipados → AICoordinator normaliza/classifica/verifica → propostas aceitas alimentam o estado → Compiler → ExecutionPlanner → ExecutionKernel executa sondas → InferenceEngine resolveCrossHostGraph, gera instâncias filhas de HostReasonersrc/reasoning/state.py)src/reasoning/ai/)Pipeline: Gerar → Normalizar → Classificar → (MetaReasoner podar) → Verificar → Armazenar
Localizado em src/deep/ (7 ficheiros). Usado com --deep-probe. Arquitetura de agente por serviço para execução de sonda isolada por contexto.
Fluxo de DeepCoordinator.run():
_build_sensor_plan via sensor_director)ScoutAgent para reconhecimento passivoProbeAgent por serviço (cada uma com contexto isolado de CVE/tecnologia)Localizado em src/verifier/ (3 ficheiros). Confirmação de CVE orientada por IA com sondas direcionadas.
A re-verificação da Fase 2 (reverify_with_context) fornece contexto completo do host para refinar testes falhos.
Localizado em src/directors/ (4 ficheiros). Seleção de parâmetros de varredura orientada por LLM.
Localizado em src/orchestrator.py. Acionado por alvos separados por vírgulas. Executa run_scan() por host, agrega resultados, constrói contexto entre hosts a partir de vereditos de fusão combinados. Grupos entre hosts detetam serviços/versões partilhados entre hosts para narração de cadeia de ataque multi-salto.
src/nvd_lookup.py)--nvd-key)src/epss.py): API da FIRST.org em lotes de 100 IDs de CVE, cache de disco de 24h em ~/.netlogic/epss_cache.json, falha suave para 0.0src/external/nuclei_runner.py encapsula o binário Nuclei (licença MIT). Opcional — degrada-se graciosamente quando o binário não é encontrado. Os resultados alimentam o pipeline de fusão como sinais tipados (rótulos de gravidade removidos para evitar enviesamento do LLM).```
scoop install nuclei # Windows brew install nuclei # macOS go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Linux
## Fusion Benchmark
`src/fusion/benchmark.py` — medição offline contra cassetes HTTP rotulados (`benchmark/*.json` e `src/fusion/data/`). Métricas:
| Métrica | Limiar de gate |
|---|---|
| Redução de FP | ≥ 80% |
| Recall crítico | = 100% |
Dois modos:
- **Oráculo** (`--benchmark`): limite superior de IA perfeita — mede apenas a maquinaria determinística
- **Modelo real** (`--benchmark --benchmark-ai`): medido com LLM configurado
---
## Arquitetura```
netlogic/
├── netlogic.py ← Local launcher (`--gui`, optional CLI helpers)
│
├── src/ ← Scan engine (used by the web API)
│ ├── scanner.py ← TCP scanner, 22 service probes, banner grabbing
│ ├── engine.py ← Orchestrator: SensorStep pipeline, all scan modules + fusion
│ ├── orchestrator.py ← Multi-host: per-host scan → cross-host context
│ ├── ai_analyst.py ← LLM integration (9 providers, stdlib-only transport)
│ ├── cve_correlator.py ← CVE matching: NVD
│ ├── nvd_lookup.py ← NVD API v2.0 client, disk cache, CISA KEV
│ ├── epss.py ← EPSS enrichment (FIRST.org, 24h cache)
│ ├── service_prober.py ← Unauthenticated service access, default creds, admin paths
│ ├── vuln_prober.py ← CVE-specific safe active probes
│ ├── osint.py ← DoH, CT logs, ASN lookup
│ ├── tls_analyzer.py ← SSL/TLS deep analysis
│ ├── header_audit.py ← HTTP security header audit
│ ├── stack_fingerprint.py ← CMS, framework, cloud, CDN, WAF detector
│ ├── web_fingerprint.py ← Favicon mmh3, JS secrets, version files, exposed paths, lander detection
│ ├── dns_security.py ← SPF, DKIM, DMARC, DNSSEC, zone transfer
│ ├── takeover.py ← Subdomain takeover (25 provider fingerprints)
│ ├── authenticated.py ← SSH subprocess: dpkg/rpm/apk parsing, 60+ product mappings
│ ├── topology.py ← PTR, IPv6, traceroute, ASN/org/country
│ ├── reachability_prober.py ← Lateral movement matrix from subnet adjacency
│ ├── network_prober.py ← /24 subnet sweep: live-host → full port scan
│ ├── service_enum.py ← Protocol attribute extraction (SSH KEX, SMBv1, RDP NLA, SNMP)
│ ├── ssl_utils.py ← Configurable SSL context management, TLS probe
│ ├── scan_diff.py ← Change-over-time: diffs against prior JSON report
│ ├── json_bridge.py ← Streaming JSON events for agent / REST API
│ ├── reporter.py ← Terminal, JSON, HTML output renderers
│ │
│ ├── fusion/ ← Precision funnel (12 files)
│ │ ├── signals.py ← Signal schema
│ │ ├── gate.py ← Deterministic agreement
│ │ ├── adjudicator.py ← AI adjudication (gray band only)
│ │ ├── synthesis.py ← Attack graph + 6-section report
│ │ ├── ai.py ← CompleteFn/StreamCompleteFn adapter
│ │ ├── engine_bridge.py ← Artifacts → Signals → verdicts
│ │ ├── benchmark.py ← Offline benchmark (oracle + real model)
│ │ ├── cassette.py ← HTTP cassette record/replay
│ │ ├── corpus.py ← Cassette→case conversion + CLI
│ │ ├── cross_host.py ← Cross-host verdict correlation
│ │ ├── sensors/nuclei.py ← Nuclei YAML → Signal conversion
│ │ └── sensors/wappalyzer.py← Wappalyzer fingerprint → Signal
│ │
│ ├── directors/ ← AI sensor directors (4 files)
│ │ ├── sensor_director.py ← LLM selects which sensors to enable
│ │ ├── reprobe.py ← LLM designs re-probe plans
│ │ ├── nuclei_selector.py ← LLM selects Nuclei template tags
│ │ └── subnet_director.py ← LLM directs subnet probing
│ │
│ ├── verifier/ ← AI CVE verification (3 files)
│ │ ├── engine.py ← Verifier orchestration
│ │ ├── planner.py ← Built-in + AI-generated probe plans
│ │ └── runner.py ← Raw TCP/TLS probe execution
│ │
│ ├── deep/ ← Deep probe agents (7 files)
│ │ ├── coordinator.py ← Full deep pipeline orchestrator
│ │ ├── scout_agent.py ← Passive recon agent
│ │ ├── probe_agent.py ← Per-service probe agent
│ │ ├── chain.py ← Exploit chain planning + PoC generation
│ │ ├── sandbox.py ← Restricted PoC execution
│ │ ├── base_agent.py ← Abstract base
│ │ └── models.py ← Mission/AgentReport data models
│ │
│ ├── reasoning/ ← Adaptive reasoning engine (~58 files)
│ │ ├── director.py ← ReconDirector (main loop)
│ │ ├── state.py ← WorldModel/InvestigationState/ExecutionState
│ │ ├── hypothesis.py ← Hypothesis engine (competing candidates)
│ │ ├── evidence_graph.py ← Temporal entity graph (content-addressed obs)
│ │ ├── confidence.py ← Noisy-OR belief computation
│ │ ├── provenance.py ← Observation→Inference→Hypothesis edges
│ │ ├── scheduler.py ← Information-gain action selection
│ │ ├── strategy.py ← Meta-reasoning: personas, explore/exploit
│ │ ├── strategies.py ← Concrete strategy implementations
│ │ ├── action_gate.py ← Risk-tiered probe authorisation
│ │ ├── change_detection.py ← Phase 7: observation-level diff
│ │ ├── active_validation.py ← Phase 8b: SAFE_ACTIVE probes
│ │ ├── cross_host.py ← Cross-host world modeling
│ │ ├── objective.py ← Objective DAG management
│ │ ├── intent.py ← Intent model + EvidenceType enum (29 types)
│ │ ├── candidate.py ← Action candidate with lazy factory
│ │ ├── actions.py ← Action model with RiskTier + Predicate
│ │ ├── compiler.py ← Intent → InvestigationGraph
│ │ ├── execution_planner.py ← InvestigationGraph → ProbePlanGraph
│ │ ├── execution_kernel.py ← Probe execution with validators
│ │ ├── probe_executor.py ← Read-only probe backends
│ │ ├── primitive_registry.py← Probe primitive catalogue
│ │ ├── generators.py ← Deterministic objective/hypothesis population
│ │ ├── playbooks.py ← YAML playbook system
│ │ ├── planning_pass.py ← GoalPlanner integration
│ │ ├── budget.py ← Probe budget management
│ │ ├── inference.py ← Deterministic rule-based inference
│ │ ├── novel_inference.py ← Novel-vuln hypothesis rules
│ │ ├── investigation_planner.py ← Goal-directed investigation planning
│ │ ├── investigation_memory.py ← Strategy attempt memory
│ │ ├── observation_translator.py ← Raw data → structured observations
│ │ ├── observation.py ← Immutable, content-addressed observation
│ │ ├── reflect.py ← PlannerFeedback generation
│ │ ├── reasoning_validator.py ← Continuous integrity audit
│ │ ├── builder.py ← State population from artifacts
│ │ ├── trace.py ← Execution tracing
│ │ ├── explanation.py ← Explanation records
│ │ ├── ai/ ← AI cognitive layer (subsystem)
│ │ ├── packs/ ← Technology pack calibration
│ │ ├── playbooks/ ← YAML playbook templates
│ │ └── rules/ ← JSON inference rules
│ │
│ └── external/nuclei_runner.py ← Nuclei binary wrapper
│
├── api/ ← FastAPI controller
│ ├── main.py ← App factory, lifespan, middleware stack
│ ├── cli.py ← Typer -> netlogic.py bridge
│ ├── db.py ← PostgreSQL connection + migration runner
│ ├── crypto.py ← Fernet seal/unseal (AES-128-CBC + HMAC-SHA256)
│ ├── auth/
│ │ ├── api_keys.py ← Dual-store (memory/PG), SHA-256 hashed
│ │ ├── jwt_handler.py ← Stdlib-only HS256 JWT
│ │ ├── oidc.py ← Clerk/IdP OIDC (RS256 + JWKS)
│ │ ├── license.py ← LicenseManager (stub → real payment API)
│ │ ├── rate_limit.py ← Sliding-window, IP banning
│ │ ├── provisioning.py ← Clerk auto-provisioning
│ │ └── dependencies.py ← require_org FastAPI dependency
│ ├── agents/
│ │ ├── registry.py ← Agent lifecycle (concurrency-aware, JSON persistence)
│ │ └── local_agent.py ← Built-in in-process agent
│ ├── jobs/
│ │ ├── manager.py ← ScanJob lifecycle, capped event deque (10k), SSE, Postgres
│ │ └── executor.py ← Dispatch (capability/selector, least-loaded, reclaimer)
│ ├── middleware/audit.py ← X-Request-ID + structured audit + SIEM shipping
│ ├── models/
│ │ ├── scan_request.py ← Pydantic ScanRequest (ipaddress validation)
│ │ └── agent.py ← AgentRegistration constraints
│ ├── routes/
│ │ ├── auth.py ← /v1/auth/*
│ │ ├── jobs.py ← /v1/jobs/*
│ │ ├── agents.py ← /v1/agents/*
│ │ ├── health.py ← /health + /v1/health
│ │ ├── license.py ← /v1/license/*
│ │ └── settings.py ← /v1/settings/*
│ └── storage/
│ ├── json_store.py ← 10 MB cap, 500 file cap, atomic writes
│ ├── pg_store.py ← Postgres JSONB upsert
│ └── reasoning_store.py ← Dual-store for reasoning state
│
├── dashboard/ ← React SPA (Vite + TypeScript + Tailwind + Clerk)
│ └── src/
│ └── pages/ ← Dashboard, NewScan, ScanDetail, Agents, Targets,
│ TargetTimeline, Settings, License, Login, SignUp, Legal
│
├── docs/ ← Design documentation
│ ├── DEPLOY_SAAS.md, saas-auth.md
│ ├── REASONING_ENGINE_DESIGN.md
│ ├── LEGAL_COMPLIANCE.md
│ ├── ENTERPRISE_READINESS.md
│ └── DESIGN_PARTNER_PACK.md
│
├── db/migrations/ ← PostgreSQL schema migrations
└── benchmark/ ← HTTP cassette recordings for fusion benchmark
Todas as rotas sob o prefixo /v1/. Autenticação:
POST /v1/auth/token → JWT HS256 (expiração padrão de 1h)require_org verifica contra JWKSPOST /v1/auth/token Exchange API key for JWT [10/min/IP] POST /v1/auth/keys Create API key (X-Admin-Key) [admin] GET /v1/auth/keys List keys (masked) [admin] DELETE /v1/auth/keys Revoke key (body, not URL) [admin]
### Empregos```
POST /v1/jobs Create scan job [30/min/org]
GET /v1/jobs List recent jobs
GET /v1/jobs/history/{target} Scan history for target
GET /v1/jobs/{id} Job detail
GET /v1/jobs/{id}/stream SSE event stream [60/min/org]
GET /v1/jobs/{id}/export Export (format=json|md|raw)
POST /v1/jobs/{id}/explore-beyond AI deep-dive on finding
POST /v1/jobs/{id}/cancel Cancel job
DELETE /v1/jobs/{id} Remove job
POST /v1/agents/register Register agent [5/hr/IP] POST /v1/agents/{id}/heartbeat Keep-alive [3/min] GET /v1/agents/{id}/tasks Poll pending jobs POST /v1/agents/{id}/tasks/{job_id}/events Submit events [60/min, 500/batch] POST /v1/agents/{id}/tasks/{job_id}/complete Mark done/failed GET /v1/agents List agents (org-scoped) GET /v1/agents/{id} Agent detail DELETE /v1/agents/{id} Deregister POST /v1/agents/{id}/activate Enable agent POST /v1/agents/{id}/deactivate Disable agent
### Licença / Configurações```
GET /v1/license License status
POST /v1/license/activate Activate key [3/hr/IP]
GET /v1/settings/ai Get org AI config (key masked)
POST /v1/settings/ai Update org AI config (encrypted)
POST /v1/settings/ai/test Test AI connection
GET /health Service status + uptime GET /docs OpenAPI docs GET /redoc ReDoc docs
---
## Variáveis de Ambiente
### Controlador
| Variável | Padrão | Descrição |
|---|---|---|
| `NETLOGIC_ENV` | _(não definido)_ | `production`/`prod` = validação de segredo na inicialização |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | Segredo de assinatura HS256, ≥32 caracteres |
| `NETLOGIC_JWT_EXPIRY` | `3600` | Tempo de vida do JWT em segundos |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | Credencial de administrador, ≥32 caracteres em produção |
| `NETLOGIC_API_KEYS` | _(vazio)_ | Chaves iniciais: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(vazio)_ | Origens permitidas (CORS desabilitado se vazio) |
| `NETLOGIC_PORT` | `8000` | Porta de vinculação |
| `NETLOGIC_HOST` | `0.0.0.0` | Endereço de vinculação |
| `NETLOGIC_NO_BROWSER` | _(não definido)_ | `1` desativa abertura automática |
| `NETLOGIC_OIDC_ISSUER` | _(não definido)_ | URL da API Frontend do Clerk → login OIDC |
| `NETLOGIC_OIDC_AUDIENCE` | _(não definido)_ | Audiência OIDC |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(não definido)_ | org_id de fallback para usuários OIDC |
| `NETLOGIC_DATABASE_URL` | _(não definido)_ | String de conexão PostgreSQL |
| `NETLOGIC_SECRETS_KEY` | _(não definido)_ | Chave Fernet para credenciais em repouso |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | Tempo de vida do token do agente (7 dias) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | Máximo de tarefas na fila por agente |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | Máximo de agentes registrados |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | Provedor de IA padrão |
| `NETLOGIC_AI_API_KEY` | _(vazio)_ | Chave de IA padrão |
| `NETLOGIC_AI_MODEL` | padrão do provedor | Modelo padrão |
| `NETLOGIC_AI_BASE_URL` | padrão do provedor | URL base personalizada |
| `NETLOGIC_NVD_KEY` | _(vazio)_ | Chave da API NVD |
| `NETLOGIC_VALID_LICENSES` | _(vazio)_ | Sobrescritas de licença para dev/teste |
| `NETLOGIC_LICENSE_KEY` | _(vazio)_ | Chave de licença da instância |
| `NETLOGIC_SCANS_DIR` | _(padrão)_ | Diretório de armazenamento de varreduras |
| `NETLOGIC_SIEM_ENDPOINT` | _(vazio)_ | URL de envio de logs de auditoria |
| `NETLOGIC_WAPPALYZER_DATA` | _(integrado)_ | Caminho das impressões digitais do Wappalyzer |
### Agente
| Variável | Padrão | Descrição |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | URL base do controlador |
| `NETLOGIC_API_KEY` | _(não definido)_ | Chave da API para registro |
---
## Arquitetura de Segurança
### Pilha de middleware (ordem aplicada)
1. **AuditMiddleware** — Correlação `X-Request-ID`, log de auditoria JSON estruturado, envio para SIEM
2. **RequestSizeLimitMiddleware** — Limite de corpo de 10 MB (proteção contra DoS)
3. **LicenseMiddleware** — Bloqueia todas as rotas `/v1/` quando sem licença (retorna 402)
4. **SecurityHeadersMiddleware** — HSTS (1 ano), CSP (diferenciado para HTML vs API), X-Frame-Options, X-Content-Type-Options, Permissions-Policy, Referrer-Policy
5. **OriginCheckMiddleware** — Validação de Origin em POST/PUT/DELETE (defesa em profundidade contra CSRF)
6. **CORSMiddleware** — Restritivo: sem curinga, apenas origens específicas
### Autenticação
- **Chaves de API**: SHA-256 com hash em repouso; texto simples apenas em `create()` e no corpo da requisição durante `verify()`
- **JWT**: HS256 com stdlib (`hashlib`+`hmac`+`base64`), campo `alg` fixado antes da verificação (impede `alg=none`), fallback aleatório efêmero para desenvolvimento
- **OIDC**: Clerk/Auth0/WorkOS — RS256 + JWKS, provisionamento automático de usuários e organizações no primeiro login
- **Tokens de agente**: SHA-256 com hash no registro, comparação em tempo constante, expiração em 7 dias
### Limitação de taxa
Janela deslizante em memória. Por endpoint, por escopo (IP, org_id, agent_id). Bloqueio de IP após 5 falhas de troca de token em 10 minutos (bloqueio de 1 hora).
### Proteção de dados
- Chaves de API LLM: criptografadas com Fernet em repouso (AES-128-CBC + HMAC-SHA256). Falha-fechada em produção: requer `NETLOGIC_SECRETS_KEY`
- Multitenância: todos os dados no escopo do `org_id`; pesquisa entre organizações retorna 404 (e não 403)
- Path traversal: todos os caminhos de armazenamento validados, separadores e `..` rejeitados
---
## CI / Testes```bash
pip install -r requirements-dev.txt
python -m pytest
Pipeline de CI (.github/workflows/ci.yml) — 5 jobs:
pip-auditnpm ci + npm run buildO NetLogic é destinado apenas a avaliações de segurança autorizadas, testes de penetração e administração de rede. Escanear ou sondar hosts sem permissão explícita por escrito é ilegal na maioria das jurisdições. O autor não assume nenhuma responsabilidade pelo uso não autorizado.
MIT © 2026 Dmitry Flynn — Veja LICENSE.txt
| Mecanismo de Verificação | Re-verificação de CVE orientada por IA: projeta planos de sonda HTTP bruta a partir do contexto CVE, executa via sockets stdlib |
| Orquestração Multi-Host | Pipeline de varredura completo por host → contexto entre hosts e matriz de alcançabilidade → descoberta de cadeia de ataque |
| Diretores de Sensores de IA | LLM decide quais sensores priorizar com base em portas abertas, stack de tecnologia e CVEs |
| SSH Autenticado | Subprocesso ssh com credenciais lê versões reais de pacotes instalados (60+ mapeamentos de produto) |
| Enumeração de Serviços | Extração de atributos em nível de protocolo (KEX SSH, SMBv1, NLA RDP, comunidade SNMP, estado de autenticação HTTP) |
| Mapeador de Topologia | DNS reverso, IPv6, traceroute, ASN/org/país via ip-api.com |
| Sonda de Acessibilidade | Matriz de movimento lateral pós-comprometimento a partir de adjacência de sub-rede |
| Sonda de Rede | Varredura ativa de sub-rede (/24 vizinhos privados) com descoberta em duas fases (varredura de atividade → varredura completa de portas) |
| Diff de Varredura | Mudança ao longo do tempo: difere a varredura atual do relatório JSON anterior mais recente por alvo |
| Gerenciamento de Licenças | Sistema de licença comercial com ativação por chave (stub para Stripe/Paddle/Lemon Squeezy) |
| Configuração de IA por Org | Cada organização armazena suas próprias credenciais de LLM criptografadas em repouso via Fernet |
| OIDC / Clerk | Logins humanos via JWTs de sessão emitidos pelo Clerk verificados contra JWKS público com provisionamento automático |
| PostgreSQL | Persistência multi-inquilino completa com migrações aplicadas automaticamente (trabalhos de varredura, configurações de org, estado de raciocínio, auditoria) |
| Benchmark de Fusão | Benchmark offline contra cassetes HTTP gravadas; métricas de precisão/recall/recall crítico/redução de FP |
netlogic <target> [flags]| Varredura única no terminal (sem servidor), imprime/escreve o relatório. |
| Formato | Exemplo | Modo |
|---|
| Hostname | example.com | Varredura de host único |
| IPv4 | 10.0.0.5 | Varredura de host único |
| CIDR | 192.168.1.0/24 | Varredura CIDR (apenas scanner, sem fusão) |
| Separado por vírgula | target1,target2 | Orquestração multi-host (contexto entre hosts) |
GoalPlanner produz planos de investigaçãoReasoningValidator → ProvenanceBuilder regista arestas → estado persistido| Camada | Classe | O que rastreia |
|---|
| WorldModel | WorldModel | EvidenceGraph, observações, crenças, hosts, tecnologia, acessibilidade |
| InvestigationState | InvestigationState | Objetivos (DAG), hipóteses, contradições, becos sem saída, persona atual |
| ExecutionState | ExecutionState | Orçamento, probe_history, proveniência, investigation_plans, AI transcript |
| LearnedPatterns | LearnedPatterns | Heurísticas de múltiplas varreduras + playbooks |
| Componente | Ficheiro | Descrição |
|---|
| EvidenceGraph | evidence_graph.py | Grafo de entidades temporais deduplicado (observações endereçadas por conteúdo via SHA-256) |
| Hypothesis engine | hypothesis.py | Candidatos concorrentes com probabilidades, entropia, ganho de informação, resolução posterior |
| ConfidenceEngine | confidence.py | Noisy-OR sobre fontes distintas; apenas versão limitada a 0.60; KEV/sonda fixado em 0.97 |
| ProvenanceBuilder | provenance.py | Arestas Observação→Inferência→Hipótese, endereçadas por hash de conteúdo |
| Scheduler | scheduler.py | Seleção de ação por ganho de informação com explore_reserve (10%) |
| StrategyManager | strategy.py | Meta-raciocínio: seleção de persona, modo explorar/explorar, deteção de platô |
| ActionGate | action_gate.py | Defesa em profundidade: níveis de risco (READ_ONLY < SAFE_ACTIVE < INTRUSIVE < EXPLOIT), máximo do núcleo é SAFE_ACTIVE |
| InferenceEngine | inference.py | Regras determinísticas de rules/*.json, nunca escreve confiança |
| NovelInferenceEngine | novel_inference.py | Regras para cache_poisoning, request_smuggling, auth_bypass etc. |
| ExecutionKernel | execution_kernel.py | Valida + executa + rastreia sondas (escopo → somente leitura → orçamento → dedup → profundidade) |
| Playbook system | playbooks.py | Playbooks YAML com condições de gatilho e modelos de intenção |
| Change detection | change_detection.py | Fase 7: diffs observações imutáveis (não estado), produz ScanDelta de DeltaEvents |
| Active validation | active_validation.py | Fase 8b: sondas SAFE_ACTIVE não destrutivas através do ActionGate |
| Ficheiro | Componente |
|---|
coordinator.py | AICoordinator — orquestração de pipeline em estágios |
proposals.py | Envelope Proposal tipado com payload específico do tipo, proveniência, economia |
normalize.py | ProposalNormalizer — gate de validação total |
rank.py | ProposalRanker — score = raw_score × prob_correct × reputation_weight |
meta_reasoner.py | Poda determinística (deteção de loop, redução de incerteza) |
verifier.py | 4 estágios: Sintaxe → Semântica → Evidência → Segurança |
store.py | ProposalStore — ledger de ciclo de vida |
transcript.py | InvestigationTranscript — gravação de cadeia causal |
evaluation.py | Arnês de avaliação determinística baseado em cassete |
reputation.py | AgentReputation — rastreia taxa de aceitação/rejeição por agente |
agents/hypothesis_generator.py | C1 — propõe explicações concorrentes + hipóteses de novas vulnerabilidades |
agents/counterfactual.py | C11 — propõe objetivos de refutação |
agents/investigation_designer.py | C2 — concebe planos de recolha de evidências |
| Componente | Ficheiro | Descrição |
|---|
DeepCoordinator | coordinator.py | Orquestra todo o pipeline profundo: plano de sensor IA → ScoutAgent → ProbeAgent por serviço → enumeração de serviços → Nuclei → verificador → takeover → sonda de sub-rede → topologia → auth → diff → acessibilidade |
ScoutAgent | scout_agent.py | Reconhecimento passivo: TLS, cabeçalhos, stack, DNS, OSINT |
ProbeAgent | probe_agent.py | Visita um serviço com contexto isolado de CVE/tecnologia — executa sondas + verificador |
ExploitChain | chain.py | Planeamento de caminho de ataque BFS sobre vereditos confirmados por fusão, geração de PoC |
Sandbox | sandbox.py | Subprocesso restrito para validação de PoC (diretório temporário, timeout, limpeza) |
Mission / AgentReport | models.py | Modelos de dados para diretivas e resultados de agente |
| Componente | Ficheiro | Descrição |
|---|
run_verifier() | engine.py | Orquestra: gerar planos → executar → construir Sinais confirmados por sonda |
generate_plans_for_cves() | planner.py | Por CVE (CVSS ≥ 7.0): verifica ~20 planos embutidos → IA gera plano HTTP bruto (método, caminho, cabeçalhos, corpo, status/corpo esperados) |
run_test() | runner.py | Execução de socket TCP/TLS bruto, parsing manual de HTTP/1.0, correspondência de padrão de corpo esperado |
| Diretor | Ficheiro | O que decide |
|---|
SensorDirector | sensor_director.py | Quais sensores ativar/desativar e com que prioridade, com base em portas abertas + stack tecnológica + CVEs |
ReprobeDirector | reprobe.py | Se descobertas potenciais podem ser resolvidas com sondas HTTP direcionadas |
NucleiSelector | nuclei_selector.py | Quais tags de template do Nuclei incluir/excluir (reduz execuções irrelevantes) |
SubnetDirector | subnet_director.py | Quais hosts adjacentes sondar, quais portas, a que profundidade (skip/quick/standard/deep) |