# 画面設計書 96-インスタンス監査

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンス監査機能（Get-DbaInstanceAudit、Get-DbaInstanceAuditSpecification、Copy-DbaInstanceAudit、Copy-DbaInstanceAuditSpecification）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Server監査（Audit）は、セキュリティイベントのログ記録とコンプライアンス要件の遵守に不可欠な機能です。本機能群は、インスタンスレベルの監査オブジェクトと監査仕様の取得、およびインスタンス間のコピーを提供します。監査オブジェクトは監査イベントの保存先（ファイル、アプリケーションログ、セキュリティログ）を定義し、監査仕様はどのイベントを捕捉するかを定義します。これにより、監査構成の確認、コンプライアンスレポート作成、サーバー移行時の監査設定移行が効率的に行えます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaInstanceAudit -SqlInstance <インスタンス名>`
- `Get-DbaInstanceAuditSpecification -SqlInstance <インスタンス名>`
- `Copy-DbaInstanceAudit -Source <ソース> -Destination <宛先>`
- `Copy-DbaInstanceAuditSpecification -Source <ソース> -Destination <宛先>`

**主要な操作・処理内容**：
1. **監査オブジェクト取得**：インスタンスレベルの監査定義（ファイルパス、サイズ制限、ロールオーバー設定等）を取得
2. **監査仕様取得**：サーバーレベルの監査仕様（関連する監査名、有効状態等）を取得
3. **監査コピー**：ソースインスタンスから宛先インスタンスへ監査オブジェクトをコピー
4. **監査仕様コピー**：サーバー監査仕様を他のインスタンスへコピー

**画面遷移**：
本機能は監査設定の確認・移行の起点として使用される。取得した監査情報はコンプライアンスレポート、比較分析、設定エクスポートなどに活用される。

**権限による表示制御**：
- 監査情報の取得にはSQL Serverインスタンスへの接続権限が必要
- 監査オブジェクトの作成・削除にはsysadmin権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 335 | Get-DbaInstanceAudit | 主機能 | インスタンス監査の取得 |
| 360 | Copy-DbaInstanceAudit | 補助機能 | インスタンス監査のコピー |
| 336 | Get-DbaInstanceAuditSpecification | 補助機能 | インスタンス監査仕様の取得 |
| 361 | Copy-DbaInstanceAuditSpecification | 補助機能 | インスタンス監査仕様のコピー |

## 画面種別

CLI（コマンドラインインターフェース）/ セキュリティ・監査

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaInstanceAudit`
- `Get-DbaInstanceAuditSpecification`
- `Copy-DbaInstanceAudit`
- `Copy-DbaInstanceAuditSpecification`

## 入出力項目

### Get-DbaInstanceAudit パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| Audit | string[] | いいえ | 取得する監査名（フィルター用） |
| ExcludeAudit | string[] | いいえ | 除外する監査名 |
| EnableException | switch | いいえ | 例外を有効化 |

### Get-DbaInstanceAuditSpecification パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| EnableException | switch | いいえ | 例外を有効化 |

### Copy-DbaInstanceAudit パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Source | DbaInstanceParameter | はい | コピー元のSQL Serverインスタンス |
| SourceSqlCredential | PSCredential | いいえ | ソース接続用の資格情報 |
| Destination | DbaInstanceParameter[] | はい | コピー先のSQL Serverインスタンス |
| DestinationSqlCredential | PSCredential | いいえ | 宛先接続用の資格情報 |
| Audit | object[] | いいえ | コピーする監査名 |
| ExcludeAudit | object[] | いいえ | 除外する監査名 |
| Path | string | いいえ | 宛先での監査ファイルパス |
| Force | switch | いいえ | 既存監査の上書き、ディレクトリ作成 |
| WhatIf | switch | いいえ | 実行内容のプレビュー |
| Confirm | switch | いいえ | 確認プロンプト |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### Get-DbaInstanceAudit 出力（Microsoft.SqlServer.Management.Smo.Audit）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | 監査オブジェクト名 |
| IsEnabled | bool | 監査が有効かどうか |
| OnFailure | enum | 監査イベント書き込み失敗時のアクション（Continue/Shutdown/FailOperation） |
| MaximumFiles | int | 保持する最大監査ファイル数 |
| MaximumFileSize | int | 各監査ファイルの最大サイズ |
| MaximumFileSizeUnit | enum | サイズ単位（Megabyte/Gigabyte/Terabyte） |
| MaximumRolloverFiles | int | ロールオーバー前の最大ファイル数 |
| QueueDelay | int | 監査ターゲットへのフラッシュ遅延（ミリ秒） |
| ReserveDiskSpace | bool | ディスク領域を事前確保するか |
| FullName | string | 監査ファイルの完全ローカルパス |
| RemoteFullName | string | 監査ファイルのリモートUNCパス |

