ci-guard-mcp

ci-guard-mcp

1つのローカル監査エンジン。CLI、GitHub Action、そして4つのMCPツール。

リスクのあるGitHubワークフロー、文書化されていない環境変数、認証情報の可能性、競合する依存関係の設定を、マージ前に検出します。監査は決定論的かつ読み取り専用で、ソースコードをサービスに送信せずに実行されます。実行時の依存関係はyamlとignoreの2つです。

ローカルで実行

Node.js 20以降が必要です。インデックスのスキャンと追跡対象ファイルの選択にはGitが必要です。

# Run directly with npx:
npx ci-guard-mcp scan . --fail-on warn
npx ci-guard-mcp scan . --sandbox
npx ci-guard-mcp scan . --no-git
npx ci-guard-mcp scan . --format json
npx ci-guard-mcp scan . --format sarif > findings.sarif
npx ci-guard-mcp scan . --auditor workflows --auditor lockfile
npx ci-guard-mcp scan . --auditor secrets --staged
npx ci-guard-mcp scan . --auditor secrets --include-ignored

# Or from a local source checkout:
npm ci --ignore-scripts
npm run build
node dist/cli.js scan .

終了コード：しきい値未満の場合は0、しきい値以上の検出事項がある場合は1、引数、設定、またはI/Oのエラーの場合は2です。デフォルトは--fail-on errorで、warnを指定すると警告でも失敗します。情報レベルの検出事項によってスキャンが失敗することはありません。出力形式はtext、json、sarif、githubです。--root PATHは位置引数のスキャンディレクトリと同じです。--include-ignoredを指定すると、.gitignoreのルールに一致する追跡対象ファイルも監査します（たとえば、.gitignoreの追加前にコミットされた.env）。--helpで全フラグを確認できます。

ステージ済みモードは意図的にシークレットの検出に限定されています。変更されたインデックスのblob全体（名前変更・追加されたファイルを含む）を読み取るため、ステージされていない編集によってステージ済みの認証情報が隠されることはありません。インデックス内の無視ルールを適用し、削除、シンボリックリンク、サブモジュールはスキップします。ほかの監査にはリポジトリ全体のコンテキストが必要なため、--stagedと組み合わせることはできません。

GitHub Action

このリポジトリの公開後は、FULL_COMMIT_SHAの代わりにレビュー済みの完全なコミットSHAを使用してください。

name: Repository audit
on: [push, pull_request]
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: carelessdept/ci-guard-mcp@FULL_COMMIT_SHA
        id: guard
        with:
          path: .
          fail-on: warn

入力：path（デフォルトは.）、fail-on（errorまたはwarn、デフォルトはerror）。出力：errors、warnings、findings（いずれも10進数の件数）。出力とMarkdown形式のジョブサマリーは、検出事項のしきい値を評価する前に書き込まれます。検出事項はエスケープされたワークフロー注釈になり、監査に失敗するとアクションはステータス1で終了します。運用上のエラーの場合は2で終了し、完全な件数を報告したとはみなしません。

このコンポジットアクションは、ロックされたビルド依存関係をライフサイクルスクリプトを無効にしてランナーの一時ディレクトリにインストールし、コンパイル済みのCLIを実行します。npmレジストリへのアクセス、Bash、およびactions/setup-node@v4に対応したランナーが必要です。スキャン対象リポジトリの依存関係やスクリプトがインストールまたは実行されることはありません。セルフ監査ワークフローはローカルアクションを実行し、その出力を検証します。コードスキャンサービスにアップロードする場合は、CLIを別途--format sarifで実行してください。このアクション自体はレポートをアップロードせず、書き込み権限も要求しません。

MCP サーバー

stdio サーバーは改行区切りの JSON-RPC 2.0 を使用し、MCP バージョン 2025-11-25、2025-06-18、2025-03-26、2024-11-05 をネゴシエートして、初期化、ping、ツールの検出、ツールの呼び出し、通知の無応答処理を実装しています。クライアントは初期化後に notifications/initialized を送信する必要があります。ネットワークトランスポートも認証情報も不要です。

npm 公開後の MCP クライアント設定例：

{
  "mcpServers": {
    "ci-guard": {
      "command": "npx",
      "args": ["--yes", "ci-guard-mcp", "--mcp", "--root", "/absolute/path/to/repository"]
    }
  }
}

