# 機能設計書 648-Read-DbaAuditFile

## 概要

本ドキュメントは、SQL Server監査ファイル（.sqlaudit）を解析して構造化されたイベントデータに変換するdbatools PowerShellコマンド「Read-DbaAuditFile」の機能設計書です。

### 本機能の処理概要

Read-DbaAuditFileは、SQL Server Audit機能によって作成された.sqlauditファイルを読み込み、バイナリデータを人間が読める形式のPowerShellオブジェクトに変換するコマンドです。

**業務上の目的・背景**：SQL Server Auditは、データベースアクセスやセキュリティイベントを.sqlaudit形式のバイナリファイルに記録します。このプロプライエタリ形式は直接読み取ることができないため、セキュリティ調査、コンプライアンスレポート、アクセスパターン分析のためにはデータを変換する必要があります。本機能により、監査データを簡単にフィルタリング、エクスポート、分析できます。

**機能の利用シーン**：
- セキュリティインシデント調査
- コンプライアンス監査レポートの作成
- データベースアクセスパターンの分析
- 不正アクセスの検出
- 定期的なセキュリティレビュー

**主要な処理内容**：
1. 入力パスの解決（文字列、FileInfo、Auditオブジェクト対応）
2. ワイルドカード展開による関連監査ファイルの収集
3. Read-XEventによる監査ファイルの読み込み
4. フィールドとアクションの抽出・構造化
5. PSCustomObjectとしての結果出力

**関連システム・外部連携**：
- SQL Server監査ファイル（.sqlaudit）
- ファイルシステム（ローカル/UNC共有）

**権限による制御**：監査ファイルへのファイルシステム読み取り権限が必要です。リモートファイルの場合は管理共有へのアクセス権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI専用 | 主機能 | コマンドライン実行のみ |

## 機能種別

データ取得・変換 / セキュリティ分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | object[] | Yes | 監査ファイルパス（文字列、FileInfo、Auditオブジェクト） | パイプライン対応 |
| Raw | switch | No | 生の列挙オブジェクトを返す | - |
| EnableException | switch | No | エラー時に例外をスロー | - |

### 入力データソース

- パイプライン入力:
  - 文字列パス
  - Get-ChildItem からの FileInfo オブジェクト
  - Get-DbaInstanceAudit からの Audit オブジェクト
- 直接パラメータ指定

## 出力仕様

### 出力データ（Raw指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | System.Object | Read-XEventからの生の列挙オブジェクト |

### 出力データ（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | 監査イベント名 |
| timestamp | DateTime | イベント発生日時 |
| (Fields.*) | various | 監査ファイルに含まれるフィールド（動的） |
| (Actions.*) | various | 監査ファイルに含まれるアクション（動的） |

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 入力パスの解決
   ├─ 文字列: そのまま使用
   ├─ FileInfo: FullName を使用
   └─ Auditオブジェクト: FullName または RemoteFullName を使用

2. ワイルドカード展開
   └─ ベースファイル名から *.sqlaudit パターンで関連ファイルを取得

3. 各ファイルのアクセス確認
   └─ Test-Path でアクセス可能性を確認

4. Read-XEvent でファイル読み込み
   └─ 各監査ファイルのバイナリデータを読み込み

5. Raw指定時
   └─ 生のenumオブジェクトを返して終了

6. カラム情報の収集
   ├─ Fields.Name からフィールド名を収集
   └─ Actions.Name からアクション名を収集（サフィックスのみ抽出）

7. 各イベントをPSCustomObjectに変換
   ├─ name, timestamp を設定
   ├─ Fields の値をプロパティに追加
   └─ Actions の値をプロパティに追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パスループ]
    B --> C{パスの型?}
    C -->|String| D[そのまま使用]
    C -->|FileInfo| E[FullName使用]
    C -->|Audit| F{IsLocalHost?}
    F -->|Yes| G[FullName使用]
    F -->|No| H[RemoteFullName使用]
    D --> I[ワイルドカード展開]
    E --> I
    G --> I
    H --> I
    I --> J[ファイルループ]
    J --> K{アクセス可能?}
    K -->|No| L[Stop-Function]
    K -->|Yes| M[Read-XEvent]
    L --> J
    M --> N{Raw指定?}
    N -->|Yes| O[enum返却]
    N -->|No| P[カラム収集]
    O --> Q[終了]
    P --> R[イベントループ]
    R --> S[PSCustomObject生成]
    S --> T[プロパティ設定]
    T --> U[オブジェクト出力]
    U --> R
    R --> B
    B --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ワイルドカード展開 | ベースファイル名から関連する全*.sqlauditファイルを収集 | 常時 |
