docs: 添加消息协议文档，定义数据包格式和消息类型
This commit is contained in:
wuko233
parent
7a85688719
commit
5b0700faf2
|
|
@ -0,0 +1,277 @@
|
||||||
|
# 消息交互
|
||||||
|
|
||||||
|
## 数据包格式
|
||||||
|
|
||||||
|
### 通用数据包结构
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "消息类型",
|
||||||
|
"timestamp": 1612345678901,
|
||||||
|
"payload": {
|
||||||
|
// 根据消息类型的具体数据结构
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据类型定义
|
||||||
|
```go
|
||||||
|
type Packet struct {
|
||||||
|
Type string `json:"type"` // 消息类型
|
||||||
|
Timestamp int64 `json:"timestamp"` // Unix时间戳
|
||||||
|
Payload interface{} `json:"payload"` // 消息载荷
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 消息类型及数据结构
|
||||||
|
|
||||||
|
### 1. 系统状态更新 (`STATUS_UPDATE`)
|
||||||
|
|
||||||
|
**描述**: 定期发送的系统性能指标
|
||||||
|
|
||||||
|
**推送频率**: 每30秒一次
|
||||||
|
|
||||||
|
**Payload 结构**: `ServerMetrics`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"timestamp": "2024-01-15T10:30:00Z",
|
||||||
|
"cpu": {
|
||||||
|
"model": "Intel(R) Xeon(R) CPU E5-2680 v4",
|
||||||
|
"cores": 14,
|
||||||
|
"logical_cores": 28,
|
||||||
|
"usage_percent": 45.67,
|
||||||
|
"per_core_percent": [23.4, 45.6, 12.3, ...],
|
||||||
|
"mhz": 2400.5,
|
||||||
|
"cache_size": 35840
|
||||||
|
},
|
||||||
|
"memory": {
|
||||||
|
"total_gb": 128.0,
|
||||||
|
"used_gb": 64.5,
|
||||||
|
"available_gb": 63.5,
|
||||||
|
"used_percent": 50.4,
|
||||||
|
"swap_total_gb": 16.0,
|
||||||
|
"swap_used_gb": 2.3
|
||||||
|
},
|
||||||
|
"disk": [
|
||||||
|
{
|
||||||
|
"mountpoint": "/",
|
||||||
|
"device": "/dev/sda1",
|
||||||
|
"fstype": "ext4",
|
||||||
|
"total_gb": 500.0,
|
||||||
|
"used_gb": 250.0,
|
||||||
|
"free_gb": 250.0,
|
||||||
|
"used_percent": 50.0,
|
||||||
|
"inodes_percent": 12.3
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"network": {
|
||||||
|
"interfaces": [
|
||||||
|
{
|
||||||
|
"name": "eth0",
|
||||||
|
"hardware_addr": "00:11:22:33:44:55",
|
||||||
|
"ip_addresses": ["192.168.1.100", "fe80::211:22ff:fe33:4455"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total_recv_mb": 1234.56,
|
||||||
|
"total_sent_mb": 987.65,
|
||||||
|
"tcp_connections": 245,
|
||||||
|
"established_conn": 128
|
||||||
|
},
|
||||||
|
"load": {
|
||||||
|
"load_1": 2.34,
|
||||||
|
"load_5": 2.12,
|
||||||
|
"load_15": 1.89,
|
||||||
|
"relative_load_1": 0.83,
|
||||||
|
"relative_load_5": 0.76,
|
||||||
|
"relative_load_15": 0.68,
|
||||||
|
"procs_running": 132,
|
||||||
|
"procs_total": 456
|
||||||
|
},
|
||||||
|
"processes": [
|
||||||
|
{
|
||||||
|
"pid": 1234,
|
||||||
|
"name": "nginx",
|
||||||
|
"cmdline": "nginx: master process",
|
||||||
|
"memory_mb": 125.6,
|
||||||
|
"cpu_percent": 12.3
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"host": {
|
||||||
|
"hostname": "server01",
|
||||||
|
"os": "linux",
|
||||||
|
"platform": "ubuntu",
|
||||||
|
"platform_version": "20.04",
|
||||||
|
"kernel_version": "5.4.0-42-generic",
|
||||||
|
"boot_time": "2024-01-15T08:00:00Z",
|
||||||
|
"uptime": "2小时30分钟45秒",
|
||||||
|
"cpu_count": 28,
|
||||||
|
"architecture": "x86_64",
|
||||||
|
"host_id": "abcdef12-3456-7890-abcd-ef1234567890"
|
||||||
|
},
|
||||||
|
"runtime": {
|
||||||
|
"go_version": "go1.21.0",
|
||||||
|
"goos": "linux",
|
||||||
|
"goarch": "amd64",
|
||||||
|
"goroot": "/usr/local/go",
|
||||||
|
"gomaxprocs": 28,
|
||||||
|
"num_cpu": 28,
|
||||||
|
"num_goroutine": 42
|
||||||
|
},
|
||||||
|
"quick_metrics": {
|
||||||
|
"cpu_percent": 45.67,
|
||||||
|
"memory_percent": 50.4,
|
||||||
|
"root_disk_percent": 50.0,
|
||||||
|
"available_memory_gb": 63.5
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. SSH登录告警 (`SSH_ALERT`)
|
||||||
|
|
||||||
|
**描述**: SSH登录安全告警（特别是root登录）
|
||||||
|
|
||||||
|
**触发条件**: SSH登录事件，当检测到root登录时触发HIGH级别告警
|
||||||
|
|
||||||
|
**Payload 结构**: `Alert`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "SSH_ROOT_LOGIN",
|
||||||
|
"level": "HIGH",
|
||||||
|
"message": "检测到来自192.168.1.50的root登录",
|
||||||
|
"timestamp": "2024-01-15T10:31:15Z",
|
||||||
|
"data": {
|
||||||
|
"timestamp": "2024-01-15T10:31:15Z",
|
||||||
|
"hostname": "server01",
|
||||||
|
"username": "root",
|
||||||
|
"method": "publickey",
|
||||||
|
"source_ip": "192.168.1.50",
|
||||||
|
"port": "22",
|
||||||
|
"service": "sshd",
|
||||||
|
"pid": "12345",
|
||||||
|
"message": "Accepted publickey for root from 192.168.1.50 port 22"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 文件完整性告警
|
||||||
|
|
||||||
|
#### 3.1 非白名单文件告警 (`NON_WHITELISTED_FILE`)
|
||||||
|
|
||||||
|
**描述**: 扫描发现不在白名单中的文件
|
||||||
|
|
||||||
|
**触发条件**: 定期扫描中发现未在白名单中注册的文件
|
||||||
|
|
||||||
|
**Payload 结构**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "NON_WHITELISTED_FILE",
|
||||||
|
"timestamp": 1612345678901,
|
||||||
|
"payload": {
|
||||||
|
"filepath": "/tmp/suspicious_file.bin",
|
||||||
|
"status": "detected"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3.2 文件Hash不匹配告警 (`FILE_HASH_MISMATCH`)
|
||||||
|
|
||||||
|
**描述**: 白名单文件被篡改（Hash值不匹配）
|
||||||
|
|
||||||
|
**触发条件**: 文件hash与白名单记录不符
|
||||||
|
|
||||||
|
**Payload 结构**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "FILE_HASH_MISMATCH",
|
||||||
|
"timestamp": 1612345678901,
|
||||||
|
"payload": {
|
||||||
|
"filepath": "/usr/bin/ls",
|
||||||
|
"status": "detected"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 实时文件监控告警
|
||||||
|
|
||||||
|
#### 4.1 实时文件变动告警 (`REALTIME_FILE_ALERT`)
|
||||||
|
|
||||||
|
**描述**: 监控目录中检测到非白名单文件的创建或修改
|
||||||
|
|
||||||
|
**触发条件**: 使用fsnotify监控到文件系统事件
|
||||||
|
|
||||||
|
**Payload 结构**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "REALTIME_FILE_ALERT",
|
||||||
|
"timestamp": 1612345678901,
|
||||||
|
"payload": {
|
||||||
|
"filepath": "/tmp/new_suspicious_file",
|
||||||
|
"operation": "CREATE",
|
||||||
|
"time": "2024-01-15T10:32:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4.2 实时Hash不匹配告警 (`REALTIME_HASH_MISMATCH`)
|
||||||
|
|
||||||
|
**描述**: 监控到白名单文件被实时篡改
|
||||||
|
|
||||||
|
**Payload 结构**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "REALTIME_HASH_MISMATCH",
|
||||||
|
"timestamp": 1612345678901,
|
||||||
|
"payload": {
|
||||||
|
"filepath": "/etc/passwd",
|
||||||
|
"operation": "WRITE",
|
||||||
|
"time": "2024-01-15T10:33:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 配置接口
|
||||||
|
|
||||||
|
### 1. 配置下载接口
|
||||||
|
|
||||||
|
Agent 启动时会通过 HTTP 下载两份配置：
|
||||||
|
|
||||||
|
#### 官方配置 (GET)
|
||||||
|
- **URL**: `http://localhost:8090/api/v1/configs/official.json`
|
||||||
|
- **响应格式**: 符合 `OfficialConfig` 结构
|
||||||
|
|
||||||
|
#### 用户配置 (GET)
|
||||||
|
- **URL**: `http://localhost:8090/api/v1/configs/user.json`
|
||||||
|
- **响应格式**: 符合 `UserConfig` 结构
|
||||||
|
|
||||||
|
### 2. 配置数据结构
|
||||||
|
|
||||||
|
#### OfficialConfig
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"whitelist_files": {
|
||||||
|
"/usr/bin/ls": ["hash1", "hash2"],
|
||||||
|
"/bin/bash": ["hash3"]
|
||||||
|
},
|
||||||
|
"whitelist_processes": ["sshd", "nginx", "docker"],
|
||||||
|
"ignored_paths": ["/proc", "/sys", "/dev"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### UserConfig
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"audit_server_url": "ws://audit.example.com:8090/api/v1/ws",
|
||||||
|
"supplement_files": {
|
||||||
|
"/opt/myapp/bin/app": ["user_hash1"]
|
||||||
|
},
|
||||||
|
"supplement_processes": {
|
||||||
|
"myapp": "/opt/myapp/bin/app start",
|
||||||
|
"custom_service": ""
|
||||||
|
},
|
||||||
|
"ignored_paths": ["/mnt/temp"],
|
||||||
|
"check_perm_paths": ["/etc/sudoers", "/etc/shadow"],
|
||||||
|
"email_config": {
|
||||||
|
"imap_server": "imap.example.com",
|
||||||
|
"emergency_mail": ["admin@example.com", "security@example.com"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user