fukusuket/THuntCloud
GitHub: fukusuket/THuntCloud
基于 Docker Compose 的本地 AWS CloudTrail 威胁猎杀工具，利用 Rust 高效摄取日志至 DuckDB，并通过 AI 驱动的自然语言查询实现无需 SIEM 基础设施的日志分析与可视化。
Stars: 0 | Forks: 0
# 🪽THuntCloud🪽
## AWS 日志威胁猎杀工具
[](LICENSE)
[](docker/docker-compose.yml)
[](ingester/Cargo.toml)
[](agent/requirements.txt)
## 概述
THuntCloud 能够直接在本地 PC 上对 AWS CloudTrail 日志进行快速、AI 驱动的威胁猎杀。
- **无需 SIEM** — 所有分析均通过 DuckDB 在本地运行
- **AI 辅助** — 通过 OpenAI API (`gpt-5.4`) 实现自然语言 → SQL 生成
- **GeoIP 富化** — 通过 MaxMind GeoLite2 用国家、城市、ASN 信息富化 `source_ip_address`
- **内置仪表盘** — Apache Superset 提供预置的 CloudTrail 仪表盘
- **单命令启动** — `docker compose up -d`
## 截图
### AI Agent (Streamlit UI)
### 仪表盘 (Apache Superset)
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ Docker Compose │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ ingester │ │ agent │ │ dashboard │ │
│ │ (Rust) │ │ (Streamlit) │ │ (Superset) │ │
│ │ │ │ │ │ │ │
│ │ CloudTrail │ │ AI-Agent │ │ BI / Viz │ │
│ │ gz ingest │ │ SQL gen/exec │ │ │ │
│ │ READ_WRITE │ │ READ_ONLY │ │ READ_ONLY │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│ └──────────────────┴─────────────────┘ │
│ │ │
│ ┌───────▼──────┐ │
│ │ DuckDB │ │
│ │ (Bind Mount) │ │
│ │ (SSD) │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## 处理流程
### 1. 日志摄取流程
```
sequenceDiagram
actor User
participant FS as Local Filesystem
(CloudTrail .json.gz) participant Ingester as ingester
(Rust) participant DuckDB User->>Ingester: docker compose run ingester ingest --path /data/logs activate Ingester Ingester->>FS: Walk directory & list .json / .json.gz files loop For each file Ingester->>FS: Read file alt .json.gz Ingester->>Ingester: Decompress (flate2) end Ingester->>Ingester: Parse JSON (serde_json) Ingester->>Ingester: Compute checksum (duplicate check) Ingester->>DuckDB: Batch INSERT into cloudtrail_events (READ_WRITE) DuckDB-->>Ingester: OK end Ingester-->>User: Ingestion complete (stats: records, duration) deactivate Ingester ``` ### 2. AI 辅助威胁猎杀流程 ``` sequenceDiagram actor User participant UI as agent
(Streamlit UI) participant LLM as OpenAI API
(gpt-5.4) participant Validator as SQL Validator
(EXPLAIN + keyword filter) participant DuckDB User->>UI: Enter natural language query activate UI UI->>LLM: Send query + schema context (system prompt) activate LLM LLM-->>UI: Return generated SQL deactivate LLM UI->>Validator: Validate SQL activate Validator alt Unsafe keyword detected (DROP / INSERT / UPDATE …) Validator-->>UI: Reject — return error UI-->>User: Show validation error else EXPLAIN passes Validator->>DuckDB: EXPLAIN (READ_ONLY)
DuckDB-->>Validator: Execution plan OK
Validator-->>UI: SQL approved
deactivate Validator
UI->>DuckDB: Execute SQL (READ_ONLY)
DuckDB-->>UI: Result rows
UI->>LLM: Send results + "analyze for threats" prompt
activate LLM
LLM-->>UI: Threat analysis summary
deactivate LLM
UI-->>User: Display results + analysis (+ optional PDF report)
end
deactivate UI
```
### 3. 仪表盘可视化流程
```
sequenceDiagram
actor User
participant Superset as dashboard
(Apache Superset) participant Init as superset-init
(one-shot) participant DuckDB Note over Init,DuckDB: First startup only Init->>Superset: Register DuckDB connection (READ_ONLY) Init->>Superset: Import pre-built CloudTrail dashboards & charts Init->>Superset: Register dataset (cloudtrail_events) User->>Superset: Open http://localhost:8088 activate Superset Superset-->>User: Show CloudTrail dashboard loop For each chart panel Superset->>DuckDB: Execute chart SQL (READ_ONLY) DuckDB-->>Superset: Result rows Superset-->>User: Render chart / table end opt Ad-hoc SQL (SQL Lab) User->>Superset: Enter custom SQL in SQL Lab Superset->>DuckDB: Execute SQL (READ_ONLY) DuckDB-->>Superset: Result rows Superset-->>User: Display results / visualization end deactivate Superset ``` ## 快速开始 ### 前置条件 - Docker Desktop (或 Docker Engine + Docker Compose v2) - 最低 16 GB RAM，推荐使用 SSD - *(可选)* OpenAI API key (`gpt-5.4` 访问权限) — agent 模块需要此项 - *(可选)* [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) `.mmdb` 文件用于 GeoIP 富化 ### 1. 克隆并配置 ``` git clone https://github.com/fukusuket/THuntCloud.git cd THuntCloud ``` ### 2. 放置 CloudTrail 日志 ``` # 您的自有日志 cp /path/to/cloudtrail/logs/*.json.gz docker/logs/ ``` ### 3. 构建并摄取日志 ``` cd docker docker compose --profile ingest build ingester docker compose --profile ingest run --rm ingester ingest --path /data/logs ``` #### 启用 GeoIP 富化（可选） 下载 [GeoLite2 `.mmdb` 文件](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) 并将它们放置在 `docker/data/geoip/` 中。 ``` docker/ └── data/ └── geoip/ ← place .mmdb files here ├── GeoLite2-City.mmdb ├── GeoLite2-Country.mmdb └── GeoLite2-ASN.mmdb ``` 这些文件以只读方式绑定挂载到容器的 `/data/geoip/` 目录。 支持三种数据库类型： | 标志 | 数据库 | 提供内容 | |------|----------|----------| | `--geoip-city` | GeoLite2-City.mmdb | 国家 + 城市 + 经纬度 | | `--geoip-country` | GeoLite2-Country.mmdb | 仅国家（比 City 更轻量的替代方案） | | `--geoip-asn` | GeoLite2-ASN.mmdb | ASN 号码 + 组织名称 | **完整富化（City + ASN）：** ``` docker compose --profile ingest run --rm ingester ingest \ --path /data/logs \ --geoip-city /data/geoip/GeoLite2-City.mmdb \ --geoip-asn /data/geoip/GeoLite2-ASN.mmdb ``` ``` docker compose --profile ingest run --rm ingester ingest --path /data/logs ``` #### 在现有数据库上回填 GeoIP 如果日志是在没有 GeoIP 的情况下摄取的，请使用 `enrich` 子命令回填地理列，而无需重新摄取。 首先将 `.mmdb` 文件放置在 `docker/data/geoip/` 中，然后： ``` # 完整 enrichment (城市 + ASN) docker compose --profile ingest run --rm ingester enrich \ --geoip-city /data/geoip/GeoLite2-City.mmdb \ --geoip-asn /data/geoip/GeoLite2-ASN.mmdb ``` ### 4. 启动所有服务 ``` docker compose up -d --build ``` ### 5. 打开用户界面 | 服务 | URL | 凭据 | |---------|-----|-------------| | Agent (AI 猎杀) | http://localhost:8501 | — | | 仪表盘 (Superset) | http://localhost:8088 | `admin` / `admin` | ## Docker 操作 所有命令均从 `docker/` 目录运行。 ``` docker compose down && docker compose up -d # Restart (keep data) docker compose down && docker compose up -d --build # Rebuild & restart docker compose up -d superset # Dashboard only docker compose up -d agent # Agent only docker compose logs -f # View logs docker compose down -v # Full reset (delete data) ``` ### 重新摄取日志 ``` docker compose down rm -f data/db/threat_hunting.db data/db/threat_hunting.db.wal docker compose --profile ingest run --rm ingester ingest --path /data/logs docker compose up -d --build ``` ## ingester CLI 参考 ``` ingester ingest --path
[--db ] # DuckDB file (default: /data/db/threat_hunting.db)
[--no-progress] # Disable progress bar output
[--include ] # comma-separated include patterns, e.g. "*CloudTrail*"
[--exclude ] # comma-separated exclude patterns, e.g. "*vpcflowlogs*"
[--from ]# ingest files on or after this date
[--to ]# ingest files on or before this date
[--workers ] # parallel threads (default: CPU count)
[--geoip-city ] # GeoLite2-City.mmdb (or GEOIP_CITY_PATH env)
[--geoip-country ] # GeoLite2-Country.mmdb (or GEOIP_COUNTRY_PATH env)
[--geoip-asn ] # GeoLite2-ASN.mmdb (or GEOIP_ASN_PATH env)
ingester enrich
[--db ] # DuckDB file (default: /data/db/threat_hunting.db)
[--geoip-city ] # GeoLite2-City.mmdb (or GEOIP_CITY_PATH env)
[--geoip-country ] # GeoLite2-Country.mmdb (or GEOIP_COUNTRY_PATH env)
[--geoip-asn ] # GeoLite2-ASN.mmdb (or GEOIP_ASN_PATH env)
```
## 模块概述
| 模块 | 语言 / 框架 | 角色 |
|--------|---------------------|------|
| `ingester` | Rust 1.85+ | 解析 CloudTrail 日志并将其加载到 DuckDB；可选 GeoIP 富化 (READ_WRITE) |
| `agent` | Python 3.12+ / Streamlit | 用于交互式威胁猎杀的 AI-Agent UI (READ_ONLY) |
| `dashboard` | Apache Superset | 日志数据的 BI 可视化 (READ_ONLY) |
## 许可证
Apache License 2.0 — 详见 [LICENSE](LICENSE)。
第三方许可证归属请参见 [NOTICE](NOTICE)。
## 致谢
- **[Yamato Security](https://github.com/Yamato-Security)** — 提供了 [suzaku-sample-data](https://github.com/Yamato-Security/suzaku-sample-data) 仓库
- **[flaws.cloud](http://flaws.cloud)** — 故意设计为易受攻击的 AWS 环境，其 CloudTrail 日志是极佳的威胁猎杀练习数据集。
- **[Apache Superset](https://superset.apache.org/)** — 为内置仪表盘提供支持的开源 BI 平台。
- **[DuckDB](https://duckdb.org/)** — THuntCloud 数据引擎核心的嵌入式分析数据库。
- **[siem-on-amazon-opensearch-service](https://github.com/aws-samples/siem-on-amazon-opensearch-service)** — AWS 针对 Amazon OpenSearch Service 上 SIEM 的示例项目，参考了其日志解析和规范化模式。
- **[cloud-trail-lake-query-samples](https://github.com/aws-samples/cloud-trail-lake-query-samples)** — AWS 针对 CloudTrail Lake 的示例查询，参考了其威胁猎杀查询模式。
### 仪表盘 (Apache Superset)
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ Docker Compose │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ ingester │ │ agent │ │ dashboard │ │
│ │ (Rust) │ │ (Streamlit) │ │ (Superset) │ │
│ │ │ │ │ │ │ │
│ │ CloudTrail │ │ AI-Agent │ │ BI / Viz │ │
│ │ gz ingest │ │ SQL gen/exec │ │ │ │
│ │ READ_WRITE │ │ READ_ONLY │ │ READ_ONLY │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│ └──────────────────┴─────────────────┘ │
│ │ │
│ ┌───────▼──────┐ │
│ │ DuckDB │ │
│ │ (Bind Mount) │ │
│ │ (SSD) │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## 处理流程
### 1. 日志摄取流程
```
sequenceDiagram
actor User
participant FS as Local Filesystem(CloudTrail .json.gz) participant Ingester as ingester
(Rust) participant DuckDB User->>Ingester: docker compose run ingester ingest --path /data/logs activate Ingester Ingester->>FS: Walk directory & list .json / .json.gz files loop For each file Ingester->>FS: Read file alt .json.gz Ingester->>Ingester: Decompress (flate2) end Ingester->>Ingester: Parse JSON (serde_json) Ingester->>Ingester: Compute checksum (duplicate check) Ingester->>DuckDB: Batch INSERT into cloudtrail_events (READ_WRITE) DuckDB-->>Ingester: OK end Ingester-->>User: Ingestion complete (stats: records, duration) deactivate Ingester ``` ### 2. AI 辅助威胁猎杀流程 ``` sequenceDiagram actor User participant UI as agent
(Streamlit UI) participant LLM as OpenAI API
(gpt-5.4) participant Validator as SQL Validator
(EXPLAIN + keyword filter) participant DuckDB User->>UI: Enter natural language query activate UI UI->>LLM: Send query + schema context (system prompt) activate LLM LLM-->>UI: Return generated SQL deactivate LLM UI->>Validator: Validate SQL activate Validator alt Unsafe keyword detected (DROP / INSERT / UPDATE …) Validator-->>UI: Reject — return error UI-->>User: Show validation error else EXPLAIN passes Validator->>DuckDB: EXPLAIN
(Apache Superset) participant Init as superset-init
(one-shot) participant DuckDB Note over Init,DuckDB: First startup only Init->>Superset: Register DuckDB connection (READ_ONLY) Init->>Superset: Import pre-built CloudTrail dashboards & charts Init->>Superset: Register dataset (cloudtrail_events) User->>Superset: Open http://localhost:8088 activate Superset Superset-->>User: Show CloudTrail dashboard loop For each chart panel Superset->>DuckDB: Execute chart SQL (READ_ONLY) DuckDB-->>Superset: Result rows Superset-->>User: Render chart / table end opt Ad-hoc SQL (SQL Lab) User->>Superset: Enter custom SQL in SQL Lab Superset->>DuckDB: Execute SQL (READ_ONLY) DuckDB-->>Superset: Result rows Superset-->>User: Display results / visualization end deactivate Superset ``` ## 快速开始 ### 前置条件 - Docker Desktop (或 Docker Engine + Docker Compose v2) - 最低 16 GB RAM，推荐使用 SSD - *(可选)* OpenAI API key (`gpt-5.4` 访问权限) — agent 模块需要此项 - *(可选)* [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) `.mmdb` 文件用于 GeoIP 富化 ### 1. 克隆并配置 ``` git clone https://github.com/fukusuket/THuntCloud.git cd THuntCloud ``` ### 2. 放置 CloudTrail 日志 ``` # 您的自有日志 cp /path/to/cloudtrail/logs/*.json.gz docker/logs/ ``` ### 3. 构建并摄取日志 ``` cd docker docker compose --profile ingest build ingester docker compose --profile ingest run --rm ingester ingest --path /data/logs ``` #### 启用 GeoIP 富化（可选） 下载 [GeoLite2 `.mmdb` 文件](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) 并将它们放置在 `docker/data/geoip/` 中。 ``` docker/ └── data/ └── geoip/ ← place .mmdb files here ├── GeoLite2-City.mmdb ├── GeoLite2-Country.mmdb └── GeoLite2-ASN.mmdb ``` 这些文件以只读方式绑定挂载到容器的 `/data/geoip/` 目录。 支持三种数据库类型： | 标志 | 数据库 | 提供内容 | |------|----------|----------| | `--geoip-city` | GeoLite2-City.mmdb | 国家 + 城市 + 经纬度 | | `--geoip-country` | GeoLite2-Country.mmdb | 仅国家（比 City 更轻量的替代方案） | | `--geoip-asn` | GeoLite2-ASN.mmdb | ASN 号码 + 组织名称 | **完整富化（City + ASN）：** ``` docker compose --profile ingest run --rm ingester ingest \ --path /data/logs \ --geoip-city /data/geoip/GeoLite2-City.mmdb \ --geoip-asn /data/geoip/GeoLite2-ASN.mmdb ``` ``` docker compose --profile ingest run --rm ingester ingest --path /data/logs ``` #### 在现有数据库上回填 GeoIP 如果日志是在没有 GeoIP 的情况下摄取的，请使用 `enrich` 子命令回填地理列，而无需重新摄取。 首先将 `.mmdb` 文件放置在 `docker/data/geoip/` 中，然后： ``` # 完整 enrichment (城市 + ASN) docker compose --profile ingest run --rm ingester enrich \ --geoip-city /data/geoip/GeoLite2-City.mmdb \ --geoip-asn /data/geoip/GeoLite2-ASN.mmdb ``` ### 4. 启动所有服务 ``` docker compose up -d --build ``` ### 5. 打开用户界面 | 服务 | URL | 凭据 | |---------|-----|-------------| | Agent (AI 猎杀) | http://localhost:8501 | — | | 仪表盘 (Superset) | http://localhost:8088 | `admin` / `admin` | ## Docker 操作 所有命令均从 `docker/` 目录运行。 ``` docker compose down && docker compose up -d # Restart (keep data) docker compose down && docker compose up -d --build # Rebuild & restart docker compose up -d superset # Dashboard only docker compose up -d agent # Agent only docker compose logs -f # View logs docker compose down -v # Full reset (delete data) ``` ### 重新摄取日志 ``` docker compose down rm -f data/db/threat_hunting.db data/db/threat_hunting.db.wal docker compose --profile ingest run --rm ingester ingest --path /data/logs docker compose up -d --build ``` ## ingester CLI 参考 ``` ingester ingest --path
标签：AI安全助手, Apache Superset, AWS CloudTrail, Docker Compose, DuckDB, GeoIP, Kubernetes, MaxMind, OpenAI GPT, Petitpotam, Python, Rust, SQL生成, Streamlit, Web报告查看器, 云基础设施安全, 云审计, 可视化界面, 安全运营, 扫描框架, 无SIEM, 无后门, 本地优先, 本地安全分析, 版权保护, 网络流量审计, 自然语言转SQL, 访问控制, 逆向工具, 通知系统