基本概念
| 用語 | 定義 |
|---|---|
| PreToolUse フック | ツールの実行前に動作するフック。CC Safety Net は各エージェントの PreToolUse または同等のイベントを使い、実行前にシェルコマンドを検査します。仕組みを参照してください。 |
| Fail-closed | ガードが信頼できる判定に到達できない場合、その 1 つのツール呼び出しを許可せず拒否する動作。予期しない解析エラー、不正または大きすぎるフック入力、空のコマンド、パーサー上限、strict モードで解析できないコマンドが該当します。無効な設定は fail-closed ではなく、degraded になります。設計原則とセキュリティモデルを参照してください。 |
| 判定 | 1 つのツール呼び出しに対するガードの許可または拒否の結果。監査ログがコマンド判定を記録するとき、ルール ID、有効な安全レベル、degraded ランタイムのフォールバック状態を含む 1 つの監査レコードを書き込みます。監査ログを参照してください。 |
| セグメント | 複合コマンドをシェル演算子（&&、||、|、;、改行）で分割した 1 つのコマンド。エンジンはセグメントを順に解析し、有効な作業ディレクトリなどの関連状態をセグメント間で引き継ぎます。1 つのセグメントがブロックされると、コマンド全体が拒否されます。解析エンジンを参照してください。 |
| 解析エンジン | コマンド文字列を解析し、ブロックするかを決めるプラットフォーム非依存のコア。すべてのエージェント統合が同じエンジンに入力を渡します。解析エンジンを参照してください。 |
| 統合モデル | CC Safety Net がコーディングエージェント内で動作する方法。標準入力フックのサブプロセス、エージェントが読み込むプラグイン、インプロセス拡張、イベントプラグインのいずれかです。統合モデルによって、エージェントが CC Safety Net を呼び出す方法が変わります。すべての統合が同じ解析エンジンを使います。統合アーキテクチャを参照してください。 |
設定
| 用語 | 定義 |
|---|---|
| ポリシー | 設定ドキュメント policy.json。既定では ~/.cc-safety-net/policy.json。安全プリセット、機能オーバーライド、worktree モード、破壊的コマンド保護、シークレット保護、監査保持を格納します。カスタムルールを格納する場所ではありません。ポリシーを参照してください。 |
| ポリシースナップショット | 各ツール呼び出しで、ポリシーファイル、rule.json、ロックファイル、ダイジェスト検証済みのルールブックキャッシュから構成される有効なランタイムポリシー。読み込み時に書き込み、ネットワーク要求、キャッシュを実行しません。状態は ready または degraded の正確に 2 つです。設定の回復を参照してください。 |
| プリセット | 継承する機能の既定値を提供する safety.level の値。standard、strict、paranoid のいずれかです。オーバーライドによってどのプリセットにも一致しない組み合わせになると、報告される有効レベルは custom です。モードを参照してください。 |
| 機能 | プリセットから継承され、個別に設定できる保護動作。fail_closed、paranoid_rm、paranoid_interpreters のいずれかです。ポリシーファイルの safety.overrides は機能を上げ下げします。レガシーの環境変数フラグは上げることしかできません。モードを参照してください。 |
| Degraded | 設定ソースが拒否されたときのポリシースナップショット状態。検証できないソースは削除されるか、保護的な既定値へフォールバックします。通常の作業は継続し、すべての診断表示で状態が報告されます。もう 1 つの状態は ready です。設定の回復を参照してください。 |
シェルコマンドの形式
| 用語 | 定義 |
|---|---|
| シェルラッパー | bash -c 'git reset --hard' など、別のコマンドをラップするシェルコマンド。CC Safety Net は、ラップされたコマンドを最大 10 レベルまで再帰的に解析します。ブロックされるコマンドを参照してください。 |
| インタープリターのワンライナー | python -c 'import os; os.system("rm -rf /")' のように、コードをインラインで実行するコマンド。既定で危険なパターンを検出して解析します。ブロックされるコマンドを参照してください。 |
| 動的置換 | $(...)、<(...)、$VAR など、実行時の展開に依存するコマンド値または構造。CC Safety Net は、コマンドの種類と安全レベルに従って動的置換を処理します。一部の形式は standard で許可され、fail-closed 動作が有効な場合にブロックされます。解析エンジンを参照してください。 |
再帰削除とパス
| 用語 | 定義 |
|---|---|
| cwd 自体を示すターゲット | rm -rf . など、現在の作業ディレクトリ自体に解決される rm -rf のターゲット。すべての安全レベルでブロックされます。ブロックされるコマンドを参照してください。 |
| 有効な cwd | 複合コマンド内の cd および pushd コマンドにわたって追跡される作業ディレクトリ。rm -rf のターゲット分類と worktree 検出に使います。解析エンジンを参照してください。 |
| cwd 内のターゲット | 現在の作業ディレクトリ内に解決される、再帰的な強制削除ターゲット。既定では許可され、paranoid rm モードではブロックされます。許可されるコマンドを参照してください。 |
モード
| 用語 | 定義 |
|---|---|
| strict モード | fail_closed 機能を有効にする strict プリセット。安全に解析できないコマンドを拒否します。ポリシーファイルの safety.level を設定するか、CC_SAFETY_NET_STRICT=1 でレベルを上げます。モードを参照してください。 |
| paranoid モード | strict に加えて paranoid_rm と paranoid_interpreters 機能を有効にする paranoid プリセット。ポリシーファイルの safety.level を設定するか、CC_SAFETY_NET_PARANOID、CC_SAFETY_NET_PARANOID_RM、CC_SAFETY_NET_PARANOID_INTERPRETERS で個別の機能を上げます。モードを参照してください。 |
| worktree の緩和 | ポリシーファイルの workflow.worktree_mode または CC_SAFETY_NET_WORKTREE=1 によって worktree モードを有効にすると、確認済みのリンクされた Git worktree 内で、選択されたローカル Git 破棄コマンドが許可されます。CC Safety Net が worktree を確認できない場合は、緩和を適用しません。モードを参照してください。 |
ルール
| 用語 | 定義 |
|---|---|
| ルールブック | カスタムブロックルール、メタデータ、任意の fixture を格納する JSON ファイル。rule.json でソースとして設定され、SHA-256 ダイジェストによってロックファイルに固定され、検証済みキャッシュから適用されます。ルールブック名はユーザー範囲とプロジェクト範囲でグローバルに確保されます。カスタムルールを参照してください。 |
| 透過ラッパー | rule.json の transparent_wrappers で宣言するコマンド。解析はラッパーを通して、ラッパーが実行する保護対象コマンドに到達します。ラッパーはルールブックではなく rule.json にあります。そのため、ルールブックが削除されてもラッパーは残りますが、rule.json を読み取れないと、その範囲のラッパーは失われます。カスタムルールを参照してください。 |
| ロックファイル | ルールブックソースのダイジェストとキャッシュ済み内容を追跡する JSON ファイル（rule.lock）。古いルールブックまたは改ざんされたルールブックの検出に使います。カスタムルールを参照してください。 |
ルールブック、ルール、fixture、ロックファイルの正式なスキーマについては、カスタムルールのリファレンスを参照してください。
policy.json のスキーマについては、ポリシーを参照してください。explain --json が返す JSON 形式については、explain トレースを参照してください。