dsh-pentester 0.0.1 → 1.0.0

package/README.md

@@ -1,13 +1,47 @@
 # dsh-pentester
 
-Pentesting agent plugin for DeepSeek Harness.
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的最小化 Root-Orchestrator PTES 渗透测试插件。
 
-## Install
+**唯一事实来源是 [`docs/plan.md`](docs/plan.md)**；架构视图见 [`docs/architecture.md`](docs/architecture.md)，磁盘布局见 [`docs/workspace.md`](docs/workspace.md)，领域术语见 [`CONTEXT.md`](CONTEXT.md)。
+
+## 心智模型
+
+```
+User ⇄ DSH Root Session（pentester persona preset）
+   → Root 是唯一 Orchestrator：判断缺口、派发 Delegation、决定推进/回溯阶段
+   → Root 工具面 4 个：pentester_delegate / pentester_cancel_delegation /
+     pentester_advance_stage / pentester_rollback_stage
+   → Root 每次 reasoning 前注入 compact run state（target/branch/stage/delegations）
+Delegation（并行多个）= 各一个 DSH child session（AgentProfile + 不可变 task_prompt）
+   → Worker 工具只有 pentester_container_exec（dockerode；Root 不可见）
+   → Worker 写完 result.md 即完成任务（完成标志）；缺失 → failed
+Deliverable = 文件（workspace/stages/<NN>-<stage>/delegations/D-00N/）
+```
+
+## 安装
 
 ```bash
+# github 源
+dsh plugin --profile web add github:fb0sh/dsh-pentester
+# npm 源
 dsh plugin --profile web add dsh-pentester
-````
+```
+
+## 布局
 
-## Status
+| 目录/文件 | 职责 |
+| --- | --- |
+| `src/` | model/stages/profiles/store、workspace/git、dsh/delegations/tools/worker-tools、docker/（host/connection/images/runtime）、rpc/settings-store、index |
+| `src/ui/client/` | Settings 的 “Pentester Config” 页（Tab：Docker Engine） |
+| `agents/*/profile.yml` | 7 个 AgentProfile（systemPrompt/skills/mcpServers） |
+| `docker/` | Toolbox Dockerfile（kali 等，镜像白名单来源） |
+| `presets/pentester/` | Root persona preset + `run-state.mjs`（工具面限制 + 动态状态注入） |
+
+## 开发
+
+```bash
+pnpm run check   # typecheck + build（含 client bundle）
+pnpm test        # node --test
+```
 
-Early development.
+Docker host 优先级：Settings（settings.json）> 插件配置 > 本地 socket 自动发现 > `DOCKER_HOST` > 默认 socket。本地 Docker 用 bind mount（host workspace == 容器 /workspace）；远程 daemon 用共享 volume，阶段边界才做 mirror sync。

package/agents/impact/profile.yml

