Skip to content

Settings Reference

rimae/scan provides a centralized Settings interface for managing integrations, vulnerability sources, scoring formulas, retention policies, branding, and system health. All settings screens are accessible from the sidebar under Settings and require the admin role unless otherwise noted.

Note: All configuration changes made through the Settings UI are recorded in the audit log with the actor, timestamp, and before/after values.

Integrations

The Integrations panel manages connections to external infrastructure services. Each integration includes a Test Connection button that validates connectivity and reports response time. Note that for Wazuh, you must save the connection settings first, then use the Test Connection button -- it tests the saved (persisted) values, not unsaved form inputs.

Wazuh

Wazuh provides live asset inventory -- OS packages, application versions, and agent status.

Field Description Default
url Wazuh API base URL (e.g., https://wazuh.example.com:55000) From WAZUH_API_URL env
api_key Wazuh API key (stored masked after save) From WAZUH_API_KEY env
poll_interval_minutes How often to poll Wazuh for inventory updates 15
staleness_threshold_hours Mark assets as stale if no Wazuh heartbeat within this window 24

Note: Initial values come from the rimae-scan.conf environment file. Overrides saved through the UI take precedence and are stored encrypted in the database.

GitHub

GitHub integration enables repository scanning across your organization, dependency parsing, and supply-chain vulnerability correlation.

Field Description Default
org GitHub organization name From GITHUB_ORG env
auth_type Authentication method: pat (Personal Access Token) or app (GitHub App) pat
pat Personal Access Token (stored masked) From GITHUB_PAT env
app_id GitHub App ID (when auth_type is app) Empty
private_key GitHub App private key (stored masked) Empty

Ceph

Ceph integration pulls storage cluster health and version data from the Ceph Manager API.

Field Description Default
url Ceph Manager API URL (e.g., https://ceph-mgr:8003) From CEPH_MGR_URL env
api_key Ceph API key (stored masked) From CEPH_API_KEY env

The test connection checks the /api/health/full endpoint on the Ceph Manager.

Docker

Docker integration discovers container images running on your hosts.

Field Description Default
socket_path Docker daemon socket path /var/run/docker.sock
registry_url Private registry URL for image metadata lookups Empty
registry_auth Registry authentication credentials (stored masked) Empty

Integration Platforms

The Platforms panel manages connections to SIEM, scanner, threat intelligence, ticketing, and notification systems. Each platform type supports multiple adapters, and adapters can be enabled or disabled independently.

Platform Types

Type Mode Description
siem Multi-active Ingest security events from SIEM systems (Wazuh, Splunk, Elastic, QRadar, etc.)
scanner Multi-active Import findings from vulnerability scanners (Nessus, Qualys, Rapid7, etc.)
threat_intel Multi-active Correlate with threat intelligence feeds (MISP, VirusTotal, Shodan, etc.)
ticketing Exclusive Create and sync remediation tickets (Jira, Zendesk, Frappe Helpdesk)
notification Multi-active Dispatch alerts via notification channels (Slack, PagerDuty, email, etc.)

Platform Properties

Each platform configuration includes:

Field Description
slug Unique adapter identifier (e.g., jira, splunk, shodan)
platform_type One of: siem, scanner, threat_intel, ticketing, notification
config Encrypted JSON configuration (base URL, credentials, options)
enabled Whether this adapter is active

Actions

  • Test Connection -- Validates connectivity to the configured endpoint
  • Sync Now -- Triggers an immediate data sync for the adapter
  • Add Platform -- Register a new adapter with encrypted configuration

Vulnerability Sources

The Vulnerability Sources panel lists all configured data sources that rimae/scan crawls for vulnerability intelligence. Sources are organized by category and can be individually enabled or disabled.

Source Properties

Each vulnerability source has the following configurable fields:

Field Description
enabled Whether the source is actively crawled
crawl_interval_minutes How often (in minutes) to fetch updates from this source
api_key_ref Reference to a stored secret for authenticated sources
priority_weight Weight used in the composite scoring formula (0.0 -- 10.0)
notes Free-text notes for operators

Read-Only Fields

These fields are set during source registration and reflect the source's configuration:

Field Description
slug Unique identifier (e.g., nvd, epss, cisa-kev)
name Human-readable display name
category Source category grouping
fetch_url URL where data is fetched from
fetch_method HTTP method used for fetching
auth_required Whether the source requires authentication
auth_type Type of authentication (e.g., api_key, bearer)
parser_type Parser used to process the response
contributes_to Which data fields this source populates

Last Crawl Status

Each source displays its last crawl status:

  • last_crawled_at -- Timestamp of the most recent crawl
  • last_crawl_status -- Result status (e.g., success, error)
  • last_crawl_record_count -- Number of records processed in the last crawl

Crawl Now

Admins can trigger an immediate crawl for any source using the Crawl Now button, which queues a background task. The endpoint returns HTTP 202 Accepted.

Test Connection

The Test button sends a HEAD request to the source's fetch_url and reports reachability and response time.

Filtering

The source list supports filtering by:

  • Category -- Filter to a specific source category
  • Enabled -- Show only enabled or disabled sources

OS Version Configurations

The OS Versions panel manages the operating system versions tracked by rimae/scan. Each version defines where to find advisories, how to match CVEs, and what dependency chains apply.

Version Properties

Field Description
distro Distribution name (e.g., ubuntu, almalinux, proxmox, debian, esxi)
version Version string (e.g., 22.04, 9, 8.2)
codename Release codename (e.g., jammy, bookworm)
eol_date End-of-life date
advisory_base_url Base URL for the vendor's advisory page
advisory_feed_url URL to the machine-readable advisory feed
advisory_feed_type Feed format: usn, alma_errata, proxmox, vmsa, dsa, oval, or scraped_html
secondary_advisory_sources Additional advisory sources (e.g., Debian DSA for Proxmox)
nvd_cpe_string CPE string for NVD matching
oval_url OVAL definition feed URL
debian_base_version For Proxmox: the underlying Debian version
debian_base_codename For Proxmox: the underlying Debian codename
enabled Whether this version is actively tracked

Auto-Discovered Versions

OS versions can be automatically discovered by the Version Onboarding Agent. These arrive with auto_discovered=true and enabled=false (staged for review).

Staged discoveries can be:

  • Approved -- Sets enabled=true, activating advisory crawling for this version
  • Edited -- Modify any field before approving
  • Left staged -- Remains disabled until manually approved

Test Feed

The Test Feed button validates that the advisory_feed_url is reachable.

Re-Run Agent

For any OS version, admins can re-trigger the onboarding agent to refresh its configuration data.

Application Configs

The Application Configs panel manages tracked applications (Nginx, PostgreSQL, Redis, etc.) and their version probing strategies.

App Properties

Field Description
name Display name
slug Unique identifier
category Application category grouping
probe_method How to detect the installed version (command, http, api)
probe_command Shell command to extract version (when probe_method is command)
probe_url_template URL template for HTTP version probing
probe_auth_type Authentication type for the probe endpoint
probe_auth_secret_ref Reference to stored credentials for the probe
version_parse_pattern Regex pattern to extract version from probe output
advisory_source_slug Which vuln source provides advisories for this app
nvd_cpe_string CPE string for NVD matching
vendor_advisory_url Direct link to the vendor's advisory page
github_repo GitHub repository (e.g., nginx/nginx) for release tracking
enabled Whether this app is actively probed and tracked

Probe Now

The Probe Now button triggers an immediate version detection probe via a background task.

Score Formula Customization

The Score Formula panel controls how rimae/scan calculates the composite risk score for vulnerability matches. The composite score determines the order of the remediation queue.

How It Works

Each enabled vulnerability source has a priority_weight (0.0 -- 10.0). The composite score is a weighted average:

composite = (w1 * source1_score + w2 * source2_score + ...) / sum(weights)

The formula preview shows the current calculation:

composite = (1.0*nvd + 1.5*epss + 2.0*cisa-kev + ...) / sum(weights)

Adjusting Weights

  • Increase a source's weight to make its signal count more in prioritization
  • Set a weight to 0.0 to exclude a source from scoring without disabling its crawling
  • Use the Reset to Defaults button to set all weights back to 1.0

Warning: Changing weights recalculates composite scores on the next correlation run. Existing scores are not retroactively updated until the next scan cycle.

Retention Policies

The Retention panel controls how long rimae/scan retains historical data.

Field Description Default Constraints
retention_days Global retention period in days 365 30 -- 3650
per_table_overrides Per-table retention overrides (table name to days) {}

Per-table overrides allow different retention periods for specific data types. For example, you might keep vulnerability match history for 2 years but audit logs for only 90 days:

{
  "audit_logs": 90,
  "scan_runs": 180,
  "vuln_matches": 730
}

Branding / White-Label

The Branding panel customizes the look and feel of the rimae/scan interface and exported reports. Branding settings are publicly readable (no auth required for the GET endpoint) so the frontend can apply them before login.

Configurable Fields

Field Description Default
product_name Displayed product name (max 64 chars) rimae/scan
product_tagline Tagline shown on the login page None
company_name Your organization name None
primary_color Primary brand color (hex) #7F77DD
primary_color_dark Primary color for dark mode None
accent_color Accent/highlight color (hex) #5DCAA5
sidebar_style Sidebar visual style dark
default_theme Default UI theme dark
report_header_text Header text on exported reports None
report_footer_text Footer text on exported reports None
support_url Link to your support portal None
documentation_url Link to your documentation None
hide_rimae-scan_attribution Hide "Powered by rimae/scan" in reports false

Logo and Favicon Uploads

Uploaded logos appear in the sidebar navigation and on the login page.

Upload custom assets through the branding asset endpoints:

Asset Type Format Max Size
logo_light PNG only 2 MB
logo_dark PNG only 2 MB
favicon ICO 2 MB

Note: SVG logos are rejected for security reasons (XSS risk). Convert logos to PNG before uploading.

Logging

The Logging panel provides admin-only controls for managing the application log level and reviewing log output configuration.

Log Level Management

Field Description Default
log_level Application log verbosity info

Available levels, from most to least verbose:

  • debug -- Detailed diagnostic output for troubleshooting
  • info -- Normal operational messages (default)
  • warn -- Warning conditions that may require attention
  • error -- Error conditions that need immediate investigation

Changes to the log level take effect immediately -- no application restart is required.

Runtime Configuration

The log level can be changed through the Settings UI or via the API:

Method Endpoint Description
GET /api/system/log-level Returns the current log level
PUT /api/system/log-level Sets a new log level (body: { "level": "debug" })

File-Based Logging

Application logs are written to /var/log/rimae-scan/rimae-scan.log. Log rotation is managed by logrotate with the following policy:

  • Rotation frequency: Weekly or when the log file reaches 500 MB, whichever comes first
  • Compressed: Yes (gzip)

Note: stdout is always forwarded to the systemd journal (journalctl -u rimae-scan -f) regardless of file logging configuration.

System Status and Force Actions

The System panel provides real-time infrastructure health and administrative trigger actions.

System Status

The status endpoint reports:

Field Description
version Current rimae/scan version
db_connected Whether PostgreSQL is reachable
redis_connected Whether Redis is reachable
scheduler_jobs Number of registered cron jobs
active_tasks Number of currently running background tasks
log_level Current application log level

Force Actions

These admin-only actions queue background tasks:

Action Description
Force Correlate Triggers a full vulnerability correlation run across all assets and sources
Force Inventory Triggers a complete inventory pull from all connected integrations

Both actions dispatch actual background tasks and return HTTP 202 Accepted with a confirmation message. Progress can be monitored via the worker logs (journalctl -u rimae-scan -f).

Maintenance Mode

Admins can toggle maintenance mode on and off. When enabled, the system signals to clients that it is undergoing maintenance.