Overview

aaai (audit for asset integrity) is a folder diff auditor.

It compares two directory trees and audits the differences against a YAML definition of expected changes. Every accepted change requires a human-readable reason, making audit decisions traceable and explainable.

Key concepts

Getting Started

インストール

# ソースからビルド（Rust 1.81+ が必要）
cargo build --release -p aaai-cli -p aaai-gui

# バイナリを PATH に追加（例）
cp target/release/aaai ~/.local/bin/
cp target/release/aaai-gui ~/.local/bin/

初回セットアップ（推奨: aaai init）

新しいプロジェクトでは aaai init が最も簡単な出発点です。

cd /your/project
aaai init

対話的に以下を設定できます。

• Before / After フォルダパス
• 監査定義ファイルの場所
• 承認者名
• 初回スナップショットの生成

--non-interactive フラグで CI/スクリプトから使えます。

aaai init --non-interactive --dir /path/to/project

手動セットアップ（ステップバイステップ）

1. 差分テンプレートを生成する

aaai snap --left ./before --right ./after --out audit.yaml

生成された audit.yaml の各エントリに reason フィールドを記入します（空欄のままだと Pending 扱い）。

2. 監査を実行する

aaai audit --left ./before --right ./after --config audit.yaml

• PASSED — 全エントリが期待通りに変更されている
• FAILED — ルール不一致のエントリがある
• PENDING — reason 未記入のエントリがある（--allow-pending で続行可）

3. 問題を確認して修正する

# 差分の詳細を確認
aaai diff --left ./before --right ./after --content

# ベストプラクティスチェック
aaai lint audit.yaml

4. レポートを出力する

# Markdown レポート
aaai report --left ./before --right ./after --config audit.yaml --out report.md

# HTML レポート（ブラウザで開ける）
aaai report --left ./before --right ./after --config audit.yaml \
            --format html --out report.html

GUI を使う

aaai-gui

Opening 画面で Before / After / 定義ファイルを指定して「監査を開始」をクリックします。 詳しくは GUI ガイド を参照してください。

.aaai.yaml でデフォルト設定

プロジェクトルートに .aaai.yaml を置くと、よく使うパスと設定を省略できます。

version: "1"
default_definition: "audit/audit.yaml"
default_ignore: "audit/.aaaiignore"
approver_name: "your-name"
mask_secrets: true

# 初期テンプレート生成
aaai config --init

シェル補完のインストール

# Zsh の例
aaai completions zsh > ~/.zfunc/_aaai
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
source ~/.zshrc

次のステップ

• CLI リファレンス — 全コマンドの詳細
• 監査定義ファイル — YAML フォーマット
• 内容監査戦略 — None / Checksum / LineMatch / Regex / Exact
• CI/CD 統合 — GitHub Actions での使い方
• GUI ガイド — 3 ペイン画面の操作方法

CLI リファレンス

aaai の全コマンドとフラグを説明します。

共通オプション

すべてのコマンドで --help が使えます。

aaai --help
aaai <command> --help

aaai audit

2つのフォルダを比較し、監査定義ファイルに照らして審査します。

aaai audit --left <BEFORE> --right <AFTER> --config <FILE> [OPTIONS]

終了コード:

例:

# 基本的な監査
aaai audit --left ./before --right ./after --config audit.yaml

# CI/CD 向け（JSON 出力 + 履歴なし）
aaai audit --left ./before --right ./after --config audit.yaml \
           --json-output --no-history

# 除外パターン + 機密値マスク
aaai audit --left ./before --right ./after --config audit.yaml \
           --ignore .aaaiignore --mask-secrets

aaai snap

現在の差分から監査定義テンプレートを生成します。

aaai snap --left <BEFORE> --right <AFTER> --out <FILE> [OPTIONS]

例:

# 初回スナップショット
aaai snap --left ./before --right ./after --out audit.yaml

# テンプレート適用（バージョン番号変更パターン）
aaai snap --left ./before --right ./after --out audit.yaml \
          --template version_bump

# 承認者を自動設定
aaai snap --left ./before --right ./after --out audit.yaml \
          --approver "alice" --suggest-glob

aaai report

監査結果をレポートファイルに出力します。

aaai report --left <BEFORE> --right <AFTER> --config <FILE> \
            --out <FILE> [--format markdown|json|html|sarif]

例:

aaai report --left ./before --right ./after --config audit.yaml \
            --format html --out report.html

# GitHub Actions 向け SARIF
aaai report --left ./before --right ./after --config audit.yaml \
            --format sarif --out results.sarif

aaai check

差分を実行せずに定義ファイルの妥当性を検証します。

aaai check <FILE> [--all]

aaai lint

定義ファイルのベストプラクティスをチェックします。

aaai lint <FILE> [OPTIONS]

検出項目:

aaai diff

定義ファイルなしで純粋な差分を表示します。

aaai diff --left <BEFORE> --right <AFTER> [OPTIONS]

aaai merge

2 つの定義ファイルをマージします。

