# L1alert

**Repository Path**: hnwlc/l1alert

## Basic Information

- **Project Name**: L1alert
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# L1 Alert Triage System

告警快速初筛系统 — 安全告警研判管道的**第一道智能关卡**。

```
L0 (SIEM/安全设备) → L1 (本系统) → L2 (深度 Agent)
    172.8亿日志/天      数万告警/天      数百告警/天
```

## 核心目标

- **降噪**: 将海量告警中 60-80% 的无害告警自动过滤
- **分级**: 剩余告警按风险分类（Pass / Triage / Escalate）并打分
- **提效**: 让 L2 深度研判只处理真正需要关注的告警

## 架构

两进程部署，三段式管道：

```
                         ┌──────────────────────┐
                         │     L1-core 进程       │
  Kafka 告警 → Normalizer → Admission → Dedup → Rule Engine → Scorer → Output Router
                         │         ↑              │
                         │    Context Enricher    │
                         │  (CMDB/Intel/Profile)  │
                         └─────────┬──────────────┘
                                   │ 内部 Kafka (llm.req / llm.resp)
                         ┌─────────┴──────────────┐
                         │    LLM Worker 进程       │
                         │  Batcher → Executor     │
                         │  → Validator → Cache    │
                         │  (独立部署，独立扩缩容)    │
                         └────────────────────────┘
```

## 支持的告警源与场景

| 告警源 | 典型日志类型 | 去重指纹 | 核心判定字段 | Phase 1 覆盖 |
|--------|-------------|---------|-------------|-------------|
| **WAF** | SQLi, XSS, 命令注入, 路径穿越 | source + rule_id + src_ip | src_ip, dest_ip, uri | ✅ 完整 |
| **HIDS** | 进程创建, 文件变更, 权限提升 | source + rule_id + src_ip + process_name | process_name, user, file_path | ✅ 完整 |
| **EDR** | 可疑进程, 注册表修改, DLL 注入 | source + rule_id + src_ip + process_name | process_name, parent_process, command_line, file_hash | ✅ 结构支持，规则待丰富 |
| **CloudTrail / GCP Audit** | IAM 变更, 存储桶策略修改, 安全组变更 | source + rule_id + identity | user, identity, cloud_resource | ✅ 结构支持，规则待丰富 |
| **DLP** | 邮件外发, USB 拷贝, 云盘上传 | source + rule_id + src_ip | data_classification, data_volume, dest_type | ⚠️ 结构支持，需专用 Normalizer |
| **DNS 异常** | DGA 域名, 隧道检测, 异常查询 | source + rule_id + domain | domain, query_type, response_ip | ✅ 结构支持 |
| **网络设备故障** | SNMP linkDown/linkUp, Syslog 接口翻动 | source + rule_id + device_name + interface_name | device_name, interface_name, device_role | ✅ 结构支持，3 条内置规则 |
| **钓鱼 / 恶意 URL** | 恶意链接点击, 可疑域名访问 | source + rule_id + url_domain | url_domain, url_path | ✅ 结构支持 |
| **K8s Audit / Falco** | 容器逃逸, 特权提升, 异常镜像拉取 | source + rule_id + k8s_namespace | k8s_namespace, pod_label, container_image | ⚠️ 结构支持，需专用 Normalizer |
| **失败登录 / 爆破** | SSH/RDP 暴力破解, 应用登录失败 | source + rule_id + dest_ip + dest_port | src_ip, dest_ip, attempt_count | ⚠️ 需 stateful 计数 |
| **横向移动** | 内网扫描, PTH 攻击, 远程执行 | — | — | ❌ 需跨告警关联引擎 |
| **通用 / 未知源** | 任意 JSON 告警 | 可配置 | 按约定字段名自动映射 | ✅ Generic Normalizer 兜底 |

> **图例**: ✅ 完整 = Normalizer + 去重 + 规则示例齐全 | ⚠️ = 结构体已支持，需源特定的 Normalizer 或 stateful 能力 | ❌ = 超出 Phase 1 范围

### 内置规则示例

```
白名单: 已知扫描器放行 (CMDB asset_type=scanner)
黑名单: 高置信度 C2 情报升级 (ThreatIntelCategory=C2 && Confidence>80)
上下文: 生产数据库首次外联 (DestAssetType=db && SrcFirstOutbound)
时间:   非工作时间 critical 告警 (!IsWorkingHours && Severity=critical)
主机:   生产环境 /tmp 异常进程 (SrcAssetEnv=prod && ProcessName matches /tmp/*)
云审计: 管理员删除存储桶策略 (Source=cloudtrail && User=admin && RuleID=DeleteBucketPolicy)
网络:   核心设备链路故障 (Source=snmp && DeviceName matches core-* && RuleID=link_down)
```

