│              │              │           │         │
      └──────────────┴──────────────┴───────────┴─────────┘
                       │
                       ▼
              ┌─────────────────┐
              │   SQLite DB     │
              │  (40+ Columns)  │
              └────────┬────────┘
                       │
    ┌──────────────────┼──────────────────┐
    ▼                  ▼                  ▼

### データ処理パイプライン

1. **発見フェーズ** (設定可能な間隔、デフォルト30分)
   - Shodanスキャン（設定可能なクエリ）
   - CVE相関を用いたNVDエンリッチメント
   - コンテキストのための内部システムエンリッチメント

2. **分析フェーズ**
   - 40以上の属性からの特徴量エンジニアリング
   - アンサンブルモデル予測（ランダムフォレスト40% + 勾配ブースティング40% + MLP 20%）
   - リスクラベル生成（0=低、1=中、2=高）
   - 信頼度スコアリング

3. **アラートフェーズ**
   - 新しい高リスク資産の確認
   - SendGrid経由でのメールアラートの生成と送信
   - 通知ステータスの更新

4. **モデル再トレーニング** (設定可能な間隔、デフォルト60分)
   - すべての履歴データの読み込み
   - 特徴量の抽出
   - バランスの取れたクラス重みでアンサンブルをトレーニング
   - パフォーマンスメトリクスの検証
   - 監査用のメタデータ保存

---

## 📋 はじめに

