NetLogic — это продвинутый инструментарий для сетевого анализа и кибербезопасности, предназначенный для проверки трафика, анализа пакетов и обнаружения угроз.
Облачный картограф поверхности атаки и коррелятор уязвимостей — v3.0
NetLogic — это платформа сетевой безопасности, объединяющая активное сканирование портов, корреляцию CVE (живой NVD API), анализ SSL/TLS, аудит безопасности HTTP, оценку DNS/электронной почты, обнаружение перехвата поддоменов, пассивный OSINT, активное зондирование уязвимостей, механизм рассуждений на базе ИИ, обнаружение цепочек атак между хостами и архитектуру агентов глубокого зондирования — поставляемая как веб-приложение (React dashboard + FastAPI). Основной движок сканирования написан на чистом Python 3.9+ stdlib без сторонних зависимостей.
| Модуль | Описание |
|---|---|
| Сканер портов | TCP-сканирование с 43/58 портами, 22 пробы сервисов, захват баннеров |
| Коррелятор CVE | Живой NVD API v2.0 + обогащение EPSS через FIRST.org |
| Анализатор TLS | Версии протоколов, слабые шифры, POODLE/BEAST/CRIME/DROWN, срок действия сертификата |
| Аудит HTTP-заголовков | HSTS, CSP, X-Frame-Options, CORS, флаги cookie; оценка 0–100 |
| Стековый отпечаток | CMS, фреймворк, облачный провайдер, CDN, WAF из баннера/заголовка/тела |
| Безопасность DNS | SPF, DKIM, DMARC, DNSSEC, передача зоны, оценка спуфинга |
| Пассивный OSINT | Журналы Certificate Transparency, DoH DNS, поиск ASN — без прямого контакта с целью |
| Пробник сервисов | Неаутентифицированные пробы Redis/Mongo/ES/Docker/K8s/etcd, 33 административных пути |
| Обнаружитель перехвата | Обнаружение поддоменов через CT-логи + 25 CNAME-отпечатков облачных провайдеров |
| Интеграция с Nuclei | Обёртка для 13k+ шаблонов сообщества (CVE, технологии, экспозиция, неверная конфигурация) — лицензия MIT |
| Конвейер слияния | Многосенсорный шлюз сигналов → детерминированное согласование → арбитраж ИИ → граф атак → 6-секционный отчёт |
| Веб-отпечаток | Хэш фавикона (совместимый с Shodan mmh3), секреты JS, маркеры версий, раскрытые файлы, обнаружение страниц по умолчанию |
| AI-анализ | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — потоковая передача токенов через SSE |
| Машина рассуждений | Адаптивный цикл наблюдение→рассуждение→действие с EvidenceGraph, механизмом гипотез, затуханием уверенности, происхождением, планировщиком, плейбуками, обнаружением изменений, активной проверкой |
| Глубокое исследование | Архитектура агентов для каждого сервиса: ScoutAgent (разведка), ProbeAgent (целевые проверки CVE), Coordinator, Sandbox |
| Агент расследования ИИ | Цикл в стиле ReAct: после базовых датчиков ИИ управляет подобранной, ограниченной по объёму, проверяемой поверхностью инструментов (~35 инструментов) для проверки зацепок и построения цепочек атак — с опциональными агрессивными инструментами (пробы на сбой, произвольное доказательство, произвольная эксплуатация) для авторизованных целей |
Есть ровно два способа запустить NetLogic:
| Режим | Команда | Что делает |
|---|---|---|
| Веб-приложение | netlogic --gui | Запускает FastAPI + обслуживает React SPA + встроенный агент сканирования, автоматически генерирует секреты и открывает панель управления в вашем браузере. Это единственный способ запустить веб-приложение. |
Поверхность продукта — это веб-приложение (React dashboard + FastAPI). Движок сканирования в src/ обеспечивает задания, запускаемые из интерфейса.
pip install -r requirements-api.txt pip install -e .
netlogic --gui
netlogic scanme.nmap.org --full
---
## Справочник по CLI```
netlogic [target] [flags]
Точкой входа является api.cli:main (определённая в pyproject.toml), которая делегирует выполнение к netlogic.py:main(). Вся логика сканирования находится в 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
### Выбор порта```
# 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
### Поддерживаемые AI-провайдеры
| Провайдер | Модель по умолчанию | Стиль 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` | указанный пользователем | OpenAI |
### Механизм рассуждений```
# 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
После запуска базовых сенсоров опциональный агент в стиле ReAct позволяет ИИ самостоятельно управлять своими инструментами для проверки зацепок и построения цепочек атак, вместо того чтобы оставлять совпадения версий/баннеров с CVE непроверенными. ИИ предлагает вызовы инструментов; детерминированная среда выполнения выполняет их — каждый инструмент ограничен областью действия по цели, санирован и записан как наблюдение. ИИ никогда не взаимодействует с сетью напрямую.```
netlogic example.com --ai --ai-agent
netlogic example.com --ai --agent-depth --agent-max-steps 24 --agent-max-requests 80
Агент имеет ~35 инструментов, доступных только для чтения/безопасно-активных по умолчанию: HTTP/TLS/DNS-проверки, `dir_enum`, `confirm_tech`,
`timing_probe`, `cve_probe` (контрольные проверки на известные CVE), `sqli_boolean`/`sqli_time`, `ssrf_canary`,
`idor_diff`, `file_disclosure`, `browser_get` (безголовый, проходит JavaScript-задачи), плюс учёт в HackerOne
(`record_poc`, `severity_suggest`, `submit_readiness`).
**Опциональные агрессивные инструменты** — отключены по умолчанию, **ТОЛЬКО для АВТОРИЗОВАННЫХ / принадлежащих целей в зоне ответственности** (никогда при публичном или чужом сканировании). Каждый требует `--ai-agent`:
| Флаг | Инструмент | Что разблокирует | Ограничения |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | Проверки на курированные CVE, связанные с падением/DoS (http.sys, MS15-034), которые МОГУТ вызвать падение хоста | Фиксированный каталог из 3 CVE — не без ограничений |
| `--allow-freeform-proof` | `http_proof` | Уровень C: произвольные GET/HEAD/OPTIONS (+ POST по путям, похожим на поиск/вход/graphql) | Деструктивные шаблоны + PUT/PATCH/DELETE заблокированы; только проверка, не изменение |
| `--allow-exploit-requests` | `exploit_request` | Уровень E: **любой метод** (включая PUT/PATCH/DELETE) + произвольный путь/заголовки/тело к цели | Ограничено зоной ответственности; отказ при массовых деструктивных шаблонах (DROP/TRUNCATE TABLE, `rm -rf`) и при внедрении заголовков CR/LF; каждый запрос аудируется |
Детерминированный ActionGate оставляет ядро на уровне `safe_active`; эти три флага — явные, аудируемые
разрешения выше этого уровня. Пример (собственная лабораторная машина + локальная модель):```
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
### Бенчмарк```
# 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
### Управление кэшем NVD```
netlogic --cache-stats
netlogic example.com --nvd-key YOUR_NVD_KEY
netlogic --version # Show version and exit netlogic --gui # Start web dashboard
---
## Конвейер слияния
Конвейер слияния — это воронка **датчики → шлюз → арбитраж ИИ → синтез**, заменяющая монолитные вызовы ИИ на точный шлюз. Он находится в `src/fusion/` (12 файлов).
### Схема сигнала (`src/fusion/signals.py`)
Контракт данных с доказательствами. Каждый датчик испускает объекты `Signal`:
- `source`: `probe`/`banner`/`nuclei`/`wappalyzer`/`nvd`/`osv`/`tls`/`dns`
- `kind`: `vuln`/`tech`/`exposure`/`misconfig`/`service`
- `claim`: нормализованный субъект (например, `"CVE-2021-44228"`, `"nginx"`)
- `host`, `port`, `service`, `evidence` (макс. 600 символов)
- `confidence` (0..1), `reliability` (`high`/`medium`/`low`)
- `kev`, `epss` (0..1), `cvss` (0..10), `exploit_available`, `version_matched`, `probe_confirmed`
- `exposure` dict (доступность, WAF, точка обзора)
- `observed_data` (необработанные байты, отправленные ИИ — НЕ имена датчиков или степени серьёзности для предотвращения смещения меток)
- `ai_view()` отбрасывает метаданные датчика, возвращает только наблюдаемые факты
### Шлюз (`src/fusion/gate.py`)
Детерминированное согласование — получая `list[Signal]`, группирует по субъекту и возвращает `list[Verdict]`:
| Условие | Вердикт |
|---|---|
| В списке KEV ИЛИ подтверждено зондом ИЛИ критический+эксплойт/высокий EPSS | **Подтверждено** (закреплено — не может быть отброшено) |
| ≥2 независимых источника согласны, ≥1 высокой надёжности | **Подтверждено** (если все — совпадение версий, то серый) |
| Только один источник низкой надёжности, низкое/среднее воздействие, нет подтверждения | **Отброшено** |
| Всё остальное | **Серый** (требует токена ИИ) |
### Арбитраж ИИ (`src/fusion/adjudicator.py`)
Затрагивает только серую зону. Ограничения безопасности реализованы в коде (не в промпте):
- Серые элементы высокого/критического уровня НИКОГДА не могут быть отброшены — в худшем случае понижены до `potential`
- Совпадения только по версии ограничены `potential` (дистрибутивы переносят исправления без изменения версий)
- ИИ также обнаруживает новые находки из полного контекста хоста
- Безопасный отказ: сбой ИИ оставляет серую зону как `potential` — без потери данных
### Синтез (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → детерминированный граф достижимости из ПОДТВЕРЖДЁННЫХ находок.
`full_synthesize(...)` → отчёт ИИ из 6 разделов:
1. Исполнительное резюме
2. Ключевые находки (таблица)
3. Цепочки атак (на основе графа, LLM описывает реальные рёбра)
4. За пределами известных CVE
5. Ложные срабатывания и шум
6. Устранение
### Датчики
| Датчик | Файл | Что выдает |
|---|---|---|
| Engine bridge | `engine_bridge.py` | Преобразует артефакты сканирования → Signals из NVD, зондов, стека, Nuclei, верификатора |
| Wappalyzer | `sensors/wappalyzer.py` | Беспривязная Wappalyzer-совместимая идентификация HTTP-ответов |
| Nuclei | `sensors/nuclei.py` | Запускает YAML-шаблоны для ответов (подмножество синтаксиса Nuclei) |
| Cassette | `cassette.py` | Запись/воспроизведение из HTTP-кассет (офлайн-эталонные данные) |
### Межхостовой анализ (`src/fusion/cross_host.py`)
Группировка вердиктов после арбитража по общим службам+версиям для описания многошаговых цепочек атак в синтезе.
### Поток конвейера```
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
Расположен в src/reasoning/ (~58 файлов). Многофазовый цикл с защитными проверками: наблюдать→рассуждать→действовать. Включается с помощью --reason.
src/reasoning/director.py — ReconDirector.run())StrategyManager выбирает персону → Scheduler выбирает действие → SensorStep выполняет → EvidenceGraph свёртывает наблюдения → ConfidenceEngine обновляет убежденияProposal → AICoordinator нормализует/ранжирует/верифицирует → принятые предложения порождают состояние → Compiler → ExecutionPlanner → ExecutionKernel запускает пробы → InferenceEngine разрешаетCrossHostGraph, порождает экземпляры HostReasonersrc/reasoning/state.py)src/reasoning/ai/)Конвейер: Generate → Normalize → Rank → (MetaReasoner prune) → Verify → Store
Расположена в src/deep/ (7 файлов). Используется с --deep-probe. Периодическая архитектура агентов на службу для изолированного по контексту выполнения проб.
Поток DeepCoordinator.run():
_build_sensor_plan через sensor_director)ScoutAgent для пассивной разведкиProbeAgent на службу (каждый с изолированным контекстом CVE/технологий)Расположен в src/verifier/ (3 файла). Подтверждение CVE с помощью целенаправленных проб с использованием ИИ.
Повторная верификация фазы 2 (reverify_with_context) предоставляет полный контекст хоста для уточнения неудачных тестов.
Расположены в src/directors/ (4 файла). Выбор параметров сканирования на основе LLM.
Расположено в src/orchestrator.py. Запускается при указании целей через запятую. Запускает run_scan() для каждого хоста, агрегирует результаты, строит межхостовой контекст на основе объединённых вердиктов слияния. Межхостовые группы обнаруживают общие службы/версии на нескольких хостах для описания многошаговых цепочек атак.
src/nvd_lookup.py)--nvd-key)src/epss.py): API FIRST.org пакетами по 100 CVE ID, 24-часовой дисковый кеш в ~/.netlogic/epss_cache.json, отказоустойчивость до 0.0src/external/nuclei_runner.py обёртывает бинарник Nuclei (лицензия MIT). Опционально — корректно деградирует при отсутствии бинарника. Результаты поступают в конвейер слияния как типизированные сигналы (метки серьёзности удаляются для предотвращения смещения LLM).```
scoop install nuclei # Windows brew install nuclei # macOS go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Linux
---
## Бенчмарк Fusion
`src/fusion/benchmark.py` — офлайн-измерение по размеченным HTTP-кассетам (`benchmark/*.json` и `src/fusion/data/`). Метрики:
| Метрика | Пороговое значение |
|---|---|
| Снижение ЛП | ≥ 80% |
| Полнота критических случаев | = 100% |
Два режима:
- **Oracle** (`--benchmark`): идеальная верхняя граница ИИ — измеряет только детерминированный механизм
- **Реальная модель** (`--benchmark --benchmark-ai`): измерение с настроенной LLM
---
## Архитектура```
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
Все маршруты находятся под префиксом /v1/. Аутентификация:
POST /v1/auth/token → HS256 JWT (по умолчанию срок действия 1 час)require_org зависимость проверяет через 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]
### Вакансии```
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
### Лицензия / Настройки```
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
---
## Переменные окружения
### Контроллер
| Переменная | По умолчанию | Описание |
|---|---|---|
| `NETLOGIC_ENV` | _(не задано)_ | `production`/`prod` = проверка секретов при запуске |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | Секрет подписи HS256, ≥32 символов |
| `NETLOGIC_JWT_EXPIRY` | `3600` | Время жизни JWT в секундах |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | Учётные данные администратора, ≥32 символов в production |
| `NETLOGIC_API_KEYS` | _(пусто)_ | Начальные ключи: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(пусто)_ | Разрешённые источники (CORS отключён, если пусто) |
| `NETLOGIC_PORT` | `8000` | Порт привязки |
| `NETLOGIC_HOST` | `0.0.0.0` | Адрес привязки |
| `NETLOGIC_NO_BROWSER` | _(не задано)_ | `1` отключает автооткрытие |
| `NETLOGIC_OIDC_ISSUER` | _(не задано)_ | URL Frontend API Clerk → вход через OIDC |
| `NETLOGIC_OIDC_AUDIENCE` | _(не задано)_ | Аудитория OIDC |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(не задано)_ | Запасной org_id для пользователей OIDC |
| `NETLOGIC_DATABASE_URL` | _(не задано)_ | Строка подключения PostgreSQL |
| `NETLOGIC_SECRETS_KEY` | _(не задано)_ | Ключ Fernet для шифрования учётных данных в покое |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | Время жизни токена агента (7 дней) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | Максимум ожидающих задач на агента |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | Максимум зарегистрированных агентов |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | Провайдер ИИ по умолчанию |
| `NETLOGIC_AI_API_KEY` | _(пусто)_ | Ключ ИИ по умолчанию |
| `NETLOGIC_AI_MODEL` | по умолчанию провайдера | Модель по умолчанию |
| `NETLOGIC_AI_BASE_URL` | по умолчанию провайдера | Пользовательский базовый URL |
| `NETLOGIC_NVD_KEY` | _(пусто)_ | Ключ API NVD |
| `NETLOGIC_VALID_LICENSES` | _(пусто)_ | Переопределения лицензий для разработки/тестирования |
| `NETLOGIC_LICENSE_KEY` | _(пусто)_ | Ключ лицензии экземпляра |
| `NETLOGIC_SCANS_DIR` | _(по умолчанию)_ | Каталог хранения сканирований |
| `NETLOGIC_SIEM_ENDPOINT` | _(пусто)_ | URL отправки журналов аудита |
| `NETLOGIC_WAPPALYZER_DATA` | _(встроенный)_ | Путь к отпечаткам Wappalyzer |
### Агент
| Переменная | По умолчанию | Описание |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | Базовый URL контроллера |
| `NETLOGIC_API_KEY` | _(не задано)_ | Ключ API для регистрации |
---
## Архитектура безопасности
### Стек промежуточного ПО (порядок применения)
1. **AuditMiddleware** — корреляция `X-Request-ID`, структурированный JSON-журнал аудита, отправка в SIEM
2. **RequestSizeLimitMiddleware** — лимит тела 10 МБ (защита от DoS)
3. **LicenseMiddleware** — блокирует все маршруты `/v1/` при отсутствии лицензии (возвращает 402)
4. **SecurityHeadersMiddleware** — HSTS (1 год), CSP (различно для HTML и API), X-Frame-Options, X-Content-Type-Options, Permissions-Policy, Referrer-Policy
5. **OriginCheckMiddleware** — проверка Origin для POST/PUT/DELETE (глубинная защита CSRF)
6. **CORSMiddleware** — ограничительный: без wildcard, только конкретные источники
### Аутентификация
- **Ключи API**: SHA-256 хешируются в покое; открытый текст только при `create()` и в теле запроса во время `verify()`
- **JWT**: HS256 со стандартной библиотекой (`hashlib`+`hmac`+`base64`), поле `alg` фиксируется перед проверкой (предотвращает alg=none), эфемерная случайная запасная для разработки
- **OIDC**: Clerk/Auth0/WorkOS — RS256 + JWKS, автоматическое создание пользователей и организаций при первом входе
- **Токены агентов**: SHA-256 хешируются в реестре, сравнение с постоянным временем, срок действия 7 дней
### Ограничение частоты
Скользящее окно в памяти. На каждый конечный пункт, по каждой области (IP, org_id, agent_id). Блокировка IP после 5 неудачных обменов токенами за 10 минут (блокировка на 1 час).
### Защита данных
- Ключи API LLM: шифруются Fernet в покое (AES-128-CBC + HMAC-SHA256). Закрытый сбой в production: требуется `NETLOGIC_SECRETS_KEY`
- Мультиарендность: все данные привязаны к `org_id`; запрос из другой организации возвращает 404 (а не 403)
- Обход пути: все пути хранения проверяются, разделители и `..` отклоняются
---
## CI / Тестирование```bash
pip install -r requirements-dev.txt
python -m pytest
CI pipeline (.github/workflows/ci.yml) — 5 заданий:
pip-auditnpm ci + npm run buildNetLogic предназначен только для авторизованных оценок безопасности, тестирования на проникновение и администрирования сети. Сканирование или проверка хостов без явного письменного разрешения незаконны в большинстве юрисдикций. Автор не несет ответственности за несанкционированное использование.
MIT © 2026 Dmitry Flynn — См. LICENSE.txt
| Механизм верификации | Повторная верификация CVE с помощью ИИ: разработка планов зондов raw-HTTP из контекста CVE, выполнение через сокеты stdlib |
| Многохостовая оркестрация | Полный конвейер сканирования для каждого хоста → межхостовый контекст и матрица достижимости → обнаружение цепочек атак |
| Директоры сенсоров ИИ | LLM решает, какие датчики приоритезировать на основе открытых портов, технологического стека и CVE |
| Аутентифицированный SSH | Дочерний процесс ssh с учётными данными считывает реальные версии установленных пакетов (60+ соответствий продуктов) |
| Перечисление сервисов | Извлечение атрибутов на уровне протокола (SSH KEX, SMBv1, RDP NLA, SNMP community, состояние HTTP-аутентификации) |
| Картограф топологии | Обратный DNS, IPv6, traceroute, ASN/организация/страна через ip-api.com |
| Пробник достижимости | Матрица латерального перемещения после компрометации из смежности подсетей |
| Сетевой пробник | Активное сканирование подсети (/24 частные соседи) с двухфазным обнаружением (проверка активности → полное сканирование портов) |
| Разница сканирований | Изменения со временем: сравнение текущего сканирования с последним предыдущим JSON-отчётом для каждой цели |
| Управление лицензиями | Система коммерческих лицензий с активацией ключей (заглушка для Stripe/Paddle/Lemon Squeezy) |
| AI-конфигурация для каждой организации | Каждая организация хранит свои учётные данные LLM, зашифрованные в состоянии покоя через Fernet |
| OIDC / Clerk | Вход пользователей через сессионные JWT, выданные Clerk, проверенные по общедоступному JWKS с автоматическим предоставлением |
| PostgreSQL | Полная многотенантная персистентность с автоматически применяемыми миграциями (задания сканирования, настройки организации, состояние рассуждений, аудит) |
| Бенчмарк слияния | Офлайн-бенчмарк на записанных HTTP-кассетах; метрики precision/recall/critical-recall/FP-reduction |
| CLI | netlogic <target> [flags] | Одноразовое терминальное сканирование (без сервера), печатает/записывает отчёт. |
| Формат | Пример | Режим |
|---|
| Имя хоста | example.com | Сканирование одного хоста |
| IPv4 | 10.0.0.5 | Сканирование одного хоста |
| CIDR | 192.168.1.0/24 | Обход CIDR (только сканер, без слияния) |
| Разделённые запятыми | target1,target2 | Оркестрация нескольких хостов (межхостовый контекст) |
GoalPlanner создаёт планы расследованияReasoningValidator аудит целостности → ProvenanceBuilder записывает рёбра → состояние сохраняется| Уровень | Класс | Что отслеживается |
|---|
| WorldModel | WorldModel | EvidenceGraph, наблюдения, убеждения, хосты, технологии, достижимость |
| InvestigationState | InvestigationState | Цели (DAG), гипотезы, противоречия, тупики, текущая персона |
| ExecutionState | ExecutionState | Бюджет, probe_history, происхождение, investigation_plans, ИИ-транскрипт |
| LearnedPatterns | LearnedPatterns | Межсканировочные эвристики + playbooks |
| Компонент | Файл | Описание |
|---|
| EvidenceGraph | evidence_graph.py | Дедуплицированный темпоральный граф сущностей (наблюдения с адресацией по содержимому через SHA-256) |
| Движок гипотез | hypothesis.py | Конкурирующие кандидаты с вероятностями, энтропией, приростом информации, апостериорным разрешением |
| ConfidenceEngine | confidence.py | Noisy-OR по различным источникам; только по версии ограничен 0.60; KEV/проба фиксирована на 0.97 |
| ProvenanceBuilder | provenance.py | Рёбра Наблюдение→Вывод→Гипотеза, адресация по хешу содержимого |
| Scheduler | scheduler.py | Выбор действий на основе прироста информации с резервом исследования (10%) |
| StrategyManager | strategy.py | Мета-рассуждение: выбор персоны, режим исследования/эксплуатации, обнаружение плато |
| ActionGate | action_gate.py | Защита в глубину: уровни риска (READ_ONLY < SAFE_ACTIVE < INTRUSIVE < EXPLOIT), максимум для ядра — SAFE_ACTIVE |
| InferenceEngine | inference.py | Детерминированные правила из rules/*.json, никогда не записывает уверенность |
| NovelInferenceEngine | novel_inference.py | Правила для cache_poisoning, request_smuggling, auth_bypass и др. |
| ExecutionKernel | execution_kernel.py | Проверяет + выполняет + трассирует пробы (scope → read-only → budget → dedup → depth) |
| Система playbooks | playbooks.py | YAML playbooks с условиями запуска и шаблонами намерений |
| Обнаружение изменений | change_detection.py | Фаза 7: сравнивает неизменяемые наблюдения (не состояние), создаёт ScanDelta из DeltaEvents |
| Активная валидация | active_validation.py | Фаза 8b: неразрушающие пробы SAFE_ACTIVE через ActionGate |
| Файл | Компонент |
|---|
coordinator.py | AICoordinator — оркестрация многоэтапного конвейера |
proposals.py | Типизированный конверт Proposal с полезной нагрузкой, происхождением, экономикой |
normalize.py | ProposalNormalizer — общий шлюз валидации |
rank.py | ProposalRanker — оценка = raw_score × prob_correct × reputation_weight |
meta_reasoner.py | Детерминированное отсечение (обнаружение циклов, снижение неопределённости) |
verifier.py | 4 этапа: Синтаксис → Семантика → Доказательства → Безопасность |
store.py | ProposalStore — реестр жизненного цикла |
transcript.py | InvestigationTranscript — запись причинно-следственной цепочки |
evaluation.py | Кассетный детерминированный оценочный стенд |
reputation.py | AgentReputation — отслеживает частоту принятия/отклонения для каждого агента |
agents/hypothesis_generator.py | C1 — предлагает конкурирующие объяснения + гипотезы о новых уязвимостях |
agents/counterfactual.py | C11 — предлагает цели опровержения |
agents/investigation_designer.py | C2 — проектирует планы сбора доказательств |
| Компонент | Файл | Описание |
|---|
DeepCoordinator | coordinator.py | Оркестрирует полный конвейер глубокого зондирования: ИИ-план датчиков → ScoutAgent → ProbeAgent на службу → перечисление служб → Nuclei → верификатор → захват → подсеть → топология → аутентификация → различие → достижимость |
ScoutAgent | scout_agent.py | Пассивная разведка: TLS, заголовки, стек, DNS, OSINT |
ProbeAgent | probe_agent.py | Ориентирован на одну службу с изолированным контекстом CVE/технологий — выполняет пробы + верификатор |
ExploitChain | chain.py | Планирование атак BFS по подтверждённым вердиктам слияния, генерация PoC |
Sandbox | sandbox.py | Ограниченный подпроцесс для проверки PoC (временная директория, тайм-аут, очистка) |
Mission / AgentReport | models.py | Модели данных для директив агентов и результатов |
| Компонент | Файл | Описание |
|---|
run_verifier() | engine.py | Оркестрирует: генерация планов → выполнение → построение Signal'ов, подтверждённых пробами |
generate_plans_for_cves() | planner.py | Для каждой CVE (CVSS ≥ 7.0): проверяет ~20 встроенных планов → ИИ генерирует план с сырым HTTP (метод, путь, заголовки, тело, ожидаемый статус/тело) |
run_test() | runner.py | Выполнение через сырой TCP/TLS сокет, ручной разбор HTTP/1.0, сопоставление шаблона ожидаемого тела |
| Директор | Файл | Что решает |
|---|
SensorDirector | sensor_director.py | Какие датчики включить/отключить и с каким приоритетом, на основе открытых портов + технологического стека + CVE |
ReprobeDirector | reprobe.py | Можно ли разрешить потенциальные находки с помощью целенаправленных HTTP-проб |
NucleiSelector | nuclei_selector.py | Какие теги шаблонов Nuclei включить/исключить (сокращает нерелевантные запуски) |
SubnetDirector | subnet_director.py | Какие соседние хосты зондировать, какие порты, с какой глубиной (пропуск/быстро/стандартно/глубоко) |