# 画面設計書 58-データマスキング

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータマスキング（Data Masking）機能の設計仕様を記載したものです。JSON構成ファイルに基づいて本番データをランダム化された値に置き換え、開発・テスト環境で安全に使用できるデータセットを作成する機能を提供します。

### 本画面の処理概要

本機能は、SQL Serverデータベース内の機密データをランダム化された値に置き換えるPowerShellコマンドを提供します。Bogusライブラリを使用して、名前、住所、電話番号などのリアルなフェイクデータを生成し、元のデータの形式やデータ型を維持しながら機密情報を保護します。

**業務上の目的・背景**：本番環境のデータベースには顧客情報、個人情報、機密ビジネスデータが含まれており、開発やテスト環境でそのまま使用することはセキュリティリスクとなります。データマスキングにより、本番データの構造と特性を維持しながら、実際の機密情報を安全なフェイクデータに置き換えることができます。GDPR、HIPAA、PCI DSSなどのコンプライアンス要件への対応にも有用です。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbDataMasking` - データマスキングの実行
- `New-DbaDbMaskingConfig` - マスキング構成ファイルの生成

**主要な操作・処理内容**：
1. JSON構成ファイルの読み込みと検証
2. 対象テーブルとカラムの特定
3. 一時的なインデックスと識別列の作成（パフォーマンス最適化）
4. 行ごとのランダム値生成とUPDATE実行
5. ユニーク制約の処理
6. 決定論的マスキング（同じ値を常に同じマスク値に変換）
7. マスキング結果の出力

**画面遷移**：本機能はCLIコマンドであり、New-DbaDbMaskingConfigで生成した構成ファイルをパイプライン入力として受け取ることができます。

**権限による表示制御**：データマスキング操作には対象テーブルへのSELECT、UPDATE権限、およびALTER TABLE権限（一時インデックス作成時）が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 168 | Invoke-DbaDbDataMasking | 主機能 | データマスキングの実行 |
| 192 | New-DbaDbMaskingConfig | 補助機能 | マスキング構成ファイルの生成 |

## 画面種別

実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Invoke-DbaDbDataMasking`

## 入出力項目

### Invoke-DbaDbDataMasking パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | string[] | 対象データベース名 |
| FilePath | Yes | object | JSON構成ファイルパス（パイプライン入力対応） |
| Locale | No | string | フェイクデータのロケール（デフォルト: en） |
| CharacterString | No | string | ランダム文字列に使用する文字セット |
| Table | No | string[] | 対象テーブル（ワイルドカード対応） |
| Column | No | string[] | 対象カラム（ワイルドカード対応） |
| ExcludeTable | No | string[] | 除外テーブル |
| ExcludeColumn | No | string[] | 除外カラム |
| MaxValue | No | int | 生成文字列の最大長 |
| ModulusFactor | No | int | NULL生成頻度（デフォルト: 10） |
| ExactLength | No | switch | 元データと同じ長さの値を生成 |
| CommandTimeout | No | int | SQLコマンドタイムアウト（デフォルト: 300秒） |
| BatchSize | No | int | バッチサイズ（デフォルト: 1000行） |
| Retry | No | int | ユニーク値生成のリトライ回数（デフォルト: 1000） |
| DictionaryFilePath | No | string[] | 決定論的マスキング用辞書ファイル |
| DictionaryExportPath | No | string | 辞書エクスポートパス |
| Force | No | switch | 確認プロンプトをスキップ |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Invoke-DbaDbDataMasking 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| Columns | array | マスキングされたカラム名 |
| Rows | int | マスキングされた行数 |
| Elapsed | prettytimespan | 処理時間 |
| Status | string | ステータス（Successful/Failed） |

## イベント仕様

### 1-データマスキング実行

1. JSON構成ファイルの読み込みと検証（Test-DbaDbDataMaskingConfig）
2. サポートされているデータ型とマスキングタイプの検証
3. SQL Server 2005以上の確認
4. tempdbに決定論的値テーブルの作成
5. 辞書ファイルのインポート（指定時）
6. 各テーブルに対するマスキング処理の実行

