---

## CLI 参考```
netlogic [target] [flags]

### 端口选择```
# 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

### 支持的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

该代理默认拥有约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

### 基准测试```
# 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

### NVD 缓存管理```
netlogic --cache-stats
netlogic example.com --nvd-key YOUR_NVD_KEY

---

## 融合流程

融合流程是一个 **传感器 → 门控 → 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 或探针确认或严重+利用/高 EPSS | **已确认**（固定——不可丢弃） |
| ≥2 个独立来源一致，且 ≥1 个高可靠性 | **已确认**（除非全部版本匹配 → 灰色） |
| 单个低可靠性、低/中影响、无佐证 | **已丢弃** |
| 其他所有情况 | **灰色**（消耗一个 AI token） |

### AI 裁决 (`src/fusion/adjudicator.py`)

仅处理灰色区域。安全约束在代码中强制执行（而非提示）：
- 高/严重灰色项目绝不能丢弃——最坏情况下降级为 `potential`
- 仅版本匹配限制为 `potential`（发行版可能在不增加版本号的情况下进行向后移植）
- AI 还会从完整的主机上下文中发现新发现
- 软故障：AI 故障时灰色区域保持为 `potential` —— 无静默数据丢失

### 综合 (`src/fusion/synthesis.py`)

`build_attack_graph(verdicts)` → 从 CONFIRMED 发现中生成确定性的可达性图。
`full_synthesize(...)` → 6 部分 AI 报告：
1. 执行摘要
2. 关键发现（表格）
3. 攻击链（基于图，LLM 描述真实边）
4. 已知 CVE 之外
5. 误报与噪音
6. 修复建议

### 传感器

| 传感器 | 文件 | 输出内容 |
|---|---|---|
| 引擎桥接 | `engine_bridge.py` | 将扫描产物转换为来自 NVD、探针、栈、Nuclei、验证器的 Signal |
| 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/fusion/benchmark.py` — 离线测量，与标记的 HTTP 磁带进行对比（`benchmark/*.json` 和 `src/fusion/data/`）。指标：

| 指标 | 门限阈值 |
|---|---|
| FP 降低 | ≥ 80% |
| 关键召回率 | = 100% |

两种模式：
- **Oracle**（`--benchmark`）：完美 AI 上限 —— 仅测量确定性机制
- **真实模型**（`--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

### 职位```
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

### 许可证 / 设置```
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

---

## 环境变量

### 控制器

| 变量 | 默认值 | 描述 |
|---|---|---|
| `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 前端 API 地址 → OIDC 登录 |
| `NETLOGIC_OIDC_AUDIENCE` | _(unset)_ | OIDC 受众 |
| `NETLOGIC_OIDC_DEFAULT_ORG` | _(unset)_ | OIDC 用户的后备组织 ID |
| `NETLOGIC_DATABASE_URL` | _(unset)_ | PostgreSQL 连接字符串 |
| `NETLOGIC_SECRETS_KEY` | _(unset)_ | Fernet 密钥用于静态凭据加密 |
| `NETLOGIC_AGENT_TOKEN_MAX_AGE` | `604800` | Agent 令牌生命周期（7天） |
| `NETLOGIC_AGENT_PENDING_CAP` | `50` | 每个 Agent 的最大排队任务数 |
| `NETLOGIC_MAX_AGENTS_PER_ORG` | `100` | 最大注册 Agent 数 |
| `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)_ | 审计日志传输地址 |
| `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** — 10 MB 请求体限制（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，首次登录时自动配置用户和组织
- **Agent 令牌**：注册表中 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