ソースをチェックアウトした場合は、"command": "node" と "args": ["/absolute/path/to/ci-guard-mcp/dist/cli.js", "--mcp", "--root", "/absolute/path/to/repository"] を使用してください。

ツール	動作	引数
scan_repo	4 つすべての監査を実行	path?: string、includeIgnored?: boolean
check_env_drift	環境とデプロイの差異を確認	path?: string
audit_github_workflows	ワークフローのセキュリティを監査	path?: string
check_secret_leaks	認証情報の検出結果を伏せ字で表示	path?: string、staged?: boolean、includeIgnored?: boolean

パスは起動ルート内で解決されます。親ディレクトリへの移動や、ルート外へ抜けるシンボリックリンクは拒否されます。レスポンスにはテキスト形式の JSON と、同じレポートを含む structuredContent が含まれます。ツール引数が無効な場合は JSON-RPC エラーになり、実行に失敗した場合は isError: true が使用されます。標準出力にはプロトコルメッセージのみが出力されます。1 MiB を超えるフレームは拒否され、サーバーは次の改行から処理を再開します。メモリ使用量と順序を予測しやすくするため、リクエストは直列化されます。スキャンは次にキューに入ったリクエストの処理前に完了するため、キャンセル通知によって実行中の監査が中断されることはありません。

監査ルール

ルール	重大度	検出内容
workflow/pwn-request	error	イベント由来の PR ヘッド参照／リポジトリを使った pull_request_target ／ GitLab MR のチェックアウト
workflow/script-injection	error	GitHub イベント／ヘッド参照、または GitLab MR／コミットの式が run ／ script に直接展開されている状態
workflow/secret-exfiltration	error	run スクリプト内での ${{ secrets.* }} または ${{ toJSON(secrets) }} の直接展開
workflow/unpinned-action	warn	不変の SHA／sha256 ダイジェストが指定されていないリモートアクション、再利用可能なワークフロー、または GitLab の include ／ component ／ image
workflow/missing-permissions	warn	トップレベルの permissions がない状態
workflow/invalid-yaml	error	不正なワークフロー YAML、キーの重複、またはマッピングではないドキュメント
env/undocumented	warn	.env.example ／ .env.template に記載されていないリテラルのソース参照
env/dead-template	info	ソースまたはデプロイでの使用が検出されないテンプレート宣言
env/invalid-compose	error	不正な Compose YAML
secret/aws、secret/github、secret/stripe、secret/openai、secret/anthropic、secret/slack、secret/private-key	error	既知の認証情報の形式／秘密鍵ヘッダー
secret/high-entropy	error	認証情報らしい名前に対する、高エントロピーの引用符付き代入
lockfile/conflict	error	同じディレクトリ内に複数の認識対象パッケージマネージャーロックファイルがある状態
lockfile/insecure-http	error	テキスト形式のロックファイル内にある HTTP URL
lockfile/unbounded-version	warn	依存関係セクション内にある *、latest、およびこれらを参照する npm エイリアス
lockfile/invalid-package	error	不正な JSON パッケージマニフェスト
scan/skipped-file	warn	設定されたサイズ上限を超えるファイル

環境変数のパターンとして、process.env.X、角括弧構文、import.meta.env.X、Python の os.environ[...] ／ .get(...) ／ os.getenv(...)、Go の os.Getenv(...)、Rust の std::env::var(...) ／ env::var(...) がサポートされています。テンプレートと宣言はスキャンルート全体から集約されます。Docker の ENV と Compose の environment エントリーは使用箇所として扱われます。ソースで参照されている場合、デプロイ専用の変数にもドキュメントが必要です。テスト／フィクスチャはソース参照の抽出対象から除外されます。

シークレットは既知のプレフィックスと文脈に応じたエントロピー（24 文字以上、シャノンエントロピー 4.3 ビット／文字以上）を使って検出されます。値とソースの抜粋が検出結果、SARIF、MCP の結果に含まれることはありません。Git ルート内では、通常のシークレット監査は追跡対象の作業ツリーファイルを読み取り、未追跡ファイルはスキップされます。Git がない場合は、スキャン対象となるすべてのファイルがスキャンされます。その他の監査では未追跡ファイルも対象になります。デフォルトで .gitignore とネストされた ignore ルールが適用されます（--include-ignored または includeIgnored: true を指定すると、.gitignore に一致する追跡対象ファイルも強制的にスキャンされます）。組み込みの依存関係／ビルドディレクトリの除外設定も適用されます。シンボリックリンクと NUL を含むバイナリファイルはスキップされます。

