raccoon-audit

Raccoon Audit 🦝

浣熊充满好奇。它掀起每块石头，窥探每条缝隙，把每件东西都洗一遍，看看它的本来面目。没有什么能逃过它灵巧的爪子。表面看似干净的东西，经仔细检查后也会暴露秘密。浣熊能发现别人错过的东西——提交中埋藏的密钥、依赖项中潜藏的漏洞，以及无人留意时逐渐堆积的混乱。

何时启用

• 用户要求“审计安全性”或“检查是否有密钥”
• 用户说“清理一下”或“部署前清理”
• 用户调用 /raccoon-audit 或提到浣熊／清理
• 部署到生产环境之前（安全检查）
• 接手代码库时（排查未知风险）
• 安全事件之后（事后审计）
• 移除未使用的代码、依赖项或功能
• 准备开源发布时（清理内部信息）

搭配使用： spider-weave 处理身份验证安全，beaver-build 测试安全修复

---

审计

RUMMAGE → INSPECT → SANITIZE → PURGE → VERIFY
    ↓         ↓          ↓         ↓         ↓
Search   Examine   Cleanse   Remove   Confirm
Everything  Closely   Contaminated Dead     Clean

阶段 1：翻找

小爪子掀起石头，好奇的目光探向下方……

系统地搜索不该出现的东西：

密钥检测：

# Search for common secret patterns
grep -r "api_key\|apikey\|api-key" . --include="*.{js,ts,py,json,yaml,yml,env,md}" 2>/dev/null | head -20
grep -r "password\|passwd\|pwd" . --include="*.{js,ts,py,json,yaml,yml,env}" 2>/dev/null | head -20
grep -r "secret\|token\|private_key" . --include="*.{js,ts,py,json,yaml,yml,env}" 2>/dev/null | head -20
grep -r "AKIA[0-9A-Z]{16}" . 2>/dev/null  # AWS access keys
grep -r "ghp_[a-zA-Z0-9]{36}" . 2>/dev/null  # GitHub personal tokens

常见藏匿处：

• .env 文件（应加入 .gitignore）
• 包含硬编码值的 config.json
• 包含真实凭据的测试夹具
• 看起来过于真实的文档示例
• 含有密钥的注释代码
• Git 历史记录（检查 git log -p，查找已删除的密钥）

裸错误检测（Signpost 合规性）：

Grove 要求所有错误都使用 Signpost 代码。搜索违规项：

# Find bare throw error() without throwGroveError
grep -r "throw error(" --include="*.ts" --include="*.js" | grep -v "throwGroveError\|node_modules\|\.test\."

# Find ad-hoc JSON error responses without buildErrorJson
grep -r "json.*error.*status" --include="*.ts" | grep -v "buildErrorJson\|node_modules"

# Find console.error without logGroveError
grep -r "console\.error" --include="*.ts" --include="*.svelte" | grep -v "logGroveError\|node_modules"

# Find bare alert() where toast should be used
grep -r "alert(" --include="*.svelte" --include="*.ts" | grep -v "node_modules"

Signpost 合规性检查清单：

• 没有裸用 throw error()——使用 throwGroveError() 或 buildErrorJson()
• 没有不配套使用 logGroveError() 的 console.error
• 没有临时拼凑的 JSON 错误结构——全部使用 buildErrorJson()
• 没有 alert()——使用来自 @autumnsgrove/lattice/ui 的 toast
• adminMessage 绝不暴露在客户端响应中

依赖项检查：

# Check for known vulnerabilities
npm audit
pip audit  # if using Python

输出： 找到的潜在密钥、漏洞和可疑模式清单

---

阶段 2：检查

浣熊仔细地用爪子翻转物品，一边清洗一边检查……

检查发现项，将真实风险与误报区分开来：

密钥验证： 对找到的每个潜在密钥：

1. 它是真正的密钥吗？——测试密钥／令牌是否有效
2. 它仍在使用吗？——检查创建日期和最后使用时间
3. 影响范围有多大？——它能访问哪些内容？
4. 暴露程度如何？——公开仓库、内部环境，还是仅限本地？

漏洞评估：

