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

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

### GitHub profile

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

It also exposes both a JSON CLI and a minimal 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 - A JSON-first CLI for automation and agent usage - Simple, inspectable detection logic instead of opaque pipelines - A local MCP tool server that IDE agents can call directly

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_cli.py: JSON-only control-plane CLI for operators and agents - 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 CLI - llms.txt: LLM-oriented project map for AI search and coding assistants

## Quick Start

  git clone https://github.com/netkr/mini-hids.git
  cd mini-hids
  

Adjust config.json, then start the daemon:

  sudo python3 mini_hids.py
  

Use the JSON CLI:

  python3 hids_cli.py --action status
  python3 hids_cli.py --action get_alerts --lines 20
  python3 hids_cli.py --action get_blacklist
  python3 hids_cli.py --action ban --ip 192.168.1.100 --reason "manual ban"
  python3 hids_cli.py --action unban --ip 192.168.1.100
  

## Use With AI Agents

Mini-HIDS now ships with a local MCP server. That means tools like Cursor, Claude Desktop, and other MCP-compatible clients can call the project directly instead of shelling out ad hoc.

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

This is the practical replacement for a fake "one-click deploy" button. Mini-HIDS needs local log access and firewall privileges, so local or server-side MCP integration is the correct deployment model.

## CLI Output

All CLI commands return 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",
    "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. - 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 the CLI.

## 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 - Added JSON CLI for status, alerts, blacklist inspection, manual ban, and unban

  git clone https://github.com/netkr/mini-hids.git
  cd mini-hids
  

Adjust config.json, then start the daemon:

  sudo python3 mini_hids.py
  

Use the JSON CLI:

  python3 hids_cli.py --action status
  python3 hids_cli.py --action get_alerts --lines 20
  python3 hids_cli.py --action get_blacklist
  python3 hids_cli.py --action ban --ip 192.168.1.100 --reason "manual ban"
  python3 hids_cli.py --action unban --ip 192.168.1.100
  

## Use With AI Agents

Mini-HIDS now ships with a local MCP server. That means tools like Cursor, Claude Desktop, and other MCP-compatible clients can call the project directly instead of shelling out ad hoc.

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

This is the practical replacement for a fake "one-click deploy" button. Mini-HIDS needs local log access and firewall privileges, so local or server-side MCP integration is the correct deployment model.

## CLI Output

All CLI commands return 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",
    "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. - 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 the CLI.

## 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 - Added JSON CLI for status, alerts, blacklist inspection, manual ban, and unban

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",
    "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. - 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 the CLI.

## 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 - Added JSON CLI for status, alerts, blacklist inspection, manual ban, and unban