agent-guards

agent-guards core

Package Guard、Agent Firewall、Payment Guard、Email Guard、Code Guard、Agent Web Tools を支える検出エンジンを、1 つのパッケージにまとめてお使いのマシンで実行できます。

ここで行う処理はすべて決定論的です。正規表現ルール、公開リスト、パーサーを使用します。どの検出処理でもモデルを呼び出さないため、同じ入力には常に同じ判定が返され、各判定にはその判定を行ったルールのバージョンが記載されます。

実行する

npx agent-guards

これにより、6 つすべての製品のツールを備えた MCP stdio サーバーが起動します。設定も API キーもアカウントも必要ありません。

npx agent-guards --offline          # local engines only
npx agent-guards --only code-guard  # one product
npx agent-guards --list             # what you get, and which tools need the network
npx agent-guards --disable check_ip,check_password

同じパッケージで guard CLI もインストールされます。

npx --yes --package agent-guards guard scan src/
npx --yes --package agent-guards guard diff
npx --yes --package agent-guards guard stats --json

pre-commit

このリポジトリでは、pre-commit フレームワーク用のステージ済み差分フックを公開しています。Node 18 以降が必要です。.pre-commit-config.yaml に次の内容を追加してください。

repos:
  - repo: https://github.com/mlawsonking/MCP
    rev: main  # pin this to a commit SHA in a shared repository
    hooks:
      - id: agent-guards-diff

次に pre-commit install を実行します。このフックは追加された行のみをスキャンし、固定されたチェックアウト内のルールを使用します。モデルを呼び出したり、ファイルの内容を外部に送信したりすることはありません。もう 1 つの手動フック agent-guards-scan は、pre-commit run agent-guards-scan --hook-stage manual を実行したときに作業ツリー全体をスキャンします。

ローカルとクラウド、その違いが重要な理由

ローカルツールはすべてお使いのマシン上で実行されます。スキャンするテキストが外部に送信されることはありません。

オフラインで動作するローカル機能	ネットワークが必要な機能
プロンプトインジェクションと Unicode 難読化のスキャン	パッケージの存在、公開からの経過期間、脆弱性の確認（npm、PyPI、OSV）
シークレットと PII の検出、検出内容のマスキング	制裁対象および詐欺リストの照合（OFAC リスト、ブロックリスト）
コードと差分のスキャン	漏えいしたパスワードの照会（Have I Been Pwned）
URL 構造の分析	ドメインの経過期間、ASN、ブロックリストでの評価
メールの解析、なりすましのヒューリスティック検出、ヘッダーの読み取り	SPF/DMARC/MX レコード、使い捨てドメインリスト

クラウドツールは、各ツールの説明に呼び出すサービスを記載しています。--offline を指定すると、確認できなかったことが報告されます。判定結果は返されません。

この違いこそが設計のすべてです。実行されなかったチェックは、問題なしという意味ではありません。このコードベースではかつて逆の動作をしていました。背後の照会に失敗した、または照会が一度も試みられなかったにもかかわらず、4 つのエンドポイントが「制裁対象ではない」「既知の脆弱性はない」「ハニーポットではない」「安全」と回答していたのです。「わからない」という意味なのに「問題なし」と伝えるセキュリティツールは、ツールがないよりも危険です。

検出できるものと、できないもの

インジェクションスキャナーは、既知の命令上書き、ジェイルブレイク、プロンプト漏えい、データ流出、ツールポイズニングの言い回しと、それらを隠すために使われる Unicode の手法（ゼロ幅文字、双方向制御文字、Unicode タグブロック、非表示 CSS、HTML コメント内の命令）に一致するパターンを検出します。これは分類器ではなく、決定論的なパターンスキャナーです。新しい言い回しはすり抜けます。ルールを読めば、それを回避する書き方ができます。これは防御の一層であり、完全な防壁ではありません。

シークレットスキャナーは、22 種類の認証情報形式に加え、一般的な代入形式と 3 種類の PII パターンを検出します。未知の形式のシークレットや、複数行に分割されたシークレットは検出されません。保証されるのは、検出した値が redacted 出力から完全に除去されることです。隣にあるラベルだけを除去するわけではありません。

コードスキャナーは、JS/TS と Python を対象とする 31 個の正規表現ルールで構成されています。パーサー、データフロー解析、汚染追跡はないため、変数だけを引数にした exec(cmd) には反応せず、exec("ls " + dir) には反応します。これは意図的な制限であり、それを固定するテストがあります。

制裁対象の照合では、EVM 形式の OFAC アドレスリストを対象にしています。ハニーポットチェックは、honeypot.is が実際にシミュレーションするチェーンのみを対象としています。

ライブラリとして使う

const guards = require('agent-guards');

guards.injection.scan(untrustedText);      // { risk, score, verdict, findings, rules_version }
guards.secrets.scan(text);                 // { found, verdict, findings, redacted, rules_version }
guards.code.scanDiff(unifiedDiff, 'py');   // findings against new-file line numbers
await guards.safeFetch(url);               // SSRF-guarded: pins the resolved IP, rechecks every hop

選択した覚えのない URL を取得するときは、safeFetch を使ってください。ホスト名を一度だけ解決し、解決先にプライベートアドレスまたはループバックアドレスが含まれていればリクエストを拒否します。そして、そのアドレスに直接接続するため、DNS リバインディングによって汚染される二度目の名前解決は発生しません。リダイレクトの各段階でも再確認を行い、コネクションプールは使いません。プールされた接続ではアドレスの固定が行われないためです。

ルールの更新

ルールは古くなります。アドレスが制裁対象になったり、マルウェアを配布したパッケージが npm から削除されたりします。ルールが再インストール時にしか更新されない場合、こうした変更は反映されません。そのため、サーバーと CLI は1日1回ほど、ルールフィードに新しいルールセットがあるかを確認し、あれば適用します。

取得時に送信するのは、リクエスト元のサーフェス（cli、plugin、mcp、facade のいずれか）と、現在使用しているルールのバージョンの2つです。

GET /api/rules/latest?surface=mcp&have=2026.07.31

マシン ID、ユーザー ID、ファイル名、スキャンした内容などは一切送信しません。バンドルには Ed25519 で署名し、このパッケージにコンパイルされた公開鍵で検証するため、どのミラーから配信されたかは関係ありません。署名、スキーマ、または ReDoS チェックに失敗したバンドルは破棄され、現在のルールがそのまま維持されます。ルールが自動的に古いバージョンに戻ることはありません。

guard update --status     # what is in use, and when it last checked
guard update              # pull now

各判定には rules_provenance が含まれ、値は bundled または feed@<version> のいずれかです。そのため、どのルールセットによって結果が生成されたかを常に確認できます。

更新を無効にするには、--offline、AGENT_GUARDS_NO_FEED=1、または ~/.agent-guards/config.json の {"feed": false} を使用します。AGENT_GUARDS_FEED_URL を設定すると、別の場所を参照できます。更新を無効にしても、パッケージにコンパイルされたルールですべての機能を引き続き利用できます。

バンドル形式、検証手順、悪意のあるパッケージのリストの管理方法については、rules/README.md をご覧ください。

テスト

npm test

オフラインのテストスイートのみです、サードパーティのエンドポイントに対して検証するテストは手動で実行します。ランダムに失敗するテストスイートでは、誰もが失敗を気にしなくなるためです。

ライセンス

MIT。