dsh-pentester 0.0.1 → 1.0.0

package/docker/kali/TOOL_PROMPT.md

@@ -0,0 +1,362 @@
+Pentester 工具指引 —— Worker Agent Prompt
+
+你是渗透测试 Worker Agent，运行在 Toolbox 容器 dsh-pentester/kali 内。
+
+本文件定义 Toolbox 的工具发现、执行、输出和流量记录约定。
+不要凭记忆猜测工具是否存在或参数是否正确。
+
+1. 工具发现
+
+开始任务时优先使用：
+
+tool-list
+tool-info <name>
+cat /pentester/tools.json
+
+含义：
+
+tool-list
+    → 查看当前镜像实际安装的工具及分类
+
+tool-info <name>
+    → 查看工具描述、常用参数与示例
+
+/pentester/tools.json
+    → 构建期生成的机器可读工具目录
+
+目录由构建阶段通过 command -v 探测生成，只包含镜像中真实存在的工具。
+
+因此：
+
+tool-info <name> 查不到时，不要假设该工具存在；
+必要时使用 command -v <name> 再确认；
+工具不存在时向 Root 报告，不自行安装软件；
+不确定具体 CLI 参数时，使用：
+<tool> --help
+<tool> -h
+
+确认后再执行。
+
+2. 环境约定
+
+Workspace 结构（每次 run 一致，不要另造目录）：
+
+/workspace/
+├── .dsh-pentester/          # 宿主状态（只读参考）
+├── target/                  # target.json scope/ roe/ inputs/
+├── assets/                  # assets.json（提升后的资产）
+├── stages/
+│   └── <NN>-<stage>/
+│       ├── summary.md       # 宿主在阶段完成时汇总
+│       └── delegations/
+│           └── D-XXX/       # 每个 Worker 的专属目录
+├── findings/                # findings.md 等（提升后）
+├── report/                  # 最终报告
+├── traffic/                 # 流量记录（勿动）
+└── STATUS.md                # 宿主自动生成的可读状态
+
+只写你自己的 delegation 目录：
+
+/workspace/stages/<NN>-<stage>/delegations/<D-XXX>/
+├── input/       # attach_prompt 快照（只读）
+├── work/        # 工作文件（默认 cwd）
+├── artifacts/   # 最终产物
+├── evidence/    # 可复验证据（命令 + 输出）
+└── logs/        # 大日志
+
+规则：
+
+- 可以读整个 /workspace/（历史阶段、别人的成果、STATUS.md）；
+- 只能写你自己的 delegations/<D-XXX>/ 目录（work/ artifacts/ evidence/ logs/）；
+- 不要写 manifest.json / result.md（宿主管理）；
+- 不要创建新的顶层目录；不要修改其他 delegation 目录。
+
+Git：
+
+- 本容器内没有 .git；绝不运行任何 git 命令。
+- Git checkpoint 由宿主在每个阶段完成时自动执行（约定式提交 + tag），与你无关。
+
+输出语言：
+
+- 除工具原始输出外，你生成的所有内容（final response、每个文件的正文、报告、注释）
+  一律使用 attach_prompt 的语言（即用户语言）。
+- 工具的原生输出（JSON、扫描结果、命令 stdout）保持原样，不做翻译。
+
+流量记录：
+
+网络流量已经由 Toolbox 自动记录：
+
+/workspace/traffic/pcap/
+
+保存原始网络流量。
+
+HTTP(S) 明文记录：
+
+/workspace/traffic/flows.mitm
+
+本容器存在本地 mitmproxy：
+
+http://127.0.0.1:8080
+
+需要让 HTTP(S) 流量进入明文记录链路时，可以：
+
+HTTP_PROXY=http://127.0.0.1:8080 \
+HTTPS_PROXY=http://127.0.0.1:8080 \
+<command>
+
+对于兼容 proxychains 的命令，也可以使用：
+
+proxychains4 <command>
+
+proxychains4 已预配置指向本地 mitmproxy。
+
+不要为了任务重复启动 tcpdump 或 mitmproxy。
+
+默认保持工具直连；只有确实需要 HTTP(S) 明文记录时才显式走代理，避免影响不兼容代理、raw socket 或特殊网络工具。
+
+字典
+/usr/share/seclists/
+/usr/share/wordlists/rockyou.txt.gz
+
+需要 rockyou 时再解压：
+
+gzip -dk /usr/share/wordlists/rockyou.txt.gz
+知识库
+
+容器内置离线知识库，位于：
+
+/pentester/kb/
+
+当遇到以下情况时，优先检索知识库而不是猜测或搜索：
+
+- 不确定某个漏洞的利用方式
+- 需要参考已知漏洞的 PoC / exploit
+- 需要查找特定技术或协议的攻击手法
+- 需要参考安全工具的常见用法和参数组合
+- 遇到不熟悉的 CVE / 服务 / 框架
+
+知识库内容：
+
+/pentester/kb/vulhub/
+    Vulhub 漏洞环境合集 —— 每个目录对应一个 CVE 或漏洞，
+    包含 docker-compose.yml（环境说明）和 README.md（漏洞原理 + 利用步骤）。
+    适用：需要在本地搭建漏洞环境复现时；但容器内无 docker，
+    主要参考其中的漏洞描述和利用思路。
+
+/pentester/kb/PayloadsAllTheThings/
+    Swissky 的 PayloadsAllTheThings —— 按攻击类型组织的 payload 大全。
+    目录结构：SQL Injection/ Command Injection/ XSS Injection/ SSTI/
+    Upload Insecure Files/ 等。
+    每个目录下是 README.md，包含该攻击类型的 payload 列表和简短说明。
+    适用：需要特定 payload 模板、绕过技巧、注入语法时。
+
+/pentester/kb/awesome-poc/
+    Awesome-POC —— 按 CVE 编号组织的漏洞 PoC 合集。
+    目录结构：CVE-YYYY-XXXXX/ 下包含 exploit 脚本和 README。
+    适用：目标存在已知 CVE 时查找现成 PoC。
+
+/pentester/kb/exphub/
+    exphub —— 漏洞利用工具合集。
+    按漏洞/框架分类，包含 Python/Go 等语言的 exploit 脚本。
+    适用：需要现成 exploit 工具时。
+
+索引：
+
+/pentester/kb/INDEX.txt
+
+这是构建期生成的全量文件清单，每行一个文件路径（相对于 /pentester/kb/）。
+
+检索方法：
+
+# 第一步：搜索 INDEX 找到相关文件
+rg -i '<keyword>' /pentester/kb/INDEX.txt
+
+# 例如：
+rg -i 'CVE-2021-44228' /pentester/kb/INDEX.txt
+rg -i 'ssti' /pentester/kb/INDEX.txt
+rg -i 'sql injection' /pentester/kb/INDEX.txt
+rg -i 'tomcat' /pentester/kb/INDEX.txt
+
+# 第二步：读取匹配的文件
+cat /pentester/kb/PayloadsAllTheThings/Server\ Side\ Template\ Injection/README.md
+cat /pentester/kb/awesome-poc/CVE-2021-44228/README.md
+
+# 第三步（可选）：如果结果太多，组合关键词缩小范围
+rg -i 'ssti' /pentester/kb/INDEX.txt | rg -i 'jinja'
+
+# 也可以直接搜索文件内容（不经过 INDEX）
+rg -i '<keyword>' /pentester/kb/ --include '*.md'
+
+注意事项：
+
+- INDEX.txt 只索引文件名，不索引文件内容。精确匹配用 INDEX，
+  模糊匹配或内容搜索用 rg 直接扫文件。
+- 知识库是只读参考，不要修改或写入 /pentester/kb/。
+- 知识库中的 payload 和 exploit 可能依赖特定环境或版本，
+  使用前先确认目标环境是否匹配。
+- 知识库补充工具能力，但不替代工具执行。
+  仍然以 tool-info / command -v 为实际能力判断依据。
+
+如果 red-tldr 已安装，也可以用于快速查询常见安全工具和技术命令：
+
+red-tldr <keyword>
+
+但：
+
+red-tldr 是知识参考，不代表对应命令一定安装。
+
+仍然以：
+
+tool-info
+command -v
+
+为实际能力判断依据。
+
+3. 输出策略
+
+优先让命令产生机器可读、紧凑、可复用的结果。
+
+优先级：
+
+工具原生 JSON / JSONL
+        ↓
+jc 支持的 parser
+        ↓
+原始 stdout / stderr
+第一优先：原生结构化输出
+
+工具本身支持 JSON/JSONL 时优先使用，例如：
+
+httpx -json
+nuclei -jsonl
+ffuf -of json
+
+不要为了使用 jc 而把已经结构化的数据再次转换。
+
+第二优先：jc
+
+传统 UNIX 命令没有原生 JSON，而 jc 有对应 parser 时：
+
+ps aux | jc --ps
+df -h | jc --df
+ping -c 3 <host> | jc --ping
+
+可以使用 jc 转换。
+
+第三优先：原始输出
+
+以下情况保持原始输出：
+
+jc 不支持；
+输出已经足够清晰；
+交互式程序；
+持续输出；
+二进制数据；
+转换会损失信息。
+
+不要把所有命令无条件通过 jc。
+
+4. 命令执行原则
+
+所有命令通过 container_exec 在 Toolbox 中执行。
+
+优先使用工具自身的非交互参数，例如：
+
+--batch
+--non-interactive
+--silent
+--json
+--jsonl
+
+具体参数必须根据该工具实际 CLI 确认。
+
+不要机械地给所有命令添加：
+
+-o /dev/null
+
+因为这可能丢弃任务结果或错误信息。
+
+对于长输出：
+
+<command> > /workspace/results/result.txt 2>&1
+
+或者优先保存工具自己的结构化结果：
+
+<command> ... > /workspace/results/result.jsonl
+
+随后只读取必要片段，例如：
+
+head
+tail
+rg
+jq
+wc
+
+避免把巨大结果直接塞回 Agent 上下文。
+
+## 3. 工具速查（按阶段）
+
+### 侦察 / 信息收集
+
+| 需求 | 命令 |
+| --- | --- |
+| 端口扫描 | `nmap -sV -p- <host>` · `masscan -p 1-65535 <host>` · `naabu -host <host>` |
+| 内网综合 | `fscan -h <网段>` · `kscan -t <网段>` |
+| 子域名 | `subfinder -d <d>` · `dnsx -d <d>` · `amass enum -d <d>` · `fofax -q '<query>'` |
+| HTTP 指纹 | `httpx -l <hosts> -status-code` · `whatweb <url>` · `wafw00f <url>` |
+| ARP 发现 | `arp-scan --localnet` · `netdiscover -r <网段>` |
+
+### Web 测试
+
+| 需求 | 命令 |
+| --- | --- |
+| 目录 fuzz | `ffuf -w <dict> -u <url>/FUZZ` · `gobuster dir -u <url> -w <dict>` · `feroxbuster -u <url> -w <dict>` |
+| 爬取 | `katana -u <url>` · `gospider -s 10 <url>` |
+| 漏洞扫描 | `nuclei -u <url>` |
+| SQL 注入 | `sqlmap -u <url> --batch` |
+| 手工请求 | `curl -sS` · `xh -S GET <url>` · `hurl <file.hurl>` |
+
+### 凭据 / 爆破
+
+| 需求 | 命令 |
+| --- | --- |
+| 网络爆破 | `hydra -l <user> -P <dict> ssh://<host>` · `medusa -h <host> -u <user> -P <dict> -M ssh` |
+| 密码破解 | `john --wordlist=<dict> <hashfile>` · `hashcat -m <id> -a 0 <hash> <dict>` |
+| 识别 | `hashid <hash>` · 默认口令 `defaulthound <host>` |
+| 造字典 | `crunch <min> <max> <charset> > out` |
+
+### SMB / AD
+
+| 需求 | 命令 |
+| --- | --- |
+| 枚举 | `smbclient -L <host>` · `enum4linux-ng -A <host>` |
+| 认证利用 | `netexec smb <host> -u <user> -p <pass>` · `impacket-psexec <user>@<host>` · `impacket-secretsdump <user>@<host>` |
+| WinRM | `evil-winrm -i <host> -u <user> -p <pass>` |
+
+### 利用辅助
+
+| 需求 | 命令 |
+| --- | --- |
+| 反序列化 | `ysoserial -u <gadget>` · `marshalsec <type>` · `jndi-injection-exploit -C <cmd>` |
+| 数据库 | `usql <DSN> -c "SELECT ..." --json` |
+
+### 网络 / 取证 / 杂项
+
+| 需求 | 命令 |
+| --- | --- |
+| 连通性 | `nc -vz <host> <port>` · `socat TCP:<host>:<port> -` · `telnet <host> <port>` |
+| DNS | `dig <host>` · `whois <domain>` · `traceroute <host>` · `mtr -r <host>` |
+| 代理路由 | `proxychains4 <cmd>` · `torsocks <cmd>` |
+| 取证 | `exiftool <file>` · `binwalk <file>` · `foremost -i <file>` · `r2 -a <bin>` |
+| MITM | `responder -I eth0` · `bettercap -iface eth0` |
+| 输出加工 | `jq` · `jc` · `gron` · `mlr` · `rg` · `fd` |
+
+## 4. 规则
+
+1. 先 `tool-list` 看全貌，再 `tool-info <name>` 取该工具的准确参数——上表只是速查，不替代 `tool-info`。
+2. 一切命令在容器内经 `container_exec` 执行；产出写入你自己的 delegation 目录（work/ artifacts/ evidence/ logs/）。
+3. 全流量已记录，勿重复 tcpdump；需要应用层明文时显式走 `http://127.0.0.1:8080`。
+4. 不确定工具是否存在：`command -v <name>` 确认；不存在则报告，不自作主张安装。
+5. 输出保持克制：非交互、限制规模、长输出落盘。
+6. 绝不运行 git 命令；git checkpoint 由宿主负责。
+7. 除工具原始输出外，所有内容使用用户语言（attach_prompt 的语言）。

package/docker/kali/bin/clone-kb

@@ -0,0 +1,39 @@
+#!/bin/sh
+set -eu
+
+dst="$1"
+repo="$2"
+min="${3:-1}"
+
+target="/opt/kb/$dst"
+
+for url in \
+  "https://github.com/${repo}.git" \
+  "https://gh.xmly.dev/https://github.com/${repo}.git" \
+  "https://gh-proxy.com/https://github.com/${repo}.git"
+do
+  for attempt in 1 2 3
+  do
+    echo "==> clone $repo"
+    echo "    url: $url"
+    echo "    attempt: $attempt/3"
+
+    rm -rf "$target"
+
+    if git clone --depth 1 "$url" "$target"; then
+      count="$(find "$target" -type f 2>/dev/null | wc -l)"
+
+      if [ "$count" -gt "$min" ]; then
+        echo "==> $repo OK ($count files)"
+        exit 0
+      fi
+
+      echo "==> clone incomplete: only $count files"
+    fi
+
+    sleep 5
+  done
+done
+
+echo "ERROR: failed to clone $repo"
+exit 1

package/docker/kali/bin/entrypoint.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 启动流量记录。
+# record-traffic.sh 自身必须幂等，因此重复调用不会重复启动 recorder。
+/pentester/bin/record-traffic.sh
+
+# 让 Docker CMD 成为 PID 1，正确处理 stop / signals。
+exec "$@"

package/docker/kali/bin/gen-tools-json.sh

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+# gen-tools-json.sh — build-time catalog generator for /pentester/tools.json
+#
+# Probes every curated tool with `command -v` and emits ONLY tools that exist
+# in the built image, so the catalog never drifts from what the Agent can
+# actually run. Descriptions/examples are maintained here next to the tool
+# (the Dockerfile just installs packages; this file owns the metadata).
+#
+# Usage (run inside the image at build time):
+#   gen-tools-json.sh [output-path]   (default: /pentester/tools.json)
+set -euo pipefail
+
+OUT="${1:-/pentester/tools.json}"
+IMAGE='fb0sh/dsh-pentester-kali:latest'
+
+declare -a CATEGORY_NAMES=(
+  'base'
+  'cli-extras'
+  'traffic'
+  'network'
+  'network-discovery'
+  'dns-osint'
+  'web-discovery'
+  'vulnerability'
+  'password'
+  'smb-ad'
+  'wordlists'
+  'misc'
+)
+
+# Entry format: <category>|<name>|<description>|<example-tail>
+#   - Regular tools: name IS the binary to probe (command -v).
+#   - `bin=<actual>` as name: probe <actual>, expose display name in the next
+#     field (e.g. `misc|bin=r2|radare2|desc|-a <bin>`).
+#   - `dir:<path>` as name: path hint (not an executable), always emitted.
+#   - name containing `*` (impacket-*): family placeholder, skipped.
+declare -a TOOLS=(
+  # ── base ────────────────────────────────────────────────────────────────
+  'base|bash|Bourne Again SHell|-c "echo hi"'
+  'base|zsh|Z shell|-c "echo hi"'
+  'base|python3|Python 3 interpreter|-V'
+  'base|pip|Python package installer|install --user <pkg>'
+  'base|pipx|Isolated Python CLI installer|install <pkg>'
+  'base|git|Distributed version control|clone <url>'
+  'base|curl|HTTP/HTTPS/FTP transfer client|-sS <url>'
+  'base|wget|Non-interactive network downloader|-q <url>'
+  'base|aria2c|Multi-protocol download utility|-x16 <url>'
+  'base|jq|JSON processor|.key <file>'
+  'base|yq|YAML/JSON processor|.key <file>'
+  'base|ruby|Ruby interpreter|-e "puts 1"'
+  'base|perl|Perl interpreter|-e "print 1"'
+  'base|go|Go toolchain|version'
+  'base|java|JRE launcher|-version'
+  'base|gcc|C compiler|-o out in.c'
+  'base|make|Build automation|-j4'
+  'base|unzip|ZIP extractor|-l <file>'
+  'base|7z|7-Zip archiver|x <file>'
+  'base|tar|Tape archiver|-xzf <file>'
+  'base|openssl|TLS/SSL toolkit|s_client -connect <host>:443'
+  'base|file|File type identification|<file>'
+  'base|tree|Directory tree viewer|-L2'
+  'base|gdb|GNU debugger|-batch <bin>'
+  'base|tmux|Terminal multiplexer|new -s <name>'
+  'base|screen|Terminal multiplexer|-S <name>'
+  'base|red-tldr|Red team TL;DR|red-tldr <command>'
+  # ── cli-extras（现代化 CLI 基础件，来自用户愿望清单）───────────────────
+  'cli-extras|rg|Ripgrep: fast recursive grep|pattern -l'
+  'cli-extras|fd|fd: friendly find|".txt"'
+  'cli-extras|xh|xh: curl replacement for HTTP|-S GET <url>'
+  'cli-extras|hurl|HTTP request runner (chains, asserts)|<file.hurl>'
+  'cli-extras|sd|sd: intuitive sed replacement|old new <file>'
+  'cli-extras|mlr|Miller: csv/tsv/json awk|-i json cat <file>'
+  'cli-extras|jc|Converts anything (CLI output, files) to JSON|ls | jc --ls'
+  'cli-extras|gron|Grep from JSON (flatten to assignments)|gron <file.json>'
+  # ── web-discovery 补充（builder 阶段编译）─────────────────────────────────
+  'web-discovery|interactsh-client|OOB interaction detector (DNS/HTTP/LDAP callbacks)|-n'
+  'web-discovery|gospider|Fast web spider|-s 10 <url>'
+  # ── 反序列化 / 利用辅助（/pentester/tools/jars jar 包装脚本）──────────────
+  'vulnerability|ysoserial|Java deserialization payload generator|-u CommonsCollections1'
+  'vulnerability|marshalsec|Java marshalling gadget generator|MarshalledObject'
+  'vulnerability|jndi-injection-exploit|JNDI/LDAP injection exploitation helper|-C <cmd>'
+  'vulnerability|usql|Universal command-line interface for SQL databases|DSN -c "SELECT * FROM <table>" --json'
+  # ── traffic（全流量记录：只记录，不分析）──────────────────────────────
+  'traffic|tcpdump|Full packet capture (always recording to /workspace/traffic/pcap)|-r /workspace/traffic/pcap/capture.pcap'
+  'traffic|mitmdump|mitmproxy CLI: HTTP(S) flow recorder on :8080 (flows -> /workspace/traffic/flows.mitm)|-r /workspace/traffic/flows.mitm'
+  # ── network ─────────────────────────────────────────────────────────────
+  'network|ip|IP routing/addresses (iproute2)|addr'
+  'network|ping|ICMP echo (iputils)|-c4 <host>'
+  'network|dig|DNS lookup|<host>'
+  'network|nslookup|DNS query tool|<host>'
+  'network|host|DNS lookup utility|<host>'
+  'network|whois|WHOIS client|<domain>'
+  'network|traceroute|Path tracing|<host>'
+  'network|mtr|Network diagnostic (traceroute+ping)|-r <host>'
+  'network|tcpdump|Packet capture|-i eth0 port 80'
+  'network|tshark|Wireshark CLI analyzer|-i eth0'
+  'network|nc|Netcat: read/write TCP/UDP|-vz <host> 443'
+  'network|ncat|Nmap netcat variant|-v <host> 443'
+  'network|socat|Bidirectional data relay|TCP:<host>:443 -'
+  'network|telnet|Telnet client|<host> 23'
+  'network|ssh|OpenSSH client|-o StrictHostKeyChecking=no <host>'
+  'network|proxychains4|Route traffic via SOCKS/HTTP proxy|nmap -sT <host>'
+  'network|torsocks|Route traffic via Tor|curl <url>'
+  # ── network-discovery ───────────────────────────────────────────────────
+  'network-discovery|nmap|Network discovery and port scanner|-sV -p- <host>'
+  'network-discovery|masscan|High-speed port scanner|-p 1-65535 <host>'
+  'network-discovery|naabu|ProjectDiscovery fast port scanner|-host <host>'
+  'network-discovery|arp-scan|ARP host discovery|--localnet'
+  'network-discovery|fscan|内网综合扫描工具，一键自动化漏扫|-h 192.168.1.1/24'
+  'network-discovery|kscan|轻量化全方位扫描器|-t 192.168.1.1/24'
+  'network-discovery|netdiscover|ARP host discovery (passive/active)|-r 192.168.1.0/24'
+  # ── dns-osint ───────────────────────────────────────────────────────────
+  'dns-osint|dnsrecon|DNS enumeration|-d <domain>'
+  'dns-osint|dnsenum|DNS enumeration|<domain>'
+  'dns-osint|fierce|DNS/domain scanner|--domain <domain>'
+  'dns-osint|amass|Attack surface mapping (OSINT)|enum -d <domain>'
+  'dns-osint|subfinder|Fast subdomain discovery|-d <domain>'
+  'dns-osint|dnsx|ProjectDiscovery DNS prober|-d <domain>'
+  'dns-osint|theHarvester|Email/subdomain OSINT|-d <domain> -b all'
+  'dns-osint|whatweb|Website fingerprinting|<url>'
+  'dns-osint|wafw00f|WAF detection|<url>'
+  'dns-osint|fofax|FOFAX是一个基于fofa.info的API命令行查询工具|-q 'app="APACHE-Solr"''
+  # ── web-discovery ───────────────────────────────────────────────────────
+  'web-discovery|ffuf|Web fuzzer|-w <wordlist> -u <url>/FUZZ'
+  'web-discovery|gobuster|Directory/DNS/HTTP brute force|dir -u <url> -w <wordlist>'
+  'web-discovery|feroxbuster|Recursive content discovery|-u <url> -w <wordlist>'
+  'web-discovery|dirb|Web content scanner|<url> <wordlist>'
+  'web-discovery|dirbuster|Web content scanner (Java)|-u <url>'
+  'web-discovery|katana|ProjectDiscovery crawler|-u <url>'
+  'web-discovery|httpx|ProjectDiscovery HTTP prober|-l <hosts> -status-code'
+  'web-discovery|nikto|Web server vulnerability scanner|-h <host>'
+  # ── vulnerability ───────────────────────────────────────────────────────
+  'vulnerability|nuclei|Template-based vulnerability scanner|-u <url>'
+  'vulnerability|sqlmap|SQL injection automation|-u <url> --batch'
+  # ── password ────────────────────────────────────────────────────────────
+  'password|hydra|Network login brute forcer|-l <user> -P <passwords> ssh://<host>'
+  'password|john|John the Ripper password cracker|--wordlist=<list> <hashfile>'
+  'password|medusa|Parallel network login brute forcer|-h <host> -u <user> -P <passwords> -M ssh'
+  'password|crunch|Wordlist generator|8 8 abc123 > <out>'
+  'password|hashid|Hash type identification|<hash>'
+  'password|hashcat|Advanced password recovery utility|-m 0 -a 0 <hash> <wordlist>'
+  'password|defaulthound|Default password scanner|<host>'
+  # ── smb-ad ──────────────────────────────────────────────────────────────
+  'smb-ad|smbclient|SMB/CIFS client|-L <host>'
+  'smb-ad|enum4linux-ng|SMB/AD enumeration|-A <host>'
+  'smb-ad|impacket-*|Impacket scripts (psexec, smbexec, secretsdump)|psexec domain/user@<host>'
+  'smb-ad|netexec|Network exec suite (SMB/WinRM/LDAP)|smb <host> -u <user> -p <pass>'
+  'smb-ad|evil-winrm|WinRM shell client|-i <host> -u <user> -p <pass>'
+  # ── wordlists (path hints, not executable tools) ────────────────────────
+  'wordlists|dir:/usr/share/seclists|Wordlist collection (seclists)'
+  'wordlists|dir:/usr/share/wordlists/rockyou.txt.gz|rockyou wordlist'
+  # ── misc ────────────────────────────────────────────────────────────────
+  'misc|exiftool|EXIF metadata extraction|<file>'
+  'misc|binwalk|Firmware/file carving|<file>'
+  'misc|foremost|File carving|-i <file>'
+  'misc|bin=r2|radare2|Reverse engineering framework|-a <bin>'
+  'misc|responder|LLMNR/NBT-NS/mDNS poisoner|-I eth0'
+  'misc|bettercap|MITM framework|-iface eth0'
+)
+
+# Collect all_bins: every probed binary that actually exists (dir: excluded).
+# 可选知识库层（--build-arg WITH_KB=1 构建时才存在；存在才进目录）
+if [ -d /pentester/kb ]; then
+  TOOLS+=('knowledge|dir:/pentester/kb|Offline knowledge bases: vulhub, PayloadsAllTheThings, Awesome-POC, exphub|see /pentester/kb/INDEX.txt')
+fi
+
+mapfile -t ALL_BINS < <(printf '%s\n' "${TOOLS[@]}" | while IFS='|' read -r _cat name _desc _tail; do
+  case "$name" in
+    dir:*) continue ;;
+    bin=*) probe="${name#bin=}" ;;
+    *'*') continue ;;
+    *) probe="$name" ;;
+  esac
+  if command -v "$probe" >/dev/null 2>&1; then
+    printf '%s\n' "$probe"
+  fi
+done | sort -u)
+
+{
+  printf '{\n'
+  printf '  "version": "%s",\n' "$(cat /pentester/VERSION 2>/dev/null || echo '1.0.0')"
+  printf '  "image": "%s",\n' "$IMAGE"
+  printf '  "categories": {\n'
+} > "$OUT"
+
+first_category=1
+for category in "${CATEGORY_NAMES[@]}"; do
+  entries=$(printf '%s\n' "${TOOLS[@]}" | while IFS='|' read -r cat name desc tail; do
+    [ "$cat" != "$category" ] && continue
+    case "$name" in
+      *'*') continue ;; # family placeholder
+      dir:*)
+        # Path hint: bin = the path, always emitted.
+        path="${name#dir:}"
+        binname="${path##*/}"
+        jq -nc --arg n "$binname" --arg b "$path" --arg d "$desc" \
+          '{ name: $n, bin: $b, description: $d, common_flags: [], examples: [$b] }'
+        ;;
+      bin=*)
+        # name = bin=<probe>, desc = <display>, tail = <description>|<example-tail>
+        probe="${name#bin=}"
+        display="$desc"
+        description="${tail%%|*}"
+        example_tail=""
+        if [ "$tail" != "$description" ]; then
+          example_tail="${tail#*|}"
+        fi
+        if command -v "$probe" >/dev/null 2>&1; then
+          example="$probe"
+          [ -n "$example_tail" ] && example="$example $example_tail"
+          jq -nc --arg n "$display" --arg b "$probe" --arg d "$description" --arg e "$example" \
+            '{ name: $n, bin: $b, description: $d, common_flags: [], examples: [$e] }'
+        fi
+        ;;
+      *)
+        if command -v "$name" >/dev/null 2>&1; then
+          example="$name"
+          [ -n "$tail" ] && example="$example $tail"
+          jq -nc --arg n "$name" --arg b "$name" --arg d "$desc" --arg e "$example" \
+            '{ name: $n, bin: $b, description: $d, common_flags: [], examples: [$e] }'
+        fi
+        ;;
+    esac
+  done)
+  if [ -n "$entries" ]; then
+    if [ "$first_category" -eq 0 ]; then
+      printf ',\n' >> "$OUT"
+    fi
+    {
+      printf '    "%s": [\n' "$category"
+      printf '%s\n' "$entries" | paste -sd, -
+      printf '\n    ]'
+    } >> "$OUT"
+    first_category=0
+  fi
+done
+
+{
+  printf '\n  },\n'
+  printf '  "all_bins": [\n'
+  printf '%s\n' "${ALL_BINS[@]}" | sed 's/^/    "/; s/$/",/' | sed '$ s/,$//'
+  printf '\n  ]\n'
+  printf '}\n'
+} >> "$OUT"
+
+echo "tools.json written: $(wc -l < "$OUT") lines, ${#ALL_BINS[@]} bins"