# 工具链：安装与配置

本插件**自身零依赖**（只用 Node 内置模块），但 `pentest_env_check` 会体检、`pentest_scan` 会调用本机的外部安全工具。

> **不装也能用。** `pentest_recon` 的 DNS / 端口 / Web 指纹探测是内置实现（`node:dns`、`node:net`、`node:http`），一个外部工具都没有时依然完整可用。外部工具只提供**增强**。

> ⚠️ 全部操作仅限**已获得书面授权**的目标。

## 一、工具清单

下表与 `lib/probe.js` 里的 `TOOL_CATALOG` 逐项对应（共 20 项），`pentest_env_check` 报告的也是这一份。

### 端口与服务

| 工具 | 用途 | 建议 |
| --- | --- | --- |
| [nmap](https://nmap.org/download) | 端口扫描、服务与版本识别 | **推荐**（`pentest_recon --includeExternal` 会用它复核） |
| [naabu](https://github.com/projectdiscovery/naabu) | 高速端口探测 | 可选（大网段时比内置探测快） |
| [masscan](https://github.com/robertdavidgraham/masscan) | 大网段端口扫描 | 可选（需自行编译或取 prebuilt） |

### 资产发现

| 工具 | 用途 | 建议 |
| --- | --- | --- |
| [subfinder](https://github.com/projectdiscovery/subfinder) | 被动子域枚举 | 推荐 |
| [amass](https://github.com/owasp-amass/amass) | 子域与关系图谱枚举 | 可选 |
| [dnsx](https://github.com/projectdiscovery/dnsx) | 批量 DNS 解析 | 可选 |
| [httpx](https://github.com/projectdiscovery/httpx) | 存活探测与 Web 指纹（`pentest_scan kind=fingerprint`） | **推荐**，但**注意同名陷阱**（见第五节） |
| [katana](https://github.com/projectdiscovery/katana) | 爬虫与 URL 收集 | 可选 |
| [WhatWeb](https://github.com/urbanadventurer/WhatWeb) | Web 技术栈指纹 | 可选 |

### 漏洞扫描 / 内容发现 / 漏洞验证

| 工具 | 用途 | 建议 |
| --- | --- | --- |
| [nuclei](https://github.com/projectdiscovery/nuclei) | 模板化漏洞扫描（`pentest_scan kind=template`） | **推荐** |
| [nikto](https://github.com/sullo/nikto) | Web 服务器配置检查 | 可选 |
| [ffuf](https://github.com/ffuf/ffuf) | 目录与参数爆破（`pentest_scan kind=content`） | **推荐** |
| [gobuster](https://github.com/OJ/gobuster) | 目录与子域爆破 | 可选（与 ffuf 二选一） |
| [sqlmap](https://sqlmap.org) | SQL 注入验证 | 可选，**需显式授权** |

### 基础工具

| 工具 | 用途 | 备注 |
| --- | --- | --- |
| curl | HTTP 请求与下载 | 系统通常自带 |
| openssl | TLS 证书与协议检查 | 系统通常自带 |
| nslookup | DNS 查询 | Windows 自带 |
| dig | DNS 查询 | Linux/macOS 自带（Windows 可装 BIND 工具） |
| whois | 域名与 IP 注册信息 | 包管理器安装 |
| jq | JSON 结果处理 | 包管理器安装 |

## 二、一键脚本

包内提供两个脚本，都**默认只检测、只打印命令**，加 `-Apply` / `--apply` 才真正执行安装：

```powershell
# Windows
powershell -ExecutionPolicy Bypass -File scripts\install-toolchain.ps1
powershell -ExecutionPolicy Bypass -File scripts\install-toolchain.ps1 -Apply
```

```bash
# Linux / macOS
bash scripts/install-toolchain.sh
bash scripts/install-toolchain.sh --apply
```

脚本通过 `lib/probe.js` 的 `detectTools` 做检测，因此**清单只有一份来源**，不会和插件跑偏。

## 三、分平台手动安装

### Windows

```powershell
# 基础工具与 nmap
winget install --id Insecure.Nmap -e
winget install --id jqlang.jq -e

# Go 生态（需先装 Go 1.21+）：见第四节
```

### macOS

```bash
brew install nmap whatweb nikto jq whois
# Go 生态：见第四节
```

### Linux（Debian/Ubuntu）

```bash
sudo apt install nmap masscan nikto whatweb sqlmap jq whois dnsutils
# Go 生态：见第四节
```

> 包管理器里的 ID / 包名可能随版本变化，装之前用 `winget search <名>`、`brew search <名>`、`apt-cache search <名>` 确认一下。

## 四、ProjectDiscovery 全家桶（推荐）

`subfinder`、`dnsx`、`httpx`、`katana`、`naabu`、`nuclei` 建议整套装，它们口径一致、输出可互相喂。有 Go 1.21+ 时：

```bash
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
```

另外两个 Go 写的常用工具：

```bash
go install -v github.com/ffuf/ffuf/v2@latest
go install -v github.com/OJ/gobuster/v3@latest
```

注意 `go install` 的产物落在 `$(go env GOPATH)/bin`，确认它在 `PATH` 里，否则 `pentest_env_check` 检测不到。

nuclei 装完还需要拉模板（首次运行会自动拉，也可手动）：

```bash
nuclei -update-templates
```

## 五、两个必须知道的坑

### 1. 同名不同物 —— `httpx`

`httpx` 这个名字同时属于两个完全不同的东西：

- **ProjectDiscovery httpx** —— 安全扫描器（本插件预期的）
- **Python httpx** —— 一个 HTTP 客户端库，也会装出一个 `httpx` 命令

插件为此内置了**身份正则校验**：只有版本输出里出现 `current version` 或 `projectdiscovery` 才认；否则标记为 `usable: false`，`pentest_scan` **绝不会**拿它去扫。

实测过：一台机器上 `httpx -version` 返回 `Usage: httpx [OPTIONS] URL`，就是 Python 那个——插件正确拦下了它。

所以 `pentest_env_check` 报告"可用 N 个"时，留意有没有 `identityWarnings`。

### 2. 中文 Windows 的 GBK 输出

`nslookup`、`whois` 这类系统工具按控制台代码页输出 GBK，而 Node 默认按 UTF-8 解码，会变成 `Ĭ�Ϸ�����` 这样的乱码。插件的 `lib/probe.js#decodeOutput` 已做处理：先严格试 UTF-8，失败回退 `gb18030`/`gbk`/`big5`/`shift_jis`。

如果你在别处也解析这类命令的输出，记得同一个坑。

## 六、与本插件的对应关系

| 插件能力 | 依赖的外部工具 | 缺失时的行为 |
| --- | --- | --- |
| `pentest_recon` 的 DNS / 端口 / Web 指纹 | **无**（内置实现） | 始终可用 |
| `pentest_recon --includeExternal` | nmap | 返回 `skipped`，其余结果照常 |
| `pentest_scan kind=fingerprint` | httpx（身份须匹配） | 返回 `skipped` 并说明原因 |
| `pentest_scan kind=template` | nuclei | 同上 |
| `pentest_scan kind=content` | ffuf + 字典 | 同上 |
| `pentest_env_check` | 全部 20 项（只探测版本） | 列出缺失项 |

**关键点**：工具缺失一律是**优雅降级**（返回 `skipped` 并说明），不会让流程中断。

## 七、验证

装完用插件自带的体检跑一遍：

```
pentest_env_check
```

它会给出：可用数量 / 身份相符数量 / 缺失清单 / 身份不符警告。预期看到 `usableCount` 上升，且没有 `identityWarnings`。

如果某个工具装了却检测不到，先确认它在 `PATH` 里（`Get-Command <名>` / `command -v <名>`），再确认版本命令能正常输出。