### 2-テーブルごとのマスキング処理

1. テーブルの存在確認
2. ID列の確認、存在しない場合は一時ID列の追加
3. マスキングインデックスの作成（パフォーマンス最適化）
4. データの取得（FilterQuery対応）
5. ユニークインデックス処理（HasUniqueIndex時）
6. 行ごとの値生成とUPDATE文の構築
7. バッチ単位でのUPDATE実行
8. アクションおよびコンポジット処理
9. 一時インデックスとID列のクリーンアップ
10. 結果オブジェクトの出力

### 3-決定論的マスキング

1. 元の値をキーとして検索
2. 既存のマッピングがあれば再利用
3. 新規の場合は値を生成しマッピングを保存
4. 辞書エクスポート（DictionaryExportPath指定時）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbDataMasking | 対象テーブル | UPDATE | カラム値のマスキング |
| Invoke-DbaDbDataMasking | tempdb.dbo.DeterministicValues | CREATE/INSERT | 決定論的値の管理 |
| Invoke-DbaDbDataMasking | 対象テーブル | ALTER TABLE | 一時ID列の追加/削除 |
| Invoke-DbaDbDataMasking | 対象テーブル | CREATE/DROP INDEX | マスキングインデックス |

### サポートされるデータ型

- bit, bigint, bool, char, date, datetime, datetime2, decimal
- float, int, money, nchar, ntext, nvarchar
- smalldatetime, smallint, text, time, tinyint
- uniqueidentifier, userdefineddatatype, varchar

### サポートされないカラム/データ型

- Identity（自動生成）
- ForeignKey（参照整合性）
- Computed（計算列）
- hierarchyid, geography, geometry, xml

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Errors found testing the configuration file | 構成ファイル検証エラー |
| MSG-002 | エラー | Could not parse masking config file | JSONパースエラー |
| MSG-003 | エラー | $columnType is not supported | サポート外データ型 |
| MSG-004 | エラー | Table $tableName is not present in $db | テーブル不存在 |
| MSG-005 | エラー | Could not create a unique row after $retryCount tries | ユニーク値生成失敗 |
| MSG-006 | エラー | Error updating $schema.$table | UPDATE失敗 |
| MSG-007 | 警告 | Column present in -ExcludeColumn cannot be excluded because it's part of an unique index | ユニークインデックスカラム除外不可 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 構成ファイル不正 | Stop-Functionで処理停止、検証エラー返却 |
| テーブル不存在 | Stop-Functionで該当テーブルスキップ |
| ユニーク値生成失敗 | Stop-Functionで処理停止（Retry回数到達後） |
| UPDATE失敗 | maskingErrorFlag=trueを設定、Status=Failed |
| 値変換失敗 | Stop-Functionで該当行スキップ |

## 備考

- SQL Server 2005以上が必要（MinimumVersion 9）
- ModulusFactorでNULL生成頻度を制御（10 = 約10%がNULL）
- DictionaryExportPathで出力された辞書ファイルは機密情報を含むため厳重管理が必要
- バッチサイズの調整によりメモリ使用量とパフォーマンスのバランスを取れる
- アクション機能で日付の加減算、数値演算が可能
- コンポジット機能で複数カラムの値を組み合わせた値を生成可能

---

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

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

### 推奨読解順序

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

マスキング構成ファイルの構造とサポートされるデータ型を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | JSON構成ファイル | `bin/datamasking/` | マスキング構成のスキーマ |
| 1-2 | supportedDataTypes | `public/Invoke-DbaDbDataMasking.ps1` 行187-199 | サポートデータ型の定義 |

**読解のコツ**: 構成ファイルはTables配列を持ち、各テーブルにColumns配列があります。各カラムにMaskingType、SubType、MinValue、MaxValueなどを指定します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbDataMasking.ps1 | `public/Invoke-DbaDbDataMasking.ps1` | マスキング実行のメインロジック |

