CISECSL/aisac-agent
GitHub: CISECSL/aisac-agent
一款面向 SOAR 系统的轻量级跨平台安全代理，集成自动化事件响应、日志采集与资产监控能力。
Stars: 1 | Forks: 0
# AISAC Agent
[](https://go.dev/)
[](LICENSE)
[]()
**AISAC Agent** 是一个用 Go 编写的多功能安全 Agent，提供：
- **SOAR 响应**：执行由 SOAR 系统下达的事件响应操作
- **SIEM 采集**：收集日志并转发至 AISAC 平台
- **资产监控**：通过心跳上报 Agent 健康状态和系统指标
它可以根据您的需求以多种运行模式部署在端点和服务器上。
## 快速安装
### Linux (一键安装)
```
curl -sSL https://raw.githubusercontent.com/CISECSL/aisac-agent/main/scripts/quick-install.sh \
-o /tmp/quick-install.sh && sudo bash /tmp/quick-install.sh
```
这将下载最新的 release 二进制文件并启动配置向导。
### 从源码安装 (需要 Go 1.21+)
```
git clone https://github.com/CISECSL/aisac-agent.git
cd aisac-agent
sudo ./scripts/install.sh
```
### 前置条件
在安装之前，您需要从 AISAC dashboard 获取以下信息：
- **API Key** (`aisac_xxxx...`) — Dashboard > Assets > API Key
- **Asset ID** (UUID) — Dashboard > Assets > ID
## 目录
- [快速安装](#quick-install)
- [概述](#overview)
- [运行模式](#operating-modes)
- [架构](#architecture)
- [功能](#features)
- [配置](#configuration)
- [Agent 配置](#agent-configuration)
- [心跳配置](#heartbeat-configuration)
- [收集器配置](#collector-configuration)
- [SOAR 配置](#soar-configuration)
- [支持的操作](#supported-actions)
- [REST API](#rest-api)
- [通信协议](#communication-protocol)
- [安全功能](#security-features)
- [平台支持](#platform-support)
- [开发](#development)
- [测试](#testing)
- [部署](#deployment)
- [路线图](#roadmap)
- [贡献](#contributing)
- [许可证](#license)
## 概述
AISAC Agent 是完整安全运营平台的一部分。该 Agent 运行在端点上（Linux, Windows, macOS）并提供三项主要能力：
1. **SOAR 响应 Agent**：通过 WebSocket 连接到中央 Command Server，并使用双向 TLS 认证。当您的 SIEM/SOAR 系统检测到安全事件时，自动响应操作会被发送给 Agent 以立即执行。
2. **SIEM 日志收集器**：从各种来源（Suricata, syslog, JSON 文件）收集日志，并将其转发至 AISAC 平台进行分析和关联。
3. **资产健康监控器**：通过心跳向 AISAC 平台报告 Agent 状态和系统指标（CPU, 内存, 磁盘），实现资产清单和健康监控。
**主要优势：**
- 自动化事件响应，降低 MTTR (Mean Time To Respond)
- 集中式日志收集以供 SIEM 分析
- 实时资产健康监控
- 通过 mTLS 或 API key 认证进行安全通信
- 跨平台支持 (Linux, Windows, macOS)
- 可扩展的操作框架
- 速率限制和安全控制
- 用于合规性的审计日志
## 运行模式
AISAC Agent 支持灵活的部署配置：
### 模式 1: 完整 SOAR 模式 (默认)
Agent 通过 WebSocket 连接到 Command Server 以接收并执行安全操作。
```
server:
enabled: true
url: "wss://command-server:8443/ws"
tls:
enabled: true
# mTLS certificates required
```
**使用场景**：需要自动事件响应能力的端点。
### 模式 2: 仅心跳模式
Agent 向 AISAC 平台报告状态，但不具备 SOAR 能力。不需要 Command Server 或 mTLS 证书。
```
server:
enabled: false
heartbeat:
enabled: true
url: "https://api.aisac.cisec.es/v1/heartbeat"
api_key: "aisac_your_api_key_here"
asset_id: "your-asset-uuid-here"
```
**使用场景**：无需命令执行的资产监控，轻量级部署。
### 模式 3: 收集器模式 (SIEM)
Agent 收集日志并将其转发至 AISAC 平台。
```
server:
enabled: false
collector:
enabled: true
sources:
- name: suricata
type: file
path: /var/log/suricata/eve.json
parser: suricata_eve
output:
type: http
url: "https://api.aisac.cisec.es/v1/logs"
api_key: "aisac_your_api_key_here"
```
**使用场景**：从 IDS/IPS、防火墙和系统日志中收集日志。
### 模式 4: 组合模式
所有功能同时启用。
```
server:
enabled: true
url: "wss://command-server:8443/ws"
heartbeat:
enabled: true
url: "https://api.aisac.cisec.es/v1/heartbeat"
api_key: "aisac_your_api_key_here"
asset_id: "your-asset-uuid-here"
collector:
enabled: true
# ... collector configuration
```
**使用场景**：包含响应、收集和监控的全面安全运营
## 架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ AISAC Platform │
│ (React + Supabase + Edge Functions) │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ │
│ │ Asset Dashboard │ │ SIEM Analytics │ │ Incident Response │ │
│ └────────▲────────┘ └────────▲─────────┘ └──────────┬──────────┘ │
└───────────┼────────────────────┼───────────────────────┼────────────┘
│ Heartbeat │ Log Ingest │ Webhook
│ API │ API ▼
│ │ ┌────────────────────┐
│ │ │ n8n Workflow │
│ │ │ (Orchestration) │
│ │ └─────────┬──────────┘
│ │ │ REST API
│ │ ▼
│ │ ┌────────────────────┐
│ │ │ Command Server │
│ │ │ (WebSocket + API) │
│ │ └─────────┬──────────┘
│ │ │ WebSocket + mTLS
│ │ ┌───────────┼───────────┐
▼ ▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ AISAC Agent │
│ ┌──────────────┐ ┌───────────────┐ ┌───────────────────────────┐ │
│ │ Heartbeat │ │ Collector │ │ Executor │ │
│ │ (Status) │ │ (SIEM) │ │ (SOAR) │ │
│ │ │ │ │ │ │ │
│ │ • CPU/Mem │ │ • Suricata │ │ • Response: │ │
│ │ • Disk │ │ • Wazuh │ │ block_ip, isolate_host │ │
│ │ • Uptime │ │ • Syslog │ │ • Investigation: │ │
│ │ │ │ • JSON logs │ │ dns_lookup, check_hash │ │
│ │ │ │ • Batching │ │ • Forensics: │ │
│ │ │ │ │ │ collect_forensics │ │
│ └──────────────┘ └───────────────┘ └───────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### 组件角色
- **AISAC Platform**：基于 Web 的安全运营平台，包含仪表盘、分析和事件管理
- **n8n Workflow Engine**：编排安全工作流并触发 Agent 命令
- **Command Server**：Agent 管理和 SOAR 命令分发的中央枢纽
- **Agent - Heartbeat**：向平台报告 Agent 健康状况和系统指标
- **Agent - Collector**：从各种来源收集日志并转发给 SIEM
- **Agent - Executor**：执行安全响应操作（封锁 IP、隔离主机等）
## 功能
### SOAR 响应
- **实时 WebSocket 通信**：具有自动重连功能的持久连接
- **双向 TLS 认证**：使用 mTLS 进行安全的 Agent-Server 认证
- **操作框架**：用于实现安全操作的可扩展系统
- **响应操作**：封锁 IP、隔离主机、禁用用户、终止进程
- **调查操作**：DNS 查询、哈希信誉、IP 信誉、IOC 搜索
- **取证操作**：收集取证证据、威胁搜寻
- **速率限制**：针对每个操作的速率限制，防止意外过载
- **输入验证**：对 IP 地址、用户名、进程名进行严格验证
- **受保护资源**：防止对系统关键账户和进程执行操作
- **SOAR 回调**：可选的外部系统（n8n, SOAR 平台）webhook 回调
- **平台 Webhook**：连接到 Command Server 时自动进行 Agent 注册
### SIEM 采集
- **多源日志收集**：Suricata EVE, Wazuh alerts, syslog, 通用 JSON 文件
- **智能事件过滤**：Suricata 解析器过滤遥测数据，保留与安全相关的事件
- **高效批处理**：可配置的批量大小和刷新间隔
- **断点续传支持**：Sincedb 跟踪以在重启后保持位置持久性
- **文件轮转检测**：自动处理日志轮转
- **HTTP 输出**：安全地将日志转发到 AISAC ingest API
### 资产监控
- **心跳上报**：向 AISAC 平台定期更新状态
- **系统指标**：CPU、内存、磁盘使用情况监控
- **动态间隔**：服务器控制的心跳频率
- **API Key 认证**：简单且安全的认证方式
### 通用
- **多种运行模式**：SOAR、收集器、心跳或组合模式
- **结构化日志**：使用 zerolog 进行 JSON 日志记录
- **跨平台**：原生支持 Linux, Windows 和 macOS
- **简易安装**：Linux 一键安装程序
## 支持的操作
### 响应操作
| 操作 | 描述 | 平台 | 状态 |
|--------|-------------|-----------|--------|
| `block_ip` | 在防火墙中封锁 IP 地址 | Linux (iptables/nftables), Windows Firewall, macOS (pf) | ✅ 稳定 |
| `unblock_ip` | 从防火墙中移除 IP 封锁 | Linux (iptables/nftables), Windows Firewall, macOS (pf) | ✅ 稳定 |
| `isolate_host` | 将主机从网络隔离 | Linux, Windows, macOS | ✅ 稳定 |
| `unisolate_host` | 恢复网络连接 | Linux, Windows, macOS | ✅ 稳定 |
| `disable_user` | 禁用用户账户 | Linux (usermod), Windows (net user/AD), macOS (dscl) | ✅ 稳定 |
| `enable_user` | 重新启用用户账户 | Linux (usermod), Windows (net user/AD), macOS (dscl) | ✅ 稳定 |
| `kill_process` | 根据名称或 PID 终止进程 | Linux, Windows, macOS | ✅ 稳定 |
### 调查操作
| 操作 | 描述 | 平台 | 状态 |
|--------|-------------|-----------|--------|
| `dns_lookup` | 执行 DNS 解析查询 | 所有 | ✅ 稳定 |
| `check_hash` | 检查文件哈希信誉 (VirusTotal 等) | 所有 | ✅ 稳定 |
| `check_ip_reputation` | 根据威胁情报检查 IP 信誉 | 所有 | ✅ 稳定 |
| `search_ioc` | 在主机上搜索失陷指标 | 所有 | ✅ 稳定 |
### 取证操作
| 操作 | 描述 | 平台 | 状态 |
|--------|-------------|-----------|--------|
| `collect_forensics` | 收集取证证据（内存、磁盘痕迹） | 所有 | ✅ 稳定 |
| `threat_hunt` | 搜索威胁指标和可疑活动 | 所有 | ✅ 稳定 |
### 操作示例
#### 封锁 IP 地址
```
{
"action": "block_ip",
"parameters": {
"ip_address": "192.168.1.100",
"duration": 3600,
"rule_name": "malicious_ip_block"
}
}
```
#### 禁用用户账户
```
{
"action": "disable_user",
"parameters": {
"username": "compromised_user",
"reason": "account_compromise"
}
}
```
#### 终止进程
```
{
"action": "kill_process",
"parameters": {
"process_name": "malware.exe",
"force": true
}
}
```
#### DNS 查询
```
{
"action": "dns_lookup",
"parameters": {
"hostname": "suspicious-domain.com",
"record_type": "A"
}
}
```
#### 检查哈希信誉
```
{
"action": "check_hash",
"parameters": {
"hash": "44d88612fea8a8f36de82e1278abb02f",
"hash_type": "md5"
}
}
```
#### 检查 IP 信誉
```
{
"action": "check_ip_reputation",
"parameters": {
"ip_address": "203.0.113.42"
}
}
```
#### 搜索 IOC
```
{
"action": "search_ioc",
"parameters": {
"ioc_type": "hash",
"ioc_value": "44d88612fea8a8f36de82e1278abb02f",
"search_paths": ["/var/log", "/tmp"]
}
}
```
#### 收集取证数据
```
{
"action": "collect_forensics",
"parameters": {
"artifact_types": ["processes", "connections", "files"],
"output_path": "/tmp/forensics"
}
}
```
## 技术栈
- **语言**: Go 1.21+
- **WebSocket**: [gorilla/websocket](https://github.com/gorilla/websocket)
- **HTTP 路由器**: [gorilla/mux](https://github.com/gorilla/mux)
- **日志**: [zerolog](https://github.com/rs/zerolog)
- **CLI 框架**: [cobra](https://github.com/spf13/cobra)
- **配置**: YAML ([gopkg.in/yaml.v3](https://gopkg.in/yaml.v3))
- **构建工具**: Makefile + [GoReleaser](https://goreleaser.com/)
- **TLS**: Go crypto/tls (双向 TLS)
## 从源码构建
```
git clone https://github.com/CISECSL/aisac-agent.git
cd aisac-agent
make deps
make build
```
这将创建：
- `build/aisac-agent` - Agent 二进制文件
- `build/aisac-server` - Command server 二进制文件
有关详细的安装、配置和部署说明，请参阅 **[docs/INSTALL.md](docs/INSTALL.md)**。
## 配置
Agent 通过 YAML 文件进行配置（默认：`/etc/aisac/agent.yaml`）。
### Agent 配置
```
agent:
# Agent ID (auto-generated if empty)
id: ""
# Labels for agent grouping/filtering
labels:
- production
- webserver
# Internal heartbeat interval (WebSocket ping)
heartbeat_interval: 30s
# Reconnection settings
reconnect_delay: 5s
max_reconnect_delay: 5m
logging:
level: "info" # debug, info, warn, error
format: "json" # json, text
output: "stdout" # stdout, file
file: "/var/log/aisac/agent.log"
```
### 心跳配置
向 AISAC 平台报告 Agent 状态和指标：
```
heartbeat:
# Enable heartbeat reporting
enabled: true
# AISAC Platform heartbeat endpoint
url: "https://api.aisac.cisec.es/v1/heartbeat"
# API Key for authentication (format: aisac_xxxx...)
# Get this from the AISAC Platform when registering the asset
api_key: "aisac_your_api_key_here"
# Asset ID (UUID from AISAC Platform)
# This identifies the monitored asset in the platform
asset_id: "your-asset-uuid-here"
# Heartbeat interval (server can override via response)
interval: 120s
# Request timeout
timeout: 10s
# Skip TLS verification (NOT RECOMMENDED)
skip_tls_verify: false
```
**心跳负载**（发送至服务器）：
```
{
"asset_id": "uuid-here",
"timestamp": "2024-12-04T12:34:56Z",
"agent_version": "1.0.1",
"metrics": {
"cpu_percent": 45.2,
"memory_percent": 68.5,
"disk_percent": 55.0,
"uptime_seconds": 86400
}
}
```
### 收集器配置
收集日志并转发至 AISAC SIEM：
```
collector:
# Enable log collection
enabled: true
# Log sources to collect
sources:
# Suricata EVE JSON logs
- name: suricata
type: file
path: /var/log/suricata/eve.json
parser: suricata_eve
tags:
- security
- ids
# System syslog
- name: syslog
type: file
path: /var/log/syslog
parser: syslog
tags:
- system
# Generic JSON logs
- name: app_logs
type: file
path: /var/log/myapp/*.json
parser: json
tags:
- application
# Output configuration
output:
# Output type: http
type: http
# Ingest endpoint URL
url: "https://api.aisac.cisec.es/v1/logs"
# API Key for authentication
api_key: "aisac_your_api_key_here"
# Request timeout
timeout: 30s
# Number of retry attempts
retry_attempts: 3
# Delay between retries
retry_delay: 5s
# Batching configuration
batch:
# Number of events per batch
size: 100
# Maximum time before flushing (even if batch not full)
interval: 5s
# File reading configuration
file:
# Start position for new files: "end" or "beginning"
start_position: end
# Path to store file positions (for resume after restart)
sincedb_path: /var/lib/aisac/sincedb.json
```
**支持的解析器**：
| 解析器 | 描述 |
|--------|-------------|
| `suricata_eve` | Suricata EVE JSON 格式（过滤遥测数据，保留安全事件） |
| `syslog` | RFC3164/RFC5424 syslog |
| `json` | 通用 JSON 日志 |
| `wazuh` | Wazuh HIDS alerts JSON 格式 |
**注意**：Suricata 解析器会自动过滤掉遥测事件（flow, netflow, stats, dns, http, tls 等），仅处理与安全相关的事件（alert, anomaly, drop, pkthdr），以减少数据量并防止事件通道饱和。
### SOAR 配置
启用来自 SOAR 系统的命令执行：
```
server:
# Enable SOAR functionality (receive commands from server)
# Set to false to run in collector/heartbeat-only mode
enabled: true
# Command server WebSocket URL
url: "wss://localhost:8443/ws"
# Connection timeout
connect_timeout: 30s
write_timeout: 10s
read_timeout: 60s
tls:
# Enable mTLS (required when server.enabled is true)
enabled: true
cert_file: "/etc/aisac/certs/agent.crt"
key_file: "/etc/aisac/certs/agent.key"
ca_file: "/etc/aisac/certs/ca.crt"
skip_verify: false
actions:
# Only these actions will be executed
enabled:
# Response actions
- block_ip
- unblock_ip
- isolate_host
- unisolate_host
- disable_user
- enable_user
- kill_process
# Investigation actions
- dns_lookup
- check_hash
- check_ip_reputation
- search_ioc
# Forensics actions
- collect_forensics
- threat_hunt
# Rate limits per action (prevent abuse)
rate_limits:
block_ip:
max_per_minute: 10
max_per_hour: 100
isolate_host:
max_per_minute: 1
max_per_hour: 5
default_timeout: 5m
# 可选：SOAR 回调配置
callback:
enabled: false
url: "https://n8n.example.com/webhook/aisac-callback"
auth_token: ""
timeout: 30s
retry_attempts: 3
retry_delay: 5s
```
### 环境变量
| 变量 | 描述 | 示例 |
|----------|-------------|---------|
| **通用** | | |
| `AISAC_AGENT_ID` | Agent 唯一标识符 | `agent-prod-web01` |
| `AISAC_LOG_LEVEL` | 日志级别 | `info` |
| **SOAR 模式** | | |
| `AISAC_SERVER_URL` | WebSocket 服务器 URL | `wss://server:8443/ws` |
| `AISAC_CERT_FILE` | Agent 证书路径 | `/etc/aisac/certs/agent.crt` |
| `AISAC_KEY_FILE` | Agent 私钥路径 | `/etc/aisac/certs/agent.key` |
| `AISAC_CA_FILE` | CA 证书路径 | `/etc/aisac/certs/ca.crt` |
| **心跳** | | |
| `AISAC_HEARTBEAT_API_KEY` | 心跳 API key | `aisac_xxxx...` |
| `AISAC_HEARTBEAT_ASSET_ID` | 来自平台的 Asset UUID | `uuid-here` |
| **收集器** | | |
| `AISAC_COLLECTOR_API_KEY` | 收集器 API key | `aisac_xxxx...` |
| **安装程序** | | |
| `AISAC_REGISTER_URL` | 覆盖注册端点 (staging) | `https://staging-api.aisac.cisec.es/v1/webhooks/agent-connected` |
| `AISAC_NONINTERACTIVE` | 以非交互模式运行安装程序 `true` |
## REST API
Command Server 暴露了一个 REST API 用于 Agent 管理和命令执行。
### 认证
所有 API 端点（`/health` 除外）均需要 Bearer token 认证：
```
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
https://server:8443/api/v1/agents
```
### 端点
#### 1. 健康检查
```
GET /api/v1/health
```
**响应：**
```
{
"status": "healthy",
"version": "1.0.0",
"agent_count": 5
}
```
#### 2. 列出所有 Agent
```
GET /api/v1/agents
Authorization: Bearer YOUR_TOKEN
```
**响应：**
```
[
{
"id": "agent-001",
"hostname": "web-server-01",
"platform": "linux",
"arch": "amd64",
"version": "1.0.0",
"labels": ["production", "webserver"],
"status": "connected",
"last_seen": "2024-12-04T12:34:56Z"
}
]
```
#### 3. 获取 Agent 详情
```
GET /api/v1/agents/{id}
Authorization: Bearer YOUR_TOKEN
```
**响应：**
```
{
"id": "agent-001",
"hostname": "web-server-01",
"platform": "linux",
"arch": "amd64",
"version": "1.0.0",
"labels": ["production", "webserver"],
"status": "connected",
"last_seen": "2024-12-04T12:34:56Z"
}
```
#### 4. 向 Agent 发送命令
```
POST /api/v1/agents/{id}/command
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"action": "block_ip",
"parameters": {
"ip_address": "192.168.1.100",
"duration": 3600
},
"execution_id": "exec-soar-12345",
"timeout_seconds": 30
}
```
**响应：**
```
{
"command_id": "cmd-1701692896123456789",
"status": "sent"
}
```
### 示例：通过 curl 发送命令
```
curl -X POST \
-H "Authorization: Bearer YOUR_SECURE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "block_ip",
"parameters": {
"ip_address": "203.0.113.42",
"duration": 7200,
"rule_name": "block_malicious_ip"
},
"execution_id": "soar-exec-001",
"timeout_seconds": 30
}' \
https://localhost:8443/api/v1/agents/agent-001/command
```
## 通信协议
### 消息类型
#### 服务器 → Agent
- `command` - 执行操作
- `ping` - 连接健康检查
- `config_update` - 更新 Agent 配置
- `cancel` - 取消正在运行的命令
#### Agent → 服务器
- `register` - 初始注册
- `response` - 操作执行结果
- `heartbeat` - 定期状态更新
- `pong` - Ping 响应
### 命令消息格式
```
{
"id": "cmd-1701692896123456789",
"type": "command",
"timestamp": "2024-12-04T12:34:56Z",
"payload": {
"id": "cmd-1701692896123456789",
"action": "block_ip",
"parameters": {
"ip_address": "192.168.1.100",
"duration": 3600
},
"execution_id": "exec-soar-12345",
"timeout_seconds": 30,
"priority": 1
}
}
```
### 响应消息格式
```
{
"id": "resp-1701692896987654321",
"type": "response",
"timestamp": "2024-12-04T12:35:02Z",
"payload": {
"id": "resp-1701692896987654321",
"command_id": "cmd-1701692896123456789",
"status": "success",
"result": {
"success": true,
"message": "IP 192.168.1.100 blocked successfully",
"details": {
"rule_id": "aisac-block-192.168.1.100",
"expiry": "2024-12-04T13:34:56Z"
}
},
"execution_time_ms": 150
}
}
```
## 安全功能
### 1. 双向 TLS (mTLS) 认证
- 服务器和 Agent 均使用 X.509 证书进行认证
- 防止未授权 Agent 连接
- 加密所有通信
### 2. API Bearer Token 认证
- 所有非健康检查端点的 REST API 均需要 Bearer token
- Token 必须通过 `--api-token` 标志提供
- Token 应随机生成并安全存储
### 3. 输入验证
- IP 地址验证支持 CIDR 表示法
- 用户名根据允许的字符集进行验证
- 进程名经过清理以防止命令注入
### 4. 受保护的系统资源
- 无法禁用系统账户（root, administrator 等）
- 无法终止关键系统进程
- 可配置的保护列表
### 5. 速率限制
- 每个操作的速率限制（每分钟和每小时）
- 防止意外或恶意过载
- 可针对每种操作类型配置限制
### 6. 操作白名单
- 仅可执行明确启用的操作
- 默认拒绝策略
- 针对 Agent 的操作控制
### 7. 审计日志
- 所有操作均以结构化 JSON 格式记录
- 包括执行时间、参数和结果
- 适用于 SIEM 集成
### 8. 超时保护
- 默认和针对特定命令的超时设置
- 防止操作挂起
- 支持优雅取消
## 平台支持
| 功能 | Linux | Windows | macOS |
|---------|-------|---------|-------|
| `block_ip` | iptables, nftables | Windows Firewall | PF (Packet Filter) |
| `unblock_ip` | iptables, nftables | Windows Firewall | PF (Packet Filter) |
| `isolate_host` | iptables | Windows Firewall | PF |
| `unisolate_host` | iptables | Windows Firewall | PF |
| `disable_user` | usermod | net user, AD | dscl |
| `enable_user` | usermod | net user, AD | dscl |
| `kill_process` | kill, pkill | taskkill | kill, pkill |
### 平台特定说明
#### Linux
- 需要 `root` 或 `sudo` 权限
- 同时支持 iptables 和 nftables
- 测试于 Ubuntu 20.04+, RHEL 8+, Debian 11+
#### Windows
- 需要管理员权限
- Windows Firewall API 集成
- 支持 Active Directory 进行用户管理
- 测试于 Windows Server 2016+, Windows 10+
#### macOS
- 需要 `root` 或 `sudo` 权限
- 使用 PF (Packet Filter) 进行防火墙操作
- Directory Services 集成
- 测试于 macOS 11 (Big Sur)+
## 开发
### 项目结构
```
aisac-agent/
├── cmd/
│ ├── agent/ # Agent entry point
│ └── server/ # Command server entry point
├── internal/
│ ├── agent/ # Agent core logic (lifecycle, connection)
│ ├── actions/ # SOAR action implementations
│ ├── callback/ # SOAR callback client
│ ├── collector/ # SIEM log collector
│ │ ├── collector.go # Main collector component
│ │ ├── tailer.go # File tailer with rotation
│ │ ├── parser*.go # Log parsers (JSON, syslog, Suricata)
│ │ ├── output*.go # Output destinations (HTTP)
│ │ ├── batcher.go # Event batching
│ │ └── sincedb.go # Position tracking
│ ├── config/ # Configuration management
│ ├── heartbeat/ # Platform heartbeat client
│ └── platform/ # Platform-specific code
│ ├── firewall_*.go # Firewall operations
│ ├── user_*.go # User management
│ └── process_*.go # Process control
├── pkg/
│ ├── protocol/ # Communication protocol
│ └── types/ # Shared types
├── configs/ # Example configurations
├── scripts/
│ ├── install.sh # Linux installer
│ └── gen-certs.sh # Certificate generation
├── Makefile # Build automation
└── go.mod
```
### 构建命令
```
# 为当前平台构建
make build
# 仅构建 Agent
make build-agent
# 仅构建 Server
make build-server
# 为所有平台构建
make build-all
# 为特定平台构建
make build-linux
make build-windows
make build-darwin
# 跨平台构建创建：
# build/linux-amd64/
# build/linux-arm64/
# build/windows-amd64/
# build/darwin-amd64/
# build/darwin-arm64/
```
### 代码质量
```
# 格式化代码
make fmt
# 运行 Linter
make lint
# 运行 go vet
make vet
# 运行所有检查
make fmt lint vet test
```
## 测试
### 运行所有测试
```
make test
```
### 运行带覆盖率的测试
```
make test-coverage
# 在浏览器中打开 coverage.html
```
### 运行特定测试
```
# 测试特定 Package
go test -v ./internal/actions
# 测试特定函数
go test -v ./internal/actions -run TestBlockIP
# 使用 Race Detector 测试
go test -v -race ./...
```
### 测试覆盖率报告
```
make test-coverage
```
生成：
- `coverage.out` - 覆盖率数据
- `coverage.html` - HTML 覆盖率报告
## 部署
### Linux 服务 (systemd)
创建 `/etc/systemd/system/aisac-agent.service`：
```
[Unit]
Description=AISAC Security Agent
After=network.target
[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/aisac-agent --config /etc/aisac/agent.yaml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
启用并启动：
```
sudo systemctl enable aisac-agent
sudo systemctl start aisac-agent
sudo systemctl status aisac-agent
```
### Windows 服务
使用 [NSSM](https://nssm.cc/) (Non-Sucking Service Manager)：
```
nssm install AISACAgent "C:\Program Files\AISAC\aisac-agent.exe"
nssm set AISACAgent AppParameters "--config C:\Program Files\AISAC\agent.yaml"
nssm set AISACAgent DisplayName "AISAC Security Agent"
nssm set AISACAgent Description "Automated security response agent"
nssm set AISACAgent Start SERVICE_AUTO_START
nssm start AISACAgent
```
### macOS 服务 (launchd)
创建 `/Library/LaunchDaemons/com.aisac.agent.plist`：
```
Label
com.aisac.agent
ProgramArguments
/usr/local/bin/aisac-agent
--config
/etc/aisac/agent.yaml
RunAtLoad
KeepAlive
StandardErrorPath
/var/log/aisac/agent.log
StandardOutPath
/var/log/aisac/agent.log
```
加载并启动：
```
sudo launchctl load /Library/LaunchDaemons/com.aisac.agent.plist
sudo launchctl start com.aisac.agent
```
### Docker 部署
构建 Docker 镜像：
```
make docker-build
```
运行服务器：
```
docker run -d \
--name aisac-server \
-p 8443:8443 \
-v /path/to/certs:/certs \
aisac-server:latest \
--cert /certs/server.crt \
--key /certs/server.key \
--ca /certs/ca.crt \
--api-token YOUR_TOKEN
```
运行 Agent：
```
docker run -d \
--name aisac-agent \
--privileged \
-v /path/to/config:/etc/aisac \
aisac-agent:latest \
--config /etc/aisac/agent.yaml
```
**注意**：防火墙和系统操作需要 `--privileged` 权限。
## 路线图
### v1.0.0 (MVP) ✅
- [x] 支持自动重连的 WebSocket 连接
- [x] 基本操作：`block_ip`, `isolate_host`, `disable_user`, `kill_process`
- [x] YAML 配置
- [x] 结构化日志 (zerolog)
- [x] 跨平台构建
### v1.0.1 ✅
- [x] mTLS 认证
- [x] 带 Bearer token 认证的 REST API
- [x] 解除封锁/隔离/启用操作
- [x] 向 AISAC 平台进行心跳上报
- [x] 日志收集器 (SIEM 功能)
- [x] 多种运行模式（SOAR、仅心跳、收集器）
- [x] Linux 安装脚本 (`curl | bash`)
- [x] 用于无证书部署的 `server.enabled` 标志
### v1.1.0 (当前版本) ✅
- [x] 调查操作：`dns_lookup`, `check_hash`, `check_ip_reputation`, `search_ioc`
- [x] 取证操作：`collect_forensics`, `threat_hunt`
- [x] Wazuh 日志解析器支持
- [x] Suricata 事件类型过滤（仅保留安全事件）
- [x] 用于自动 Agent 注册的平台 Webhook
- [x] 用于 SOAR 分发的 Command Server URL 填充
- [x] 增强调试日志以用于故障排除
### v1.2.0 (计划中) 🚧
- [ ] Prometheus 指标端点
- [ ] Agent 自动更新机制
- [ ] Windows 安装程序 (MSI)
- [ ] Linux 软件包
### v1.3.0 (未来)
- [ ] 面向收集器的 OpenSearch 输出
- [ ] EDR 集成 (CrowdStrike, SentinelOne)
- [ ] 自定义操作插件
- [ ] Agent 分组和批量操作
- [ ] 用于 Agent 管理的 Web UI
- [ ] Kubernetes operator
## 贡献
欢迎贡献！请遵循以下准则：
1. **Fork 本仓库**
2. **创建功能分支**：`git checkout -b feature/amazing-feature`
3. **提交您的更改**：`git commit -m 'Add amazing feature'`
4. **推送到分支**：`git push origin feature/amazing-feature`
5. **发起 Pull Request**
### 开发准则
- 遵循 Go 最佳实践和惯用语
- 为新功能编写测试
- 更新文档
- 提交前运行 `make lint` 和 `make test`
- 使用约定式提交信息
### 代码风格
本项目使用：
- `gofmt` 进行格式化
- `golangci-lint` 进行 lint 检查
- Go modules 进行依赖管理
## 许可证
本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 致谢
- [gorilla/websocket](https://github.com/gorilla/websocket) - WebSocket 实现
- [zerolog](https://github.com/rs/zerolog) - 快速结构化日志
- [cobra](https://github.com/spf13/cobra) - CLI 框架
## 支持
如有问题、疑问或贡献：
- **Issues**: [GitHub Issues](https://github.com/CISECSL/aisac-agent/issues)
- **文档**: [Wiki](https://github.com/CISECSL/aisac-agent/wiki)
- **邮箱**: support@aisac.io
## 相关项目
- **AISAC Platform**: 基于 Web 的安全运营平台
- 仓库: `/Users/alvaromoralesmoreno/Desarrollo/aisac-39`
- Supabase URL: `https://hsxtlxeqzmcggxwnxnol.supabase.co`
**用 ❤️ 为安全社区构建**
标签：Agent, AISAC, AMSI绕过, DevSecOps, EVTX分析, Go语言, HTTP/HTTPS抓包, Incident Response, Log Forwarding, Remote Management, Security Agent, SOAR, 上游代理, 威胁检测, 安全事件响应, 安全运营, 态势感知, 扫描框架, 日志审计, 日志收集, 程序破解, 端点安全, 网络安全, 自动化响应, 补丁管理, 请求拦截, 资产监控, 运维工具, 隐私保护