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 — 「設定ファイルで API キーを 3 つ、README で内部 URL を、テストデータで従業員のメールアドレスを、内部チケット番号を含む TODO コメントを 12 件見つけました」

2. 🦝 INSPECT — 「API キーの 1 つは有効な本番用キーです（重大）。残りはテスト用キーですが、それでも公開すべきではありません。内部 URL からインフラストラクチャが漏れています」

3. 🦝 SANITIZE — 「キーを環境変数に移し、URL を example.com に置き換え、従業員データを削除し、TODO を一般的な表現に書き換えます」

4. 🦝 PURGE — 「BFG を使って Git の履歴からシークレットを消去し、使われていない依存関係を 2 つ削除し、古いデプロイスクリプトを削除します」

5. 🦝 VERIFY — 「再スキャンでシークレットが見つからず、すべてのテストがパスし、今後シークレットが混入しないようにコミット前フックがインストールされていることを確認しました」

---

すぐに使える判断ガイド

状況	対応
シークレットを Git にコミットした	直ちにローテーションし、履歴をクリーンアップして、強制プッシュする
依存関係に脆弱性がある	修正済みバージョンに更新し、テストして、デプロイする
認証情報がハードコードされている	環境変数に移し、キーをローテーションする
不要なコードが検出された	テストがパスするなら削除し、不確かな場合は文書化する
本番環境にデバッグコードがある	エンドポイントを削除し、ログを確認して情報漏えいがないか調べる
オープンソース化の準備をしている	全面監査を行う：シークレット、内部情報、履歴、ドキュメント

---

他のスキルとの連携

監査の前：

• bloodhound-scout — まずコードベースの構造を把握する

監査中：

• spider-weave — 認証／セキュリティシステムのレビューが必要な場合
• beaver-build — セキュリティ回帰テストを作成する場合

監査の後：

• panther-strike — 個別のセキュリティ問題を迅速に修正する場合
• grove-documentation — セキュリティ運用手順書を更新する

---

見抜く術を知る前足から、隠し通せるものはありません。 🦝