medusa-security

Medusa セキュリティスキル

アイデンティティ

AI ファーストのセキュリティスキャナー統合スキルです。Medusa の 76 個のスキャナーと 3,000 件を超える検出パターンを活用し、AI/ML 固有の脆弱性検出を含む包括的なセキュリティ分析を行います。

機能

1. フルスキャン — 76 個すべてのスキャナーによる包括的なセキュリティ分析
2. AI のみのスキャン — プロンプトインジェクション、MCP セキュリティ、エージェントセキュリティ、RAG セキュリティ
3. クイックスキャン — Git で変更されたファイルのみを対象に、迅速な開発フィードバックを提供します
4. 対象を絞ったスキャン — 特定のスキャナーカテゴリ（mcp、secrets、prompt-injection など）
5. SARIF 出力の解析 — 標準 SARIF v2.1.0 形式の構造化された検出結果
6. JSON 出力の解析 — Medusa 独自の JSON 形式
7. OWASP マッピング — 検出結果を OWASP Agentic AI（ASI01-10）および OWASP Top 10（A01-10）に対応付けます
8. 修正ガイダンス — 検出結果を agent-studio のスキルおよびエージェントに関連付けます
9. CI/CD 統合 — 失敗判定のしきい値、GitHub Code Scanning 用の SARIF アップロード

前提条件

Python 3.10+
pip install medusa-security

インストールを確認します：python -m medusa --version

ワークフロー：フルセキュリティスキャン

# Step 1: Verify installation
python -m medusa --version

# Step 2: Run scan
medusa scan . --format sarif --fail-on high

# Step 3: Parse output (use scripts/main.cjs)
node .claude/skills/medusa-security/scripts/main.cjs --mode full --target .

# Step 4: Review findings by severity
# CRITICAL → immediate fix required
# HIGH → fix before release
# MEDIUM → fix in next sprint
# LOW → track and address

ワークフロー：AI のみのスキャン

medusa scan . --format sarif --ai-only

スキャン対象：プロンプトインジェクション（800 件以上のパターン）、MCP セキュリティ（400 件以上のパターン）、エージェントセキュリティ（500 件以上のパターン）、RAG セキュリティ（300 件以上のパターン）。

ワークフロー：クイックスキャン（開発時）

medusa scan . --format sarif --quick

Git で変更されたファイルのみをスキャンします。開発中の迅速なフィードバックに使用してください。

ワークフロー：対象を絞ったスキャン

# MCP security only
medusa scan . --format sarif --scanners mcp-server,mcp-config

# Secrets only
medusa scan . --format sarif --scanners secrets,gitleaks,env

# AI context files only
medusa scan . --format sarif --scanners ai-context

出力処理

このスキルでは、.claude/skills/medusa-security/scripts/ にあるヘルパースクリプトを使用します。

スクリプト	用途
sarif-parser.cjs	SARIF v2.1.0 出力を解析します
json-parser.cjs	Medusa の JSON 出力を解析します
finding-formatter.cjs	OWASP マッピングを含む検出結果を整形します
main.cjs	パイプライン全体をオーケストレーションします
cli-wrapper.cjs	Medusa CLI の呼び出しをラップします
security-review.cjs	決定論的なレポート作成ツール（Glob の再帰なし）

パイプラインの使用

# Full scan with structured output
node .claude/skills/medusa-security/scripts/main.cjs --mode full --target .

# AI-only scan
node .claude/skills/medusa-security/scripts/main.cjs --mode ai-only --target .

# Quick scan (git-changed files)
node .claude/skills/medusa-security/scripts/main.cjs --mode quick --target .

決定論的なセキュリティレビュー（Claude セッションでの推奨）

最終的なセキュリティレビューレポートが必要で、再帰的な Glob のタイムアウトを避けたい場合に使用してください。

node .claude/skills/medusa-security/scripts/security-review.cjs

次のファイルを作成します。

/.claude/context/reports/security/security-review-medusa-scan-2026-02-17.md

また、次の固定パスをチェックします。

• .claude/hooks/
• .claude/lib/
• .claude/skills/medusa-security/scripts/
• .claude/CLAUDE.md

重要なランタイムのガードレール

• 長時間のセッションでは、.claude/skills/medusa-security/**/* のような再帰的な glob パターンを避けてください。
• ファイルを直接読み込み、決定論的なスクリプトのエントリーポイントを優先してください。

OWASP マッピング

検出結果は自動的に次の項目に対応付けられます。