## 为什么拆分为两个进程

L1-core（规则引擎）和 LLM Worker（批量化推理）是两种不同特征的 workload：

| 维度 | L1-core | LLM Worker |
|------|---------|------------|
| 资源特征 | CPU 密集（哈希、正则、规则匹配） | IO 密集（HTTP 网络等待、JSON 序列化） |
| 故障隔离 | LLM 崩溃不影响核心规则处理 | 独立 OOM 不拖垮 L1-core |
| 独立 GC | GC 压力小 | JSON 编解码多，GC 压力大 |
| 扩缩容 | 按告警吞吐量 | 按模型推理能力 |

## 技术栈

| 组件 | 选型 |
|------|------|
| 语言 | Go 1.23+ |
| 规则引擎 | [expr-lang/expr](https://github.com/expr-lang/expr) |
| 去重 | [bits-and-blooms/bloom](https://github.com/bits-and-blooms/bloom) + [hashicorp/golang-lru](https://github.com/hashicorp/golang-lru) |
| 消息队列 | [segmentio/kafka-go](https://github.com/segmentio/kafka-go) |
| LLM 后端 | ollama（兼容 OpenAI API） |
| 监控 | Phase 1-3: CLI stderr 汇总 → Phase 4: 内置 HTMX 面板 或 Prometheus + Grafana |
| 配置 | YAML |

## 快速开始

### 前置条件

- Go 1.23+
- （可选）ollama 或兼容 OpenAI API 的 LLM 服务（仅 `--llm` 模式需要）
- （Phase 4）Kafka（告警输入输出通道 + LLM 内部队列）

### 安装

```bash
git clone git@github.com:L1alert/l1alert.git
cd l1alert
go mod download
```

### 运行（CLI 单进程模式）

```bash
# 从 stdin 读取 JSONL 告警，规则引擎处理
cat alerts.jsonl | go run cmd/l1-server/main.go run

# 从 stdin 读取 CSV 告警（需指定告警源）
cat alerts.csv | go run cmd/l1-server/main.go run --csv --source waf

# 启用 LLM 分类（需要 ollama 运行中）
cat alerts.jsonl | go run cmd/l1-server/main.go run --llm

# 规则评估模式（显示每条告警匹配了哪些规则）
cat alerts.jsonl | go run cmd/l1-server/main.go eval --verbose
```

### 命令行标志

| 标志 | 默认值 | 说明 |
|------|--------|------|
| `--csv` | false | 从 stdin 读取 CSV 格式（需配合 `--source`） |
| `--source` | `"stdin"` | 告警源名称，对应 Normalizer（waf / hids / cloudtrail / stdin 等） |
| `--rules` | `rules.yaml` | 规则文件路径 |
| `--llm` | false | 启用 LLM 分类（run 模式，需要 ollama） |
| `--verbose` | false | 显示每条告警的规则命中详情（eval 模式） |
| `--only-unmatched` | false | 仅显示零规则命中的告警（eval 模式） |

## 渐进式建设

| Phase | 验证节点 | 内容 | 状态 |
|-------|---------|------|------|
| Phase 1 | `cat alerts.jsonl \| go run . run` | Normalizer + 去重 + 规则引擎 + CLI（run / eval） | ✅ 完成 |
| Phase 2 | Phase 1 + CMDB/Intel 加载 | 上下文注入（CMDB + 实体画像 + 威胁情报分层） | ✅ 完成 |
| Phase 3 | Phase 2 + LLM Batch | LLM 批量化推理 + 综合评分 + 输出路由 | ✅ 完成 |
| Phase 4 | Prometheus + Grafana | 反馈回路 + 监控 + 规则健康度 + 集成测试 | 规划中 |

## 设计文档

详细设计见 [`docs/superpowers/`](docs/superpowers/)：

- [设计文档](docs/superpowers/2026-06-24-l1-alert-triage-system-design.md) — 架构、选型、拆分决策、上下文工程
- [实施计划](docs/superpowers/2026-06-24-l1-implementation-plan.md) — 分阶段任务与代码
- [技术评估](docs/superpowers/2026-06-24-l1-technical-evaluation.md) — 方案可行性、Stage 1 场景覆盖与算法局限

## License

MIT