┌──────────────────────────────────────────────────────────────┐
│                  RISK EVALUATION MATRIX                      │
├──────────────────────────────────────────────────────────────┤
│  CRITICAL  │  Active secrets in public repos                │
│            │  SQL injection vulnerabilities                 │
│            │  Remote code execution paths                   │
├────────────┼────────────────────────────────────────────────┤
│  HIGH      │  Dependencies with known CVEs                  │
│            │  Weak cryptography (MD5, SHA1)                 │
│            │  Missing authentication on admin endpoints     │
├────────────┼────────────────────────────────────────────────┤
│  MEDIUM    │  Information disclosure in error messages      │
│            │  Missing rate limiting                         │
│            │  Verbose logging of sensitive data             │
├────────────┼────────────────────────────────────────────────┤
│  LOW       │  Outdated dependencies (no known CVEs)         │
│            │  Unused code/dependencies                      │
│            │  Comments containing internal details          │
└────────────┴────────────────────────────────────────────────┘

代码异味检查：

• 绕过安全检查的函数
• 遗留的启用状态调试标志
• 本应可配置的硬编码 URL
• 关于安全问题的 TODO 注释
• 已禁用的测试（尤其是与安全相关的测试）

输出： 按优先级排列并标注严重级别的已确认问题清单

---

阶段 3：清理

受污染的物品要彻底擦拭，直到闪闪发亮……

清理混乱，同时不破坏功能：

密钥轮换（如果已暴露）：

# 1. Revoke the exposed secret immediately
curl -X DELETE https://api.service.com/keys/EXPOSED_KEY_ID \
  -H "Authorization: Bearer ADMIN_TOKEN"

# 2. Generate new secret
NEW_KEY=$(curl -X POST https://api.service.com/keys \
  -H "Authorization: Bearer ADMIN_TOKEN" | jq -r '.key')

# 3. Update configuration (environment variables, not code!)
echo "SERVICE_API_KEY=$NEW_KEY" >> .env.local

代码清理：

// BEFORE: Secret in code
const API_KEY = "sk-live-abc123xyz789";

// AFTER: Environment variable
const API_KEY = process.env.SERVICE_API_KEY;
if (!API_KEY) {
  throw new Error("SERVICE_API_KEY environment variable required");
}

安全加固：

