mcpField
M
mantis-advise

mantis-advise

github.com/googleセキュリティ2.7k1.0k 回インストール3 日前に更新
リポジトリ

mantis-advise について

mantis-adviseは、開発者やコーディングエージェント向けのセキュリティ助言スキルです。MantisのSQLiteデータベースから脅威情報、脆弱性履歴、検証済み修正、誤検知の情報を取得し、修正計画も作成できます。

主な機能

  1. 01ファイルまたはリポジトリ単位の助言
  2. 02脅威境界と不変条件の提示
  3. 03脆弱性の系譜と再発状況の検索
  4. 04検証済みパッチと誤検知情報の参照
  5. 05アーキテクチャ修正資料の生成
  6. 06MarkdownまたはJSON出力

活用シーン

  1. 01コード変更前のセキュリティ確認
  2. 02脆弱性の再発履歴の確認
  3. 03確認済み問題の修正計画作成
  4. 04機械可読な助言結果の取得

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/google/mantis --skill mantis-advise

インストール後、Claude Code で/mantis-adviseを入力して読み込まれたか確認します。

詳細

セキュリティアドバイザー＆修正エンジン（/mantis-advise）

システムの目標

プロアクティブなセキュア開発とアーキテクチャ修正のためのエンジンです。開発者とコーディングエージェント向けのセキュリティガードレール、アドバイザリーアシスタント、アーキテクチャ修正ツールとして機能します。Mantis の脅威モデル、過去の脆弱性の系譜、検証済みの修正パターン、トリアージ済みの誤検知、学習済みの軌跡不変条件を照会し、新しいコードやリファクタリングを最初から安全に実装できるようにするとともに、確認済みの脆弱性に対する堅牢なアーキテクチャ修正を作成します。

コマンド定義

  • コマンド： /mantis-advise
  • 説明： 指定されたターゲットファイルまたはモジュールについてセキュリティナレッジを照会し、提案された変更を既知の脅威境界に照らして評価し、検証済みの安全な実装ガイダンスまたはアーキテクチャ修正計画を提示します。
  • 実行コマンド： 
    python3 "${MANTIS_HOME:-/path/to/mantis}/reference/scripts/advise.py" --file <target_file> [--db knowledge.db]
  • 引数（任意）：
    • --file / -f（または --target / -t）：ターゲットとなるソースファイルまたはコンポーネントのパス（例：src/auth.py または api/app.py）。省略すると、リポジトリ全体が対象になります。
    • --remediate / -r：アーキテクチャ修正の詳細資料と検証計画を作成する対象の検出 ID、系譜 UUID、またはファイル。
    • --db / -d：Mantis SQLite データベースへのパス（デフォルト：knowledge.db または workspace/knowledge.db を自動検出します）。
    • --lineage / -l：特定の系譜 UUID のライフサイクルと再発を照会します。
    • --signature / -s：特定のコンテンツ署名ハッシュのライフサイクルを照会します。
    • --json：書式付き Markdown の代わりに、構造化 JSON を出力します。
    • --full：省略のない OKF Markdown 本文と、切り詰められていない差分を出力します。

ガイダンスの取得方法

