lightweight-host-intrusion-detection-and-log-analysis-system

原始内容

# Mini-HIDS

## Install With Your Agent

The simplest way to use Mini-HIDS is to give this GitHub repository link to your agent tool:

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

Then tell the agent:

```text
Wrap this project as a skill for me.
```

The agent can clone the repository, read the included project map, package the MCP server and runtime files, and expose Mini-HIDS as an agent-callable local security skill.

Stop brute-force IPs and suspicious web payloads on a small Linux server in minutes, without deploying a full SIEM or heavyweight EDR stack.

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

[中文文档](README_zh.md)

Mini-HIDS is a lightweight Linux host intrusion detection tool built with the Python standard library. It focuses on three things that are easy to operationalize on small servers:

- Detect repeated SSH login failures with a sliding time window
- Detect obvious web attack payloads from access logs
- Scan common script files for suspicious webshell patterns

Mini-HIDS is designed as an **agent-native** security tool. It exposes a local MCP server so AI agents can inspect status, read alerts, query the blacklist, and trigger ban or unban actions through a standard tool interface.

## Why This Exists

Most open-source security tools are optimized for human operators first. Mini-HIDS is intentionally small enough to understand quickly, script easily, and embed into agent workflows without a large control plane.

This repository is a good fit if you want:

- A single-host defensive tool for VPS or small Linux fleets
- An agent-native interface via MCP for AI-driven security operations
- Simple, inspectable detection logic instead of opaque pipelines

This repository is not a good fit if you need:

- Cross-host correlation or centralized SOC workflows
- Kernel telemetry, eBPF, or endpoint prevention
- High-fidelity detection engineering with low false positives

## Architecture

- `mini_hids.py`: long-running daemon that tails logs, tracks attack windows, bans IPs, and rescans web roots
- `hids_core.py`: control-plane API for MCP and agent integration
- `hids_common.py`: shared config loading, SQLite helpers, IP validation, and firewall backends
- `mcp_server.py`: stdio MCP adapter that exposes Mini-HIDS actions as agent-callable tools
- `config.json`: runtime configuration loaded by both the daemon and the MCP server
- `llms.txt`: LLM-oriented project map for AI search and coding assistants

## Quick Start

After your agent has packaged the project as a skill, adjust `config.json` for the target server and start the daemon:

```bash
sudo python3 mini_hids.py
```

## Use With AI Agents

Mini-HIDS ships with a local MCP server. Tools like Cursor, Claude Desktop, and other MCP-compatible clients can call the project directly.

Run the MCP server:

```bash
python3 mcp_server.py
```

Example client config:

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

A ready-to-copy sample is also included at [`examples/claude_desktop_mcp.json`](examples/claude_desktop_mcp.json).

Available MCP tools:

- `mini_hids_status`
- `mini_hids_get_alerts`
- `mini_hids_get_blacklist`
- `mini_hids_ban_ip`
- `mini_hids_unban_ip`
- `mini_hids_scan_webshell`

This is the practical deployment model. Mini-HIDS needs local log access and firewall privileges, so local or server-side MCP integration is the correct approach.

## MCP Tool Output

All MCP tools return structured JSON. Example:

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

## Requirements

- Python 3.6+
- Linux
- Root privileges for firewall operations and protected log access
- One supported firewall backend:
  - `iptables`
  - `nft`
  - `fail2ban-client`

## Configuration

Edit `config.json` instead of modifying the Python files.

```json
{
  "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
}
```

Notes:

- `BLACKLIST_DB`, `ALERT_LOG`, and `PID_FILE` can be absolute paths. If they are relative, they are created in the project directory.
- `FIREWALL_BACKEND` can be empty for auto-detection, or set to `iptables`, `nftables`/`nft`, or `fail2ban`.
- `CHECK_INTERVAL` controls how often the daemon checks for expired bans.
- `WEBSHELL_SCAN_INTERVAL` controls how often the daemon rescans web roots.
- `TRUSTED_IPS` are never banned by the daemon or MCP tools.

## Security Notes

- Run the daemon as root if you need firewall enforcement or access to privileged logs.
- Review `TRUSTED_IPS` carefully to avoid locking yourself out.
- Web attack and webshell detection are heuristic. Treat alerts as signals, not final verdicts.
- MCP clients should be treated as privileged local integrations, since they can trigger ban and unban operations.

