add-guard-protection

Arcjet Guard による保護の追加

Arcjet Guard は、レート制限、プロンプトインジェクションの検出、機密情報のブロック、HTTP リクエストがないコードパス向けのカスタムルールを提供します。AI エージェントのツール呼び出し、MCP ツールハンドラー、バックグラウンドジョブプロセッサー、キューワーカーなどが対象です。

ステップ 0：Arcjet CLI のセットアップ

Arcjet CLI は、認証、サイトの管理、リモートルールの設定、トラフィックの監視を行う主要なツールです。まだ利用できない場合は、インストールしてください。

# Via npx (no install required)
npx @arcjet/cli --help

# Or install globally via npm
npm install -g @arcjet/cli

# Or via Homebrew
brew install arcjet

認証

arcjet auth login

ブラウザーが開き、認証が行われます。arcjet auth status でステータスを確認してください。

サイトとキーのセットアップ

# List your teams
arcjet teams list

# List sites for a team
arcjet sites list --team-id <team-id>

# Create a new site
arcjet sites create --team-id <team-id> --name "My Guard App" --confirm

# Get the SDK key for a site
arcjet sites get-key --site-id <site-id>

キーを環境ファイル（.env、.env.local など）に ARCJET_KEY として追加してください。

ステップ 1：言語を判定してインストールする

プロジェクト内に言語を示すファイルがあるか確認してください。

• package.json → JavaScript/TypeScript → npm install @arcjet/guard（@arcjet/guard >= 1.4.0 が必要です）
• requirements.txt / pyproject.toml → Python → pip install arcjet（arcjet >= 0.7.0 が必要です。Guard は含まれています）
• go.mod、Cargo.toml、pom.xml、またはその他の言語 → Guard は利用できません。Arcjet Guard が現在サポートしているのは JavaScript/TypeScript と Python のみであることをユーザーに伝えてください。独自の模倣実装を作成したり、存在しないパッケージをでっち上げたりしないでください。ユースケースについて Arcjet に問い合わせるよう提案してください。

ステップ 2：言語別リファレンスを読む

コードを書く前に、判定した言語のリファレンスファイルを必ず読んでください。 リファレンスには、その言語で使用する正確なインポート、コンストラクターのシグネチャ、ルール設定構文、guard() の呼び出しパターンが記載されています。

• JavaScript/TypeScript：references/javascript.md
• Python：references/python.md

API を推測しないでください。リファレンスファイルが、すべてのコードパターンの信頼できる情報源です。

ステップ 3：Guard クライアントを作成する（モジュールスコープで一度だけ）

クライアントは永続的な接続を保持します。モジュールスコープで一度だけ作成し、再利用してください。関数内や呼び出しごとに作成してはいけません。変数名は arcjet にしてください。

環境ファイル（.env、.env.local など）に ARCJET_KEY が設定されているか確認してください。設定されていない場合は、次の優先順位でキーを取得してください。

1. CLI（推奨）： arcjet sites get-key --site-id <site-id> を実行します（事前に arcjet auth login が必要です。ステップ 0 を参照してください）
2. MCP： Arcjet MCP サーバーが接続されている場合は、サイトの一覧表示とキーの取得に使用します
3. 手動（最後の手段）： プレースホルダーを追加し、https://app.arcjet.com でキーを取得するようユーザーに伝えます

ステップ 4：ルールをモジュールスコープで設定する

ルールは再利用可能なファクトリーとして一度設定し、その後、呼び出しごとの入力を渡して呼び出します。この二段階のパターンは重要です。ルール設定にはサーバー側の集計に使用される安定した ID が含まれ、呼び出しごとの入力は変化するためです。

レート制限ルールを設定する際は、意味が分かりやすく衝突を減らせるよう、bucket に説明的な名前（例："tool-calls"、"session-api"）を設定してください。

ユースケースに応じたルールの選択

ユースケース	推奨ルール
AI エージェントのツール呼び出し	tokenBucket + detectPromptInjection
MCP ツールハンドラー	slidingWindow または tokenBucket + detectPromptInjection
バックグラウンド AI タスクプロセッサー	tokenBucket + localDetectSensitiveInfo
ユーザー入力を扱うキューワーカー	tokenBucket + detectPromptInjection + localDetectSensitiveInfo
ツールの結果からインジェクションをスキャンする	detectPromptInjection（返されたコンテンツをスキャンします）

ステップ 5：各操作の直前にインラインで guard() を呼び出す

各操作が実行される場所で、直接 guard() を呼び出してください。保護が必要な各ツールハンドラー、タスクプロセッサー、または関数内にインラインで記述します。guard を共通のヘルパー関数でラップしないでください。

各 guard() 呼び出しには、以下を指定します。

• label：ダッシュボードに表示する説明用の文字列（例："tools.search_web"、"tasks.generate"）
• rules：バインドされたルール呼び出しの配列
• metadata（任意）：分析や監査に使用するキーと値のペア（例：{ userId }）

レート制限ルールには、明示的な key 文字列が必要です。ユーザー ID、セッション ID、API キー、または安定した識別子を使用してください。

