### 環境設定

**重要:** アプリケーションを起動する前に環境変数を設定する必要があります。アプリケーションでは `NEO4J_PASSWORD` の設定が必要です。

プロジェクトルートに `.env` ファイルを作成します：```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

**注意:** `NEO4J_PASSWORD` が設定されていない場合、アプリケーションは起動に失敗します。詳細は [環境変数の修正](https://github.com/blevene/bandjacks/blob/main/ENV_VARIABLES_FIX.md) を参照してください。

### サービスの起動```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

> **注記:** CLIには環境変数（NEO4J_PASSWORDなど）の設定が必要です。`.env`があるプロジェクトルートから実行してください。

### クエリコマンド```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

### 文書抽出```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

### ワークフローコマンド```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

## フロントエンドUI

Next.jsのフロントエンドは、システムを操作するためのモダンなインターフェースを提供します。

### レポート管理 (`/reports`)
- **レポート一覧**: 取り込まれたすべてのレポートをステータスおよびテクニック数とともに表示
- **新規レポート** (`/reports/new`): PDF/TXTファイルのアップロードまたはレポート内容の貼り付け
- **レポート詳細** (`/reports/[id]`): 抽出されたテクニック、エンティティ、証拠を表示
- **レビューインターフェース** (`/reports/[id]/review`): ヒューマンインザループのレビューワークフロー

### 共起分析 (`/analytics/cooccurrence`)

> **注意:** これらのページにはNeo4j内の`AttackEpisode`データが必要です。まず抽出パイプラインを通じてレポートを処理するか、`POST /v1/flows/build`を使用して侵入セットデータからエピソードを生成してください。

- **ハブページ**: エピソード/テクニック/アクターのカウントを含む概要
- **上位ペア** (`/pairs`): NPMI/Liftメトリクスによる共起テクニックペア
- **条件付き確率** (`/conditional`): P(B|A)条件付き確率
- **バンドル** (`/bundles`): 頻繁に共起するテクニックバンドル
- **アクター** (`/actors`): アクター固有のテクニックパターン
- **ブリッジング** (`/bridging`): 複数のアクターにまたがって使用されるテクニック

### システムヘルス (`/health`)
- 全コンポーネント(Neo4j, OpenSearch, Redis)のリアルタイムヘルスステータス
- キャッシュ統計とメモリ使用量
- Kubernetes互換のヘルスエンドポイント

### フロントエンドの起動```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

### 2. レポートからのテクニック抽出

脅威インテリジェンスレポートからMITRE ATT&CKテクニックを抽出します:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## 抽出パイプラインのアーキテクチャ

Bandjacksの抽出パイプラインは、マルチエージェントアーキテクチャを使用して構造化された脅威インテリジェンスを抽出します。

### パイプラインのコンポーネント

抽出パイプラインは9つの特殊なエージェントを順番に使用します。

#### 1. **EntityExtractionAgent** - エンティティ認識
- 脅威アクター、マルウェア、ツール、キャンペーンを抽出
- 最初に実行され、テクニック抽出のためのコンテキストを提供
- JSONスキーマ検証を伴うfew-shotプロンプトを使用
- チャンク分割されたドキュメントを、プログレッシブウィンドウ抽出で処理

#### 2. **SpanFinderAgent** - 行動テキスト検出
- 14の戦術固有の正規表現パターンを使用して、脅威行動を含むテキストスパンを検出
- 明示的なテクニックID（T1566.001）と行動パターンを識別
- キーワードインデックスブーストによる信頼度でスパンをスコアリング
- LLM呼び出しなし — 高速化のための純粋なパターンマッチング

#### 3. **BatchRetrieverAgent** - 候補検索
- OpenSearchのKNNベクトル検索を使用して、スパンごとの候補テクニックを検索
- 冗長な埋め込みを避けるため、同一スパンテキストをエンコード前に重複排除
- スパンごとに上位k件の候補と類似度スコアを返却

#### 4. **プリフィルター** - スパン削減
- 候補テクニックごとにスパンを`max_spans_per_technique`（デフォルト2）に制限
- 候補ごとに最もスコアの高いスパンを保持し、証拠品質を維持
- 最小限のテクニック損失で、マッパーのLLM呼び出しを約46%削減

