OWASP CTF

一个用于安全学习活动的自托管控制平面——一台机器，一个免费的 GitHub 组织。
可为大学、高中、OWASP 分会或聚会运行。

参与本工具包的开发（人类与智能体）

在编写代码之前，请阅读 AGENTS.md。它是操作手册： CI 运行的确切命令、本仓库已经遇到过的失败模式，以及 docs/reviewing.md 中的审查不变量。CLAUDE.md 是指向 同一文件的指针。

当 CI 通过 且 最新提交上的每个可操作的 CodeRabbit 讨论串都已解决（或有记录地拒绝）时，变更才算就绪。 提交遵循 Conventional Commits，且不带有 AI 署名。

小而明确的工作会被标记为 good first issue。 新模块从 issue 开始，而不是 PR——参见 CONTRIBUTING.md。

这是什么

一个控制平面，而非单一游戏。 这台机器为活动提供共享 主干——一个 GitHub 组织、队伍注册、实时排行榜、组织者 管理面板，以及为其提供数据的评分流水线。模块将 挑战内容接入该主干，任意子集都可以单独或一起运行： 补丁计分的 Secure Development、Quiz 题库、 Jeopardy 面板，以及外部托管的 AI 挑战。模块 契约是主干与内容之间的边界， 因此这台机器被构建为可承载更多模块—— 取证、API 安全、云——随着它们落地。

它为何存在。 Secure Development 模块教授的是防御而非 攻击，而且它是教授安全编码的一种真正出色的方式。直到现在， 运行一次意味着要搭建 Vercel、Upstash、Lambda 和 DynamoDB，承担 云账单，并拥有对私有评分镜像的访问权限。对于有预算的会议来说，这是 一个合理的请求。对于大学安全课程、高中社团、OWASP 分会之夜或 周末工作坊来说，这是一个不合理的请求。

本工具包消除了这一障碍。一切都在你已有的单台机器上通过 Docker Compose 运行——一台笔记本电脑、一台闲置台式机、一台小型 VPS——再加上一个免费的 GitHub 组织用于 fork。全部六个目标的评分标准都随工具包一起提供，因此 无需申请私有镜像，也无需编写评分代码。没有任何计费，没有任何数据回传， 活动结束后你归档仓库并停止该技术栈。

适用对象： 任何想运行此活动、又不想为此 成为云运维人员的人——课程讲师、社团组织者、OWASP 分会负责人、工作坊主持人、举办内部培训日的安全团队。

状态

已部署并端到端演练；尚未针对真实人群运行。 完整的 评分路径随工具包提供——评分器的 bearer 认证 POST /score、 用于 fork 的自包含评分工作流、轮询传输——并且 scripts/smoke.sh 针对 mock 驱动整条流水线。除此之外， 本工具包在本仓库所发布的同一份 Compose 文件下，在一台托管机器上持续运行， GET /health 会报告正在为其提供服务的精确修订版本，而对那个实时实例的 端到端测试正是发现并修复一批真实缺陷的地方——这类缺陷是 mock 测试套件无法看到的。

尚未发生的是真实活动：一群参赛者同时针对真实 fork 打开真实 PR，持续数小时。这就是"流水线能工作"与"流水线在 40 人规模下能工作" 之间的差距。有两个注意事项是公开而非被掩盖的：Security Shepherd 结果匹配器 有一个明确的残余限制（措辞异常的拒绝仍可能被读作解题——它 可能对正确的补丁少给分，但绝不会白送分），并且完整人群的 负载情况尚未测试。详情与当前状态：状态与上游依赖。

它不是什么

• 不是通用 CTF 平台。 CTFd 成熟、 久经考验，并拥有庞大的插件生态——如果你想要一个 具有最大灵活性的传统 jeopardy 或攻防活动， 请使用 CTFd。本工具包的 Jeopardy 模块刻意比 CTFd 更小。
• 不是托管练习场。 picoCTF 为你提供 零运维的课程和挑战——如果你不需要用你自己的内容和名单运行 你自己的活动，它是更好的答案。
• 不是攻击训练器。 旗舰模块评分的是补丁，而非 漏洞利用。参赛者修复漏洞，流水线证明修复有效。