@@ -0,0 +1,19 @@
+id: impact
+name: Post Exploitation Agent
+description: Impact assessment: lateral reach, data exposure, business consequences.
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Post Exploitation specialist of an authorized pentest run.
+  Method: from verified footholds, assess blast radius, data exposure and
+  business impact. Enumerate what is reachable rather than taking
+  destructive actions. Quantify or clearly describe business consequences
+  and record cleanup/recovery actions taken. Write your assessment
+  (impact-assessment.md ...) into your delegation directory
+  /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/ (artifacts/ for final
+  outputs, evidence/ for proof, work/ for scratch). Stay strictly inside the
+  recorded targets and RoE. Never modify .git/, .dsh-pentester/, other
+  delegation directories or target/. Never run git commands. When the task is
+  finished, write result.md in your delegation directory — it is the
+  completion marker. Write all content (except tool raw output) in the
+  language of your task_prompt (the user's language).

package/agents/recon/profile.yml

@@ -0,0 +1,23 @@
+id: recon
+name: Recon Agent
+description: Intelligence gathering over in-scope targets (network, service and OSINT surface).
+# Skills / MCP are attached by DSH presets (deferred wiring; names are reserved).
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Recon specialist of an authorized pentest run.
+  Method: enumerate in-scope services and endpoints, fingerprint technology
+  stacks, and record structured facts. Prefer passive or low-noise techniques
+  first. Never rescan what earlier deliverables already cover — read
+  /workspace first: /workspace/target/ and earlier stage dirs under
+  /workspace/stages/ (including sibling D-* deliverable dirs).
+  Write your outputs (assets.json / services.json / notes.md ...) into YOUR
+  delegation directory /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/:
+  work/ for scratch, artifacts/ for final outputs, evidence/ for reproducible
+  evidence (commands + outputs). Every claim must be reproducible from the
+  command output you keep. Stay strictly inside the recorded targets and RoE.
+  Never modify .git/, .dsh-pentester/, other delegation directories or
+  target/. Never run git commands; the host owns git checkpoints. When the
+  task is finished, write result.md in your delegation directory — it is the
+  completion marker. Write all content (except tool raw output) in the
+  language of your task_prompt (the user's language).

package/agents/reporting/REPORT_TEMPLATE.md

@@ -0,0 +1,333 @@
+# {目标名称} 渗透测试报告
+
+**报告编号**: PT-{YYYY}-{MMDD}-{PROJECT}
+**测试目标**: {目标 IP/域名}
+**测试日期**: {开始日期}
+**报告日期**: {报告日期}
+**报告分类**: 机密
+**测试框架**: PTES (Penetration Testing Execution Standard)
+
+---
+
+## 目录
+
+1. [执行摘要](#1-执行摘要)
+2. [测试范围与授权](#2-测试范围与授权)
+3. [测试方法论](#3-测试方法论)
+4. [技术发现详述](#4-技术发现详述)
+5. [攻击链分析](#5-攻击链分析)
+6. [影响评估](#6-影响评估)
+7. [修复优先级建议](#7-修复优先级建议)
+8. [清理记录](#8-清理记录)
+9. [附录](#9-附录)
+
+---
+
+## 1. 执行摘要
+
+### 1.1 测试概述
+
+{一段话概述测试目标、技术栈、端口/服务范围}
+
+### 1.2 核心结论
+
+**整体风险等级: {CRITICAL / HIGH / MEDIUM / LOW}**
+
+{一句话总结最重要的发现}
+
+### 1.3 关键发现
+
+| 严重性 | 漏洞数量 | 关键漏洞 |
+|--------|----------|----------|
+| 🔴 CRITICAL | {N} | {列出 CRITICAL 漏洞名} |
+| 🟡 HIGH | {N} | {列出 HIGH 漏洞名} |
+| 🟠 MEDIUM | {N} | {列出 MEDIUM 漏洞名} |
+| 🟢 LOW | {N} | {列出 LOW 漏洞名} |
+
+### 1.4 业务影响
+
+- {影响点 1}
+- {影响点 2}
+- {影响点 3}
+
+### 1.5 最快攻击路径
+
+```
+{描述最高效的攻击链，从入口到完全控制}
+```
+
+---
+
+## 2. 测试范围与授权
+
+### 2.1 测试范围
+
+| 属性 | 值 |
+|------|-----|
+| **主要目标** | {IP/域名} |
+| **端口范围** | {端口列表} |
+| **应用范围** | {应用描述} |
+| **排除项** | {排除项，无则填"无"} |
+
+### 2.2 交战规则 (Rules of Engagement)
+
+- ✅ {允许的操作}
+- ❌ {禁止的操作}
+- 范围仅限 {范围}
+
+### 2.3 授权
+
+{授权说明}
+
+---
+
+## 3. 测试方法论
+
+本次渗透测试严格遵循 **PTES (Penetration Testing Execution Standard)** 标准，按七个阶段依次执行：
+
+### 3.1 预参与阶段 (Pre-engagement)
+{预参与阶段做了什么}
+
+### 3.2 情报收集 (Intelligence Gathering)
+{情报收集阶段做了什么，使用了哪些工具和技术}
+
+### 3.3 威胁建模 (Threat Modeling)
+{威胁建模阶段做了什么，使用了什么框架}
+
+### 3.4 漏洞分析 (Vulnerability Analysis)
+{漏洞分析阶段做了什么，验证了哪些攻击路径}
+
+### 3.5 利用 (Exploitation)
+{利用阶段做了什么，实现了哪些攻击}
+
+### 3.6 后利用 (Post-exploitation)
+{后利用阶段做了什么，评估了持久化和横向移动}
+
+### 3.7 报告 (Reporting)
+{报告阶段说明}
+
+---
+
+## 4. 技术发现详述
+
+{每个发现一个独立小节，按严重性从高到低排列}
+
+---
+
+### F-001: {漏洞名称}
+
+| 属性 | 值 |
+|------|-----|
+| **严重性** | {🔴 CRITICAL / 🟡 HIGH / 🟠 MEDIUM / 🟢 LOW} |
+| **CVSS 3.1 评分** | **{X.X}** |
+| **CVSS 向量** | `CVSS:3.1/{向量}` |
+| **CWE** | {CWE-XXX: 描述} |
+| **发现阶段** | {阶段名称} |
+| **利用验证** | {阶段名称} |
+
+#### 漏洞描述
+
+{清晰描述漏洞原理}
+
+#### CVSS 向量解析
+
+| 度量 | 值 | 说明 |
+|------|-----|------|
+| AV:N | {值} | {说明} |
+| AC:L | {值} | {说明} |
+| PR:N | {值} | {说明} |
+| UI:N | {值} | {说明} |
+| S:C | {值} | {说明} |
+| C:H | {值} | {说明} |
+| I:H | {值} | {说明} |
+| A:H | {值} | {说明} |
+
+#### 复现步骤
+
+{详细复现步骤，包含具体命令和参数}
+
+#### 影响
+
+- {影响点 1}
+- {影响点 2}
+- {影响点 3}
+
+#### 证据
+
+- {证据文件路径 1}
+- {证据文件路径 2}
+
+#### 修复建议
+
+1. {修复建议 1}
+2. {修复建议 2}
+3. {修复建议 3}
+
+---
+
+### F-002: {漏洞名称}
+
+{同上结构}
+
+---
+
+{继续添加更多发现...}
+
+---
+
+## 5. 攻击链分析
+
+### 5.1 最快攻击路径
+
+```
+{描述最高效攻击路径}
+```
+
+### 5.2 完整攻击链
+
+```
+{描述完整攻击链，分阶段展示}
+```
+
+### 5.3 攻击链组合
+
+{使用 mermaid 流程图描绘攻击链组合}
+
+```mermaid
+flowchart LR
+    A[匿名攻击者] --> B{选择入口}
+    B -->|路径 A| C[入口A]
+    B -->|路径 B| D[入口B]
+    C --> E[权限]
+    D --> E
+    E --> F[目标]
+```
+
+---
+
+## 6. 影响评估
+
+### 6.1 数据泄露统计
+
+| 数据类型 | 数量 | 敏感度 | 详情 |
+|----------|------|--------|------|
+| {数据类型} | {数量} | {🔴 高 / 🟡 中 / 🟢 低} | {详情} |
+
+### 6.2 泄露的 PII 详情
+
+| 用户 | 邮箱 | 手机号 | 收货地址 |
+|------|------|--------|----------|
+| {用户名} | {邮箱} | {手机号} | {地址} |
+
+### 6.3 CIA 三元组评估
+
+| 维度 | 等级 | 说明 |
+|------|------|------|
+| **机密性** (Confidentiality) | {等级} | {说明} |
+| **完整性** (Integrity) | {等级} | {说明} |
+| **可用性** (Availability) | {等级} | {说明} |
+
+### 6.4 合规风险
+
+- {合规风险 1}
+- {合规风险 2}
+
+### 6.5 持久化评估
+
+| 持久化方式 | 可行性 | 隐蔽性 | 持久性 | 说明 |
+|-----------|--------|--------|--------|------|
+| {方式} | {✅/❌} | {高/中/低} | {高/中/低} | {说明} |
+
+### 6.6 横向移动
+
+{横向移动评估}
+
+---
+
+## 7. 修复优先级建议
+
+### 7.1 P0 — 立即修复（24 小时内）
+
+| # | 修复项 | 关联漏洞 | 修复方法 |
+|---|--------|---------|---------|
+| 1 | **{修复项}** | {漏洞ID} | {具体修复方法} |
+
+### 7.2 P1 — 尽快修复（1 周内）
+
+| # | 修复项 | 关联漏洞 | 修复方法 |
+|---|--------|---------|---------|
+
+### 7.3 P2 — 计划修复（1 月内）
+
+| # | 修复项 | 关联漏洞 | 修复方法 |
+|---|--------|---------|---------|
+
+---
+
+## 8. 清理记录
+
+### 8.1 已完成的清理
+
+| 操作 | 目标 | 状态 |
+|------|------|------|
+| {操作} | {目标} | ✅ |
+
+### 8.2 无法清理的项目
+
+| 项目 | 数量 | 原因 |
+|------|------|------|
+| {项目} | {数量} | {原因} |
+
+### 8.3 建议的后续清理
+
+1. {建议 1}
+2. {建议 2}
+
+---
+
+## 9. 附录
+
+### 9.1 技术栈总览
+
+```
+{技术栈架构图}
+```
+
+### 9.2 API 端点汇总
+
+**公开端点** ({N} 个):
+{列出公开端点}
+
+**需认证端点** ({N} 个):
+{列出需认证端点}
+
+**管理员端点** ({N} 个):
+{列出管理员端点}
+
+### 9.3 漏洞汇总表
+
+| ID | 漏洞名称 | 严重性 | CVSS | CWE | 阶段 |
+|----|---------|--------|------|-----|------|
+| F-001 | {名称} | {严重性} | {CVSS} | {CWE} | {阶段} |
+
+### 9.4 交付物路径
+
+| 阶段 | 路径 |
+|------|------|
+| 预参与 | `/workspace/stages/01-pre-engagement/summary.md` |
+| 情报收集 | `/workspace/stages/02-intelligence-gathering/` |
+| 威胁建模 | `/workspace/stages/03-threat-modeling/` |
+| 漏洞分析 | `/workspace/stages/04-vulnerability-analysis/` |
+| 利用 | `/workspace/stages/05-exploitation/` |
+| 后利用 | `/workspace/stages/06-post-exploitation/` |
+| 报告 | `/workspace/report/report.md` |
+
+### 9.5 测试账号
+
+{列出测试期间创建的账号，建议后续清理}
+
+---
+
+**报告结束**
+
+*本报告为 {目标名称} 渗透测试的最终交付物，包含全部确认漏洞的详细分析、攻击链演示、影响评估和修复建议。报告仅供授权人员查阅，请勿外传。*

package/agents/reporting/profile.yml

@@ -0,0 +1,45 @@
+id: reporting
+name: Reporting Agent
+description: Final report assembly from the full pentest deliverable tree.
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Reporting specialist of an authorized pentest run.
+  Method: read the ENTIRE workspace deliverable tree — /workspace/stages/
+  (all stage dirs with summary.md and delegation dirs), /workspace/findings/,
+  /workspace/target/ — then write
+  the final report to /workspace/report/report.md (your delegation directory
+  is /workspace/stages/07-reporting/delegations/<D-XXX>/, but the report must
+  land in /workspace/report/). The report must cover: scope and RoE,
+  methodology per stage, confirmed findings (each with evidence references,
+  impact and remediation advice), unverified items with reasons, and an
+  executive summary. report.md is the canonical human-readable deliverable.
+
+  REPORT STRUCTURE — follow this exact template. Read
+  /pentester/REPORT_TEMPLATE.md for the full section-by-section structure.
+  The nine required sections are:
+
+  1. Executive Summary — overview, risk rating, key findings table, business
+     impact, fastest attack path.
+  2. Scope & Authorization — target table, RoE checklist, authorization.
+  3. Methodology — one subsection per PTES stage, what was done and how.
+  4. Technical Findings — one subsection per finding (F-001, F-002, ...),
+     each with: severity, CVSS 3.1 score + vector, CWE, discovery/exploitation
+     stage, description, CVSS vector breakdown table, reproduction steps,
+     impact, evidence paths, and numbered remediation advice.
+  5. Attack Chain Analysis — fastest path, full chain, mermaid flowchart.
+  6. Impact Assessment — data leak statistics, PII detail table, CIA triad
+     table, compliance risk, persistence table, lateral movement.
+  7. Remediation Priority — P0 (24h), P1 (1 week), P2 (1 month) tables with
+     fix item, associated finding, and concrete fix method.
+  8. Cleanup Record — completed cleanup table, items that could not be
+     cleaned up with reasons, recommended follow-up cleanup.
+  9. Appendix — tech stack diagram, API endpoint summary (public /
+     authenticated / admin), findings summary table, deliverable paths,
+     test accounts.
+
+  Never modify .git/, .dsh-pentester/, other delegation directories or
+  target/. Never run git commands. When the task is finished, write result.md
+  in your delegation directory — it is the completion marker. Write all
+  content (except tool raw output) in the language of your task_prompt (the
+  user's language).

package/agents/threat-model/profile.yml

@@ -0,0 +1,19 @@
+id: threat-model
+name: Threat Modeling Agent
+description: Attacker-view modeling of entry points, trust boundaries and attack paths.
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Threat Modeling specialist of an authorized pentest run.
+  Method: from the intelligence deliverables (/workspace/assets/,
+  /workspace/stages/02-intelligence-gathering/), model entry points, trust
+  boundaries, high-value assets and candidate attack paths. Rank paths by
+  impact and feasibility, and produce a prioritized verification list for
+  the vulnerability analysis stage. Write threat-model.md into your delegation
+  directory /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/ (artifacts/
+  for final outputs). This is an analysis task: you normally do not need
+  intrusive tooling; cite the deliverable files you rely on. Never modify
+  .git/, .dsh-pentester/, other delegation directories or target/. Never run
+  git commands. When the task is finished, write result.md in your delegation
+  directory — it is the completion marker. Write all content (except tool raw
+  output) in the language of your task_prompt (the user's language).

package/agents/validation/profile.yml

@@ -0,0 +1,20 @@
+id: validation
+name: Exploitation Validation Agent
+description: Controlled verification of exploitability and impact within RoE.
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Exploitation Validation specialist of an authorized pentest run.
+  Method: validate only previously identified candidate issues, with the
+  minimum intensity that proves or disproves exploitability. Keep every
+  step reproducible and evidence-backed (write validation-results.md and
+  evidence into your delegation directory
+  /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/: artifacts/ for final
+  outputs, evidence/ for proof, work/ for scratch).
+  Explicitly respect the Rules of Engagement: no destructive actions, no
+  persistence beyond what the RoE allows, and record cleanup steps. Report
+  unvalidated items with reasons. Never modify .git/, .dsh-pentester/, other
+  delegation directories or target/. Never run git commands. When the task is
+  finished, write result.md in your delegation directory — it is the
+  completion marker. Write all content (except tool raw output) in the
+  language of your task_prompt (the user's language).

package/agents/vulnerability/profile.yml

@@ -0,0 +1,19 @@
+id: vulnerability
+name: Vulnerability Analysis Agent
+description: Candidate vulnerability identification and assessment with evidence.
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Vulnerability Analysis specialist of an authorized pentest run.
+  Method: verify candidate issues from the threat model in priority order.
+  Every candidate finding must carry reproducible evidence (command + output
+  kept in evidence/), a confidence level, and a recommended validation
+  approach. Write findings.md (and supporting files) into your delegation
+  directory /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/ (artifacts/
+  for final outputs, evidence/ for proof, work/ for scratch). Distinguish
+  confirmed facts from inference. Stay strictly inside the recorded targets
+  and RoE. Never modify .git/, .dsh-pentester/, other delegation directories
+  or target/. Never run git commands. When the task is finished, write
+  result.md in your delegation directory — it is the completion marker. Write
+  all content (except tool raw output) in the language of your task_prompt
+  (the user's language).

package/agents/web/profile.yml

@@ -0,0 +1,19 @@
+id: web
+name: Web & API Agent
+description: Web application and API analysis (routing, auth, input handling, tech stack).
+skills:
+mcpServers:
+systemPrompt: |
+  You are the Web/API specialist of an authorized pentest run.
+  Method: map routes and endpoints, understand authentication and session
+  handling, then probe input handling and business logic for candidate
+  issues. Reuse recon deliverables; do not re-enumerate what is already
+  known. Record requests/responses that support each candidate issue in
+  your delegation directory /workspace/stages/<NN>-<stage>/delegations/<D-XXX>/
+  (evidence/ for request/response pairs, artifacts/ for final outputs,
+  work/ for scratch). Stay strictly inside the recorded targets and RoE;
+  never attempt destructive actions. Never modify .git/, .dsh-pentester/,
+  other delegation directories or target/. Never run git commands. When the
+  task is finished, write result.md in your delegation directory — it is the
+  completion marker. Write all content (except tool raw output) in the
+  language of your task_prompt (the user's language).

package/cordis.dev.patch.yml

@@ -0,0 +1,16 @@
+# Development overlay. Not shipped as the default plugin patch.
+# Enable the canonical DEV fixture Engagement (opt-in only):
+#
+#   dsh web --patch ./cordis.dev.patch.yml
+#
+# or merge this insert into a development profile. Production `cordis.patch.yml`
+# must not set devSeed.
+- insert:
+    - id: dsh-pentester
+      name: dsh-pentester
+      config:
+        verbose: true
+        devSeed: true
+        # UI Preview: presentation-only sample data for inspecting the layouts.
+        # Independent of devSeed; uncomment to enable without creating fixture state.
+        # uiPreview: true

package/cordis.patch.yml

@@ -1,3 +1,5 @@
 - insert:
     - id: dsh-pentester
       name: dsh-pentester
+      config:
+        verbose: true

package/docker/README.md

@@ -0,0 +1,60 @@
+# Toolbox 镜像构建
+
+唯一工厂镜像：`fb0sh/dsh-pentester-kali`（目录与工具契约见 `docs/architecture.md`；
+**镜像内工具清单与路径见 [`docker/kali/README.md`](kali/README.md)**）。
+
+## 构建
+
+```bash
+# 一键构建 + 推送（推荐）：版本号在脚本顶部 VERSION 变量
+bash scripts/build-docker-image.sh
+```
+
+脚本等价于：
+
+```bash
+VERSION="1.0.0"
+
+docker buildx build \
+  --add-host host.docker.internal=host-gateway \
+  --build-arg HTTP_PROXY=http://host.docker.internal:7890 \
+  --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
+  --build-arg NO_PROXY=localhost,127.0.0.1 \
+  --build-arg http_proxy=http://host.docker.internal:7890 \
+  --build-arg https_proxy=http://host.docker.internal:7890 \
+  --build-arg no_proxy=localhost,127.0.0.1 \
+  --build-arg WITH_KB=1 \
+  --build-arg KEEP_KB_GIT=0 \
+  --build-arg DSH_PENTESTER_KALI_VERSION="$VERSION" \
+  --build-arg KALI_SOURCES="deb https://mirrors.tuna.tsinghua.edu.cn/kali kali-rolling main contrib non-free non-free-firmware" \
+  --load \
+  -t "fb0sh/dsh-pentester-kali:${VERSION}" \
+  -t fb0sh/dsh-pentester-kali:latest \
+  --push \
+  docker/kali
+```
+
+## 构建 ARG
+
+| ARG | 默认 | 说明 |
+| --- | --- | --- |
+| `http_proxy` / `https_proxy` / `HTTP_PROXY` / `HTTPS_PROXY` | 空（直连） | 构建期代理（apt / go / wget / pipx）；BuildKit 原生 proxy build args |
+| `KALI_SOURCES` | 空（官方源） | 自定义 `/etc/apt/sources.list` 全文；kali-base 阶段生效 |
+| `WITH_KB` | `1` | 知识库层（vulhub / PayloadsAllTheThings / Awesome-POC / exphub → `/pentester/kb/`） |
+| `KEEP_KB_GIT` | `0` | 保留各 KB 顶层 `.git`（默认删除，显著减小体积） |
+| `DSH_PENTESTER_KALI_VERSION` | 必填 | 版本号：写入 OCI label、`DSH_PENTESTER_KALI_VERSION` env 与 `/pentester/VERSION`；构建自检校验非空 |
+
+## 构建要点
+
+- **多阶段构建**：
+  - `kali-base` —— Kali sources / CA / archive keyring（含自定义 https 源的 http 引导装 CA 流程）
+  - `gobuilder` —— 编译 Go 工具族（httpx / katana / naabu / dnsx / interactsh-client / gospider / gron / usql / fofax / red-tldr），产物 `/out/bin` → `/pentester/tools/bin`
+  - `kb-builder` —— 独立 clone 知识库（`/opt/kb` 暂存，`KEEP_KB_GIT=0` 剥离 .git），`COPY` 到 `/pentester/kb`
+  - `runtime` —— APT 装配 + 自定义工具 + 自检
+- **STABLE APT AREA**：1～9 类稳定工具在一个 APT transaction 内安装（基础 / 网络 / 发现 / OSINT / Web / 凭据 / SMB-AD / 字典 / 取证），APT lists/cache 走 BuildKit cache mount 不落镜像层；新增工具追加到 **EXTRA TOOLS** 区域，不要改稳定层。
+- **工具目录构建期生成**：`bin/gen-tools-json.sh` 用 `command -v` 探测产出 `/pentester/tools.json` —— 装漏的工具不会进目录，Agent 看到的目录与实际可执行工具永远一致。
+- **构建期自检**：验证核心二进制 / pipx 工具 / jar / 数据包 / tools.json / VERSION 一致性，任一缺失镜像直接 build fail。
+- **构建代理不泄漏**：不通过 ENV 写代理，成品镜像无 `http_proxy` 等残留。
+- **Agent Prompt 随镜像发布**：`docker/kali/TOOL_PROMPT.md` → `/pentester/PROMPT.md`。
+- 版本号唯一来源为 `DSH_PENTESTER_KALI_VERSION`（构建脚本顶部 `VERSION` 变量），写入 OCI label 与 `/pentester/VERSION`。
+- 镜像内分类工具清单与安装路径：见 [`docker/kali/README.md`](kali/README.md)。