# 画面設計書 71-権限取得

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「権限取得」機能の設計書です。SQL Server インスタンスおよびデータベースに設定された権限情報を包括的に取得・監査するためのコマンド群について記述します。

### 本画面の処理概要

本機能は、SQL Server のセキュリティ監査およびコンプライアンスレポート作成のために、サーバーレベルおよびデータベースレベルの権限情報を詳細に取得する機能を提供します。

**業務上の目的・背景**：SQL Server環境のセキュリティ監査、コンプライアンス要件への対応、アクセス問題のトラブルシューティング、および環境間の権限移行計画において、誰がどのオブジェクトにどのような権限を持っているかを正確に把握することが重要です。本機能は、明示的な権限（GRANT/DENY/REVOKE）と暗黙的な権限（固定ロールから継承される権限、dboユーザー、スキーマ所有者の権限）の両方を取得し、完全なセキュリティ可視化を実現します。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaPermission` または `Get-DbaUserPermission` コマンドを直接実行します。パイプライン入力としてSQL Serverインスタンス情報を渡すことも可能です。

**主要な操作・処理内容**：
1. `Get-DbaPermission`: sys.server_permissions および sys.database_permissions からの明示的権限の取得、固定ロールからの暗黙的権限の取得
2. `Get-DbaUserPermission`: DISA STIG方式に基づく包括的セキュリティ監査の実行、サーバーログイン・データベースユーザー・ロールメンバーシップ・オブジェクトレベル権限の詳細取得

**画面遷移**：本機能はCLIコマンドのため画面遷移は存在しません。ただし、`Connect-DbaInstance` で確立した接続を利用し、取得した権限情報を他のコマンド（`Export-Csv`、`Out-GridView`等）にパイプラインで渡すことが可能です。

**権限による表示制御**：実行ユーザーの権限に応じて取得可能な権限情報が制限されます。sysadmin権限を持つユーザーはすべての権限情報を取得できますが、制限されたユーザーは自身がアクセス可能なオブジェクトの権限のみ取得できます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 561 | Get-DbaPermission | 主機能 | SQL Server権限の取得 |
| 564 | Get-DbaUserPermission | 補助機能 | ユーザー権限の監査 |

## 画面種別

一覧（権限情報の一覧取得）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaPermission`
- `Get-DbaUserPermission`

## 入出力項目

### Get-DbaPermission 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 分析対象データベース |
| ExcludeDatabase | object[] | No | 除外データベース |
| IncludeServerLevel | switch | No | サーバーレベル権限を含める |
| ExcludeSystemObjects | switch | No | システムオブジェクトを除外 |
| EnableException | switch | No | 例外を有効化 |

### Get-DbaUserPermission 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 監査対象データベース |
| ExcludeDatabase | object[] | No | 除外データベース |
| ExcludeSystemDatabase | switch | No | システムデータベースを除外 |
| IncludePublicGuest | switch | No | public/guest権限を含める |
| IncludeSystemObjects | switch | No | システムオブジェクトを含める |
| ExcludeSecurables | switch | No | オブジェクトレベル権限を除外 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaPermission 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名（サーバーレベル権限の場合は空） |
| PermState | string | 権限状態（GRANT/DENY/REVOKE） |
| PermissionName | string | 権限名（SELECT, CONNECT, EXECUTE等） |
| SecurableType | string | セキュリティ保護可能なオブジェクトの種類 |
| Securable | string | セキュリティ保護可能なオブジェクトの名前 |
| Grantee | string | 権限を持つプリンシパル名 |
| GranteeType | string | プリンシパルの種類 |
| RevokeStatement | string | REVOKE用T-SQLステートメント |
| GrantStatement | string | GRANT用T-SQLステートメント |

### Get-DbaUserPermission 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Object | string | スコープ（SERVERまたはデータベース名） |
| Type | string | 監査行の種類 |
| Member | string | ログインまたはプリンシパル名 |
| RoleSecurableClass | string | ロール名またはセキュリティ保護可能なクラス |
| SchemaOwner | string | スキーマ/所有者名 |
| Securable | string | セキュリティ保護可能なオブジェクト名 |
| GranteeType | string | 被付与者の種類 |
| Grantee | string | 権限が付与されたプリンシパル名 |
| Permission | string | 権限名 |
| State | string | 権限状態（GRANT/DENY） |
| Grantor | string | 権限付与者 |
| GrantorType | string | 権限付与者の種類 |
| SourceView | string | データ取得元のSTIGビュー |

