# 機能設計書 332-Find-DbaInstance

## 概要

本ドキュメントは、複数のスキャン方式を使用してネットワーク上のSQL Serverインスタンスを検出する機能「Find-DbaInstance」の設計仕様を記載する。

### 本機能の処理概要

Find-DbaInstanceは、ネットワークインフラストラクチャ全体でSQL Serverインスタンスを包括的に検出する機能である。複数の検出方法を組み合わせて、完全なSQL Serverインベントリの作成、コンプライアンス監査、セキュリティリスクを持つ未文書化インスタンスの発見を支援する。

**業務上の目的・背景**：企業環境では、正式なデプロイメントプロセスを経ずに構築された「シャドウIT」データベースや、ドキュメント化されていないSQL Serverインスタンスが存在することがある。これらのインスタンスはセキュリティリスクやコンプライアンス違反の原因となる可能性がある。本機能は、ネットワーク全体をスキャンしてすべてのSQL Serverインスタンスを発見し、インベントリを完全に把握することを目的とする。

**機能の利用シーン**：
- 移行やコンプライアンスレビュー前にすべてのSQL Serverインスタンスを監査する際
- 標準的なデプロイメントプロセスをバイパスしたシャドウITデータベースを発見する際
- 合併・買収したネットワーク上のインスタンスをインベントリする際
- ディザスタリカバリドキュメントと実際に稼働しているインスタンスを照合する際
- 非標準ポートや特殊な構成で動作するインスタンスを特定する際

**主要な処理内容**：
1. **Discovery Phase（検出フェーズ）**：ターゲットリストの構築
   - Active Directory SPNルックアップ（登録されたSQLサービスを検出）
   - SQL Instance Enumeration（SSMSと同じブラウジング方式）
   - IPアドレス範囲スキャン（サブネット全体をスキャン）
   - ドメインサーバー検索（ADのすべてのWindowsサーバーをターゲット）

2. **Scan Phase（スキャンフェーズ）**：各ターゲットの検証
   - Browserサービスクエリ
   - WMI/CIM SQLサービス列挙
   - TCPポート接続テスト（デフォルト1433）
   - DNS解決チェック
   - Pingテスト
   - オプションのSQL接続試行

3. 信頼度レベル（High/Medium/Low）の判定

**関連システム・外部連携**：
- Active Directory（SPN検索、ドメインサーバー検索）
- SQL Server Browserサービス（UDP 1434）
- WMI/CIM（SQLサービス列挙）
- DNS（名前解決）

**権限による制御**：
- WMIアクセスには管理者権限が必要な場合がある
- SQL接続には適切なSQL Server認証が必要
- Active Directoryクエリにはドメイン参加またはクレデンシャルが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

ネットワークスキャン / インスタンス検出 / インベントリ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | Yes (Computer ParameterSet) | スキャン対象のコンピュータ | パイプライン入力可能 |
| DiscoveryType | DbaInstanceDiscoveryType | Yes (Discover ParameterSet) | 自動検出方式 | DataSourceEnumeration, DomainSPN, IPRange, DomainServer |
| Credential | PSCredential | No | Windows接続用資格情報 | - |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| ScanType | DbaInstanceScanType[] | No | 使用する検証方式（デフォルト: Default） | ValidateSet適用 |
| IpAddress | string[] | No | スキャン対象のIPアドレス範囲 | - |
| DomainController | string | No | 使用するドメインコントローラー | - |
| TCPPort | int[] | No | テストするTCPポート（デフォルト: 1433） | - |
| MinimumConfidence | DbaInstanceConfidenceLevel | No | 結果フィルタリングの最小信頼度 | None, Low, Medium, High |
| EnableException | switch | No | 例外を直接スローする | - |

### 入力データソース

- Active Directory（SPN、コンピュータオブジェクト）
- ネットワーク（UDP/TCP接続）
- SQL Server Browserサービス
- WMI/CIM

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| MachineName | string | コンピュータのネットワーク名 |
| ComputerName | string | コンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス識別子 |
| Port | int | TCPポート番号 |
| Confidence | DbaInstanceConfidenceLevel | 検出の信頼度 |
| Availability | string | インスタンスの可用性状態 |
| DnsResolution | IPHostEntry | DNS解決結果 |
| Ping | bool | Ping応答結果 |
| TcpConnected | bool | TCP接続結果 |
| SqlConnected | bool | SQL接続結果 |
| Timestamp | DateTime | スキャン実行日時 |
| ScanTypes | DbaInstanceScanType | 実行されたスキャン種別 |
| Services | object[] | 検出されたSQLサービス |
| SystemServices | object[] | システムSQLサービス |
| SPNs | string[] | 登録されているSPN |
| BrowseReply | DbaBrowserReply | Browserサービスからの応答 |
| PortsScanned | DbaPortReport[] | ポートスキャン結果 |

