security-audit

安全审计技能

面向安全关键系统的全面手动深度代码审计协议。包含针对最常见 AI 辅助开发问题的快速「氛围编程防护措施」。

使用时机

• 重要版本发布前
• 收到安全审查请求时
• 审计身份验证／支付流程时
• 提到「审计」或「安全」时
• 使用 AI 搭建新项目后（检查氛围编程是否合理）
• 面向用户的应用首次部署前

审计阶段

阶段 0：定义范围

定义边界：

• FULL_SCAN：整个代码库
• FEATURE_SCAN：特定功能（docs/features/[Name].md）
• DIFF_SCAN：git diff --staged 或 git diff HEAD~1

阶段 1：侦探（静态分析）

# 1. Detect package manager & run dependency audit
# Auto-detect: check which lockfile exists
# pnpm-lock.yaml → pnpm audit
# package-lock.json → npm audit
# yarn.lock → yarn audit
# bun.lockb → bun pm audit (or bunx audit)
pnpm audit  # ← swap for your package manager

# 2. Secret scanning (use jstar if available)
jstar detect

# 3. Manual grep patterns:
# Secrets
grep -rE "(api_key|secret|password|token)\s*[:=]\s*['\"\`][a-zA-Z0-9_\-\.]{10,}['\"\`]"

# RCE/Injection
grep -rE "(dangerouslySetInnerHTML|eval\(|exec\(|\.queryRaw)"

# Debugging
grep -rE "(console\.log|debugger|todo)"

阶段 1.5：氛围编程防护措施（AI 专项检查）

这些是快速、主动的检查，可发现最常见的氛围编程安全问题。 在深入分析之前运行。每项约需 2 分钟。

1.5.1 — 幽灵／虚假包检测（供应链）

风险： AI 模型会幻觉出包名。攻击者会注册这些名称并植入恶意软件。

注意： npm view 会直接查询 npm 注册表，无论使用哪种包管理器（pnpm、yarn、bun 等）都适用。无需安装 npm——它只是查询注册表。

# For each unfamiliar dependency in package.json:
# 1. Verify it exists on the real registry (works with ANY package manager)
npm view <package-name> version  # Should return a version, not 404
# Alt for pnpm users: pnpm info <package-name>
# Alt for bun users: bunx npm-cli view <package-name>

# 2. Check download stats (low downloads = suspicious)
npm view <package-name> --json | grep -E "downloads|modified"

# 3. Look for typosquatting (e.g., "lodahs" instead of "lodash")
# Compare against known-good package names

操作： 移除任何在 npm／PyPI 上不存在或下载量低得可疑的包。对照官方文档核实。

1.5.2 — AI 构建的身份验证检测

风险： AI 很容易生成看似可用、实则存在隐蔽漏洞的自定义登录系统（没有 CSRF、防哈希较弱、会话不失效等）。

# Scan for custom auth patterns (red flags):
grep -rE "(bcrypt\.hash|jwt\.sign|createHash|crypto\.createCipher)" --include="*.ts" --include="*.tsx" --include="*.js"
grep -rE "(password.*=.*req\.(body|query)|session\[|cookie\[)" --include="*.ts" --include="*.tsx" --include="*.js"

# Check if a battle-tested auth provider is installed:
grep -E "(next-auth|@auth/|@clerk|@supabase/auth|auth0|lucia|better-auth)" package.json

操作： 如果发现自定义身份验证，且未使用成熟的提供商：

• 标记为高严重性
• 建议迁移到：Clerk、NextAuth/Auth.js、Supabase Auth、Auth0、Lucia 或 Better Auth
• 只有团队具备专门的安全专业知识时，自定义身份验证才可接受

1.5.3 — .gitignore 验证

风险： 氛围编程进展很快。少一条 .gitignore 规则，就可能把密钥推送到公开的 GitHub。机器人会全天候扫描暴露的密钥。

# 1. Check .gitignore exists
test -f .gitignore && echo "EXISTS" || echo "MISSING — CRITICAL"

# 2. Verify essential entries are present:
for pattern in ".env" ".env.local" ".env.*.local" "node_modules" "*.pem" "*.key" ".DS_Store"; do
  grep -qF "$pattern" .gitignore || echo "MISSING from .gitignore: $pattern"
done

