Skip to main content
Glama
srcGuardedWorkflow

srcGuardedWorkflow

README.md
# SRC Guarded Workflow

## 当前版本

当前发布版本为 `0.7.2`。版本变更记录见 `CHANGELOG.md`。

版本迭代遵循:

- `PATCH`:兼容性修复和文档更新
- `MINOR`:新增工具、Playbook、专家路由或工作流能力
- `MAJOR`:破坏兼容性的插件 API、Scope 格式、MCP 契约或审批语义变更

发布前必须更新版本号、运行测试、验证 Skill、重新生成迁移包,然后提交并打 `vX.Y.Z` 标签。

本地生成发布包:

```powershell
.\scripts\build_release.ps1
```

推送 `vX.Y.Z` 标签后,GitHub Actions 会运行测试、构建并发布两个 ZIP 资产。

一个可迁移的 Codex 插件:把“给定 SRC 资产 → 自动建立范围 → 被动侦察 → 基线采集 → 候选分析 → 人工批准后的低影响验证 → 证据门禁 → 报告草稿”打包成聊天驱动的 MCP 工作流。

## 你现在怎么用

在聊天里给出:

```text
SRC 项目:<项目名或规则链接>
授权资产:https://target.example.com/path
确认:该资产在授权范围内
```

Codex 会优先调用 `srcGuardedWorkflow` MCP 工具的 `src_start`:

1. 创建本次运行目录。
2. 只允许该资产的主机、端口、路径和只读方法。
3. 做 DNS/证书透明度的被动侦察。
4. 发送一次低影响 `GET` 基线请求。
5. 生成 `attack-surface.md`、证据和运行状态。
6. 后续高风险操作通过聊天里的 `APPROVE <code>` 人工门禁。

不需要记忆命令行。命令行工具仍然保留,供调试和跨平台迁移使用。

## 插件结构

```text
src-workflow/
├── plugin.json                 # 可迁移 Agent Plugin 清单
├── mcp.json                    # 本地 stdio MCP 服务
├── skills/src-bug-bounty/      # 聊天入口 Skill
├── server/src_guarded_mcp.py   # MCP 工具服务
├── scripts/                    # 范围、HTTP、证据、报告脚本
├── schemas/                    # Scope / Finding schema
├── knowledge/expert-routes.json # 场景到专家 Playbook 的路由
├── config/scope.example.yaml
├── templates/clueboard.md      # 跨轮线索板
├── templates/report.md
├── THIRD_PARTY_NOTICES.md      # 第三方来源与许可证
├── tests/
└── install.ps1 / install.sh
```

## 仓库结构与文件简介

