# 画面設計書 60-PIIスキャン

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるPIIスキャン（PII Scan）機能の設計仕様を記載したものです。データベース内の個人識別情報（PII：Personal Identifiable Information）を含む可能性のあるカラムを検出し、データマスキングの対象候補を特定する機能を提供します。

### 本画面の処理概要

本機能は、SQL Serverデータベースのテーブルを走査し、PIIを含む可能性のあるカラムを検出するPowerShellコマンドを提供します。カラム名パターンマッチングとデータ値パターン認識の2つの手法を使用して、氏名、住所、電話番号、社会保障番号などの機密データを特定します。

**業務上の目的・背景**：GDPR、HIPAA、PCI DSSなどのデータプライバシー規制に対応するため、組織はデータベース内の個人情報を特定し適切に保護する必要があります。本機能により、データベース全体を効率的にスキャンし、PIIを含む可能性のあるカラムを特定することで、データマスキング計画の策定やコンプライアンス監査を支援します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbPiiScan` - PIIスキャンの実行

**主要な操作・処理内容**：
1. 対象データベースとテーブルの選択
2. カラム名に基づくPIIパターンマッチング（KnownName）
3. データ値に基づくパターン認識（Pattern）
4. geographyデータ型の検出（DataType）
5. 検出結果とマスキング推奨の出力

**画面遷移**：本機能はCLIコマンドであり、検出結果をNew-DbaDbMaskingConfigに渡してマスキング構成ファイルを生成することができます。

**権限による表示制御**：PIIスキャンにはテーブルへのSELECT権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 170 | Invoke-DbaDbPiiScan | 主機能 | PIIスキャンの実行 |

## 画面種別

実行（CLI）

## URL/ルーティング

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

## 入出力項目

### Invoke-DbaDbPiiScan パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | string[] | 対象データベース名 |
| Table | No | string[] | 対象テーブル |
| Column | No | string[] | 対象カラム |
| Country | No | string[] | 国名フィルタ（例: United States） |
| CountryCode | No | string[] | 国コードフィルタ（例: US, CA, GB） |
| ExcludeTable | No | string[] | 除外テーブル |
| ExcludeColumn | No | string[] | 除外カラム |
| SampleCount | No | int | サンプル行数（デフォルト: 100） |
| KnownNameFilePath | No | string | カスタム既知名パターンファイル |
| PatternFilePath | No | string | カスタムデータパターンファイル |
| ExcludeDefaultKnownName | No | switch | デフォルトの既知名パターンを除外 |
| ExcludeDefaultPattern | No | switch | デフォルトのデータパターンを除外 |
| Force | No | switch | 強制実行 |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Invoke-DbaDbPiiScan 出力プロパティ（共通）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| Column | string | カラム名 |
| PII-Category | string | PIIカテゴリ（Identity, Location, Contactなど） |
| PII-Name | string | PII名（SSN, Geography, Phoneなど） |
| FoundWith | string | 検出方法（DataType, KnownName, Pattern） |
| MaskingType | string | 推奨マスキングタイプ |
| MaskingSubType | string | 推奨マスキングサブタイプ |

### FoundWith="Pattern"時の追加プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Country | string | パターンの国名 |
| CountryCode | string | パターンの国コード |
| Pattern | string | マッチした正規表現パターン |
| Description | string | パターンの説明 |

### FoundWith="KnownName"時の追加プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Pattern | string | マッチしたカラム名パターン |

## イベント仕様

### 1-PIIスキャン実行

1. デフォルトの既知名パターンとデータパターンの読み込み
2. カスタムパターンファイルの読み込み（指定時）
3. Country/CountryCodeによるパターンフィルタリング
4. 各インスタンスへの接続
5. 各データベース/テーブル/カラムに対するスキャン

### 2-カラムごとのスキャン処理

1. geographyデータ型の検出（FoundWith="DataType"）
2. カラム名の既知名パターンマッチング（FoundWith="KnownName"）
3. サンプルデータの取得（SampleCount行）
4. データ値のパターンマッチング（FoundWith="Pattern"）
5. 重複除外と結果追加

### 3-パターンファイル構造

**既知名パターン（pii-knownnames.json）**:
- Category: PIIカテゴリ
- Name: PII名
- Pattern: カラム名の正規表現パターン配列
- MaskingType, MaskingSubType: マスキング推奨

**データパターン（pii-patterns.json）**:
- Category: PIIカテゴリ
- Name: PII名
- Country, CountryCode: 対象国
- Pattern: データ値の正規表現パターン
- Description: パターンの説明
- MaskingType, MaskingSubType: マスキング推奨

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbPiiScan | 対象テーブル | SELECT | サンプルデータの読み取りのみ |

本機能はデータベースへの更新を行いません。読み取り専用のスキャン機能です。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Couldn't parse known names file | 既知名ファイルパースエラー |
| MSG-002 | エラー | Couldn't parse pattern file | パターンファイルパースエラー |
| MSG-003 | エラー | Couldn't not find known names file | 既知名ファイル不存在 |
| MSG-004 | エラー | Couldn't not find patterns file | パターンファイル不存在 |
| MSG-005 | エラー | Please enter a SQL Server instance | SqlInstance未指定 |
| MSG-006 | エラー | Please enter a database | Database未指定 |
| MSG-007 | エラー | Error executing query | クエリ実行エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SqlInstance未指定 | Stop-Functionで処理停止 |
| Database未指定 | Stop-Functionで処理停止 |
| パターンファイル不正 | Stop-Functionで処理停止 |
| データ取得失敗 | Stop-Functionで該当テーブルスキップ |

## 備考

- デフォルトパターンは`bin/datamasking/pii-knownnames.json`と`pii-patterns.json`
- SQL Server 2005以上が必要（MinimumVersion 9）
- SampleCountでパターンマッチングのサンプル行数を制御（デフォルト: 100）
- テキスト型カラムではLTRIM(RTRIM())を適用してパターンマッチング
- Country/CountryCodeでパターンを国別にフィルタリング可能
- 検出結果は重複を除外して出力

---

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

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

### 推奨読解順序

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

パターンファイルの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | pii-knownnames.json | `bin/datamasking/pii-knownnames.json` | カラム名パターン定義 |
| 1-2 | pii-patterns.json | `bin/datamasking/pii-patterns.json` | データ値パターン定義 |

**読解のコツ**: 既知名パターンはカラム名のマッチング、データパターンはデータ値のマッチングに使用されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbPiiScan.ps1 | `public/Invoke-DbaDbPiiScan.ps1` | PIIスキャンのメインロジック |

**主要処理フロー (Invoke-DbaDbPiiScan)**:
1. **行177-248**: begin ブロック - パターンファイル読み込み、パラメータ検証
2. **行250-263**: インスタンス接続
3. **行268-291**: データベース・テーブルフィルタリング
4. **行299-314**: カラムフィルタリング
5. **行316-335**: geographyデータ型検出
6. **行336-378**: 既知名パターンマッチング
7. **行380-453**: データ値パターンマッチング
8. **行464**: 結果出力

#### Step 3: パターンマッチングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbPiiScan.ps1 | `public/Invoke-DbaDbPiiScan.ps1` 行336-378 | 既知名マッチングロジック |
| 3-2 | Invoke-DbaDbPiiScan.ps1 | `public/Invoke-DbaDbPiiScan.ps1` 行380-453 | データパターンマッチングロジック |

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

```
Invoke-DbaDbPiiScan
    |
    +-- begin ブロック
    |       +-- デフォルト既知名パターン読み込み
    |       |       +-- Get-Content pii-knownnames.json
    |       |       +-- ConvertFrom-Json
    |       |
    |       +-- デフォルトデータパターン読み込み
    |       |       +-- Get-Content pii-patterns.json
    |       |       +-- ConvertFrom-Json
    |       |
    |       +-- カスタムパターン読み込み (指定時)
    |       |
    |       +-- Country/CountryCodeフィルタリング
    |
    +-- process ブロック
    |       +-- Connect-DbaInstance (MinimumVersion 9)
    |       |
    |       +-- foreach データベース
    |       |       +-- テーブルフィルタリング
    |       |       |
    |       |       +-- foreach テーブル
    |       |       |       +-- カラムフィルタリング
    |       |       |       |
    |       |       |       +-- foreach カラム
    |       |       |       |       |
    |       |       |       |       +-- geography検出
    |       |       |       |       |   (FoundWith="DataType")
    |       |       |       |       |
    |       |       |       |       +-- 既知名パターンマッチング
    |       |       |       |       |   (FoundWith="KnownName")
    |       |       |       |       |
    |       |       |       |       +-- サンプルデータ取得
    |       |       |       |       |   (Invoke-DbaQuery TOP SampleCount)
    |       |       |       |       |
    |       |       |       |       +-- データパターンマッチング
    |       |       |       |           (FoundWith="Pattern")
    |       |       |       |
    |       |       |       +-- 重複除外・結果追加
    |       |
    |       +-- piiScanResults出力
