SecureStorage-HIDS

Integrity monitoring HIDS with a Neo4j backend and a small SSL client-server protocol.

Requirements

• Python 3.9+
• Neo4j 5.x (local, Docker or Aura)
• pip and virtualenv (recommended)

Quick start

1. Clone the repository and create a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate  # Windows
   # source .venv/bin/activate  # Linux/Mac
   pip install -r requirements.txt

2. Configure environment variables. Copy .env.example to .env and fill in real values:

   cp .env.example .env        # Linux/Mac
   copy .env.example .env      # Windows

3. Make sure Neo4j is running and create the database user/password you configured in .env.

4. Run the server:

   python -m hids.server.main

   or, after installing the package:

   hids-server

Environment variables

Variable	Default	Description
DB_HOST	localhost	Neo4j host
DB_USER	neo4j	Neo4j username
DB_PASSWORD	-	Neo4j password (required)
TOKEN	-	Shared secret used for HMAC and client authentication (required)
SERVER_HOST	0.0.0.0	Server bind address (use 0.0.0.0 to accept remote connections)
SERVER_PORT	8080	Server port
RESOURCES_PATHS	src/main/resources	Semicolon-separated directories to monitor
CLEAR_DB_ON_START	1	Set to 0 to keep existing Neo4j nodes on startup

Additional optional variables are available in .env.example for token rotation, alerts, JWT, RBAC, hash algorithms, honeypots, HTTP REST API and signing.

Running tests

pytest

A standalone manual test harness is also available in the package:

python -m hids.tests.test

Docker

Build and run with Docker Compose:

cp .env.example .env
# Edit .env with real values
docker-compose up --build

The server service waits for Neo4j to be healthy before starting.

Notes

• The first time the server starts it generates self-signed SSL certificates under src/main/ssl/. In production replace these with certificates from a trusted CA.
• The server deletes and reloads the Neo4j graph on each start unless CLEAR_DB_ON_START=0 is set.
• The client protocol now uses JSON line-delimited messages and requires the TOKEN secret to authenticate.

Detection capabilities

The HIDS includes the following detection modules:

• File integrity monitoring — hash-based change detection with baseline snapshots.
• File permission monitoring — tracks mode, uid and gid changes in baseline comparisons.
• Anomaly detection — statistical analysis of file access patterns.
• Honeypots — decoy files that trigger alerts when touched.
• Process monitoring — detects suspicious processes and Living-off-the-Land (LotL) binaries.
• Reverse shell detection — flags connections to known suspicious ports.
• Privilege escalation detection — monitors setuid binaries, sudoers changes and kernel module loading.
• Container monitoring — tracks processes running inside Docker containers.
• Log analysis — parses system logs and systemd journal entries for suspicious activity.
• Rootkit detection — scans for hidden files, kernel modules and LKM rootkits.
• Cron job monitoring — detects persistence via crontab modifications.
• SSH config monitoring — alerts on insecure SSH configuration changes.
• Firewall monitoring — tracks iptables/nftables rule changes.
• USB device monitoring — logs removable device connections.
• Service monitoring — detects systemd service file tampering.
• User monitor — tracks user account creation and modification.
• YARA scanner — scans files against YARA rules.
• Kernel module monitor — alerts on module load/unload events.
• DNS monitor — detects suspicious DNS resolutions.
• Network monitor — tracks outbound connections.
• Persistent connections — flags long-lived suspicious connections.
• Process hollowing — detects process memory injection.
• Correlation engine — correlates events across detectors.
• GeoIP enrichment — adds geographic context to network events.

Alerting

Alerts can be delivered through multiple channels:

• Email — SMTP-based alerts with digest support.
• Webhooks — Slack, Microsoft Teams and Discord formats.
• Audit log — tamper-evident audit trail.

REST API

The server exposes an optional HTTP REST API (enabled with HTTP_PORT) with:

• Health, metrics (Prometheus), ping endpoints
• File, log and report listing with optional pagination (?page=2&page_size=50)
• Baseline save/compare, anomalies, compliance, events and HA status
• Enrollment token creation and agent enrollment
• Command execution via POST /command
• OpenAPI spec at /openapi.json and a dashboard at /dashboard

Operational features

• Key rotation — automatic rotation of signing and auth keys.
• Baseline versioning — keep multiple baseline snapshots with timestamps.
• Health watchdog — auto-restart on health check failures.
• ECS export — export events in Elastic Common Schema format.
• Log rotation — automatic rotation of log files.
• High availability — multi-node HA with heartbeat and failover.
• RBAC — role-based access control for commands and REST endpoints.
• mTLS — mutual TLS with certificate pinning.
• Rate limiting — per-IP rate limiting and ban lists.