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
   # Optional: install GUI dependencies if you want the desktop interface
   # pip install -r requirements-gui.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 src/main/python/main.py

The server runs headless by default if no display/GUI dependencies are available. If customtkinter is installed and HEADLESS is not set, the GUI starts automatically.

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
HEADLESS	0	Set to 1 to disable the GUI
CLEAR_DB_ON_START	1	Set to 0 to keep existing Neo4j nodes on startup

Running tests

python src/main/python/test.py

For pytest (if installed):

pytest

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.