### Get-DbaInstanceAuditSpecification 出力（Microsoft.SqlServer.Management.Smo.ServerAuditSpecification）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| ID | int | 監査仕様の一意識別子 |
| Name | string | 監査仕様名 |
| AuditName | string | 関連する監査の名前 |
| Enabled | bool | 監査仕様が有効かどうか |
| CreateDate | DateTime | 作成日時 |
| DateLastModified | DateTime | 最終更新日時 |
| Guid | Guid | グローバル一意識別子 |

### Copy-DbaInstanceAudit 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DateTime | DbaDateTime | コピー操作の実行日時 |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | コピーされた監査名 |
| Type | string | オブジェクトタイプ（常に "Server Audit"） |
| Status | string | 結果ステータス（Successful/Skipped/Failed） |
| Notes | string | 追加情報（スキップ理由、エラー詳細等） |

## イベント仕様

### 1-監査取得処理（Get-DbaInstanceAudit）

1. Connect-DbaInstanceでSQL Server接続（MinimumVersion 10）
2. $server.Auditsから監査コレクションを取得
3. Auditパラメータでフィルタリング（指定時）
4. ExcludeAuditパラメータで除外（指定時）
5. 各監査にFullName（ローカルパス）とRemoteFullName（UNCパス）を計算・追加
6. メタ情報（ComputerName, InstanceName, SqlInstance）を追加して出力

### 2-監査仕様取得処理（Get-DbaInstanceAuditSpecification）

1. Connect-DbaInstanceでSQL Server接続（MinimumVersion 10）
2. $server.ServerAuditSpecificationsから監査仕様コレクションを取得
3. メタ情報（ComputerName, InstanceName, SqlInstance）を追加して出力

### 3-監査コピー処理（Copy-DbaInstanceAudit）

1. ソースインスタンスに接続し、監査コレクションを取得
2. 各宛先インスタンスに対して：
   - 宛先に同名の監査が存在するかチェック
   - 存在する場合：-Force指定なしでスキップ、-Force指定で削除後再作成
   - ファイルパスが宛先に存在するかチェック
   - 存在しない場合：-Force指定でディレクトリ作成、なしでスキップ
   - 監査オブジェクトのScript()メソッドでT-SQLを生成し実行

## データベース更新仕様

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| 監査取得 | sys.server_audits | SELECT | 監査定義の読み取り |
| 監査仕様取得 | sys.server_audit_specifications | SELECT | 監査仕様の読み取り |
| 監査コピー（作成） | sys.server_audits | INSERT | 監査オブジェクトの作成 |
| 監査コピー（削除） | sys.server_audits | DELETE | 既存監査の削除（Force時） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | エラー | Failure（接続エラー時） |
| MSG002 | 情報 | Server audit {auditName} exists at destination. Use -Force to drop and migrate. |
| MSG003 | 情報 | Dropping server audit {auditName}. |
| MSG004 | 情報 | Issue dropping audit from {destinstance} |
| MSG005 | 警告 | {FilePath} does not exist on {destinstance}. Skipping {auditName}. Specify -Force to create the directory. |
| MSG006 | 情報 | Force specified. Creating directory. |
| MSG007 | 警告 | Couldn't create directory {FilePath}. Using default data directory. |
| MSG008 | 情報 | File path {FilePath} exists on {destinstance}. |
| MSG009 | 情報 | Copying server audit {auditName}. |
| MSG010 | エラー | Issue creating audit on {destinstance} |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、処理を継続（Continue） |
| 監査削除失敗 | Status = "Failed"として出力し、処理を継続 |
| ディレクトリ作成失敗 | デフォルトデータディレクトリにフォールバック |
| 監査作成失敗 | Status = "Failed"、Notesにエラー詳細を出力 |

## 備考

- SQL Server 2008以降が必要（MinimumVersion 10）
- 監査ファイルパスはローカルパスとUNCパスの両方で参照可能
- Copy-DbaInstanceAuditは関連する監査仕様を自動的にはコピーしない（別途Copy-DbaInstanceAuditSpecificationが必要）
- -Force使用時は既存監査の削除と不足ディレクトリの作成が行われる