// Add input validation
function sanitizeInput(input: string): string {
  return input.replace(/[<>\"']/g, "");
}

// Add rate limiting
const rateLimiter = new Map<string, number[]>();

// Remove debug endpoints
// DELETE: app.get('/debug/users', ...)

依赖项更新：

# Update vulnerable packages
npm update package-name
# or
pip install --upgrade package-name

# Verify fix
npm audit  # Should show 0 vulnerabilities

输出： 密钥已移出代码、漏洞已修复的干净代码

---

阶段 4：清除

不该留下的东西会被彻底带走，再也不会回来……

移除有害的残留物：

清理 Git 历史记录（如果密钥曾被提交）：

# Use BFG Repo-Cleaner or git-filter-branch
# WARNING: This rewrites history - coordinate with team!

# BFG approach (recommended):
bfg --delete-files '.*env' --replace-text secrets.txt my-repo.git

# Or specific file cleanup:
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch path/to/secret-file' \
  --prune-empty --tag-name-filter cat -- --all

移除死代码：

# Find unused exports
npx ts-prune  # TypeScript

# Find unused dependencies
npx depcheck

# Remove with confidence after tests pass
git rm src/old-feature/
npm uninstall unused-package

环境清理：

• 从服务中移除旧 API 密钥
• 删除使用真实凭据创建的测试账户
• 如果 CI/CD 缓存中包含密钥，则清除缓存
• 如果数据库凭据已暴露，则进行轮换

更新文档：

• 从公开文档中移除内部 URL
• 清理示例中的员工姓名／ID
• 更新架构图（移除敏感细节）

输出： 干净的代码仓库、全新的凭据，以及已清理的历史记录

---

阶段 5：VERIFY

浣熊洗着爪子，最后检查一遍……

确认一切都已清理干净，并且能一直保持干净：

自动验证：

# Re-run secret scan - should find nothing
grep -r "sk-live\|sk-test" . --include="*.{js,ts,json}" 2>/dev/null

# Security tests pass
npm run test:security

# No new vulnerabilities
npm audit --audit-level=moderate

手动检查：

• 应用无需硬编码密钥即可启动
• 已记录所有环境变量（不包括它们的值！）
• 测试套件通过
• 日志中没有敏感数据
• 错误消息不会泄露内部信息

预防措施：

# Install pre-commit hooks
npm install --save-dev husky
npx husky add .husky/pre-commit "npm run lint && npm run security-check"

# Add to CI/CD pipeline
# .github/workflows/security.yml
- name: Security Scan
  run: |
    npm audit --audit-level=moderate
    npx secretlint "**/*"

验证报告：

## 🦝 RACCOON AUDIT COMPLETE

### Secrets Found & Fixed

| Location      | Severity | Action Taken                  |
| ------------- | -------- | ----------------------------- |
| config.ts     | CRITICAL | Moved to env var, rotated key |
| test/fixtures | HIGH     | Replaced with mock data       |
| README.md     | MEDIUM   | Removed internal URL          |

### Dependencies

- 3 vulnerabilities patched
- 2 unused packages removed
- All packages up to date

### Verification

- [x] No secrets in current codebase
- [x] Git history cleaned (force push required)
- [x] Pre-commit hooks installed
- [x] All tests passing

输出： 状况良好，并已落实预防措施

---

浣熊守则

好奇心

检查一切。浣熊不会想当然——它会验证。那个“无害”的测试文件里可能藏着生产环境凭据。

彻底

把每件东西都洗干净。只清理一半的密钥仍然是暴露的密钥。别只清理表面。

安全

小心处理受污染的物品。轮换密钥时，确保零停机切换。修复安全问题时，别影响生产环境。

沟通

使用调查隐喻：

• “掀开石头……”（彻底搜索）
• “清洗物品……”（仔细检查）
• “擦洗干净……”（清理）
• “带走……”（清除）

---

反模式

浣熊绝不会：

• 把密钥留在代码中，还加上“TODO: remove this”注释
• 在密钥已提交后跳过 Git 历史记录
• 轮换凭据时影响生产环境
• 认为“这只是测试密钥”就代表它是安全的
• 清理后忘记更新文档
• 相信“别人已经处理好了”

---

审计示例

用户：“在开源前审计代码库”

浣熊流程：

1. 🦝 RUMMAGE — “在配置文件中发现 3 个 API 密钥、README 中的内部 URL、测试数据中的员工邮箱，以及 12 条带有内部工单编号的 TODO 注释”

2. 🦝 INSPECT — “其中一个 API 密钥是正在使用的生产密钥（严重）。其他的是测试密钥，但也不应公开。内部 URL 会暴露基础设施信息。”

3. 🦝 SANITIZE — “将密钥移至环境变量，用 example.com 替换这些 URL，清除员工数据，并以通用方式重写 TODO”

4. 🦝 PURGE — “使用 BFG 清理 Git 历史中的密钥，移除 2 个未使用的依赖项，删除旧部署脚本”

5. 🦝 VERIFY — “重新扫描后未发现密钥，所有测试均通过，并已安装提交前钩子，以防止今后出现密钥”

---

快速决策指南

情况	操作
密钥已提交到 Git	立即轮换，清理历史记录并强制推送
依赖项存在漏洞	更新到已修补的版本，测试并部署
凭据硬编码	移至环境变量并轮换密钥
检测到死代码	如果测试通过则移除；不确定时则记录说明
生产环境中存在调试代码	移除端点，并检查日志是否有信息泄露
准备开源	全面审计：密钥、内部信息、历史记录、文档

---

与其他技能集成

审计前：

• bloodhound-scout — 先了解代码库结构

审计期间：

• spider-weave — 如果需要审查身份验证/安全系统
• beaver-build — 如果要编写安全回归测试

审计后：

• panther-strike — 如果要快速修复特定安全问题
• grove-documentation — 更新安全运行手册

---

没有什么能瞒过懂得如何寻找的爪子。 🦝