Configuration¶

Reference for rimae/scan configuration, service management, logging, and backup/restore.

Configuration File¶

rimae/scan reads /etc/rimae-scan/rimae-scan.conf at startup -- a standard dotenv file loaded by internal/config.

Ownership: rimae-scan:root, mode 600.

Core Settings¶

Variable	Default	Description
`DATABASE_URL`	`postgres://rimae-scan:rimae-scan@localhost:5432/rimae-scan`	PostgreSQL connection string (pgx/v5 standard format).
`REDIS_URL`	`redis://localhost:6379/0`	Redis connection URL. Used for rate limiting and caching.
`SECRET_KEY`	(none, required)	64-character hex string for JWT signing. Generated automatically by the installer. The application refuses to start in production if this is set to the default placeholder.
`ENCRYPTION_KEY`	(none, required)	32-character hex string for encrypting stored secrets (API keys, passwords). Same startup validation as `SECRET_KEY`.
`DOMAIN`	`localhost`	FQDN used by Caddy for TLS certificate provisioning and by the API for CORS origin.
`DEBUG`	`false`	Disables rate limiting and allows default secrets. Never enable in production.
`LOG_LEVEL`	`info`	Valid values: `debug`, `info`, `warn`, `error`. Can be changed at runtime via the admin UI without restarting.
`LOG_FILE`	`/var/log/rimae-scan/rimae-scan.log`	Path to the log file. Set empty to disable file logging (stdout to journal is always active).

TLS / ACME Settings¶

Caddy handles TLS automatically via Let's Encrypt. These settings are only needed for customization.

Variable	Default	Description
`ACME_EMAIL`	(empty)	Email address for Let's Encrypt certificate registration. Required for automatic HTTPS.
`ACME_CA_URL`	(empty)	Custom ACME CA directory URL. Set this if using an internal CA like step-ca.
`INTERNAL_CA_CERT_PATH`	(empty)	Path to a PEM-encoded CA certificate for trusting an internal ACME CA.

Integration Settings¶

Variable	Default	Description
`WAZUH_API_URL`	(empty)	URL of the Wazuh manager API (e.g., `https://wazuh.example.com:55000`).
`WAZUH_API_KEY`	(empty)	API key for authenticating to the Wazuh API.
`WAZUH_TLS_VERIFY`	`true`	Verify TLS certificates when connecting to Wazuh. Set to `false` for self-signed certificates.
`GITHUB_ORG`	(empty)	GitHub organization name for repository scanning.
`GITHUB_PAT`	(empty)	GitHub personal access token with `repo` scope.
`CEPH_MGR_URL`	(empty)	Ceph manager API URL for cluster inventory.
`CEPH_API_KEY`	(empty)	API key for Ceph manager authentication.
`CEPH_TLS_VERIFY`	`true`	Verify TLS certificates when connecting to Ceph.
`HTTP_PROBE_TLS_VERIFY`	`true`	Verify TLS certificates for HTTP version probes.

If your environment uses an internal CA, set SSL_CERT_FILE (in the systemd unit or rimae-scan.conf) to your CA bundle. This applies globally to all outbound TLS connections -- Wazuh, Ceph, HTTP probes, and everything else.

AI / Enrichment Settings¶

Variable	Default	Description
`ANTHROPIC_API_KEY`	(empty)	API key for Anthropic Claude. Enables the source discovery and version onboarding LLM agents.
`VULNCHECK_API_KEY`	(empty)	API key for the VulnCheck enrichment service.

Authentication Settings¶

Variable	Default	Description
`AUTH_MODE`	`internal`	Authentication mode. Set to `internal` for built-in user management. LDAP and OIDC are configured separately.

LDAP Settings¶

LDAP is enabled automatically when LDAP_SERVER_URL is set.

Variable	Default	Description
`LDAP_SERVER_URL`	(empty)	LDAP server URL (e.g., `ldaps://ldap.example.com:636`).
`LDAP_BIND_DN`	(empty)	Bind DN for the service account (e.g., `cn=rimae-scan,ou=services,dc=example,dc=com`).
`LDAP_BIND_PASSWORD`	(empty)	Password for the bind DN.
`LDAP_USER_SEARCH_BASE`	(empty)	Base DN for user searches (e.g., `ou=people,dc=example,dc=com`).
`LDAP_USER_FILTER`	`(uid={username})`	LDAP filter for user lookup. `{username}` is replaced with the login name.
`LDAP_GROUP_SEARCH_BASE`	(empty)	Base DN for group membership searches.
`LDAP_ADMIN_GROUP_DN`	(empty)	DN of the group that maps to the admin role.
`LDAP_ANALYST_GROUP_DN`	(empty)	DN of the group that maps to the analyst role.
`LDAP_READONLY_GROUP_DN`	(empty)	DN of the group that maps to the read-only role.
`LDAP_TLS_VERIFY`	`true`	Verify the LDAP server's TLS certificate.
`LDAP_REQUIRE_TLS`	`true`	Require TLS for LDAP connections (StartTLS or LDAPS).
`LDAP_CA_CERT_PATH`	(empty)	Path to a CA certificate for verifying the LDAP server.

