| name | f8x-tool-maintenance |
| description | 维护 f8x 渗透工具安装器：新增工具安装函数、更新版本号、管理 F8X_TOOL_LIST 注册、构建 Arsenal 多平台投递物。当修改 f8x 脚本、添加新渗透工具、更新工具版本、检查工具覆盖、或构建 arsenal 二进制时，务必使用此 skill。即使用户只是提到 "装个 xxx 工具"、"f8x 里加一下"、"更新一下版本" 也应触发。 |
f8x 工具维护
f8x (/Users/f0x/pte-project/infra-plat/f8x/f8x) 是一个 12800+ 行的 Bash 脚本，包含 161 个安装函数，自动化安装渗透测试工具。
架构概览
新增或修改一个工具涉及最多 6 个位置：
① 版本变量 (行 93-435 区域)
② 安装函数 (行 3305-6990 区域)
③ 安装组调用 (行 10502-10950 区域)
④ F8X_TOOL_LIST 注册 (行 10957+)
⑤ Arsenal 投递物 [可选] (行 11359+)
⑥ catalog.json 重新生成 (python3 generate_catalog.py)
其中 ①②④⑥ 是必须的，③ 看工具分类决定，⑤ 仅适用于需要投递到目标机执行的工具。
新增工具流程
Step 1: 添加版本变量（行 93-435 区域）
f8x 的版本变量分两个区域：
- 渗透工具 (行 93-370)：
Software version variable setting (pentest)
- 其他工具 (行 373-435)：
Software version variable setting (other)
最简单情况只需一个变量：
xxx_Ver="v1.0.0"
但很多工具还需要定义关联的文件名变量，因为 release 文件名中嵌入了版本号：
xxx_Ver="v1.0.0"
xxx_bin_amd64="xxx_1.0.0_linux_amd64.tar.gz"
xxx_bin_arm64="xxx_1.0.0_linux_arm64.tar.gz"
更新版本时，这些 _bin_*、_File_*、_Dir_* 变量中的版本号也必须同步修改，这是最容易出错的地方。
位置约定：云安全工具放在 k8spider_Ver 附近，AD 工具放在 ligolo_ng_Ver 附近。
版本覆盖机制：f8x 在行 460 会 source ./f8x_version.sh（如果存在），可以在不修改主脚本的情况下覆盖版本号，适合测试和自定义部署。
Step 2: 编写安装函数（行 3305-6990 区域）
函数命名：渗透工具推荐 Pentest_xxx_Install()，但不是强制的。F8X_TOOL_LIST 中实际存在多种命名风格：
Pentest_xxx_Install() — 大多数渗透工具xxx_Install() — 基础设施工具（frp_Install, nps_Install, RedGuard_Install, Docker_Install 等）
函数名只要和 F8X_TOOL_LIST 注册时一致即可。
根据工具类型选择模板 → 详见 references/install-templates.md
四种常见模板：
- 模板 A：GitHub Release 下载裸二进制（Go/Rust 静态编译工具）
- 模板 A2：GitHub Release 下载压缩包（tar.gz/zip，用预定义的
_bin_* 变量）
- 模板 B：Git Clone + pip install（Python PoC/工具）
- 模板 C：pip install（PyPI 包）
内置 helper 函数（直接在安装函数中调用，无需自己实现）：
Install_Switch7 "requirements.txt" — 自动用 pip3/pip 安装 requirements.txtInstall_Switch8 "包名" — pip install 指定包（带 --break-system-packages 兼容新版 pip）Install_Switch "apt包名" — apt install
Step 3: 注册到安装组（行 10502-10950 区域）
根据工具类别在对应函数中添加调用。调用链：-ka → kali_Tools("a") → kali_Tools_TypeA()
| 触发选项 | 实际调用 | 分类 | 典型工具 |
|---|
-ka | kali_Tools_TypeA() (行 10539) | 信息收集/资产发现 | nmap, ffuf, subfinder, fscan, httpx 等 30+ |
-kb | kali_Tools_TypeB() (行 10623) | 漏洞扫描/利用 | metasploit, sqlmap, nuclei, xray 等 |
-kc | kali_Tools_TypeC() (行 10680) | 后渗透/内网 | impacket, responder, crackmapexec, mitmproxy 等 |
-kd | kali_Tools_TypeD() (行 10715) | 密码/杂项 | hashcat, jadx, ncat, mapcidr, dnsx 等 |
-ke | kali_Tools_TypeE() (行 10754) | 补充/大型字典 | SecLists, hakrawler, subjs, assetfinder |
-ad | Ad_Tools() (行 10773) | AD 域渗透专用 | impacket, certipy, noPac, ligolo-ng 等 |
-cloud | cloud() (行 10897) | 云安全 | k8spider, kubectl, kubeletctl, tccli 等 |
分类决策：不确定放哪个 Type 时，看工具在渗透流程中的位置——收集目标信息用 TypeA，发现和利用漏洞用 TypeB，拿到 shell 之后的操作用 TypeC，不好归类的放 TypeD。TypeE 留给辅助资源（字典、被动收集）。域渗透/云安全有专门的 -ad / -cloud。
格式：
echo -e "\033[1;33m\n>> Installing xxx\n\033[0m"
Pentest_xxx_Install
Step 4: 注册到 F8X_TOOL_LIST（行 10957+）
让 -install、--list-tools、--search 能找到工具：
xxx|Pentest_xxx_Install|0
格式：工具名(小写)|安装函数名|依赖级别
- 0 = 无额外依赖（wget 下载二进制）
- 1 = 需要 Python（自动调用
Py_Check）
- 2 = 需要 Go（自动调用
GO_Check）
- 3 = 需要 Python + Go
注意：--list-tools 和 --search 不需要 root 权限（在 Main() 之前就被拦截处理）。
Step 5: Arsenal 投递物 [可选]（行 11359+）
仅当工具需要投递到目标机上执行时才需要。
适合 Arsenal 的工具：
- Go/Rust 静态编译二进制，有 GitHub Releases 多平台预编译文件
- 需要在目标机上直接执行（fscan, chisel, frpc, cdk 等）
- agent 类工具（ligolo-agent）
不适合 Arsenal 的：
- Python 脚本（需要运行环境）
- 攻击机本地工具（nmap, responder）
- 系统工具（apt 包）
详见 references/arsenal-guide.md
Step 6: 更新 catalog.json（目录元数据）
generate_catalog.py 自动从 f8x 脚本提取工具目录信息，供 redc-gui 软件商店和 f8x 官网使用。
新增工具后必须重新生成：
cd /Users/f0x/pte-project/infra-plat/f8x
python3 generate_catalog.py ./f8x ./catalog.json
URL 自动提取机制：
- 优先从安装函数体中提取
github.com/xxx/yyy URL（git clone / wget 等）
- 无法提取时，fallback 到
KNOWN_TOOL_URLS 字典（generate_catalog.py 中硬编码）
- 都没有时 URL 为空字符串，不会报错，但生成时会打印 warning
何时需要手动添加 KNOWN_TOOL_URLS：
- 工具通过
Install_Switch（apt/yum）安装，函数体里没有 GitHub URL
- 工具的项目主页不是 GitHub（如 nmap.org, mitmproxy.org）
- 在
generate_catalog.py 的 KNOWN_TOOL_URLS 字典中添加 "工具名": "URL"
includes 子工具：
- 对 batch 类 flag（如
-k, -ad），catalog.json 会自动生成 includes 字段
- 列出该 flag 包含的所有子工具名称和项目 URL
- 数据来自递归追踪入口函数（
BATCH_ENTRY_FUNCTIONS）的调用链
新增 batch flag 时：
- 在
BATCH_ENTRY_FUNCTIONS 字典中添加 "-flag": ["入口函数名"]
- 重新运行
generate_catalog.py
验证：
python3 -c "import json; d=json.load(open('catalog.json')); m=[x for x in d['modules'] if x['flag']=='-k'][0]; print(len(m.get('includes',[])), 'tools')"
更新工具版本
版本更新有独立的 skill，详见 f8x-version-update。以下是快速参考：
- 在 GitHub Releases 页面确认最新版本
- 修改版本变量
xxx_Ver="vNEW"
- 关键：同步修改所有关联的文件名变量（
_bin_amd64、_bin_arm64、_File_*、_Dir_*），版本号嵌在文件名里！
Nuclei_Ver="v3.8.0"
Nuclei_Install_amd64="nuclei_3.7.0_linux_amd64.zip"
- 如果 release 文件名格式变了，同步修改安装函数和 arsenal case 块
- 批量检查用：
python3 check_releases.py（根目录）
- 也可以用
f8x_version.sh 临时覆盖版本号测试，不影响主脚本
常用命令
./f8x -install nuclei
./f8x --search nmap
./f8x --list-tools
./f8x --list-tools table
./f8x -arsenal
./f8x -ka
./f8x -kb
./f8x -kc
./f8x -kd
./f8x -ke
./f8x -cloud
./f8x -ad
关键文件路径
| 文件 | 作用 |
|---|
/Users/f0x/pte-project/infra-plat/f8x/f8x | f8x 安装器主脚本（12800+ 行） |
/Users/f0x/pte-project/infra-plat/f8x/f8x_version.sh | 版本覆盖配置（source 加载，可选） |
/Users/f0x/pte-project/infra-plat/f8x/check_releases.py | 批量检查工具版本更新 |
/Users/f0x/pte-project/infra-plat/f8x/generate_catalog.py | 自动生成 catalog.json（提取 flag、子工具、URL） |
/Users/f0x/pte-project/infra-plat/f8x/catalog.json | 工具目录元数据（供 redc-gui 和 f8x 官网使用） |
/Users/f0x/pte-project/infra-plat/f8x/doc/ai-friendly-tool-install-design.md | AI 友好化改造设计文档 |
端到端示例：添加 httpx
以 ProjectDiscovery 的 httpx 为例，走一遍完整的 5 步流程：
Step 1 — 版本变量（行 93-370 区域，渗透工具段）：
httpx_Ver="v1.6.10"
httpx_bin_amd64="httpx_1.6.10_linux_amd64.zip"
httpx_bin_arm64="httpx_1.6.10_linux_arm64.zip"
Step 2 — 安装函数（模板 A2，因为 release 是 zip 压缩包）：
Pentest_httpx_Install(){
name="httpx"
which httpx > /dev/null 2>&1
if [ $? == 0 ]; then
Echo_ALERT "$name installed"
else
case $Linux_architecture_Name in
*"linux-x86_64"*) httpx_bin="${httpx_bin_amd64}" ;;
*"linux-arm64"*) httpx_bin="${httpx_bin_arm64}" ;;
*) httpx_bin="${httpx_bin_amd64}" ;;
esac
local tmp_dir="/tmp/httpx_install"
mkdir -p "$tmp_dir"
$Proxy_OK wget ${GitProxy}https://github.com/projectdiscovery/httpx/releases/download/${httpx_Ver}/${httpx_bin} \
-O "$tmp_dir/${httpx_bin}" ${wget_option} 2>/dev/null || Echo_ERROR2
cd "$tmp_dir" && unzip -o "${httpx_bin}" > /dev/null 2>&1
mv "$tmp_dir/httpx" /usr/local/bin/httpx
chmod +x /usr/local/bin/httpx
rm -rf "$tmp_dir"
which httpx > /dev/null 2>&1 && Echo_INFOR "Successfully installed $name $httpx_Ver" || Echo_ERROR3
fi
}
Step 3 — 注册到 kali_Tools_TypeA()（信息收集类工具）：
echo -e "\033[1;33m\n>> Installing httpx\n\033[0m"
Pentest_httpx_Install
Step 4 — 注册到 F8X_TOOL_LIST：
httpx|Pentest_httpx_Install|0
Step 5 — Arsenal（可选）：httpx 是静态二进制，但通常在攻击机本地使用做 HTTP 探测，不需要投递到目标机 → 跳过。
Step 6 — 重新生成 catalog.json：
python3 generate_catalog.py ./f8x ./catalog.json
httpx 的安装函数里有 github.com/projectdiscovery/httpx，URL 会自动提取，无需手动添加 KNOWN_TOOL_URLS。
常见错误
- 版本号不同步：改了
xxx_Ver 但忘了改 xxx_bin_amd64 里的版本号 → 下载 404。这是最高频的错误
- 写了函数但忘记注册：安装函数写好了，但没有在 F8X_TOOL_LIST 里添加条目 →
-install xxx 找不到工具
- 工具名大小写不匹配：F8X_TOOL_LIST 里工具名是小写（
nuclei|...），搜索时也用小写匹配，不要写成大写
- Arsenal case 块缺
;;：bash case 语法必须以 ;; 结尾，漏了会导致穿透到下一个分支
- release 文件名变了没跟进：上游项目改了 release 命名格式（比如从
_amd64 变成 -amd64），但 f8x 变量还是旧格式
- 新增工具后忘了重新生成 catalog.json：redc-gui 软件商店和 f8x 官网不会显示新工具 → 运行
python3 generate_catalog.py ./f8x ./catalog.json
- apt/pip 安装的工具缺 URL：通过包管理器安装的工具不会自动提取 URL，需要在
KNOWN_TOOL_URLS 里手动添加项目地址
- 已安装检测用了
test -d 但目录在下载前就创建了：如果安装函数先 mkdir -p "$dir" 再下载，网络失败后目录已存在，重试时 test -d $dir 误判为已安装。对于安装到 $P_Dir/xxx 目录的工具，应该用 test -x "$dir/二进制名" 检查实际二进制文件是否存在，而不是检查目录
参考文件
references/install-templates.md — 四种安装函数模板（含完整代码和内置 helper 说明）references/arsenal-guide.md — Arsenal 投递物配置指南（含 case 块模板和特殊平台占位符）
