╔╦╦╬╬╬╬╬╬╦╦╗
 ╔╬╬╬╝╝┘      ╚╝╝╬╬╬┐
╬╬╝╚╩╬╗╔          ╚╬╬╬

**この Entra ID のクライアント ID とシークレットで、実際に何ができるのか？**

あなたは、許可されたエンゲージメントで Entra ID (Azure AD) アプリケーションの資格情報 — クライアント ID とシークレット — を発見しました。
その所属するテナントはスコープ内にあります。
`secret_stalker` はこれら 2 つの値を受け取り、コールドスタートから次のことを教えてくれます。

1. **有効かどうか、そしてシークレットはいつ期限切れになりますか？** — 有効でない場合は、*その理由*
   (シークレットの誤り、期限切れのシークレット、テナント内に存在しないアプリなど)。有効なシークレットの場合、
   アプリ登録の `passwordCredentials` を読み取り、有効期限の日付と
   残り日数を報告します（ディレクトリ読み取りが必要。下記の注を参照）。
2. **どの Microsoft Graph 権限を持ちますか？** — 発行されたトークンから直接読み取られるアプリケーション権限に加え、
   保持する **Entra ディレクトリロール**（
   トークンの `wids` クレームから受動的に検出されるものも）と **所有するオブジェクト**
   （資格情報を追加できるアプリ/SP）。
3. **Azure に対してどのような制御を持ちますか？** — RBAC ロール割り当て（
   管理グループとサブスクリプションのスコープ）。
4. **実際のデータに到達できますか？** — オプションの Key Vault（シークレット / キー / 証明書）、
   Storage（blob / file / queue / table）、および Cosmos DB データプレーン到達可能性チェック。
5. **影響は何ですか？** — 危険な権限、ロール、所有権、そして到達可能な
   データを既知の権限昇格 / 横移動プリミティブにマッピングし、重大度で評価し、
   具体的な **攻撃経路** の説明を提供します。

認証は **クライアント シークレット** または **証明書** (`--cert`) のいずれかを使用し、
**商用クラウドとソブリンクラウド** (`--cloud`) で動作します。

デフォルトでは **パッシブ** であり、**何も変更しません** — 読み取り専用の
列挙のみです。

> ⚠️ **許可されたテストのみ。** 実行するのは、あなたが実行を許可されたエンゲージメントで
> 明示的にスコープ内にあるテナントのみです。

---

## インストール```bash
pip install -r requirements.txt        # just runs it from source
#   — or —
pip install .                          # installs the `secret_stalker` command
pip install '.[cert]'                  # + certificate (--cert) auth support
pip install '.[dev]'                   # + pytest for the test suite

`--tenant` はテナント GUID またはドメインのいずれかを受け入れます。ドメインは公開 OpenID 設定エンドポイントを介して自動的に
テナント ID に解決されます。

### シェルの履歴に秘密情報を残さない

フラグではなく環境変数で認証情報を渡します:```bash
export SS_TENANT=contoso.onmicrosoft.com
export SS_CLIENT_ID=11111111-2222-3333-4444-555555555555
export SS_SECRET='<client-secret>'

python -m secret_stalker

証明書認証にはオプションの `cryptography` パッケージが必要です（`pip install '.[cert]'`）。
このツールは、証明書自体の有効期限を報告します（アプリの
`keyCredentials` 内の拇印に一致）。シークレットの場合と同様に、`--cert`/`--cert-password`
は `SS_CERT` / `SS_CERT_PASSWORD` からも読み取られます。

### ソブリンクラウドと政府クラウド

デフォルトでは、secret_stalker は **商用** クラウドを対象としています。ソブリンテナントの場合、
`--cloud`（または `SS_CLOUD`）を渡して、Entra オーソリティと Graph / ARM / Key
Vault エンドポイントが一致するようにしてください — そうしないと、有効な資格情報もアクセス権がないように見えます:```bash
# US Government (GCC High)
python -m secret_stalker --cloud usgov  --tenant contoso.onmicrosoft.us ...

# US DoD (L5)
python -m secret_stalker --cloud usdod  ...

# Azure operated by 21Vianet (China)
python -m secret_stalker --cloud china  --tenant contoso.partner.onmschina.cn ...

