Skillppx logo

Lightweight Host Intrusion Detection and Log Analysis System (Mini-HIDS)

基于AI的Linux主机实时日志监控与攻击检测，支持自动封禁IP。

已扫描
适合谁
运维工程师、AI安全自动化开发者
不适合谁
需要跨主机联动的大型企业安全团队、依赖内核级防护或高精度检测的高级安全需求者
国内可用性
需网络配置。可能需要网络配置或第三方服务可访问。
安装难度
中等（★★☆）。基于终端操作、依赖、API Key 和本地环境要求的初步判断。

安装与下载

openclaw skills install @netkr/mini-hids
下载官方 ZIP

Skill 说明

命令、参数、文件名以原文为准

Mini-HIDS

通过你的代理安装

使用 Mini-HIDS 最简单的方式是将此 GitHub 仓库链接提供给你的代理工具：

https://github.com/netkr/mini-hids

然后告诉代理：

把这个项目包装成一个技能给我。

代理可以克隆仓库，读取包含的项目地图，打包 MCP 服务器和运行时文件，并将 Mini-HIDS 作为可由代理调用的本地安全技能暴露出来。

在几分钟内即可阻止小型 Linux 服务器上的暴力破解 IP 和可疑的 Web 负载，无需部署完整的 SIEM 或重型 EDR 堆栈。

![Mini-HIDS 流程图](images/mini-hids-flow.svg)

[中文文档](README_zh.md)

Mini-HIDS 是一个基于 Python 标准库构建的轻量级 Linux 主机入侵检测工具。它专注于三个在小型服务器上易于操作的功能：

  • 使用滑动时间窗口检测重复的 SSH 登录失败
  • 从访问日志中检测明显的 Web 攻击载荷
  • 扫描常见脚本文件中的可疑 Webshell 模式

Mini-HIDS 被设计为一种代理原生的安全工具。它暴露一个本地 MCP 服务器，使 AI 代理可以通过标准工具接口检查状态、读取警报、查询黑名单，并触发封禁或解封操作。

为何存在此项目

大多数开源安全工具首先面向人类操作员进行优化。Mini-HIDS 有意保持足够小，以便快速理解、轻松编写脚本，并嵌入到代理工作流中，而无需庞大的控制平面。

如果你希望：

  • 一个适用于 VPS 或小型 Linux 集群的单主机防御工具
  • 通过 MCP 提供的代理原生接口实现 AI 驱动的安全运维
  • 简单、可检查的检测逻辑，而非不透明的处理管道

那么这个仓库适合你。

但如果你需要：

  • 跨主机关联或集中式 SOC 工作流
  • 内核遥测、eBPF 或终端预防功能
  • 高精度检测工程且要求极低误报率

则此仓库不适合。

架构

  • mini_hids.py：长期运行的守护进程，实时跟踪日志、监控攻击窗口、封禁 IP 并重新扫描 Web 根目录
  • hids_core.py：用于 MCP 和代理集成的控制平面 API
  • hids_common.py：共享配置加载、SQLite 辅助函数、IP 验证及防火墙后端
  • mcp_server.py：标准输入输出的 MCP 适配器，将 Mini-HIDS 的操作暴露为代理可调用的工具
  • config.json：由守护进程和 MCP 服务器共同加载的运行时配置文件
  • llms.txt：面向大语言模型的项目地图，用于 AI 搜索与代码助手

快速开始

在代理将项目打包为技能后，修改 config.json 以适应目标服务器，并启动守护进程：

sudo python3 mini_hids.py

与 AI 代理配合使用

Mini-HIDS 自带本地 MCP 服务器。像 Cursor、Claude Desktop 这类支持 MCP 的客户端可以直接调用该项目。

运行 MCP 服务器：

python3 mcp_server.py

示例客户端配置：

{
  "mcpServers": {
    "mini-hids": {
      "command": "python3",
      "args": ["/absolute/path/to/mini-hids/mcp_server.py"]
    }
  }
}

一个可直接复制的示例也包含在 [examples/claude_desktop_mcp.json](examples/claude_desktop_mcp.json) 中。

可用的 MCP 工具：

  • mini_hids_status
  • mini_hids_get_alerts
  • mini_hids_get_blacklist
  • mini_hids_ban_ip
  • mini_hids_unban_ip
  • mini_hids_scan_webshell

这是实际部署模型。Mini-HIDS 需要本地日志访问权限和防火墙权限，因此本地或服务器端的 MCP 集成是正确做法。

MCP 工具输出

所有 MCP 工具返回结构化 JSON。示例：

{
  "success": true,
  "data": {
    "is_running": true,
    "pid": 12345,
    "firewall_backend": "iptables"
  }
}

要求

  • Python 3.6+
  • Linux
  • 根权限（用于防火墙操作和受保护日志访问）
  • 以下任一支持的防火墙后端：

