Skip to main content
Glama
IBM QRadar SIEM MCP Server

IBM QRadar SIEM MCP Server

README.md
# QRadar SIEM Engineering & Automation MCP Server (TOON Native)

MCP Server for **IBM QRadar SIEM** built on [PyRadar](https://github.com/binhnguyen143/PyRadar) with native **TOON (Token-Oriented Object Notation)** serialization.

Tối ưu hóa đặc biệt cho SIEM Engineer & SecOps Automation, giảm **50% – 60% token tiêu thụ** cho LLM Agent khi làm việc với dữ liệu bảng (Log Sources, Network Hierarchy, AQL events, Reference Sets).

---

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

```bash
pip install -r requirements.txt
```

### Các biến môi trường cấu hình:

| Biến môi trường | Mặc định | Mô tả |
| :--- | :--- | :--- |
| `QRADAR_HOST` | *(Bắt buộc)* | IP hoặc Hostname của QRadar Console (vd: `10.10.1.5` hoặc `qradar.company.com`). |
| `QRADAR_TOKEN` | `None` | SEC Token của QRadar API (hoặc dùng `QRADAR_USERNAME` / `QRADAR_PASSWORD`). |
| `QRADAR_VERIFY_SSL` | `true` | `true`, `false`, hoặc đường dẫn tới file CA certificate bundle. |
| `QRADAR_API_VERSION` | `26.0` | Phiên bản REST API của QRadar (mặc định 26.0). |
| `QRADAR_OUTPUT_FORMAT` | `toon` | Định dạng dữ liệu trả về: `toon` (mặc định tiết kiệm token) hoặc `json`. |
| `QRADAR_WRITE_SCOPES` | `none` | Phân quyền ghi theo domain: `none`, `log_sources`, `network_hierarchy`, `reference_sets`, `ceps`, hoặc `all`. |
| `QRADAR_ALLOW_DELETE` | `false` | Khóa an toàn cho các thao tác xóa hủy dữ liệu (DELETE). Cần bật `true` rõ ràng khi muốn xóa. |

---

## 2. Danh mục Công cụ (Tools & Capabilities)

### Phân hệ 1: Tự động hóa Log Source
- `audit_log_source_targets(targets, aql_lookback_hours=24)`: Rà soát danh sách IP/Host theo **7 trạng thái chuẩn**: `OK`, `Warning`, `Error`, `Not Available`, `Disabled`, `Undefined` (đang rơi vào SIM Generic), `Unknown` (không có log source và không có traffic).
- `discover_sim_generic_ips(hours=24, min_events=5, sample_payloads=2)`: Tìm các IP đang đổ log vào SIM Generic (devicetype=105) kèm mẫu payload để xác định loại DSM.
- `batch_create_log_sources(specs, dry_run=True)`: Tạo hàng loạt Log Source tuân thủ chuẩn đặt tên `<Đơn vị>-<Tên hệ thống>-<Hostname> @ <IP>`. Hỗ trợ chế độ xem trước (Dry-Run).
- `get_log_sources_for_standardization(filter_expr="", only_non_compliant=False)`: Rà soát các Log Source chưa đạt chuẩn đặt tên hoặc chưa gán đúng nhóm.
- `preview_and_apply_standardization(updates, dry_run=True)`: Xem trước bảng TOON Diff (`old_name` $\to$ `new_name`, `old_groups` $\to$ `new_groups`) và áp dụng thay đổi hàng loạt.

### Phân hệ 2: Tối ưu hóa Network Hierarchy Đa Domain
- `list_network_hierarchy(staged=False, domain_id=None)`: Liệt kê danh sách Network Hierarchy (hỗ trợ xem cấu hình nháp `staged=True` và lọc theo `domain_id`).
- `evaluate_network_hierarchy_coverage(candidate_networks, sample_traffic_hours=24)`:
  - Phân vùng kiểm tra theo `domain_id` (cho phép trùng CIDR giữa các Domain khác nhau).
  - Phát hiện `EXACT_DUPLICATE`, `SUPERNET_SUBNET_OVERLAP`, và `CONTIGUOUS_MERGEABLE` trong cùng Domain.
  - Chạy AQL đo thực tế **% Traffic Coverage** của các IP nội bộ phát sinh sự kiện.
- `stage_network_hierarchy(networks, mode="merge", dry_run=True)`: Đẩy cấu hình an toàn vào `staged_networks` với chế độ xem trước diff.

### Phân hệ 3: Quản lý Reference Set
- `list_reference_sets(filter_expr="")`: Liệt kê các Reference Set kèm số lượng phần tử và TTL.
- `get_reference_set_values(name, range_header="0-499")`: Bảng TOON chứa các giá trị với mốc thời gian xem lần cuối dạng tương đối (`0.5h`, `2.1d`).
- `create_reference_set(name, element_type="ALNIC", time_to_live=None, timeout_type="LAST_SEEN")`: Tạo Reference Set mới.
- `update_reference_set_values(name, action="add|remove|purge", values=[])`: Thêm/xóa hàng loạt hoặc dọn sạch (purge) Reference Set.

### Phân hệ 4 & 5: AQL Templates & Tự động hóa CEPs (Custom Event Properties)
- `run_aql_template(template_id, params={})`: Chạy các câu AQL chuẩn hóa: `sim_generic_sources`, `unparsed_event_samples`, `check_ips_last_event`, `eps_by_log_source`, `uncovered_hierarchy_ips`.
- `lookup_aql_fields_and_ceps(keyword="")`: Tra cứu các trường CEP có trên QRadar để viết AQL chính xác.
- `test_cep_regex_on_payloads(regex_str, capture_group=1, payloads=[])`: Dùng Python `re` kiểm thử biểu thức Regex trực tiếp trên mẫu raw log trước khi cấu hình lên SIEM.
- `analyze_events_for_cep_recommendations(log_source_id, log_source_type_id)`: Lấy mẫu payload unparsed và đối chiếu với các CEPs hiện có của DSM để đề xuất trường mới.
- `upsert_custom_event_property(name, regex_str, ...)`: Tự động tạo/tái sử dụng `property_expression` và tạo binding `regex_properties` trên QRadar.
- **Resource:** `qradar://aql/reference`: Cẩm nang tra cứu cú pháp và hàm AQL.

### Core & Generic SDK:
- `run_aql(query)`: Chạy AQL tùy ý, trả về bảng TOON.
- `list_offenses`, `get_offense`: Tra cứu cảnh báo vi phạm.
- `list_endpoints`, `call_endpoint`: Gọi trực tiếp toàn bộ 729 endpoints của `qradar-sdk`.

---

## 3. Cấu hình MCP Client (Claude Desktop / Antigravity IDE)

Thêm vào file cấu hình MCP client:

```json
{
  "mcpServers": {
    "qradar": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "QRADAR_HOST": "qradar.example.com",
        "QRADAR_TOKEN": "your-authorized-service-token",
        "QRADAR_VERIFY_SSL": "false",
        "QRADAR_OUTPUT_FORMAT": "toon",
        "QRADAR_WRITE_SCOPES": "log_sources,network_hierarchy,reference_sets,ceps",
        "QRADAR_ALLOW_DELETE": "false"
      }
    }
  }
}
```

TDQS

A3.6/5.0

Scored across 27 tools

Disambiguation5/5

Each tool maps to a distinct QRadar resource/action: offenses, Ariel searches, reference sets/maps/tables, rules, assets, log sources, and health. Even the similar reference-data tools are clearly separated by resource type and operation.

Naming Consistency4/5

The qradar_ prefix and verb_noun style are highly consistent across list/get/update/add/delete operations. Minor deviations like qradar_health_check and qradar_add_to_reference_set break the strict pattern slightly, but they remain readable and predictable.

Tool Count2/5

At 27 tools, the server exceeds the 25-tool threshold for too many. While the QRadar domain is broad, many tools are parallel list/get pairs, making the overall surface heavier than necessary for agent selection.

Completeness3/5

Core workflows like offense triage, Ariel search, and reference-set enrichment are well covered. However, reference collections lack create/delete lifecycle operations, and rules, log sources, building blocks, and servers are mostly read-only, leaving notable gaps for full SIEM administration.