aaai merge <BASE> <OVERLAY> [--out <FILE>] [OPTIONS]

aaai history

過去の監査実行履歴を表示します。

aaai history [-n <N>] [--stats] [--json-output]

aaai export

承認済みエントリを CSV または TSV に出力します。

aaai export --left <BEFORE> --right <AFTER> --config <FILE> \
            [--out <FILE>] [--format csv|tsv] [--all]

aaai dashboard

カラーコードの統計カードを表示します。

aaai dashboard --left <BEFORE> --right <AFTER> --config <FILE> [--detail]

aaai watch

ファイル変更を監視して自動再実行します。

aaai watch --left <BEFORE> --right <AFTER> --config <FILE> \
           [--debounce-ms <MS>]

Ctrl+C で停止します。

aaai init

対話型プロジェクト初期設定ウィザードです。

aaai init [--dir <DIR>] [--non-interactive]

--non-interactive でプロンプトをスキップしてデフォルト値で .aaai.yaml を生成します。

aaai config

プロジェクト設定ファイル .aaai.yaml を表示または生成します。

aaai config [--init] [--dir <DIR>] [--show]

aaai version

バージョン情報を表示します。

aaai version [--json-output]

aaai completions

シェル補完スクリプトを生成します。

aaai completions <bash|zsh|fish|powershell>

インストール例:

# Bash
aaai completions bash >> ~/.bash_completion

# Zsh
aaai completions zsh > ~/.zfunc/_aaai
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

# Fish
aaai completions fish > ~/.config/fish/completions/aaai.fish

Audit Definition File

YAML document that stores expected differences.

version: "1"
meta:
  description: "Release v2.3.0 audit"
entries:
  - path: "config/server.toml"
    diff_type: Modified
    reason: "Port changed — INF-42"
    strategy:
      type: LineMatch
      rules:
        - action: Removed
          line: "port = 80"
        - action: Added
          line: "port = 8080"
    enabled: true

Content Audit Strategies

aaai provides five strategies for content-level auditing. The strategy is chosen per entry in the audit definition.

None

Checks only that the expected diff type occurred. No content inspection.

strategy:
  type: None

When to use: File additions/deletions where content doesn’t need to be verified; or as a placeholder while you define more specific rules.

Caution: Do not use for important configuration files without adding a more specific strategy later.

Checksum

Verifies the file’s SHA-256 digest matches an expected value.

strategy:
  type: Checksum
  expected_sha256: "abc123...64hexchars"

When to use: Binary files (images, archives, compiled assets), or any file where byte-for-byte identity must be confirmed.

Getting the hash:

sha256sum myfile.bin   # Linux
shasum -a 256 myfile   # macOS

LineMatch

Verifies that specific lines were added and/or removed.

strategy:
  type: LineMatch
  rules:
    - action: Removed
      line: "port = 80"
    - action: Added
      line: "port = 8080"

When to use: Configuration value changes. The most common strategy for TOML, YAML, .env, and INI files.

Rules: Each rule checks for one exact line. Order does not matter. Whitespace is significant (leading/trailing spaces must match).

Regex

Verifies that changed lines match a regular expression pattern.

strategy:
  type: Regex
  pattern: "^version = \"\\d+\\.\\d+\\.\\d+\""
  target: AddedLines   # AddedLines | RemovedLines | AllChangedLines

When to use: Version numbers, dates, or any value that changes predictably but cannot be pinned to a single exact value.

Target options:

• AddedLines — pattern applied to lines only in the after file
• RemovedLines — pattern applied to lines only in the before file
• AllChangedLines — pattern applied to all changed lines

Exact

Verifies that the after-file’s full content exactly matches expected text.

strategy:
  type: Exact
  expected_content: |
    [server]
    host = "0.0.0.0"
    port = 8080

When to use: Small, stable files where any deviation is unacceptable.

Caution: Avoid for files larger than a few KB. Hard to maintain when the file changes frequently.

GUI ガイド

aaai-gui を起動します。

aaai-gui

1. Opening 画面（プロジェクト選択）

起動後に最初に表示される画面です。

プロファイル機能 — よく使う設定の組み合わせをプロファイルとして保存できます。

1. 4つのフィールドを入力する
2. プロファイル名を入力して「現在の設定をプロファイルとして保存」をクリック
3. 次回以降は保存済みプロファイルを「読み込む」ボタンで一発展開

「監査を開始」ボタンを押すと、バックグラウンドスレッドでフォルダ比較を実行します（大規模フォルダでも GUI は応答を維持します）。

2. メイン画面（3 ペイン）

2-1. ダッシュボード

ファイルを選択する前に表示されます。

• 結果バナー — PASSED（緑）または FAILED（赤）を大きく表示
• サマリーカード — OK / Pending / Failed / Error / Ignored の件数
• 要注意リスト — Failed / Pending / Error のエントリを最大 8 件表示

2-2. ファイルツリー（左ペイン）

変更のあった全ファイルを一覧表示します。

