paolocavallis/security-playbook

# AI 辅助开发安全手册 一条命令即可为任何项目设置 CI 安全检查、AI 代理规则和依赖监控。 无阻碍。无钩子。无摩擦。 ## 快速开始 ``` cd /path/to/your-project bash /path/to/security-playbook/setup.sh ``` 就是这样。运行一次，安全永久运行。 ## 工作原理 ``` setup.sh runs in your project │ ├─→ .github/workflows/security.yml CI checks on every PR (warnings only) ├─→ .github/dependabot.yml Auto-updates vulnerable dependencies ├─→ .claude/CLAUDE.md Security rules for Claude Code ├─→ AGENTS.md Security rules for Codex ├─→ .cursorrules Security rules for Cursor ├─→ .gitignore Blocks .env files from commits ├─→ .gitleaks.toml Secret scanner config └─→ Semgrep Skills Static analysis for AI agents ``` ## CI：每个 PR 执行 4 项安全检查 所有检查均为**建议性** —— 它们会标记问题，但绝不会阻止合并或部署。 ``` PR opened │ ▼ ┌─────────────┐ ┌──────────────────┐ ┌─────────┐ ┌────────────────────┐ │ Secret Scan │ │ Dependency Audit │ │ Semgrep │ │ Environment Safety │ │ (gitleaks) │ │(npm/pnpm/yarn/bun)│ │ (OWASP) │ │ (.env, secrets) │ └──────┬──────┘ └────────┬─────────┘ └────┬────┘ └─────────┬──────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ✅ or ⚠️ ✅ or ⚠️ ✅ or ⚠️ ✅ or ⚠️ │ │ │ │ └──────────────────┴──────────────────┴─────────────────┘ │ ▼ Results in PR job summary + stdout AI agents read & fix warnings ``` ### CI 加固 生成的工作流默认应用安全最佳实践： - **`permissions: contents: read`** — 最小权限 token 范围 - **`persist-credentials: false`** — runner 上不保留 git 凭证 - **`--ignore-scripts`** — 防止在 audit 安装期间执行不受信任的生命周期脚本 - **Semgrep 镜像通过 SHA256 摘要固定** — 不可变容器引用 - **Action SHA 固定** — 所有 GitHub Actions 通过 commit hash 引用，而非可变 tag - **双重输出** — 警告同时发送到 stdout（用于 `gh` CLI / AI 代理）和 `GITHUB_STEP_SUMMARY`（用于 Web UI） ### 包管理器支持 | 管理器 | 审计 | 检测 | |---------|-------|-----------| | npm | `npm audit` | `package-lock.json` | | pnpm | `pnpm audit` | `pnpm-lock.yaml` | | yarn | `yarn audit` | `yarn.lock` | | bun | 尚不可用 | `bun.lockb` / `bun.lock`（附带指导警告） | 锁定文件位于子目录的 Monorepo 项目会收到额外的警告，列出未审计的路径。 ## AI 代理集成 您的 AI 编码工具会自动遵循安全规则并审查 CI 结果： | 代理 | 读取 | 功能 | |-------|-------|-------------| | Claude Code | `.claude/CLAUDE.md` | 遵循规则 + 运行 `gh pr checks` 以审查 CI | | Codex | `AGENTS.md` | 遵循规则 + 检查 PR 作业摘要 | | Cursor | `.cursorrules` | 遵循规则 + 检查 PR 作业摘要 | 每个代理的部署前检查清单包括审查 CI 警告并在报告任务完成前修复它们。 ## 抗脆弱循环 每一次安全发现都会增强系统： ``` Finding → LESSONS-LEARNED.md → New rule in CLAUDE.md or new CI check → Immune ``` ## 团队推广 请参阅 [`CI-SECURITY-SETUP.md` → Team Rollout Decisions](CI-SECURITY-SETUP.md#team-rollout-decisions)，了解在团队范围内采用之前需要解决的问题：阻断性与建议性检查、误报抑制、monorepo 覆盖范围、Bun 支持、Semgrep 摘要刷新所有权等。 ## 文档 | 文件 | 内容 | |------|------| | [`SECURITY-PLAYBOOK.md`](SECURITY-PLAYBOOK.md) | 完整参考 — 10 个安全领域，50+ 规则 | | [`CI-SECURITY-SETUP.md`](CI-SECURITY-SETUP.md) | CI 工作流详细信息、强制执行选项、团队推广指南 | | [`SECURITY-REVIEW-PROCESS.md`](SECURITY-REVIEW-PROCESS.md) | 月度审计流程 | | [`LESSONS-LEARNED.md`](LESSONS-LEARNED.md) | 发现日志和反馈循环 | | [`APPENDIX-MCP-INTEGRATIONS.md`](APPENDIX-MCP-INTEGRATIONS.md) | Google、Slack、BigQuery、GitHub、AWS 的规则 | ## 许可证 MIT

标签：AI辅助开发, CI/CD安全, Claude Code, Cursor, Dependabot, DevSecOps, GitHub Actions, Gitleaks, Llama, SAST, Semgrep, StruQ, Syscall 审计, WordPress安全扫描, 上游代理, 云安全监控, 人工智能安全, 依赖监控, 合规性, 合规自动化, 威胁情报, 安全专业人员, 安全基线, 安全工程, 密钥泄露检测, 应用安全, 开发安全, 开发者工具, 敏感数据保护, 教学环境, 文档安全, 暗色界面, 环境安全, 盲注攻击, 自动化运维, 自动笔记, 静态分析