## イベント仕様

### 1-Get-DbaPermission実行

1. Connect-DbaInstance を使用してSQL Serverに接続（SQL Server 2005以上が必要）
2. IncludeServerLevel が指定された場合、sys.server_permissions とシステム関数を使用してサーバーレベル権限を取得
3. 指定されたデータベースに対して sys.database_permissions を使用してデータベースレベル権限を取得
4. 固定ロール、dboユーザー、db_ownerロールメンバー、スキーマ所有者からの暗黙的権限を追加取得
5. 結果をパイプラインに出力

### 2-Get-DbaUserPermission実行

1. Connect-DbaInstance を使用してSQL Serverに接続（SQL Server 2008以上が必要、Azure非対応）
2. tempdb に STIG スキーマと関連オブジェクト（ビュー、関数）を作成
3. サーバーログインとサーバーセキュリティ保護可能オブジェクトの権限を取得
4. 各データベースについて、STIG スキーマを再作成し、データベースロールメンバーとデータベースセキュリティ保護可能オブジェクトの権限を取得
5. tempdb から STIG スキーマを削除
6. 結果をパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaPermission実行 | sys.server_permissions | SELECT | サーバー権限情報の取得 |
| Get-DbaPermission実行 | sys.database_permissions | SELECT | データベース権限情報の取得 |
| Get-DbaPermission実行 | sys.server_principals | SELECT | サーバープリンシパル情報の取得 |
| Get-DbaPermission実行 | sys.database_principals | SELECT | データベースプリンシパル情報の取得 |
| Get-DbaUserPermission実行 | tempdb.STIG.* | SELECT | STIG監査用ビューからの取得 |
| Get-DbaUserPermission実行 | tempdb | CREATE/DROP | STIGスキーマの一時作成・削除 |

### テーブル別更新項目詳細

#### sys.server_permissions（読み取り専用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | state_desc, permission_name, class, major_id, grantee_principal_id | ExcludeSystemObjects指定時は major_id > 0 | サーバーレベル権限の取得 |

#### sys.database_permissions（読み取り専用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | state_desc, permission_name, class, major_id, grantee_principal_id | ExcludeSystemObjects指定時は major_id > 0 | データベースレベル権限の取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | 警告 | The database $db is not accessible. Skipping database. | データベースがアクセス不可の場合 |
| MSG-002 | エラー | Failure executing against $($db.Name) on $instance | データベースクエリ実行失敗時 |
| MSG-003 | エラー | Failed to create or use STIG schema on $instance | STIGスキーマ作成失敗時 |
| MSG-004 | 情報 | Processing $db on $instance | 各データベース処理開始時（Verbose） |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Function で処理を停止し、エラーメッセージを表示 |
| MinimumVersion | SQL Server 2005未満（Get-DbaPermission）または2008未満（Get-DbaUserPermission） | 接続時に自動検証、非対応バージョンはスキップ |
| AccessDenied | データベースへのアクセス権限不足 | 警告メッセージを表示し、該当データベースをスキップ |
| AzureUnsupported | Azure SQL Databaseへの接続（Get-DbaUserPermission） | サポート外のエラーを表示 |
| InterruptedExecution | Ctrl-Cによる中断（Get-DbaUserPermission） | STIGスキーマがtempdbに残存する可能性がある旨を警告 |

## 備考

- Get-DbaPermission は SQL Server 2005 以上をサポート
- Get-DbaUserPermission は SQL Server 2008 以上をサポート（Azure SQL Database 非対応）
- Get-DbaUserPermission を中断した場合、tempdb に STIG スキーマが残存する可能性があるため、手動でクリーンアップが必要
- 両コマンドとも、セキュリティ監査やコンプライアンスレポート作成に活用可能

---

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

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

### 推奨読解順序

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

まず、権限情報がどのような形式で返されるかを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPermission.ps1 | `public/Get-DbaPermission.ps1` | 出力オブジェクトのプロパティ定義（行66-88） |
| 1-2 | Get-DbaUserPermission.ps1 | `public/Get-DbaUserPermission.ps1` | PSCustomObjectの構造定義（行265-282、305-323） |

