NetLogic es un kit de herramientas avanzado de análisis de red y ciberseguridad para la inspección de tráfico, análisis de paquetes y detección de amenazas.
Mapeador de Superficie de Ataque Nativo en la Nube y Correlacionador de Vulnerabilidades — v3.0
NetLogic es una plataforma de seguridad de red que combina escaneo activo de puertos, correlación CVE (API NVD en vivo), análisis SSL/TLS, auditoría de seguridad HTTP, evaluación de seguridad DNS/correo electrónico, detección de toma de control de subdominios, OSINT pasivo, sondeo activo de vulnerabilidades, un motor de razonamiento basado en IA, descubrimiento de cadenas de ataque entre hosts y arquitectura de agente de sonda profunda, presentada como una aplicación web (panel React + FastAPI). El motor de escaneo principal es Python 3.9+ puro con la biblioteca estándar y cero dependencias de terceros.
| Módulo | Descripción |
|---|---|
| Port Scanner | Escaneo TCP connect con 43/58 puertos, 22 sondas de servicio, captura de banners |
| CVE Correlator | Correlación CVE con API NVD v2.0 en vivo + enriquecimiento EPSS vía FIRST.org |
| TLS Analyzer | Versiones de protocolo, cifrados débiles, POODLE/BEAST/CRIME/DROWN, caducidad de certificados |
| HTTP Header Audit | HSTS, CSP, X-Frame-Options, CORS, indicadores de cookies; puntuación 0–100 |
| Stack Fingerprint | Detección de CMS, framework, proveedor cloud, CDN, WAF a partir de banner/cabecera/cuerpo |
| DNS Security | SPF, DKIM, DMARC, DNSSEC, transferencia de zona, puntuación de suplantación |
| Passive OSINT | Registros de transparencia de certificados, DNS DoH, consulta ASN — sin contacto directo con el objetivo |
| Service Prober | Sondas no autenticadas Redis/Mongo/ES/Docker/K8s/etcd, 33 rutas administrativas |
| Takeover Detector | Descubrimiento de subdominios por CT log + 25 huellas CNAME de proveedores cloud |
| Nuclei Integration | Envoltorio para más de 13k plantillas comunitarias (CVE, tecnología, exposición, mala configuración) — licencia MIT |
| Fusion Pipeline | Compuerta de señales multisensor → acuerdo determinista → adjudicación de IA → gráfico de ataque → informe de 6 secciones |
| Web Fingerprint | Hash de favicon (mmh3 compatible con Shodan), secretos en JS, marcadores de versión, archivos expuestos, detección de páginas predeterminadas |
| AI Analysis | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — transmisión SSE de tokens |
| Reasoning Engine | Bucle adaptativo de observar→razonar→actuar con EvidenceGraph, motor de hipótesis, decaimiento de confianza, procedencia, planificador, playbooks, detección de cambios, validación activa |
| Deep Probe | Arquitectura de agente por servicio: ScoutAgent (recon), ProbeAgent (verificaciones CVE específicas), Coordinador, Sandbox |
| AI Investigation Agent | Bucle estilo ReAct: después de los sensores base, la IA impulsa una superficie de herramientas seleccionadas, con alcance acotado y auditadas (~35 herramientas) para verificar pistas y construir cadenas de ataque — con herramientas agresivas optativas (sondas de caída, prueba libre, exploit libre) para objetivos autorizados |
Hay exactamente dos formas de ejecutar NetLogic:
| Modo | Comando | Qué hace |
|---|---|---|
| Web app | netlogic --gui | Inicia FastAPI + sirve la SPA React + agente de escaneo en proceso, genera automáticamente secretos y abre el panel en tu navegador. Esta es la única forma de ejecutar la aplicación web. |
| CLI |
La superficie del producto es la aplicación web (panel React + FastAPI). El motor de escaneo en src/ impulsa los trabajos iniciados desde la interfaz de usuario.
pip install -r requirements-api.txt pip install -e .
netlogic --gui
netlogic scanme.nmap.org --full
## Referencia de CLI```
netlogic [target] [flags]
El punto de entrada es api.cli:main (definido en pyproject.toml), que delega en netlogic.py:main(). Toda la lógica de escaneo está en 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
### Selección de puertos```
# 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
### Proveedores de IA compatibles
| Proveedor | Modelo predeterminado | 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 por el usuario | OpenAI |
### Motor de razonamiento```
# 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
Después de que los sensores de referencia se ejecuten, un agente opcional estilo ReAct permite a la IA manejar sus propias herramientas para verificar pistas y construir cadenas de ataque, en lugar de dejar las coincidencias de CVE de versiones/banners como pistas no verificadas. La IA propone llamadas a herramientas; un entorno de ejecución determinista las ejecuta — cada herramienta está restringida por alcance al objetivo, sanitizada y registrada como una observación. La IA nunca toca la red directamente.```
netlogic example.com --ai --ai-agent
netlogic example.com --ai --agent-depth --agent-max-steps 24 --agent-max-requests 80
El agente tiene ~35 herramientas de solo lectura/activas seguras por defecto: sondas HTTP/TLS/DNS, `dir_enum`, `confirm_tech`,
`timing_probe`, `cve_probe` (verificaciones de marcadores de CVE conocidos y seleccionados), `sqli_boolean`/`sqli_time`, `ssrf_canary`,
`idor_diff`, `file_disclosure`, `browser_get` (sin cabeza, supera desafíos JS), además del registro de HackerOne
(`record_poc`, `severity_suggest`, `submit_readiness`).
**Herramientas agresivas opcionales** — desactivadas por defecto, **solo para objetivos AUTORIZADOS / dentro del alcance propios** (nunca en un
escaneo público o de desconocidos). Cada una requiere `--ai-agent`:
| Banderín | Herramienta | Qué desbloquea | Restricciones mantenidas |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | Verificaciones seleccionadas de CVE de caídas/DoS (http.sys, MS15-034) que PUEDEN bloquear el host | Catálogo fijo de 3 CVEs — no libre |
| `--allow-freeform-proof` | `http_proof` | Nivel C: GET/HEAD/OPTIONS libres (+ POST en rutas tipo búsqueda/inicio de sesión/graphql) | Patrones destructivos + PUT/PATCH/DELETE bloqueados; comprobación, no mutación |
| `--allow-exploit-requests` | `exploit_request` | Nivel E: **cualquier método** (incl. PUT/PATCH/DELETE) + ruta/encabezados/cuerpo arbitrarios contra el objetivo | Delimitado por alcance; cierre seguro ante patrones masivamente destructivos (DROP/TRUNCATE TABLE, `rm -rf`) e inyección de encabezados CR/LF; cada solicitud auditada |
El ActionGate determinista mantiene el núcleo en `safe_active`; estos tres banderines son las autorizaciones explícitas y auditadas
por encima de él. Ejemplo (caja de laboratorio propia + 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
### Gestión de caché de NVD```
netlogic --cache-stats
netlogic example.com --nvd-key YOUR_NVD_KEY
netlogic --version # Show version and exit netlogic --gui # Start web dashboard
---
## Pipeline de Fusión
El pipeline de fusión es un embudo **sensores → compuerta → adjudicación de IA → síntesis** que reemplaza las llamadas monolíticas de IA con una compuerta de precisión. Reside en `src/fusion/` (12 archivos).
### Esquema de señal (`src/fusion/signals.py`)
Contrato de datos que portan evidencia. Cada sensor emite objetos `Signal`:
- `source`: `probe`/`banner`/`nuclei`/`wappalyzer`/`nvd`/`osv`/`tls`/`dns`
- `kind`: `vuln`/`tech`/`exposure`/`misconfig`/`service`
- `claim`: sujeto normalizado (ej. `"CVE-2021-44228"`, `"nginx"`)
- `host`, `port`, `service`, `evidence` (limitado a 600 caracteres)
- `confidence` (0..1), `reliability` (`high`/`medium`/`low`)
- `kev`, `epss` (0..1), `cvss` (0..10), `exploit_available`, `version_matched`, `probe_confirmed`
- `exposure` dict (accesibilidad, WAF, punto de vista)
- `observed_data` (bytes brutos enviados a la IA — NO nombres de sensores ni severidades para evitar sesgo de etiquetas)
- `ai_view()` elimina metadatos del sensor, devuelve solo hechos observados
### Compuerta (`src/fusion/gate.py`)
Acuerdo determinista — dado `list[Signal]`, agrupa por sujeto y devuelve `list[Verdict]`:
| Condición | Verdicto |
|---|---|
| Listado en KEV O confirmado por sonda O crítico+exploit/EPSS alto | **Confirmado** (fijado — no descartable) |
| ≥2 fuentes independientes concuerdan, ≥1 de alta confiabilidad | **Confirmado** (a menos que todas coincidan por versión → gris) |
| Solo baja confiabilidad, impacto bajo/medio, sin corroboración | **Descartado** |
| Todo lo demás | **Gris** (cuesta un token de IA) |
### Adjudicación de IA (`src/fusion/adjudicator.py`)
Solo toca la banda gris. Restricciones de seguridad aplicadas en código (no en el prompt):
- Los elementos grises de impacto alto/crítico NUNCA pueden ser descartados — como máximo degradados a `potential`
- Las coincidencias solo por versión se limitan a `potential` (las distribuciones retroportan sin cambios de versión)
- La IA también descubre nuevos hallazgos a partir del contexto completo del host
- Fallo seguro: una interrupción de la IA deja la banda gris como `potential` — sin pérdida silenciosa de datos
### Síntesis (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → grafo de accesibilidad determinista a partir de hallazgos CONFIRMADOS.
`full_synthesize(...)` → informe de IA de 6 secciones:
1. Resumen Ejecutivo
2. Hallazgos Principales (tabla)
3. Cadenas de Ataque (basadas en grafos, la LLM narra aristas reales)
4. Más Allá de los CVE Conocidos
5. Falsos Positivos y Ruido
6. Remediación
### Sensores
| Sensor | Archivo | Lo que produce |
|---|---|---|
| Puente del motor | `engine_bridge.py` | Convierte artefactos de escaneo → Signals desde NVD, sondas, pila, Nuclei, verificador |
| Wappalyzer | `sensors/wappalyzer.py` | Huellas digitales compatibles con Wappalyzer sin dependencias de respuestas HTTP |
| Nuclei | `sensors/nuclei.py` | Ejecuta plantillas YAML contra respuestas (subconjunto de sintaxis de Nuclei) |
| Cassette | `cassette.py` | Grabación/reproducción desde cassettes HTTP (datos de referencia fuera de línea) |
### Multi-host (`src/fusion/cross_host.py`)
Agrupación posterior a la adjudicación de veredictos entre hosts por servicio+versión compartidos para la narración de cadenas de ataque de múltiples saltos en la síntesis.
### Flujo del Pipeline```
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
Ubicado en src/reasoning/ (~58 archivos). Bucle de múltiples fases, con compuerta de seguridad, observar→razonar→actuar. Habilitado con --reason.
src/reasoning/director.py — ReconDirector.run())StrategyManager selecciona persona → Scheduler elige acción → SensorStep ejecuta → EvidenceGraph pliega observaciones → ConfidenceEngine actualiza creenciasProposal tipados → AICoordinator normaliza/clasifica/verifica → Propuestas aceptadas siembran estado → Compiler → ExecutionPlanner → ExecutionKernel ejecuta sondas → InferenceEngine resuelveCrossHostGraph, genera instancias hijas de HostReasonersrc/reasoning/state.py)src/reasoning/ai/)Pipeline: Generar → Normalizar → Clasificar → (Poda del MetaReasoner) → Verificar → Almacenar
Ubicado en src/deep/ (7 archivos). Usado con --deep-probe. Arquitectura de agente por servicio para ejecución de sondas aisladas por contexto.
Flujo de DeepCoordinator.run():
_build_sensor_plan mediante sensor_director)ScoutAgent para reconocimiento pasivoProbeAgent por servicio (cada una con contexto aislado de CVE/tecnología)Ubicado en src/verifier/ (3 archivos). Confirmación de CVE impulsada por IA con sondas dirigidas.
La re-verificación de Fase 2 (reverify_with_context) proporciona contexto completo del host para refinar pruebas fallidas.
Ubicado en src/directors/ (4 archivos). Selección de parámetros de escaneo impulsada por LLM.
Ubicado en src/orchestrator.py. Activado por objetivos separados por comas. Ejecuta run_scan() por host, agrega resultados, construye contexto entre hosts a partir de veredictos de fusión combinados. Los grupos entre hosts detectan servicios/versiones compartidos entre hosts para narración de cadena de ataque de múltiples saltos.
src/nvd_lookup.py)--nvd-key)src/epss.py): API de FIRST.org en lotes de 100 IDs de CVE, caché en disco de 24h en ~/.netlogic/epss_cache.json, fallo suave a 0.0src/external/nuclei_runner.py envuelve el binario de Nuclei (licencia MIT). Opcional — degrada elegantemente cuando no se encuentra el binario. Los resultados se alimentan en el pipeline de fusión como señales tipadas (las etiquetas de severidad se eliminan para prevenir sesgo del LLM).```
scoop install nuclei # Windows brew install nuclei # macOS go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Linux
---
## Benchmark de Fusion
`src/fusion/benchmark.py` — medición offline contra casetes HTTP etiquetados (`benchmark/*.json` y `src/fusion/data/`). Métricas:
| Métrica | Umbral de puerta |
|---|---|
| Reducción de FP | ≥ 80% |
| Recuperación crítica | = 100% |
Dos modos:
- **Oráculo** (`--benchmark`): cota superior de IA perfecta — mide únicamente el mecanismo determinista
- **Modelo real** (`--benchmark --benchmark-ai`): medido con el LLM configurado
---
## Arquitectura```
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 las rutas bajo el prefijo /v1/. Autenticación:
POST /v1/auth/token → HS256 JWT (por defecto 1h de expiración)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]
### Trabajos```
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
### Licencia / Configuración```
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
---
## Variables de entorno
### Controlador
| Variable | Predeterminado | Descripción |
|---|---|---|
| `NETLOGIC_ENV` | _(sin establecer)_ | `production`/`prod` = validación de secreto al inicio |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | Secreto de firma HS256, ≥32 caracteres |
| `NETLOGIC_JWT_EXPIRY` | `3600` | Duración de JWT en segundos |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | Credencial de administrador, ≥32 caracteres en producción |
| `NETLOGIC_API_KEYS` | _(vacío)_ | Claves iniciales: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(vacío)_ | Orígenes permitidos (CORS deshabilitado si está vacío) |
| `NETLOGIC_PORT` | `8000` | Puerto de enlace |
| `NETLOGIC_HOST` | `0.0.0.0` | Dirección de enlace |
| `NETLOGIC_NO_BROWSER` | _(sin establecer)_ | `1` deshabilita apertura automática |
| `NETLOGIC_OIDC_ISSUER` | _(sin establecer)_ | URL de la API de Frontend de Clerk → inicio de sesión OIDC |
| `NETLOGIC_OIDC_AUDIENCE` | _(sin establecer)_ | Audiencia OIDC |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(sin establecer)_ | org_id de respaldo para usuarios OIDC |
| `NETLOGIC_DATABASE_URL` | _(sin establecer)_ | Cadena de conexión PostgreSQL |
| `NETLOGIC_SECRETS_KEY` | _(sin establecer)_ | Clave Fernet para credenciales en reposo |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | Duración del token de agente (7 días) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | Máximo de tareas en cola por agente |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | Máximo de agentes registrados |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | Proveedor de IA predeterminado |
| `NETLOGIC_AI_API_KEY` | _(vacío)_ | Clave de IA predeterminada |
| `NETLOGIC_AI_MODEL` | predeterminado del proveedor | Modelo predeterminado |
| `NETLOGIC_AI_BASE_URL` | predeterminado del proveedor | URL base personalizada |
| `NETLOGIC_NVD_KEY` | _(vacío)_ | Clave API de NVD |
| `NETLOGIC_VALID_LICENSES` | _(vacío)_ | Anulaciones de licencia para desarrollo/pruebas |
| `NETLOGIC_LICENSE_KEY` | _(vacío)_ | Clave de licencia de la instancia |
| `NETLOGIC_SCANS_DIR` | _(predeterminado)_ | Directorio de almacenamiento de escaneos |
| `NETLOGIC_SIEM_ENDPOINT` | _(vacío)_ | URL de envío de registros de auditoría |
| `NETLOGIC_WAPPALYZER_DATA` | _(integrado)_ | Ruta de huellas digitales de Wappalyzer |
### Agente
| Variable | Predeterminado | Descripción |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | URL base del controlador |
| `NETLOGIC_API_KEY` | _(sin establecer)_ | Clave API para registro |
---
## Arquitectura de seguridad
### Pila de middleware (orden aplicado)
1. **AuditMiddleware** — correlación `X-Request-ID`, registro de auditoría JSON estructurado, envío a SIEM
2. **RequestSizeLimitMiddleware** — límite de cuerpo de 10 MB (protección DoS)
3. **LicenseMiddleware** — bloquea todas las rutas `/v1/` cuando no hay licencia (devuelve 402)
4. **SecurityHeadersMiddleware** — HSTS (1 año), CSP (diferenciado HTML vs API), X-Frame-Options, X-Content-Type-Options, Permissions-Policy, Referrer-Policy
5. **OriginCheckMiddleware** — validación de Origen en POST/PUT/DELETE (defensa en profundidad contra CSRF)
6. **CORSMiddleware** — restrictivo: sin comodín, solo orígenes específicos
### Autenticación
- **Claves API**: SHA-256 hasheadas en reposo; texto plano solo en `create()` y en el cuerpo de la solicitud durante `verify()`
- **JWT**: HS256 con librería estándar (`hashlib`+`hmac`+`base64`), campo `alg` fijado antes de la verificación (previene alg=none), respaldo aleatorio efímero para desarrollo
- **OIDC**: Clerk/Auth0/WorkOS — RS256 + JWKS, aprovisiona automáticamente usuarios + organizaciones en el primer inicio de sesión
- **Tokens de agente**: SHA-256 hasheados en el registro, comparación en tiempo constante, caducidad de 7 días
### Limitación de tasa
Ventana deslizante en memoria. Por endpoint, por ámbito (IP, org_id, agent_id). Baneo de IP después de 5 intercambios de token fallidos en 10 minutos (baneo de 1 hora).
### Protección de datos
- Claves API de LLM: cifradas con Fernet en reposo (AES-128-CBC + HMAC-SHA256). Fallo-cerrado en producción: requiere `NETLOGIC_SECRETS_KEY`
- Multi-inquilino: todos los datos limitados a `org_id`; la búsqueda entre organizaciones devuelve 404 (no 403)
- Path traversal: todas las rutas de almacenamiento validadas, separadores y `..` rechazados
---
## CI / Pruebas```bash
pip install -r requirements-dev.txt
python -m pytest
Pipeline de CI (.github/workflows/ci.yml) — 5 trabajos:
pip-auditnpm ci + npm run buildNetLogic está destinado únicamente para evaluaciones de seguridad autorizadas, pruebas de penetración y administración de redes. Escanear o sondear hosts sin permiso explícito por escrito es ilegal en la mayoría de las jurisdicciones. El autor no asume ninguna responsabilidad por el uso no autorizado.
MIT © 2026 Dmitry Flynn — Consulte LICENSE.txt
| Verifier Engine | Re-verificación de CVE impulsada por IA: diseña planes de sonda HTTP sin procesar a partir del contexto CVE, ejecuta a través de sockets de la biblioteca estándar |
| Multi-Host Orchestration | Tubería de escaneo completo por host → contexto entre hosts y matriz de alcanzabilidad → descubrimiento de cadenas de ataque |
| AI Sensor Directors | La LLM decide qué sensores priorizar según puertos abiertos, pila tecnológica y CVEs |
| Authenticated SSH | Subproceso ssh con credenciales lee versiones reales de paquetes instalados (más de 60 asignaciones de productos) |
| Service Enum | Extracción de atributos a nivel de protocolo (SSH KEX, SMBv1, RDP NLA, comunidad SNMP, estado de autenticación HTTP) |
| Topology Mapper | DNS inverso, IPv6, traceroute, ASN/org/país vía ip-api.com |
| Reachability Prober | Matriz de movimiento lateral posterior a la compromisión desde la adyacencia de subred |
| Network Prober | Barrido activo de subred (/24 vecinos privados) con descubrimiento en dos fases (barrido en vivo → escaneo completo de puertos) |
| Scan Diff | Cambio en el tiempo: diferencias del escaneo actual con respecto al informe JSON anterior más reciente por objetivo |
| License Management | Sistema de licencias comerciales con activación por clave (stub para Stripe/Paddle/Lemon Squeezy) |
| Per-Org AI Config | Cada organización almacena sus propias credenciales LLM cifradas en reposo mediante Fernet |
| OIDC / Clerk | Inicios de sesión humanos mediante JWTs de sesión emitidos por Clerk verificados contra JWKS público con aprovisionamiento automático |
| PostgreSQL | Persistencia multi-tenant completa con migraciones aplicadas automáticamente (trabajos de escaneo, configuración de organización, estado de razonamiento, auditoría) |
| Fusion Benchmark | Benchmark fuera de línea contra cassettes HTTP grabados; métricas de precisión/recuperación/recuperación crítica/reducción de FP |
netlogic <target> [flags]| Escaneo único en terminal (sin servidor), imprime/escribe el informe. |
| Formato | Ejemplo | Modo |
|---|
| Nombre de host | example.com | Escaneo de un solo host |
| IPv4 | 10.0.0.5 | Escaneo de un solo host |
| CIDR | 192.168.1.0/24 | Barrido CIDR (solo escáner, sin fusión) |
| Separado por comas | target1,target2 | Orquestación multi-host (contexto entre hosts) |
GoalPlanner produce planes de investigaciónReasoningValidator auditoría de integridad → ProvenanceBuilder registra aristas → estado persistido| Capa | Clase | Lo que rastrea |
|---|
| WorldModel | WorldModel | EvidenceGraph, observaciones, creencias, hosts, tecnología, alcanzabilidad |
| InvestigationState | InvestigationState | Objetivos (DAG), hipótesis, contradicciones, puntos muertos, persona actual |
| ExecutionState | ExecutionState | Presupuesto, probe_history, procedencia, investigation_plans, transcripción de IA |
| LearnedPatterns | LearnedPatterns | Heurísticas entre escaneos + playbooks |
| Componente | Archivo | Descripción |
|---|
| EvidenceGraph | evidence_graph.py | Grafo de entidades temporales deduplicado (observaciones direccionadas por contenido mediante SHA-256) |
| Motor de hipótesis | hypothesis.py | Candidatos en competencia con verosimilitudes, entropía, ganancia de información, resolución posterior |
| ConfidenceEngine | confidence.py | Noisy-OR sobre fuentes distintas; solo versión limitado a 0.60; KEV/sonda fijado en 0.97 |
| ProvenanceBuilder | provenance.py | Aristas Observación→Inferencia→Hipótesis, direccionadas por hash de contenido |
| Scheduler | scheduler.py | Selección de acciones basada en ganancia de información con explore_reserve (10%) |
| StrategyManager | strategy.py | Meta-razonamiento: selección de persona, modo explorar/explotar, detección de meseta |
| ActionGate | action_gate.py | Defensa en profundidad: niveles de riesgo (READ_ONLY < SAFE_ACTIVE < INTRUSIVE < EXPLOIT), máximo del núcleo es SAFE_ACTIVE |
| InferenceEngine | inference.py | Reglas deterministas de rules/*.json, nunca escribe confianza |
| NovelInferenceEngine | novel_inference.py | Reglas para cache_poisoning, request_smuggling, auth_bypass etc. |
| ExecutionKernel | execution_kernel.py | Valida + ejecuta + traza sondas (scope → read-only → budget → dedup → depth) |
| Sistema de playbooks | playbooks.py | Playbooks YAML con condiciones de activación y plantillas de intención |
| Detección de cambios | change_detection.py | Fase 7: diferencia observaciones inmutables (no estado), produce ScanDelta de DeltaEvents |
| Validación activa | active_validation.py | Fase 8b: sondas SAFE_ACTIVE no destructivas a través de ActionGate |
| Archivo | Componente |
|---|
coordinator.py | AICoordinator — orquestación de pipeline por etapas |
proposals.py | Sobre Proposal tipado con carga útil específica del tipo, procedencia, economía |
normalize.py | ProposalNormalizer — puerta de validación total |
rank.py | ProposalRanker — puntuación = raw_score × prob_correct × reputation_weight |
meta_reasoner.py | Poda determinista (detección de bucles, reducción de incertidumbre) |
verifier.py | 4 etapas: Sintaxis → Semántica → Evidencia → Seguridad |
store.py | ProposalStore — registro de ciclo de vida |
transcript.py | InvestigationTranscript — grabación de cadena causal |
evaluation.py | Entorno de evaluación determinista basado en cassette |
reputation.py | AgentReputation — rastrea tasa de aceptación/rechazo por agente |
agents/hypothesis_generator.py | C1 — propone explicaciones competidoras + hipótesis de vulnerabilidades novedosas |
agents/counterfactual.py | C11 — propone objetivos de refutación |
agents/investigation_designer.py | C2 — diseña planes de recolección de evidencia |
| Componente | Archivo | Descripción |
|---|
DeepCoordinator | coordinator.py | Orquesta el pipeline completo de sonda profunda: plan de sensores IA → ScoutAgent → ProbeAgent por servicio → enumeración de servicios → Nuclei → verificador → takeover → sonda de subred → topología → auth → diff → alcanzabilidad |
ScoutAgent | scout_agent.py | Reconocimiento pasivo: TLS, cabeceras, pila, DNS, OSINT |
ProbeAgent | probe_agent.py | Apunta a un servicio con contexto aislado de CVE/tecnología — ejecuta sondas + verificador |
ExploitChain | chain.py | Planificación de ruta de ataque BFS sobre veredictos confirmados por fusión, generación de PoC |
Sandbox | sandbox.py | Subproceso restringido para validación de PoC (directorio temporal, tiempo de espera, limpieza) |
Misión / AgentReport | models.py | Modelos de datos para directivas y resultados de agentes |
| Componente | Archivo | Descripción |
|---|
run_verifier() | engine.py | Orquesta: generar planes → ejecutar → construir Señales confirmadas por sonda |
generate_plans_for_cves() | planner.py | Por CVE (CVSS ≥ 7.0): verifica ~20 planes incorporados → IA genera plan HTTP sin formato (método, ruta, cabeceras, cuerpo, estado/cuerpo esperado) |
run_test() | runner.py | Ejecución de socket TCP/TLS sin procesar, análisis manual HTTP/1.0, coincidencia de patrón de cuerpo esperado |
| Director | Archivo | Lo que decide |
|---|
SensorDirector | sensor_director.py | Qué sensores habilitar/deshabilitar y con qué prioridad, basado en puertos abiertos + pila tecnológica + CVEs |
ReprobeDirector | reprobe.py | Si los hallazgos potenciales pueden resolverse con sondas HTTP dirigidas |
NucleiSelector | nuclei_selector.py | Qué etiquetas de plantillas Nuclei incluir/excluir (reduce ejecuciones irrelevantes) |
SubnetDirector | subnet_director.py | Qué hosts adyacentes sondear, qué puertos, a qué profundidad (omitir/rápido/estándar/profundo) |