# 機能設計書 86-handle_completion_insecurities

## 概要

本ドキュメントは、zsh補完ファイルのセキュリティ問題を検出し、ユーザーに警告する`handle_completion_insecurities`関数の機能設計について記述する。

### 本機能の処理概要

zshの補完機能で使用されるディレクトリのパーミッションを監査し、セキュリティ上問題のあるディレクトリ（グループまたはその他のユーザーに書き込み権限がある）を検出してユーザーに警告する機能である。

**業務上の目的・背景**：zshの補完スクリプトはシェル起動時に自動的に実行されるため、悪意あるスクリプトが補完ディレクトリに配置されると、任意のコードが実行される可能性がある。特に、他のユーザーが書き込み可能なディレクトリは攻撃のベクトルとなりうるため、Oh My Zshはこれらのセキュリティリスクを検出し、ユーザーに修正を促す必要がある。

**機能の利用シーン**：Oh My Zsh初期化時（oh-my-zsh.sh読み込み時）にcompaudit関数を呼び出し、安全でないディレクトリが検出された場合に本関数が呼び出される。ユーザーにセキュリティリスクを通知し、修正方法を案内する。

**主要な処理内容**：
1. compaudit関数を呼び出してセキュリティ監査を実行
2. 安全でないディレクトリのリストを取得
3. 検出されたディレクトリの所有者とパーミッションを表示
4. 修正方法の案内メッセージを出力
5. セキュリティ警告をスキップする方法を案内

**関連システム・外部連携**：zshビルトインのcompaudit関数を使用する。

**権限による制御**：特になし。ただし、パーミッション修正にはディレクトリの所有権またはroot権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面関連なし（関数） |

## 機能種別

セキュリティ監査 / 警告表示

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- compaudit関数の出力：安全でないディレクトリのリスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準出力 | 文字列 | 警告メッセージ、ディレクトリ情報、修正手順 |

### 出力先

- 標準出力：警告メッセージ

## 処理フロー

### 処理シーケンス

```
1. compaudit実行
   └─ 標準エラー出力を抑制して実行
2. 結果の解析
   └─ 出力を配列に格納
3. 空チェック
   └─ 安全でないディレクトリがなければ終了
4. 警告メッセージ表示
   └─ "[oh-my-zsh] Insecure completion-dependent directories detected:"
5. ディレクトリ詳細表示
   └─ ls -ldで所有者・パーミッション表示
6. 修正手順の案内
   └─ chmod g-w,o-w の実行方法を説明
7. スキップ方法の案内
   └─ ZSH_DISABLE_COMPFIX変数の設定方法を説明
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[compaudit実行]
    B --> C{安全でないディレクトリあり?}
    C -->|No| D[終了]
    C -->|Yes| E[警告メッセージ表示]
    E --> F[ls -ld でディレクトリ詳細表示]
    F --> G[修正手順の案内表示]
    G --> H[スキップ方法の案内表示]
    H --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-001 | 補完停止 | セキュリティリスクのあるディレクトリからは補完を読み込まない | 安全でないディレクトリが検出された場合 |
| BR-86-002 | 警告スキップ | ZSH_DISABLE_COMPFIX=true設定で警告をスキップ可能 | ユーザーが明示的に設定した場合 |
| BR-86-003 | 重複排除 | 検出されたディレクトリリストは重複を排除 | 常時（-aUフラグ使用） |

### 計算ロジック

特になし。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | compaudit失敗 | compauditが利用不可 | 警告なしで処理継続 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

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

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

- 本機能自体がセキュリティ機能であり、補完ディレクトリの脆弱性を検出
- グループ/その他書き込み可能なディレクトリはセキュリティリスク
- root所有またはユーザー所有でない補完ディレクトリは危険

## 備考

- compauditはzshビルトイン関数
- ZSH_DISABLE_COMPFIX環境変数でスキップ可能

---

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

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

### 推奨読解順序

#### Step 1: 関数全体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compfix.zsh | `lib/compfix.zsh` | 1-45行目: 関数全体の構造 |

**読解のコツ**: zsh固有の配列構文（`${(f@):-"..."}`）に注意。fは改行分割、@は各要素を個別に展開、Uは重複排除。

**主要処理フロー**:
1. **1-4行目**: 関数の目的を説明するコメント
2. **5行目**: 関数定義開始
3. **17-18行目**: compauditを実行し、結果を配列に格納
4. **21行目**: 空チェック（安全でないディレクトリがなければreturn）
5. **24-25行目**: 警告メッセージとls -ldによるディレクトリ詳細表示
6. **27-43行目**: 修正手順とスキップ方法のヒアドキュメント表示

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

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

**compauditの出力例**:
```
There are insecure directories:
/usr/share/zsh/site-functions
/usr/share/zsh/5.0.6/functions
/usr/share/zsh
/usr/share/zsh/5.0.6
```

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

```
oh-my-zsh.sh (初期化)
    │
    └─ handle_completion_insecurities()  ← 本機能
           │
           ├─ compaudit (zshビルトイン)
           │
           └─ ls -ld (外部コマンド)
```

### データフロー図

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

compaudit出力 ───────────▶ handle_completion_insecurities() ──▶ 警告メッセージ
(安全でないディレクトリ)           │
                                   └─▶ ディレクトリ詳細
                                       (ls -ld出力)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compfix.zsh | `lib/compfix.zsh` | ソース | 補完セキュリティ関連関数 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zsh初期化（本関数を呼び出す） |