OIDC Settings¶

OIDC is enabled automatically when OIDC_ISSUER_URL is set.

Variable	Default	Description
`OIDC_ISSUER_URL`	(empty)	OpenID Connect issuer URL (e.g., `https://auth.example.com/realms/rimae-scan`).
`OIDC_CLIENT_ID`	(empty)	OIDC client ID.
`OIDC_CLIENT_SECRET`	(empty)	OIDC client secret.
`OIDC_SCOPES`	`openid profile email`	Space-separated list of OIDC scopes to request.
`OIDC_ROLE_CLAIM`	`roles`	JWT claim containing the user's role.
`OIDC_ADMIN_CLAIM_VALUE`	`admin`	Claim value that maps to the admin role.
`OIDC_ANALYST_CLAIM_VALUE`	`analyst`	Claim value that maps to the analyst role.

SMTP Settings (Optional)¶

Configure via the Settings UI or directly in the config file.

Variable	Default	Description
`SMTP_HOST`	(empty)	SMTP server hostname.
`SMTP_PORT`	`587`	SMTP server port.
`SMTP_USERNAME`	(empty)	SMTP authentication username.
`SMTP_PASSWORD`	(empty)	SMTP authentication password.
`SMTP_FROM_ADDRESS`	(empty)	Sender address for email notifications.

Rate Limiting¶

Variable	Default	Description
`RATE_LIMIT_WRITE`	`60`	Maximum write requests (POST/PATCH/PUT/DELETE) per user per minute.
`RATE_LIMIT_EXPORT`	`5`	Maximum export requests per user per minute.

Authentication endpoints (login, setup) are rate-limited at 10 requests per IP per minute regardless of these settings.

Rate limiting is backed by Redis. If Redis is unavailable, auth endpoints fall back to an in-process counter; other rate limits are bypassed. Rate limiting is disabled entirely when DEBUG=true.

Web Server (Caddy) Configuration¶

Caddy handles automatic HTTPS via Let's Encrypt and reverse proxies all traffic to the Go binary.

The Caddyfile lives at /etc/rimae-scan/Caddyfile. The domain is injected via the DOMAIN environment variable from /etc/rimae-scan/caddy.env.

Default Caddyfile¶

The frontend is embedded in the Go binary, so Caddy acts purely as a reverse proxy:

{$DOMAIN:localhost} {
    reverse_proxy localhost:8000
}

Routing Summary¶

Path	Handler
`/api/*`	API endpoints (served by Go binary on port 8000)
`/ws/*`	WebSocket connections (served by Go binary)
Everything else	Embedded React frontend (served by Go binary)

Caddy terminates TLS and forwards all traffic to the Go server.

Using an Internal ACME CA¶

If you run an internal CA (e.g., step-ca), set these in /etc/rimae-scan/rimae-scan.conf:

ACME_CA_URL=https://step-ca.internal/acme/acme/directory
INTERNAL_CA_CERT_PATH=/etc/ssl/certs/internal-ca.pem

Caddy Systemd Integration¶

The installer creates a systemd drop-in at /etc/systemd/system/caddy.service.d/rimae-scan.conf that points Caddy to the rimae/scan Caddyfile:

[Service]
EnvironmentFile=/etc/rimae-scan/caddy.env
ExecStart=
ExecStart=/usr/bin/caddy run --config /etc/rimae-scan/Caddyfile --adapter caddyfile

Systemd Service Management¶

rimae/scan runs as systemd services under the rimae-scan user with hardened security settings.

Services¶

Service	Description	Port
`rimae-scan`	Go binary running the Echo v4 API server with embedded robfig/cron scheduler	8000 (localhost only)

Common Operations¶

# Start all services
sudo systemctl start rimae-scan

# Stop all services
sudo systemctl stop rimae-scan

# Restart a single service
sudo systemctl restart rimae-scan

# View service status
systemctl status rimae-scan

# View logs (live)
journalctl -u rimae-scan -f

# View worker logs (last 100 lines)
journalctl -u rimae-scan -n 100

Security Hardening¶

All services run with these systemd security directives:

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictNamespaces=true
LockPersonality=true
ReadWritePaths=/var/lib/rimae-scan /var/log/rimae-scan

Log Locations and Rotation¶

Default Log Destination¶

All rimae/scan services log to the systemd journal (StandardOutput=journal).

# All rimae/scan services
journalctl -u rimae-scan

# Specific service, since boot
journalctl -u rimae-scan -b

# Follow real-time
journalctl -u rimae-scan -f

# Filter by time
journalctl -u rimae-scan --since "2024-01-01 00:00:00" --until "2024-01-02 00:00:00"

Journal Disk Usage¶

journalctl -u rimae-scan --disk-usage

Log Rotation¶

Systemd journal rotation is configured system-wide in /etc/systemd/journald.conf. Recommended settings:

[Journal]
SystemMaxUse=2G
MaxRetentionSec=90day

Apply changes with sudo systemctl restart systemd-journald.

Log Directory¶

/var/log/rimae-scan exists for scripts and tools that write log files directly (e.g., the backup script). The health check script warns if this directory exceeds 500 MB.

Backup and Restore¶

Creating a Backup¶

sudo bash /usr/lib/rimae-scan/scripts/backup.sh

This creates a timestamped backup in /var/backups/rimae-scan/<YYYYMMDD_HHMMSS>/ containing:

File	Contents
`rimae-scan_db.sql.gz`	Compressed PostgreSQL database dump
`config/rimae-scan.conf`	Configuration file (encrypted with GPG if a backup key is configured)
`config/Caddyfile`	Caddy configuration
`config/caddy.env`	Caddy environment file
`config/golang-migrate.ini`	golang-migrate migration configuration
`caddy_data.tar.gz`	Caddy TLS certificates and state

Backup Options¶

# Custom retention period (default: 7 days)
sudo bash /usr/lib/rimae-scan/scripts/backup.sh --retention 14

# Custom backup directory
sudo bash /usr/lib/rimae-scan/scripts/backup.sh --backup-dir /mnt/backup/rimae-scan

Automated Backups¶

Add a cron job for daily backups:

sudo crontab -e
# Add this line:
0 2 * * * /usr/lib/rimae-scan/scripts/backup.sh >> /var/log/rimae-scan/backup.log 2>&1

Encrypted Backups¶

To encrypt configuration backups automatically:

head -c 32 /dev/urandom | base64 > /var/lib/rimae-scan/.backup-key
chmod 600 /var/lib/rimae-scan/.backup-key

When .backup-key exists and gpg is installed, the backup script encrypts rimae-scan.conf using symmetric GPG encryption before storing it.

Store the backup key separately from the backups. If you lose the key, the encrypted configuration backup is unrecoverable.

Restoring from Backup¶

Stop services:

sudo systemctl stop rimae-scan

Restore the database:

sudo -u postgres dropdb rimae-scan
sudo -u postgres createdb -O rimae-scan rimae-scan
gunzip -c /var/backups/rimae-scan/<timestamp>/rimae-scan_db.sql.gz | sudo -u postgres psql -d rimae-scan

Restore the configuration:

# If encrypted:
gpg --batch --passphrase-file /var/lib/rimae-scan/.backup-key \
    -d /var/backups/rimae-scan/<timestamp>/config/rimae-scan.conf.gpg \
    > /etc/rimae-scan/rimae-scan.conf

# If plaintext:
sudo cp /var/backups/rimae-scan/<timestamp>/config/rimae-scan.conf /etc/rimae-scan/rimae-scan.conf
sudo chown rimae-scan:root /etc/rimae-scan/rimae-scan.conf
sudo chmod 600 /etc/rimae-scan/rimae-scan.conf

Restore Caddy certificates (optional):

sudo tar -xzf /var/backups/rimae-scan/<timestamp>/caddy_data.tar.gz -C /

Start services:

sudo systemctl start rimae-scan

Settings UI¶

Many configuration options are also available through the web UI at https://your-domain/settings/.

Page	Description
OS Versions	Manage monitored OS distributions and versions
Vuln Sources	Enable/disable vulnerability sources and view crawl status
App Configs	Configure application definitions and version probes
Integrations	Configure Wazuh, GitHub, Ceph, and other integrations
Retention	Set data retention policies
Auth	Manage authentication providers (internal, LDAP, OIDC)
Score Formula	Customize the composite risk scoring weights
Branding	Customize logo, colors, and product name
System	View system status and perform administrative actions

Integration settings (Wazuh, GitHub, Ceph, etc.) can be configured either in rimae-scan.conf or through Settings > Integrations. Values saved through the UI are stored as encrypted database overrides and take priority over values in the config file. Core infrastructure values (database, Redis, secrets) are always read from rimae-scan.conf.