## Limitations

- Detection is regex-based and intentionally simple.
- The project does not yet ship with automated tests or service packaging.
- `nftables` support uses a dedicated `mini_hids` table and timeout-enabled sets, so existing firewall policies should still be reviewed before production use.


## v1.2 Release Notes

- Unified runtime configuration loading from config.json with default merging
- Added shared core module for config, firewall, IP validation, and blacklist persistence
- Added SQLite-backed blacklist persistence with automatic recovery and expired-entry cleanup
- Improved ban/unban idempotency and reduced risk of duplicate firewall rules
- Fixed firewall backend detection, including proper nftables support
- Improved daemon scheduling so ban expiry is checked on a short interval
- Added incremental webshell scanning based on file modification time
- Improved log tailing robustness with log rotation handling
- Normalized runtime file paths for blacklist.db, hids_alert.log, and mini_hids.pid

## v1.3 Release Notes

- Refactored to agent-native architecture, removing human CLI interface
- Created dedicated control-plane API module (`hids_core.py`) for MCP and agent integration
- Removed `hids_cli.py` and its argparse-based command-line interface
- Updated MCP server to import from control-plane API module
- Simplified project structure by eliminating dual-mode (CLI + MCP) design
- Updated documentation to reflect agent-native positioning and MCP-first workflow

## v1.4 Release Notes

- Extracted common ban/unban logic to `hids_common.py`, eliminating code duplication
- Added `validate_ban_request()`, `execute_ban()`, `execute_unban()` shared functions
- Added structured alert parsing with `parse_alert_line()` for agent-friendly output
- Added `mini_hids_scan_webshell` MCP tool for on-demand webshell scanning
- Extracted `WEBSHELL_PATTERNS` to shared module, removing duplicate definitions
- Added unit tests (`test_hids.py`) covering core functionality
- Added systemd service file (`mini-hids.service`) for production deployment

## v1.5 Release Notes

- Added configurable `FIREWALL_BACKEND` selection with auto-detection fallback
- Improved access log client IP extraction for less rigid web attack detection
- Shared webshell scan implementation between daemon and MCP control-plane code
- Added explicit MCP argument validation for clearer agent-facing errors
- Hardened daemon PID file creation against stale files and concurrent starts
- Expanded unit tests for access log parsing, webshell scanning, daemon detection, and MCP validation

Mini-HIDS

Install With Your Agent

The simplest way to use Mini-HIDS is to give this GitHub repository link to your agent tool:

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

Then tell the agent:

Wrap this project as a skill for me.

The agent can clone the repository, read the included project map, package the MCP server and runtime files, and expose Mini-HIDS as an agent-callable local security skill.

Stop brute-force IPs and suspicious web payloads on a small Linux server in minutes, without deploying a full SIEM or heavyweight EDR stack.

Mini-HIDS flow

中文文档

Mini-HIDS is a lightweight Linux host intrusion detection tool built with the Python standard library. It focuses on three things that are easy to operationalize on small servers:

Detect repeated SSH login failures with a sliding time window
Detect obvious web attack payloads from access logs
Scan common script files for suspicious webshell patterns

Mini-HIDS is designed as an agent-native security tool. It exposes a local MCP server so AI agents can inspect status, read alerts, query the blacklist, and trigger ban or unban actions through a standard tool interface.

Why This Exists

Most open-source security tools are optimized for human operators first. Mini-HIDS is intentionally small enough to understand quickly, script easily, and embed into agent workflows without a large control plane.

This repository is a good fit if you want:

A single-host defensive tool for VPS or small Linux fleets
An agent-native interface via MCP for AI-driven security operations
Simple, inspectable detection logic instead of opaque pipelines

This repository is not a good fit if you need:

Cross-host correlation or centralized SOC workflows
Kernel telemetry, eBPF, or endpoint prevention
High-fidelity detection engineering with low false positives

Architecture

mini_hids.py: long-running daemon that tails logs, tracks attack windows, bans IPs, and rescans web roots
hids_core.py: control-plane API for MCP and agent integration
hids_common.py: shared config loading, SQLite helpers, IP validation, and firewall backends
mcp_server.py: stdio MCP adapter that exposes Mini-HIDS actions as agent-callable tools
config.json: runtime configuration loaded by both the daemon and the MCP server
llms.txt: LLM-oriented project map for AI search and coding assistants