#### 5. **DiscoveryAgent** - LLM発見（条件付き）
- 検索の信頼度が低い場合（平均0.7未満）に作動
- LLMを使用してベクトル検索が見逃したテクニックを発見
- 低信頼度スパンをすべて1回のバッチ呼び出しで処理

#### 6. **BatchMapperAgent** - テクニックマッピング（LLM）
- 最大10個のグループ（`MAX_MAPPER_BATCH_SIZE`、2026年5月に25からデフォルト低下、クラウドLLMのトランケーションを制限するため）でスパンをバッチ処理
- スパンごとに信頼度スコアとともにすべての関連テクニックを抽出
- 構造化出力のためのJSONスキーマ検証を使用

#### 7. **EvidenceVerifierAgent** - 証拠検証
- 引用と行参照のパターンベース検証
- 証拠品質を40〜100点のスケールでスコアリング
- LLM呼び出しなし — 正規表現とテキストマッチング

#### 8. **ConsolidatorAgent** - 証拠統合
- 複数のスパンにわたって見つかった重複テクニックを統合
- Jaccard類似度（>85%閾値）を使用して証拠を集約
- 統合された信頼度スコアを持つ最終テクニックリストを生成

#### 9. **AttackFlowSynthesizer** - シーケンス生成（LLM）
- 時間マーカー（"first", "then", "after"）を分析
- ナラティブから因果関係を推論
- 確率的エッジを持つSTIX Attack Flowオブジェクトを作成
- シーケンスが不明な場合は共起モデリングにフォールバック

### パフォーマンス最適化

- **スマートチャンク分割**: ドキュメントを2KBチャンクにオーバーラップ付きで分割
- **バッチ処理**: マッパーはLLM呼び出しごとに最大25スパンを処理
- **並列処理**: チャンクはワーカースレッド間で並行処理
- **応答キャッシュ**: LLM応答をキャッシュして重複呼び出しを回避
- **早期終了**: 高信頼度の抽出は検証をスキップ
- **TechniqueCache**: すべてのATT&CKテクニックを起動時にロードしてO(1)ルックアップを実現
- **プリフィルター**: LLMマッパーの前に候補テクニックごとのスパンを制限（呼び出し46%削減）
- **バッチ埋め込み**: テクニック埋め込みをバッチで生成（2〜5倍高速）
- **コネクションプーリング**: リクエスト間でNeo4j/OpenSearch接続を共有
- **UNWINDバッチ**: Neo4j書き込みをUNWIND経由でバッチ化（30〜40クエリ→6〜7）
- **モデル事前ウォームアップ**: 埋め込みモデルを起動時にロードしてコールドスタートレイテンシを回避

### 処理時間

| ドキュメントサイズ | 処理時間 | 抽出されるテクニック数 |
|--------------|-----------------|---------------------|
| 小（5KB未満） | 10〜20秒 | 5〜10テクニック |
| 中（5〜15KB） | 20〜40秒 | 10〜15テクニック |
| 大（15KB超） | 30〜60秒 | 15〜25テクニック |

## 共起分析

Bandjacksはテクニック間の関係を理解するための分析機能を提供します。

> **注:** 分析にはNeo4j内の`AttackEpisode`および`AttackAction`データが必要です。これらは以下の場合に作成されます。
> - レポートが抽出パイプラインを通じて処理された場合
> - 攻撃フローが`/v1/flows/build`経由で構築された場合
> - 攻撃エピソードを含むSTIXバンドルが取り込まれた場合
>
> エピソードが存在しない場合、分析は空の結果を返します。

### グローバル共起

すべての攻撃エピソードにわたって、どのテクニックが頻繁に一緒に出現するかを計算します。```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### テクニックバンドル

頻繁に同時発生するテクニックバンドル（3～5のテクニック）を特定する：```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## 人間参加型レビューシステム

Bandjacks は、抽出されたインテリジェンスを検証するための包括的なレビューシステムを備えています:

### 統合レビューインターフェース

