NetLogic은 트래픽 검사, 패킷 분석 및 위협 탐지를 위한 고급 네트워크 분석 및 사이버 보안 툴킷입니다.
클라우드 네이티브 공격 표면 매퍼 & 취약점 상관 분석기 — v3.0
NetLogic은 네트워크 보안 플랫폼으로, 활성 포트 스캐닝, CVE 상관 분석(실시간 NVD API), SSL/TLS 분석, HTTP 보안 감사, DNS/이메일 보안 평가, 서브도메인 탈취 탐지, 패시브 OSINT, 활성 취약점 프로빙, AI 기반 추론 엔진, 호스트 간 공격 체인 발견 및 딥 프로브 에이전트 아키텍처를 결합하여 웹 앱(React 대시보드 + FastAPI)으로 제공합니다. 핵심 스캔 엔진은 순수 Python 3.9+ stdlib이며 타사 종속성이 없습니다.
| 모듈 | 설명 |
|---|---|
| 포트 스캐너 | 43/58 포트 TCP 연결 스캔, 22개 서비스 프로브, 배너 그래빙 |
| CVE 상관 분석기 | 실시간 NVD API v2.0 + FIRST.org를 통한 EPSS 강화 |
| TLS 분석기 | 프로토콜 버전, 취약한 암호, POODLE/BEAST/CRIME/DROWN, 인증서 만료 |
| HTTP 헤더 감사 | HSTS, CSP, X-Frame-Options, CORS, 쿠키 플래그; 0–100 점수 |
| 스택 핑거프린트 | 배너/헤더/본문에서 CMS, 프레임워크, 클라우드 제공자, CDN, WAF 탐지 |
| DNS 보안 | SPF, DKIM, DMARC, DNSSEC, 영역 전송, 스푸핑 가능 점수 |
| 패시브 OSINT | 인증서 투명성 로그, DoH DNS, ASN 조회 — 대상 직접 접촉 없음 |
| 서비스 프로버 | 인증 없는 Redis/Mongo/ES/Docker/K8s/etcd 프로브, 33개 관리자 경로 |
| 탈취 탐지기 | CT 로그 서브도메인 발견 + 25개 클라우드 제공자 CNAME 핑거프린트 |
| Nuclei 통합 | 13k+ 커뮤니티 템플릿(CVE, 기술, 노출, 잘못된 구성)을 위한 래퍼 — MIT 라이선스 |
| 퓨전 파이프라인 | 다중 센서 신호 게이트 → 결정적 합의 → AI 판정 → 공격 그래프 → 6섹션 보고서 |
| 웹 핑거프린트 | 파비콘 해시(Shodan 호환 mmh3), JS 비밀, 버전 마커, 노출된 파일, 기본 랜더 탐지 |
| AI 분석 | OpenAI / Anthropic / OpenRouter / Ollama / Gemini / Groq / Kimi / Qwen — 토큰 스트리밍 SSE |
| 추론 엔진 | 적응형 관찰→추론→행동 루프, EvidenceGraph, 가설 엔진, 신뢰도 감쇠, 출처, 스케줄러, 플레이북, 변경 탐지, 활성 검증 포함 |
| 딥 프로브 | 서비스별 에이전트 아키텍처: ScoutAgent(정찰), ProbeAgent(대상 CVE 확인), Coordinator, Sandbox |
| AI 조사 에이전트 | ReAct 스타일 루프: 기본 센서 후 AI가 큐레이팅된 범위 제한 및 감사된 도구 표면(~35 도구)을 구동하여 리드를 검증하고 공격 체인 구축 — 승인된 대상에 대한 선택적 공격적 도구(충돌 프로브, 자유 형식 증명, 자유 형식 익스플로잇) 포함 |
| 검증기 엔진 | AI 기반 CVE 재검증: CVE 컨텍스트에서 원시 HTTP 프로브 계획 설계, stdlib 소켓을 통해 실행 |
| 다중 호스트 오케스트레이션 | 호스트당 전체 스캔 파이프라인 → 호스트 간 컨텍스트 및 도달 가능성 매트릭스 → 공격 체인 발견 |
| AI 센서 디렉터 | LLM이 열린 포트, 기술 스택 및 CVE를 기반으로 우선 순위를 지정할 센서 결정 |
| 인증 SSH | 자격 증명 ssh 서브프로세스가 실제 설치된 패키지 버전(60개 이상 제품 매핑) 읽기 |
| 서비스 열거 | 프로토콜 수준 속성 추출(SSH KEX, SMBv1, RDP NLA, SNMP 커뮤니티, HTTP 인증 상태) |
NetLogic을 실행하는 방법은 정확히 두 가지입니다:
| 모드 | 명령어 | 설명 |
|---|---|---|
| 웹 앱 | netlogic --gui | FastAPI 시작 + React SPA 제공 + 인프로세스 스캔 에이전트, 비밀 자동 생성, 브라우저에서 대시보드 열기. 이것이 웹 앱을 실행하는 유일한 방법입니다. |
| CLI | netlogic <target> [flags] | 일회성 터미널 스캔(서버 없음), 보고서 출력/저장 |
제품 표면은 웹 앱(React 대시보드 + FastAPI)입니다. src/ 아래의 스캔 엔진은 UI에서 시작된 작업을 구동합니다.
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 스타일 에이전트를 통해 AI가 자체 도구를 구동하여 리드를 확인하고 공격 체인을 구축할 수 있습니다. 이는 버전/배너 CVE 적중을 확인되지 않은 리드로 남겨두는 대신입니다. AI는 도구 호출을 제안하고, 결정론적 런타임이 이를 실행합니다. 모든 도구는 대상에 범위가 제한되고, 살균되며, 관찰 결과로 기록됩니다. AI는 직접 네트워크에 접촉하지 않습니다.```
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` (헤드리스, JS 챌린지 통과), 그리고 HackerOne 부기
(`record_poc`, `severity_suggest`, `submit_readiness`).
**옵트인 공격적 도구** — 기본적으로 꺼져 있으며, **승인된/소유한 범위 내 대상 전용** (공용 또는 낯선 스캔에서는 절대 사용하지 않음). 각각 `--ai-agent`가 필요합니다:
| 플래그 | 도구 | 해제하는 기능 | 보존된 제약 |
|---|---|---|---|
| `--allow-crash-probes` | `crash_probe` | 큐레이팅된 크래시/DoS CVE 검사 (http.sys, MS15-034)로 호스트를 크래시시킬 수 있음 | 고정된 3-CVE 카탈로그 — 자유 형식 아님 |
| `--allow-freeform-proof` | `http_proof` | 계층 C: 자유 형식 GET/HEAD/OPTIONS (검색/로그인/GraphQL 유사 경로에는 POST 포함) | 파괴적 패턴 + 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
---
## 융합 파이프라인
융합 파이프라인은 **센서 → 게이트 → AI 판정 → 종합**의 단계로 구성되어 기존의 단일 AI 호출을 정밀 게이트로 대체합니다. `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` 딕셔너리 (도달 가능성, WAF, 관점)
- `observed_data` (AI에 전송된 원시 바이트 — 레이블 편향을 방지하기 위해 센서 이름이나 심각도가 아님)
- `ai_view()`는 센서 메타데이터를 제거하고 관찰된 사실만 반환합니다
### 게이트 (`src/fusion/gate.py`)
결정적 합의 — `list[Signal]`을 받아 주제별로 그룹화하여 `list[Verdict]`를 반환합니다:
| 조건 | 판정 |
|---|---|
| KEV 목록에 있음 또는 probe-confirmed 또는 critical+exploit/high-EPSS | **확정** (고정 — 삭제 불가) |
| 2개 이상의 독립적 출처가 일치하고, 1개 이상이 high-reliability | **확정** (단, 모두 version-matched인 경우 → 회색) |
| 단일 low-reliability, low/medium 영향, 상호 확인 없음 | **폐기** |
| 그 외 모든 경우 | **회색** (AI 토큰 소모) |
### AI 판정 (`src/fusion/adjudicator.py`)
회색 영역에만 관여합니다. 코드(프롬프트가 아님)에 안전 제약 조건이 적용됩니다:
- High/critical 회색 항목은 절대 폐기될 수 없음 — 최악의 경우 `potential`로 강등
- 버전 일치 전용 결과는 `potential`로 제한됨 (배포판이 버전 범프 없이 패치를 백포트하는 경우)
- AI는 전체 호스트 컨텍스트에서 새로운 발견 결과도 찾아냅니다
- 소프트 실패: AI 장애 발생 시 회색 영역은 `potential`로 유지 — 데이터 손실 없음
### 종합 (`src/fusion/synthesis.py`)
`build_attack_graph(verdicts)` → 확정된 발견 결과로부터 결정적 도달 가능성 그래프 생성.
`full_synthesize(...)` → 6개 섹션의 AI 보고서:
1. 경영진 요약
2. 주요 발견 결과 (표)
3. 공격 체인 (그래프 기반, LLM이 실제 에지를 설명)
4. 알려진 CVE 외의 항목
5. 오탐 및 노이즈
6. 수정 조치
### 센서
| 센서 | 파일 | 생성 항목 |
|---|---|---|
| 엔진 브리지 | `engine_bridge.py` | 스캔 결과를 NVD, 프로브, 스택, Nuclei, 검증기로부터의 신호로 변환 |
| Wappalyzer | `sensors/wappalyzer.py` | 의존성 없는 Wappalyzer 호환 HTTP 응답 핑거프린팅 |
| Nuclei | `sensors/nuclei.py` | 응답에 대해 YAML 템플릿 실행 (Nuclei 구문의 일부) |
| 카세트 | `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를 통한 호스트 간 탐색, 하위 HostReasoner 인스턴스 생성GoalPlanner가 조사 계획 생성src/reasoning/state.py)src/reasoning/ai/)파이프라인: 생성 → 정규화 → 순위화 → (MetaReasoner 가지치기) → 검증 → 저장
src/deep/에 위치 (7개 파일). --deep-probe와 함께 사용. 컨텍스트 격리 프로브 실행을 위한 서비스별 에이전트 아키텍처.
DeepCoordinator.run() 흐름:
_build_sensor_plan via sensor_director)ScoutAgent 디스패치ProbeAgent 인스턴스 (각각 격리된 CVE/기술 컨텍스트)src/verifier/에 위치 (3개 파일). 대상 프로브를 사용한 AI 기반 CVE 확인.
2단계 재검증 (reverify_with_context)은 전체 호스트 컨텍스트를 제공하여 실패한 테스트를 개선합니다.
src/directors/에 위치 (4개 파일). LLM 기반 스캔 매개변수 선택.
src/orchestrator.py에 위치. 쉼표로 구분된 대상으로 트리거됩니다. 호스트별로 run_scan()을 실행하고, 결과를 집계하며, 결합된 융합 판정에서 교차 호스트 컨텍스트를 구축합니다. 교차 호스트 그룹은 다중 홉 공격 체인 설명을 위해 호스트 간 공유 서비스/버전을 감지합니다.
src/nvd_lookup.py)--nvd-key)src/epss.py): FIRST.org API를 100개 CVE ID 단위로 배치 호출, 24시간 디스크 캐시 (~/.netlogic/epss_cache.json), 실패 시 0.0으로 소프트 실패src/external/nuclei_runner.py는 Nuclei 바이너리(MIT 라이선스)를 래핑합니다. 선택 사항 — 바이너리가 없으면 정상적으로 성능이 저하됩니다. 결과는 융합 파이프라인에 타입화된 Signal로 공급됩니다 (심각도 레이블은 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` — 레이블이 지정된 HTTP 캐셋(`benchmark/*.json` 및 `src/fusion/data/`)에 대한 오프라인 측정. 메트릭:
| 메트릭 | 게이트 임계값 |
|---|---|
| FP 감소 | ≥ 80% |
| 중요 재현율 | = 100% |
두 가지 모드:
- **Oracle** (`--benchmark`): 완벽한 AI 상한선 — 결정론적 메커니즘만 측정
- **Real model** (`--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 의존성이 JWKS에 대해 검증POST /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
---
## 환경 변수
### Controller
| 변수 | 기본값 | 설명 |
|---|---|---|
| `NETLOGIC_ENV` | _(unset)_ | `production`/`prod` = 시작 시 비밀 검증 |
| `NETLOGIC_JWT_SECRET` | `changeme-in-production` | HS256 서명 비밀, 32자 이상 |
| `NETLOGIC_JWT_EXPIRY` | `3600` | JWT 수명(초) |
| `NETLOGIC_ADMIN_KEY` | `admin-changeme` | 관리자 자격 증명, 프로덕션에서는 32자 이상 |
| `NETLOGIC_API_KEYS` | _(empty)_ | 시드 키: `key1:org1,key2:org2,...` |
| `NETLOGIC_CORS_ORIGINS` | _(empty)_ | 허용된 출처(비어 있으면 CORS 비활성화) |
| `NETLOGIC_PORT` | `8000` | 바인드 포트 |
| `NETLOGIC_HOST` | `0.0.0.0` | 바인드 주소 |
| `NETLOGIC_NO_BROWSER` | _(unset)_ | `1`은 자동 열기 비활성화 |
| `NETLOGIC_OIDC_ISSUER` | _(unset)_ | Clerk Frontend API URL → OIDC 로그인 |
| `NETLOGIC_OIDC_AUDIENCE` | _(unset)_ | OIDC 대상 |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(unset)_ | OIDC 사용자를 위한 대체 org_id |
| `NETLOGIC_DATABASE_URL` | _(unset)_ | PostgreSQL 연결 문자열 |
| `NETLOGIC_SECRETS_KEY` | _(unset)_ | 저장된 자격 증명을 위한 Fernet 키 |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | 에이전트 토큰 유효 기간(7일) |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | 에이전트당 최대 대기 작업 수 |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | 최대 등록 에이전트 수 |
| `NETLOGIC_AI_PROVIDER` | `openrouter` | 기본 AI 제공자 |
| `NETLOGIC_AI_API_KEY` | _(empty)_ | 기본 AI 키 |
| `NETLOGIC_AI_MODEL` | provider default | 기본 모델 |
| `NETLOGIC_AI_BASE_URL` | provider default | 사용자 지정 기본 URL |
| `NETLOGIC_NVD_KEY` | _(empty)_ | NVD API 키 |
| `NETLOGIC_VALID_LICENSES` | _(empty)_ | 개발/테스트 라이선스 재정의 |
| `NETLOGIC_LICENSE_KEY` | _(empty)_ | 인스턴스 라이선스 키 |
| `NETLOGIC_SCANS_DIR` | _(default)_ | 스캔 저장 디렉터리 |
| `NETLOGIC_SIEM_ENDPOINT` | _(empty)_ | 감사 로그 전송 URL |
| `NETLOGIC_WAPPALYZER_DATA` | _(built-in)_ | Wappalyzer 지문 경로 |
### Agent
| 변수 | 기본값 | 설명 |
|---|---|---|
| `NETLOGIC_CONTROLLER` | `http://localhost:8000` | 컨트롤러 기본 URL |
| `NETLOGIC_API_KEY` | _(unset)_ | 등록을 위한 API 키 |
---
## 보안 아키텍처
### 미들웨어 스택(적용 순서)
1. **AuditMiddleware** — `X-Request-ID` 상관 관계, 구조화된 JSON 감사 로그, SIEM 전송
2. **RequestSizeLimitMiddleware** — 10MB 본문 제한(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** — POST/PUT/DELETE Origin 검증(심층 CSRF 방어)
6. **CORSMiddleware** — 제한적: 와일드카드 없음, 특정 출처만 허용
### 인증
- **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). 10분 내에 5회 토큰 교환 실패 시 IP 차단(1시간 차단).
### 데이터 보호
- LLM API 키: 저장 시 Fernet 암호화(AES-128-CBC + HMAC-SHA256). 프로덕션에서는 폐쇄 실패: `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 jobs:
pip-auditnpm ci + npm run buildNetLogic은 승인된 보안 평가, 침투 테스트 및 네트워크 관리 목적으로만 사용됩니다. 명시적인 서면 허가 없이 호스트를 스캔하거나 프로브하는 것은 대부분의 관할권에서 불법입니다. 저자는 승인되지 않은 사용에 대해 책임을 지지 않습니다.
MIT © 2026 Dmitry Flynn — LICENSE.txt 참조
| 토폴로지 매퍼 |
| 역방향 DNS, IPv6, traceroute, ip-api.com을 통한 ASN/조직/국가 |
| 도달 가능성 프로버 | 서브넷 인접성을 통한 사후 침해 측면 이동 매트릭스 |
| 네트워크 프로버 | 활성 서브넷 스위프(/24 사설 이웃)와 2단계 발견(라이브 스위프 → 전체 포트 스캔) |
| 스캔 차이 | 시간 경과에 따른 변경: 대상별 가장 최근 이전 JSON 보고서와 현재 스캔 비교 |
| 라이선스 관리 | 키 활성화를 통한 상용 라이선스 시스템(Stripe/Paddle/Lemon Squeezy 스텁) |
| 조직별 AI 구성 | 각 조직이 Fernet을 통해 저장된 자체 LLM 자격 증명을 암호화 |
| OIDC / Clerk | Clerk에서 발급한 세션 JWT를 확인하여 공개 JWKS로 사람 로그인, 자동 프로비저닝 포함 |
| PostgreSQL | 자동 적용 마이그레이션(스캔 작업, 조직 설정, 추론 상태, 감사)을 통한 완전한 멀티 테넌트 영속성 |
| 퓨전 벤치마크 | 기록된 HTTP 캐셋에 대한 오프라인 벤치마크; 정밀도/재현율/중요 재현율/FP 감소 메트릭 |
| Format | Example | Mode |
|---|
| Hostname | example.com | 단일 호스트 스캔 |
| IPv4 | 10.0.0.5 | 단일 호스트 스캔 |
| CIDR | 192.168.1.0/24 | CIDR 스윕 (스캐너 전용, 융합 없음) |
| Comma-separated | target1,target2 | 다중 호스트 오케스트레이션 (호스트 간 컨텍스트) |
ReasoningValidator 무결성 감사 → ProvenanceBuilder가 엣지 기록 → 상태 영속화| 레이어 | 클래스 | 추적하는 내용 |
|---|
| WorldModel | WorldModel | EvidenceGraph, 관찰, 신념, 호스트, 기술, 도달 가능성 |
| InvestigationState | InvestigationState | 목표(DAG), 가설, 모순, 막다른 길, 현재 페르소나 |
| ExecutionState | ExecutionState | 예산, probe_history, 출처, 조사 계획, AI 기록 |
| LearnedPatterns | LearnedPatterns | 스캔 간 휴리스틱 + 플레이북 |
| 구성 요소 | 파일 | 설명 |
|---|
| EvidenceGraph | evidence_graph.py | 중복 제거된 시간적 엔터티 그래프 (SHA-256을 통한 콘텐츠 주소 지정 관찰) |
| 가설 엔진 | hypothesis.py | 가능성, 엔트로피, 정보 이득, 사후 해소를 포함한 경쟁 후보 |
| ConfidenceEngine | confidence.py | 개별 소스에 대한 Noisy-OR; 버전 전용은 0.60으로 제한됨; KEV/프로브는 0.97로 고정 |
| ProvenanceBuilder | provenance.py | 관찰→추론→가설 엣지, 콘텐츠 해시 주소 지정 |
| Scheduler | scheduler.py | 정보 이득 기반 액션 선택, explore_reserve(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 | 프로브 검증 + 실행 + 추적 (범위 → 읽기 전용 → 예산 → 중복 제거 → 깊이) |
| 플레이북 시스템 | playbooks.py | 트리거 조건 및 의도 템플릿이 있는 YAML 플레이북 |
| 변경 감지 | change_detection.py | 7단계: 불변 관찰(상태 아님) 비교, DeltaEvents의 ScanDelta 생성 |
| 능동 검증 | active_validation.py | 8b단계: ActionGate를 통한 비파괴적 SAFE_ACTIVE 프로브 |
| 파일 | 구성 요소 |
|---|
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 | 전체 딥 파이프라인 오케스트레이션: AI 센서 계획 → ScoutAgent → 서비스별 ProbeAgent → 서비스 열거 → Nuclei → 검증기 → 인수 → 서브넷 프로브 → 토폴로지 → 인증 → diff → 도달 가능성 |
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개의 내장 계획 확인 → AI가 원시 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 | 인접 호스트 중 프로브할 대상, 포트, 깊이 (skip/quick/standard/deep) |