From 5b0700faf2cda3f6b65379e01aa598903ed28c43 Mon Sep 17 00:00:00 2001 From: wuko233 Date: Sun, 15 Mar 2026 09:02:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=B6=88=E6=81=AF?= =?UTF-8?q?=E5=8D=8F=E8=AE=AE=E6=96=87=E6=A1=A3=EF=BC=8C=E5=AE=9A=E4=B9=89?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=8C=85=E6=A0=BC=E5=BC=8F=E5=92=8C=E6=B6=88?= =?UTF-8?q?=E6=81=AF=E7=B1=BB=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/MessageProtocol.md | 277 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 docs/MessageProtocol.md diff --git a/docs/MessageProtocol.md b/docs/MessageProtocol.md new file mode 100644 index 0000000..40bfd0c --- /dev/null +++ b/docs/MessageProtocol.md @@ -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"] + } +} +```