既存のソースファイルを必ず変更してください。依存関係を package.json/requirements.txt に追加するだけでは不十分です。guard() 呼び出しは、実際のコードに組み込む必要があります。

ステップ 6：判定を処理する

必ず decision.conclusion を確認してください。

• "DENY" → 操作をブロックします。ルールごとの結果アクセサー（リファレンスを参照）を使用して、再試行までの時間など、具体的なエラーメッセージを表示します。
• "ALLOW" → 安全に続行できます。

判定を確認する正確なパターンと、ルールごとの結果アクセサーについては、言語リファレンスを参照してください。

よくある間違い

• guard を共通のヘルパー関数でラップする — guardToolCall() や protectCall() などのラッパーを介して guard() を呼び出すと、各操作に適用されるルールがわかりにくくなります。各操作が実行される場所でインラインに guard() を呼び出してください。
• 呼び出しのたびにクライアントを作成する — クライアントは永続的な接続を保持します。モジュールスコープで一度だけ作成してください。
• 関数内でルールを設定する — ルール設定には安定した ID が含まれています。呼び出しごとに作成すると、ダッシュボードの追跡とレート制限の状態が損なわれます。
• レート制限ルールで key パラメーターを指定し忘れる — key がないと、Guard はユーザーごとの制限を追跡できません。
• レート制限ルールで bucket を指定し忘れる — 名前付きのバケットがないと、異なるルールが衝突する可能性があります。
• リクエストがないのに HTTP SDK を使用する — HTTP を使用しないコードでは、@arcjet/node、@arcjet/next、arcjet() ではなく、@arcjet/guard / arcjet.guard を使用してください。
• decision.conclusion を確認しない — 続行する前に必ず確認してください。
• 汎用的な DENY メッセージを使用する — ルールごとの結果アクセサーを使用して、再試行までの時間など、具体的な情報をユーザーに伝えてください。

ステップ 7：CLI で Guard の判定を検証する（近日公開）

注： arcjet guards CLI サブコマンドはまだリリースされていません。利用可能になったら、このフィードバックループを使って Guard の判定が正しく行われていることを確認してください。

Guard のコードを追加したら、CLI を使って判定が正しく行われていることを確認します。アプリケーションを実行し、Guard を呼び出して判定を調べ、必要に応じて調整するというフィードバックループを作ります。

1. 監視を開始する

別のターミナルで、Guard の判定のストリーミングを開始します。

arcjet guards watch --site-id <site-id>

このコマンドは新しい Guard の判定をポーリングし、届いた順に表示します。拒否だけに絞り込むには --conclusion DENY を、より頻繁にポーリングするには --interval 2 を使用してください。

2. Guard を呼び出す

アプリケーションを実行し、guard() を呼び出すコードパスを実行します。各呼び出しの判定が、監視出力に表示されます。

3. 判定を確認する

判定が期待どおりでない場合は、詳細を確認します。

# List recent guard decisions
arcjet guards list --site-id <site-id>

# Get per-rule breakdown for a specific decision
arcjet guards details --site-id <site-id> --decision-id <decision-id>

詳細ビューには、各ルールの実行、そのモード（ライブ／ドライラン）、判定、理由、およびスキップされたかどうかが表示されます。これを使って、Guard が予期せず許可または拒否した理由を調べてください。

4. 調整して繰り返す

ルールが期待どおりに動作しない場合は、次の点を確認してください。

• label が判定に表示される内容と一致していること
• レート制限ルールの key が正しいこと（キーが異なるとバケットも異なります）
• 各ルールの bucket 名が一意であること
• ルールの順序が正しいこと。ルールは配列の順に実行され、前のルールが DENY を返すと、後続のルールは実行されません

その後、判定が期待どおりになるまで、再実行して再度監視してください。

CLI クイックリファレンス

タスク	コマンド
CLI のインストール／実行	npx @arcjet/cli or brew install arcjet
認証	arcjet auth login
認証状態の確認	arcjet auth status
チームの一覧表示	arcjet teams list
サイトの一覧表示	arcjet sites list --team-id <id>
サイトの作成	arcjet sites create --team-id <id> --name "Name" --confirm
SDK キーの取得	arcjet sites get-key --site-id <id>
ガード判定の監視	arcjet guards watch --site-id <id>
ガード判定の一覧表示	arcjet guards list --site-id <id>
ガード判定の詳細	arcjet guards details --site-id <id> --decision-id <id>

グローバルフラグ

すべてのコマンドで以下を使用できます。

• --output text|json — 出力形式（デフォルト：TTY では text、それ以外では json）
• --fields <list> — JSON 出力に含めるフィールドをカンマ区切りで指定します
• --no-color — ANSI カラーを無効にします（NO_COLOR 環境変数にも対応）
• --timeout <duration> — 最大実行時間（例：30s、5m。0 を指定すると無効になります）

終了コード

コード	意味
0	成功
1	一般エラー（不明なコマンド、API エラー、ネットワークエラー）
2	認証エラー（未ログイン、トークンの期限切れ）
3	入力検証エラー（無効な ID、範囲外の値）
4	確認が必要です（変更操作には --confirm が必要です）