给vuln-bank贡献新漏洞场景:完整社区参与指南与测试用例编写实践

原创2026-10-22 15:26:141,684 阅读

给vuln-bank贡献新漏洞场景:完整社区参与指南与测试用例编写实践

vuln-bank 是一个刻意存在漏洞的银行 Web 应用,覆盖 SQL 注入、BOLA、提示词注入、GraphQL 缺陷等 11 大类安全漏洞场景,是练习 Web 应用、API 与 AI 集成应用安全测试的理想靶场。本文是一份完整的社区参与指南:带你从了解项目结构出发,走通"新增漏洞场景 + 编写测试用例"的完整贡献流程,并解析仓库中 5 类真实测试模式,帮助新手零门槛完成第一次贡献。

vuln-bank故意易受攻击的银行应用安全测试靶场示意图

为什么选择 vuln-bank 作为安全测试练习平台?

与其他靶场不同,vuln-bank 不只是"一堆漏洞的堆砌",它是一个功能完整的银行系统:用户注册登录、转账、借款、虚拟卡、账单支付、商户 API、GraphQL 分析面板,以及基于真实 LLM(DeepSeek API)的 AI 客服。每个功能背后都埋着精心设计的漏洞,例如:

场景域 代表漏洞 对应模块
认证与授权 登录 SQL 注入、弱 JWT、BOLA/BOPLA auth.py、app.py
商户支付 API 明文 API Key、可预测授权码、SQL 注入 merchant_payments.py
AI 客服 提示词注入(CWE-77)、AI 越权读库 ai_agent_deepseek.py
GraphQL 分析 Schema 内省、Resolver SQL 注入 transaction_graphql.py
文件与配置 无限文件上传、SSRF、暴露 .env exposed_env_files.py

完整的漏洞清单可以查看 README.md 中的 "Implemented Vulnerabilities" 章节——这也是你贡献新场景时最好的"选题参考表"。

⚠️ 提醒:本项目只用于隔离环境中的教学与安全研究,严禁部署到生产或公共网络。

3分钟看懂项目结构:从哪入手改代码?

贡献前,先建立一张"文件地图",知道每个功能该改哪里:

  • app.py:Flask 主应用(约 2500 行),所有核心路由(注册、登录、转账、文件上传、SSRF 入口 /upload_profile_picture_url 等)都在这里;
  • auth.py:JWT 生成与校验、token_required 装饰器,做认证类漏洞场景的入口;
  • database.py:连接池与 SQL 执行封装,几乎所有模块都从这里取连接;
  • merchant_payments.py:商户支付 API 的独立示例模块(路由注入、假 API Key 生成);
  • ai_agent_deepseek.py:AI 客服 Agent,系统提示词本身就"故意不设防";
  • xss_cleanup.py:存储型 XSS 的"过期清理"后台任务,是理解"受控漏洞窗口"设计的好例子;
  • tests/:全部测试用例,共 6 个文件,是本文后半部分的重点;
  • docker-compose.yml:一键拉起 web + db + xss-cleaner + autoheal 四个服务;
  • start.sh:容器启动脚本,等待数据库就绪后再拉起 Flask。

💡 新手建议:从独立模块(如 merchant_payments.py)或纯函数模块(如 username_validation.py)入手,比直接改 app.py 风险小得多。

贡献新漏洞场景:5 步标准流程

第 1 步:本地跑起靶场环境

克隆仓库并在隔离环境中用 Docker 启动(推荐方式):

git clone https://gitcode.com/gh_mirrors/vu/vuln-bank
cd vuln-bank
docker-compose up -d --build

启动后访问 http://localhost:5000,API 文档在 /api/docs,GraphQL 端点在 /graphql。Docker 环境自带自动恢复能力:web 服务挂了会自动重启,xss-cleaner 会在 15 分钟后清除超期 XSS 载荷(可通过 XSS_PAYLOAD_TTL_MINUTES 调整窗口),这些细节在 docker-compose.yml 中一目了然。

