> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 監査ログリファレンス

> CC Safety Net の監査ログに関するリファレンス。ファイル配置、JSONL レコードスキーマ、記録内容、保持と削除、範囲が限定されたシークレット編集について説明します。

CC Safety Net は、コマンドの判定を構造化された監査証跡に書き込みます。エージェントが何を実行しようとしたか、その結果がどうなったかを確認するために使います。ログは JSON Lines（JSONL）形式で、1 行に 1 つの JSON オブジェクトがあります。CC Safety Net は、これらのログをローカルマシンに保存します。

このページでは、ファイル配置、レコードスキーマ、対象範囲、保持、編集の制限を定義します。UI でログを読む方法については、[ダッシュボード](/docs/ja/guides/dashboard)を参照してください。ターミナルで読む方法については、[`logs`](/docs/ja/reference/cli-commands)を参照してください。

## ログの配置

レコードは、プロジェクトおよび月ごとのパスに書き込まれます。

```text theme={"dark"}
~/.cc-safety-net/logs/<encoded-cwd>/<YYYY-MM>/<YYYY-MM-DD>-<session-id>.jsonl
```

| パス部分                        | 導出方法                                                                             |
| --------------------------- | -------------------------------------------------------------------------------- |
| `~/.cc-safety-net/logs`     | 監査ルート。ホームディレクトリは、`CC_SAFETY_NET_AUDIT_HOME`、`HOME`、OS のホーム検索の順で取得され、絶対パスである必要がある |
| `<encoded-cwd>`             | 作業ディレクトリの英数字以外の各文字を `-` に置き換え、180 文字に切り詰めたもの。エンコードするものがない場合は `no-cwd`            |
| `<YYYY-MM>`                 | レコードのタイムスタンプの年月                                                                  |
| `<YYYY-MM-DD>-<session-id>` | レコードの日付とエージェントのセッション ID                                                          |

セッション ID はファイル名に入る前にサニタイズされます。`A-Za-z0-9_.-` 以外の連続した文字は `_` にまとめられます。先頭と末尾の `.`、`-`、`_` は削除されます。結果は 128 文字に切り詰められます。サニタイズ後に空文字列、`.`、`..` になった場合、**書き込み全体を中止します**。これはパストラバーサルに対する防御であり、単なる書式調整ではありません。

ディレクトリはモード `0700` で作成され、ログファイルにはモード `0600` で追記されます。

書き込みの失敗は無視されます。監査ログは、許可またはブロックの判定を変更できません。

