# sysarmor

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

## Basic Information

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

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2026-03-05

## 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 <repository-url>
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 规则）
- ✅ 环境完全清理验证

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

### 系统访问地址
- **🎨 Web 界面**: http://localhost:3000（需部署前端）
- **🌐 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

# 部署基础设施（Manager + Middleware + Processor + Indexer）
make deploy

# 完整部署（基础设施 + 生产前端）
make deploy-full

# 开发部署（基础设施 + 开发前端，支持热更新）
make deploy-dev
```

**前端独立部署**（需要先部署基础设施）：
```bash
make deploy-ui      # 部署生产前端
make deploy-ui-dev  # 部署开发前端（支持热更新）
make down-ui        # 停止前端服务
```

### 服务管理
```bash
make up          # 启动服务（不重新构建）
make down        # 停止所有服务
make restart     # 重启所有服务
make status      # 查看服务状态
```

### 测试验证
```bash
make health      # 系统健康检查（8 个检查点）
make test        # 集成测试（健康检查 + API 端点）
make test-e2e    # E2E 测试（数据流 + Agentless）
```

### 数据管理
```bash
make seed-generate  # 生成示例数据文件
make seed          # 导入数据到数据库
make seed-clean    # 清理数据
make seed-reset    # 重置数据（清理 + 导入）
```

**📦 示例数据内容**:
- 5 个 Collectors (prod/staging/dev 环境)
- 4 个 Alerts (不同严重级别)
- 3 个 Threats (APT/内部威胁/暴力破解)
- 1 个完整威胁图谱 (7节点攻击链)

**📖 更多运维命令**: 详见 [运维指南](docs/guides/operations.md) - 包含单元测试、性能测试、数据管理、Volume 管理、工具脚本等完整运维操作

## 📚 文档

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

**快速链接**:
- 🚀 **[快速开始](docs/getting-started/quickstart.md)** - 15分钟体验完整数据流
- 🏗️ **[架构设计](docs/architecture/overview.md)** - 系统架构和组件设计
- 🔧 **[运维指南](docs/guides/operations.md)** - 完整的部署、监控、测试、维护操作手册
- 🔌 **[Manager API](docs/api/manager-api.md)** - REST API接口详细文档
- ⚙️ **[配置指南](docs/guides/configuration.md)** - 环境变量和服务配置详解
- 🧪 **[测试指南](tests/README.md)** - 单元测试、集成测试、E2E测试

---

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