• OWASP Agentic AI Top 10（ASI01-10）：目的の乗っ取り、ツールの誤用、コンテキストの汚染など
• OWASP Top 10（A01-10）：アクセス制御の不備、インジェクション、暗号化の失敗など

重大度のトリアージ

重大度	対応	期限
CRITICAL	直ちに修正	マージ前
HIGH	リリース前に修正	同じスプリント内
MEDIUM	次のスプリントで修正	次のサイクル
LOW	追跡して対応	バックログ

エージェントとの統合

エージェント	用途
security-architect	主な利用者です。包括的なセキュリティレビューに使用します。
penetration-tester	許可を得たうえで、対象を絞った脆弱性スキャンに使用します。
code-reviewer	コードレビューワークフローの一環として AI のみのスキャンを使用します。

CI/CD 統合

# GitHub Actions example
- name: Security Scan
  run: |
    pip install medusa-security
    medusa scan . --format sarif --fail-on high -o reports/
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: reports/medusa-results.sarif

厳守事項

1. Medusa のインストールをスキャン前に必ず確認してください。まず python -m medusa --version を実行します。インストールされていない場合はエラーではなく出力が何も返されないため、すべての脆弱性が気付かれないまま見落とされます。
2. リリースゲートとして AI のみのモードに決して頼らないでください。AI のみのモードでは、従来の SAST パターン（SQLi、XSS、パストラバーサル）を検出できません。リリースゲートの判断には、76 個すべてのスキャナーを網羅するフルスキャンが必要です。
3. CI/CD パイプラインでは --fail-on high を必ず設定してください。失敗のしきい値がないと、CRITICAL の検出結果があってもパイプラインが成功し、セキュリティ態勢に対する誤った安心感を生みます。
4. GitHub Code Scanning への SARIF のアップロードを決して省略しないでください。ローカルにしかない SARIF はビルド後に失われます。github/codeql-action/upload-sarif@v3 でアップロードすれば、検出結果が保持され、PR レビュー、傾向分析、コンプライアンス監査の記録に利用できます。
5. マージ前に CRITICAL および HIGH の検出結果を必ず修正してください。重大度の高い検出結果を未解決のままデプロイすると、攻撃対象領域が拡大し、スキャンによるセキュリティ態勢の向上が無効になります。

アンチパターン

アンチパターン	失敗する理由	正しい方法
インストール確認を省略する	Medusa がインストールされていない場合、エラーではなく何も出力されません。そのため、すべての脆弱性が気付かれないまま見落とされます	まず python -m medusa --version を実行し、終了コードが 0 以外の場合は中止します
リリースゲートに AI のみのモードを使用する	AI のみのモードでは従来の SAST パターン（SQLi、XSS、パストラバーサル）を検出できません。すべてを網羅するには 76 個のスキャナーが必要です	CI/CD ゲートではフルスキャンモードを使用し、AI のみのモードは開発時の迅速なフィードバックに限って使用します
CI で失敗のしきい値を設定しない	CRITICAL の検出結果があってもパイプラインが成功し、セキュリティ態勢に対する誤った安心感を生みます	CI パイプラインでは常に --fail-on high を使用します。高リスクのリポジトリでは --fail-on critical に変更します
MEDIUM の検出結果を無視する	MEDIUM の検出結果は、HIGH の検出結果と組み合わさることで、悪用可能な攻撃経路につながる可能性があります	各スプリントで MEDIUM の検出結果をトリアージし、追跡課題を作成せずに放置しないでください
Code Scanning に SARIF をアップロードしない	検出結果はローカルファイルにしかなく、ビルド後に失われます。そのため、PR 単位のレビューや傾向分析ができません	すべての CI 実行で github/codeql-action/upload-sarif@v3 を使って SARIF をアップロードします

メモリープロトコル

スキャン後：

• 新しい脆弱性パターンを patterns.json に記録する
• 重要な検出結果を issues.md に記録する
• 傾向分析のためにスキャン履歴を追跡する
• 繰り返し発生する誤検知には recordGotcha() を使用する

const manager = require('.claude/lib/memory/memory-manager.cjs');

manager.recordGotcha({
  text: 'False positive: medusa flags X pattern in Y context',
  area: 'security-scanning',
});

manager.recordPattern({
  text: 'Prompt injection found in CLAUDE.md context files',
  area: 'ai-security',
});

関連スキル

• security-architect — 脅威モデリングと OWASP 分析
• static-analysis — CodeQL および Semgrep の SARIF 分析
• semgrep-rule-creator — カスタム Semgrep ルールの作成
• insecure-defaults — ハードコードされた認証情報の検出
• variant-analysis — 脆弱性の亜種の発見