**読解のコツ**: .OUTPUTSセクションのドキュメントコメントを確認し、返されるオブジェクトの構造を把握します。

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

処理の起点となるパラメータ定義と初期化処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPermission.ps1 | `public/Get-DbaPermission.ps1` | param ブロック（行112-121）、begin ブロックでのSQL構築（行122-323） |
| 2-2 | Get-DbaUserPermission.ps1 | `public/Get-DbaUserPermission.ps1` | param ブロック（行107-119）、begin ブロックでのSQL定義（行121-225） |

**主要処理フロー**:
1. **行112-121（Get-DbaPermission）**: パラメータ定義（SqlInstance, Database, IncludeServerLevel等）
2. **行122-183（Get-DbaPermission）**: サーバーレベル権限取得用SQL文の構築
3. **行185-323（Get-DbaPermission）**: データベースレベル権限取得用SQL文の構築

#### Step 3: サーバー接続と権限取得処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPermission.ps1 | `public/Get-DbaPermission.ps1` | process ブロック（行326-365）での接続とクエリ実行 |
| 3-2 | Get-DbaUserPermission.ps1 | `public/Get-DbaUserPermission.ps1` | process ブロック（行228-336）でのSTIGスキーマ管理とクエリ実行 |

**主要処理フロー**:
- **行329（Get-DbaPermission）**: Connect-DbaInstance による接続（MinimumVersion 9 = SQL Server 2005）
- **行336（Get-DbaPermission）**: サーバーレベル権限クエリの実行
- **行359（Get-DbaPermission）**: データベースレベル権限クエリの実行

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

```
Get-DbaPermission
    |
    +-- Connect-DbaInstance (SQL Server 接続)
    |       +-- MinimumVersion 9 チェック
    |
    +-- server.Query() (サーバーレベル権限)
    |       +-- sys.server_permissions
    |       +-- sys.server_principals
    |       +-- sys.fn_builtin_permissions('SERVER')
    |
    +-- db.ExecuteWithResults() (データベースレベル権限)
            +-- sys.database_permissions
            +-- sys.database_principals
            +-- sys.fn_builtin_permissions('DATABASE')
            +-- sys.database_role_members
            +-- sys.databases
            +-- sys.schemas

Get-DbaUserPermission
    |
    +-- Connect-DbaInstance (SQL Server 接続)
    |       +-- MinimumVersion 10 チェック
    |       +-- AzureUnsupported フラグ
    |
    +-- Invoke-DbaQuery (STIGスキーマ削除)
    |       +-- tempdb.STIG.* オブジェクト削除
    |
    +-- Invoke-DbaQuery (STIGスキーマ作成)
    |       +-- bin/stig.sql ファイル読み込み
    |       +-- tempdb.STIG スキーマ作成
    |
    +-- Invoke-DbaQuery (サーバー権限取得)
    |       +-- tempdb.STIG.server_role_members
    |       +-- tempdb.STIG.server_permissions
    |
    +-- Invoke-DbaQuery (データベース権限取得)
            +-- tempdb.STIG.database_role_members
            +-- tempdb.STIG.database_permissions
```

### データフロー図

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

SqlInstance  ───+
                |
SqlCredential ──+──> Connect-DbaInstance ───> Server Object
                |
Database ───────+

Server Object ──+
                |
                +──> sys.server_permissions ──+
                |    sys.database_permissions |
                |    sys.fn_builtin_permissions|──> DataRow[]
                |    sys.database_role_members |    (権限情報)
                |    sys.schemas              |
                |                              |
                +──> STIG Schema (tempdb) ────+

DataRow[] ──────────> Pipeline Output ──────> Format-Table
                                              Export-Csv
                                              Out-GridView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPermission.ps1 | `public/Get-DbaPermission.ps1` | ソース | 主要な権限取得コマンド |
| Get-DbaUserPermission.ps1 | `public/Get-DbaUserPermission.ps1` | ソース | STIG方式の包括的監査コマンド |
| stig.sql | `bin/stig.sql` | SQL | STIG監査用スキーマ・ビュー定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | SQLクエリ実行ユーティリティ |