フィルターバー — 「変更のみ」「すべて」「未承認」「失敗・エラー」で絞り込めます。

検索バー — パス名でインクリメンタルフィルターをかけられます。

バッチ選択 — 各行のチェックボックスで複数選択し、「Batch Approve」ボタンで共通理由を入力して一括承認できます。

2-3. 差分ビューア（中央ペイン）

ファイルを選択すると左右並列の差分を表示します。

• 追加行 — 緑の背景
• 削除行 — 赤の背景
• 行番号 — 左端に表示
• 統計バー — ヘッダー下に +N lines / −N lines とサイズ変化を表示
• バイナリファイル — SHA-256・サイズ・一致/不一致を専用パネルで表示

2-4. インスペクター（右ペイン）

選択したファイルの審査・承認を行います。

ヘッダー

• パス・差分種別・ステータスバッジを表示
• AuditWarning がある場合は黄色の警告ブロックを表示

入力フィールド

「承認して適用」ボタンで承認します。承認後は「保存」ボタンで定義ファイルに書き込みます。

3. キーボードショートカット

4. フッター

5. レポート出力

ツールバーの Export MD / Export JSON ボタンでレポートを出力できます。

出力先: カレントディレクトリの aaai-report.md / aaai-report.json

6. 典型的なワークフロー

1. aaai-gui を起動
2. Before / After / 定義ファイルを指定して「監査を開始」
3. ダッシュボードで全体状況を把握
4. Pending エントリをファイルツリーで選択
5. 差分ビューアで変更内容を確認
6. インスペクターで理由・戦略を入力して「承認して適用」
7. Ctrl+S で保存
8. Ctrl+R で再実行して全 OK を確認
9. Export MD でレポートを出力

CI/CD Integration

aaai is designed to run in CI/CD pipelines with predictable exit codes and machine-readable output.

Exit codes

GitHub Actions example

- name: Audit release artifacts
  run: |
    aaai audit \
      --left ./dist-before \
      --right ./dist-after \
      --config ./audit/release.yaml \
      --no-history

SARIF annotations

Generate SARIF output to get inline file annotations in GitHub pull requests:

- name: Run aaai audit
  run: |
    aaai report \
      --left ./before \
      --right ./after \
      --config ./audit.yaml \
      --format sarif \
      --out results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Allowing pending entries in draft mode

During initial setup, you may want CI to pass even when entries are pending:

aaai audit --left ./before --right ./after \
           --config ./audit.yaml \
           --allow-pending --no-history

Watch mode for local development

aaai watch --left ./before --right ./after --config ./audit.yaml

Project-level defaults (.aaai.yaml)

Place .aaai.yaml at the repository root to avoid repeating flags:

version: "1"
default_definition: "audit/audit.yaml"
default_ignore: "audit/.aaaiignore"
approver_name: "ci-bot"
mask_secrets: true

Shell completion

Install completions for faster CLI use:

# Bash
aaai completions bash >> ~/.bash_completion

# Zsh
aaai completions zsh > ~/.zfunc/_aaai

# Fish
aaai completions fish > ~/.config/fish/completions/aaai.fish

Frequently Asked Questions

Why does aaai require a reason for every entry?

The central value of aaai is explainability. A diff without a reason is just a change — it tells you what happened but not why it was accepted. The mandatory reason transforms each entry from a technical fact into a human-readable decision record that future maintainers (including your future self) can understand.

How do I handle files I never want to audit?

Add them to .aaaiignore using gitignore-style patterns:

# Build artifacts
target/**
dist/**
*.lock

# OS files
.DS_Store
Thumbs.db

Can I use glob patterns in audit rules?

Yes. The path field accepts glob patterns:

- path: "logs/*.log"
  diff_type: Modified
  reason: "Log files rotate on every deploy"
  strategy:
    type: None

Exact-path entries always take priority over glob entries when both match.

What happens when an entry expires?

Expired entries (expires_at in the past) still produce OK verdicts during audit — expiry is a reminder, not an enforcement mechanism. The CLI and GUI both display warnings so you know to review them.

How do I merge definitions from two teams?

aaai merge base.yaml overlay.yaml --out merged.yaml

The overlay wins on conflicts. Use --detect-conflicts first to see what would be overwritten.

Can I generate completions for my shell?

Yes — see CI/CD Integration.

How do I embed diff text in reports?

aaai report --left ./before --right ./after \
            --config ./audit.yaml --out report.md \
            --include-diff

This embeds a diff-formatted block for every Modified text file.

Is aaai safe to run in CI on untrusted code?

aaai reads files but never executes them. It does write to:

• The audit definition file when saving.
• ~/.aaai/history.jsonl (unless --no-history is passed).

It never modifies the files it is comparing.

What is SARIF output used for?

SARIF (Static Analysis Results Interchange Format) is a JSON standard that GitHub, GitLab, and Azure DevOps use to show inline annotations on pull requests. Generate SARIF with --format sarif and upload it via your CI provider’s upload action to get per-file, per-line annotations.