<Note>
  `~/.cc-safety-net/logs/` の直下にあるフラットファイルは、以前のバージョンが使った**レガシー**配置です。`logs` は今もこれらを読み、保持処理もこれらを対象にします。[`logs --prune-legacy`](#レガシーログの削除) は、このファイルを対象にします。新しいレコードがこの場所に書き込まれることはありません。
</Note>

## 各レコードには 1 つの判定が入る

各行には、許可またはブロックされた 1 つのコマンド判定が記録されます。コマンド、判定の原因となったセグメント、理由、一致したルールが含まれます。

* 書き込み処理では、コマンド出力、モデルプロンプト、ツール結果、会話内容を読み取らず、保存もしません。
* 拒否は常に記録されます。
* 許可の判定は、ツール呼び出しが実際にコマンドへルーティングされた場合にのみ記録されます。許可されたコマンド以外のツール呼び出しでは、レコードは作られません。
* fail-closed パスから生じたブロック、つまりアナライザーでエラーが発生し、推測せずにガードが拒否した場合も記録されます。このレコードには `failureStage` と `errorCode` が設定されるため、正確に検索できます。`logs --suspect` はこのフィールドを使います。

## レコードスキーマ

| フィールド            | 型                   | 有無               | 説明                                                                                                        |
| ---------------- | ------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `ts`             | string              | 常にある             | 判定の ISO 8601 タイムスタンプ                                                                                      |
| `id`             | string              | 常に書き込まれる         | 16 文字の 16 進数。`logs --id` が受け取る ID                                                                         |
| `v`              | string              | 任意               | レコードを書いた CC Safety Net のバージョン、または `dev`                                                                   |
| `sessionId`      | string              | 任意               | サニタイズされたエージェントセッション ID                                                                                    |
| `decision`       | `"allow" \| "deny"` | 任意。既定値は `"deny"` | 実行された判定                                                                                                   |
| `agent`          | string              | 任意               | 統合 ID。例は `claude-code`。表示名のキーとしても使う                                                                       |
| `shape`          | string              | 任意               | レコードの元になったアダプター入力形式                                                                                       |
| `level`          | string              | 任意               | 判定時に有効だった安全レベル                                                                                            |
| `configFallback` | `true`              | 任意               | フォールバックポリシーを使って判定した場合に存在する                                                                                |
| `toolName`       | string              | 任意               | ツール名。256 文字が上限                                                                                            |
| `command`        | string              | 常にある             | 完全なコマンド。編集後に上限を適用                                                                                         |
| `segment`        | string              | 常にある             | 判定の原因になった特定のセグメント。編集後に上限を適用                                                                               |
| `truncated`      | `true`              | 任意               | 何かが切り詰められた場合だけ存在する。下記を参照                                                                                  |
| `reason`         | string              | 常にある             | 人が読める判定理由                                                                                                 |
| `ruleId`         | string              | 任意               | 一致したルールの ID                                                                                               |
| `intent`         | string              | 任意               | ブロック意図の分類                                                                                                 |
| `failureStage`   | string              | 任意               | ガードの失敗によって拒否された場合、つまり fail-closed になった場合に設定される                                                            |
| `errorCode`      | string              | 任意               | `path-canonicalization-limit`、`tool-input-limit`、`structural-shell-syntax-limit`、`unexpected-error` のいずれか |
| `cwd`            | string \| `null`    | 任意               | 作業ディレクトリ。編集後に上限を適用                                                                                        |

レコードの例：

```json theme={"dark"}
{"ts":"2025-01-15T10:30:00.000Z","id":"3fa9c2d1a70e8b42","v":"2.0.0","sessionId":"a1b2c3","decision":"deny","agent":"claude-code","level":"standard","command":"git reset --hard","segment":"git reset --hard","reason":"git reset --hard destroys all uncommitted changes permanently. Use 'git stash' first.","ruleId":"git-reset-hard","cwd":"/path/to/project"}
```

### 長さの上限と切り詰めインジケーター

| フィールド      | 上限        |
| ---------- | --------- |
| `command`  | 10,000 文字 |
| `segment`  | 2,000 文字  |
| `toolName` | 256 文字    |
| `cwd`      | 32,768 文字 |

上限は編集の**後**に適用されます。そのため、編集処理がトークンの途中で切れることはありません。

`command`、`segment`、`toolName`、`cwd` のいずれかが上限を超えると、レコードに `truncated: true` が追加されます。このフラグが `false` として書き込まれることはありません。フラグがなければ、何も切り詰められていません。`logs --id` は、これを `truncated: yes` または `-` として表示します。

## 記録内容：監査の対象範囲

`CC_SAFETY_NET_AUDIT_SCOPE` は、許可されたコマンド判定を拒否と一緒にログへ記録するかを決めます。

| 値         | 効果                                       |
| --------- | ---------------------------------------- |
| 未設定       | **既定値。** `all` と同じ                       |
| `all`     | 許可とブロックの両方のコマンド判定を記録する                   |
| `blocked` | 拒否のみを記録する。プライバシーを最小化する設定                 |
| その他       | 無効として扱う。拒否のみの記録にフォールバックし、`doctor` でも報告する |

無効な値は通知なしで処理されません。`doctor` は警告重大度の finding `environment.audit-scope-invalid` を生成します。内容は「Audit scope value is invalid」で、変数を `all` または `blocked` に設定して統合を再起動する修正ヒントが付きます。問題の値自体は意図的に表示されません。

拒否が対象範囲によって抑制されることはありません。対象範囲は許可の分岐のみを制御します。

## 保持

| 設定      | 値                                      |
| ------- | -------------------------------------- |
| 既定の保持期間 | **30 日**                               |
| 設定可能な範囲 | **1～365 日**                            |
| 設定キー    | `policy.json` の `audit.retention_days` |

`audit.retention_days` は 1～365 の整数である必要があります。それ以外は検証で拒否されます。まったく使用できない値は、既定の 30 日にフォールバックします。保持期間は、ポリシーファイルから単独で直接読み取られます。そのため、ポリシーのほかの部分が検証に失敗しても削除処理は動作します。

同じ値が、`logs --since` の上限と GUI の Activity ビューが提示する期間を制限します。

<Warning>
  保持期間の短縮は**元に戻せません**。スイープは実行ごとにカットオフを再計算します。値を小さくすると、既存のレコードが即座に削除対象になり、リンクが解除されます。アーカイブ、ゴミ箱、取り消しはありません。このため、GUI は値を小さくする前に確認を求めます。
</Warning>

### 削除処理は操作時に実行される

タイマーで動作する処理はありません。保持スイープは、次の操作によって開始されます。

* 各監査書き込みの後。削除の失敗によってレコードが失われないように、意図的に書き込み後に実行する
* `logs` が読み取る前
* `doctor` がアクティビティの要約を作る前
* GUI の Activity フィードが読み込まれる前

スイープは、監査ルートごとに UTC の 1 日に最大 1 回だけ走査します。監査ルートにある 0 バイトの `.last-prune` マーカーで抑制します。例外を送出せず、監査ルートを作成せず、シンボリックリンクをたどらず、認識しないファイル形式には触れません。空の月ディレクトリと空のプロジェクトディレクトリは回収されます。ただし、実行中の書き込みとの競合を避けるため、現在の月は残します。レガシーのフラットファイルは、そのファイルのタイムスタンプと内部のすべてのレコードの両方によって完全に期限切れだと証明できる場合にのみ削除されます。異なる経過時間のレコードを含むファイルは、書き換えも分割もされません。

何もスイープを開始しないため、CC Safety Net の操作がない間は、**期限切れのレコードがディスクに残ることがあります**。`logs --id` は、ディスク上にあるレコードを検索します。削除処理がまだ到達していない場合、保持期間を過ぎたレコードを返すことがあります。

### レガシーログの削除

<Warning>
  `cc-safety-net logs --prune-legacy` は、監査ルートにあるレガシーのフラットな `*.jsonl` ファイルをすべて**即時かつ元に戻せない形で**削除します。確認プロンプトも `--yes` フラグもありません。唯一のプレビューは `--dry-run` で、削除対象の正確なセットを報告し、何も削除しません。対象かどうかはファイルの場所だけで決まります。経過時間、スキーマの有効性、不正な行はすべて関係ありません。
</Warning>

これは保持スイープではありません。保持スイープは、完全に期限切れの場合にのみレガシーファイルを削除します。`--prune-legacy` は経過時間に関係なく削除します。ネストされたプロジェクトごとのログには入らず、触れません。そのことはコマンド出力にも表示されます。フラグの終了動作と拒否される組み合わせについては、[`logs --prune-legacy`](/docs/ja/reference/cli-commands)を参照してください。

## 件数と返されるエントリ

件数は期間全体を対象にします。エントリのリストには上限があるため、2 つの数値が異なることがあります。

| 表示場所               | 期間                                    | 件数                                                      | 返されるエントリ                                                               |
| ------------------ | ------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------- |
| GUI の Activity ビュー | ローカル日付の全日。日ごとのバケットの合計は、ブロック総数と正確に一致する | ブロック、許可、エージェント、ルール、コマンド、エラー、日ごとの系列をすべて期間全体で計算する         | 上限は 500。拒否が集中しても「許可済み」を追い出さないように、判定間で上限を分割する。リストが件数より少ない場合は応答にフラグを設定する |
| `doctor` のアクティビティ  | 7 日間。ローリング期間                          | 期間全体のブロック総数とセッション数。監査対象範囲に関係なく、`doctor` は許可判定をすべてスキップする | 最新の 3 件                                                                |
| `logs`             | `--since`。既定値は 30 日                   | 期間全体でフィルタリングと疑わしい繰り返しの検出を実行する                           | `--limit`。既定値は 20                                                      |

`logs` がログを走査するとき、削除する必要があったすべてのソース、つまり読み取れないディレクトリ、読み取れないファイル、不正なレコードを数えます。stderr には 1 つの警告 `warning: N audit log sources could not be read; these results are incomplete` が出ます（N が 1 の場合は `source`）。パスは表示されません。stdout と終了コードは変わらないため、`--json` の出力は解析可能な状態を保ちます。ログディレクトリがない場合は履歴が空であり、ソースの脱落ではないため、警告は出ません。

通常のリストと GUI の期間は、保持期間より前を表示しません。GUI は固定リストではなく保持値から期間の選択肢を導出します。ただし、期限切れのレコードが削除前にディスクに残っている間は、`logs --id` で直接検索すると返されることがあります。各保持設定で選べる期間については、[ダッシュボード](/docs/ja/guides/dashboard)を参照してください。

## シークレットの編集

コマンド、セグメント、ツール名、作業ディレクトリは、レコードをシリアライズする**前**にシークレット編集処理へ渡されます。認識された値は `<redacted>` に置き換えられます。

* 名前に `TOKEN`、`SECRET`、`PASSWORD`、`PASS`、`KEY`、`CREDENTIALS` を含む環境変数代入
* データベース接続変数（`DATABASE_URL`、`POSTGRES_URL`、`MYSQL_URL`、`REDIS_URL`、`MONGODB_URL`、その他の DSN、URL、URI、接続文字列変数）
* PEM 秘密鍵ブロック（`-----BEGIN ... PRIVATE KEY-----`）
* シークレットを含む HTTP ヘッダー（`Authorization`、`Cookie`、`X-API-KEY`、`API-KEY`）
* URL 資格情報（`scheme://user:pass@host` と `scheme://token@host`）および `-u user:pass`
* 署名済み URL の署名クエリパラメーター。テキストの先頭、空白、`?`、`&`、`;`、`|` の後にパラメーター名がある場合に、大文字と小文字を区別せず `x-amz-signature`、`x-goog-signature`、`sig`、`signature` の値を処理する
* 固定リストにあるプロバイダートークン形式（`ghp_...`、`gho_...`、`xoxb-...`、`npm_...`、`sk_live_...`、`rk_live_...`、`pypi-...` など）
* JWT（`eyJ...`）と AWS アクセスキー ID（`AKIA...` / `ASIA...`）

<Warning>
  **編集の範囲は限定されています。** これは固定パターンのリストであり、分類器ではありません。認識しないものはすべて、そのまま保持されます。これには、絶対ファイルシステムパス、プロジェクト名とディレクトリ名、ホスト名、IP アドレス、ユーザー名、チケット ID、ファイル名、リストにない形式の資格情報が含まれます。`reason` フィールドは、書き込み時にまったく編集されません。監査ログを機密性のあるローカルデータとして扱ってください。issue またはチャットに抜粋を貼り付ける前に確認してください。
</Warning>

GUI が誤検知レポートを送る前に、ホームディレクトリの接頭辞は削除されます。そのほかのパスはレポートに残ることがあります。

権限（ディレクトリは `0700`、ファイルは `0600`）とローカル保存は、アクセスを制限します。ログを編集することも、安全に共有できる状態にすることもありません。

## 関連ページ

* [CLI コマンド](/docs/ja/reference/cli-commands) — `logs` コマンド、フィルター、JSON 出力。
* [ダッシュボード](/docs/ja/guides/dashboard) — GUI の Activity フィードで同じレコードを読む方法。
* [ポリシー](/docs/ja/configuration/policy) — `audit.retention_days` フィールドとその検証。
* [explain トレース](/docs/ja/reference/explain-trace) — `explain` 出力にも同じ編集範囲が適用されます。
* [セキュリティモデル](/docs/ja/guides/security-model) — 監査ログが全体の脅威モデルのどこにあるか。