第 2 步:选题——先查"漏洞地图"再动手

贡献前回答三个问题:

  1. 该场景是否已存在? 对照 README.md 的 11 类漏洞清单,避免重复建设;
  2. 它落在哪个模块? 认证类改 auth.py,支付类仿照 merchant_payments.py 新增独立模块;
  3. 它是否可被测试证明? 一个"只有人肉才能复现"的漏洞场景,对靶场价值有限——可自动化验证是高质量场景的标志。

第 3 步:实现漏洞场景

以"给商户 API 加一个可预测的订单号"为例,思路与现有代码完全同构:参考 merchant_payments.py 中 generate_authorization_code 基于时间戳生成 AUTH{timestamp}{rand} 的写法,把"可预测性"设计成可观察、可断言的行为。

实现时遵循仓库的既有约定:

  • 漏洞代码旁保留注释说明其教学意图(参考 ai_agent_deepseek.py 中 # VULNERABILITY: 注释风格);
  • 不要把"教学漏洞"误当 bug 修掉——tests/test_xss_cleanup.py 中专门有一条测试,断言漏洞注入点依然存在,说明"漏洞本身"也是被守护的行为。

第 4 步:把场景写进文档

在 README.md 对应分类下补充该漏洞的描述,并视情况在 "Testing Guide" 章节给出复现步骤(例如 curl 示例)。文档与漏洞同步更新,是使用者的基本体验。

第 5 步:提交前自检

提交 PR 前跑一遍本地测试套件(不需要真实容器即可运行):

python3 -m unittest discover -s tests -v

该命令会执行 /healthz 行为校验与 start.sh 启动逻辑的冒烟测试;若本地未装齐依赖,相关用例会优雅跳过(Skip)而不是报错。

测试用例编写实践:仓库中的 5 种真实测试模式

这是贡献质量的分水岭。tests/ 目录下的 6 个文件,恰好覆盖了从简单到复杂的 5 种模式,直接对照学习即可。

模式一:纯函数单测——零依赖,最快上手

test_username_validation.py 是最佳入门范例:它只针对 username_validation.py 中的纯函数 username_validation_error 编写,不需要数据库、不需要容器。三个用例分别覆盖"合法字符放行"、"特殊字符拒绝"(含 <script>、admin'-- 等攻击输入)、"长度边界"三类行为,并用 subTest 让每个输入独立报告失败。

✨ 启示:给你的新场景抽出最小可测单元(一个校验函数、一个生成器),先写这种测试,收益最快。

模式二:数据库 Mock——用假连接测 SQL 行为

test_xss_cleanup.py 展示了"不连真库也能测数据库逻辑"的完整套路,分三步:

  1. 在 tests/test_xss_cleanup.py 中动态安装一个 fake_psycopg2 模块,让被测代码以为数据库驱动已就位;
  2. 用 FakeConnection / FakeCursor 记录每条 SQL 与参数(见 tests/test_xss_cleanup.py);
  3. 断言 SQL 文本与参数是否符合预期——例如校验 xss_cleanup.py 中三条 UPDATE 是否都携带了 ttl_minutes 参数、是否只提交了一次。

✨ 启示:对任何直接拼 SQL 的漏洞场景(如商户登录查询),都可以用同样的 Fake 思路固化它的注入行为,防止后续维护者误改。

模式三:Flask test_client 全链路测试——测整个 HTTP 行为

test_merchant_payments.py 是最重的一个文件,示范了 API 级测试的标准做法:

  • 通过 app.test_client() 发起真实 HTTP 请求(tests/test_merchant_payments.py),覆盖注册返回 API Key、登录返回弱 JWT、扣款成功/冻结卡/余额不足三条分支;
  • 用 patch.object 把数据库执行与 API Key 生成替换为受控实现,再用 FakeMerchantStore 这个"内存数据库"模拟商户、虚拟卡与支付流水;
  • 最精彩的是 tests/test_merchant_payments.py:断言"用 merchant_id 查询可以看到别人的支付记录"——即 BOLA 漏洞被固化为测试预期。

✨ 启示:对 API 类新场景,测试要同时断言正常路径(200 成功)与漏洞路径(越权/重复/负数金额依然可通)。

模式四:运行时冒烟测试——守护"能启动"这件事

test_runtime_smoke.py 关注系统级行为:/healthz 在数据库可用/不可用时分别返回 200/503(tests/test_runtime_smoke.py),以及通过伪造 pg_isready 可执行文件验证 start.sh 确实会"等待数据库就绪再启动 Flask"(tests/test_runtime_smoke.py)。

✨ 启示:新增容器化组件(如新的 worker)时,补一条 /healthz 或健康检查相关断言,就能防止启动链路被悄悄破坏。

模式五:浏览器 E2E——验证漏洞在真实页面生效

tests/run_xss_cleanup_e2e.mjs 是 Node + Chrome DevTools Protocol 编写的端到端脚本:它注册用户、写入 XSS 载荷、驱动真实浏览器确认"过期前脚本执行、过期后被清理",并把结果按 before_expiry / after_expiry 打印成结构化日志。

✨ 启示:存储型 XSS、CSRF 这类必须依赖浏览器语义的场景,E2E 是唯一可靠的证明方式;用时间戳后缀生成一次性用户名,可保证测试可重复。

测试命名与断言的通用约定

从现有文件可归纳出仓库的隐性规范:

  • 文件名 test_*.py、类名 *Tests、方法名 test_*,动词开头描述行为(test_frozen_card_charge_fails);
  • 断言失败信息可自解释:用 assertEqual(response.status_code, 400, body=...) 这类形式附带上下文;
  • 对"应该是漏洞"的行为,明确断言漏洞成立,而不是断言它被修复;
  • 环境依赖缺失时用 unittest.SkipTest 跳过(tests/test_merchant_payments.py),保持 CI 绿色。

贡献自检清单(提交 PR 前逐条核对)

# 检查项
1 新场景已在 README 漏洞清单与 Testing Guide 中登记
2 漏洞行为有至少一个自动化测试固化(而非仅文档描述)
3 python3 -m unittest discover -s tests -v 全部通过
4 docker-compose up -d --build 后场景可手工复现
5 没有误删/误修其他"教学漏洞"注入点
6 新增文件遵循现有命名与注释风格(# VULNERABILITY: 标记)

常见问题 FAQ

Q:本地没装 PostgreSQL 也能写测试吗? 可以。模式一(纯函数)完全离线;模式二/三通过 fake psycopg2 与 test_client 绕过真实数据库;仅 E2E(模式五)需要真实容器环境。

Q:我修好了一个漏洞,能提交吗? 要区分"真实 bug"与"教学漏洞"。前者欢迎修复;后者(如 SQL 拼接、明文 API Key)正是项目存在的原因,tests/test_xss_cleanup.py 甚至专门断言它们必须保留。

Q:想加 AI 类或 GraphQL 类场景从哪入手? 分别阅读 ai_agent_deepseek.py(系统提示词与 DeepSeek 调用链路)和 graphql/ 目录下的查询定义配合 transaction_graphql.py,按同样"漏洞 + 测试固化"双件套装法扩展即可。

写在最后

给 vuln-bank 贡献的核心心法可以概括为一句话:漏洞场景是"特性",测试用例是它的"合同"——测试负责证明漏洞按设计存在、按设计工作。掌握本文介绍的 5 种测试模式后,你贡献的每一个新场景都不会是孤立的"功能代码",而是靶场版图中一个可复现、可验证、可教学的完整节点。

伦理提醒:所有实验仅限隔离环境,遵守"ethical hacking only"原则。☕

登录后查看全文
vuln-bank