# ローカルLLM異常検知システム


Ollamaを使用したZero-shot/Few-shot異常検知システム。ネットワークトラフィック、システムログ、センサーデータの3種類のデータに対応し、CSV形式で簡単にデータを扱えます。

## 📋 目次

- [特徴](#特徴)
- [デモ](#デモ)
- [必要要件](#必要要件)
- [インストール](#インストール)
- [クイックスタート](#クイックスタート)
- [使用方法](#使用方法)
- [ファイル構成](#ファイル構成)
- [詳細ガイド](#詳細ガイド)
- [関数リファレンス](#関数リファレンス)
- [トラブルシューティング](#トラブルシューティング)
- [FAQ](#faq)
- [貢献](#貢献)
- [ライセンス](#ライセンス)

## 特徴

### 🎯 主要機能

- **Zero-shot検知**: 事前学習なしで異常を検出
- **Few-shot検知**: 少数の例を与えて精度向上（推奨）
- **3種類のデータタイプ対応**:
  - 🌐 ネットワークトラフィック（DDoS、ポートスキャン、不正通信など）
  - 📝 システムログ（SQLインジェクション、ブルートフォース、不正アクセスなど）
  - 📊 センサー時系列データ（温度・振動異常、故障予兆など）

### 💡 技術的特徴

- ✅ **CSV形式**: 標準的なCSVファイルで簡単にデータを扱える
- ✅ **カスタマイズ可能**: Few-shotサンプルを独自に編集可能
- ✅ **大量データ対応**: 100件以上のサンプルデータ生成に対応
- ✅ **ローカル実行**: データを外部に送信せず、プライバシー保護
- ✅ **柔軟な設定**: コマンドライン引数で細かく制御可能
- ✅ **マルチモデル対応**: 用途に応じて複数のLLMモデルを選択可能

## デモ

### 実行例

```powershell
# デフォルト設定で実行
PS> python anomaly_detection.py

======================================================================
ローカルLLM異常検知システム (Ollama)
======================================================================

Ollama異常検知システムを初期化中...
✓ 使用モデル: llama3.2:3b
✓ 接続先: http://localhost:11434
✓ 検知モード: few-shot
✓ 分析件数制限: 10件
✓ 対象データ: all

======================================================================
【1. ネットワークトラフィック異常検知】
======================================================================
✓ データ読み込み成功: sample_data/network_traffic.csv (120件)

分析対象: 10件のトラフィック

[few-shot検知実行中...]

LLM分析結果:
[1] 正常: Google DNSへの通常のHTTPS通信
[2] 正常: 社内サーバーへのSSH接続
[3] 異常: Torネットワークへの大量通信（リスクレベル: 高）
    理由: 匿名化ネットワークへの異常な大量データ送信
    推奨対応: 送信元IPの調査とネットワーク制限
...
```

## 必要要件

### システム要件

| 項目 | 最小要件 | 推奨 |
|------|---------|------|
| OS | Windows 11, macOS 10.15, Linux | 最新版 |
| CPU | 2コア以上 | 4コア以上 |
| メモリ | 8GB | 16GB以上 |
| ストレージ | 10GB以上の空き容量 | 20GB以上 |
| GPU | 不要（あると高速化） | NVIDIA GPU |

### ソフトウェア要件

- **Python**: 3.10以上
- **Ollama**: 最新版
- **Pythonライブラリ**: `requests`

## インストール

### ステップ1: Ollamaのインストール

#### macOS / Linux
```bash
$ curl -fsSL https://ollama.com/install.sh | sh
```

#### Windows
PowerShellで実行:
```powershell
PS> winget install Ollama.Ollama
```

または、[公式サイト](https://ollama.com/download)からインストーラーをダウンロード

### ステップ2: Pythonライブラリのインストール

```bash
PS> python -m venv .venv
PS> .venv\Scripts\activate

PS> pip install requests
```

### ステップ3: プロジェクトのZIPをダウンロードして解凍

### ステップ4: 動作確認

```bash
# システム環境をチェック（オプション）
PS> python system_check.py
```

## クイックスタート

### 5分で始める異常検知

#### 1. Ollamaの起動（別ターミナル）

```bash
PS> ollama serve
```

このターミナルは起動したまま維持してください。

#### 2. モデルのダウンロード

```bash
# 推奨モデル（軽量・高速）
PS> ollama pull llama3.2:3b
```

#### 3. Few-shotテンプレートの生成

```bash
PS> python few_shot_examples.py
```

実行結果:
```
======================================================================
Few-shot学習用サンプルファイル生成
======================================================================

✓ CSVファイル保存: few_shot_examples/network_examples.txt
✓ CSVファイル保存: few_shot_examples/log_examples.txt
✓ CSVファイル保存: few_shot_examples/sensor_examples.txt

======================================================================
✓ すべてのテンプレートファイルを生成しました
======================================================================
```

#### 4. サンプルデータの生成

```bash
PS> python generate_sample_data.py
```

実行結果:
```
======================================================================
サンプルデータ生成プログラム（CSV形式）
======================================================================

【1. ネットワークトラフィックデータ生成】
✓ CSVファイル保存: sample_data/network_traffic.csv
   生成件数: 正常=100, 異常=20, 合計=120

【2. システムログデータ生成】
✓ CSVファイル保存: sample_data/system_logs.csv
   生成件数: 正常=150, 異常=30, 合計=180

【3. センサー時系列データ生成】
✓ CSVファイル保存: sample_data/sensor_data.csv
   生成件数: 60データポイント (300分間, 5分間隔)

======================================================================
✓ 全サンプルデータの生成が完了しました
======================================================================
```

#### 5. 異常検知の実行

```bash
PS> python anomaly_detection.py
```

🎉 おめでとうございます！これで異常検知が実行されます。

## 使用方法

### 基本的な使用方法

#### デフォルト実行（Few-shot、10件分析）
```bash
PS> python anomaly_detection.py
```

#### Zero-shot検知
```bash
PS> python anomaly_detection.py --mode zero-shot
```

#### 高精度モデルを使用
```bash
PS> python anomaly_detection.py --model llama3.2:7b
```

### データ量の制御

```bash
# 最初の20件を分析
PS> python anomaly_detection.py --limit 20

# 最初の50件を分析
PS> python anomaly_detection.py --limit 50

# 全件分析（制限なし）
PS> python anomaly_detection.py --limit -1
```

### 特定のデータタイプのみ分析

```bash
# ネットワークトラフィックのみ
PS> python anomaly_detection.py --only network

# システムログのみ
PS> python anomaly_detection.py --only logs

# センサーデータのみ
PS> python anomaly_detection.py --only sensor
```

### カスタムFew-shotの使用

#### 1. テンプレートを編集
```bash
# お好みのエディタで開く
Start-Process notepad few_shot_examples/network_examples.txt
```

自社環境に合わせた正常・異常の例を追加・編集します。

#### 2. カスタムFew-shotで実行
```bash
# ネットワークトラフィックのみカスタム
PS> python anomaly_detection.py \
  --mode few-shot \
  --few-shot-network few_shot_examples/network_examples.txt

# すべてのデータタイプにカスタム指定
PS> python anomaly_detection.py \
  --mode few-shot \
  --few-shot-network few_shot_examples/network_examples.txt \
  --few-shot-log few_shot_examples/log_examples.txt \
  --few-shot-sensor few_shot_examples/sensor_examples.txt
```

### 組み合わせ例

```bash
# 高精度モデルでネットワークトラフィックを全件分析
PS> python anomaly_detection.py \
  --model llama3.2:7b \
  --mode few-shot \
  --only network \
  --limit -1

# カスタムFew-shotでログを30件分析
PS> python anomaly_detection.py \
  --mode few-shot \
  --few-shot-log my_custom_log_examples.txt \
  --only logs \
  --limit 30

# Zero-shotで全データタイプを5件ずつ分析
PS> python anomaly_detection.py \
  --mode zero-shot \
  --limit 5
```

### サンプルデータのカスタマイズ

```bash
# デフォルト設定（正常100件、異常20件など）
PS> python generate_sample_data.py

# カスタム設定で生成
PS> python generate_sample_data.py --traffic-normal 200 --traffic-anomaly 50

# 大量データ生成
PS> python generate_sample_data.py \
  --traffic-normal 1000 \
  --log-normal 2000 \
  --sensor-duration 1440 \
  --sensor-interval 1

```

### ヘルプの表示

```bash
# 異常検知プログラムのヘルプ
PS> python anomaly_detection.py --help

# サンプルデータ生成のヘルプ
PS> python generate_sample_data.py --help
```

## ファイル構成

```
llm-anomaly-detection/
│
├── README.md                      # このファイル
├── LICENSE.md                     # ライセンスファイル
│
├── few_shot_examples.py           # Few-shotサンプル定義
├── generate_sample_data.py        # サンプルデータ生成プログラム
├── anomaly_detection.py           # メイン異常検知プログラム
├── system_check.py                # システム環境チェックツール
│
├── few_shot_examples/             # Few-shotテンプレート（自動生成）
│   ├── network_examples.txt       # ネットワーク用サンプル
│   ├── log_examples.txt           # ログ用サンプル
│   └── sensor_examples.txt        # センサー用サンプル
│
└── sample_data/                   # CSVデータ（自動生成）
     ├── network_traffic.csv        # ネットワークトラフィックデータ
     ├── system_logs.csv            # システムログデータ
     └── sensor_data.csv            # センサーデータ

```

## 詳細ガイド

### CSV形式の仕様

#### ネットワークトラフィック (network_traffic.csv)
```csv
id,src_ip,dst_ip,port,protocol,packets,bytes,label
1,192.168.1.10,8.8.8.8,443,HTTPS,150,45000,normal
2,192.168.1.50,185.220.101.5,9050,TCP,5000,2500000,anomaly
```

**カラム説明:**
- `id`: 連番
- `src_ip`: 送信元IPアドレス
- `dst_ip`: 宛先IPアドレス
- `port`: ポート番号
- `protocol`: プロトコル名（HTTP, HTTPS, SSH, TCP など）
- `packets`: パケット数
- `bytes`: バイト数
- `label`: 正解ラベル（normal/anomaly）※分析には使用しない

#### システムログ (system_logs.csv)
```csv
id,timestamp,level,message,label
1,2025-10-08 10:30:15,INFO,User 'admin' logged in,normal
2,2025-10-08 03:15:45,WARNING,Failed login attempt (attempt 15),anomaly
```

**カラム説明:**
- `id`: 連番
- `timestamp`: タイムスタンプ（YYYY-MM-DD HH:MM:SS形式）
- `level`: ログレベル（INFO, WARNING, ERROR, CRITICAL）
- `message`: ログメッセージ本文
- `label`: 正解ラベル（normal/anomaly）※分析には使用しない

#### センサーデータ (sensor_data.csv)
```csv
id,timestamp,temperature,vibration,label
1,2025-10-08 10:00:00,22.5,0.05,normal
2,2025-10-08 10:30:00,52.3,5.2,anomaly
```

**カラム説明:**
- `id`: 連番
- `timestamp`: タイムスタンプ
- `temperature`: 温度（℃）
- `vibration`: 振動（mm/s）
- `label`: 正解ラベル（normal/anomaly）※分析には使用しない

### モデルの選択ガイド

| モデル | サイズ | メモリ要件 | 速度 | 精度 | 推奨用途 |
|--------|--------|-----------|------|------|----------|
| llama3.2:3b | 3B | 8GB | ⚡⚡⚡ 高速 | ⭐⭐⭐ 中 | リアルタイム検知、開発・テスト |
| llama3.2:7b | 7B | 16GB | ⚡⚡ 中速 | ⭐⭐⭐⭐ 高 | バッチ処理、本番環境 |
| mistral:7b | 7B | 16GB | ⚡⚡ 中速 | ⭐⭐⭐⭐ 高 | 高精度が必要な場合 |

### Zero-shot vs Few-shot

| 検知方式               | 利点                                                      | 欠点                                                | 推奨シーン                                                           |
| ------------------ | ------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------- |
| **Zero-shot検知**    | ✅ 事例なしで即座に検知可能<br>✅ セットアップが簡単<br>✅ 未知の攻撃パターンにも対応可能      | ❌ 精度が低い場合がある<br>❌ 誤検知が多い可能性<br>❌ ドメイン固有の知識を活用できない | ・新しいシステムや未知の脅威<br>・Few-shotサンプルの準備ができていない場合<br>・概要把握や初期調査       |
| **Few-shot検知（推奨）** | ✅ 精度が大幅に向上<br>✅ 誤検知率が低い<br>✅ ドメイン固有の知識を活用<br>✅ カスタマイズ可能 | ❌ 適切な例が必要<br>❌ セットアップに時間がかかる                      | ・既知のパターンがある場合<br>・本番環境での運用<br>・高精度が必要な場合<br>・自社環境に合わせたカスタマイズが必要 |



### カスタムデータの使用

#### 独自のCSVデータを使用する場合

1. **データディレクトリを準備**
```bash
PS> mkdir my_data
```

2. **CSVファイルを作成**（上記の形式に従う）
```bash
# 例: my_data/network_traffic.csv
```

3. **カスタムディレクトリを指定して実行**
```bash
PS> python anomaly_detection.py --data-dir my_data
```

#### プログラムから直接使用

```python
from anomaly_detection import OllamaAnomalyDetector, load_csv_data

# 検知器の初期化
detector = OllamaAnomalyDetector(model_name="llama3.2:3b")

# CSVデータの読み込み
data = load_csv_data("my_data/network_traffic.csv")

# 異常検知実行
result = detector.detect_network_anomaly(data, mode="few-shot")
print(result['raw_response'])
```

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

### Ollamaに接続できない

**エラーメッセージ:**
```
エラー: Ollamaサーバーに接続できません。'ollama serve'を実行してください。
```

**解決方法:**
```bash
# Ollamaが起動しているか確認
PS> ps | Select-String -Pattern "ollama"

# 起動していない場合は起動
PS> ollama serve
```

### モデルがダウンロードされていない

**エラーメッセージ:**
```
Error: model 'llama3.2:3b' not found
```

**解決方法:**
```bash
# 利用可能なモデルを確認
PS> ollama list

# モデルをダウンロード
PS> ollama pull llama3.2:3b
```

### メモリ不足エラー

**症状:**
- モデルが起動しない
- 処理が途中で止まる

**解決方法:**
- より小さいモデル（3b）を使用
```bash
PS> python anomaly_detection.py --model llama3.2:3b
```

- 分析するデータ件数を減らす
```bash
PS> python anomaly_detection.py --limit 5
```

- 他のアプリケーションを終了してメモリを確保

### タイムアウトエラー

**エラーメッセージ:**
```
エラー: タイムアウトしました。
```

**解決方法:**
- より軽量なモデルを使用
- 分析データ件数を減らす
- マシンスペックを確認

### サンプルデータが見つからない

**エラーメッセージ:**
```
✗ ファイルが見つかりません: sample_data/network_traffic.csv
```

**解決方法:**
```bash
# サンプルデータを生成
PS> python generate_sample_data.py
```

### Few-shotファイルが読み込めない

**エラーメッセージ:**
```
⚠️ カスタムFew-shotファイルが見つかりません
```

**解決方法:**
```bash
# Few-shotテンプレートを生成
PS> python few_shot_examples.py

# ファイルパスが正しいか確認
ls few_shot_examples/
```

## FAQ

### Q1: どのモデルを使うべきですか？

**A:** 用途によります：
- **開発・テスト**: `llama3.2:3b`（高速）
- **本番環境**: `llama3.2:7b`（高精度）
- **高精度要求**: `mistral:7b`

### Q2: Zero-shotとFew-shotはどちらが良いですか？

**A:** **Few-shotを推奨**します。精度が大幅に向上します。Zero-shotは未知の脅威や初期調査に適しています。

### Q3: GPUは必要ですか？

**A:** **不要**ですが、あると高速化されます。CPUでも十分動作します。

### Q4: 商用利用できますか？

**A:** はい、MITライセンスで商用利用可能です。ただし、使用するLLMモデルのライセンスも確認してください。

### Q5: 独自データで使用できますか？

**A:** はい、CSV形式で準備すれば使用できます。詳細は[カスタムデータの使用](#カスタムデータの使用)を参照してください。

### Q6: リアルタイム監視に使えますか？

**A:** はい、Pythonスクリプトからライブラリとして使用できます。詳細は[応用例](#応用例)を参照してください。

### Q7: どのくらいのデータ量を処理できますか？

**A:** メモリとモデルにより異なりますが、一度に数百件程度が推奨です。大量データはバッチ処理してください。

## 応用例

### リアルタイム監視システム

```python
import time
from anomaly_detection import OllamaAnomalyDetector

detector = OllamaAnomalyDetector()

while True:
    # センサーからデータ取得（実装は環境に依存）
    sensor_data = read_sensor_data()
    
    # 異常検知
    result = detector.detect_sensor_anomaly(sensor_data, mode="few-shot")
    
    # アラート処理
    if "異常" in result['raw_response']:
        send_alert(result)
    
    time.sleep(60)  # 1分ごとに監視
```

### バッチ処理

```python
from anomaly_detection import OllamaAnomalyDetector, load_csv_data

def analyze_log_file(filepath):
    detector = OllamaAnomalyDetector(model_name="llama3.2:7b")
    logs = load_csv_data(filepath)
    result = detector.detect_log_anomaly(logs, mode="few-shot")
    
    # 結果をファイルに保存
    with open("analysis_result.txt", "w") as f:
        f.write(result['raw_response'])
    
    return result

# 実行
result = analyze_log_file("sample_data/system_logs.csv")
```


## ライセンス
このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。
本プログラムは研究・学習目的での利用を想定しています。
商用利用時は使用するLLM（例: `llama3`）のライセンス条項をご確認ください。

## 参考資料

- [Ollama公式ドキュメント](https://github.com/ollama/ollama)
- [LLama 3.2モデル情報](https://ollama.com/library/llama3.2)
- [LLMによる異常検知の論文](https://arxiv.org/search/?query=llm+anomaly+detection)

## サポート

問題が発生した場合:

1. **ドキュメント確認**: このREADMEとトラブルシューティングセクション
2. **環境チェック**: `python system_check.py` を実行
3. **Issue検索**: 既存のIssueを検索
4. **新規Issue**: 解決しない場合は新規Issueを作成

## 謝辞

- [Ollama](https://ollama.com/)チーム - ローカルLLM実行環境の提供
- [Meta AI](https://ai.meta.com/) - LLama 3.2モデルの開発
- すべての貢献者の皆様

## 更新履歴

### v1.0.0 (2025-10-12)
- 初版リリース
- Zero-shot/Few-shot異常検知機能
- 3種類のデータタイプ対応
- CSV形式サポート
- カスタムFew-shot機能
- 100件以上のサンプルデータ生成

---

