# 機能設計書 87-compaudit

## 概要

本ドキュメントは、zsh補完ファイルのセキュリティ監査を実行する`compaudit`ビルトイン関数の機能設計について記述する。

### 本機能の処理概要

zshの補完システムで使用されるディレクトリのパーミッションをチェックし、セキュリティ上問題のあるディレクトリ（グループまたはその他のユーザーに書き込み権限がある、または所有者が不適切）を検出して報告するzshビルトイン関数である。

**業務上の目的・背景**：zshの補完ファイルはシェル起動時に自動的に実行されるため、セキュリティ上重要である。他のユーザーが書き込み可能なディレクトリに補完ファイルが配置されていると、悪意あるコードが実行される可能性がある。compauditはこれらのリスクを特定し、Oh My Zshのセキュリティ機能（handle_completion_insecurities）と連携して動作する。

**機能の利用シーン**：Oh My Zsh初期化時やユーザーが明示的に補完ディレクトリのセキュリティを確認したい場合に使用される。handle_completion_insecurities関数から呼び出され、検出結果に基づいて警告が表示される。

**主要な処理内容**：
1. fpathに含まれるディレクトリを走査
2. 各ディレクトリのパーミッションと所有者をチェック
3. グループ/その他書き込み可能なディレクトリを検出
4. 所有者がrootでもカレントユーザーでもないディレクトリを検出
5. 問題のあるディレクトリのパスを出力

**関連システム・外部連携**：zshビルトイン関数として提供され、compinit/compfixと連携して動作する。

**権限による制御**：特になし。パーミッションチェックは読み取り専用。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面関連なし（zshビルトイン関数） |

## 機能種別

セキュリティ監査 / バリデーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 引数は受け取らない | - |

### 入力データソース

- `$fpath`配列：補完ファイルの検索パス
- ファイルシステム：各ディレクトリのパーミッションと所有者情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | 文字列 | 安全でないディレクトリのパス（改行区切り） |
| 標準エラー出力 | 文字列 | "There are insecure directories:"メッセージ |

### 出力先

- 標準出力：安全でないディレクトリのリスト
- 標準エラー出力：警告ヘッダーメッセージ

## 処理フロー

### 処理シーケンス

```
1. fpathディレクトリの走査
   └─ 各ディレクトリについて以下をチェック
2. パーミッションチェック
   └─ グループ/その他の書き込み権限を確認
3. 所有者チェック
   └─ root または カレントユーザーが所有者か確認
4. 結果出力
   ├─ 問題があれば標準エラーにヘッダー出力
   └─ 問題のあるディレクトリを標準出力に出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[fpath配列を取得]
    B --> C{次のディレクトリ}
    C -->|あり| D[ディレクトリ存在確認]
    D --> E{存在する?}
    E -->|No| C
    E -->|Yes| F[パーミッション取得]
    F --> G{グループ書き込み可能?}
    G -->|Yes| H[安全でないリストに追加]
    G -->|No| I{その他書き込み可能?}
    I -->|Yes| H
    I -->|No| J{所有者チェック}
    J -->|問題あり| H
    J -->|問題なし| C
    H --> C
    C -->|なし| K{安全でないディレクトリあり?}
    K -->|Yes| L[ヘッダー出力 stderr]
    L --> M[ディレクトリリスト出力 stdout]
    K -->|No| N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-87-001 | グループ書き込み検出 | グループに書き込み権限があるディレクトリは安全でない | ディレクトリパーミッションにgが+wの場合 |
| BR-87-002 | その他書き込み検出 | その他に書き込み権限があるディレクトリは安全でない | ディレクトリパーミッションにoが+wの場合 |
| BR-87-003 | 所有者検証 | rootまたはカレントユーザー以外の所有者は安全でない | ディレクトリ所有者がroot/$USERでない場合 |
| BR-87-004 | ヘッダー分離 | ヘッダーメッセージはstderrに、ディレクトリリストはstdoutに出力 | 常時 |

### 計算ロジック

特になし。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ディレクトリ不在 | fpathに存在しないディレクトリが含まれる | スキップして処理継続 |

### リトライ仕様

リトライは行わない。

## トランザクション仕様

トランザクション管理なし。

## パフォーマンス要件

- シェル起動時に実行されるため、高速に完了すること
- 通常数ミリ秒で完了

## セキュリティ考慮事項

- 本機能はセキュリティ監査機能
- 検出した脆弱性に対する自動修正は行わない（ユーザーの明示的な操作が必要）

## 備考

- compauditはzshの標準ビルトイン関数
- Oh My Zshではlib/compfix.zshのhandle_completion_insecuritiesから呼び出される
- ZSH_DISABLE_COMPFIX=true設定でチェックをスキップ可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compfix.zsh | `lib/compfix.zsh` | 17-18行目: compauditの呼び出し方法 |

**読解のコツ**: compauditはzshビルトインのため、ソースコードはzsh本体にある。Oh My Zshではその出力を解析して使用している。

**主要処理フロー**:
- **17行目**: `compaudit 2>/dev/null` - 標準エラー出力を抑制してcompauditを実行
- **18行目**: 結果を配列に格納（改行分割、重複排除）

#### Step 2: compauditの出力形式を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compfix.zsh | `lib/compfix.zsh` | 6-16行目: compaudit出力形式の説明コメント |

**出力形式**:
```
There are insecure directories:    <- stderr (キャプチャされない)
/usr/share/zsh/site-functions      <- stdout
/usr/share/zsh/5.0.6/functions     <- stdout
/usr/share/zsh                     <- stdout
/usr/share/zsh/5.0.6               <- stdout
```

#### Step 3: Oh My Zshでの使用方法を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 初期化時のcompfix呼び出し部分 |

### プログラム呼び出し階層図

```
oh-my-zsh.sh (初期化)
    │
    └─ handle_completion_insecurities()
           │
           └─ compaudit (zshビルトイン)  ← 本機能
                  │
                  ├─ fpath走査
                  ├─ stat (パーミッションチェック)
                  └─ 結果出力
```

### データフロー図

```
[入力]                    [処理]                        [出力]

$fpath配列 ──────────────▶ compaudit ───────────────────▶ stdout
                               │                         (ディレクトリリスト)
ファイルシステム ────────────▶ │
(パーミッション/所有者)        └─────────────────────────▶ stderr
                                                         (ヘッダーメッセージ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compfix.zsh | `lib/compfix.zsh` | ソース | compauditの呼び出し元 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | 初期化時にcompfixを呼び出す |
| (zsh builtin) | - | ビルトイン | compaudit関数本体（zsh標準） |
