# 画面設計書 92-インスタンス検索

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンス検索機能（Find-DbaInstance）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
企業のIT環境において、ネットワーク上に存在するSQL Serverインスタンスの完全な把握は、セキュリティ監査、コンプライアンス対応、マイグレーション計画、そしてシャドーIT対策において極めて重要です。本機能は、複数の検出方法を組み合わせてネットワーク全体からSQL Serverインスタンスを包括的に検索・発見します。これにより、管理者は未文書化のインスタンス、セキュリティリスクとなる放置されたインスタンス、M&A後の統合対象インスタンスなどを効率的に特定できます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Find-DbaInstance -DiscoveryType <検出タイプ>`
- `Find-DbaInstance -ComputerName <コンピュータ名>`
- `Get-ADComputer -Filter "*" | Find-DbaInstance`

**主要な操作・処理内容**：
1. **ディスカバリーフェーズ**：ターゲットリストを複数の方法で収集
   - DomainSPN: Active Directory SPN検索によるSQL Server登録サービスの発見
   - DataSourceEnumeration: SSMS同等のUDPブロードキャストによるインスタンス列挙
   - IPRange: IPアドレス範囲スキャンによるサブネット全体のスキャン
   - DomainServer: Active Directory内のWindows Serverすべてを対象化
2. **スキャンフェーズ**：発見されたターゲットに対して検証スキャンを実行
   - Browser: SQL Server Browser Serviceへのクエリ
   - SQLService: WMI/CIMによるSQL Serverサービス列挙
   - TCPPort: デフォルト1433ポートへのTCP接続テスト
   - DNSResolve: DNS名前解決の確認
   - Ping: ICMP Pingによる到達性確認
   - SqlConnect: 実際のSQL接続テスト（オプション）
   - SPN: Service Principal Namesの検索

**画面遷移**：
本機能で発見されたインスタンスは、Get-DbaDatabase、Get-DbaLogin等の管理コマンドへパイプライン経由で渡すことができる。また、発見結果をCSVエクスポートしてインベントリ管理に活用する。

**権限による表示制御**：
- Active Directory検索にはドメインユーザー権限が必要
- WMI/CIMスキャンにはターゲットコンピュータの管理者権限が推奨
- SqlConnectスキャンにはSQL Server接続権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 332 | Find-DbaInstance | 主機能 | ネットワーク上のSQLインスタンス検索 |
| 327 | Connect-DbaInstance | API連携 | 発見されたインスタンスへの接続 |
| 694 | Get-DbaService | API連携 | SQLサービス情報の取得 |

## 画面種別

CLI（コマンドラインインターフェース）/ 検索・発見

## URL/ルーティング

PowerShellコマンド:
- `Find-DbaInstance`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstance[] | 条件付必須 | スキャン対象のコンピュータ名/IPアドレス |
| DiscoveryType | DbaInstanceDiscoveryType | 条件付必須 | 自動検出方法（DomainSPN/DataSourceEnumeration/IPRange/DomainServer） |
| Credential | PSCredential | いいえ | Windows資格情報（SPN検索、WMI/CIM接続用） |
| SqlCredential | PSCredential | いいえ | SQL Server接続用資格情報（SqlConnectスキャン用） |
| ScanType | DbaInstanceScanType[] | いいえ | 検証スキャンタイプ（Default/SQLService/Browser/TCPPort/All/SPN/Ping/SqlConnect/DNSResolve） |
| IpAddress | string[] | いいえ | カスタムIP範囲（IPRangeディスカバリー用） |
| DomainController | string | いいえ | 特定のドメインコントローラーを指定 |
| TCPPort | int[] | いいえ | スキャン対象TCPポート（デフォルト: 1433） |
| MinimumConfidence | DbaInstanceConfidenceLevel | いいえ | 結果フィルタの最小信頼度（Low/Medium/High） |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### 出力プロパティ（DbaInstanceReport）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| MachineName | string | インスタンスが発見されたコンピュータのネットワーク名 |
| ComputerName | string | コンピュータ名（MachineNameと同じ） |
| InstanceName | string | SQL Serverインスタンス名（ポートのみ検出時はnull） |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| Port | int | TCPポート番号（インスタンス名で発見時はnull） |
| Confidence | string | 発見の信頼度（High/Medium/Low） |
| Availability | string | インスタンスの可用性状態（Available/Unavailable/Unknown） |
| DnsResolution | IPHostEntry | DNS解決結果（DNSResolveスキャン実行時） |
| Ping | bool | Ping応答結果 |
| TcpConnected | bool | TCPポートの接続可否 |
| SqlConnected | bool | SQL接続成功可否（SqlConnectスキャン時のみ） |
| Timestamp | DateTime | スキャン実行日時 |
| ScanTypes | DbaInstanceScanType | 実行されたスキャンタイプ |
| Services | object[] | 検出されたSQLサービス情報（WMI/CIM経由） |
| SystemServices | object[] | システムSQLサービス情報 |
| SPNs | string[] | 登録されているService Principal Names |
| BrowseReply | DbaBrowserReply | Browser Serviceからの応答 |
| PortsScanned | DbaPortReport[] | ポートスキャン結果 |

## イベント仕様

### 1-コンピュータ指定スキャン実行

1. ComputerNameパラメータで指定されたターゲットをTest-SqlInstance内部関数へ渡す
2. 各コンピュータに対してScanTypeに基づくスキャンを実行
3. 結果をDbaInstanceReportオブジェクトとして出力
4. MinimumConfidenceでフィルタリング

### 2-自動ディスカバリー実行

1. DiscoveryTypeに基づきターゲットリストを収集
   - DataSourceEnumeration: SqlDataSourceEnumerator.Instance.GetDataSources()
   - DomainSPN: Get-DomainSPN内部関数でAD検索
   - IPRange: Resolve-IPRange内部関数でIP範囲展開
   - DomainServer: Get-DomainServer内部関数でAD検索
2. 収集されたターゲットをTest-SqlInstance内部関数へ渡す
3. 結果をDbaInstanceReportオブジェクトとして出力

### 3-Browser Serviceスキャン

1. UDPポート1434へパケット送信
2. 応答を解析してインスタンス名、TCPポート、バージョン、クラスター情報を取得
3. BrowseReplyプロパティに格納

### 4-SQLServiceスキャン

1. Get-DbaServiceでSQL Serverサービスを列挙
2. サービス状態からAvailabilityを判定（Running=Available、Stopped=Unavailable）
3. 成功時はConfidence=Highを設定

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

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

本機能はデータベースへの更新を行わない（参照のみ）。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| SqlConnectスキャン | なし | SELECT | 接続テストのみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | 情報 | Processing: {ComputerName} |
| MSG002 | 情報 | Starting |
| MSG003 | 情報 | Performing DNS resolution |
| MSG004 | 情報 | Waiting for ping response |
| MSG005 | 情報 | Finding SPNs |
| MSG006 | 情報 | Testing TCP ports |
| MSG007 | 情報 | Probing Browser service |
| MSG008 | 情報 | Finding SQL services using SQL WMI |
| MSG009 | 警告 | Datasource enumeration failed |
| MSG010 | 警告 | Failed to execute Service Principal Name discovery |
| MSG011 | 警告 | Failed to execute Windows Server discovery |
| MSG012 | エラー | Please specify DiscoveryType or ScanType |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| DNS解決失敗 | 処理を継続、DnsResolutionプロパティはnull |
| Ping失敗 | 処理を継続、Pingプロパティはfalse |
| Browser Service応答なし | 処理を継続、BrowseReplyプロパティはnull |
| WMI/CIM接続失敗 | 警告メッセージ出力、Servicesプロパティは空 |
| SQL接続失敗 | SqlConnectedプロパティをfalse、エラークラスに応じてConfidence設定 |
| パラメータ未指定 | Stop-Functionでエラー出力 |

## 備考

- ディスカバリーフェーズはネットワークトラフィックを生成するため、セキュリティチームとの事前調整を推奨
- IPRangeディスカバリーは大規模ネットワークでは時間がかかる
- 信頼度レベル：High=SQLサービス検出またはSQL接続成功、Medium=Browser応答またはポート+SPN、Low=ポートオープンまたはSPN登録のみ

---

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

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

### 推奨読解順序

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

出力されるDbaInstanceReportクラスと内部ユーティリティ関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 154-178行目の.OUTPUTSセクションで出力構造を確認 |
| 1-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 749-761行目のDbaBrowserReplyオブジェクト構造 |

**読解のコツ**: DbaInstanceReportはDatplatネームスペースで定義されたC#クラス。PowerShellからはプロパティとしてアクセス。

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

コマンドのパラメータセットと処理分岐を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 236-254行目のparamブロック |
| 2-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 1029-1095行目のprocessブロック |

**主要処理フロー**:
1. **1032-1034行目**: ComputerNameパラメータセットの処理
2. **1036-1084行目**: Discoverパラメータセットの処理（各DiscoveryTypeの分岐）
3. **1021-1026行目**: steppablePipelineでTest-SqlInstanceを呼び出し

#### Step 3: 内部ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 257-565行目のTest-SqlInstance関数 |
| 3-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 567-636行目のGet-DomainSPN関数 |
| 3-3 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 638-690行目のGet-DomainServer関数 |
| 3-4 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 692-777行目のGet-SQLInstanceBrowserUDP関数 |
| 3-5 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 779-822行目のTest-TcpPort関数 |
| 3-6 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 824-903行目のGet-IPrange関数 |

**主要処理フロー**:
- **Test-SqlInstance**: 各ターゲットに対するスキャン実行のメイン関数
- **Get-DomainSPN**: Active DirectoryからMSSQLsvc SPNを検索
- **Get-SQLInstanceBrowserUDP**: UDPでBrowser Serviceへクエリ

#### Step 4: スキャンロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 311-330行目のDNSResolve/Pingスキャン |
| 4-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 332-369行目のSPN/Browser/SQLServiceスキャン |
| 4-3 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 428-472行目の名前付きインスタンス検出 |
| 4-4 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 475-512行目のポート番号検出 |
| 4-5 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 514-560行目のSqlConnectスキャン |

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

```
Find-DbaInstance
    │
    ├─ [DiscoverパラメータSet]
    │      │
    │      ├─ DataSourceEnumeration
    │      │      └─ SqlDataSourceEnumerator.Instance.GetDataSources()
    │      │
    │      ├─ DomainSPN
    │      │      └─ Get-DomainSPN (内部関数)
    │      │             └─ LDAP検索 (servicePrincipalName=MSSQLsvc*)
    │      │
    │      ├─ IPRange
    │      │      └─ Resolve-IPRange (内部関数)
    │      │             └─ Get-IPrange (内部関数)
    │      │
    │      └─ DomainServer
    │             └─ Get-DomainServer (内部関数)
    │                    └─ LDAP検索 (operatingSystem=*windows*server*)
    │
    └─ Test-SqlInstance (内部関数)
           │
           ├─ DNSResolve
           │      └─ [System.Net.Dns]::GetHostEntry()
           │
           ├─ Ping
           │      └─ System.Net.NetworkInformation.Ping
           │
           ├─ SPN
           │      └─ Get-DomainSPN
           │
           ├─ Browser
           │      └─ Get-SQLInstanceBrowserUDP (内部関数)
           │             └─ UDP 1434接続
           │
           ├─ TCPPort
           │      └─ Test-TcpPort (内部関数)
           │             └─ Net.Sockets.TcpClient
           │
           ├─ SQLService
           │      └─ Get-DbaService
           │
           └─ SqlConnect
                  └─ Connect-DbaInstance
```

### データフロー図

```
[入力]                    [ディスカバリー]              [スキャン]                [出力]

DiscoveryType ──┬──▶ DomainSPN ─────────┐
                │                        │
                ├──▶ DataSourceEnum ────┤
                │                        │
                ├──▶ IPRange ───────────┤     ┌─────────────────┐
                │                        ├────▶│ Test-SqlInstance │
                └──▶ DomainServer ──────┘     │                 │
                                              │  ┌─ DNSResolve  │
ComputerName ─────────────────────────────────│  ├─ Ping        │
                                              │  ├─ SPN         │
                                              │  ├─ Browser     │──▶ DbaInstanceReport
                                              │  ├─ TCPPort     │
                                              │  ├─ SQLService  │
                                              │  └─ SqlConnect  │
                                              └─────────────────┘
                                                      │
                                              MinimumConfidence
                                                      │
                                                      ▼
                                              [フィルタリング]
                                                      │
                                                      ▼
                                              [結果出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | ソース | メインのインスタンス検索機能 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SqlConnectスキャンで使用 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQLServiceスキャンで使用 |
