システム構成要素
連携アダプター
アダプターは、エージェントのツール呼び出しのペイロードを正規化された呼び出し情報に変換し、ガードの判定をそのエージェント向けの拒否形式に戻します。システム全体から見ると、アダプターがコマンド実行として扱うのは、連携ごとに定めた特定のツール名だけです。未知のツールがシェルコマンドとして扱われることはありません。ポリシーファイル、Git メタデータ、機密パスの検査は引き続き受けますが、その内容がコマンドとしてパースされることはありません。 各エージェントが使うアダプター、hook のフラグ、設定ファイルの場所は、すべて連携アーキテクチャにまとめてあります。設定用のコマンドはインストールを参照してください。ポリシースナップショット
loadPolicySnapshot() は、ユーザーポリシーファイル、プロジェクトポリシーファイル、各スコープの rule.json、そして設定された各設定元が指す rulebook ファイルから、実行時に適用するポリシーを組み立てます。内容だけでなく、次の実行時契約も重要です。
- 書き込み、ネットワーク通信、メモリ上のキャッシュのいずれも行いません。 rulebook はライブファイルであり、ローダーはツール呼び出しのたびに各
rulebook.jsonをディスクから読み取ります。ネットワークに接続するのはcc-safety-net rule addとcc-safety-net rule updateだけです。 - 結果は**再帰的に不変（immutable）**です。ポリシーオブジェクト、rules 配列、各ルールとその
block_args、transparent wrapper の一覧、safety ブロックとその override、破壊的コマンドルールの override、allow path、無効化されたルールと deny path を含むシークレット保護のブロックが、いずれも freeze されます。スナップショットのラッパー自体も freeze されます。 - 結果は必ず 2 つの状態のどちらかになります。
readyでは検証済みの設定元がすべて適用されます。degradedでは、候補となった設定元が拒否され、代わりに安全な既定値が適用されます。degraded の理由には、失敗した設定元、有効になっていないもの、修復方法が示されます。 - ルールごとの出所情報（rulebook の名前とバージョン、公開の設定元指定、override の理由）がスナップショットに記録されます。プロジェクトポリシーファイルがある場合は、安全レベルをどのスコープが設定したかと、プロジェクトポリシーが緩和したフィールドごとに 1 行が併せて記録されます。これらは診断表示と GUI に表示されます。
順序付きガードステージ
どの連携でも、ツール呼び出しは次の固定順序で処理されます。拒否した操作は、表に示したfailureStage の値とともに監査ログに記録されます。
この順序から、次の 3 点が直接導かれます。
- ステージ 6 と 7 は、ステージ 8 より前に実行されます。 ポリシーファイルの保護と Git メタデータの保護は、設定を読み込む前に拒否を返します。常に有効で、設定の状態を一切持たず、preset・override・マスタースイッチのいずれでも弱められません。
- 機密パスの保護は、スナップショットの後、コマンド解析の前に実行されます。 3 つある即時ブロックの保護のうち、ポリシーで制御できるのはこれだけで、マスタースイッチ、パターンごとの override、deny path で調整します。
- 安全レベルを報告できるのは、ステージ 8 より後の判定だけです。 入力上限、ポリシーファイルの保護、Git メタデータの保護による拒否には、意図的に
levelと設定フォールバックの情報が含まれません。その時点ではどちらもまだ分かっていないからです。
コマンド解析の内部
ステージ 12 で分類処理が動きます。コマンドをシェルの演算子でセグメントに分割し、各セグメントを個別に検査します。1 つでもブロック対象があれば、コマンド全体を拒否します。 エンジンはセグメント間での作業ディレクトリの変更（cd と pushd）を追跡し、環境変数の代入を伝播します。そのため、対象の分類は実際のシェルの挙動を反映します。シェルラッパーやインタープリターの本体への再帰は、最大 10 階層までです。各アナライザー、安全レベルの境界、対象分類の完全な順序は、解析エンジンを参照してください。
パーサーと実行時の依存関係
parseCommand(source, dialect, limits) は、CC Safety Net 自前の POSIX パーサーまたは自前の PowerShell パーサーに処理を振り分けます。auto を指定した場合は、どちらを使うかを自動判定します。どちらも内部モジュールであり、サードパーティの文法定義をラップしたものではありません。
パーサーとアナライザーの処理上限はコンパイル時の定数で、ポリシーの設定項目ではありません。そのため、設定では引き上げられません。
最初の 3 つは、最初のパース処理を制限します。4 つ目は、パース後にアナライザーがコマンドから派生させる作業量を制限します。対象になるのは、
find -exec、xargs、parallel から再構築した子コマンド、ラッパーの背後に埋め込まれたコマンド、アナライザーに再投入する追跡済みの heredoc ファイル、PowerShell の Invoke-Expression のソースです。これを使い切ると、"Command analysis exceeds CC Safety Net's derived-command work limit. Reduce nested or embedded command complexity and retry." という理由で拒否します。これは再帰の深さの上限とも、上のステージ表にある構造的な検証の上限とも別の失敗です。
アナライザーの公開インターフェースは意図的に狭くしてあります。許可のときは何も返さず、ブロックのときだけ結果オブジェクトを返します。パーサー内部の complete / partial / limited という状態は公開しないため、呼び出し側はパースの確信度で処理を分岐させられません。
PowerShell への対応は限定的なサブセットです。対象は、Remove-Item とその別名、ファイル系コマンドレットの Get-Content、Set-Content、Add-Content、Copy-Item、Move-Item と別名 gc、cat、type、cp、mv、および既存のシェル共通ルールです。そのサブセットの範囲では、PowerShell 固有のクオート、パス区切り、接続演算子、パイプライン、動的な語の出どころを保持します。機密パスのチェックは、$HOME、$env:USERPROFILE、$env:HOME、~ のいずれかの先頭部分に、どちらのパス区切りでもリテラルの末尾部分を連結した形式を解決します。それ以外の方法で組み立てたパス、たとえば文字列連結、部分式、Join-Path を使ったものは評価しません。汎用の PowerShell インタープリターではありません。
依存関係
CC Safety Net の実行時のパッケージ依存はzod の 1 つだけで、設定の検証にのみ使用します。ソースコードでは createRequire を使って遅延読み込みします。分割された Node バンドル（Pi 向けを含む）もこの挙動を保ち、遅延読み込み先を同梱の dist/vendor/zod.cjs に向けます。単体で配布する Amp 用と OpenClaw 用の成果物では、代わりに zod をインライン展開します。zod を import しているソースモジュールは、ちょうど 1 つだけです。
公開されるバンドルには、サードパーティ製のシェルパーサーは含まれません。パススキャナーが読み取るフラットなエントリ列は、projectShellSyntax によってパース済みの中間表現から射影したものです。したがって、シェルの構造情報の出どころは、上に挙げた内部の POSIX パーサーと PowerShell パーサーだけであり、生のコマンド文字列を 2 度目にトークン化して結果がずれることはありません。
公開時の対象ランタイムは Node.js 18 以降です。
主な設計特性
- すべての連携で共通の、1 つの固定順序。 上のステージ表がそのまま仕様のすべてです。ガードにエージェントごとの分岐はありません。
- 常時有効な保護は設定より前に動く。 ポリシーファイルの保護と Git メタデータの保護は、それらを無効化しうるポリシーを読み込む前に拒否を返すため、無効化できません。
- ガード自身の失敗では fail closed。 依存処理が投げた例外、パーサーの処理上限の枯渇、ツール入力の上限違反は、いずれも許可ではなく拒否になり、失敗したステージに紐づけられます。無効な設定はこれとは別扱いで、拒否にはなりません。設定の復旧を参照してください。
- 評価中にネットワーク通信も書き込みも行わない。 実行時の評価はネットワーク通信を行わず、スナップショットの読み込み処理は書き込みを行いません。ガードが外向きの通信を検査・遮断することもありません。
- 中核はプラットフォームに依存しない。 アダプターが形式を変換し、ガードと分類処理はそのまま共有されます。
- 範囲は限定的で、網羅的ではない。 これは静的な実行前ポリシーゲートであり、OS のサンドボックス、権限境界、インストール済み連携を迂回するコマンドに対する保護ではありません。既知の制限を参照してください。
次に読むページ
技術ガイドは、ユーザー向けのライフサイクルの説明から設計の理由へと順に降りていく構成です。このページはその 3 番目にあたります。- 戻る：連携アーキテクチャには、各エージェントの呼び出しが上記のアダプターに到達するまでの流れが、仕組みには、同じ順序のユーザー向けの説明があります。
- 次へ：解析エンジンでは、ステージ 12 を掘り下げ、各アナライザー、安全レベルの境界、再帰削除の対象分類の順序を説明します。
- その次：設計原則では、この順序、常時有効な保護、自前のパーサーを採用した理由を説明します。
ready と degraded については設定の復旧、信頼境界についてはセキュリティモデル、この設計で対応できない範囲については既知の制限を参照してください。