- **トークン取得** は、プローブした各対象 (Graph、ARM、および `--active` 時に一致するリソースが検出された場合の Key Vault / Storage / Cosmos DB) を一覧表示します。Graph と ARM は*独立*しています: 資格情報は一方のみを保持し、もう一方は保持しない場合があります。
- **シークレット** は有効性を示し、有効なシークレットの場合は有効期限と残り日数を表示します (期限が近いものは強調表示)。期限切れシークレットに関する以下の注記を参照してください。
- **検出結果 (Findings)** は最初に読むべき部分です — 影響度の高い Graph 権限 (`GRAPH`)、ARM ロール (`ARM`)、Entra ディレクトリ ロール (`ROLE`)、所有するアプリ/SP (`OWN`)、到達可能なデータプレーン面 (`DATA`)、および要求済みだが同意されていない同意攻撃のターゲット (`WANT`) — 重複排除され、重大度が評価されています。危険な Graph/ARM 権限がなくても、すべての Key Vault シークレットを読み取れることや、ディレクトリ ロールを保持していることは、それ自体が検出結果となります。
- **攻撃経路 (Attack paths)** は、上位の検出結果を具体的な次のステップに変換します (例: *Privileged Role Administrator → 自分自身に Global Administrator を割り当て → テナント乗っ取り*)。
- **アクティブな Graph 列挙** (`--active`) は、各読み取り専用プローブが返した内容を報告します。ほとんどのプローブは小さい上限付きページを要求するため、ページがいっぱいの場合は `N+` と表示されます (例: `users  accessible  (returned 5+)`) — これは正確に 5 件ではなく*少なくとも* 5 件を意味します。上限のないプローブ (`organization`、`directoryRoles`) は `+` なしの実際の合計を報告します。
- **ディレクトリ ロール / 所有オブジェクト / 委任された権限** は、それぞれ専用のセクションがあります。ディレクトリ ロールは、ディレクトリ読み取り権限がなくてもトークンの `wids` クレームから検出されます。委任された権限はアプリ専用の資格情報では使用できませんが、ユーザー コンテキストでの切り替えや同意攻撃のターゲット選定のために表示されます。
- **全体的なリスク** は、単一の検出結果の中で最も高い重大度です。

> **シークレットの有効期限 — 判明可能な情報。** 有効期限はトークン内には*ありません*。Entra ID のアプリ登録の `passwordCredentials` に存在します。**有効な**シークレットの場合、secret_stalker は Graph 経由でそれを読み取り、シークレットの `hint` (最初の 3 文字) によって正しい資格情報と照合します — これにはディレクトリ読み取り (`Application.Read.All` / `Directory.Read.All`) が必要です。SP にそれが無い場合、日付は推測ではなく「利用不可」として報告されます。**期限切れの**シークレットの場合、認証自体が失敗するため、失効した資格情報は自身のメタデータを読み取ることができません — ツールはそれを `EXPIRED (AADSTS7000222)` としてフラグ付けしますが、正確な終了日はその資格情報だけでは取得できません。

### 終了コード

スクリプト処理に便利です:

| Code | 意味 |
|------|---------|
| `0`  | 資格情報が有効 (少なくとも 1 つのトークンを取得)。 |
| `2`  | 資格情報が無効 / アクセス権がない。 |
| `1`  | エラー — テナントを解決できない、証明書を読み込めない、または `--export` ファイルを書き込めない。 |

---

## すべてのフラグ