設定

.ciguardrc.json または package.json の ciguard オブジェクトを使用します。rc ファイルが優先されます。不明なキーと無効な型は明示的にエラーになります。配列はデフォルト値に追加されず、置き換えます。ignore と secretIgnore のパターンには、スキャンルートを基準とした gitignore 構文を使用します。

{
  "ignore": ["generated/"],
  "allowActions": ["actions/*"],
  "ignoreEnv": ["NODE_ENV", "CI", "PATH", "HOME"],
  "secretIgnore": ["test/", "tests/", "__tests__/", "fixtures/", "__fixtures__/", "*.test.*", "*.spec.*", ".env.example", ".env.template"],
  "disabledRules": [],
  "maxFileBytes": 1048576
}

デフォルトでは allowActions は空です。公式アクションにも不変のピン留めが必要です。変更可能な公式参照を許可するには actions/* を明示的に設定するか、actions/checkout のように正確な識別子を指定してください。maxFileBytes に設定できる値は 1 KiB～16 MiB です。サイズを超えるテキストファイルは警告を生成し、この警告は disabledRules では抑制できません。このリポジトリ独自の設定では、ランディングページに説明用の例が含まれているため docs/ を除外し、GitHub の 2 つのランタイム出力変数を ignoreEnv に追加しています。

SDK

import { scan, formatSarif } from 'ci-guard-mcp';
const report = await scan({ root: '/path/to/repo', auditors: ['workflows', 'secrets'] });
console.log(report.summary);
const sarif = formatSarif(report);

名前付き監査関数は、メモリー内での統合に対応するため、{ files: [{ path, content }], config } を受け取ります。SDK の config はファイル設定を上書きします。レポートにはバージョン、検出結果、件数、スキャンしたファイルが含まれます。安定したスナップショットを作成できるよう、タイムスタンプや絶対パスのルートは含まれません。filesScanned は、選択した監査関数に関連しないファイルも含め、収集された対象のテキストファイルを数えます。

境界と制限事項

これは静的なヒューリスティック監査ツールであり、セキュリティを証明するものでも、認証情報の有効性を確認するものでもありません。コードの実行、計算によって決まる環境変数名の解決、ファイルをまたいだ呼び出しの追跡、Git 履歴の検査、ファイルの復号、リモートの再利用可能なワークフロー本文の監査、依存関係の脆弱性の分析は行いません。YAML ワークフローのチェックでは、ローカルの構造化されたステップと、ジョブレベルの再利用可能なワークフローへの参照を検査します。中間の式やファイルを介して渡されるイベント由来の値は、直接的な補間チェックをすり抜ける可能性があります。リテラルな環境パターンがコメント内の例や文字列に一致することがあります。外部の利用者や動的な読み取りは検出できないため、使用されていないテンプレートに関する通知は参考情報です。

デフォルトのシークレット除外設定は、テストやテンプレートでの誤検出を意図的に減らしています。より広く検出するには、secretIgnore を [] に置き換えてください。本物らしく見える合成トークンも報告される可能性があり、未知の認証情報、エントロピーの低い認証情報、エンコードされた認証情報は見逃されることがあります。.gitignore で無視されている追跡対象ファイルは、--include-ignored（includeIgnored: true）を指定しない通常のスキャンでは除外されます。バイナリのロックファイルはバイナリコンテンツとしてスキップされます。パッケージ固有の環境スコープは推定されません。独立したドリフトチェックを行うには、パッケージのディレクトリを個別にスキャンしてください。リポジトリ設定は信頼されたローカルポリシーとして扱われるため、プルリクエストでは設定や無視対象の変更を確認してください。同時に悪意のあるローカルプロセスが動作している状況で、MCP の起動ルートを OS レベルのサンドボックスとして使用しないでください。

開発とリリース

npm ci --ignore-scripts
npm run check
node dist/cli.js scan --fail-on warn
npm pack --dry-run

CI では、Linux、macOS、Windows 上の Node 20 および 22 で、テスト、型チェック、ビルド、パッケージのチェックを実行します。回帰テストについては CONTRIBUTING.md を、脆弱性の報告については SECURITY.md を参照してください。

MIT ライセンスです。再現可能なレポート、的を絞った変更、文書化された制限事項を通じて、オープンに保守されています。

プロトコルの参照先：MCP stdio、SARIF 2.1.0。