| 文件 / 文件夹 | 中文简介 |
| 文件 / 文件夹 | 中文简介 / English |
|---|---|
| `plugin.json` | 可迁移 Agent Plugin 清单,声明名称、版本、描述、许可证 / Portable Agent Plugin manifest declaring name, version, description, license |
| `mcp.json` | 本地 stdio MCP 服务器配置,启动 `srcGuardedWorkflow` / Local stdio MCP server configuration to start `srcGuardedWorkflow` |
| `.codex-plugin/plugin.json` | Codex 插件元数据,绑定技能与 MCP 服务 / Codex plugin metadata binding skills and MCP service |
| `AGENTS.md` | 工作区指令,规范 SRC 测试流程、范围与人工审批红线 / Workspace instructions regulating SRC testing flow, scope, and human approval red lines |
| `CHANGELOG.md` | 版本变更记录,0.6.0 → 0.7.2 / Changelog, 0.6.0 → 0.7.2 |
| `LICENSE` | MIT 许可证 / MIT License |
| `README.md` | 本文件,快速上手、使用方法与仓库结构说明 / This file, quick start, usage, and repository structure |
| `THIRD_PARTY_NOTICES.md` | 第三方来源与许可证(CK-Skills、SecSkills 等) / Third-party sources and licenses (CK-Skills, SecSkills, etc.) |
| `install.ps1` | Windows 安装器,安装到个人 Skill 目录与本地插件目录 / Windows installer, installs to personal Skill directory and local plugin directory |
| `install.sh` | Linux/macOS 安装器 / Linux/macOS installer |
| `requirements.txt` | Python 依赖(PyYAML、jsonschema) / Python dependencies (PyYAML, jsonschema) |
| `config/scope.example.yaml` | 授权范围配置示例(主机、端口、路径、方法、速率) / Authorization scope configuration example (host, port, path, method, rate) |
| `knowledge/expert-routes.json` | 场景到专家 Playbook 的路由表,共 20 条 / Scenario-to-expert Playbook routing table, 20 routes |
| `knowledge/classes/*.json` | 27 类漏洞检测 Playbook(IDOR、SSRF、SQLi 等) / 27 vulnerability detection Playbooks (IDOR, SSRF, SQLi, etc.) |
| `server/src_guarded_mcp.py` | MCP 工具服务主体,提供 22 个 MCP 工具 / MCP tool service main body, provides 22 MCP tools |
| `server/intel_tools.py` | 空间搜索引擎工具(FOFA、Shodan 等) / Space search engine tools (FOFA, Shodan, etc.) |
| `server/surface_tools.py` | 表面探测工具(JS/HAR/路径/端口) / Surface detection tools (JS/HAR/path/port) |
| `scripts/new_run.py` | 新建运行目录,初始化 `CLUEBOARD.md` / `CLUEBOARD.json` / Create new run directory, initialize `CLUEBOARD.md` / `CLUEBOARD.json` |
| `scripts/guarded_http.py` | 受控 HTTP 请求,带范围、速率、重定向与审批门禁 / Controlled HTTP requests with scope, rate, redirect, and approval gates |
| `scripts/render_report.py` | 从已验证发现渲染报告草稿 / Render report draft from validated findings |
| `scripts/validate_finding.py` | 发现证据与 schema 校验 / Finding evidence and schema validation |
| `scripts/check_scope.py` | URL 与方法范围校验 / URL and method scope validation |
| `scripts/scope_rules.py` | 范围规则引擎 / Scope rule engine |
| `scripts/build_release.ps1` | 发布包构建脚本(测试 + 打包 ZIP) / Release package build script (test + package ZIP) |
| `skills/src-bug-bounty/SKILL.md` | 聊天入口 Skill,描述如何使用该插件 / Chat entry Skill, describes how to use this plugin |
| `skills/src-bug-bounty/references/*.md` | Skill 参考文档(专家路由、漏洞 Playbook、范围与证据、报告检查表、CK-Skills/SecSkills 集成) / Skill reference documents (expert routing, vulnerability Playbook, scope & evidence, report checklist, CK-Skills/SecSkills integration) |
| `templates/clueboard.md` | 跨轮线索板模板(Facts / Intents / Hints) / Cross-session clueboard template (Facts / Intents / Hints) |
| `templates/report.md` | 报告草稿模板 / Report draft template |
| `templates/finding.example.json` | 发现 JSON 示例 / Finding JSON example |
| `schemas/finding.schema.json` | 发现数据结构 Schema / Finding data structure Schema |
| `schemas/scope.schema.json` | 范围数据结构 Schema / Scope data structure Schema |
| `tests/test_mcp_server.py` / `test_workflow.py` | MCP 工具与工作流测试,共 16 个用例 / MCP tool and workflow tests, 16 test cases |
| `.github/workflows/release.yml` | 标签触发的 GitHub Actions:测试、构建、发布 ZIP 资产 / Tag-triggered GitHub Actions: test, build, publish ZIP assets |
| `migration/install.ps1 / install.sh / README.md` | 迁移包安装脚本与说明,用于换机部署 / Migration package installation scripts and instructions, for cross-machine deployment |
| `dist/` | 发布构建产物(构建后生成,不提交) / Release build artifacts (generated after build, not committed) |
| `runs/` | 测试运行目录(每次运行生成,不提交) / Test run directory (generated on each run, not committed) |
| `.pytest_cache/`、`.test-tmp/` | 测试缓存与临时目录(不提交) / Test cache and temporary directories (not committed) |
## 安装到个人环境

Windows:

```powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

安装器会:

- 安装个人 Skill 到 `~/.agents/skills/src-bug-bounty`。
- 安装插件到 `~/.agents/plugins/src-guarded-workflow`。
- 写入个人 marketplace 条目。
- 安装 `PyYAML` 和 `jsonschema`。

重启 Codex 桌面应用后,在本地 Plugins 源启用 `src-guarded-workflow`。

## MCP 工具

- `src_start`:一次调用完成授权范围创建、被动侦察、基线请求和 `CLUEBOARD.md` / `CLUEBOARD.json` 初始化。
- `src_clueboard`:读取或更新跨轮线索板,并维护 Facts / Intents / Hints 状态图(`CLUEBOARD.json`)。
- `src_hunt_route`:把 JS、认证、越权、注入、业务逻辑、文件、SSRF、Agent/MCP 等场景路由到专家流程和漏洞 Playbook。
- `src_skill_audit`:安装第三方 Skill/插件前做静态供应链安全检查,覆盖危险执行、审批绕过、提示词注入、密钥、外传和混淆信号。
- `src_prepare_run`:只创建范围与运行目录,不发目标流量。
- `src_passive_recon`:DNS、证书透明度等被动信息收集。
- `src_asset_intel`:查询 FOFA、Shodan、Quake、Hunter、ZoomEye、urlscan 等空间搜索引擎,结果标记 in_scope/out-of-scope。
- `src_intel_status`:查看空间搜索引擎 API Key 配置状态。
- `src_check_scope`:检查 URL 和方法是否在范围内。
- `src_js_inventory`:抓取基线页面和同源 JS,提取接口、参数和 source map;需要批量批准。
- `src_import_har`:导入浏览器/Burp HAR,建立范围内的请求和参数清单。
- `src_path_probe`:最多 25 条明确路径的低速探测;不接受 wordlist 暴力扫描,需要批量批准。
- `src_port_probe`:只检查 scope 明确允许的端口,最多 20 个;需要批量批准。
- `src_http`:受控 HTTP 请求,默认 dry-run;写操作和高风险操作必须带聊天批准码。
- `src_request_approval`:生成聊天审批码。
- `src_confirm_approval`:只有用户回复 `APPROVE <code>` 后才确认。
- `src_save_finding`:保存候选/已确认发现。
- `src_validate_finding`:证据、哈希、人工复核门禁。
- `src_render_report`:只从已验证发现生成报告草稿。
- `src_status`:查看运行状态、请求数、发现和审批。
- `src_vuln_playbook`:按 IDOR、SSRF、XSS、SQLi、业务逻辑等类别返回检测方法、确认条件和误报项。
- `src_tool_status`:检测本机侦察工具。
- `src_install_tool`:安装白名单内的官方工具,必须显式 `confirm: true`。

## 信息搜集链路

1. `src_start`:被动 DNS/CT + 一次基线 GET + 初始化 `CLUEBOARD.md` / `CLUEBOARD.json`。
2. `src_clueboard`:读取线索板、Fact-Intent-Hint 图和当前焦点。
3. `src_asset_intel`:用精确域名/证书/资产查询 FOFA、Shodan、Quake、Hunter、ZoomEye、urlscan。
4. `src_js_inventory`:同源 JS、接口、参数和 source map。
5. 浏览器或 Burp/Caido 登录测试账号,走真实功能,导出 HAR。
6. `src_import_har`:把 HAR 转成范围内的端点/参数清单。
7. `src_path_probe`:只探测从 JS/HTML/HAR 得到的明确路径。
8. `src_port_probe`:只检查 scope 允许的端口。
9. `src_hunt_route`:按功能点/技术栈/异常信号选择专家路线。
10. `src_vuln_playbook`:按漏洞类型进入检测。
11. `src_http`:单请求最小验证。
12. `src_clueboard`:写回事实、意图、人工提示、否定证据和覆盖度。
13. `src_save_finding` / `src_validate_finding` / `src_render_report`:证据和报告。

“可疑站点搜索”仅指授权项目内的公开资产发现,不扫描范围外主机。

## 漏洞分类与检测

执行任何候选验证前,先调用 `src_vuln_playbook`。例如:

```text
src_vuln_playbook(class_id="idor_bola")
src_vuln_playbook(query="JWT")
src_vuln_playbook(priority="high")
```

返回内容包括:

- 攻击面
- 可观察信号
- 最小安全验证
- 确认条件
- 常见误报
- 是否必须人工批准
- 潜在影响

目前内置 27 类 Playbook 和 20 条专家路由:认证绕过、会话/JWT、IDOR/BOLA、租户隔离、SQL/NoSQL 注入、SSTI、命令注入、反序列化、SSRF、开放重定向、XSS、CSRF、CORS、文件上传、路径穿越、业务逻辑、竞态、GraphQL、OAuth/JWT、信息泄露、云存储、缓存/Host Header、WebSocket、LLM 提示注入、Agentic/MCP 工作流安全、HTTP 请求走私等。

## CK-Skills 方法整合

本版本吸收 CK-Skills 的 JS-first、专家路由、跨轮线索板、证伪优先和覆盖度自检,但不导入其“任意目标直接执行”、凭据猜测、自动 WAF 绕过或完全自主利用等假设。移动端逆向、Windows 逆向和源码审计只返回 `manual_only` 手交路线。来源与 MIT 许可证见 `THIRD_PARTY_NOTICES.md`。

## SecSkills 方法整合

SecSkills 是一个 102 项目的能力索引,不是单一技能。本版本只吸收其中当前工程缺少的精华:第三方 Skill 供应链审计、Facts/Intents/Hints 状态空间图、Agentic/MCP 工作流安全、独立 Oracle 验证,以及“脚本保证覆盖、LLM 保证判断”的双层架构。未安装其列出的自主渗透平台,也未引入移动逆向、二进制利用、CTF 或域渗透自动化。详见 `skills/src-bug-bounty/references/secskills-integration.md`。

## 自动安装工具

Skill 先调用 `src_tool_status`。若缺少工具,只对白名单工具调用 `src_install_tool`,例如:

- `httpx`
- `subfinder`
- `dnsx`
- `katana`
- `nuclei`
- `gau`
- `ffuf`

安装来源仅限 ProjectDiscovery、lc/gau、ffuf 等官方 Go 模块。不会自动安装来源不明的 GitHub 项目,不会自动运行 `nuclei`、`sqlmap`、`ffuf` 或暴力破解。

## 安全边界

- 只有明确授权的 SRC 资产可以测试。
- 默认只读,写操作、认证流程、SSRF、文件上传、跨租户、凭据使用和漏洞链必须人工批准。
- 真实用户数据、凭据、内网资产和业务影响必须立即停止扩大。
- 扫描器结果只能是线索,不能直接当漏洞。
- 报告必须人工复核,不能自动提交到 SRC。

## 本地测试

```powershell
python -m unittest discover -s tests -v
```

测试覆盖:MCP 初始化/工具列表、范围创建、线索板及 Facts/Intents/Hints 图、专家路由、Skill 供应链审计、dry-run、聊天审批门禁、候选发现校验、证据记录、重定向阻断和报告渲染。