レビューシステムは、抽出されたすべての項目を1つのインターフェースで表示します:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. テクニックの検索

ATT&CK テクニックを自然言語で検索します:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### 6. AttackFlow モデルの生成

脅威アクターがどのようにテクニックを組み合わせて使用するかを示す共起モデルを作成します:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

AttackFlowモデルは、侵入セットに固有のシーケンス情報がないため、逐次順序ではなく**共起**を使用します。テクニックは以下のように接続されます。
- **戦術内エッジ**: 同じキルチェーン戦術内のテクニック間
- **戦術間エッジ**: 隣接する戦術間のテクニック間
- **ハブ＆スポークパターン**: エッジ爆発を避けるための大規模テクニックセット用

詳細な使用方法については、[AttackFlow生成ガイド](https://github.com/blevene/bandjacks/blob/main/docs/ATTACKFLOW_GENERATION.md)を参照してください。

## サポートされる入力形式

抽出パイプラインは複数の入力形式をサポートしています。

- **プレーンテキスト** - 直接的なテキストコンテンツ
- **Markdown** - 整形されたMarkdown文書
- **PDF** - pdfplumberによる抽出
- **HTML** - BeautifulSoupによる解析
- **JSON** - 構造化データの抽出

### プレーンテキストからの抽出```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### PDFから抽出```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### 攻撃フローの構築```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## API エンドポイント

### コアエンドポイント

- `POST /v1/stix/load/attack` - MITRE ATT&CK データを読み込む
- `POST /v1/reports/ingest` - 同期レポート取り込み（5KB未満）
- `POST /v1/reports/ingest_async` - 非同期レポート取り込み（5KB超）
- `POST /v1/reports/ingest/upload` - PDF/TXTファイルをアップロード
- `GET /v1/reports/jobs/{id}/status` - ジョブステータスを確認
- `POST /v1/reports/{id}/unified-review` - レビュー判定を送信
- `POST /v1/search/ttx` - 手法を検索
- `GET /v1/graph/technique/{id}` - 手法の詳細を取得

### アタックフロー

- `POST /v1/flows/build` - AttackFlow共起モデルを生成
- `GET /v1/flows/{flow_id}` - 特定のAttackFlowの詳細を取得
- `POST /v1/flows/search` - 類似のアタックフローを検索
- `GET /v1/flows/dump` - フローをページネーションとフィルタリングで一括エクスポート

### 分析

- `GET /v1/analytics/cooccurrence/global` - グローバル共起メトリクス
- `GET /v1/analytics/cooccurrence/conditional` - 条件付き確率
- `GET /v1/analytics/cooccurrence/bundles` - 手法バンドル
- `GET /v1/analytics/cooccurrence/actor` - アクター固有パターン
- `GET /v1/coverage/gaps` - 手法のカバレッジギャップ

### 防御と検知

- `GET /v1/defense/technique/{id}` - 防御推奨事項を取得
- `GET /v1/detections/technique/{id}` - 検知戦略
- `POST /v1/sigma/validate` - Sigmaルールを検証

### モニタリング

- `GET /health` - 基本ヘルスチェック
- `GET /health/live` - Kubernetes livenessプローブ
- `GET /health/ready` - Kubernetes readinessプローブ
- `GET /health/components/{component}` - 個別コンポーネントヘルス
- `GET /v1/costs/stats` - LLMコスト追跡（モデル別日次集計）
- `GET /v1/cache/stats` - LLMキャッシュ統計を取得
- `POST /v1/cache/clear` - LLMキャッシュをクリア
- `GET /v1/compliance/report` - コンプライアンスメトリクス
- `GET /v1/drift/status` - ドリフト検出ステータス
- `GET /v1/ml-metrics/performance` - MLモデルメトリクス

### アクターと来歴

- `GET /v1/actors` - 脅威アクター一覧
- `GET /v1/actors/{id}` - アクター詳細を取得
- `GET /v1/provenance/{object_id}` - オブジェクトの来歴
- `GET /v1/provenance/{object_id}/lineage` - 完全な系統連鎖
- `GET /v1/provenance/{object_id}/evidence` - 証拠スニペット

### API専用機能（UI/CLIなし）

これらのエンドポイントは完全に機能しますが、REST API経由でのみアクセス可能です（フロントエンドページやCLIコマンドはありません）。

#### 攻撃経路シミュレーション
- `POST /v1/simulation/paths` - 開始手法/グループから攻撃経路をシミュレート
- `POST /v1/simulation/predict` - 現在の状態から次に起こり得る手法を予測
- `POST /v1/simulation/whatif` - 防御シナリオのWhat-if分析
- `POST /v1/simulation/scenario` - グループ/ソフトウェア/手法のセットからシミュレート
- `GET /v1/simulation/statistics/{technique_id}` - 手法使用統計
- `GET /v1/simulation/groups/{group_id}/patterns` - グループ攻撃パターン
- `POST /v1/simulation/compare` - 複数の攻撃経路を比較

#### MDPポリシーとロールアウト
- `POST /v1/simulate/rollout` - PTGロールアウトシミュレーション
- `POST /v1/simulate/mdp` - MDP最適防御ポリシーを計算
- `GET /v1/simulate/models` - 利用可能なPTGモデル一覧

#### ドリフト検出とモニタリング
- `GET /v1/drift/status` - 全メトリクスにおける現在のドリフトステータス
- `POST /v1/drift/analyze` - カスタム閾値でドリフト分析を実行
- `GET /v1/drift/alerts` - アクティブなドリフトアラートを取得
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - アラートを確認
- `GET /v1/drift/metrics/{metric_name}` - 特定のドリフトメトリクスを取得

#### MLメトリクス追跡
- `POST /v1/ml-metrics/prediction` - 追跡用にモデル予測を記録
- `POST /v1/ml-metrics/review` - レビュー判定メトリクスを記録
- `POST /v1/ml-metrics/coverage-gap` - カバレッジギャップを記録
- `GET /v1/ml-metrics/performance` - モデルパフォーマンスメトリクスを取得
- `GET /v1/ml-metrics/dashboard` - ダッシュボードメトリクスをエクスポート

#### 通知
- `GET /v1/notifications/history` - 通知履歴を取得
- `POST /v1/notifications/clear-history` - 通知履歴をクリア
- `GET /v1/notifications/config` - 通知設定を取得
- `POST /v1/notifications/test` - テスト通知を送信

#### ベクター更新管理
- `GET /v1/vectors/status` - ベクター更新システムステータス
- `GET /v1/vectors/metrics` - ベクター更新の詳細メトリクス
- `POST /v1/vectors/update` - ベクター更新を手動トリガー
- `POST /v1/vectors/process-batch` - バッチ処理を強制実行
- `DELETE /v1/vectors/queue` - 保留中の更新キューをクリア
- `GET /v1/vectors/health` - ベクターシステムヘルスチェック

#### エンティティ無視リスト
- `GET /v1/ignorelist` - 現在の無視リストステータスを取得
- `POST /v1/ignorelist/add` - エンティティを無視リストに追加
- `DELETE /v1/ignorelist/remove` - エンティティを無視リストから削除
- `POST /v1/ignorelist/reload` - 無視リストをディスクから再読み込み

#### 候補パターンレビュー
- `GET /v1/review/candidates` - 候補攻撃パターン一覧
- `POST /v1/review/candidates` - 候補パターンを作成
- `GET /v1/review/candidates/{id}` - 候補詳細を取得
- `POST /v1/review/candidates/{id}/approve` - 候補を承認
- `POST /v1/review/candidates/{id}/reject` - 候補を却下
- `GET /v1/review/candidates/{id}/similar` - 類似パターンを検索
- `GET /v1/review/candidates/stats/summary` - 候補統計

### 完全なAPIドキュメント

完全なAPIドキュメントは以下からアクセスできます：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## アーキテクチャ

### プロジェクト構造```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**プロバイダ優先順位:** ローカルAPI > Gemini > OpenAI > LiteLLMプロキシ。
ローカルサーバーが設定されている場合、クラウドプロバイダは自動的にフォールバックとして追加されます。

#### 一般的なローカルサーバーの例

| サーバー | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### 抽出設定

システムは、設定可能なオプションを持つ単一の高性能非同期パイプラインを使用します:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### 信頼度しきい値

抽出品質を制御:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### ヘルス応答例```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## パフォーマンス最適化

### キャッシング

システムには、パフォーマンス向上のための自動LLM応答キャッシングが含まれています：```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## セキュリティ

### 入力検証

- **Cypher Injection Prevention**: すべてのグラフクエリエンドポイントは、ユーザーが指定した `relationship_types` パラメータを、既知のリレーションタイプ（USES, MITIGATES, HAS_TACTIC など）の許可リストと厳格な正規表現パターン（`^[A-Z][A-Z0-9_]*$`）に対して検証します。無効な入力は、クエリ構築前に400を返します。
- **JSON Schema Validation**: LLMの応答はJSONスキーマに対して検証され、不正なデータがパイプラインに入るのを防ぎます。
- **ADM Validation**: すべてのSTIXコンテンツは、取り込み前にATT&CKデータモデルの検証を通過する必要があります。

### 認証と認可

- **JWT Authentication**: API認証用のオプショナルミドルウェア (`JWTAuthMiddleware`)
- **Rate Limiting**: 設定可能なしきい値を持つエンドポイントごとのレート制限
- **CORS**: 設定可能なクロスオリジンリソース共有

## 高度な機能

### 来歴追跡

抽出されたすべてのエンティティには完全な来歴が含まれます:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### カバレッジ分析

脅威インテリジェンスのカバレッジを分析してください：```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## 機能ステータス

このセクションでは、さまざまな機能の実装状況を透明性をもって示します。

### 完全に機能 ✅
- **レポート抽出パイプライン** - LLMベースの手法抽出がエンドツーエンドで動作
- **MITRE ATT&CK ローディング** - エンタープライズ/モバイル/ICS ATT&CKデータをNeo4jにロード
- **ベクトル検索** - 手法のためのOpenSearchベースのセマンティック検索
- **レビューシステム** - APIとUIを介したヒューマン・イン・ザ・ループのレビューワークフロー
- **ヘルスモニタリング** - コンポーネントの健全性チェックとKubernetesプローブ
- **CLI クエリ/管理コマンド** - 検索、グラフトラバーサル、キャッシュ管理
- **攻撃フロー生成** - 侵入セットの共起ベースのフロー構築
- **攻撃シミュレーション** - `/simulation/*` および `/simulate/*` を介したMDPベースのパスシミュレーション
- **カバレッジレポート** - エグゼクティブ、テクニカル、戦術、運用ビュー向けのJSONレポート

### データ依存あり ⚠️
- **共起分析** - レポート処理からの `AttackEpisode` ノードが必要
- **アクター分析** - 侵入セットに帰属するエピソードが必要
- **手法バンドル** - パターンマイニングに十分なエピソードデータが必要
- **CLI分析コマンド** - 動作はするが、エピソードが存在しない場合は空を返す

### APIのみ (UI/CLIなし) 🔌
これらはREST APIを介してのみアクセス可能な完全実装機能です：
- **攻撃パスシミュレーション** - パス予測とwhat-if分析のための `/simulation/*` ルート
- **MDPポリシーソルバー** - 最適な防御ポリシー計算のための `/simulate/mdp`
- **ドリフト検出** - データ品質のドリフト監視のための `/drift/*` ルート
- **MLメトリクス** - モデル性能の経時追跡のための `/ml-metrics/*`
- **ベクトル管理** - ベクトル埋め込み管理のための `/vectors/*`
- **エンティティ無視リスト** - 偽陽性エンティティをフィルタリングするための `/ignorelist/*`
- **候補パターン** - 新規手法候補のための `/review/candidates/*`
- **通知** - アラート設定と履歴のための `/notifications/*`
- **来歴** - 抽出系統追跡のための `/provenance/*`
- **コンプライアンス** - コンプライアンス指標レポートのための `/compliance/*`

### 実験的 (`llm/experimental/` 内) 🧪
- **PTG (確率的脅威グラフ)** - コアロジック実装済み、限定的なテスト
- **Judge統合** - LLMベースのシーケンス検証
- **攻撃フローシミュレーター** - フローベースのシミュレーションエンジン
- **シーケンス抽出器** - フローからのシーケンス抽出

### 削除/クリーンアップ済み 🗑️
以下のスタブ機能はAPIから削除されました：
- ~~プラットフォームカバレッジ分析~~ - ハードコードされたスタブデータを返していた
- ~~トレンド分析~~ - ランダムな合成データを返していた
- ~~CSV/PDFレポートエクスポート~~ - 501を返していた；現在はJSONのみ
- ~~Geminiシーケンス推論~~ - 501スタブだった；代わりに `/sequence/propose` を使用

### 接続性マトリックス

| 機能領域 | フロントエンドUI | CLI | REST API |
|--------------|-------------|-----|----------|
| レポート管理 | ✅ | ✅ | ✅ |
| レビューワークフロー | ✅ | ✅ | ✅ |
| 検索 (TTX) | ✅ | ✅ | ✅ |
| 共起分析 | ✅ | ✅ | ✅ |
| カバレッジ分析 | ✅ | - | ✅ |
| ヘルスモニタリング | ✅ | - | ✅ |
| 検出/Sigma | ✅ | - | ✅ |
| 攻撃フロー | ✅ | - | ✅ |
| 防御オーバーレイ | ✅ | - | ✅ |
| シーケンス/PTG | ✅ | - | ✅ |
| アクター | ✅ | - | ✅ |
| 攻撃シミュレーション | - | - | ✅ |
| ドリフト検出 | - | - | ✅ |
| MLメトリクス | - | - | ✅ |
| ベクトル管理 | - | - | ✅ |
| エンティティ無視リスト | - | - | ✅ |
| 候補パターン | - | - | ✅ |
| 通知 | - | - | ✅ |
| 来歴 | - | - | ✅ |
| コンプライアンス | - | - | ✅ |

### フロントエンドページ
| ページ | ステータス | 備考 |
|------|--------|-------|
| `/reports` | ✅ 動作中 | レポートの一覧、作成、表示 |
| `/reports/[id]/review` | ✅ 動作中 | 完全なレビューワークフロー |
| `/analytics/cooccurrence` | ⚠️ データ依存 | エピソードが存在すればKPIを表示 |
| `/analytics/cooccurrence/pairs` | ⚠️ データ依存 | 実際のAPIを呼び出す |
| `/analytics/cooccurrence/bundles` | ⚠️ データ依存 | 実際のAPIを呼び出す |
| `/analytics/cooccurrence/actors` | ⚠️ データ依存 | 実際のAPIを呼び出す |
| `/health` | ✅ 動作中 | リアルタイムの健全性ステータス |

## トラブルシューティング

### よくある問題

1. **OpenSearch接続失敗**
   - OpenSearchが実行中であることを確認：`curl http://localhost:9200`
   - インデックスが存在することを確認：`curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Neo4j接続失敗**
   - Neo4jが実行中であることを確認：`neo4j status`
   - `.env` ファイルに `NEO4J_PASSWORD` が設定されていることを確認
   - パスワードがNeo4jインスタンスと一致することを確認
   - 「NEO4J_PASSWORD環境変数が必要です」と表示された場合、`.env` ファイルに設定する必要があります

3. **抽出再現率が低い**
   - `agentic_v2` メソッドを使用していることを確認
   - LLM APIキーが有効であることを確認
   - モデル名が正しいことを確認 (gemini-flash-latest)

4. **タイムアウトエラー**
   - 大きなドキュメントにはタイムアウト設定を増やす
   - 非常に大きなレポートはチャンク化を検討

5. **フロントエンドがAPIに接続しない**
   - APIがポート8000で実行中であることを確認
   - API設定のCORS設定を確認

### デバッグモード

詳細なログを有効にする：```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### コントリビューション

1. リポジトリをフォークする
2. フィーチャーブランチを作成する
3. 変更を加える
4. テストを実行: `uv run pytest`
5. リンティングを実行: `uv run ruff check`
6. プルリクエストを送信する

### コード品質```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks