Logvault

Logvault is a simple, tag-based syslog processor that listens for alarms, stores them in Redis, and provides a real-time web interface for viewing and managing them.

It's designed to be a lightweight solution for scenarios where you need to track state from syslog messages (e.g., a device is offline/online) and have a simple visual dashboard for the current status.

Features

• Syslog Listener: Receives syslog messages (RFC5424 format) over UDP.
• Tag-Based Processing: Creates or deletes alarms based on a "tag" (the syslog app_name).
  • ALARM: Creates/updates an alarm.
  • CLEAR: Deletes an alarm.
• Redis Backend: Uses Redis to store the current state of active alarms.
• Real-time Web UI: A clean web interface that automatically refreshes to show the current list of active alarms.
• HTTPS Support: The web server can serve traffic over HTTPS if a TLS certificate and key are provided.
• Web UI Authentication: Secure your web interface with one or more configurable username/secret pairs, per-user roles, and bcrypt password-hash support.
• Web UI IP Allowlist: Restrict Web UI and session-based API access to specific source IPs or CIDR ranges.
• Logout Functionality: Allows users to securely log out of the web UI.
• Manual Deletion: Allows manual deletion of alarms directly from the web UI.
• Configuration: Easily configurable via a config.yaml file.

Getting Started

Follow these instructions to get Logvault up and running.

Prerequisites

You need to have the following software installed:

• Go: Version 1.18 or higher (for building from source).
• Docker and Docker Compose: For running the application in containers.

Installation and Running

Logvault can be run in a Docker container or built from source.

1. Using Docker Compose (Recommended)

   This is the easiest way to get started. It automatically builds the Go application and runs it alongside a Redis container.

   1. Clone the repository:

      git clone https://github.com/sfreet/logvault.git
      cd logvault

   2. Configure the application: Copy config.yaml.example to config.yaml and edit it to suit your needs. You must set Web UI credentials with either web.users or the legacy username/secret pair, and set a bearer_token for the API. Prefer secret_hash over plaintext secret. If you want to limit administrator access, set web.allowed_ips to the allowed public source IPs or CIDRs. If you want to limit syslog senders, set syslog.allowed_ips.

      cp config.yaml.example config.yaml
      # Now edit config.yaml

   3. Build and run with Docker Compose:

      docker-compose up --build

      The application will be available at http://localhost:8080. In the default Compose setup, Logvault and Redis communicate over the default Docker bridge network. The Logvault container publishes 8080/tcp for the Web UI and 514/udp for syslog reception, and it reaches Redis through the service name redis:6379. In config.yaml.example, the Redis address is therefore set to redis:6379 for the Compose case. If you run Logvault outside Docker, change that value to the appropriate Redis host such as 127.0.0.1:6379.

2. Building and Running Docker Image Manually

   If you want to build and run the Docker image yourself:

   1. Clone the repository and configure as above.

   2. Build the Docker image:

      make docker # This runs `docker build -t logvault .`

   3. Run the Docker container:

      docker network create logvault-net
      docker run -d --name logvault-redis --network logvault-net redis:7-alpine
      docker run -d --name logvault --network logvault-net -e REDIS_ADDRESS=logvault-redis:6379 -p 8080:8080 -p 514:514/udp logvault

3. Building from Source

   If you prefer to build the application manually:

   1. Install Redis: Make sure you have a running Redis instance.

      # Using Docker
      docker run -d --name logvault-redis -p 6379:6379 redis

   2. Clone the repository and configure as above.

   3. Build and run the application:

      go mod tidy
      make build # This compiles the Go application into a binary named 'logvault'
      ./logvault

      You may need to use sudo if you are listening on a privileged port like 514.

   Note: You can use make help to see all available Makefile commands.

Usage

Sending Syslog Alarms

You can use the standard logger utility to send syslog messages to Logvault.

If you are using the provided Docker Compose setup, send test syslog traffic to host UDP port 2514, which is published to the container's internal syslog port 514/udp.

• To create an alarm: Use the -t ALARM tag. The message format should be "<key> <message>". The <key> is typically an IP address or hostname.

  logger -n 127.0.0.1 -P 2514 -d -t ALARM "192.168.1.100 System is overheating"

• To clear an alarm: Use the -t CLEAR tag. The message should contain the <key> of the alarm to be cleared.

  logger -n 127.0.0.1 -P 2514 -d -t CLEAR "192.168.1.100"

• To send an INSIGHTS event: Use the -t INSIGHTS tag. The payload must contain exactly 10 backtick-delimited fields in this order: Score, DetectTime, DetectType, DetectSubType, FileName, RuleName, IP, AuthID, AuthName, AuthDeptName. DetectTime must be a Unix timestamp in milliseconds.

  logger -n 127.0.0.1 -P 2514 -d -t INSIGHTS '90`1706236200000`Malware`VirusX`/usr/local/bin/mal.exe`Blocked_VirusX_Signature`192.168.1.100`admin`Administrator`IT_Security'

After sending a test event, you can verify the stored data through the API:

curl -k -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" https://127.0.0.1:8080/api/alarms

Accessing the Web UI

Once the application is running, open your web browser and navigate to the appropriate address.

• HTTP: By default, the server runs on HTTP. http://localhost:8080

• HTTPS: If you have configured a cert_file and key_file in your config.yaml, the server will run on HTTPS. https://localhost:8080

You will be prompted to enter a username and secret configured in config.yaml to access the dashboard. The UI will display a list of all active alarms and auto-refreshes every 5 seconds. Users with the admin role can delete alarms. Users with the readonly role can view alarms but cannot delete them.

If you want to restrict administrator access by source IP, configure web.allowed_ips with individual IP addresses or CIDR ranges. When this list is set, only matching source IPs can access the Web UI and session-authenticated API endpoints.

If you want to restrict syslog senders by source IP, configure syslog.allowed_ips with individual IP addresses or CIDR ranges. When this list is empty or omitted, all syslog senders are allowed.

Example:

syslog:
  host: "0.0.0.0"
  port: 514
  protocol: "udp"
  allowed_ips:
    - "203.0.113.10"
    - "198.51.100.0/24"

web:
  port: 8080
  users:
    - username: "admin"
      secret_hash: "GENERATE_WITH_SCRIPT"
      role: "admin"
    - username: "ops"
      secret_hash: "GENERATE_WITH_SCRIPT"
      role: "readonly"
  cert_file: "server.crt"
  key_file: "server.key"
  allowed_ips:
    - "203.0.113.24"
    - "198.51.100.0/24"

The legacy single-user web.username and web.secret settings are still accepted for backward compatibility and behave as an admin account. New deployments should prefer web.users, and new credentials should prefer secret_hash over plaintext secret.

You can generate a bcrypt hash with a command such as:

make build-hash-tool
./scripts/generate_password_hash.sh --password 'your_secret_password'

The offline package created by make package includes the same script and a prebuilt helper binary, so no Go toolchain is required on the target system.

make package also creates logvault-dist.tar.gz, which contains both logvault.tar.gz and install-logvault.sh.

For on-prem installation, unpack the distribution bundle and run:

tar -xzf logvault-dist.tar.gz
cd logvault-dist
./install-logvault.sh logvault.tar.gz

After installation, review config.yaml and, if you need different published ports, adjust docker-compose.yaml before loading images and starting the stack. In rootless Docker environments, avoid host ports below 1024.

By default, the installer deploys to $HOME/opt/logvault. You can override that by setting BASE_DIR or APP_DIR_NAME before running the script.

If config.yaml does not already exist on the target system, the installer creates it from config.yaml.example.

The installer also creates .env from .env.example and prompts for the host ports used by Docker Compose. By default it suggests Web UI port 6443 and syslog UDP port 2514, and writes those values to .env without requiring direct edits to docker-compose.yaml.

On first install, if the generated config.yaml still contains the default placeholders, the installer prompts for initial passwords for the admin and ops accounts, writes bcrypt hashes into config.yaml, generates an API bearer token automatically, and can initialize the external_api block without requiring manual YAML edits. For non-interactive installs, you can provide LOGVAULT_ADMIN_PASSWORD, LOGVAULT_OPS_PASSWORD, LOGVAULT_EXTERNAL_API_ENABLED, and optionally LOGVAULT_API_BEARER_TOKEN, LOGVAULT_EXTERNAL_API_URL, LOGVAULT_EXTERNAL_API_METHOD, LOGVAULT_EXTERNAL_API_BEARER_TOKEN, and LOGVAULT_EXTERNAL_API_TRIGGER_TAGS.

The installer also generates a TLS certificate for the Web UI. During installation it asks for the IPv4 address to place in the certificate SAN, or you can supply it non-interactively with TLS_CERT_IP.

You can also add or update a Web UI user directly in config.yaml:

make build-config-tool
./scripts/configure_web_user.sh --config ./config.yaml --username admin --password 'your_secret_password' --role admin

This helper rewrites config.yaml, updates or appends the matching web.users entry, stores only secret_hash, and clears plaintext secret for that user.

In the provided Docker Compose configuration, the containers use the default Docker bridge network. Because the Web UI runs behind Docker port publishing in this setup, web.allowed_ips may see the Docker bridge or host-side source address rather than the original browser client IP. If you need a strict public-client IP allowlist for the Web UI, add a reverse proxy that forwards the real client IP and update the application to trust that proxy, or run outside Docker networking.

REST API

Logvault provides two sets of REST API endpoints for accessing data.

Bearer Token Authenticated Endpoint

This endpoint is intended for external services and programmatic access. It is secured with a Bearer token.

• Endpoint: GET /api/data
• Authentication: Bearer Token
  • Set a bearer_token in your config.yaml under the api section.
  • Include it in the Authorization header of your request.
• Description: Retrieves all raw key-value pairs currently stored in Redis, including non-alarm data.

Example Request:

curl -H "Authorization: Bearer your_bearer_token" http://localhost:8080/api/data

Web UI / Session Authenticated Endpoints

These endpoints are used by the web UI and are protected by the same session cookie as the web interface. They are primarily for managing alarms.

• Endpoint: GET /api/alarms

  • Description: Retrieves all active alarms. The response is a JSON object containing key-value pairs for all entries with the alarm: prefix.

• Endpoint: DELETE /api/alarms/{key}

  • Description: Deletes a specific alarm by its key. For example, a request to /api/alarms/192.168.1.100 will delete the alarm:192.168.1.100 key from Redis.

• Endpoint: DELETE /api/alarms or DELETE /api/alarms/

  • Description: Deletes all alarms from Redis. This is used by the "Delete All" button in the web UI.

License

This project is licensed under the MIT License. See the LICENSE file for details.