它做到了那些平台做不到的事：通过 GitHub pull request 评分的补丁计分防御训练、用于在同一排行榜上混合多种游戏类型的模块契约， 以及一个你端到端拥有的控制平面——一台机器、一个免费组织、 无云账单、无遥测。

本项目不隶属于 OWASP Foundation，也未获其背书。 六个易受攻击目标中有四个是 OWASP 项目（Juice Shop、WebGoat、Security Shepherd、VulnerableApp）；DVWA 和 VAmPI 是社区项目。

快速开始

两分钟内看到它运行——无需 GitHub 组织、无需 OAuth 应用、无需 配置任何东西。你需要 带 Compose v2 的 Docker 和 openssl：```sh git clone https://github.com/dcotelo/owasp-ctf cd owasp-ctf ./scripts/dev-stack up

它会写入一次性的本地密钥，构建 scorer 和 app 镜像，启动整个技术栈，通过 scorer 的真实评分 API 播种一个演示排行榜，并打印要打开的 URL。你应该会看到带有已播种队伍的排行榜以及一个分数随时间变化的图表；`./scripts/dev-stack score <login> juice-shop 3` 会实时再计入三次解题。`./scripts/dev-stack down` 会将其拆除。

**运行真实赛事**时使用引导式向导。添加 **[`gh`
CLI](https://cli.github.com)**（已认证），如果赛事运行 Secure Development，还需添加**一个免费的 GitHub 组织**；`./setup/ctf-setup.sh check` 会先验证工具链：```sh
./setup/ctf-setup.sh            # guided, prompts for values, resumable

它会在进行过程中逐一询问每个值——你的 box URL、活动组织、管理员登录信息、你是否运行 Secure Development、GitHub 凭据——写入 .env，执行所有可自动化的步骤，引导你完成需要在 GitHub UI 中操作的步骤，并且在你中断后回来时能够恢复。其他所有内容（活动名称、运行哪些模块、哪些目标）都是运行时的 /admin 设置，因此没有需要编辑的配置文件。它只询问你实际需要的内容：没有 Secure Development 的活动不需要组织、不需要 fork、也不需要 scorer 镜像，并且永远不会被问及这些。使用 --dry-run 预览任何变更步骤——它会根据已经完整的 .env 叙述步骤 4–9，并在没有管理员登录信息，或 Secure Development 已开启但没有组织时（按设计）拒绝执行。向导最后会运行 ./setup/ctf-setup.sh doctor——一个你可以随时重新运行的按 fork 状态矩阵——然后提供可选的 fly.io 部署（默认否），因此将同一活动放到公共主机名上是一个引导式流程——主机名、预览部署，然后确认——而不是翻阅部署文档。

想要了解细节？ 每个独立的子命令、每个仅限 UI 的步骤，以及两个 GitHub 应用有何不同： docs/hosting.md。 想部署到云上？ docs/aws.md（Terraform：ECS Fargate、ElastiCache 和一个 ALB——apply 启动 / destroy 关闭）或 docs/fly.md（一台 Fly 机器）。

模块

Secure Development —— fork 一个故意存在漏洞的应用，找到缺陷，修补它，打开一个 PR。fork 中的 GitHub Action 会针对补丁运行目标的评分标准，分数会落到排行榜上（轮询模式下约 30 秒后）。六个目标，321 个挑战；原样得 0 分，正确的补丁获得其分数——双向门控。需要 GitHub 组织和评分流水线。

Quiz —— 单选和多选安全题目，在作答的那一刻就在应用内评分（多选为全有或全无），带有尝试次数上限和重试冷却时间。可以从 /admin 逐题编写，也可以作为一个 JSON 包导入和导出。不需要 GitHub、不需要 fork、不需要流水线。

Jeopardy —— 一个由组织者编写的按类别划分的 flag 面板。提交内容会被修剪和规范化，除非某个 flag 被标记为区分大小写（其卡片会注明），否则不区分大小写，并带有提交冷却时间和可选的付费提示。与 quiz 相同的 /admin + JSON 包编写方式。同样不需要 GitHub。

