tjs24/ThIOClaw
GitHub: tjs24/ThIOClaw
ThIOClaw 是一个帮助安全团队以透明、可复现、可版本控制的方式构建和运行 LLM 驱动漏洞调查代理的框架。
Stars: 0 | Forks: 0
# ThIOClaw — 漏洞调查框架
## 为什么选择 ThIOClaw？
LLM 正在以加速的趋势被整合到检测与响应工作流中——但大多数团队将其作为**不透明的黑盒**采用。你无法检查其推理过程、重现判定结果、对逻辑进行版本控制，也无法评估代理是否真正改善了你的安全态势。
ThIOClaw 基于五项工程原则构建：
| 原则 | ThIOClaw 如何实现 |
|---|---|
| **透明度** | 每次 LLM 工具调用、证据查找和判定结果都会记录在结构化的 JSONL 和 OpenTelemetry spans 中。可完整重构任何调查过程。 |
| **可重复性** | 一级信号评分是**确定性的** pandas 数学运算——每次都是相同的输入，相同的输出。LLM 在可重现的基础*之上*进行推理。 |
| **可配置性** | 信号规则、权重、判定阈值和漏洞利用链描述均为 YAML 文件。代理的 prompt 和工具是 Python 源代码。没有隐藏的控制面板。 |
| **版本控制** | 检测逻辑、代理行为和信号规则全部存在于 Git 中。更改会产生清晰的 diffs。使用标准的工程工作流进行审查、批准和回滚。 |
| **可衡量性** | 使用不同的模型、prompts 或工具配置运行相同的调查。将一级基准与二级 LLM 判定结果进行比较。Prometheus 指标会随时间跟踪代理的性能。 |
**本项目专为希望在迈向 LLM 驱动的 SecOps 之旅中获得工程控制权和可观测性的安全团队而设计。**
## macOS 设置与快速入门
### 1. 设置环境
```
git clone https://github.com/tej-nik/ThIOClaw.git
cd ThIOClaw
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 配置 LLM（本地或云端）
ThIOClaw 使用 [LiteLLM](https://github.com/BerriAI/litellm) 作为其控制平面，这意味着你可以接入**任何** LLM 提供商（Ollama、Anthropic、OpenAI、AWS Bedrock 等）而无需更改代码。
#### 选项 A：本地（Ollama）
为了完全的隐私，可以在你的 Mac 上本地运行 LLM：
```
ollama serve # Start the server
ollama pull llama3.1:8b # Pull the default model
```
#### 选项 B：直接连接云端（Anthropic / OpenAI）
导出你的提供商 API key 并通过 `THIOCLAW_MODEL` 设置模型：
```
# Anthropic Claude 3.5 Sonnet
export ANTHROPIC_API_KEY="sk-ant-..."
export THIOCLAW_MODEL="claude-3-5-sonnet-20241022"
# OpenAI GPT-4o
export OPENAI_API_KEY="sk-proj-..."
export THIOCLAW_MODEL="gpt-4o"
```
#### 选项 C：AWS Bedrock
身份验证使用 boto3 默认凭证链（环境变量、`~/.aws/credentials` profile 或 IAM role）。必须显式设置区域：
```
export AWS_REGION_NAME="us-east-1"
export AWS_PROFILE="default" # or rely on env-var credentials
export THIOCLAW_MODEL="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"
```
#### 选项 D：Google Vertex AI
适用于 Vertex 上的 Claude 和 Gemini。需要 service-account 密钥文件：
```
export VERTEXAI_PROJECT="your-gcp-project"
export VERTEXAI_LOCATION="us-central1"
export GOOGLE_APPLICATION_CREDENTIALS="/abs/path/to/service-account.json"
export THIOCLAW_MODEL="vertex_ai/gemini-1.5-pro"
# 或：export THIOCLAW_MODEL="vertex_ai/claude-3-5-sonnet@20240620"
```
#### 选择代理框架
ThIOClaw 提供了两个并行的二级代理循环实现，可在每次运行时进行选择：
```
# 原生 LiteLLM tool-calling 循环（默认）
export THIOCLAW_FRAMEWORK=litellm-direct
# Strands SDK 循环（AgentCore 原生，多智能体原语，支持 MCP）
export THIOCLAW_FRAMEWORK=strands
```
这两个实现共享相同的提供商路由和判定契约。`openclaw-bench/models.yaml` 中的 `framework` 轴让你可以针对每个模型对它们进行并排比较。
### 3. 运行调查
```
# 使用本地样本数据的单一调查周期
python -m harness.orchestrator --raw-telemetry local --once
# 调查特定 CVE
python -m harness.orchestrator --cve CVE-2026-31431 --once
# 持续监控循环（默认：每 300 秒）
python -m harness.orchestrator --raw-telemetry local
```
### 4. 预期结果
在执行过程中，代理可能会暂停并请求你的批准：
```
[ThIOClaw Agent] Proposing Query Execution:
Rationale: The existing Q6 staging query missed /var/tmp paths...
Performance Impact: Medium — scanning ~50,000 file events
Query: SELECT * FROM file_events WHERE path LIKE '/var/tmp/%'
Approve execution? (y/N): _
```
这就是**人机协同（HITL）**门控——代理会清楚地说明*为什么*需要该查询以及*成本是多少*，然后由你决定是否批准。
## 遥测数据源
两个正交的轴决定了遥测数据的来源及其组织方式：
**1. 数据位置** (`--raw-telemetry`) —— 框架从哪里读取事件：
| 标志 | 来源 | 凭证 |
|---|---|---|
| `--raw-telemetry local` | `data/events.json` | 无 |
| `--raw-telemetry s3` | 通过 `data/s3_manifest.json` 访问的 S3 存储桶 | `~/.aws/credentials` 指定的 profile |
**2. 采集器格式** (`harness.yaml` 中的 `telemetry.event_source`) —— 框架将摄取哪种事件流格式：
| 值 | 采集器 | 备注 |
|---|---|---|
| `osquery` (默认) | osquery `process_events`, `socket_events`, `kernel_module_events`, `file_events` 等 | 内置的示例数据 (`data/sample_events.json`) 即为此格式。所有六个 Q1-Q6 参考查询均针对此格式。 |
| `auditd` | Linux 内核 auditd，通过 `auditctl` 规则 + `ausearch`/`auparse` 实现 | 通过 [`rules-emerging-threats/2026/Exploits/CVE-2026-31431/`](https://github.com/SigmaHQ/sigma/pull/6052) 中的 SigmaHQ 规则实现镜像覆盖。验证手册：[`runbooks/CVE-2026-31431_sigma_validation.md`](runbooks/CVE-2026-31431_sigma_validation.md)。 |
| `both` | 两者的并集 | 适用于同时运行两种采集器的环境。数据平面与来源无关——它会对输入的任何 DataFrame 进行评分。 |
每个信号的来源支持在 `signals/.yaml` 中通过每条规则的 `supported_sources:` 进行声明。
### S3 设置
1. 使用你的存储桶、区域和密钥路径编辑 `data/s3_manifest.json`
2. 使用指定的 profile 配置你的 `~/.aws/credentials`
3. 如果使用非默认 profile，请在 `harness.yaml` 中设置 `aws.profile_name`
## 项目结构
```
ThIOClaw/
├── CLAUDE.md # Comprehensive project guide & design rationale
├── README.md # This file
├── harness.yaml # Main harness configuration
├── targets.yaml # CVE investigation targets
├── requirements.txt # Python dependencies
│
├── data_plane/ # DATA PLANE — Modular investigation scripts
│ └── cve_2026_31431.py # Deterministic pandas analysis (Q1–Q6)
│
├── scripts/ # CONTROL PLANE — LLM Agent
│ ├── thioclaw.py # CLI entry point
│ └── thioclaw_agent/
│ ├── agent.py # Agentic loop (Ollama + tool calling + HITL)
│ ├── prompts.py # System prompt
│ └── tools.py # Tool definitions + implementations
│
├── signals/ # Signal rule definitions (YAML)
│ └── CVE-2026-31431.yaml # Rules, weights, verdict logic, LLM context
│
├── queries/ # Reference Detection Queries (e.g., SQL, KQL)
│ └── CVE-2026-31431/ # Example query files
│
├── harness/ # Orchestrator engine
│ ├── orchestrator.py # CLI + run loop + concurrent dispatch
│ ├── config.py # Typed dataclasses from YAML
│ └── ingester.py # CSV → SQLite inventory ingestion
│
├── observability/ # Instrumentation
│ ├── logger.py # Thread-safe structured JSONL logger
│ ├── metrics.py # Prometheus metrics via OpenTelemetry
│ └── traces.py # OTel distributed tracing
│
├── data/ # Sample data (replace with real telemetry)
│ ├── sample_events.json # 9 events simulating a full exploit chain
│ ├── sample_inventory.csv # 8 workloads with mixed statuses
│ └── s3_manifest.json # S3 config template (no secrets)
│
├── findings/ # Output: YAML findings + JSONL log (gitignored)
├── docs/ # Output: per-run Markdown + HTML reports
├── logs/ # Output: Structured JSONL logs (gitignored)
└── tests/ # Unit tests (pytest)
```
## 架构
```
graph TD
A["Inventory Telemetry (e.g. auditd/EDR)"] -->|Ingester| B["inventory.db (SQLite)"]
C["Event Telemetry (Local/S3/API)"] -->|Data Plane| D["data_plane/.py"]
B -->|vulnerable workloads| D
D -->|"Deterministic queries (e.g. pandas)"| E["Tier 1: Deterministic Signal Scoring"]
E -->|tier1.json| F["Tier 2: ThIOClaw LLM Agent"]
F <-->|"HITL Approval Gates"| G(("Analyst Terminal"))
F --> H["findings/*.yaml"]
F --> I["docs/*.md + *.html"]
style E fill:#ff8c00,color:#fff
style F fill:#4488ff,color:#fff
style G fill:#22aa44,color:#fff
```
### 工作原理
1. **数据摄取** — 主机清单遥测数据被加载到 SQLite 中。匹配 `trigger_assessments`（例如 `vulnerable_or_not_confirmed_fixed`）的工作负载将被选中以进行调查。
2. **一级（数据平面）** — 模块化的 Python 脚本针对原始遥测事件运行确定性查询。每个查询都会检查特定的漏洞利用指标。信号使用可配置的权重进行评分，以产生确定性的判定结果：`exploited`、`suspicious`、`benign` 或 `inconclusive`。
3. **二级（控制平面）** — ThIOClaw LLM 代理接收一级结果和 CVE 的理论漏洞利用链。它关联证据，请求更深层次的遥测检查，并可以提出新的查询——但在执行之前必须通过终端获得**分析师的批准**。
4. **输出** — 调查结果以 YAML、Markdown 和 HTML 格式按运行持久化保存。所有事件均通过 OpenTelemetry 进行埋点监测。
## 内置示例：CVE-2026-31431
ThIOClaw 内置了一个针对 **CVE-2026-31431**（Linux 内核 `algif_aead` 本地权限提升）的完整调查，包括模拟完整漏洞利用链的示例遥测数据。
| 查询 | 信号 | 权重 | 层级 |
|---|---|---|---|
| Q1 | 清单中加载了 `algif_aead` 模块 | 0.3 | Suspicious |
| Q2 | 非特权用户打开 `AF_ALG` socket | 0.5 | Suspicious |
| Q3 | 打开 `AF_ALG` 后发生 UID 提升 **(主要)** | 1.0 | **Exploited** |
| Q4 | 来自非 root 父进程的 root shell | 0.9 | **Exploited** |
| Q5 | `algif_aead` 模块加载事件 | 0.4 | Suspicious |
| Q6 | 在 `/tmp`、`/dev/shm`、memfd 中进行漏洞利用暂存 | 0.6 | Suspicious |
**判定逻辑：** 如果任何 exploited 层级的信号触发且总权重 ≥ 1.0，则为 `exploited`。如果总权重 ≥ 0.5，则为 `suspicious`。如果总权重 = 0，则为 `benign`。否则为 `inconclusive`。
**Auditd 形态覆盖** — 相同的漏洞利用链也由在 [SigmaHQ/sigma#6052](https://github.com/SigmaHQ/sigma/pull/6052) 中提交的三个 SigmaHQ 规则（AF_ALG socket 创建、`algif_aead` 模块加载、setuid 路径上的 splice 操作）覆盖。使用 [`runbooks/CVE-2026-31431_sigma_validation.md`](runbooks/CVE-2026-31431_sigma_validation.md) 针对实时的 audit 遥测数据进行重现和验证。
## 可观测性
| 层级 | 实现 | Endpoint / 位置 |
|---|---|---|
| 结构化日志 | 线程安全的 JSONL 写入器 | `logs/agent_runs.jsonl` |
| 指标 | OpenTelemetry → Prometheus | `http://localhost:9090/metrics` |
| Traces | OpenTelemetry spans | stdout（默认）或 OTLP gRPC endpoint |
## 调查任意漏洞
ThIOClaw 被设计为**通用型**工具。只需三个步骤即可添加新的 CVE 目标：
1. **定义目标** — 在 `targets.yaml` 中添加一个条目，包含 CVE-ID、数据平面脚本模块路径和信号文件。
2. **配置信号** — 创建 `signals/.yaml`，包含加权规则，并在 `agent_context` 块中为 LLM 描述漏洞利用链。
3. **编写数据平面** — 创建 `data_plane/.py`，实现带有针对该漏洞遥测特征定制的 pandas 查询的 `run_investigation()` 函数。
请参阅 [CLAUDE.md](CLAUDE.md) 获取详细的说明和设计原理。
## 运行测试
```
pytest tests/ -v
pytest tests/ -v --cov=harness --cov=observability --cov-report=term-missing
```
## 许可证
详情请参阅 [LICENSE](LICENSE)。
标签：AI风险缓解, API集成, DLL 劫持, LLM代理, Python, 可观测性, 大语言模型, 安全运营, 扫描框架, 无后门, 用户代理, 自定义请求头, 逆向工具