SzymonnSowula/safecoder

# 🛡️ SafeCoder AI 代理交付的是**能运行**的应用，而不是**安全**的应用。SafeCoder 将每一次构建转化为结构化的安全审查 —— 速率限制、电子邮件验证、密钥管理、XSS/CSRF/CSP 加固、SQL/命令/路径注入预防、提示注入防御、授权、安全的 CI/CD 等。 专为 **Claude Code**、**Codex**、**OpenCode**、**Hermes Agent** 以及任何读取 Markdown 指令的编码代理而构建。 ## 它可以防范什么 | 风险 | 为什么重要 | 默认防护措施 | |------|---------------|-------------------| | 无速率限制 | 垃圾注册、联系表单滥用、暴力破解 | 默认使用基于 IP 的速率限制 | | 无电子邮件验证 | 任何人都可以使用他人的电子邮件进行注册 | 账号激活前必须验证电子邮件 | | 前端包含 API 密钥 | 审查元素 → 免费获取你的 Firebase/Supabase/OpenAI 密钥 | 密钥仅保留在后端 | | XSS | 用户输入被当作代码渲染 | 输出编码，CSP，清理 HTML | | 提示注入 | LLM 因用户输入而忽略系统指令 | 指令边界，允许列表，输出验证 | | SQL 注入 | 数据库被盗，数据丢失 | 参数化查询 / ORM | | 命令注入 | 服务器被入侵 | Shell 命令中不包含用户输入 | | 路径遍历 | 未经授权的文件访问 | 验证路径，随机文件 ID | | 不安全的文件上传 | 恶意软件，RCE | 允许列表的 MIME/类型，大小限制，沙箱 | | 缺少 authz | 用户相互访问对方的数据 | 资源级别的所有权检查 | | 不安全的 headers | 点击劫持，MIME 嗅探，来源泄露 | 默认开启安全 headers | | 错误的 CORS | 跨站已认证请求 | 精确来源允许列表 | | Git 中泄露的机密 | 密钥永久暴露 | Pre-commit 钩子 + `.env.example` 模式 | | 不安全的 CI/CD | 工作流中包含机密，未审查的部署 | 机密管理器 + 分支保护 | ## 快速开始 ### Hermes Agent — 一行代码安装 ``` bash <(curl -fsSL https://raw.githubusercontent.com/SzymonnSowula/safecoder/main/install.sh) ``` 或通过 npm 安装（推荐）： ``` npm install @szymonsdev/safecoder npx safecoder install ``` 这会添加 skill 和别名： ``` hermes-web # hermes -s safecoder hermes-app # hermes -s safecoder hermes-api # hermes -s safecoder ``` 启动一个新的终端，然后在构建任何 Web 项目之前运行 `hermes-web`。 ### Vercel Skills / open agent skills SafeCoder 兼容 `npx skills`： ``` npx skills add SzymonnSowula/safecoder@safecoder ``` ### 初始化项目 ``` npx safecoder init ``` 在项目中创建： - `AGENT_SECURITY.md` - `.env.example` - `scripts/security-audit.sh` - `SECURITY.md` - `.github/workflows/security-audit.yml` （如果存在 `.github/workflows`） ### 与 Claude Code / Codex / OpenCode 配合使用 将 `skills/safecoder/SKILL.md` 作为 `AGENT_SECURITY.md` 复制到你的项目中，并告诉代理： 或者将 `skills/safecoder/templates/PROMPT.md` 中的简短提示词粘贴到上下文中。 ## 包含内容 ``` safecoder/ ├── README.md ├── LICENSE ├── package.json # npm package + CLI ├── install.sh # One-line installer for Hermes ├── init-project.sh # Adds SafeCoder files to a project ├── bin/ │ └── cli.js # npx safecoder install / init ├── scripts/ │ └── sync-vercel-skill.sh # Syncs skill layout for Vercel Skills ├── .github/workflows/security-audit.yml # CI workflow ├── skills/safecoder/ # Vercel Skills layout │ ├── SKILL.md │ ├── references/ │ ├── templates/ │ └── scripts/ └── skills/software-development/safecoder/ # Hermes skill layout ├── SKILL.md ├── references/ │ ├── security-checklist.md │ ├── rate-limiting-patterns.md │ ├── xss-prevention.md │ ├── prompt-injection-defense.md │ ├── auth-patterns.md │ ├── jwt-oauth2-patterns.md │ ├── file-upload-security.md │ ├── cors-guide.md │ ├── logging-monitoring.md │ ├── ci-cd-security.md │ ├── api-design-security.md │ └── owasp-top-10-for-ai-apps.md ├── templates/ │ ├── env.example │ ├── security-config.yaml │ ├── security-decision-record.md │ ├── SECURITY.md │ └── PROMPT.md └── scripts/ └── security-audit.sh ``` ## 发布前安全检查清单 每个使用此 skill 的项目在合并前都必须通过以下检查： - [ ] 在身份验证、注册、联系、密码重置和 API 端点上存在速率限制 - [ ] 速率限制由 IP（不仅是电子邮件）强制执行，并为已认证的路由提供用户回退机制 - [ ] 账户执行特权操作前必须进行电子邮件验证 - [ ] 前端包中不存在任何 API 密钥、数据库 URL 或私有 token - [ ] 所有机密信息均在后端从环境变量中读取 - [ ] 用户输入在服务器端进行验证，在输出时进行转义，并在允许 HTML 时进行清理 - [ ] 数据库查询使用参数化语句或 ORM 方法 - [ ] 没有用户输入到达 shell、eval、exec 或原始 SQL - [ ] 文件上传使用允许列表的 MIME/类型、随机 ID 和大小限制 - [ ] 内容安全策略阻止内联脚本并限制脚本来源 - [ ] 设置了安全 headers（`X-Frame-Options`、`X-Content-Type-Options`、`Referrer-Policy` 等） - [ ] CORS 限制已认证端点的来源（不使用 `*`） - [ ] LLM 系统提示与用户内容隔离，并且输出根据 schema 进行验证 - [ ] AI API 调用受到速率限制和成本上限控制 - [ ] 资源访问检查确认已登录用户拥有所请求的资源 - [ ] `.env` 文件包含在 `.gitignore` 中，并且提交了 `env.example` - [ ] 在代码到达 GitHub 之前，由 Pre-commit 钩子或 CI 扫描机密信息 - [ ] 在 CI 中扫描依赖项的已知漏洞 完整版本位于 [`references/security-checklist.md`](skills/software-development/safecoder/references/security-checklist.md)。 ## 示例：基于 IP 的速率限制 ``` from slowapi import Limiter, _rate_limit_exceeded_handler from slowapi.util import get_remote_address from slowapi.errors import RateLimitExceeded from fastapi import FastAPI, Request limiter = Limiter(key_func=get_remote_address) app = FastAPI() app.state.limiter = limiter app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler) @app.post("/auth/signup") @limiter.limit("5/minute") def signup(request: Request): ... ``` 更多模式请参见 [`references/rate-limiting-patterns.md`](skills/software-development/safecoder/references/rate-limiting-patterns.md)。 ## 示例：将机密信息排除在前端之外 ❌ **绝不这样做：** ``` const supabase = createClient( "https://your-project.supabase.co", // public URL is fine "eyJhbG...VCJ9..." // NEVER put service-role key here ); ``` ✅ **请改为这样做：** - 前端仅获取开启了 RLS 的 **anon/public** 密钥 - 后端 service-role 密钥保留在服务器上的 `SUPABASE_SERVICE_ROLE_KEY` 中 - 所有特权操作都通过你的 API 进行，绝不直接从浏览器进行 ## 本地审计 将 `scripts/security-audit.sh` 复制到你的项目根目录并运行： ``` bash scripts/security-audit.sh ``` 它会检查： - 提交的 `.env` 文件 - 缺失的 `.gitignore` 条目 - 源代码中可能存在的机密 - 前端路径中的后端机密 - 危险的函数（`eval`、`innerHTML` 等） - SQL 字符串格式化 - 通配符 CORS - 依赖项漏洞 ## 为什么会有这个项目 AI 编码代理追求的是“它能运行吗？”，而不是“它安全吗？”。SafeCoder 为每一个生成的功能增加了一个安全层，这样你就不会一觉醒来面对 5,000 美元的 OpenAI 账单、充满垃圾信息的数据库或泄露的客户数据。 它是刻意为之的： 1. **默认安全** —— 显式关闭保护，而不是意外关闭。 2. **代理可读** —— 以 LLM 可以遵循的指令形式编写。 3. **框架无关** —— 适用于 Next.js、FastAPI、Node、Rails、Laravel、Tauri 等。 4. **可操作** —— 每条规则都附带代码示例和验证步骤。 ## 发布到 npm 发布为 [`@szymonsdev/safecoder`](https://www.npmjs.com/package/@szymonsdev/safecoder)。 要发布新版本： 1. 在 `package.json` 中更新 `version`。 2. 运行： npm publish --access=public 如需自动发布，请将 `NPM_TOKEN` 机密添加到仓库设置中。`.github/workflows/npm-publish.yml` 中的 GitHub Action 将在每次 GitHub 发布时进行发布。 ## 许可证 MIT

标签：AI编程助手, DevSecOps, MITM代理, 上游代理, 代码安全, 安全规范, 暗色界面, 漏洞枚举, 漏洞防御, 防御加固