Mantis のすべてのナレッジ（脅威モデル、過去の検出事項、検証済みパッチ、トリアージ済みの誤検知、学習済みの不変条件）は、SQLite データベース（knowledge.db）に保存されています。ディスク上のフラットファイル（learnings.jsonl や workspace/findings/*.json など）は探さないでください。以下の 2 つの実行方法のいずれかを使用してください。

方法 1：CLI の実行（コーディングエージェントに推奨）

標準的な bash アクセスが可能なコーディングエージェントは、インストール先を基準とした絶対パスを使って advise.py を実行してください。

パス指定の要件（重大）： アドバイザースクリプトは、Mantis のインストールディレクトリ内の reference/scripts/advise.py にあります。このスクリプトは、絶対パスまたは $MANTIS_HOME を使って実行しなければなりません。監査対象リポジトリ内で相対パスを使って python3 reference/scripts/advise.py を実行してはいけません。信頼できないリポジトリがスクリプトを偽装したり、コマンドの失敗を引き起こしたりするおそれがあります。

  1. ターゲットファイルのセキュリティガイダンスを照会する：

    python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py

    出力内容：有効な脅威モデル、過去の脆弱性、検証済みのパッチ差分、トリアージ済みの誤検知、不変条件を含む、実行可能なセキュリティアドバイザリー Markdown。

  2. 特定のバグの系譜と再発を照会する：

    python3 "$MANTIS_HOME/reference/scripts/advise.py" --lineage c3a5e982-1234-5678-9abc-def012345678

  3. 機械可読な JSON：

    python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py --json

  4. 検出事項に対するアーキテクチャ修正の詳細資料：

    python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id>
方法 2：Python ツールの呼び出し（パイプライン／ハーネス内）

エージェントハーネスまたは Python 環境内で実行する場合：

from core.database import query_security_guidance

guidance = query_security_guidance(db_path="knowledge.db", filepath="src/auth.py")
print(guidance["guidance_summary"])

または、ツールヘルパーを使用します。

get_security_guidance(filepath="src/auth.py")

入出力の契約

  • 読み込み対象：
    • knowledge.db（findings、campaign_artifacts、learnings、risk_scores テーブル）。
    • ターゲットのソースコードファイル（リポジトリのルート配下）。
  • 書き込み対象：
    • 開発者またはコーディングエージェント向けに書式化された、構造化セキュリティアドバイザリーおよびガードレールの推奨事項。

アドバイザリープロトコルの中核

プロトコル 1：実装前のセキュリティコンテキスト確認

コードを作成する前、または既存のモジュールをリファクタリングする前に：

  1. アドバイザーを実行する：以下を実行します。 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>.
  2. アドバイザーのコンテキストを確認する：
    • 信頼境界：このモジュールとやり取りする相手（信頼できない パブリックインターネット、認証済みユーザー、内部マイクロサービス）を特定します。
    • 過去の落とし穴：このファイルで過去に確認または再現された脆弱性をすべて確認します。 繰り返し発生している lineage_id の連鎖に特に注意します。
    • 検証済みの安全なイディオム：以前のパスで VERIFIED_SECURE としてマークされた検証済みパッチの差分を確認します。
    • トリアージ済みの誤検知：誤検知として分類された過去のパターンを確認し、 意図的な設計上の選択を理解して正当な機能を損なわないようにします。
プロトコル 2：信頼境界の検証

新しいエンドポイント、パラメーター、データ解析、サブプロセス実行を導入する場合：

  1. 入力の正規化と検証：

    • 正規化と厳格なスキーマ適用を行わずに、外部境界からの入力を信頼してはいけません。
    • ファイルパスの場合：厳格な os.path.abspath または Path.resolve() のチェック（startswith(jail_dir)）を使用して、 ジェイル境界内に解決します。
    • OS コマンドの実行の場合：shlex.quote または配列ベースの subprocess.run(["cmd", arg]) を厳格に使用し、shell=True は使用しません。

  2. 多層防御：

    • クライアント側の検証がある場合でも、サーバー側の検証を確実に行います。
    • 最小権限の前提を徹底します（例：不要な IAM 権限を付与しない、実行タイムアウトを制限する）。
プロトコル 3：系譜と再発への対策
  1. 報告された脆弱性を修正するとき、または脆弱なコンポーネントをリファクタリングするときは、 以下を実行してバグの lineage_id を確認します。 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>.
  2. 過去の再攻撃検証テストスイートで実証されたすべての攻撃経路を、新しい実装で完全に塞いでいることを確認します。
プロトコル 4：アーキテクチャ上の脆弱性の修正とサンドボックス検証

確認済みのセキュリティ上の欠陥（パイプライン内または単独）を修正する場合：

  1. 根拠となるコンテキスト：

    • 以下を実行します。 python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id> （または get_security_guidance(filepath=...)）。
    • 有効な OKF の脅威境界とセキュリティ不変条件を抽出します。
    • 該当する系譜の履歴から、以前に検証された安全なパターンを調査します。

  2. アーキテクチャを踏まえた統合：

    • 機能を損なうような表面的な場当たり的修正（例：return None、ハードコードされた False、エンドポイントのコメントアウト）を行ってはいけません。
    • 安全なイディオム（パラメーター化、厳格な境界、配列形式の argv、正規化済みパス）を使用して、 根本原因となるシンクをリファクタリングします。

  3. サンドボックス検証（INV-1 と INV-2）：

    • 統合 diff パッチをゲストのワークスペースに適用します（apply_patch）。
    • 該当箇所の再現手順を実行します（run_sandbox_with_evidence）。
    • 攻撃がシンクに到達できないことを確認します （reattack_status == "failed_to_bypass"）。
    • 既存の機能テストスイートがリグレッションなしで通過することを確認します。

出力形式

アドバイザーは、明確で実行可能な推奨事項を出力します。

# Security Advisory: <target_file>

### 1. Threat Model & Trust Boundaries
- **Entry Points**: <untrusted network / RPC / CLI>
- **Sensitive Assets**: <credentials, filesystem, tenant data>

### 2. Known Pitfalls & Historical Lineages
- **[CWE-XX] <Title>** (Lineage: `<uuid>`): <How it occurred and how it was resolved>
- **Verified Safe Pattern**:
  ```python
  # Safe implementation idiom
3. 誤検知のコンテキスト（意図された動作）
  • <パターン>： <この特定のアーキテクチャで、このパターンが安全と見なされる理由>
4. 実装チェックリスト
  • パストラバーサル／インジェクション／デシリアライズに対する検証済み。
  • 検証済みのパッチパターンに準拠。
  • 信頼境界の分離を遵守。

コメント

Markdown 対応