| BR-002 | アクション名サフィックス | Actions.Nameの最後の部分（.区切り）のみをプロパティ名として使用 | 常時 |
| BR-003 | ユニークカラム | Fields.NameとActions.Nameから重複を除去してカラムリストを構築 | 常時 |
| BR-004 | リモートファイルアクセス | Auditオブジェクト入力時、非ローカルはRemoteFullNameを使用 | Auditオブジェクト入力時 |

### 計算ロジック

- アクション名抽出: ($action -Split '\.')[-1]

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

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

本機能はデータベースに対する操作を行いません。ファイルシステムからの読み取りのみを実行します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | UnsupportedType | 入力がString/FileInfo/Audit以外 | サポートされる型を使用 |
| - | NoFullName | AuditオブジェクトにFullNameがない | ファイルパスが設定された監査を使用 |
| - | AccessDenied | ファイルへのアクセス権限がない | 適切な権限を持つアカウントで実行 |

### リトライ仕様

リトライなし（ファイル単位でContinueしてスキップ）

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

該当なし（読み取り専用操作）

## パフォーマンス要件

- ファイルサイズとイベント数に依存
- 大量の監査データの場合はフィルタリングを推奨

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

- 監査ファイルへの読み取り権限が必要
- 監査データは機密情報を含む可能性があるため、適切なアクセス制御が必要
- リモートファイルアクセス時は管理共有（C$等）への権限が必要

## 備考

- Read-XEvent内部関数を使用してバイナリ解析を実行
- CSVエクスポート時に全フィールドが出力されるよう、カラム情報を最初に収集

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

出力オブジェクトの動的な構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | L132-147の PSCustomObject 生成 |

**読解のコツ**: 出力プロパティはname, timestamp以外は監査ファイルの内容に依存して動的に決定されます。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | processブロック全体の流れ |

**主要処理フロー**:
1. **74-75行目**: processブロック開始、ファイルループ
2. **78行目**: 初期カラム設定（name, timestamp）
3. **80-102行目**: 入力パスの型判定と解決
4. **105行目**: ワイルドカード展開によるファイル一覧取得
5. **107-115行目**: アクセス確認とRead-XEvent実行
6. **117-119行目**: Raw指定時の早期リターン
7. **121-129行目**: カラム情報収集（Fields, Actions）
8. **132-147行目**: PSCustomObject生成ループ

#### Step 3: パス解決ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | L80-102のパス解決 |

**主要処理フロー**:
- **80-81行目**: 文字列入力の処理
- **82-83行目**: FileInfo入力の処理
- **84-101行目**: Auditオブジェクト入力の処理（ローカル/リモート分岐）

#### Step 4: カラム収集とオブジェクト生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | L121-147のオブジェクト生成 |

**主要処理フロー**:
- **121行目**: Fields.Nameからユニークなカラム名を取得
- **123-126行目**: Actions.Nameからサフィックスのみを抽出
- **128-129行目**: カラムリストの統合（重複除去）
- **133-146行目**: 各イベントのPSCustomObject生成

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

```
Read-DbaAuditFile
    │
    ├─ パス解決
    │      ├─ String → そのまま
    │      ├─ FileInfo → FullName
    │      └─ Audit → FullName/RemoteFullName
    │
    ├─ Get-ChildItem（ワイルドカード展開）
    │
    ├─ Test-Path（アクセス確認）
    │
    ├─ Read-XEvent（内部関数）
    │      └─ .sqlauditバイナリ解析
    │
    └─ PSCustomObject生成
           ├─ name, timestamp設定
           ├─ Fields値の追加
           └─ Actions値の追加
```

### データフロー図

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

Path ─────────────────┐
(String/FileInfo/      │
 Auditオブジェクト)     │
                       │
                       ├──▶ パス解決 ─────────────┐
                       │                          │
Raw ───────────────────┘                          ▼
                                           ワイルドカード展開
                                                  │
                                                  ▼
                                           Read-XEvent
                                                  │
                                 ┌────────────────┴────────────────┐
                                 ▼                                  ▼
                            [Raw=true]                         [Raw=false]
                            生enumオブジェクト                 PSCustomObject
                                                              (name,
                                                               timestamp,
                                                               Fields.*,
                                                               Actions.*)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaAuditFile.ps1 | `public/Read-DbaAuditFile.ps1` | ソース | メインコマンド実装 |
| Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | ソース | インスタンス監査情報取得（パイプライン入力元） |
| Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | ソース | 類似機能（拡張イベントファイル読み込み） |
