# IBM QRadar SIEM MCP Server

Model Context Protocol (MCP) Server cho hệ thống **IBM QRadar SIEM**, được xây dựng trên nền tảng **Python FastMCP** và SDK [PyRadar](https://github.com/binhnguyen143/PyRadar).

Server này cho phép các ứng dụng AI Agent (như Antigravity IDE, Claude Desktop, Cursor...) trực tiếp:
- Tra cứu, phân tích và cập nhật các cảnh báo bảo mật (**Offenses**).
- Chạy các câu truy vấn log và flow chuyên sâu bằng ngôn ngữ **AQL (Ariel Query Language)**.
- Quản lý danh sách chỉ số đe dọa (**Reference Sets / IoCs** như IP, Domain, Hash).
- Tự động kiểm tra trạng thái kết nối SIEM Console.

---

## 1. Cài đặt môi trường

### Yêu cầu
- Python >= 3.10
- Git

### Tạo Virtual Environment & Cài đặt thư viện

```bash
# Tạo môi trường ảo
python -m venv .venv

# Kích hoạt môi trường (Windows PowerShell)
.\.venv\Scripts\Activate.ps1
# Hoặc trên Linux/macOS:
# source .venv/bin/activate

# Cài đặt các gói phụ thuộc (bao gồm PyRadar SDK trực tiếp từ Git)
pip install -r requirements.txt
```

---

## 2. Cấu hình biến môi trường

Tạo file `.env` từ file mẫu `.env.example`:

```bash
cp .env.example .env
```

Điền các thông số QRadar của bạn vào `.env`:

```ini
# Thông tin QRadar Console
QRADAR_HOST=192.168.1.100
QRADAR_PORT=443
QRADAR_SEC_TOKEN=your-authorized-service-token-here

# Tùy chọn chứng chỉ SSL (false nếu dùng SSL self-signed nội bộ)
QRADAR_VERIFY_SSL=false
QRADAR_API_VERSION=26.0

# Ariel Query Settings
DEFAULT_AQL_WAIT_TIMEOUT=60
DEFAULT_AQL_POLL_INTERVAL=2
DEFAULT_PAGE_SIZE=50
```

---

## 3. Cấu hình kết nối MCP Client

### A. Dành cho Claude Desktop (`claude_desktop_config.json`)

Mở `%APPDATA%\Claude\claude_desktop_config.json` và thêm cấu hình server:

```json
{
  "mcpServers": {
    "qradar-siem": {
      "command": "C:\\Users\\<username>\\Documents\\Repos\\1.Automation_SIEM\\MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "qradar_mcp.server"
      ],
      "cwd": "C:\\Users\\<username>\\Documents\\Repos\\1.Automation_SIEM\\MCP"
    }
  }
}
```

### B. Dành cho Antigravity IDE / Cursor / Generic MCP Hosts (`mcp_config.json`)

```json
{
  "mcpServers": {
    "qradar-siem": {
      "command": "python",
      "args": ["-m", "qradar_mcp.server"],
      "env": {
        "QRADAR_HOST": "qradar.corp.internal",
        "QRADAR_SEC_TOKEN": "your-token",
        "QRADAR_VERIFY_SSL": "false"
      }
    }
  }
}
```

---

## 4. Danh sách MCP Tools khả dụng (27 Tools)

| Nhóm | Tên Tool | Mô tả |
| :--- | :--- | :--- |
| **System** | `qradar_health_check` | Kiểm tra kết nối HTTPS và tính hợp lệ của token tới QRadar Console. |
| **Offenses** | `qradar_list_offenses` | Lấy danh sách offenses theo bộ lọc (mặc định status OPEN, sort theo start_time). |
| | `qradar_get_offense` | Lấy chi tiết thông tin 1 offense theo ID (attacker IP, target IP, category, magnitude). |
| | `qradar_add_offense_note` | Thêm ghi chú điều tra của Analyst vào offense. |
| | `qradar_update_offense` | Cập nhật offense (gán analyst, đóng offense với closing reason, bật follow-up). |
| | `qradar_list_closing_reasons` | Xem danh sách mã lý do đóng offense (False Positive, Resolved...). |
| **Ariel (AQL)** | `qradar_execute_aql_search` | Chạy câu lệnh AQL (tự động polling kết quả hoặc trả về job id). |
| | `qradar_get_search_status` | Kiểm tra tiến độ job tìm kiếm (`WAIT`, `EXECUTE`, `COMPLETED`). |
| | `qradar_get_search_results` | Đọc kết quả log/flow từ search job đã hoàn thành. |
| | `qradar_list_ariel_databases` | Liệt kê các cơ sở dữ liệu Ariel có thể truy vấn (`events`, `flows`...). |
| **Analytics & Rules** | `qradar_list_rules` | Tìm kiếm và liệt kê Detection Rules (lọc theo origin USER/SYSTEM, enabled, type). |
| | `qradar_get_rule` | Xem chi tiết cấu hình 1 rule (identifier, owner, trạng thái enabled). |
| | `qradar_update_rule` | Bật / tắt rule (`enabled = true/false`) hoặc đổi rule owner. |
| | `qradar_list_building_blocks` | Liệt kê danh sách Building Blocks phục vụ phân tích tương quan. |
| **Asset Model** | `qradar_list_assets` | Tìm kiếm tài sản máy chủ/thiết bị (theo IP, Hostname, Risk Score). |
| | `qradar_get_asset` | Lấy đầy đủ thông tin chi tiết một tài sản (IP interfaces, MAC, OS, Users). |
| **Data Sources & Infra** | `qradar_list_log_sources` | Liệt kê các nguồn log (Log Sources), trạng thái hoạt động và thời gian nhận log cuối. |
| | `qradar_get_log_source` | Xem chi tiết cấu hình một Log Source (protocol, target collector, type). |
| | `qradar_list_servers` | Liệt kê các appliance/máy chủ trong cụm QRadar deployment (Console, EP, EC, FP). |
| **Reference Data** | `qradar_list_reference_sets` | Xem danh sách các Reference Set (Blacklist, Watchlist, Whitelist). |
| | `qradar_get_reference_set` | Đọc toàn bộ phần tử trong một Reference Set. |
| | `qradar_add_to_reference_set` | Thêm một IoC (IP, Domain, Hash) vào Reference Set phục vụ blocklist tự động. |
| | `qradar_delete_from_reference_set` | Xóa một giá trị khỏi Reference Set. |
| | `qradar_list_reference_maps` | Liệt kê các Reference Map (cấu trúc key-value). |
| | `qradar_get_reference_map` | Xem toàn bộ key-value trong một Reference Map. |
| | `qradar_update_reference_map` | Cập nhật hoặc thêm mới một key-value vào Reference Map. |
| | `qradar_list_reference_tables` | Liệt kê các Reference Tables đa cột dữ liệu. |

---

## 5. Chạy thử nghiệm trực tiếp bằng FastMCP CLI

FastMCP hỗ trợ giao diện Dev UI (MCP Inspector) để test trực quan các tools:

```bash
# Kích hoạt venv
.\.venv\Scripts\Activate.ps1

# Mở FastMCP Dev Inspector
mcp dev qradar_mcp/server.py
```
Giao diện web inspector sẽ tự động mở để bạn có thể kích hoạt thử các tool như `qradar_health_check`, `qradar_list_offenses`, v.v.