# 3. Check if .env is already tracked (damage already done):
git ls-files --cached | grep -E "\.env$|\.env\.local$|\.pem$|\.key$"
# If output exists → secrets are already in git history. Rotate ALL keys immediately.

操作： 如果缺少 .gitignore 或内容不完整 → 标记为严重。如果 .env 已被跟踪 → 标记为严重，并建议使用 git filter-branch 或 BFG Repo-Cleaner，同时立即轮换密钥。

1.5.4 — 速率限制检查

风险： 任何没有速率限制的公开 API 路由都可能遭到机器人滥用（垃圾请求、暴力破解、耗尽 API 费用）。

# Check if rate limiting middleware is installed:
grep -E "(rate-limit|@upstash/ratelimit|express-rate-limit|limiter)" package.json

# Check if it's actually applied to API routes:
grep -rE "(rateLimit|rateLimiter|Ratelimit|slidingWindow)" --include="*.ts" --include="*.tsx" --include="*.js" src/app/api/ app/api/ pages/api/

操作： 如果公开 API 路由没有使用速率限制器：

• 标记为高严重性
• 建议使用：@upstash/ratelimit（无服务器）、express-rate-limit（Express）或自定义中间件
• 最低要求：表单每个 IP 每小时 100 次请求，身份验证端点每分钟 10 次请求
• AI 驱动的端点（大模型调用）应设置更严格的限制，以防止费用攻击

1.5.5 — 行级安全（RLS）检查

风险： 默认情况下，数据库允许任何人查看所有人的数据。忘记配置 RLS 会导致数据立即泄露。

# Check if Supabase is used (most common vibe-coding DB):
grep -E "(supabase|@supabase)" package.json

# If Supabase: verify RLS is mentioned in migration files or setup:
grep -rE "(enable_rls|row_level_security|CREATE POLICY|ALTER TABLE.*ENABLE ROW LEVEL SECURITY)" --include="*.sql" --include="*.ts"

# For Prisma: check for tenant/user scoping in queries:
grep -rE "where:.*userId|where:.*user_id|where:.*tenantId" --include="*.ts" --include="*.tsx"

# For raw SQL: check for user-scoped WHERE clauses:
grep -rE "(SELECT|UPDATE|DELETE).*FROM" --include="*.ts" --include="*.tsx" | grep -v "WHERE.*user"

操作： 如果使用了数据库，但未发现 RLS／用户范围隔离：

• 标记为严重严重性
• 对于 Supabase：为所有表启用 RLS，并为 SELECT、INSERT、UPDATE、DELETE 创建策略
• 对于 Prisma／原始 SQL：确保每个涉及用户数据的查询都包含 userId／tenantId 筛选条件
• 经验法则：如果用户能看到其他用户的数据，就是数据泄露

---

阶段 2：图谱（数据流）

• 识别入口点（路由、操作、CLI）
• 追踪输入： 用户输入 → 服务 → 数据库
• 验证校验： 在边界处使用 Zod/Typebox

阶段 3：审计员（规范与代码）

• 阅读 docs/features/*.md 以确定范围
• 差距分析： 文档中有但代码中缺失的功能
• 孤儿分析： 文档中没有的代码（僵尸代码）

阶段 4：审查者（逻辑探查）

选择风险最高的文件并进行模拟：

• “如果我发送 null、空字符串或负数 ID，会怎样？”
• “如果两个请求同时访问这里，会怎样？”（竞态条件）
• “我能否直接访问这个 Service 函数？”（绕过身份验证）

阶段 5：架构师（质量）

• 性能：循环中的 await → N+1 查询
• 臃肿：文件是否超过 200 行？函数是否超过 50 行？
• 类型：是否使用了 any 或 as unknown？
• 结构：是否符合 Feature-Sliced Design？

阶段 6：报告

创建 .jstar/audit_report.md：

严重程度	类别	位置	问题	建议
CRITICAL	SECURITY	api/auth	...	...
HIGH	LOGIC	service.ts:42	...	...
HIGH	GUARDRAIL	package.json	未安装速率限制器	添加 @upstash/ratelimit

严重程度：CRITICAL、HIGH、WARNING、INFO 类别：SECURITY、LOGIC、COMPLETENESS、QUALITY、GUARDRAIL

阶段 7：修复

针对每个 CRITICAL/HIGH：

1. 实施修复
2. 运行构建/测试
3. 使用 grep/逻辑检查重新验证
4. 暂存更改