| Flag | 効果 |
|------|--------|
| `--tenant` | テナント GUID またはドメイン。(または `SS_TENANT`) |
| `--cloud` | Azure クラウド: `public` (既定)、`usgov` (GCC High)、`usdod` (DoD)、`china` (21Vianet)。Entra 機関と Graph/ARM/Key Vault エンドポイントを選択します。`gov`/`dod`/`commercial` などのエイリアスも受け付けます。(または `SS_CLOUD`) |
| `--client-id` | アプリケーション (クライアント) ID。(または `SS_CLIENT_ID`) |
| `--secret` | クライアント シークレット。履歴に残さないため `SS_SECRET` を推奨します。 |
| `--cert` | シークレットの代わりに JWT アサーション認証用の証明書: PEM (キー+証明書) または `.pfx`/`.p12`。`cryptography` が必要です。(または `SS_CERT`) |
| `--cert-password` | 暗号化された `--cert` キー/PFX のパスワード。(または `SS_CERT_PASSWORD`) |
| `--active` | オプトインの読み取り専用列挙: Graph オブジェクトのサンプル **および** Key Vault / Storage データプレーンへの到達可能性。既定ではオフで、静かに動作します。 |
| `--deep` | `--active` と併用: 到達可能な Storage に 1 レベル深く入り込み、アクセス可能なコンテナの BLOB とアクセス可能な共有のファイル (名前のみ、上限付き) を一覧表示します。ノイズが増えます。 |
| `--no-arm` | 管理グループ / サブスクリプション / RBAC の列挙をスキップします (Graph のみ)。 |
| `--workers N` | ARM スコープ検索とデータプレーン プローブ用の並列 HTTP ワーカー数 (既定 8、`1` = 順次)。 |
| `--update-manifest` | ライブ テナントから信頼できる appRole GUID→名前マップを取得し (Graph **および** この資格情報が割り当てられている他のリソース API)、キャッシュして終了します。 |
| `--json` | レポートの代わりに完全なネストされた結果を JSON として出力します。 |
| `--export PATH` | 結果をファイルに書き込みます。形式は拡張子から推測されます (`.csv` / `.ndjson` / `.jsonl` / `.json` / `.html`)。ファイルは所有者のみ (`0600`) で書き込まれます。 |
| `--export-format` | エクスポート形式を強制します (`ndjson` / `csv` / `json` / `html`)。 |
| `--timeout N` | リクエストごとのタイムアウト (秒、既定 20)。ARM コントロール プレーン要求 (RBAC 列挙 + Resource Graph 検出) は、実行が遅いため、より長いタイムアウト (`1.5×`、最小 30 秒) を使用します。 |
| `--verbose`, `-v` | すべての Graph/ARM/データプレーン HTTP リクエスト (メソッド、URL、ステータス) を stderr にトレース出力します。 |
| `--no-banner` | ASCII バナーを抑制します。 |
| `--version` | バージョンを出力して終了します。 |

---

## 結果のエクスポート

