nimosocute/ctf-codex-toolkit
GitHub: nimosocute/ctf-codex-toolkit
专为 Kali Linux/WSL 设计的 CTF Codex 工作流工具包，自动化配置 Codex CLI 作为 CTF 解题助手并管理完整的竞赛环境。
Stars: 9 | Forks: 0
# CTF Codex 工具包
[](https://www.npmjs.com/package/ctf-codex-toolkit)
[](https://github.com/nimosocute/ctf-codex-toolkit/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[English](#english) | [Tiếng Việt](#tieng-viet)
## English
专为 Kali Linux 和 Kali WSL 设计的 CTF Codex 配置。
`ctf-codex-toolkit` 通过 Kali shell 安装，可在原生 Kali 或 Kali WSL 中运行。安装程序会自动检测环境：
- 原生 Kali：仅安装 Linux 端的 Codex CTF 工具包。
- Kali WSL：安装相同的 Kali 端工具包，并恢复 Windows 启动器/快捷方式工作流。
它将受管理的 Codex CTF 环境安装到 Kali 中：skills、checklists、snippets、guard hooks、health checks、所需的 CTF 工具清单、可选的浏览器自动化助手，以及针对每个挑战的启动器。
预期的工作流程如下：
```
Kali shell
-> npm config set prefix ~/.npm-global
-> npm install -g ctf-codex-toolkit
-> ctf-codex-toolkit setup
-> auto-detect Kali native vs Kali WSL
-> ~/.codex CTF payload
-> required CTF tools from tools_inventory.md
-> /opt/codex-ctf-hooks guard hooks
-> WSL only: Windows launcher + Desktop shortcut
-> ctf-codex
-> ~/ctf-workspaces/_work/
-> codex inside Kali
```
## 目录
- [本项目提供的功能](#what-this-project-provides)
- [安装说明](#install)
- [日常使用](#daily-usage)
- [环境要求](#requirements)
- [工作原理](#how-it-works)
- [命令参考](#command-reference)
- [已安装的文件](#installed-files)
- [工作区模型](#workspace-model)
- [Skill 积分与更新](#skill-credits-and-updates)
- [Browser Arm](#browser-arm)
- [健康检查](#health-checks)
- [安全模型](#safety-model)
- [供应链说明](#supply-chain-notes)
- [贡献指南](#contributing)
- [License](#license)
## 本项目提供的功能
本代码仓库打包了在 Kali 内部将 Codex 作为 CTF 助手运行所需的各项操作组件。
| 领域 | 包含内容 |
| --- | --- |
| Codex CTF 策略 | 受管理的 `AGENTS.md`、类别路由、工作流指导 |
| Skills | Web、pwn、crypto、reverse、forensics、OSINT、malware、AI/ML、misc、solve dispatcher、writeup |
| Guard hooks | 针对大规模扫描、高风险命令和超大规模候选循环的工具前置检查 |
| 健康检查 | 用于 CTF 工具、provider、Browser Arm、hooks 的一次性环境清单检查 |
| CTF tools | `tools_inventory.md` 中列出的工具所需的 bootstrap |
| 浏览器支持 | 使用固定版本 `cloakbrowser==0.3.31` 的可选隔离 Browser Arm venv |
| 启动器 | 供日常使用的 `/usr/local/bin/ctf-codex `；在全局安装 npm 后，`ctf-codex-toolkit ` 也可使用 |
| WSL 集成 | 在 Kali WSL 内运行时，写入 Windows `.ps1`/`.cmd` 启动器和桌面快捷方式 |
| 工作区布局 | 用户选择的 CTF 根目录下针对每个挑战的目录 |
该软件包特意未提供 Codex provider 配置。用户需在本代码仓库之外保留自己的官方 OpenAI Codex 配置或兼容的第三方配置。
## 安装说明
以下所有命令均在 Kali Linux 或 Kali WSL 中运行。
如果缺少先决条件，请进行安装：
```
sudo apt update
sudo apt install -y nodejs npm python3 python3-venv git sudo
```
验证 Kali 中是否可用 Codex CLI：
```
codex --version
```
推荐日常使用做法：在 Kali 中全局安装 CLI，然后运行 setup。
使用 sudo 进行系统级安装：
```
sudo npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
从 `0.1.23` 版本开始，npm 包不再直接安装 `ctf-codex` 二进制文件。该名称归 `ctf-codex-toolkit setup` 所有，每次运行 setup 时都会覆盖旧的 `/usr/local/bin/ctf-codex` 启动器。
如果您不想使用 sudo，请使用用户拥有的 npm prefix：
```
npm config set prefix ~/.npm-global
mkdir -p ~/.npm-global/bin
grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
用户拥有的 prefix 可以避免由于尝试将全局包写入 `/usr/local` 而导致的常见 npm `EACCES` 错误。
如果您已经遇到 `EACCES` 错误，请运行相同的修复命令：
```
npm config set prefix ~/.npm-global
mkdir -p ~/.npm-global/bin
grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
进行指定版本的全局安装：
```
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit@0.1.23
ctf-codex-toolkit setup
```
不进行全局安装的一次性 setup 也可以，但管理命令必须再次通过 `npm exec` 运行：
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup
```
在 setup 之后启动挑战会话：
```
ctf-codex
```
恢复某个挑战的上次会话：
```
ctf-codex -Resume
```
如果您已进行全局安装，这也适用：
```
ctf-codex-toolkit
```
在测试未发布的更改时，直接从 GitHub 安装：
```
npm exec --yes --package github:nimosocute/ctf-codex-toolkit -- ctf-codex-toolkit setup
```
## 日常使用
在 Kali WSL 上，使用 setup 创建的 Windows 快捷方式：
```
Desktop\CTF Codex WSL.lnk
```
出现提示时，输入挑战名称，例如：
```
bachdeptrai
```
启动器会查找或创建：
```
/_work/bachdeptrai
```
然后它会在该工作区内启动 Codex。要继续之前的 Codex 对话，请在 Codex 会话内使用 Codex 的内置命令：
```
/resume
```
在原生 Kali 上，请对 `ctf-codex` 使用相同的挑战名称。例如，如果挑战名为 `bachdeptrai`，则工作区为 `/_work/bachdeptrai`；请将 `` 替换为您实际的挑战名称：
```
ctf-codex
```
稍后更新 Kali payload 和 Windows 快捷方式：
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup --skip-health --skip-tools
```
## 环境要求
- Kali Linux 或 Kali WSL
- Kali 中的 Node.js/npm
- Python 3 和 `python3-venv`
- Git
- 用于安装 `/opt/codex-ctf-hooks/*` 和 `/usr/local/bin/ctf-codex` 的 `sudo` 权限
- 在 Kali 中安装并可用作 `codex` 的 Codex CLI
本软件包不安装 Kali Linux、WSL 或 Codex CLI。它仅配置现有的 Kali 环境以适应专注于 CTF 的 Codex 工作流。
当在 Kali WSL 中运行 setup 且 Windows interop 可用时，它还会写入：
```
%USERPROFILE%\ctf-codex-wsl.ps1
%USERPROFILE%\ctf-codex-wsl.cmd
Desktop\CTF Codex WSL.lnk
```
原生 Kali 安装会自动跳过这些 Windows 文件。
使用非默认的 CTF 根目录：
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup --ctf-root ~/ctf
ctf-codex --ctf-root ~/ctf
```
在 `setup` 或 `install` 期间，CLI 会询问放置 CTF 工作区根目录的位置，并将答案存储在：
```
~/.ctf-codex-toolkit.json
```
按 Enter 键以使用：
```
~/ctf-workspaces
```
启动器还会遵循以下设置：
- `CTF_CODEX_ROOT`
- `CTF_ROOT`
- `CODEX_BIN`
显式的 CLI flags 优先于环境变量和已保存的配置。
## 工作原理
```
flowchart LR
A["Kali shell"] --> B["npm install -g ctf-codex-toolkit + setup"]
B --> C{"Kali WSL?"}
C -->|No| D["Install Kali-native toolkit"]
C -->|Yes| E["Install Kali toolkit + Windows launchers"]
D --> F["~/.codex + /opt hooks + ctf-codex"]
E --> F
F --> G["Run health checks"]
G --> H["ctf-codex "]
H --> I["~/ctf-workspaces/_work/"]
I --> J["codex inside Kali"]
```
Setup 执行五项任务：
1. 将受管理的 payload 复制到 `~/.codex`。
2. 在 Kali 中本地安装 guard hooks 和 `ctf-codex` 启动器。
3. 除非跳过，否则安装并验证映射自 `tools_inventory.md` 的 CTF 工具。
4. 准备可选的辅助环境，除非跳过，否则包括 Browser Arm。
5. 仅在 Kali WSL 中，安装 Windows 启动器文件和桌面快捷方式。
默认情况下需要安装工具。它首先使用 Kali apt，然后对最小化 Kali 中通常缺少的清单工具使用备用安装程序：
- 当缺少 apt 包时，用于 Python CTF 库的 `/opt/codex-ctf-python` venv。
- 用于 `yosys` 和 `bitwuzla` 的 `/opt/oss-cad-suite`。
- 如果 apt 不提供 `sage`，则通过 micromamba 安装 SageMath 的 `/opt/codex-ctf-sage`。
- 如果 apt 包不可用，则使用 Go 备用方案安装 `ffuf`。
- Chromium 运行时库以及用于 `cloakbrowser==0.3.31` 的隔离 Browser Arm venv。
bootstrap 之后，setup 会运行健康检查。如果仍有任何清单工具缺失，setup 将以真正的错误退出，而不是报告安装成功。
setup 之后，挑战会话将在以下目录运行：
```
/_work/
```
## 命令参考
建议在 Kali 中进行全局安装以供日常使用，因为它使所有 `ctf-codex-toolkit ...` 管理命令可直接使用。如果您使用了一次性 `npm exec`，请再次通过 `npm exec` 运行管理命令。安装的日常挑战启动器始终是 `ctf-codex`。
```
ctf-codex-toolkit --help
ctf-codex-toolkit -h
ctf-codex-toolkit --version
ctf-codex-toolkit version
ctf-codex-toolkit setup [--ctf-root ] [--no-browser-arm] [--skip-tools] [--skip-health]
ctf-codex-toolkit install [--ctf-root ] [--no-browser-arm] [--skip-tools]
ctf-codex-toolkit install-tools
ctf-codex-toolkit health
ctf-codex-toolkit update-skills [--source https://github.com/ljagiello/ctf-skills.git]
ctf-codex-toolkit install-launchers
ctf-codex --help
ctf-codex [-Resume] [--ctf-root ]
ctf-codex-toolkit [-Resume] [--ctf-root ] # only if globally installed
ctf-codex-workflow [options]
ctf-codex-wsl [options]
```
未进行全局安装的示例：
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit health
```
兼容性别名：
```
ctf-codex-workflow
ctf-codex-wsl
```
`ctf-codex` 是由 `ctf-codex-toolkit setup` 安装的日常启动器；它不是 npm bin 别名。
`setup` 是常用的入口点。它运行 `install`，然后运行 `health`。
当尚未安装可选工具时，请使用 `--skip-health`：
```
ctf-codex-toolkit setup --skip-health
```
使用 `--skip-tools` 仅安装 Codex payload、hooks、启动器和可选的 Browser Arm，而不安装完整的 CTF 清单：
```
ctf-codex-toolkit setup --skip-tools
```
稍后安装或仅修复工具清单：
```
ctf-codex-toolkit install-tools
```
使用 `--no-browser-arm` 完全跳过 Browser Arm：
```
ctf-codex-toolkit setup --no-browser-arm
```
在 Kali WSL 内使用 `install-launchers` 可仅重新创建 Windows 启动器文件和桌面快捷方式：
```
ctf-codex-toolkit install-launchers
```
当从 Kali WSL 启动 Windows 快捷方式时，它会检查已发布的 npm `latest` 版本。如果有更新的工具包版本可用，启动器会提示：
```
Update available! ->
> 1. Update now
2. Skip
3. Skip until next version
```
选择更新将刷新 Kali WSL 中的工具包 payload、启动器和已保存的工具包版本，然后继续启动挑战。它跳过完整的 CTF 工具清单安装；当您想要修复或重新安装工具时，请运行 `ctf-codex-toolkit install-tools`。Windows 启动器拥有自己嵌入的 `LauncherVersion`，因此即使 WSL 配置已包含更新的工具包版本，也会检测到过期的快捷方式文件。
如果 Codex 在打开之前失败，Windows 启动器将保持控制台打开并打印 WSL 退出代码。常见原因是未在 Kali 中安装 Codex CLI、WSL `PATH` 中缺少 `codex` 或 WSL 发行版名称错误。
## 已安装的文件
在 Kali 中，`install` 会写入：
```
~/.codex/AGENTS.md
~/.codex/ctf-checklists.md
~/.codex/ctf-snippets/
~/.codex/skills/ctf-*
~/.codex/skills/solve-challenge
~/.codex/skills/ctf-writeup
~/.codex/tools/ctf_health_check.py
~/.codex/tools/browser_arm/browser_server.py
~/.codex/tools/browser_arm/browser_client.py
~/.ctf-codex-toolkit.json
/opt/codex-ctf-hooks/*
/usr/local/bin/ctf-codex
```
仅在 Kali WSL 中，setup 还会通过 Windows interop 写入 Windows 端的启动器文件：
```
%USERPROFILE%\ctf-codex-wsl.ps1
%USERPROFILE%\ctf-codex-wsl.cmd
Desktop\CTF Codex WSL.lnk
```
安装程序不会复制：
- `~/.codex/config.toml`
- provider 密钥
- API tokens
- 会话
- 日志
- cookies
- `.env` 文件
- 私钥
- 运行时的 SQLite 状态
安装程序将 hook 可执行文件写入 `/opt/codex-ctf-hooks`，并将它们符号链接到 `~/.codex/hooks`。它故意不重写 `~/.codex/config.toml`，因为 provider 和运行时配置归用户所有。验证您的 Codex 运行时是否从 `~/.codex/hooks` 加载 hooks；如果您的 Codex 构建需要在 `config.toml` 中显式注册 hook，请注册：
```
/opt/codex-ctf-hooks/ctf_pre_tool_guard.py
/opt/codex-ctf-hooks/ctf_post_tool_guard.py
/opt/codex-ctf-hooks/ctf_stop_guard.py
```
## 工作区模型
CTF 根目录在 setup 期间选择。名为 `web_login` 的挑战将创建或使用：
```
~/ctf-workspaces/_work/web_login
```
该目录成为 Codex 的工作目录。
示例：
```
ctf-codex
ctf-codex -Resume
```
## Skill 积分与更新
打包的 CTF skill 目录衍生自 [ljagiello/ctf-skills](https://github.com/ljagiello/ctf-skills.git)。上游 CTF skill 内容的积分属于该项目及其贡献者。
此工具包将这些 skills 与 Kali 启动器、guard hooks、健康检查、snippets 和 CTF 工作流文件打包在一起。
从上游自动更新：
```
ctf-codex-toolkit update-skills
```
从 fork 或兼容的代码仓库自动更新：
```
ctf-codex-toolkit update-skills --source https://github.com//.git
```
更新程序在 Kali 中运行，克隆源代码仓库，查找包含 `SKILL.md` 的 skill 目录，并刷新以下位置中匹配的 CTF skill 目录：
```
~/.codex/skills/
```
它更新名为 `ctf-*`、`solve-challenge` 和 `ctf-writeup` 的目录。它不会删除不相关的用户 skill。
在 Kali 中手动更新：
```
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/ljagiello/ctf-skills.git "$tmp/ctf-skills"
mkdir -p ~/.codex/skills
find "$tmp/ctf-skills" -mindepth 1 -maxdepth 3 -name SKILL.md -type f -print |
while read -r skill_file; do
skill_dir="$(dirname "$skill_file")"
name="$(basename "$skill_dir")"
case "$name" in
ctf-*|solve-challenge|ctf-writeup)
rm -rf "$HOME/.codex/skills/$name"
cp -a "$skill_dir" "$HOME/.codex/skills/$name"
;;
esac
done
rm -rf "$tmp"
```
请参阅 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
## Browser Arm
默认情况下，`setup` 和 `install` 会在以下位置创建一个隔离的 venv：
```
~/.codex/tools/browser_arm/.venv
```
并安装：
```
cloakbrowser==0.3.31
```
CloakBrowser 是来自 [CloakHQ/CloakBrowser]() 的 MIT 许可浏览器自动化项目。此工具包仅将其用于可选的 Browser Arm 工作流：在 CTF Web 挑战期间执行 JavaScript、DOM 检查、存储检查、控制台日志和网络日志。
CloakBrowser 安装在隔离的 Browser Arm venv 中，而不是全局安装。首次使用时，CloakBrowser 可能会下载并缓存其 Chromium 二进制文件。
Browser Arm 服务器绑定到 `127.0.0.1` 并需要本地共享 token。默认情况下，服务器在 `BROWSER_WORKDIR` 中创建 `.browser_token`，捆绑的客户端会自动读取它。您也可以在启动这两个进程时显式设置 `BROWSER_TOKEN` 或 `BROWSER_TOKEN_FILE`。
最小化的 Kali 安装可能不包含所有 Chromium 共享库。如果 `ctf-codex-toolkit health` 报告诸如 `libnspr4.so: cannot open shared object file` 之类的 Browser Arm 错误，请安装浏览器运行时依赖项：
```
sudo apt install -y libnspr4 libnss3 libatk-bridge2.0-0 libgtk-3-0 libgbm1 libxkbcommon0
```
跳过此依赖项：
```
ctf-codex-toolkit setup --no-browser-arm
```
## 健康检查
在 Kali 中运行：
```
ctf-codex-toolkit health
```
健康检查会验证已安装的 CTF payload、选定的工具、provider 就绪信号、Browser Arm 文件以及 hook 可用性。它旨在安装后快速捕获损坏或不一致的 setup 状态。
在最小化的 Kali 上，`setup` 会首先安装并验证清单工具，包括 pwn、reverse、forensics、Web 模糊测试、破解、硬件助手以及 Browser Arm 使用的 Chromium 运行时库。诸如 `sagemath`、`ghidra`、`python3-angr` 和 oss-cad-suite 等大型包可能需要时间和磁盘空间。
## 安全模型
pre-tool guard 会阻止高风险的自动化攻击命令和广泛的候选搜索，同时允许小型的确定性循环。路径限制检查会在比较之前规范化路径，因此在工具运行之前会拒绝通过 patch/edit/write 目标的 `..` 遍历。
这是针对常见错误的纵深防御。它不是沙箱，不是安全边界，也不能替代在限定范围的 CTF 工作区中运行 Codex。静态脚本扫描是尽力而为的：会检查内联的 `python -c`/`node -e` payload 和脚本文件，但在解释器启动之前不会完全解析通过管道或 heredoc 提供的代码。
当前的回归测试包括：
- `range(1<<20)` 被阻止
- `range(10**8)` 被阻止
- `range(100000000)` 被阻止
- `range(2**20)` 被阻止
- `range(2**10)` 被允许
- 小型的 shell `for` 循环被允许
- `hashcat` 被阻止
## 供应链说明
对于正常安装，首选已发布的 npm 包：
```
npm exec --yes --package ctf-codex-toolkit@0.1.23 -- ctf-codex-toolkit setup
```
GitHub 安装形式会直接执行代码仓库内容：
```
npm exec --yes --package github:nimosocute/ctf-codex-toolkit -- ctf-codex-toolkit setup
```
对于共享或敏感环境：
- 在运行 setup 之前检查代码仓库。
- 尽可能固定 npm 版本、Git tag 或 Git commit。
- 优先选择 npm 包，而不是可变的 GitHub 分支安装。
- 在本地修改包时运行 `npm run smoke`。
CI 会在推送和 pull request 时运行 `npm run smoke` 和 `npm pack --dry-run`。
## 贡献指南
贡献者和发布说明位于 [CONTRIBUTING.md](CONTRIBUTING.md) 中。
开发检查：
```
npm run smoke
npm pack --dry-run
```
## License
[MIT](LICENSE)
## Tiếng Việt
`ctf-codex-toolkit` là bộ cài đặt Codex tập trung cho CTF trên Kali Linux và Kali WSL.
Toolkit được cài từ shell Kali, chạy được trên Kali native hoặc Kali WSL. Trình cài đặt tự nhận diện môi trường:
- Kali native: chỉ cài phần toolkit trong Linux/Kali.
- Kali WSL: cài cùng toolkit trong Kali và tạo thêm launcher/shortcut phía Windows.
Toolkit cài môi trường Codex CTF được quản lý vào Kali: skills, checklist, snippets, guard hooks, health checks, danh sách công cụ CTF cần thiết, Browser Arm tùy chọn, và launcher theo từng challenge.
Luồng sử dụng chính:
```
Kali shell
-> npm config set prefix ~/.npm-global
-> npm install -g ctf-codex-toolkit
-> ctf-codex-toolkit setup
-> tự nhận diện Kali native hay Kali WSL
-> ~/.codex CTF payload
-> công cụ CTF từ tools_inventory.md
-> /opt/codex-ctf-hooks guard hooks
-> chỉ WSL: Windows launcher + Desktop shortcut
-> nhập tên challenge
-> ~/ctf-workspaces/_work/
-> Codex chạy bên trong Kali
```
### Mục lục
- [Toolkit cung cấp gì](#toolkit-cung-cap-gi)
- [Cài đặt](#cai-dat)
- [Sử dụng hằng ngày](#su-dung-hang-ngay)
- [Yêu cầu](#yeu-cau)
- [Cách hoạt động](#cach-hoat-dong)
- [Lệnh thường dùng](#lenh-thuong-dung)
- [File được cài](#file-duoc-cai)
- [Mô hình workspace](#mo-hinh-workspace)
- [Cập nhật skills](#cap-nhat-skills)
- [Browser Arm](#browser-arm-1)
- [Health checks](#health-checks-1)
- [Mô hình an toàn](#mo-hinh-an-toan)
- [Ghi chú supply chain](#ghi-chu-supply-chain)
- [Đóng góp](#dong-gop)
- [License](#license-1)
### Toolkit cung cấp gì
Repo này đóng gói các phần cần thiết để chạy Codex như một trợ lý CTF bên trong Kali.
| Nhóm | Nội dung |
| --- | --- |
| Chính sách Codex CTF | `AGENTS.md` được quản lý, định tuyến category, hướng dẫn workflow |
| Skills | Web, pwn, crypto, reverse, forensics, OSINT, malware, AI/ML, misc, solve dispatcher, writeup |
| Guard hooks | Kiểm tra trước khi chạy tool để chặn scan rộng, lệnh rủi ro cao, vòng lặp candidate quá lớn |
| Health checks | Kiểm tra nhanh payload, tools, provider readiness, Browser Arm, hooks |
| CTF tools | Bootstrap các tool trong `tools_inventory.md` |
| Browser support | Browser Arm tùy chọn, dùng venv riêng với `cloakbrowser==0.3.31` |
| Launchers | `/usr/local/bin/ctf-codex ` cho sử dụng hằng ngày; `ctf-codex-toolkit ` cũng dùng được nếu đã cài npm global |
| WSL integration | Khi chạy trong Kali WSL, tạo Windows `.ps1`/`.cmd` launcher và Desktop shortcut |
| Workspace layout | Mỗi challenge có thư mục riêng dưới CTF root |
Toolkit không kèm cấu hình provider của Codex. Người dùng giữ config OpenAI Codex hoặc config provider khác bên ngoài repo này.
### Cài đặt
Tất cả lệnh bên dưới chạy trong Kali Linux hoặc Kali WSL.
Cài dependency cơ bản nếu thiếu:
```
sudo apt update
sudo apt install -y nodejs npm python3 python3-venv git sudo
```
Kiểm tra Codex CLI có sẵn trong Kali:
```
codex --version
```
Cách khuyến nghị để dùng hằng ngày: cài CLI global bên trong Kali, rồi chạy setup.
Cài system-wide bằng sudo:
```
sudo npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
Từ `0.1.23`, npm package không còn cài trực tiếp binary `ctf-codex`. Tên đó thuộc về `ctf-codex-toolkit setup`, và setup sẽ ghi đè launcher cũ ở `/usr/local/bin/ctf-codex` mỗi lần chạy.
Nếu không muốn dùng sudo, dùng npm prefix nằm trong home của user:
```
npm config set prefix ~/.npm-global
mkdir -p ~/.npm-global/bin
grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
Prefix trong home tránh lỗi npm `EACCES` thường gặp khi npm cố ghi global package vào `/usr/local`.
Nếu bạn đã gặp `EACCES`, chạy lại các lệnh sửa này:
```
npm config set prefix ~/.npm-global
mkdir -p ~/.npm-global/bin
grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit
ctf-codex-toolkit setup
```
Cài global theo version cố định:
```
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g ctf-codex-toolkit@0.1.23
ctf-codex-toolkit setup
```
Setup one-shot không cài global vẫn dùng được, nhưng các lệnh quản trị sau đó phải chạy lại qua `npm exec`:
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup
```
Mở một challenge sau khi setup:
```
ctf-codex
```
Resume session cuối của challenge:
```
ctf-codex -Resume
```
Nếu đã cài global, lệnh này cũng dùng được:
```
ctf-codex-toolkit
```
Cài trực tiếp từ GitHub khi test thay đổi chưa release:
```
npm exec --yes --package github:nimosocute/ctf-codex-toolkit -- ctf-codex-toolkit setup
```
### Sử dụng hằng ngày
Trên Kali WSL, dùng shortcut Windows được tạo bởi setup:
```
Desktop\CTF Codex WSL.lnk
```
Khi được hỏi, nhập tên bài, ví dụ:
```
bachdeptrai
```
Launcher sẽ tìm hoặc tạo:
```
/_work/bachdeptrai
```
Sau đó launcher mở Codex ngay trong workspace đó. Nếu muốn quay lại đoạn chat trước trong Codex, dùng lệnh có sẵn của Codex trong phiên Codex:
```
/resume
```
Trên Kali native, dùng cùng tên bài với `ctf-codex`. Ví dụ nếu bài tên là `bachdeptrai`, workspace sẽ là `/_work/bachdeptrai`; hãy thay `` bằng tên bài thật:
```
ctf-codex
```
Khi cần cập nhật payload Kali và Windows shortcut:
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup --skip-health --skip-tools
```
### Yêu cầu
- Kali Linux hoặc Kali WSL
- Node.js/npm trong Kali
- Python 3 và `python3-venv`
- Git
- `sudo` để cài `/opt/codex-ctf-hooks/*` và `/usr/local/bin/ctf-codex`
- Codex CLI đã cài trong Kali và gọi được bằng lệnh `codex`
Package này không cài Kali Linux, WSL, hoặc Codex CLI. Nó chỉ cấu hình môi trường Kali đã có để dùng Codex cho CTF.
Khi setup chạy trong Kali WSL và Windows interop hoạt động, nó cũng ghi:
```
%USERPROFILE%\ctf-codex-wsl.ps1
%USERPROFILE%\ctf-codex-wsl.cmd
Desktop\CTF Codex WSL.lnk
```
Kali native sẽ bỏ qua các file Windows này.
Dùng CTF root khác mặc định:
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit setup --ctf-root ~/ctf
ctf-codex --ctf-root ~/ctf
```
Trong lúc `setup` hoặc `install`, CLI hỏi nơi đặt CTF workspace root và lưu vào:
```
~/.ctf-codex-toolkit.json
```
Nhấn Enter để dùng mặc định:
```
~/ctf-workspaces
```
Launcher cũng đọc:
- `CTF_CODEX_ROOT`
- `CTF_ROOT`
- `CODEX_BIN`
CLI flags có độ ưu tiên cao hơn environment variables và config đã lưu.
### Cách hoạt động
```
flowchart LR
A["Kali shell"] --> B["npm install -g ctf-codex-toolkit + setup"]
B --> C{"Kali WSL?"}
C -->|No| D["Cài Kali-native toolkit"]
C -->|Yes| E["Cài Kali toolkit + Windows launchers"]
D --> F["~/.codex + /opt hooks + ctf-codex"]
E --> F
F --> G["Chạy health checks"]
G --> H["ctf-codex "]
H --> I["~/ctf-workspaces/_work/"]
I --> J["Codex bên trong Kali"]
```
Setup làm năm việc:
1. Copy payload được quản lý vào `~/.codex`.
2. Cài guard hooks và launcher `ctf-codex` trong Kali.
3. Cài và kiểm tra CTF tools trong `tools_inventory.md`, trừ khi bỏ qua.
4. Chuẩn bị helper environment tùy chọn, gồm Browser Arm nếu không tắt.
5. Chỉ trong Kali WSL, cài Windows launcher files và Desktop shortcut.
Mặc định setup sẽ cài tool inventory. Nó dùng apt của Kali trước, sau đó dùng fallback installer cho những tool hay thiếu trên Kali minimal:
- `/opt/codex-ctf-python` venv cho Python CTF libraries khi apt thiếu package.
- `/opt/oss-cad-suite` cho `yosys` và `bitwuzla`.
- `/opt/codex-ctf-sage` qua micromamba cho SageMath nếu apt không có `sage`.
- Go fallback cho `ffuf` nếu apt thiếu.
- Chromium runtime libraries và Browser Arm venv riêng cho `cloakbrowser==0.3.31`.
Sau bootstrap, setup chạy health check. Nếu tool inventory vẫn thiếu, setup sẽ báo lỗi thật thay vì báo cài thành công.
Sau setup, session challenge chạy dưới:
```
/_work/
```
### Lệnh thường dùng
Cài global trong Kali là cách khuyến nghị nếu dùng thường xuyên, vì mọi lệnh quản trị `ctf-codex-toolkit ...` sẽ gọi trực tiếp được. Nếu dùng one-shot `npm exec`, các lệnh quản trị cần chạy qua `npm exec` lại. Launcher mở bài hằng ngày luôn được cài là `ctf-codex`.
```
ctf-codex-toolkit --help
ctf-codex-toolkit -h
ctf-codex-toolkit --version
ctf-codex-toolkit version
ctf-codex-toolkit setup [--ctf-root ] [--no-browser-arm] [--skip-tools] [--skip-health]
ctf-codex-toolkit install [--ctf-root ] [--no-browser-arm] [--skip-tools]
ctf-codex-toolkit install-tools
ctf-codex-toolkit health
ctf-codex-toolkit update-skills [--source https://github.com/ljagiello/ctf-skills.git]
ctf-codex-toolkit install-launchers
ctf-codex --help
ctf-codex [-Resume] [--ctf-root ]
ctf-codex-toolkit [-Resume] [--ctf-root ] # chỉ khi đã cài global
ctf-codex-workflow [options]
ctf-codex-wsl [options]
```
Ví dụ không cài global:
```
npm exec --yes --package ctf-codex-toolkit@latest -- ctf-codex-toolkit health
```
Alias tương thích:
```
ctf-codex-workflow
ctf-codex-wsl
```
`ctf-codex` là launcher dùng hằng ngày do `ctf-codex-toolkit setup` cài; nó không phải npm bin alias.
`setup` là entry point thông thường. Nó chạy `install` rồi chạy `health`.
Dùng `--skip-health` khi chưa muốn kiểm tra tool tùy chọn:
```
ctf-codex-toolkit setup --skip-health
```
Dùng `--skip-tools` để chỉ cài payload, hooks, launchers, và Browser Arm tùy chọn, không cài toàn bộ CTF inventory:
```
ctf-codex-toolkit setup --skip-tools
```
Cài hoặc sửa riêng tool inventory sau:
```
ctf-codex-toolkit install-tools
```
Bỏ qua Browser Arm hoàn toàn:
```
ctf-codex-toolkit setup --no-browser-arm
```
Trong Kali WSL, tạo lại riêng Windows launcher files và Desktop shortcut:
```
ctf-codex-toolkit install-launchers
```
Khi chạy Windows shortcut từ Kali WSL, launcher kiểm tra version `latest` trên npm. Nếu có bản mới hơn, nó hiện:
```
Update available! ->
> 1. Update now
2. Skip
3. Skip until next version
```
Chọn update sẽ cập nhật payload, launcher, và version đã lưu trong Kali WSL, rồi tiếp tục mở challenge Nó bỏ qua cài lại full CTF inventory; dùng `ctf-codex-toolkit install-tools` khi muốn sửa hoặc cài lại tools. Windows launcher có `LauncherVersion` riêng, nên shortcut cũ vẫn bị phát hiện ngay cả khi config WSL đã ghi version toolkit mới hơn.
Nếu Codex không mở được, Windows launcher giữ console và in WSL exit code. Nguyên nhân thường gặp là Codex CLI chưa cài trong Kali, `codex` không có trong WSL `PATH`, hoặc sai tên WSL distro.
### File được cài
Trong Kali, `install` ghi:
```
~/.codex/AGENTS.md
~/.codex/ctf-checklists.md
~/.codex/ctf-snippets/
~/.codex/skills/ctf-*
~/.codex/skills/solve-challenge
~/.codex/skills/ctf-writeup
~/.codex/tools/ctf_health_check.py
~/.codex/tools/browser_arm/browser_server.py
~/.codex/tools/browser_arm/browser_client.py
~/.ctf-codex-toolkit.json
/opt/codex-ctf-hooks/*
/usr/local/bin/ctf-codex
```
Chỉ trong Kali WSL, setup cũng ghi file launcher phía Windows qua Windows interop:
```
%USERPROFILE%\ctf-codex-wsl.ps1
%USERPROFILE%\ctf-codex-wsl.cmd
Desktop\CTF Codex WSL.lnk
```
Installer không copy:
- `~/.codex/config.toml`
- provider keys
- API tokens
- sessions
- logs
- cookies
- `.env` files
- private keys
- runtime SQLite state
Installer ghi hook executable vào `/opt/codex-ctf-hooks` và symlink vào `~/.codex/hooks`. Nó không tự sửa `~/.codex/config.toml` vì provider/runtime config thuộc về người dùng. Hãy kiểm tra Codex runtime của bạn có load hooks từ `~/.codex/hooks`; nếu bản Codex yêu cầu đăng ký hook rõ trong `config.toml`, đăng ký:
```
/opt/codex-ctf-hooks/ctf_pre_tool_guard.py
/opt/codex-ctf-hooks/ctf_post_tool_guard.py
/opt/codex-ctf-hooks/ctf_stop_guard.py
```
### Mô hình workspace
CTF root được chọn khi setup. Challenge tên `web_login` sẽ tạo hoặc dùng:
```
~/ctf-workspaces/_work/web_login
```
Thư mục đó trở thành working directory cho Codex.
Ví dụ:
```
ctf-codex
ctf-codex -Resume
```
### Cập nhật skills
Các thư mục CTF skill được lấy từ [ljagiello/ctf-skills](https://github.com/ljagiello/ctf-skills.git). Credit nội dung CTF skill thuộc về project upstream và contributors của họ.
Toolkit này đóng gói các skills đó cùng Kali launchers, guard hooks, health checks, snippets, và CTF workflow files.
Cập nhật tự động từ upstream:
```
ctf-codex-toolkit update-skills
```
Cập nhật từ fork hoặc repo tương thích:
```
ctf-codex-toolkit update-skills --source https://github.com//.git
```
Updater chạy trong Kali, clone source repository, tìm các thư mục skill có `SKILL.md`, rồi refresh các CTF skill tương ứng dưới:
```
~/.codex/skills/
```
Nó cập nhật các thư mục tên `ctf-*`, `solve-challenge`, và `ctf-writeup`. Nó không xóa skill riêng không liên quan của người dùng.
Cập nhật thủ công trong Kali:
```
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/ljagiello/ctf-skills.git "$tmp/ctf-skills"
mkdir -p ~/.codex/skills
find "$tmp/ctf-skills" -mindepth 1 -maxdepth 3 -name SKILL.md -type f -print |
while read -r skill_file; do
skill_dir="$(dirname "$skill_file")"
name="$(basename "$skill_dir")"
case "$name" in
ctf-*|solve-challenge|ctf-writeup)
rm -rf "$HOME/.codex/skills/$name"
cp -a "$skill_dir" "$HOME/.codex/skills/$name"
;;
esac
done
rm -rf "$tmp"
```
Xem thêm [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
### Browser Arm
Mặc định, `setup` và `install` tạo venv riêng tại:
```
~/.codex/tools/browser_arm/.venv
```
và cài:
```
cloakbrowser==0.3.31
```
CloakBrowser là project browser automation license MIT từ [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser). Toolkit chỉ dùng nó cho Browser Arm workflow tùy chọn: chạy JavaScript, xem DOM, xem storage, console logs, và network logs trong web CTF challenges.
CloakBrowser được cài trong Browser Arm venv riêng, không cài global. Lần dùng đầu tiên, CloakBrowser có thể tải và cache Chromium binary.
Browser Arm server bind `127.0.0.1` và yêu cầu local shared token. Mặc định server tạo `.browser_token` trong `BROWSER_WORKDIR` và client đi kèm tự đọc token đó. Bạn cũng có thể set `BROWSER_TOKEN` hoặc `BROWSER_TOKEN_FILE` khi start cả server và client.
Kali minimal có thể thiếu Chromium shared libraries. Nếu `ctf-codex-toolkit health` báo lỗi Browser Arm như `libnspr4.so: cannot open shared object file`, cài runtime dependencies:
```
sudo apt install -y libnspr4 libnss3 libatk-bridge2.0-0 libgtk-3-0 libgbm1 libxkbcommon0
```
Bỏ qua dependency này:
```
ctf-codex-toolkit setup --no-browser-arm
```
### Health checks
Chạy trong Kali:
```
ctf-codex-toolkit health
```
Health check kiểm tra payload đã cài, selected tools, provider readiness signals, Browser Arm files, và hook availability. Nó giúp phát hiện setup bị thiếu hoặc lệch trạng thái ngay sau khi cài.
Trên Kali minimal, `setup` cài và kiểm tra inventory tools trước, gồm pwn, reverse, forensics, web fuzzing, cracking, hardware helpers, và Chromium runtime libraries dùng bởi Browser Arm. Các package lớn như `sagemath`, `ghidra`, `python3-angr`, và oss-cad-suite có thể tốn thời gian và dung lượng.
### Mô hình an toàn
Pre-tool guard chặn các lệnh automated attack rủi ro cao và broad candidate search, nhưng vẫn cho phép loop nhỏ có tính quyết định. Path containment được canonicalize trước khi so sánh, nên traversal kiểu `..` qua patch/edit/write bị chặn trước khi tool chạy.
Đây là defense-in-depth cho lỗi thao tác thường gặp. Nó không phải sandbox, không phải security boundary, và không thay thế việc chạy Codex trong workspace CTF đã scoped. Static script scanning là best-effort: inline `python -c`/`node -e` payload và script files được kiểm tra, nhưng code đưa qua pipe hoặc heredoc không được parse đầy đủ trước khi interpreter start.
Regression checks hiện có:
- `range(1<<20)` bị chặn
- `range(10**8)` bị chặn
- `range(100000000)` bị chặn
- `range(2**20)` bị chặn
- `range(2**10)` được cho phép
- shell `for` loop nhỏ được cho phép
- `hashcat` bị chặn
### Ghi chú supply chain
Nên dùng package npm đã publish cho cài đặt thông thường:
```
npm exec --yes --package ctf-codex-toolkit@0.1.23 -- ctf-codex-toolkit setup
```
Dạng cài từ GitHub sẽ chạy trực tiếp nội dung repository:
```
npm exec --yes --package github:nimosocute/ctf-codex-toolkit -- ctf-codex-toolkit setup
```
Với môi trường shared hoặc nhạy cảm:
- Review repository trước khi chạy setup.
- Pin npm version, Git tag, hoặc Git commit khi có thể.
- Ưu tiên npm package thay vì GitHub branch mutable.
- Chạy `npm run smoke` khi sửa package local.
CI chạy `npm run smoke` và `npm pack --dry-run` trên push và pull request.
### Đóng góp
Contributor và release notes nằm trong [CONTRIBUTING.md](CONTRIBUTING.md).
Development checks:
```
npm run smoke
npm pack --dry-run
```
### License
[MIT](LICENSE)
标签：AI合规, CTF工具, Cutter, GNU通用公共许可证, MITM代理, Node.js, 暗色界面, 漏洞搜索, 自动化配置