Quick Start

After your agent has packaged the project as a skill, adjust config.json for the target server and start the daemon:

sudo python3 mini_hids.py

Use With AI Agents

Mini-HIDS ships with a local MCP server. Tools like Cursor, Claude Desktop, and other MCP-compatible clients can call the project directly.

Run the MCP server:

python3 mcp_server.py

Example client config:

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

A ready-to-copy sample is also included at examples/claude_desktop_mcp.json.

Available MCP tools:

mini_hids_status
mini_hids_get_alerts
mini_hids_get_blacklist
mini_hids_ban_ip
mini_hids_unban_ip
mini_hids_scan_webshell

This is the practical deployment model. Mini-HIDS needs local log access and firewall privileges, so local or server-side MCP integration is the correct approach.

MCP Tool Output

All MCP tools return structured JSON. Example:

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

Requirements

Python 3.6+
Linux
Root privileges for firewall operations and protected log access
One supported firewall backend:
- iptables
- nft
- fail2ban-client

Configuration

Edit config.json instead of modifying the Python files.

{
  "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
}

Notes:

BLACKLIST_DB, ALERT_LOG, and PID_FILE can be absolute paths. If they are relative, they are created in the project directory.
FIREWALL_BACKEND can be empty for auto-detection, or set to iptables, nftables/nft, or fail2ban.
CHECK_INTERVAL controls how often the daemon checks for expired bans.
WEBSHELL_SCAN_INTERVAL controls how often the daemon rescans web roots.
TRUSTED_IPS are never banned by the daemon or MCP tools.

Security Notes

Run the daemon as root if you need firewall enforcement or access to privileged logs.
Review TRUSTED_IPS carefully to avoid locking yourself out.
Web attack and webshell detection are heuristic. Treat alerts as signals, not final verdicts.
MCP clients should be treated as privileged local integrations, since they can trigger ban and unban operations.

Limitations

Detection is regex-based and intentionally simple.
The project does not yet ship with automated tests or service packaging.
nftables support uses a dedicated mini_hids table and timeout-enabled sets, so existing firewall policies should still be reviewed before production use.

v1.2 Release Notes

Unified runtime configuration loading from config.json with default merging
Added shared core module for config, firewall, IP validation, and blacklist persistence
Added SQLite-backed blacklist persistence with automatic recovery and expired-entry cleanup
Improved ban/unban idempotency and reduced risk of duplicate firewall rules
Fixed firewall backend detection, including proper nftables support
Improved daemon scheduling so ban expiry is checked on a short interval
Added incremental webshell scanning based on file modification time
Improved log tailing robustness with log rotation handling
Normalized runtime file paths for blacklist.db, hids_alert.log, and mini_hids.pid

v1.3 Release Notes

Refactored to agent-native architecture, removing human CLI interface
Created dedicated control-plane API module (hids_core.py) for MCP and agent integration
Removed hids_cli.py and its argparse-based command-line interface
Updated MCP server to import from control-plane API module
Simplified project structure by eliminating dual-mode (CLI + MCP) design
Updated documentation to reflect agent-native positioning and MCP-first workflow

v1.4 Release Notes

Extracted common ban/unban logic to hids_common.py, eliminating code duplication
Added validate_ban_request(), execute_ban(), execute_unban() shared functions
Added structured alert parsing with parse_alert_line() for agent-friendly output
Added mini_hids_scan_webshell MCP tool for on-demand webshell scanning
Extracted WEBSHELL_PATTERNS to shared module, removing duplicate definitions
Added unit tests (test_hids.py) covering core functionality
Added systemd service file (mini-hids.service) for production deployment

v1.5 Release Notes

Added configurable FIREWALL_BACKEND selection with auto-detection fallback
Improved access log client IP extraction for less rigid web attack detection
Shared webshell scan implementation between daemon and MCP control-plane code
Added explicit MCP argument validation for clearer agent-facing errors
Hardened daemon PID file creation against stale files and concurrent starts
Expanded unit tests for access log parsing, webshell scanning, daemon detection, and MCP validation