### 前提条件
- **Python**: 3.9以降
- **APIキー** (必須):
  - Shodan APIキー (https://www.shodan.io/)
  - SendGrid APIキー (https://sendgrid.com/) - メールアラート用
- **オプションのAPIキー** (拡張エンリッチメント用):
  - CMDBエンドポイントと認証情報
  - SIEMエンドポイントと認証情報
  - パッチ管理システムのエンドポイントと認証情報
  - ネットワーク監視エンドポイントと認証情報

### インストール

#### ステップ1: リポジトリのクローン```bash
git clone https://github.com/EclipseManic/ThreatSentry-AI.git
cd ThreatSentry-AI

#### ステップ3: 依存関係のインストール```bash
pip install -r requirements.txt

`.env` をあなたの認証情報で編集してください:```ini
# Required - Threat Discovery
SHODAN_API_KEY=your_shodan_api_key_here
SHODAN_QUERY=                          # Leave empty to use presets
SHODAN_QUERY_EMPTY_TO_PRESET=True      # Use preset queries when SHODAN_QUERY is empty

# Optional - Email Alerts
SENDGRID_API_KEY=your_sendgrid_key_here
[email protected]    # Must be verified in SendGrid
[email protected],[email protected]

# Optional - Internal Enrichment (Implement in collectors/)
CMDB_API_ENDPOINT=https://cmdb.internal/api
CMDB_API_KEY=your_cmdb_key
SIEM_API_ENDPOINT=https://siem.internal/api
SIEM_API_KEY=your_siem_key

# Configuration
SCAN_INTERVAL_MINUTES=30               # How often to scan for new assets
RETRAIN_INTERVAL_MINUTES=60            # How often to retrain the model
MAX_SHODAN_RESULTS=50                  # Results per Shodan query
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR

# Paths (Optional)
SQLITE_PATH=data/db/threat_sentric_ai.db
MODEL_PATH=data/models/rf_model.pkl
LOG_FILE_PATH=data/logs/threat_sentric_ai.log

#### ステップ6: アプリケーションを実行する```bash
python run.py

#### カスタム内部コレクター
`collectors/` ディレクトリに実装:
1. 既存のコレクターからテンプレートをコピーする
2. `_collect()` メソッドを自身のAPI呼び出しで更新する
3. エンリッチメントデータを返す
4. スケジューラーに登録する (`core/scheduler.py`)

#### メールアラートのカスタマイズ
`alerts/email_alerts.py` を編集:
- ブランドメール用にHTMLテンプレートを修正
- カスタムリスク要因の説明を追加
- 修復推奨事項を調整

---

## 📊 データモデル

### デバイステーブル (40+列)```
Core Identifiers:  ip, org, country, first_seen, last_seen
Vulnerability:     cve_count, max_cvss, vulnerabilities (rel)
Security Metrics:  auth_failures_24h, traffic_anomaly_score, patch_lag_days
Risk Assessment:   risk_label, risk_score, confidence_score
Context:          network_segment, service_category, is_critical_service
Compliance:       compliance_requirements, data_sensitivity_level
Historical:       incident_history_count, last_compromise_date, false_positive_count
Alerting:         notified, alert_history

---

## 🔄 ワークフロー例

### シナリオ1：日々の脅威ハンティング
1. ダッシュボードを開く → Risk=High（赤）のデバイスを確認
2. デバイスをクリック → 詳細なCVEリストを表示
3. 組織とインフラストラクチャタイプを確認
4. SIEMと照らし合わせて最近の不審なアクティビティを確認
5. 重大度とパッチ適用遅延に基づいて対応優先順位を決定

### シナリオ2：インシデント対応
1. 新しい高リスクデバイスに関するアラートを受信
2. ダッシュボードに脆弱性詳細とリスク要因が表示される
3. Asset Managementタブを確認 → デバイスが既知かどうかを確認
4. SOCオンコールチームに手動アラートを送信
5. 対応後、Shodanの反映に合わせてダッシュボードが自動更新

### シナリオ3：リスクレポート作成
1. Analyticsタブに移動
2. リスク分布とトレンドグラフをエクスポート
3. 組織のリスクホットスポットを特定
4. 改善ロードマップを生成
5. 定期的な再エクスポートで経過を追跡

---

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

### よくある問題

#### 問題：「Shodan API Key が無効」(403 Forbidden)
- **解決策**: `.env` ファイル内のShodan APIキーを確認。ダッシュボードにはエラーが表示されるが処理は継続
- **注意**: NVDエンリッチメントは実行されない（API障害時のデータ損失を防止）

#### 問題：「デバイスにCVEが見つからない」
- **解決策**: バナー抽出を確認。`collectors/nvd_collector.py` のキーワードリストを編集
- **予防**: CSVアップロードによる手動エンリッチメントでCVEデータを手動設定

#### 問題：「モデルの信頼度が低すぎる」
- **解決策**: より多くのラベル付きデータで再学習。誤分類デバイスにフィードバックを提供
- **予防**: フィードバックシステムを活用してトレーニングデータの品質を向上

#### 問題：メールアラートが送信されない
- **解決策**: SendGrid APIキーと送信元メールアドレスが確認済みであることを確認
- **確認**: `ENABLE_EMAIL_ALERTS` 環境変数がTrueに設定されていること

#### 問題：データベースがロックまたはクエリが遅い
- **解決策**: インデックスが作成されていることを確認（init_db()で実行）
- **確認**: 重複したデータベース接続がないこと（UIリフレッシュのみ、常時書き込みは行わない）

---

## 🛡️ セキュリティに関する考慮事項

1. **APIキー管理**: 環境変数を使用し、`.env` をGitにコミットしない
2. **データベースセキュリティ**: SQLiteはシングルユーザー向け。マルチユーザーの場合はPostgreSQLに移行
3. **ネットワークセキュリティ**: 信頼できるネットワーク上で実行。APIを公開する場合はネットワークセグメンテーションを実装
4. **データプライバシー**: ログローテーションを設定してディスク容量を制限。データ保持ポリシーを実装
5. **監査ログ**: すべてのモデル判定は特徴量値とともにログに記録され、監査が可能

---

## 📈 パフォーマンス最適化のヒント

| 問題 | 解決策 |
|-------|----------|
| ダッシュボードの読み込みが遅い | 設定でページネーションサイズを増やす |
| トレーニング中のCPU高負荷 | `model/advanced_model.py` の `n_estimators` を減らす |
| メモリ使用量が多い | ログクリーンアップを有効にし、チャート解像度を下げる |
| Shodanスキャンが遅い | `MAX_SHODAN_RESULTS` を減らし、より具体的なクエリを使用 |
| NVDエンリッチメントが遅い | APIキャッシュを実装し、製品キーワード抽出を減らす |

---

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

コントリビューションを歓迎します！ ガイドラインは [CONTRIBUTING.md](https://raw.githubusercontent.com/eclipsemanic/threatsentry-ai/HEAD/CONTRIBUTING.md) をご覧ください。

改善が期待される領域：
- 追加のコレクター実装（Nessus、Tenable、Qualysとの統合）
- プログラムアクセスのためのWeb API
- ロールベースアクセスによるマルチユーザーサポート
- 高度な可視化（Grafana/ELK統合）
- Kubernetesデプロイメントサポート

---

## 📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細は [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) ファイルをご覧ください。

---

## 📞 サポートとコンタクト

- **Issue**: バグ報告や機能リクエストはGitHub Issuesへ
- **ドキュメント**: 詳細な技術ドキュメントは [docs/](https://github.com/eclipsemanic/threatsentry-ai/blob/main/docs) ディレクトリを参照
- **メール**: メンテナー情報は [CODE_OF_CONDUCT.md](https://github.com/eclipsemanic/threatsentry-ai/blob/main/CODE_OF_CONDUCT.md) に記載

---

## 🙏 謝辞

- **Shodan**: インターネットに露出したデバイスの包括的な発見に感謝
- **NVD/NIST**: 信頼性の高い脆弱性データに感謝
- **Scikit-learn**: 堅牢なMLライブラリとドキュメントに感謝
- **PyQt5**: 優れたGUIフレームワークに感謝
- **コミュニティ**: フィードバックを提供してくださったすべてのコントリビューターとユーザーに感謝

---

**EclipseManic が ❤️ を込めて制作 | 明日のインフラを今日から守る**
pip install -r requirements.txt```

---

## 🔐 Configuration

### 1. Environment Variables (`.env` file)
Create a `.env` file in the root directory with the following structure:

```bash
# --- Shodan API キー (必須) ---
SHODAN_API_KEY="YOUR_SHODAN_API_KEY"

# --- SendGrid メールアラート (必須) ---
SENDGRID_API_KEY="YOUR_SENDGRID_API_KEY"
SENDER_EMAIL="[email protected]"
ALERT_RECIPIENTS="[email protected],[email protected]"

# --- データベース ---
SQLITE_PATH="threat_sentric_ai.db"

# --- モデル ---
MODEL_PATH="threatsentry_model.pkl"

# --- スケジューラー ---
SCAN_INTERVAL_MINUTES="30"
RETRAIN_INTERVAL_MINUTES="60"
RETRAIN_ON_SCHEDULE="True"

# --- Shodan クエリ動作制御 ---
SHODAN_QUERY=""
SHODAN_QUERY_EMPTY_TO_PRESET="True"

# --- ロギング ---
LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL

# --- 内部システム認証情報 (オプション - コレクターに応じて追加) ---
# CMDB_API_ENDPOINT="..."
# CMDB_API_KEY="..."
# SIEM_API_ENDPOINT="..."
# SIEM_API_KEY="..."
# PATCH_API_ENDPOINT="..."
# PATCH_API_KEY="..."
# NETWORK_MONITOR_ENDPOINT="..."
# NETWORK_MONITOR_KEY="..."```

> The app loads environment variables via `os.getenv()` in `config.py`.  
> Never commit this file to version control.

---

## 🔍 Shodan Query Presets (`config.py`)

Modify the `SHODAN_QUERIES` dictionary to define your custom query presets:

```python
SHODAN_QUERIES = {
    "default": "product:apache",
    "org": 'org:"Your Company Name"',
    "net": 'net:"123.45.67.0/24"',
    "ssl": 'ssl:"yourcompany.com"',
    "hostname": 'hostname:".yourcompany.com"',
    "rdp": 'port:3389 "remote desktop"',
    "mongodb": 'port:27017 "mongodb"',
    "ics_modbus": 'port:502 "modbus"',
    "vuln_example": 'vuln:CVE-2024-12345',
    "http_login": 'http.title:"Login" org:"Your Company"'
}```

If `SHODAN_QUERY` in `.env` is empty **and** `SHODAN_QUERY_EMPTY_TO_PRESET=True`,  
the scheduler will automatically cycle through these presets.

---

## 🧠 Implementing Internal Collectors

> ⚠️ **Important:** The internal collectors (`cmdb_collector.py`, `siem_collector.py`, `patch_collector.py`, `network_monitor_collector.py`) are **placeholders**.  
> Replace the placeholder logic with real integrations to your systems.

You’ll need to:
- Fetch internal data using APIs, databases, or SDKs.
- Map fetched data to the `Device` model attributes.
- Update the database session with this enriched information.

Without these integrations, the model will lack context for accurate predictions.

---

## 🧪 Running the Application

### (Optional) Generate Initial Training Data
```bash
python scripts/generate_realistic_training_data.py --count 1000```
Creates `scripts/my_training_data.json`.  
You can upload this file through the GUI’s **Upload** option to initialize training data.

### Launch the Application
```bash
python run.py```
The GUI will open and the scheduler will start scanning, enriching, and predicting automatically.

---

## ⚡ Quick Demo with Generated Data

1. Complete installation (steps 1–3).  
2. Set up your `.env` file (even with placeholder keys).  
3. Optionally adjust Shodan presets in `config.py`.  
4. Generate data:
   ```bash
python scripts/generate_realistic_training_data.py --count 500   ```
5. Launch the app:
   ```bash
python run.py   ```
6. In the GUI:
   - Select **Upload** → Choose `scripts/my_training_data.json`
   - Click **Refresh** to view populated device data and risk levels.

---

## 🛠️ Scripts and Usage Guide

| Script | Description |
|--------|--------------|
| **run.py** | Main entry point. Starts DB, scheduler, and GUI. |
| **scheduler.py** | Handles periodic scanning, enrichment, prediction, and retraining. |
| **scripts/generate_realistic_training_data.py** | Generates realistic training data for testing or bootstrapping. |
| **scripts/clear_db_enhanced.py** | Interactively clean database or reset notification flags. |
| **scripts/reset_db.py** | Completely resets the database. Use with caution. |

### Example Commands

```bash
# 1000件のレコードを生成
python scripts/generate_realistic_training_data.py --count 1000

# クリーンアップオプションを表示
python scripts/clear_db_enhanced.py --help

# すべてのデバイスと脆弱性を削除
python scripts/clear_db_enhanced.py --delete-devices --delete-vulns

# 通知フラグをリセット
python scripts/clear_db_enhanced.py --reset-notified

# 危険な完全リセット
python scripts/reset_db.py```

---

## 💬 Feedback & Suggestions

This project was developed by **EclipseManic**.  
While code contributions are currently closed, your **feedback and bug reports** are highly appreciated.

Please open an [Issue](https://github.com/EclipseManic/ThreatSentry-AI/issues) to share your thoughts or report a problem.

---

## 📄 License

This project is licensed under the **MIT License**.  
See the [LICENSE](https://github.com/eclipsemanic/threatsentry-ai/blob/main/LICENSE) file for details.