# 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)。