`--export` は結果を**検出された項目ごとに 1 レコード**にフラット化します — 資格情報、トークン、Graph 権限、アプリ ロールの割り当て、ARM ロール、データプレーンのヒット、およびスコアリングされた検出結果 — それぞれが資格情報コンテキストを保持するため、行だけでも単独で成立します。```bash
# NDJSON — stream into a SIEM / log pipeline
python -m secret_stalker --export results.ndjson

# CSV — open in a spreadsheet for triage
python -m secret_stalker --active --export results.csv

# Full nested JSON to a file
python -m secret_stalker --export results.json

ターミナルレポートと `--export` は併用できます — エクスポートしてもレポートは抑制されません
( "Exported …" の確認は stderr に出力されるため、`--json` をパイプしても
クリーンなままです)。

エクスポートファイルは認証情報のコンテキスト (トークンのクレーム、シークレット `hint`、キー ID) を含むため、
共有または同期されたホストでの漏えいを防ぐために **オーナーのみ（`0600`）** で書き込まれます。
これらを機密のエンゲージメントアーティファクトとして扱ってください。シンボリックリンク経由での書き込みは
全面的に拒否されるため、エクスポートパスを別のファイルの切り詰めに
リダイレクトすることはできません。

結果内の名前は評価対象のテナントから取得されます — アプリとグループの表示名、
コンテナと BLOB の名前 — そのため、信頼できない出力として扱われます。

- **CSV** で数式として読み取られる値（先頭の `=`, `+`, `-`, `@`）には
  シングルクォートが前置されるため、`=cmd|' /C calc'!A0` のような表示名は、
  ファイルをスプレッドシートで開いても実行できません。スプレッドシートは表示時に
  クォートを除去します。

- **ターミナル、CSV、HTML** 出力では制御文字が除去されるため、ANSI エスケープを
  含む名前がターミナルのタイトルを書き換えたり、上にある検出結果を上書きしたり
  することはありません。レポートをライブで読んでも、CSV を `cat` しても、HTML を `cat` しても同様です。

- **JSON / NDJSON は忠実に保持されます**: `json.dumps` は制御文字を
  `\uXXXX` としてエンコードするため、テキストとしては無害であり、パーサーは
  テナントが返した正確な値を往復できます。生の名前は証拠であるため、そこでは保存されます。

---

## 権限 GUID の解決方法

`appRoleAssignments` は GUID として返されます。secret_stalker はフラットなルックアップ
 (appRole GUID はグローバルに一意) でそれらを名前に解決します。これは **ディレクトリの読み取りが
拒否されている場合でも** 機能し続けます。

- 既知の Graph 権限のベストエフォートマップが
  `secret_stalker/data/graph_app_roles.json` に同梱されています。
- `--update-manifest` は、対象テナントからライブで取得した信頼できるデータでそれを上書きします — Microsoft Graph **に加えて、この資格情報が
  割り当てられている他のすべてのリソース API** (例: Exchange Online、SharePoint) も含まれるため、
  非 Graph の GUID も解決されます。
- 不明な GUID は **生のままフラグ付きで** 表示されます — ツールが名前を推測することはありません。

---

## 動作の仕組み（短縮版）

- **1 回のリクエストで有効性と権限を確認。** Graph トークンの `roles` クレームは、
  付与されたアプリケーション権限のリスト *そのものです*。secret_stalker はデコードしたトークンから
  それを読み取ります — 高速かつ静かで、Graph の呼び出しは不要です。
- **Graph ≠ ARM.** これらは異なるトークンオーディエンスです。資格情報が一方に権限を持ち、
  他方には持たない場合があるため、それぞれ独立してプローブされます。
- **データプレーン ≠ コントロールプレーン.** Key Vault に対する ARM 権限 (管理) を持つことは、
  そのシークレットを読み取れること (データプレーン) と同じではありません。`--active` では、
  データプレーンの到達可能性はリソース自身のトークンオーディエンスでテストされ、オブジェクトの
  **名前のみ** をリストします。値や内容は決してリストしません。
- **サーフェスごとのデータプレーンプロービング.** データプレーンの RBAC はオブジェクトタイプ /
  サービスごとに付与されるため、それぞれ独立にプローブされます: Key Vault **secrets / keys /
  certificates**、Storage **blob / file / queue / table**、Cosmos DB
  **databases**。`Storage File Data SMB Share Reader` でありながら blob リーダーではない
  資格情報も、見逃されることなく検出されます。(Cosmos は非標準の AAD REST ヘッダーを使用するため
  **ベストエフォート** です — `denied` の結果はライブアカウントで検証してください。)
- **テナント全体の検出.** リソースは、プリンシパルが参照できるすべてのサブスクリプション (RBAC を尊重) を対象に、単一の Azure Resource Graph
  スイープで見つけられます。ARG が拒否された場合は、サブスクリプションごとのプロバイダー一覧にフォールバックします。レポートはどの
  パスが使用されたかをタグ付けします（`[discovery: resource-graph]` と `per-subscription`）。スイープは
  結果を上限 (リソースタイプあたり 1000 行 × 40 ページ) までページングするため、
  実行は常に終了します。`--verbose` はその上限に達した場合に
  その旨を出力します。
- **重要度マッピング** は `secret_stalker/risk.py` にあります — チームが高インパクトとみなすものを
  調整するには、これを編集します。

---

## プロジェクト構成```
secret_stalker/
  clouds.py      Azure cloud endpoint table (public / usgov / usdod / china)
  auth.py        client_credentials flow + tenant discovery + AADSTS decoding
  jwt_utils.py   local JWT claim extraction
  manifest.py    Graph appRole GUID -> name resolution (bundled + live cache)
  graph.py       service principal lookup + appRole resolution + active probes
  arm.py         management-group / subscription RBAC + resource discovery
  dataplane.py   Key Vault / Storage data-plane reachability probes
  risk.py        permission/role/data-plane -> impact mapping (tune this)
  report.py      terminal + JSON output
  export.py      flatten to NDJSON / CSV / JSON records for ingestion
  util.py        shared HTTP (retry/backoff + safe JSON), pmap parallel map,
                 untrusted-output sanitizing
  banner.py      ASCII banner (stderr only)
  cli.py         orchestration
  data/graph_app_roles.json   bundled permission manifest
tests/           pytest suite (run: pytest)
pyproject.toml   packaging + `secret_stalker` console entry point