ContextualWisdomLab/appguardrail
GitHub: ContextualWisdomLab/appguardrail
为 AI 辅助开发场景设计的持久化应用安全护栏，提供规则注入、静态扫描、自动修复及持续监控能力。
Stars: 0 | Forks: 0
# AppGuardrail
**专为 AI 构建的应用提供的安全护栏。**
AppGuardrail 的前身是 VibeSec。此次重命名是为了避开已被占用的第三方 PyPI `vibesec` 命名空间。
AppGuardrail 旨在帮助使用 Cursor、Claude Code、Lovable、Replit、Bolt、Supabase、Firebase、Vercel 和 Netlify 的开发者，发现并修复在 AI 辅助开发过程中引入的安全问题。
## 什么是 AppGuardrail？
AppGuardrail 是**专为 AI 辅助开发者打造的持久化安全层** —— 它不是一次性的渗透测试，而是陪伴你 AI 构建的应用度过整个生命周期（编码、部署、运行、更新和事件响应）的安全副驾驶。
## AppGuardrail 提供的功能
| 层级 | 描述 |
|---|---|
| 🛡️ **AppGuardrail Rules** | 面向 AI 编程助手（Cursor、Claude Code、Windsurf、Lovable）的安全规则 |
| 🔍 **AppGuardrail Scan** | 用于检测密钥、身份验证漏洞、配置错误以及打包 YAML regex 规则的轻量级静态分析 |
| 👁️ **AppGuardrail Review** | 易于人工阅读的审查模板和支持 AI 的审计提示词 |
| 📡 **AppGuardrail Monitor** | 用于持续进行 AppGuardrail 检查的 GitHub Actions 工作流安装器 |
| 🔧 **AppGuardrail Fix** | 适配 AI 的修复提示词 + 补丁指南 + 重新验证步骤 |
## 快速开始
### 运行 CLI
要求 Python 3.9 或更高版本。
从 PyPI 安装：
```
python3 -m pip install appguardrail
appguardrail --help
```
维护者可以使用 GitHub Actions Bot 和 OpenCode Agent 准备 PyPI 发布。请参阅[发布自动化](docs/release-automation.md)。
有关产品化路线图，请参阅 [20 亿韩元出售就绪计划](docs/product/2026-07-02-2b-krw-sale-readiness-plan.md)。
### 或通过 Docker 运行（免安装）
```
docker build -t appguardrail .
docker run --rm -v "$PWD:/src" appguardrail scan /src
```
以非 root 用户身份运行；退出代码 1 表示存在阻碍部署的发现结果。
### 在你的项目中初始化安全规则
```
# 推荐：为 Codex、Copilot、Claude Code、Cursor 和 Windsurf 安装 guardrails
appguardrail init
# 或者为单个工具显式安装
appguardrail init --tool cursor
appguardrail init --tool claude-code
appguardrail init --tool codex
appguardrail init --tool copilot
appguardrail init --tool lovable
# 适用于 Next.js + Supabase 技术栈
appguardrail init --stack nextjs-supabase
```
这会创建：
- `.cursor/rules/appguardrail.md`
- `.windsurf/rules/appguardrail.md`
- `CLAUDE.md`
- `AGENTS.md`
- `.github/copilot-instructions.md`
- `APPGUARDRAIL_CHECKLIST.md`
`appguardrail init --tool lovable` 会创建 `LOVABLE_SECURITY_CHECKLIST.md`。
### 扫描你的代码库
```
appguardrail scan .
# 同时运行 Trivy FS 以检查依赖项 CVE、secrets 和 IaC 错误配置
appguardrail scan --trivy .
# 扫描器会检测 Python、Java、JavaScript、TypeScript 和 Web 文件
# 自动检测。如果受支持的外部 SAST 工具已安装且可运行，
# scan auto 模式无需选择语言配置文件即可包含 Bandit/Ruff/Semgrep。
# 仅当您拥有已授权的运行 URL 时，才运行 OWASP ZAP baseline
APPGUARDRAIL_TARGET_URL=https://your-authorized-test-host.example appguardrail scan .
# 如果已安装 CodeGraph，请为更深入的审查准备结构化上下文
appguardrail scan --codegraph .
# 保存标准化的发现结果，用于报告生成或 dashboard 数据接入
appguardrail scan --findings-json reports/findings.json .
# 输出 SARIF 2.1.0，供 GitHub 代码扫描、VS Code 和其他工具使用
appguardrail scan --sarif appguardrail.sarif .
```
SARIF 输出结果会提供给 GitHub 代码扫描（`github/codeql-action/upload-sarif`）、VS Code SARIF 查看器以及任何其他 SARIF 消费者 —— 发现的问题将出现在 GitHub 的 **Security**（安全）标签页中，并作为 PR 内联注释，按 `security-severity` 进行排名。`appguardrail monitor` 会安装一个工作流，该工作流会在保留部署门禁的同时，自动生成并上传 SARIF。设置 `APPGUARDRAIL_CONTROL_PLANE_URL` 和 `APPGUARDRAIL_API_KEY` 仓库密钥后，该工作流还会将每次扫描推送到你的控制平面，以便进行历史记录和漂移跟踪。
### GitHub Actions
只需一步即可将扫描器添加到任何工作流中 —— 这是一个 composite action：
```
permissions:
contents: read
security-events: write # for SARIF upload
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ContextualWisdomLab/appguardrail@v1
# inputs (all optional): path, sarif, upload-sarif, pr-comment, fail-on-blocking, version
```
若要使用 PR 评论功能，还需授予 `pull-requests: write` 权限。
在 Actions 中，扫描器会**自动检测环境**（`GITHUB_ACTIONS=true`），并且无需任何额外标志即可输出：
- **PR 内联注释** —— 将每个发现结果作为确切的文件/行上的 `::error`（阻碍部署）或 `::warning` 输出，以便审查者在 diff 中看到它们。
- **作业摘要** —— 将严重程度分类和主要发现写入运行的摘要页面（`$GITHUB_STEP_SUMMARY`）。
- **置顶 PR 评论** —— 一条包含发现结果汇总的评论，在每次推送时都会原位更新（需要 `pull-requests: write` 权限；使用 `pr-comment: false` 可禁用）。
在本地使用 `appguardrail scan --github .` 强制输出相同结果。
检测内容：
- 硬编码的密钥（`SUPABASE_SERVICE_ROLE_KEY`、`STRIPE_SECRET_KEY` 等）
- 通过特征前缀检测硬编码的提供商 API token：OpenAI/Anthropic (`sk-`, `sk-ant-`)、AWS (`AKIA`/`ASIA`)、GitHub (`ghp_`/`github_pat_`)、Google (`AIza`)、Slack (`xoxb-…` token 和 `hooks.slack.com` webhook)、Twilio (`AC…`/`SK…`)、SendGrid (`SG.…`)、npm (`npm_…`) 和 PyPI (`pypi-AgEIcHlwaS…`)
- 由 Trivy 支持的依赖项漏洞、密钥和配置错误
- Bandit/Ruff/Semgrep/ZAP 发现的问题（当其可选的外部引擎可用时）
- 危险的 Supabase/Firebase 使用模式
- PHP/WordPress 风险（与超全局变量的 SQL 连接、对请求输入执行 `unserialize()`/`include`/shell-exec、`eval()`、启用 `WP_DEBUG`）
- AWS CloudFormation 模板配置错误（公开的 S3 ACL、完全开放的安全组、`*:*` IAM 策略、公开/未加密的数据库、密钥参数默认值）
- 缺少身份验证的 API 路由
- 公开的 Firebase 规则（`read/write: true`）
- 危险的 CORS 设置（`origin: "*"`）
- Vue/Svelte/Nuxt 前端风险（`v-html` 和原生 HTML 模板注入点、暴露给客户端的 `VITE_`/`NUXT_PUBLIC_` 密钥环境变量、组件中导入的 SvelteKit 私有环境变量、禁用的 SvelteKit CSRF 来源检查）
- 缺少 Stripe webhook 签名验证
- 未受保护的管理路由
- 具有风险的文件上传处理器
- Ansible playbook 风险（明文 `ansible_become_pass`/`ansible_ssh_pass`、shell/command Jinja2 注入、`validate_certs: false`、全局可写的文件模式、禁用的主机密钥检查）
- `.kt`/`.kts` 源代码中的 Kotlin/Android 原生风险（原始 SQL 插值、信任所有 TLS、WebView 文件 URL 访问、硬编码的加密密钥、全局可访问的偏好设置、敏感的 logcat 日志记录）
- 不安全的 Electron 桌面应用配置（`nodeIntegration`、禁用的 `contextIsolation`/`webSecurity`、未经验证的 `shell.openExternal`）
- C#/.NET 风险 —— 通过字符串拼接/插值构建的 SQL、`BinaryFormatter` 系列反序列化、由字符串构建的 `Process.Start` 命令、`ValidateRequest="false"`、不安全的 cookie 标志，以及 `appsettings*.json`/`web.config` 中明文的连接字符串密码
- Go 安全陷阱（通过 `fmt.Sprintf` 和 `sh -c` 进行的 SQL/命令注入、`InsecureSkipVerify`、`math/rand` token、硬编码的 JWT 签名密钥、暴露的 `pprof`）
- Ruby on Rails 风险（`scanner/rules/rails.yml`）：通过字符串插值进行的 SQL/命令注入、`raw`/`html_safe` XSS、`params.permit!` 大规模赋值、禁用的 CSRF 保护以及硬编码的 `secret_key_base`
- Java/Spring 陷阱（SQL/命令拼接注入、XXE 解析器标志、信任所有的 `X509TrustManager`、完全暴露的 Spring Boot Actuator）
列出扫描器检查的所有内容：
```
appguardrail rules # human-readable, severity-sorted
appguardrail rules --json # machine-readable (appguardrail.rules.v1)
```
扫描器会加载内置的 Python 规则以及来自 `scanner/rules/*.yml` 且受支持的 `pattern-regex` 条目。在轻量级引擎增加结构匹配功能之前，Semgrep 风格的结构化 `pattern:` 条目仍将作为文档化的规则测试件保留。
阻碍部署的计数主要针对应用程序代码。文档、测试、示例和扫描器测试件中的发现结果依然可见，但默认情况下不会导致部署门禁失败。
#### 使用 `.appguardrailignore` 跳过 vendored/生成的代码（可选）
在扫描根目录下放置一个 `.appguardrailignore` 文件 —— gitignore 风格的 glob 匹配模式，每行一个（`#` 为注释）。单独的名称（`vendor/`）会匹配树中的任意位置：
```
# 第三方 bundles
vendor/
*.min.js
docs/generated
```
扫描时会打印出跳过了多少文件，因此不会出现悄无声息的遗漏。
#### 使用 `.appguardrail.json` 调整门禁（可选）
在仓库根目录提交一个 `.appguardrail.json`，为整个团队配置部署门禁 —— 无需任何 CLI 标志：
```
{
"fail_on": "HIGH",
"exclude_rules": ["some-noisy-rule-id"]
}
```
- `fail_on` —— 导致门禁失败的最低严重程度（`CRITICAL`、`HIGH`、`WARNING` 或 `INFO`）。默认门禁会阻止 `CRITICAL` 和 `HIGH`。
- `exclude_rules` —— 要从门禁中剔除的规则 ID（发现结果仍会显示，但不会导致构建失败）。无效的配置会引发明显的扫描失败，而不是静默通过。
### 查看两次扫描之间的进度
```
appguardrail scan --findings-json before.json .
# ...修复问题...
appguardrail scan --findings-json after.json .
appguardrail diff-report before.json after.json --out progress.md
```
差异报告将发现结果归类为 **已修复 / 新增 / 持续存在**（行数变动计为持续存在，而不是“已修复 + 新增”），并附带结论优先展示 —— 回归、改善、进行中或未更改 —— 非常适合作为买家/审计证据附上。
### 自动修复安全问题
```
# 预览安全、确定性的修复（dry-run diff）
appguardrail fix .
# 应用它们
appguardrail fix --apply .
```
`appguardrail fix` 仅应用**纯增量且保持语义不变**的修复 —— 它不会静默重写改变行为的代码。第一个转换操作是为外部的 `target="_blank"` 链接添加 `rel="noopener noreferrer"`（反向标签页窃取防护）。改变行为的修复（将密钥移动到环境变量、切换 TLS 验证）仍会作为可审查的提示存在 —— 请参阅 `appguardrail report fix-pack`。这安全地闭合了“扫描 → 修复 → 验证”的循环。
### 运行控制平面 API（扫描历史记录）
```
# 配置组织 + API 密钥文件（默认为 cp.db.api-key）
appguardrail serve --db cp.db --create-org "Acme" --api-key-file acme.api-key
# 运行 API（在空数据库上引导默认组织 + 密钥）
appguardrail serve --db cp.db --port 8788
```
`appguardrail serve` 将 AppGuardrail 从一次性 CLI 转变为持久化的多租户平台：CI 推送每次扫描结果，组织查询其历史记录。
新的 bootstrap key 会写入本地密钥文件，而不是控制台日志。
```
# 在 CI 中，运行 `appguardrail scan --findings-json findings.json .` 之后
curl -X POST http://localhost:8788/api/v1/scans \
-H "Authorization: Bearer $APPGUARDRAIL_API_KEY" \
-H "Content-Type: application/json" \
-d @findings.json # or {"repo":"...","commit":"...","findings":[...]}
curl http://localhost:8788/api/v1/scans -H "Authorization: Bearer $APPGUARDRAIL_API_KEY"
```
使用 `appguardrail scan --push http://your-control-plane .` 从 CI 推送扫描结果（密钥来自 `APPGUARDRAIL_API_KEY`）。控制平面会计算**漂移** —— 即自该仓库上次扫描以来新引入的阻碍部署的发现数量。在 `http://localhost:8788/` 打开**组织控制台** —— 这是一个单页静态页面，通过你的 API key 连接，并显示扫描历史记录、阻碍部署的趋势以及单次扫描的详细信息。
使用 `POST /api/v1/keys`（仅限 owner）签发具有角色限定的 API key：`viewer`（读取）、`member`（接入扫描）或 `owner`（完全权限）。bootstrap key 即为 owner。
设置漂移警报 webhook（使用 `{"url":"…"}` 发起 `POST /api/v1/webhook`），当扫描引入了新的阻碍部署的发现时，控制平面会向其发送通知。如果该 URL 是 Slack Incoming Webhook (`hooks.slack.com`)，警报会自动格式化为 Slack Block Kit 消息 —— 包含新的阻碍项计数以及组织、仓库、扫描 ID，以及最严重的规则 ID 和文件的标题 —— 从而让 Slack 呈现出可读的卡片。任何其他 URL 都将原封不动地接收通用的 JSON payload。
端点：`POST /api/v1/scans`、`GET /api/v1/scans`、`GET /api/v1/scans/{id}`、`POST /api/v1/webhook`、`GET /api/v1/health`。通过 API key 实现租户隔离。基于标准库 + SQLite（在规模扩展时可替换为相同函数背后的托管数据库）。
### 生成 CycloneDX SBOM
```
# 将依赖项清单生成为 CycloneDX 1.5 SBOM
appguardrail sbom . --out sbom.json
```
解析 `package-lock.json`/`package.json`、`pnpm-lock.yaml`、`yarn.lock`、`requirements.txt` 和 `poetry.lock`，生成 CycloneDX 软件物料清单（SBOM） —— 这是买家和审计师期望用于供应链尽职调查的组件清单。存在锁定文件时会从中解析版本，否则从清单中获取（按组件记录）。无需第三方依赖。
### 根据发现结果生成报告
```
appguardrail report buyer-diligence \
--findings reports/findings.json \
--out reports/buyer-diligence.md \
--app-name "Demo SaaS" \
--repository "ContextualWisdomLab/demo"
appguardrail report founder-friendly \
--findings reports/findings.json \
--out reports/founder-security-review.md \
--app-name "Demo SaaS"
appguardrail report agency \
--findings reports/findings.json \
--out reports/agency-security-review.md \
--app-name "Demo SaaS" \
--client-name "Demo Client" \
--reviewer "Demo Agency"
appguardrail report fix-pack \
--findings reports/findings.json \
--out reports/fix-pack.md \
--based-on "pre-launch-review-001"
```
`appguardrail scan --findings-json` 会写入规范化的发现结果封装数据，供 report 命令接收。你也可以传递原始的发现结果 JSON 数组，或任何包含 `findings` 数组的对象。报告类型：
- `buyer-diligence`：买家易于阅读的发布态势和证据核对清单。
- `founder-friendly`：面向非安全背景创始人的通俗语言总结。
- `agency`：面向客户的即用型技术审查和重测说明。
- `fix-pack`：适配 AI 的修复提示词和验证步骤。
报告会省略原始密钥，并将规范化的元数据扩展为发布态势、发现结果摘要、补救措施和验证清单。
### 在仪表板中查看发现结果
```
# 生成发现结果，然后在浏览器中打开本地 dashboard
appguardrail scan --findings-json reports/findings.json .
appguardrail dashboard
```
`appguardrail dashboard` 提供一个独立的 Web 仪表板，用于渲染由 `scan --findings-json` 生成的 `appguardrail.findings.v1` 文件。它显示严重程度统计、阻碍部署的门禁、按类别分类的发现结果，以及带有 AppGuardrail 修复格式（问题 / 修复提示 / 验证）的单项发现结果详细视图。
```
appguardrail dashboard --findings reports/findings.json # custom findings path
appguardrail dashboard --port 8899 # custom port
appguardrail dashboard --no-open # don't launch a browser
```
无需构建步骤或依赖项 —— 该仪表板是随包发布的单页静态页面（`scanner/dashboard/index.html`），因此也可以通过 `pip install` 直接运行。你可以手动打开它，并将 `findings.json` 拖拽到页面上。
### 生成组织买家证据包
```
appguardrail org-bundle
```
此操作会写入 `appguardrail-buyer-evidence/`，其中包含：
- `org-readiness.md`：买家易于阅读的组织就绪情况陈述。
- `buyer-evidence.json`：机器可读的 KPI payload。
- `manifest.json`：来源、时间戳、警告、仓库、PR 和 action bucket 元数据。
- `README.md`：如何使用生成的证据包说明。
仅在你需要非默认组织、自定义产物路径或离线快照时，才使用 `--owner`、`--bundle-dir`、`--repos-json` 或 `--prs-json`。
### 与 pre-commit 框架结合使用
如果你的团队使用 [pre-commit](https://pre-commit.com)，请在 `.pre-commit-config.yaml` 中添加三行内容 —— 每次提交都会进行扫描，并且阻碍部署的发现结果会阻止提交：
```
repos:
- repo: https://github.com/ContextualWisdomLab/appguardrail
rev: v0.1.1
hooks:
- id: appguardrail
```
### 安装持续监控
```
appguardrail monitor
```
这会安装 `.github/workflows/appguardrail-monitor.yml`，它会在 PR、推送到常见默认分支以及手动触发工作流时运行 `appguardrail scan .`。
### 安装 pre-commit 钩子
```
appguardrail hook
# 当 CodeGraph 可用时推荐使用
appguardrail hook --codegraph
```
CodeGraph 模式会在每次扫描之前初始化或同步本地结构索引。这为人工审查者和 AI 审查代理提供了更好的调用图上下文，用于处理授权、webhook、密钥处理和其他安全敏感流程。
仓库的安全流程工作流也会在启用 CodeGraph 的情况下运行 AppGuardrail，因此 PR 在 CI 中也能获得相同的结构化安全上下文。
### 生成安全审查提示词
```
appguardrail review --stack nextjs --db supabase --payments stripe
```
输出一个你可以直接粘贴到 Claude Code 或 Cursor 中的提示词。
## 仓库结构
```
appguardrail/
├── README.md
├── rules/ # Security rules for AI coding tools
│ ├── cursor/
│ ├── claude-code/
│ ├── windsurf/
│ └── lovable/
├── checklists/ # Stack-specific security checklists
│ ├── auth.md
│ ├── authorization.md
│ ├── supabase.md
│ ├── firebase.md
│ ├── stripe.md
│ ├── file-upload.md
│ ├── api-security.md
│ ├── secrets.md
│ └── deployment.md
├── prompts/ # AI fix and review prompts
│ ├── secure-code-review.md
│ ├── fix-authz-bugs.md
│ ├── supabase-rls-review.md
│ ├── stripe-webhook-review.md
│ └── admin-route-review.md
├── scanner/ # Lightweight static analysis engine
│ ├── rules/
│ │ ├── secrets.yml
│ │ ├── authz.yml
│ │ ├── supabase.yml
│ │ ├── firebase.yml
│ │ ├── nextjs.yml
│ │ └── stripe.yml
│ └── cli/
│ └── appguardrail.py
├── reports/ # Report templates
│ └── templates/
│ ├── founder-friendly-report.md
│ ├── agency-report.md
│ └── fix-pack.md
├── examples/ # Sample vulnerable and fixed apps
│ ├── vulnerable-vibe-app/
│ └── fixed-vibe-app/
└── docs/ # Methodology and responsible testing
├── methodology.md
├── scope-and-authorization.md
└── responsible-testing.md
```
## AppGuardrail 修复格式
AppGuardrail 不会只交给你一份传统的安全报告。每一个发现结果都包含：
```
Problem:
User A can access User B's project data by supplying B's project_id.
Risk:
Customer data may be exposed across users.
Fix Prompt:
"Update all project API routes to verify that the authenticated user's id
matches project.owner_id before returning data. Return 403 when ownership
does not match. Add tests for cross-user access."
Verification:
Request User B's project_id using User A's token → expect HTTP 403.
```
## 为什么 AppGuardrail 不同于传统 SAST
传统扫描器主要针对经典漏洞（SQLi、XSS）。而 AI 编写的应用程序失败的方式截然不同：
| AI 编程失败模式 | 示例 |
|---|---|
| 缺少所有权检查 | 任何用户都可以读取任何记录 |
| 公开的存储桶 | 文件无需身份验证即可访问 |
| 暴露的 service role key | 可从浏览器直接进行完全的数据库访问 |
| Supabase/Firebase 规则错误 | RLS 被禁用或 `allow read: if true` |
| 不安全的 webhook | 缺少 Stripe 签名验证 |
| AI 生成的临时代码 | `// TODO: add auth later` 遗留在生产环境中 |
## 服务（付费）
| 产品 | 描述 |
|---|---|
| **AppGuardrail Snapshot** | 对你当前应用进行一次性安全评估 |
| **AppGuardrail Review** | 代码、配置和授权结构审查 |
| **AppGuardrail Red Team Lite** | 基于真实用户场景的防御性渗透测试 |
| **AppGuardrail Fix Pack** | 用于修复已发现问题补丁和提示词 |
| **AppGuardrail Retainer** | 对每一次更改进行月度安全审查 |
| **AppGuardrail Monitor** | 对提交和 PR 进行持续的自动化监控 |
## 贡献
本项目是开源的，欢迎以下方面的贡献：
- 面向 AI 编程工具的新安全规则
- 特定技术栈的检查清单
- 针对常见漏洞模式的修复提示词
- 扫描器检测规则
在贡献扫描器规则之前，请阅读 [docs/responsible-testing.md](docs/responsible-testing.md)。
## 许可证
MIT —— 请参阅 [LICENSE](LICENSE)
标签：AI辅助开发, Python, StruQ, 图数据库, 安全合规, 无后门, 网络代理, 请求拦截, 逆向工具, 静态代码扫描