# sysarmor

**Repository Path**: pku-oslab/sysarmor

## Basic Information

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

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SysArmor EDR/HIDS 系统

## 🎯 项目概述

SysArmor 是一个现代化的端点检测与响应(EDR/HIDS)系统，采用微服务架构，实现 agentless 数据采集、实时威胁检测和告警存储的完整数据流。

### 系统架构
```mermaid
graph LR
    A[终端设备<br/>auditd数据] -->|TCP:6000| B[Middleware<br/>Vector + Kafka]
    B -->|消息队列| C[Processor<br/>Flink + NODLINK]
    C -->|告警事件| D[Indexer<br/>OpenSearch]
    E[Manager<br/>控制平面] -.->|管理| B
    E -.->|查询| D
    E --- F[(PostgreSQL)]
```

### 核心特性
- 🚀 **Agentless 部署** - 基于 rsyslog + auditd，无需安装 Agent
- 🔧 **微服务架构** - Manager + Middleware + Processor + Indexer 四大模块
- 📊 **实时威胁检测** - Flink 流处理 + NODLINK 算法
- 🔍 **告警存储查询** - OpenSearch 索引和 REST API
- 🐳 **容器化部署** - Docker Compose 一键部署


## 🚀 快速开始

### 一键部署
```bash
git clone https://git.pku.edu.cn/oslab/sysarmor.git
cd sysarmor

# 初始化并部署 (一键完成)
make init && make deploy
```

**部署完成后，系统会自动**:
- ✅ 启动所有服务 (Manager、Kafka、Flink、OpenSearch等)
- ✅ 提交核心Flink作业 (数据转换和告警生成)
- ✅ 激活完整数据流 (auditd → events → alerts)

### 快速验证

```bash
# 1. 系统健康检查（8 个检查点）
make health

# 2. 完整数据流测试（18 个验证点）
make test-e2e-data-pipeline

# 3. API 接口测试（54 个端点）
make test
```

**数据流验证内容**：
- ✅ 服务健康检查（Manager, Kafka, OpenSearch, Flink）
- ✅ 数据导入到 Kafka raw topic
- ✅ Flink 解析和处理（raw → events → alerts）
- ✅ 告警写入 OpenSearch
- ✅ 数据流完整性验证

**📖 完整测试文档**: [tests/README.md](tests/README.md) - 113+ 测试，187+ 验证点

### 真实安装验证

验证 Agentless 部署的完整安装和卸载流程（**需要 root 权限**）：

```bash
# 1. 完整安装测试（17 个验证点）
sudo make test-e2e-agentless-install
```

**安装测试验证内容**：
- ✅ 预注册 Collector 并生成安装令牌
- ✅ 执行安装脚本（auditd + rsyslog + systemd 服务）
- ✅ 心跳上报和状态更新（inactive → active）
- ✅ 数据采集验证（auditd → rsyslog → Vector → Kafka）
- ✅ 完整数据流验证（采集的数据包含正确的 Collector ID）

```bash
# 2. 卸载测试（10 个验证点）
sudo make test-e2e-agentless-uninstall
```

**卸载测试验证内容**：
- ✅ 获取并执行卸载脚本
- ✅ systemd 服务删除验证
- ✅ 配置文件清理验证（/etc/sysarmor、rsyslog、auditd 规则）
- ✅ 环境完全清理验证

⚠️ **重要提示**：安装测试完成后，请务必运行卸载测试清理环境

### 系统访问地址
- **🌐 Manager API**: http://localhost:8080
- **📖 API 文档**: http://localhost:8080/swagger/index.html
- **🔧 Flink 监控**: http://localhost:8081
- **📊 Prometheus**: http://localhost:9090
- **🔍 OpenSearch**: http://localhost:9200

## 🔧 管理命令

### 部署操作
```bash
make init        # 初始化项目环境
make deploy      # 🎯 部署基础设施（推荐）- Manager + Middleware + Processor + Indexer
make deploy-full # 完整部署（基础设施 + 前端）
make deploy-dev  # 开发部署（基础设施 + 开发前端，支持热更新）
make up          # 启动服务（不重新构建）
make down        # 停止所有服务
make restart     # 重启所有服务
```

### 监控测试
```bash
make status      # 查看服务状态
make health      # 系统健康检查（8 个检查点）
make test        # 集成测试（健康检查 + 54 个 API 端点）
```

### 单元测试
```bash
make test-unit           # Go 单元测试（15 测试 + 4 基准）
make test-unit-verbose   # 单元测试（详细输出）
make test-bench          # 性能基准测试
make test-coverage       # 测试覆盖率报告
```

### E2E 测试
```bash
make test-e2e                      # 运行所有 E2E 测试（数据流 + Agentless）
make test-e2e-data-pipeline        # 数据管道 E2E（18 个验证点）
make test-e2e-agentless-install    # Agentless 安装 E2E（17 个验证点，需要 root）
make test-e2e-agentless-uninstall  # Agentless 卸载（10 个验证点，需要 root）
```

### 清理维护
```bash
make clean       # 清理构建文件和容器（深度清理）
```

### Volume 管理
```bash
make backup-certs         # 备份证书到本地
make restore-certs        # 恢复证书（需指定 FILE=backup.tar.gz）
make list-volumes         # 列出所有 SysArmor volumes
make inspect-certs-volume # 查看证书 volume 内容
```

### 完整测试套件
```bash
# 运行所有测试（113+ 测试，187+ 验证点）
./tests/run-all-tests.sh all

# 📖 详细测试文档
cat tests/README.md
```

### 工具脚本
```bash
# 数据导入
./tests/integration/tools/import-events-data.sh <file>

# Kafka 管理
./scripts/kafka-tools.sh list
./scripts/kafka-tools.sh export sysarmor.raw.audit 100

# Flink 管理
./scripts/flink-tools.sh list
./scripts/flink-tools.sh overview
```

## 📚 文档

详细文档请访问 **[📖 文档中心](docs/)**

**快速链接**:
- 🚀 **[快速开始](docs/getting-started/quickstart.md)** - 15分钟体验完整数据流
- 🏗️ **[架构设计](docs/architecture/overview.md)** - 系统架构和组件设计
- 🔌 **[Manager API](docs/api/manager-api.md)** - 54个REST API接口详细文档
- ⚙️ **[配置指南](docs/guides/configuration.md)** - 环境变量和服务配置详解
- 🧪 **[测试指南](tests/README.md)** - 单元测试、集成测试、E2E测试
- 📋 **[版本发布](docs/releases/)** - 版本历史和变更日志

---

**SysArmor EDR/HIDS** - 现代化端点检测与响应系统