- iptables

- nft

- fail2ban-client

配置

请编辑 config.json，不要修改 Python 文件。

{
  "LOG_PATHS": {
    "auth": ["/var/log/auth.log", "/var/log/secure"],
    "web": ["/var/log/nginx/access.log", "/var/log/apache2/access.log"],
    "mysql": ["/var/log/mysql/mysql.log", "/var/log/mysql/error.log"]
  },
  "BAN_TIME": 3600,
  "TRUSTED_IPS": ["127.0.0.1", "192.168.1.1"],
  "WEB_ROOT": ["/var/www/html", "/var/www"],
  "BLACKLIST_DB": "blacklist.db",
  "ALERT_LOG": "hids_alert.log",
  "PID_FILE": "mini_hids.pid",
  "FIREWALL_BACKEND": "",
  "MAX_FAILURES": 5,
  "WINDOW_SECONDS": 300,
  "CHECK_INTERVAL": 1,
  "WEBSHELL_SCAN_INTERVAL": 3600
}

说明：

  • BLACKLIST_DB、ALERT_LOG 和 PID_FILE 可以是绝对路径。如果是相对路径，则会在项目目录中创建。
  • FIREWALL_BACKEND 可留空以自动检测，也可设置为 iptables、nftables/nft 或 fail2ban。
  • CHECK_INTERVAL 控制守护进程检查过期封禁的频率。
  • WEBSHELL_SCAN_INTERVAL 控制守护进程重新扫描 Web 根目录的频率。
  • TRUSTED_IPS 中的 IP 不会被守护进程或 MCP 工具封禁。

安全注意事项

  • 若需防火墙强制执行或访问特权日志，请以 root 用户运行守护进程。
  • 仔细审查 TRUSTED_IPS，避免误锁自身。
  • Web 攻击和 Webshell 检测基于启发式规则，应将警报视为信号而非最终判定。
  • MCP 客户端应被视为高权限本地集成，因其可触发封禁与解封操作。

限制

  • 检测基于正则表达式，且设计上保持简单。
  • 当前尚未包含自动化测试或服务打包方案。
  • nftables 支持使用专用的 mini_hids 表和启用了超时的集合，因此在生产环境中使用前仍需审查现有防火墙策略。

v1.2 版本发布说明

  • 从 config.json 统一加载运行时配置，并支持默认值合并
  • 添加共享核心模块，用于配置、防火墙、IP 验证及黑名单持久化
  • 增加基于 SQLite 的黑名单持久化功能，支持自动恢复和过期条目清理
  • 优化封禁/解封的幂等性，降低重复防火墙规则的风险
  • 修复防火墙后端检测问题，包括对 nftables 的正确支持
  • 改进守护进程调度机制，使封禁到期检查以短间隔执行
  • 增加基于文件修改时间的增量 Webshell 扫描功能
  • 提升日志尾部追踪的鲁棒性，支持日志轮转处理
  • 统一运行时文件路径，包括 blacklist.db、hids_alert.log 和 mini_hids.pid

v1.3 版本更新说明

  • 重构为原生代理架构，移除人工命令行界面
  • 创建专用控制平面 API 模块（hids_core.py），用于 MCP 与代理集成
  • 移除 hids_cli.py 及其基于 argparse 的命令行接口
  • 更新 MCP 服务器，改为从控制平面 API 模块导入
  • 简化项目结构，消除双模式（CLI + MCP）设计
  • 更新文档，反映代理原生定位及 MCP 优先的工作流

v1.4 版本更新说明

  • 将通用封禁/解封逻辑提取至 hids_common.py，消除代码重复
  • 添加 validate_ban_request()、execute_ban()、execute_unban() 共享函数
  • 增加结构化告警解析功能，通过 parse_alert_line() 提供代理友好的输出
  • 添加 mini_hids_scan_webshell MCP 工具，支持按需进行 Webshell 扫描
  • 将 WEBSHELL_PATTERNS 提取至共享模块，避免重复定义
  • 增加单元测试（test_hids.py），覆盖核心功能
  • 添加 systemd 服务文件（mini-hids.service），便于生产环境部署

v1.5 版本更新说明

  • 增加可配置的 FIREWALL_BACKEND 选择，支持自动检测并提供回退机制
  • 改进访问日志客户端 IP 提取逻辑，降低 Web 攻击检测的严格性
  • 在守护进程与 MCP 控制平面代码之间共享 Webshell 扫描实现
  • 添加 MCP 参数显式验证，提升代理端错误提示清晰度
  • 加强守护进程 PID 文件创建逻辑，防止旧文件残留及并发启动问题
  • 扩展单元测试，覆盖访问日志解析、Webshell 扫描、守护进程检测及 MCP 验证等场景
N
@netkr

已收录 1 个 Skill

相关推荐