AI —— 托管在 box 外部的提示注入和护栏挑战。每位参赛者的挑战页面会为他们生成一个指向外部站点的个人启动链接；解题结果会回报到排行榜，可以通过该站点自己的回调，也可以将 flag 输入回应用中。不需要 GitHub、不需要 fork、不需要流水线。

围绕你启用的任何模块，平台提供：带队长的团队自助注册、加入码和 /join/<code> 链接（单人游玩即一人团队；由多名队友解出的 flag 只计一次）；带有 CTFd 风格分数随时间变化图表的实时排行榜，基于真实的每次解题时间戳；允许列表控制的 /admin 面板——冻结、评分和注册时间窗口、提示和费用、团队上限、冷却时间、模块内容、每位参赛者的支持操作、活动流和参与度指标——全部在运行时生效，无需重新构建；以及对每个管理员操作的有上限审计日志。

参赛者明细	挑战浏览器

Jeopardy flag 面板	Quiz

^{Captured from the contestant app running locally via scripts/dev-stack up with seeded demo players. Targets and fork links are event-config driven; the event name and the rest of its branding are admin-panel settings.}

工作原理

一个 Docker Compose 栈：Caddy 在 Next.js 应用前面终止 TLS；应用仅通过 srh（一个兼容 Upstash 的 REST 代理）与 Redis 通信——网络被拆分，因此任何面向互联网的组件都没有通往 redis:6379 的路由。Quiz、Jeopardy 和 AI 在应用内评分，并将分数直接存入 Redis。Secure Development 在 box 外部评分：参赛者的 fork 运行一个 GitHub Action，该 Action 启动目标，针对补丁运行评分标准，并在 PR 上发布一条机器可读的分数评论。sync 轮询器拉取这些评论——零入站网络暴露面，因此 box 可以在 NAT 后面和场地 wifi 上工作（这是唯一的传输方式：推送摄取已在 v0.6 中移除，见 #377）。分数通过单一审计写入器进入：scorer 的带 bearer 认证的 POST /score，它会验证并单调写入——已解出的题目绝不会因后续失败的运行而被取消解出。

完整图景——组件、九步分数数据流、安全模型——见 docs/architecture.md。

Secure Development：目标与评分标准

此模块的内容是一组存在漏洞的目标及其评分标准。参赛者选择一个目标，fork 组织的副本，修补它，然后打开一个 PR。每个目标的挑战都是可执行的 node:test 测试套件，按难度定价。

^{Counts are maintained by hand and pinned to the vendored rubric by apps/web/src/lib/tests/apps-catalogue.test.ts — re-check them after a vendor-rubric.sh bump. Reference patches that prove a correct fix scores (the positive-direction gate) live separately under patches/.}

评分标准位于 scorer/rubric.owasp/，从 OWASP-CTF/dc34-owasp-secure-development-ctf vendor 而来，并固定到记录在 scorer/rubric.owasp/PROVENANCE.md 中的单个上游提交。使用以下命令针对更新的提交重新 vendor：```sh ./scripts/vendor-rubric.sh --all --ref

同时支持两种评分标准形态，且单个评分标准目录可以混合使用它们：`<target>.yaml` 文件使用声明式 HTTP 请求/期望探测语法，而 `<target>/tests/challenges/` 目录使用由 `catalogue.<target>.json` 定价的可执行测试。编写指南：
[docs/scorer.md](https://github.com/owasp/owasp-ctf/blob/main/docs/scorer.md)。

**关于评分标准的保密性。** 这些评分标准是公开的。目标本身是开源的，其解决方案也已发布，因此该工具包将评分标准的私密性视为防止针对检查的作弊，而非防止知晓答案——对于自托管活动而言，这是一个被接受的权衡。你可以随时用自己的私有评分标准覆盖：```sh
cp -r /path/to/private-rubric scorer/rubric
docker build -t ghcr.io/<org>/score:latest --build-arg RUBRIC_DIR=rubric scorer/

scorer/rubric/ 已被 gitignore 忽略，专为此用途保留。

运行一场活动

