文档

快速开始

安装 Kunsec 最快的方式是使用一键安装脚本：

curl -fsSL https://kunsec.ciyra.com/download/install.sh | sudo bash

安装过程中，脚本会交互式询问以下配置：

  • 审计服务器地址与端口
  • SMTP 邮箱服务器配置
  • AI API Key 与模型
  • 文件扫描根路径与进程扫描间隔

安装完成后，服务会自动启动并设置为开机自启。

配置文件说明

配置文件路径为 /etc/sysmonitord/config.yaml。以下是各主要配置区块的说明：

Server

server:
  host: "127.0.0.1"
  port: 8080

控制 Kunsec 本地 HTTP 服务监听地址与端口。

Log

log:
  level: "info"   # 可选: debug, info, warn, error

日志输出级别，生产环境建议使用 info。

Scanner

scanner:
  hash:
    algorithm: "xxhash64"
  file:
    include_paths:
      - /
    exclude_paths:
      - /proc
      - /sys
      - /dev
    fast_hash: true
    fast_hash_size: 100MB
    fast_hash_chunk: 2MB
  process:
    interval: 300

扫描引擎配置：包含哈希算法、文件扫描路径、进程扫描间隔等。

Notification

notification:
  interval: 5
  email:
    enabled: true
    recipients:
      - admin@example.com
    smtp:
      server: smtp.example.com
      port: 465
      username: sysmonitord@example.com
      password: "${SYSMONITORD_SMTP_PASSWORD}"

告警邮件配置。密码建议使用环境变量注入。

AI

ai:
  enabled: true
  api_url: "https://api.openai.com/v1/chat/completions"
  api_key: "${SYSMONITORD_AI_API_KEY}"
  model: "gpt-4o-mini"
  timeout: 120

AI 分析配置。API Key 强烈建议通过环境变量 SYSMONITORD_AI_API_KEY 注入。

Audit

audit:
  enabled: true
  server: "192.168.1.100"
  port: 9000
  buffer_size: 1000

审计服务端配置，所有监控日志将推送至此地址。

Script

script:
  enabled: true
  dir: "/etc/sysmonitord/scripts"
  timeout_ms: 5000

JavaScript 脚本钩子配置，用于自定义事件响应逻辑。

命令行使用

Kunsec 使用 Cobra CLI 框架，提供以下子命令：

start

sysmonitord start

启动监控守护进程。首次启动时会自动执行全量扫描并建立白名单。

status

sysmonitord status

查看当前运行状态，包含白名单统计、可疑事件数量、审计推送状态等。

safe

sysmonitord safe

交互式安全确认界面，将可疑文件或进程移至白名单。

ai

sysmonitord ai

手动触发 AI 分析，对当前可疑事件进行批量判断。

version

sysmonitord version

显示当前版本、构建时间与 Git Commit。

全局参数

sysmonitord -c /path/to/config.yaml start

使用 -c 指定自定义配置文件路径。默认会依次查找 ./config.yaml 和 /etc/sysmonitord/config.yaml。

扫描配置

扫描引擎是 Kunsec 的核心，负责建立基线白名单和持续监控。

文件扫描

首次启动时会对 include_paths 下的所有文件进行遍历并计算哈希。计算策略：

  • 小文件（≤ 100MB）：全量 xxhash64 哈希
  • 大文件（> 100MB）：分层抽样哈希（头尾各 1MB + 文件大小）

exclude_paths 支持 glob 模式，如 **/node_modules、/home/*/.cache。

进程扫描

每 interval 秒扫描一次系统中所有进程，对比白名单中的 进程名:可执行文件路径:哈希 三元组。

通知配置

Kunsec 支持邮件告警通知。当检测到可疑文件或进程时，会按照 interval（分钟）间隔发送汇总邮件。

为避免频繁告警，系统内置防抖动机制：同一事件在 30 秒内不会重复触发邮件。

审计推送配置

审计模块负责将所有事件实时推送至审计服务端。

  • 内存缓冲：优先写入内存队列，容量 10000 条
  • 磁盘缓冲：内存满时持久化到磁盘，保证数据不丢失
  • 批量推送：每 5 秒或达到 1000 条时触发推送
  • 断点续传：网络恢复后自动补齐未推送数据

故障排查

服务无法启动

journalctl -u sysmonitord -n 50 --no-pager

查看 systemd 日志，最常见的失败原因是配置文件格式错误或端口被占用。

AI 分析无响应

检查环境变量 SYSMONITORD_AI_API_KEY 是否已正确设置，以及 API 地址是否可达。

审计推送失败

检查审计服务器地址与端口配置，确认网络连通性。失败数据会自动缓冲到磁盘，不会丢失。

误报过多

调整 exclude_paths 排除高频变化目录，或使用 sysmonitord safe 将已知安全的文件/进程加入白名单。