---

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

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

### 推奨読解順序

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

SMO監査オブジェクトと監査仕様オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | 44-71行目の.OUTPUTSセクション |
| 1-2 | Get-DbaInstanceAuditSpecification.ps1 | `public/Get-DbaInstanceAuditSpecification.ps1` | 36-54行目の.OUTPUTSセクション |

**読解のコツ**: Audit（監査オブジェクト）とServerAuditSpecification（監査仕様）の違いを理解する。

#### Step 2: 監査取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | 84-91行目のparamブロック |
| 2-2 | Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | 93-126行目のprocessブロック |

**主要処理フロー**:
- **96行目**: MinimumVersion 10でSQL Server接続
- **101行目**: $server.Auditsで監査コレクション取得
- **103-108行目**: Audit/ExcludeAuditでフィルタリング
- **110-115行目**: FullName（ローカル）とRemoteFullName（UNC）の計算
- **117-121行目**: メタ情報追加

#### Step 3: 監査仕様取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstanceAuditSpecification.ps1 | `public/Get-DbaInstanceAuditSpecification.ps1` | 74-90行目のprocessブロック |

**主要処理フロー**:
- **77行目**: MinimumVersion 10でSQL Server接続
- **82行目**: $server.ServerAuditSpecificationsで監査仕様コレクション取得
- **83-87行目**: メタ情報追加と出力

#### Step 4: 監査コピーロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | 125-135行目のbeginブロック |
| 4-2 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | 167-196行目の既存監査チェックと削除 |
| 4-3 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | 198-228行目のパス存在チェックとディレクトリ作成 |
| 4-4 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | 229-243行目の監査作成

**主要処理フロー**:
- **167行目**: 宛先に同名監査が存在するかチェック
- **175-195行目**: Force時は既存監査を削除
- **198行目**: Test-DbaPathでファイルパス存在チェック
- **233-234行目**: Script()メソッドでT-SQL生成し実行

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

```
Get-DbaInstanceAudit
    │
    ├─ Connect-DbaInstance (MinimumVersion 10)
    │      └─ SQL Server接続確立
    │
    └─ $server.Audits
           ├─ フィルタリング（Audit/ExcludeAudit）
           ├─ FullName/RemoteFullName計算
           ├─ Add-Member（メタ情報追加）
           └─ Select-DefaultView（出力）

Get-DbaInstanceAuditSpecification
    │
    ├─ Connect-DbaInstance (MinimumVersion 10)
    │      └─ SQL Server接続確立
    │
    └─ $server.ServerAuditSpecifications
           ├─ Add-Member（メタ情報追加）
           └─ Select-DefaultView（出力）

Copy-DbaInstanceAudit
    │
    ├─ Connect-DbaInstance (Source)
    │      └─ ソース接続確立
    │
    └─ foreach ($destinstance in $Destination)
           │
           ├─ Connect-DbaInstance (Destination)
           │      └─ 宛先接続確立
           │
           ├─ 既存監査チェック
           │      ├─ Force時：Drop後再作成
           │      └─ 非Force時：スキップ
           │
           ├─ Test-DbaPath（ファイルパス存在チェック）
           │      ├─ Force時：New-DbaDirectory
           │      └─ 非Force時：スキップ
           │
           └─ $currentAudit.Script() → $destServer.Query()
                  └─ 監査作成
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │ $server.Audits│
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ フィルタリング │
                          └───────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
   FilePath取得              FullName計算           RemoteFullName計算
   (TrimEnd)              (directory\filename)    (\\computer\path)
        │                         │                         │
        └─────────────────────────┼─────────────────────────┘
                                  ▼
                          ┌───────────────┐
                          │ Add-Member    │
                          │ (メタ情報追加) │
                          └───────────────┘
                                  │
                                  ▼
                          Select-DefaultView
                                  │
                                  ▼
                      [Microsoft.SqlServer.Management.Smo.Audit]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceAudit.ps1 | `public/Get-DbaInstanceAudit.ps1` | ソース | インスタンス監査取得 |
| Get-DbaInstanceAuditSpecification.ps1 | `public/Get-DbaInstanceAuditSpecification.ps1` | ソース | インスタンス監査仕様取得 |
| Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | ソース | インスタンス監査コピー |
| Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | ソース | インスタンス監査仕様コピー |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認 |
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成 |