当技术栈在你的 EVENT_URL 上启动后：

• 参赛者使用 GitHub 登录并组建或加入团队——计分必须加入团队，而 Play solo 可一键创建单人团队。然后他们可以游玩你启用的任意模块：安全开发采用 patch-and-PR 模式，quiz 和 classic 在应用内作答并提交，ai 则打开个人启动链接。
• 组织者通过 /admin 进行管理：冻结排行榜、开启和关闭注册、设置日程、编写 quiz 题目、classic 挑战和 ai 挑战——当某位参赛者卡住时，只修复该参赛者，而不是重置整个活动。
• 观察 poller 使用 docker compose logs -f sync（它以启用 secure-development 的方式运行）。所有状态都保存在具名 Docker 卷中，因此机器重启不会丢失任何数据。
• 活动结束后，运行 ./setup/ctf-setup.sh teardown 归档目标仓库——然后自行卸载 GitHub App 并删除组织的 Actions secrets。未启用 secure-development 的活动没有需要归档的 fork。

团队、管理面板、活动前验证套件以及本地开发栈均已在 docs/operations.md 中说明；前置条件、分数传输、OAuth 设置和活动配置见 docs/hosting.md。

为什么这样构建

• 自包含，无需云。 一切都在一台机器上通过 Docker Compose 加一个免费的 GitHub 组织运行。评分标准随套件一起提供——无需申请私有镜像，无需编写评分代码——并且所有内容在具名 Docker 卷上重启后依然保留。
• 原样提交得零分，补丁才能得分。 每个目标都设有门槛：如果某个测试在未修补的应用上也能通过，那对每位参赛者来说都是白送分，因此构建过程会拒绝发布这样的测试。
• 零入站网络暴露面。 无需任何外部服务访问你的机器——它通过轮询 GitHub 获取评分评论——因此校园网、封闭实验室或场地 wifi 无需修改防火墙即可使用。

完整的推理、替代方案和权衡取舍以编号 ADR 的形式记录在 docs/decisions.md 中。

文档

渲染于 dcotelo.github.io/owasp-ctf。

贡献与安全

欢迎贡献——CONTRIBUTING.md 涵盖开发环境、CI 门禁以及如何提议模块；CODE_OF_CONDUCT.md 同样适用。

Agent 应遵循 AGENTS.md。以下命令与 CI 一致；make help 列出相同的目标。

每个服务独立测试（全部使用 Node 22）：```sh (cd sync && npm ci && npm test) (cd scorer && npm ci && npm test && node tools/vacuous-sweep.mjs) ./scripts/acceptance-scorer.sh # from the repo root — the script lives in scripts/ (cd apps/web && corepack pnpm install --frozen-lockfile && corepack pnpm lint && corepack pnpm test) ./scripts/smoke.sh # the full poll pipeline, end to end

在工具包本身发现了漏洞？**[SECURITY.md](https://github.com/owasp/owasp-ctf/blob/main/SECURITY.md)** —— 目标漏洞是有意为之，不在范围内。

## 许可证与致谢

MIT —— 参见 [LICENSE](https://github.com/owasp/owasp-ctf/blob/main/LICENSE)。`scorer/rubric.owasp/` 下的评分标准内容来自上游
[OWASP-CTF](https://github.com/OWASP-CTF/dc34-owasp-secure-development-ctf)
活动，固定于 `scorer/rubric.owasp/PROVENANCE.md` 中的提交 —— 本工具包之所以存在，是因为那场活动值得不止一次地举办。易受攻击的目标并非内置：活动会从各自的上游仓库 fork 它们
（[Juice Shop](https://github.com/juice-shop/juice-shop)、
[WebGoat](https://github.com/WebGoat/WebGoat)、
[DVWA](https://github.com/digininja/DVWA)、
[Security Shepherd](https://github.com/OWASP/SecurityShepherd)、
[VulnerableApp](https://github.com/SasanLabs/VulnerableApp)、
[VAmPI](https://github.com/erev0s/VAmPI)），且各自保留自己的许可证。
OWASP® 是 OWASP Foundation 的注册商标；本项目与其无关联，亦未获其认可。