NetLogic è un toolkit avanzato di analisi di rete e cybersecurity per l'ispezione del traffico, l'analisi dei pacchetti e il rilevamento delle minacce
Mapper di Superficie d'Attacco Cloud-Native & Correlatore di Vulnerabilità — v3.0
NetLogic è una piattaforma di sicurezza di rete che combina scansione attiva delle porte, correlazione CVE (tramite API NVD live), analisi SSL/TLS, audit di sicurezza HTTP, valutazione della sicurezza DNS/email, rilevamento di takeover di sottodomini, OSINT passivo, probing attivo delle vulnerabilità, un motore di ragionamento basato su IA, scoperta di catene di attacco cross-host e architettura di agenti di deep probe — presentata come web app (dashboard React + FastAPI). Il motore di scansione principale è puro Python 3.9+ stdlib senza dipendenze di terze parti.
| Modulo | Descrizione |
|---|---|
| Port Scanner | Scansione TCP connect su 43/58 porte, 22 sonde di servizio, cattura banner |
| CVE Correlator | API NVD v2.0 live + arricchimento EPSS tramite FIRST.org |
| TLS Analyzer | Versioni dei protocolli, cifrari deboli, POODLE/BEAST/CRIME/DROWN, scadenza certificati |
| HTTP Header Audit | HSTS, CSP, X-Frame-Options, CORS, flag cookie; punteggio 0–100 |
| Stack Fingerprint | Rilevamento CMS, framework, cloud provider, CDN, WAF da banner/header/corpo |
| DNS Security | SPF, DKIM, DMARC, DNSSEC, zone transfer, punteggio di spoofabilità |
| Passive OSINT | Log di trasparenza dei certificati, DNS DoH, lookup ASN — nessun contatto diretto con il target |
| Service Prober | Sonde non autenticate per Redis/Mongo/ES/Docker/K8s/etcd, 33 percorsi admin |
| Takeover Detector | Scoperta di sottodomini tramite log CT + 25 impronte CNAME di cloud provider |
| Nuclei Integration | Wrapper per oltre 13k template della comunità (CVE, tech, esposizione, misconfig) — licenza MIT |
| Fusion Pipeline | Gate multi-sensore → accordo deterministico → delibera IA → grafo d'attacco → report in 6 sezioni |
| Web Fingerprint | Hash favicon (mmh3 compatibile Shodan), segreti JS, marcatori versione, file esposti, rilevamento lander predefinito |
| AI Analysis | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — streaming SSE tramite token |
| Reasoning Engine | Ciclo adattivo observe→reason→act con EvidenceGraph, motore di ipotesi, decadimento della confidenza, provenienza, scheduler, playbook, rilevamento cambiamenti, validazione attiva |
| Deep Probe | Architettura ad agente per servizio: ScoutAgent (ricognizione), ProbeAgent (verifiche CVE mirate), Coordinatore, Sandbox |
| AI Investigation Agent | Ciclo stile ReAct: dopo i sensori di base, l'IA guida una superficie di strumenti curata, limitata nell'ambito e sottoposta ad audit (~35 strumenti) per verificare indizi e costruire catene d'attacco — con strumenti aggressivi opzionali (crash probe, proof libero, exploit libero) per target autorizzati |
Ci sono esattamente due modi per eseguire NetLogic:
| Modalità | Comando | Cosa fa |
|---|---|---|
| Web app | netlogic --gui | Avvia FastAPI + serve la SPA React + agente di scansione in-process, genera segreti automaticamente e apre la dashboard nel browser. Questo è l'unico modo per eseguire la web app. |
| CLI |
La superficie del prodotto è la web app (dashboard React + FastAPI). Il motore di scansione sotto src/ alimenta i job avviati dall'interfaccia utente.
pip install -r requirements-api.txt pip install -e .
netlogic --gui
netlogic scanme.nmap.org --full
## Riferimento CLI```
netlogic [target] [flags]
The entry point is api.cli:main (defined in pyproject.toml), which delegates to netlogic.py:main(). All scan logic is in 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
### Selezione della porta```
# 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
### Fornitori IA supportati
| Provider | Modello predefinito | Stile 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` | specificato dall'utente | OpenAI |
### Motore di ragionamento```
# 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
Dopo l'esecuzione dei sensori di base, un agente in stile ReAct opzionale consente all'AI di guidare i propri strumenti per verificare le piste e costruire catene di attacco, invece di lasciare gli hit CVE da versioni/banner come piste non verificate. L'AI propone chiamate a strumenti; un runtime deterministico le esegue — ogni strumento è scope-gated rispetto al target, sanificato e registrato come osservazione. L'AI non tocca mai la rete direttamente.```
netlogic example.com --ai --ai-agent
netlogic example.com --ai --agent-depth --agent-max-steps 24 --agent-max-requests 80
L'agente ha circa 35 strumenti di sola lettura/attivi sicuri per impostazione predefinita: probe HTTP/TLS/DNS, `dir_enum`, `confirm_tech`, `timing_probe`, `cve_probe` (controlli di marcatori CVE noti curati), `sqli_boolean`/`sqli_time`, `ssrf_canary`, `idor_diff`, `file_disclosure`, `browser_get` (headless, supera le sfide JS), oltre alla contabilità HackerOne (`record_poc`, `severity_suggest`, `submit_readiness`).
**Strumenti aggressivi opt-in** — disattivati per impostazione predefinita, **solo su target autorizzati/di proprietà in ambito** (mai su scansioni pubbliche o di sconosciuti). Ciascuno richiede `--ai-agent`:
| Flag | Tool | What it unlocks | Rails kept |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | Controlli CVE curati di crash/DoS (http.sys, MS15-034) che POTREBBERO crashare l'host | Fixed 3-CVE catalog — not freeform |
| `--allow-freeform-proof` | `http_proof` | Livello C: GET/HEAD/OPTIONS liberi (+ POST su percorsi tipo search/login/graphql) | Destructive patterns + PUT/PATCH/DELETE blocked; proof, not mutation |
| `--allow-exploit-requests` | `exploit_request` | Livello E: **qualsiasi metodo** (incl. PUT/PATCH/DELETE) + percorso/intestazioni/corpo arbitrari contro il target | Scope-gated; fail-closed on mass-destructive patterns (DROP/TRUNCATE TABLE, `rm -rf`) and CR/LF header injection; every request audited |
Il determinista ActionGate mantiene il core a `safe_active`; queste tre flag sono gli opt-in espliciti e verificati sopra di esso. Esempio (lab box di proprietà + modello locale):```
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
### Gestione della 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
Il fusion pipeline è un imbuto **sensors → gate → AI adjudication → synthesis** che sostituisce le chiamate AI monolitiche con un gate di precisione. Si trova in `src/fusion/` (12 file).
### Schema dei segnali (`src/fusion/signals.py`)
Contratto dati che trasportano evidenze. Ogni sensore emette oggetti `Signal`:
- `source`: `probe`/`banner`/`nuclei`/`wappalyzer`/`nvd`/`osv`/`tls`/`dns`
- `kind`: `vuln`/`tech`/`exposure`/`misconfig`/`service`
- `claim`: soggetto normalizzato (e.g. `"CVE-2021-44228"`, `"nginx"`)
- `host`, `port`, `service`, `evidence` (massimo 600 caratteri)
- `confidence` (0..1), `reliability` (`high`/`medium`/`low`)
- `kev`, `epss` (0..1), `cvss` (0..10), `exploit_available`, `version_matched`, `probe_confirmed`
- `exposure` dict (raggiungibilità, WAF, punto di osservazione)
- `observed_data` (byte grezzi inviati all'AI — NON nomi di sensori o severità per prevenire bias di etichetta)
- `ai_view()` rimuove i metadati del sensore, restituisce solo i fatti osservati
### Gate (`src/fusion/gate.py`)
Accordo deterministico — dati `list[Signal]`, raggruppa per soggetto e restituisce `list[Verdict]`:
| Condizione | Verdetto |
|---|---|
| In elenco KEV O confermato da probe O critico+exploit/EPSS alto | **Confermato** (bloccato — non eliminabile) |
| ≥2 fonti indipendenti concordano, ≥1 alta affidabilità | **Confermato** (a meno che non siano tutti version-matched → grigio) |
| Solo a bassa affidabilità, impatto basso/medio, nessuna corroborazione | **Scartato** |
| Tutto il resto | **Grigio** (costa un token AI) |
### Giudizio AI (`src/fusion/adjudicator.py`)
Tocca solo la banda grigia. Vincoli di sicurezza applicati nel codice (non nel prompt):
- Gli elementi grigi alti/critici NON possono MAI essere scartati — al massimo degradati a `potential`
- Le corrispondenze solo versione sono limitate a `potential` (le distribuzioni backportano senza incrementi di versione)
- L'AI scopre anche nuovi risultati dal contesto completo dell'host
- Fail-soft: un'interruzione dell'AI lascia la banda grigia come `potential` — nessuna perdita di dati silenziosa
### Sintesi (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → grafo di raggiungibilità deterministico dai risultati CONFERMATI.
`full_synthesize(...)` → report AI in 6 sezioni:
1. Riepilogo Esecutivo
2. Risultati Chiave (tabella)
3. Catene di Attacco (basate su grafi, LLM narra i collegamenti reali)
4. Oltre le CVE Note
5. Falsi Positivi e Rumore
6. Remediation
### Sensori
| Sensore | File | Cosa produce |
|---|---|---|
| Ponte motore | `engine_bridge.py` | Converte artefatti di scansione → Segnali da NVD, probe, stack, Nuclei, verificatore |
| Wappalyzer | `sensors/wappalyzer.py` | Rilevamento impronte compatibile con Wappalyzer a zero dipendenze delle risposte HTTP |
| Nuclei | `sensors/nuclei.py` | Esegue template YAML sulle risposte (sottoinsieme della sintassi di Nuclei) |
| Cassette | `cassette.py` | Registrazione/riproduzione da cassette HTTP (dati benchmark offline) |
### Cross-host (`src/fusion/cross_host.py`)
Raggruppamento post-giudizio dei verdetti tra host per servizio+versione condivisi per la narrazione di catene di attacco multi-hop nella sintesi.
### Flusso della 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
Si trova in src/reasoning/ (~58 file). Ciclo multi-fase, con gate di sicurezza, osserva→ragiona→agisci. Abilitato con --reason.
src/reasoning/director.py — ReconDirector.run())StrategyManager seleziona persona → Scheduler sceglie azione → SensorStep esegue → EvidenceGraph aggrega osservazioni → ConfidenceEngine aggiorna credenzeProposal tipizzate → AICoordinator normalizza/classifica/verifica → I proposal accettati alimentano lo stato → Compiler → ExecutionPlanner → ExecutionKernel esegue probe → InferenceEngine risolveCrossHostGraph, genera istanze figlie di HostReasonersrc/reasoning/state.py)src/reasoning/ai/)Pipeline: Generate → Normalize → Rank → (MetaReasoner pota) → Verify → Store
Si trova in src/deep/ (7 file). Usato con --deep-probe. Architettura agente per servizio per esecuzione di probe in contesto isolato.
DeepCoordinator.run() flusso:
_build_sensor_plan tramite sensor_director)ScoutAgent per ricognizione passivaProbeAgent per servizio (ciascuno con contesto CVE/tech isolato)Si trova in src/verifier/ (3 file). Conferma CVE guidata dall'AI con probe mirati.
La riverifica della Fase 2 (reverify_with_context) fornisce il contesto completo dell'host per affinare i test falliti.
Si trova in src/directors/ (4 file). Selezione dei parametri di scansione guidata da LLM.
Si trova in src/orchestrator.py. Attivato da target separati da virgola. Esegue run_scan() per host, aggrega i risultati, costruisce il contesto cross-host dai verdetti di fusione combinati. I gruppi cross-host rilevano servizi/versioni condivisi tra host per la narrazione di catene di attacco multi-hop.
src/nvd_lookup.py)--nvd-key)src/epss.py): API FIRST.org in batch di 100 ID CVE, cache su disco di 24 ore in ~/.netlogic/epss_cache.json, fallback morbido a 0.0src/external/nuclei_runner.py incapsula il binario Nuclei (licenza MIT). Opzionale — degrada gradualmente quando il binario non viene trovato. I risultati alimentano la pipeline di fusione come segnali tipizzati (etichette di gravità rimosse per prevenire bias dell'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` — misura offline contro cassette HTTP etichettate (`benchmark/*.json` e `src/fusion/data/`). Metriche:
| Metrica | Soglia di gate |
|---|---|
| Riduzione FP | ≥ 80% |
| Richiamo critico | = 100% |
Due modalità:
- **Oracle** (`--benchmark`): limite superiore di AI perfetta — misura il meccanismo deterministico da solo
- **Modello reale** (`--benchmark --benchmark-ai`): misurato con LLM configurato
---
## Architettura```
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
Tutte le route sotto prefisso /v1/. Autenticazione:
POST /v1/auth/token → JWT HS256 (scadenza predefinita 1h)require_org verifica rispetto a 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]
### Lavori```
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
### Licenza / Impostazioni```
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
---
## Variabili d'Ambiente
### Controller
| Variabile | Default | Descrizione |
|---|---|---|
| `NETLOGIC_ENV` | _(non impostato)_ | `production`/`prod` = validazione del segreto all'avvio |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | Segreto di firma HS256, ≥32 caratteri |
| `NETLOGIC_JWT_EXPIRY` | `3600` | Durata del JWT in secondi |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | Credenziale admin, ≥32 caratteri in produzione |
| `NETLOGIC_API_KEYS` | _(vuoto)_ | Chiavi seed: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(vuoto)_ | Origini consentite (CORS disabilitato se vuoto) |
| `NETLOGIC_PORT` | `8000` | Porta di ascolto |
| `NETLOGIC_HOST` | `0.0.0.0` | Indirizzo di ascolto |
| `NETLOGIC_NO_BROWSER` | _(non impostato)_ | `1` disabilita l'apertura automatica |
| `NETLOGIC_OIDC_ISSUER` | _(non impostato)_ | URL API Frontend di Clerk → login OIDC |
| `NETLOGIC_OIDC_AUDIENCE` | _(non impostato)_ | Pubblico OIDC |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(non impostato)_ | org_id di fallback per utenti OIDC |
| `NETLOGIC_DATABASE_URL` | _(non impostato)_ | Stringa di connessione PostgreSQL |
| `NETLOGIC_SECRETS_KEY` | _(non impostato)_ | Chiave Fernet per le credenziali a riposo |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | Durata del token agente (7 giorni) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | Massimo di attività in coda per agente |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | Massimo di agenti registrati |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | Provider AI predefinito |
| `NETLOGIC_AI_API_KEY` | _(vuoto)_ | Chiave AI predefinita |
| `NETLOGIC_AI_MODEL` | default del provider | Modello predefinito |
| `NETLOGIC_AI_BASE_URL` | default del provider | URL base personalizzato |
| `NETLOGIC_NVD_KEY` | _(vuoto)_ | Chiave API NVD |
| `NETLOGIC_VALID_LICENSES` | _(vuoto)_ | Override licenze per sviluppo/test |
| `NETLOGIC_LICENSE_KEY` | _(vuoto)_ | Chiave di licenza dell'istanza |
| `NETLOGIC_SCANS_DIR` | _(default)_ | Directory di archiviazione scansioni |
| `NETLOGIC_SIEM_ENDPOINT` | _(vuoto)_ | URL di invio log di audit |
| `NETLOGIC_WAPPALYZER_DATA` | _(integrato)_ | Percorso impronte digitali Wappalyzer |
### Agente
| Variabile | Default | Descrizione |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | URL base del Controller |
| `NETLOGIC_API_KEY` | _(non impostato)_ | Chiave API per la registrazione |
---
## Architettura di Sicurezza
### Stack middleware (ordine di applicazione)
1. **AuditMiddleware** — correlazione `X-Request-ID`, log di audit JSON strutturato, invio SIEM
2. **RequestSizeLimitMiddleware** — limite corpo di 10 MB (protezione DoS)
3. **LicenseMiddleware** — blocca tutte le route `/v1/` quando non licenziato (restituisce 402)
4. **SecurityHeadersMiddleware** — HSTS (1 anno), CSP (differenziato HTML vs API), X-Frame-Options, X-Content-Type-Options, Permissions-Policy, Referrer-Policy
5. **OriginCheckMiddleware** — validazione Origin per POST/PUT/DELETE (difesa approfondita CSRF)
6. **CORSMiddleware** — restrittivo: nessun wildcard, solo origini specifiche
### Autenticazione
- **Chiavi API**: SHA-256 hashate a riposo; in chiaro solo su `create()` e nel corpo della richiesta durante `verify()`
- **JWT**: HS256 con stdlib (`hashlib`+`hmac`+`base64`), campo `alg` bloccato prima della verifica (previene alg=none), fallback casuale effimero per sviluppo
- **OIDC**: Clerk/Auth0/WorkOS — RS256 + JWKS, crea automaticamente utenti e organizzazioni al primo login
- **Token agente**: SHA-256 hashati nel registro, confronto a tempo costante, scadenza 7 giorni
### Limitazione delle richieste
Finestra scorrevole in memoria. Per endpoint, per ambito (IP, org_id, agent_id). Ban IP dopo 5 scambi di token falliti in 10 minuti (ban di 1 ora).
### Protezione dei dati
- Chiavi API LLM: crittografate con Fernet a riposo (AES-128-CBC + HMAC-SHA256). Fallimento chiuso in produzione: richiede `NETLOGIC_SECRETS_KEY`
- Multi-tenancy: tutti i dati limitati a `org_id`; la ricerca tra organizzazioni restituisce 404 (non 403)
- Path traversal: tutti i percorsi di archiviazione validati, separatori e `..` rifiutati
---
## CI / Test```bash
pip install -r requirements-dev.txt
python -m pytest
Pipeline CI (.github/workflows/ci.yml) — 5 job:
pip-auditnpm ci + npm run buildNetLogic è destinato esclusivamente a valutazioni di sicurezza autorizzate, test di penetrazione e amministrazione di rete. Scansionare o sondare host senza esplicita autorizzazione scritta è illegale nella maggior parte delle giurisdizioni. L'autore declina ogni responsabilità per l'uso non autorizzato.
MIT © 2026 Dmitry Flynn — Vedi LICENSE.txt
| Verifier Engine | Riverifica CVE guidata da IA: progetta piani di probe HTTP raw dal contesto CVE, esegue tramite socket stdlib |
| Multi-Host Orchestration | Pipeline di scansione completa per host → contesto cross-host e matrice di raggiungibilità → scoperta catena d'attacco |
| AI Sensor Directors | LLM decide quali sensori prioritizzare in base a porte aperte, stack tecnologico e CVE |
| Authenticated SSH | Sottoprocesso ssh con credenziali legge versioni reali dei pacchetti installati (60+ mapping di prodotto) |
| Service Enum | Estrazione di attributi a livello di protocollo (KEX SSH, SMBv1, NLA RDP, community SNMP, stato auth HTTP) |
| Topology Mapper | DNS inverso, IPv6, traceroute, ASN/org/paese tramite ip-api.com |
| Reachability Prober | Matrice di movimento laterale post-compromissione da adiacenza di sottorete |
| Network Prober | Scansione attiva di sottorete (/24 vicini privati) con scoperta in due fasi (live sweep → scansione porte completa) |
| Scan Diff | Differenze nel tempo: confronta la scansione corrente con l'ultimo report JSON precedente per target |
| License Management | Sistema di licenze commerciali con attivazione tramite chiave (stub per Stripe/Paddle/Lemon Squeezy) |
| Per-Org AI Config | Ogni organizzazione memorizza le proprie credenziali LLM crittografate a riposo tramite Fernet |
| OIDC / Clerk | Accessi umani tramite JWT di sessione emessi da Clerk, verificati contro JWKS pubbliche con provisioning automatico |
| PostgreSQL | Persistenza multi-tenant completa con migrazioni applicate automaticamente (job di scansione, impostazioni organizzazione, stato del ragionamento, audit) |
| Fusion Benchmark | Benchmark offline su cassette HTTP registrate; metriche di precisione/richiamo/richiamo critico/riduzione falsi positivi |
netlogic <target> [flags]| Scansione terminale one-shot (nessun server), stampa/scrive il report. |
| Formato | Esempio | Modalità |
|---|
| Nome host | example.com | Scansione singolo host |
| IPv4 | 10.0.0.5 | Scansione singolo host |
| CIDR | 192.168.1.0/24 | Scansione CIDR (solo scanner, nessuna fusione) |
| Separati da virgola | target1,target2 | Orchestrazione multi-host (contesto cross-host) |
GoalPlanner produce piani di investigazioneReasoningValidator audit di integrità → ProvenanceBuilder registra archi → stato persistito| Layer (Layer) | Classe (Class) | Cosa traccia |
|---|
| WorldModel (Mondo) | WorldModel | EvidenceGraph, osservazioni, credenze, host, tecnologia, raggiungibilità |
| InvestigationState (Stato Investigativo) | InvestigationState | Obiettivi (DAG), ipotesi, contraddizioni, vicoli ciechi, persona corrente |
| ExecutionState (Stato di Esecuzione) | ExecutionState | Budget, cronologia_probe, provenienza, piani_investigativi, trascrizione AI |
| LearnedPatterns (Pattern Appresi) | LearnedPatterns | Euristiche cross-scan + playbook |
| Componente | File | Descrizione |
|---|
| EvidenceGraph | evidence_graph.py | Grafo temporale di entità deduplicate (osservazioni indirizzate per contenuto tramite SHA-256) |
| Hypothesis engine | hypothesis.py | Candidati in competizione con probabilità, entropia, guadagno informativo, risoluzione a posteriori |
| ConfidenceEngine | confidence.py | Noisy-OR su fonti distinte; solo versione limitata a 0.60; KEV/probe fissati a 0.97 |
| ProvenanceBuilder | provenance.py | Archi Osservazione→Inferenza→Ipotesi, indirizzati per hash del contenuto |
| Scheduler | scheduler.py | Selezione azioni basata sul guadagno informativo con explore_reserve (10%) |
| StrategyManager | strategy.py | Meta-ragionamento: selezione della persona, modalità explore/exploit, rilevamento plateau |
| ActionGate | action_gate.py | Difesa in profondità: livelli di rischio (READ_ONLY < SAFE_ACTIVE < INTRUSIVE < EXPLOIT), massimo core è SAFE_ACTIVE |
| InferenceEngine | inference.py | Regole deterministiche da rules/*.json, non scrive mai confidenza |
| NovelInferenceEngine | novel_inference.py | Regole per cache_poisoning, request_smuggling, auth_bypass ecc. |
| ExecutionKernel | execution_kernel.py | Valida + esegue + traccia probe (scope → sola lettura → budget → dedup → profondità) |
| Playbook system | playbooks.py | Playbook YAML con condizioni di attivazione e template di intent |
| Change detection | change_detection.py | Fase 7: diff su osservazioni immutabili (non stato), produce ScanDelta di DeltaEvents |
| Active validation | active_validation.py | Fase 8b: probe SAFE_ACTIVE non distruttivi tramite ActionGate |
| File | Componente |
|---|
coordinator.py | AICoordinator — orchestrazione pipeline a stadi |
proposals.py | Busta Proposal tipizzata con payload specifico per tipo, provenienza, economicità |
normalize.py | ProposalNormalizer — gate di validazione totale |
rank.py | ProposalRanker — punteggio = raw_score × prob_correct × reputation_weight |
meta_reasoner.py | Potatura deterministica (rilevamento loop, riduzione incertezza) |
verifier.py | 4 stadi: Sintassi → Semantica → Evidenza → Sicurezza |
store.py | ProposalStore — registro del ciclo di vita |
transcript.py | InvestigationTranscript — registrazione della catena causale |
evaluation.py | Harness di valutazione deterministica basato su cassette |
reputation.py | AgentReputation — traccia il tasso di accettazione/rifiuto per agente |
agents/hypothesis_generator.py | C1 — propone spiegazioni concorrenti + ipotesi di vulnerabilità nuove |
agents/counterfactual.py | C11 — propone obiettivi di confutazione |
agents/investigation_designer.py | C2 — progetta piani di raccolta evidenze |
| Componente | File | Descrizione |
|---|
DeepCoordinator | coordinator.py | Orchestra l'intera pipeline deep: piano sensori AI → ScoutAgent → ProbeAgent per servizio → enumerazione servizi → Nuclei → verificatore → takeover → probe subnet → topologia → auth → diff → raggiungibilità |
ScoutAgent | scout_agent.py | Ricognizione passiva: TLS, header, stack, DNS, OSINT |
ProbeAgent | probe_agent.py | Prende di mira un servizio con contesto CVE/tech isolato — esegue probe + verificatore |
ExploitChain | chain.py | Pianificazione percorso di attacco BFS su verdetti confermati dalla fusione, generazione PoC |
Sandbox | sandbox.py | Subprocesso ristretto per validazione PoC (directory temporanea, timeout, pulizia) |
Mission / AgentReport | models.py | Modelli dati per direttive e risultati degli agenti |
| Componente | File | Descrizione |
|---|
run_verifier() | engine.py | Orchestra: genera piani → esegui → costruisci Signals confermati da probe |
generate_plans_for_cves() | planner.py | Per CVE (CVSS ≥ 7.0): controlla ~20 piani incorporati → L'AI genera un piano HTTP grezzo (metodo, percorso, header, corpo, status/corpo atteso) |
run_test() | runner.py | Esecuzione socket TCP/TLS grezzi, parsing manuale HTTP/1.0, corrispondenza pattern corpo atteso |
| Director | File | Cosa decide |
|---|
SensorDirector | sensor_director.py | Quali sensori abilitare/disabilitare e con quale priorità, in base a porte aperte + stack tecnologico + CVE |
ReprobeDirector | reprobe.py | Se i potenziali risultati possono essere risolti con probe HTTP mirati |
NucleiSelector | nuclei_selector.py | Quali tag dei template Nuclei includere/escludere (riduce esecuzioni irrilevanti) |
SubnetDirector | subnet_director.py | Quali host adiacenti sondare, quali porte, a quale profondità (skip/quick/standard/deep) |