**主要処理フロー (Invoke-DbaDbDataMasking)**:
1. **行184-227**: begin ブロック - デフォルト値設定、サポート型定義
2. **行234-259**: 構成ファイル読み込みと検証
3. **行274-286**: インスタンス接続と決定論的値テーブル作成
4. **行335-433**: データ取得とユニークインデックス処理
5. **行798-1075**: 行ごとのマスキング処理とバッチ実行
6. **行1077-1157**: アクション・コンポジット処理
7. **行1235-1285**: クリーンアップと結果出力

#### Step 3: ユニークインデックス処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbDataMasking.ps1 | `public/Invoke-DbaDbDataMasking.ps1` 行437-756 | ユニーク値生成ロジック |

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

```
Invoke-DbaDbDataMasking
    |
    +-- begin ブロック
    |       +-- supportedDataTypes定義
    |       +-- Get-DbaRandomizedType
    |       +-- デフォルト値設定
    |
    +-- Test-DbaDbDataMaskingConfig (構成検証)
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |
    +-- tempdb.DeterministicValues作成
    |
    +-- Import-DbaCsv (辞書インポート)
    |
    +-- foreach テーブル
    |       +-- テーブル存在確認
    |       +-- ID列追加（必要時）
    |       +-- マスキングインデックス作成
    |       +-- データ取得
    |       +-- Convert-DbaIndexToTable (ユニークインデックス時)
    |       |
    |       +-- foreach 行
    |       |       +-- foreach カラム
    |       |       |       +-- Get-DbaRandomizedValue
    |       |       |       +-- Convert-DbaMaskingValue
    |       |       +-- UPDATE文構築
    |       |
    |       +-- Invoke-DbaQuery (バッチ実行)
    |       +-- アクション処理
    |       +-- コンポジット処理
    |       +-- インデックス/ID列クリーンアップ
    |       +-- 結果出力
    |
    +-- 辞書エクスポート (指定時)
    +-- DeterministicValuesテーブル削除
```

### データフロー図

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

FilePath (JSON)   ------>  Test-DbaDbDataMaskingConfig
                          (構成検証)
                                |
                                v
SqlInstance       ------>  Connect-DbaInstance
SqlCredential              (MinimumVersion 9)
                                |
                                v
DictionaryFilePath -----> Import-DbaCsv
                          (決定論的値インポート)
                                |
                                v
Table/Column      ------>  テーブル/カラム選択
ExcludeTable/             (フィルタリング)
ExcludeColumn                   |
                                v
                   データ取得 ($db.Query)
                                |
                                v
Locale            ------>  Get-DbaRandomizedValue
CharacterString            (フェイクデータ生成)
MaxValue                        |
                                v
BatchSize         ------>  バッチ UPDATE実行
CommandTimeout             (Invoke-DbaQuery)
                                |
                                v
DictionaryExportPath --->  Export-Csv
                          (辞書エクスポート)
                                |
                                v
                   PSCustomObject  ----->  出力
                   (ComputerName, Schema,
                    Table, Columns, Rows,
                    Elapsed, Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbDataMasking.ps1 | `public/Invoke-DbaDbDataMasking.ps1` | ソース | マスキング実行コマンド |
| New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | ソース | マスキング構成生成 |
| Test-DbaDbDataMaskingConfig.ps1 | `public/Test-DbaDbDataMaskingConfig.ps1` | ソース | 構成ファイル検証 |
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | ランダム値生成 |
| Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | ソース | マスキングタイプ取得 |
| Convert-DbaMaskingValue.ps1 | `private/functions/Convert-DbaMaskingValue.ps1` | ソース | 値変換 |
| Convert-DbaIndexToTable.ps1 | `private/functions/Convert-DbaIndexToTable.ps1` | ソース | インデックス変換 |
| Import-DbaCsv.ps1 | `public/Import-DbaCsv.ps1` | ソース | CSVインポート |
