# 機能設計書 190-New-DbaDbMaskingConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDbMaskingConfig` コマンドレットの機能設計書である。このコマンドレットは、データベーステーブルをスキャンして機密データ（PII）を検出し、データマスキング用のJSON設定ファイルを自動生成する機能を提供する。

### 本機能の処理概要

本機能は、SQL Serverデータベースのテーブルとカラムを分析し、個人情報（PII）として識別される可能性のある機密情報を自動検出する。カラム名のパターンマッチングとデータサンプリングを使用して、社会保障番号、メールアドレス、電話番号などの機密データを特定し、各カラムのマスキング方法を定義するJSON設定ファイルを生成する。

**業務上の目的・背景**：本番データベースから開発・テスト環境を作成する際、個人情報保護法やGDPRなどの規制に準拠するため、機密データのマスキングが必要である。手動での機密データ特定は時間がかかりエラーが発生しやすいため、自動検出と設定ファイル生成により、安全で効率的なデータマスキングプロセスを実現する。

**機能の利用シーン**：
- 本番データベースから開発環境用のマスキング設定作成
- GDPR/個人情報保護法準拠のためのPII検出
- テスト環境構築のためのデータ匿名化準備
- セキュリティ監査用の機密データ棚卸

**主要な処理内容**：
1. pii-knownnames.jsonからの既知名パターン読み込み
2. pii-patterns.jsonからのデータパターン読み込み
3. データベーステーブル・カラムのスキャン
4. カラム名とデータサンプルによるPII検出
5. データ型に応じたマスキングタイプの決定
6. JSON設定ファイルの生成と保存

**関連システム・外部連携**：Bogusライブラリ、pii-knownnames.json、pii-patterns.json

**権限による制御**：対象データベースへのSELECT権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 59 | データマスキング | 補助機能 | マスキング設定の作成 |

## 機能種別

設定ファイル生成 / PII検出 / メタデータ分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | パイプラインから入力可能 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Database | string[] | No | 処理対象データベース | - |
| Table | string[] | No | 処理対象テーブル | - |
| Column | string[] | No | 処理対象カラム | - |
| Path | string | Yes | 設定ファイルの保存先ディレクトリ | 必須 |
| Locale | string | No | マスキング用のロケール設定 | デフォルト'en' |
| CharacterString | string | No | 文字列データに使用する文字セット | デフォルト英数字 |
| SampleCount | int | No | PII判定用サンプル行数 | デフォルト100 |
| KnownNameFilePath | string | No | カスタム既知名ファイルパス | - |
| PatternFilePath | string | No | カスタムパターンファイルパス | - |
| ExcludeDefaultKnownName | switch | No | デフォルト既知名を除外 | - |
| ExcludeDefaultPattern | switch | No | デフォルトパターンを除外 | - |
| Force | switch | No | ディレクトリ強制作成 | - |
| InputObject | object[] | No | Invoke-DbaDbPiiScanからのパイプ入力 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverデータベースのメタデータ（テーブル、カラム）
- SQL Serverデータベースのサンプルデータ
- pii-knownnames.json（既知名パターン定義）
- pii-patterns.json（データパターン定義）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 設定ファイル名 |
| FullName | string | 設定ファイルの完全パス |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | datetime | 作成日時 |
| LastWriteTime | datetime | 最終更新日時 |
| DirectoryName | string | 親ディレクトリパス |

### 出力先

JSONファイル（命名規則に従った自動命名）

### ファイル命名規則

| 条件 | ファイル名形式 |
|------|---------------|
| テーブル指定なし | servername.databasename.DataMaskingConfig.json |
| テーブル1-4個指定 | servername.databasename.table1-table2.DataMaskingConfig.json |
| テーブル5個以上指定 | servername.databasename.Tables_yyyyMMddHHmmss.DataMaskingConfig.json |

### JSON設定ファイル構造

```json
{
  "Name": "データベース名",
  "Type": "DataMaskingConfiguration",
  "Tables": [
    {
      "Name": "テーブル名",
      "Schema": "スキーマ名",
      "Columns": [
        {
          "Name": "カラム名",
          "ColumnType": "データ型",
          "CharacterString": "使用文字セット",
          "MinValue": 1,
          "MaxValue": 100,
          "MaskingType": "Random",
          "SubType": "String2",
          "Format": null,
          "Separator": null,
          "Deterministic": false,
          "Nullable": true,
          "KeepNull": true,
          "Composite": null,
          "Action": null,
          "StaticValue": null
        }
      ],
      "HasUniqueIndex": false,
      "FilterQuery": null
    }
  ]
}
```

## 処理フロー

### 処理シーケンス