```

### データフロー図

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

pii-knownnames.json --->  既知名パターン読み込み
KnownNameFilePath   --->  (デフォルト + カスタム)
                                |
                                v
pii-patterns.json   --->  データパターン読み込み
PatternFilePath     --->  (デフォルト + カスタム)
                                |
                                v
Country/            --->  パターンフィルタリング
CountryCode                     |
                                v
SqlInstance         --->  Connect-DbaInstance
SqlCredential              (MinimumVersion 9)
                                |
                                v
Database            --->  データベース選択
Table/Column        --->  テーブル/カラムフィルタリング
ExcludeTable/              |
ExcludeColumn               v
                   foreach カラム
                          |
                   +------+------+------+
                   |      |      |      |
                   v      v      v      v
               geography  既知名   サンプル
               データ型   パターン  データ取得
               検出      マッチング (SampleCount行)
                   |      |      |
                   |      |      v
                   |      |   データパターン
                   |      |   マッチング
                   |      |      |
                   +------+------+
                          |
                          v
                   重複除外・結果追加
                          |
                          v
                   PSCustomObject配列  ----->  出力
                   (ComputerName, Database,
                    Schema, Table, Column,
                    PII-Category, PII-Name,
                    FoundWith, MaskingType,
                    MaskingSubType, ...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbPiiScan.ps1 | `public/Invoke-DbaDbPiiScan.ps1` | ソース | PIIスキャン実行コマンド |
| pii-knownnames.json | `bin/datamasking/pii-knownnames.json` | データ | カラム名パターン定義 |
| pii-patterns.json | `bin/datamasking/pii-patterns.json` | データ | データ値パターン定義 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