### 出力先

パイプライン出力（Dataplat.Dbatools.Discovery.DbaInstanceReport オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理
   └─ ユーティリティ関数定義、パラメータスプラット構築

2. パイプライン処理のセットアップ
   └─ Test-SqlInstance関数のSteppablePipeline作成

3. 検出フェーズ（DiscoveryTypeによる分岐）
   └─ DataSourceEnumeration: UDPブロードキャストによる検出
   └─ DomainSPN: Active Directory SPNルックアップ
   └─ IPRange: IPアドレス範囲スキャン
   └─ DomainServer: ドメインサーバー検索

4. スキャンフェーズ（各ターゲットに対して）
   └─ DNS解決、Ping、Browser、WMI、TCPポート、SPN、SQL接続

5. 信頼度判定
   └─ High: SQLサービス検出またはSQL接続成功
   └─ Medium: Browser応答またはポート+SPN一致
   └─ Low: 単一の指標のみ

6. 結果出力
   └─ MinimumConfidence以上の結果をパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータセット判定}
    B -->|Computer| C[ComputerName処理]
    B -->|Discover| D[Discovery実行]

    D --> E{DiscoveryType}
    E -->|DataSourceEnumeration| F[UDPブロードキャスト]
    E -->|DomainSPN| G[AD SPN検索]
    E -->|IPRange| H[IPレンジスキャン]
    E -->|DomainServer| I[ADサーバー検索]

    C --> J[Test-SqlInstance]
    F --> J
    G --> J
    H --> J
    I --> J

    J --> K[DNS解決]
    K --> L[Ping]
    L --> M[SPNルックアップ]
    M --> N[TCPポートテスト]
    N --> O[Browserサービスクエリ]
    O --> P[WMI/CIMサービス検出]

    P --> Q{SqlConnect指定?}
    Q -->|Yes| R[SQL接続テスト]
    Q -->|No| S[信頼度判定]
    R --> S

    S --> T{MinimumConfidence以上?}
    T -->|Yes| U[結果出力]
    T -->|No| V[スキップ]

    U --> W[終了]
    V --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 信頼度High判定 | SQLサービス検出またはSQL接続成功でHigh | SQLServiceまたはSqlConnectスキャン成功時 |
| BR-002 | 信頼度Medium判定 | Browser応答、またはポート1433開放、またはポート+SPN一致でMedium | Browser応答またはポートスキャン結果による |
| BR-003 | 信頼度Low判定 | 単一の指標（オープンポートまたはSPN）のみでLow | 他の検証が失敗した場合 |
| BR-004 | デフォルトスキャン | SqlConnect以外のすべてのスキャンがデフォルト | ScanType未指定時 |
| BR-005 | 重複排除 | 同一コンピュータは1回のみスキャン | computersScannedリストで管理 |

### 計算ロジック

IPアドレス範囲の計算:
- CIDR表記: 10.1.1.0/24 から開始・終了IPを計算
- サブネットマスク: 10.1.1.0/255.255.255.0 から範囲を計算
- 範囲指定: 10.1.1.1-10.1.1.254 を直接使用

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

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

本機能はSQL Serverメタデータへのアクセスを行わない（接続確認のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| DNSFailure | 名前解決エラー | DNS解決失敗 | 警告ログ出力、処理継続 |
| PingFailure | Pingエラー | Ping失敗 | 警告ログ出力、処理継続 |
| BrowserFailure | Browserエラー | Browserサービス応答なし | 処理継続 |
| WMIFailure | WMIエラー | WMIアクセス失敗 | 警告ログ出力、処理継続 |
| SqlConnectFailure | SQL接続エラー | SQL接続失敗 | SqlConnected=false設定 |

### リトライ仕様

リトライは行わない。各スキャンは独立して実行され、失敗しても次のスキャンに進む。

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

本機能はデータ変更を行わないため、トランザクション管理は不要。

## パフォーマンス要件