```
1. beginブロック処理
   └─ pii-knownnames.json読み込み
   └─ pii-patterns.json読み込み
   └─ カスタムパターンファイル読み込み（指定時）
   └─ 出力パスの検証/作成
   └─ サポートデータ型リスト初期化
2. processブロック処理
   └─ InputObjectまたはSqlInstanceからデータベース取得
3. 各データベース処理
   └─ テーブルコレクション取得
4. 各テーブル処理
   └─ ユニークインデックス有無確認
   └─ カラムコレクション取得
5. 各カラム処理
   └─ 非サポートカラムのスキップ（Identity, FK, Computed等）
   └─ データ型によるMin/MaxValue設定
   └─ 既知名パターンマッチング
   └─ データサンプリングによるパターンマッチング
   └─ マスキングタイプの決定
6. テーブル設定オブジェクト作成
7. データベース設定オブジェクト作成
8. JSONファイル出力
   └─ ファイル名決定
   └─ ConvertTo-Jsonで変換
   └─ Set-Contentで保存
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[pii-knownnames.json読み込み]
    B --> C[pii-patterns.json読み込み]
    C --> D[出力パス確認/作成]
    D --> E[Get-DbaDatabase]
    E --> F{データベース存在?}
    F -->|No| G[終了]
    F -->|Yes| H[各テーブルを処理]
    H --> I[各カラムを処理]
    I --> J{非サポート型?}
    J -->|Yes| K[スキップ]
    J -->|No| L{既知名マッチ?}
    L -->|Yes| M[既知名設定を使用]
    L -->|No| N{パターンマッチ?}
    N -->|Yes| O[パターン設定を使用]
    N -->|No| P[データ型からデフォルト設定]
    M --> Q[カラム設定追加]
    O --> Q
    P --> Q
    K --> R{次のカラム?}
    Q --> R
    R -->|Yes| I
    R -->|No| S[テーブル設定追加]
    S --> T{次のテーブル?}
    T -->|Yes| H
    T -->|No| U[JSON出力]
    U --> V[Get-ChildItem]
    V --> W[結果出力]
    W --> X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 非サポートカラムスキップ | Identity, FK, Computed, TemporalTable列はスキップ | カラム処理時 |
| BR-002 | 非サポートデータ型スキップ | hierarchyid, geography, geometry, xmlはスキップ | カラム処理時 |
| BR-003 | 既知名優先 | カラム名が既知名パターンに一致する場合は定義済み設定を使用 | カラム名マッチ時 |
| BR-004 | パターンマッチング | データサンプルがパターンに一致する場合は定義済み設定を使用 | データマッチ時 |
| BR-005 | デフォルトサンプル数 | SampleCount未指定時は100行 | SampleCount未指定時 |
| BR-006 | デフォルトロケール | Locale未指定時は'en' | Locale未指定時 |

### PII検出優先順位

| 優先度 | 検出方法 | 説明 |
|--------|---------|------|
| 1 | InputObject | Invoke-DbaDbPiiScanからのパイプ入力 |
| 2 | KnownName | カラム名パターンマッチング |
| 3 | Pattern | データサンプルのパターンマッチング |
| 4 | DataType | データ型に基づくデフォルト設定 |

### データ型別マスキング設定

| ColumnType | MaskingType | SubType | MaxValue |
|------------|-------------|---------|----------|
| bit/bool | Random | Bool | null |
| bigint | Random | Number | 9223372036854775807 |
| int | Random | Number | 2147483647 |
| smallint | Random | Number | 32767 |
| tinyint | Random | Number | 255 |
| date/datetime/datetime2 | Date | Past | null |
| float | Random | Float | null |
| decimal/numeric | Random | Decimal | null |
| money | Commerce | Price | 922337203685477.5807 |
| char/varchar/nchar/nvarchar | Random | String2 | MaximumLength |
| uniqueidentifier | Random | Guid | null |
| varbinary | Random | Byte | MaximumLength |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| メタデータ取得 | sys.tables, sys.columns等 | SELECT | テーブル・カラム情報の取得 |
| サンプルデータ取得 | 対象テーブル | SELECT TOP(n) | PII検出用データサンプリング |

本機能はメタデータとサンプルデータの読み取りのみを行い、データの変更は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------  |
| - | pii-knownnames.json読み込み失敗 | ファイル破損または不存在 | モジュール再インストール |
| - | pii-patterns.json読み込み失敗 | ファイル破損または不存在 | モジュール再インストール |
| - | カスタムファイル読み込み失敗 | 指定ファイルが存在しないまたは形式不正 | ファイルパス・形式確認 |
| - | パス作成失敗 | ディレクトリ作成権限なし | 権限確認またはForce使用 |
| - | テーブルなし | データベースにテーブルがない | テーブル存在確認 |
| - | クエリ実行失敗 | サンプルデータ取得時のエラー | 権限確認 |
| - | JSON出力失敗 | ファイル書き込み権限なし | パス権限確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

トランザクション管理なし（読み取り専用操作）

## パフォーマンス要件

- テーブル数・カラム数に比例した処理時間
- 各カラムでSampleCount行のサンプリングを実行するため、カラム数が多い場合は時間がかかる
- SampleCountを減らすことでパフォーマンスを改善可能

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

- 対象データベースへのSELECT権限が必要
- サンプルデータは一時的にメモリ上で処理され、永続化されない
- 設定ファイルにはスキーマ情報とマスキングルールのみが含まれ、実データは含まれない
- 出力パスへの書き込み権限が必要

## 備考

- 生成された設定ファイルはInvoke-DbaDbDataMaskingで使用
- pii-knownnames.jsonとpii-patterns.jsonはモジュール内のbin/datamaskingディレクトリに配置
- Bogusライブラリの機能に基づいたデータ生成タイプを使用
- Invoke-DbaDbPiiScanの結果をパイプで渡すことで検出処理をスキップ可能

---

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

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

### 推奨読解順序

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

パラメータ定義と設定ファイル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | 143-162行目のparamブロック |

**読解のコツ**: Pathは必須パラメータ。SampleCountのデフォルトは100。Localeのデフォルトは'en'。InputObjectでInvoke-DbaDbPiiScanの結果を受け取れる。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | 163-247行目のbeginブロック |

**主要処理フロー**:
- **170-178行目**: pii-knownnames.json読み込み
- **181-189行目**: pii-patterns.json読み込み
- **192-216行目**: カスタムパターンファイル読み込み
- **218-229行目**: 出力パスの検証と作成
- **231-244行目**: サポートデータ型リスト定義

#### Step 3: カラム処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | 294-611行目のカラム処理 |

**主要処理フロー**:
- **298-326行目**: 非サポートカラムのスキップ（Identity, FK, Computed等）
- **346-417行目**: データ型によるMin/MaxValue設定（switch文）
- **444-466行目**: 既知名パターンマッチング
- **473-520行目**: データサンプリングとパターンマッチング
- **524-541行目**: PII検出時のカラム設定
- **543-610行目**: PII未検出時のデフォルト設定

#### Step 4: JSON出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | 638-665行目のJSON出力処理 |

**主要処理フロー**:
- **644-652行目**: ファイル名決定（テーブル数による分岐）
- **658行目**: ConvertTo-JsonでJSON変換（Depth 5）
- **659行目**: Get-ChildItemでFileInfo返却

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

```
New-DbaDbMaskingConfig
    │
    ├─ Get-Content (pii-knownnames.json)
    │      └─ 既知名パターン読み込み
    │
    ├─ Get-Content (pii-patterns.json)
    │      └─ データパターン読み込み
    │
    ├─ Get-DbaDatabase
    │      └─ データベース情報取得
    │
    ├─ テーブル/カラム処理
    │      ├─ $tableobject.Indexes.IsUnique
    │      ├─ $tableobject.Columns
    │      └─ Invoke-DbaQuery（サンプリング）
    │
    ├─ ConvertTo-Json
    │      └─ 設定オブジェクトのJSON変換
    │
    ├─ Set-Content
    │      └─ JSONファイル書き込み
    │
    └─ Get-ChildItem
           └─ FileInfo返却
```

### データフロー図

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

SqlInstance ─────────▶ Get-DbaDatabase
Database ────────────▶ テーブル取得
                              │
                              ▼
pii-knownnames.json ─▶ 既知名マッチング
pii-patterns.json ───▶ パターンマッチング
                              │
                              ▼
カラムメタデータ ────▶ MaskingType/SubType決定
サンプルデータ ──────▶ (Invoke-DbaQuery)
                              │
                              ▼
                       テーブル設定構築
                              │
                              ▼
                       ConvertTo-Json
                              │
                              ▼
Path ─────────────────▶ Set-Content ─────────────────▶ *.DataMaskingConfig.json
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | ソース | メイン機能の実装 |
| pii-knownnames.json | `bin/datamasking/pii-knownnames.json` | 設定 | 既知名パターン定義 |
| pii-patterns.json | `bin/datamasking/pii-patterns.json` | 設定 | データパターン定義 |
| Invoke-DbaDbDataMasking.ps1 | `public/Invoke-DbaDbDataMasking.ps1` | ソース | 生成設定を使用したデータマスキング |
| Invoke-DbaDbPiiScan.ps1 | `public/Invoke-DbaDbPiiScan.ps1` | ソース | PII検出（パイプ入力元） |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース情報取得 |