- IPRangeスキャンは大規模ネットワークで時間がかかる場合がある
- UDPタイムアウトは2秒（デフォルト）
- 並列処理は行わないため、多数のターゲットでは処理時間が長くなる

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

- ネットワークスキャンはセキュリティ監視システムでアラートをトリガーする可能性がある
- WMIアクセスには適切な権限が必要
- SQL接続試行は監査ログに記録される
- 規制環境では、ネットワーク全体スキャン前にセキュリティチームと調整が必要

## 備考

- SQL Server 2005以上に対応
- IPv4アドレスのみサポート（IPv6は正規表現チェックで検出されるが、範囲スキャンは未対応）
- クラスター環境のインスタンスも検出可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 出力オブジェクト構造（154-177行目の.OUTPUTS） |

**読解のコツ**: Dataplat.Dbatools.Discovery名前空間のカスタム型（DbaInstanceReport、DbaBrowserReply、DbaPortReport）を理解することが重要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | パラメータ定義（239-254行目） |
| 2-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | begin/process/endブロック構造 |

**主要処理フロー**:
1. **255-1027行目**: begin - ユーティリティ関数定義とパイプラインセットアップ
2. **1029-1096行目**: process - 検出とスキャン実行
3. **1098-1103行目**: end - パイプライン終了処理

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Test-SqlInstance関数（257-565行目）- メインスキャンロジック |
| 3-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Get-DomainSPN関数（567-636行目）- AD SPN検索 |
| 3-3 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Get-DomainServer関数（638-690行目）- ADサーバー検索 |
| 3-4 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Get-SQLInstanceBrowserUDP関数（692-777行目）- Browserクエリ |
| 3-5 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Test-TcpPort関数（779-822行目）- TCPポートテスト |
| 3-6 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | Resolve-IPRange関数（905-997行目）- IP範囲計算 |

#### Step 4: 信頼度判定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | 名前付きインスタンスの信頼度判定（448-467行目） |
| 4-2 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | ポート番号のみの信頼度判定（488-505行目） |
| 4-3 | Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | SqlConnect時の信頼度判定（514-555行目） |

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

```
Find-DbaInstance
    │
    ├─ Test-SqlInstance (内部関数 - Steppable Pipeline)
    │      │
    │      ├─ DNS解決 ([System.Net.Dns]::GetHostEntry)
    │      │
    │      ├─ Ping (System.Net.NetworkInformation.Ping)
    │      │
    │      ├─ Get-DomainSPN (内部関数)
    │      │      └─ System.DirectoryServices.DirectorySearcher
    │      │
    │      ├─ Get-SQLInstanceBrowserUDP (内部関数)
    │      │      └─ System.Net.Sockets.UdpClient
    │      │
    │      ├─ Test-TcpPort (内部関数)
    │      │      └─ Net.Sockets.TcpClient
    │      │
    │      ├─ Get-DbaService
    │      │      └─ WMI/CIM経由のサービス列挙
    │      │
    │      └─ Connect-DbaInstance (SqlConnect時)
    │
    ├─ Get-DomainSPN (検出フェーズ)
    │
    ├─ Get-DomainServer (検出フェーズ)
    │
    └─ Resolve-IPRange (検出フェーズ)
           │
           └─ Get-IPrange (内部関数)
```

### データフロー図

```
[入力]                    [Discovery Phase]              [Scan Phase]                [出力]

ComputerName ─────────────────────────────────────┐
                                                  │
DiscoveryType ──▶ DataSourceEnumeration ─────────┼──▶ Test-SqlInstance ──▶ DbaInstanceReport
              ──▶ DomainSPN ─────────────────────┤        │
              ──▶ IPRange ───────────────────────┤        ├─ DNS解決
              ──▶ DomainServer ──────────────────┘        ├─ Ping
                                                          ├─ SPN検索
                                                          ├─ Browser
                                                          ├─ TCPポート
                                                          ├─ WMI/CIM
                                                          └─ SqlConnect
                                                                │
                                                                ▼
                                                          信頼度判定
                                                                │
                                                                ▼
                                                          MinimumConfidenceフィルタ
                                                                │
                                                                ▼
                                                          パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaInstance.ps1 | `public/Find-DbaInstance.ps1` | ソース | メイン関数（すべての内部関数含む） |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQLサービス列挙 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaSpn.ps1 | `public/Test-DbaSpn.ps1` | ソース | SPN検証（process部で使用） |
