Quick start
guide.

Quick start

From zero to monitoring in 5 minutes.

Requirements

What your Linux host needs to run RuntimeGuard.

The eBPF agent uses CO-RE (Compile Once, Run Everywhere) — the same binary works on Ubuntu 20.04+, Debian 11+, RHEL 8+, Fedora 33+, Amazon Linux 2023, and any cloud-provider kernel that ships with BTF enabled (Google Cloud, AWS, Azure all do by default).

To verify BTF is available on your host:

Learning mode vs Enforcing mode

Understand your host's activity before letting RuntimeGuard take action.

What each mode does

Mode	Incidents	Alerts	Containment (kill)
learning	Created with status learning	None	None
enforcing	Created with status open	Slack, email, webhook	SIGKILL on offending process (if containment is enabled for the rule)

Recommended rollout

Every new host starts in learning mode automatically. Leave it there for at least a few days — ideally through a full week including weekends to capture all scheduled jobs (cron, backups, log rotation, deployments).

Check the dashboard daily. If you see incidents marked learning, investigate them:

• Is this a legitimate process? → Raise the threshold for that rule in the Rules tab.
• Is this suspicious? → You already found a threat before enabling containment.

Open the Rules tab in the dashboard and adjust thresholds for rules that fire on legitimate activity. Default thresholds:

Rule	Default threshold	Window	Severity
file_rename_burst	5 renames	60 seconds	HIGH / 80
file_write_burst	10 writes	60 seconds	MEDIUM / 65
process_exec_burst	50 executions	60 seconds	HIGH / 75
priv_esc_attempt	3 escalations	60 seconds	HIGH / 85
network_burst	20 connections	60 seconds	MEDIUM / 60

Once you are satisfied with the thresholds, switch the host to enforcing mode from the dashboard. Go to Hosts, click the host, and toggle the mode to Enforcing.

In enforcing mode, when a rule fires:

• An incident is created with status open.
• You receive a Slack and/or email alert immediately.
• If containment is enabled for the rule, the offending process receives SIGKILL on the host within seconds.

Enforcing without containment

A good intermediate step is to run in enforcing mode with containment turned off. You receive full alerts (Slack, email, webhook) but no processes are killed. Once you have confirmed there are no false positives, enable containment per rule in the Rules tab.

Configuration reference

Agent environment variables

Variable	Default	Description
AGENT_API_KEY	—	Required. Your RuntimeGuard API key from the dashboard.
AGENT_API_URL	https://api.runtimeguard.io	Backend API endpoint. Override for self-hosted deployments.
AGENT_HOST_ID	hostname	Identifier for this host, shown in the dashboard.
AGENT_BATCH_SIZE	25	Flush after this many events are buffered.
AGENT_FLUSH_INTERVAL_SECONDS	5	Flush interval even if batch size is not reached.

Backend environment variables

If you are running the backend yourself (self-hosted tier), these are the variables to configure:

Variable	Default	Description
BACKEND_PORT	8080	Port the API server listens on.
ADMIN_SECRET	dev-admin-secret	Secret for admin API endpoints. Change this in production.
CORS_ORIGIN	http://localhost:5173	Allowed CORS origin for the dashboard.
POSTGRES_DSN	see .env.example	PostgreSQL connection string for tenant/incident storage.
CLICKHOUSE_DSN	see .env.example	ClickHouse connection for event time-series.
ALERT_WEBHOOK_URL	—	Webhook URL for incident alerts (Slack-compatible).

Slack notifications

Receive instant alerts in your Slack workspace when an incident is detected.

RuntimeGuard supports per-account Slack webhooks — each customer configures their own. No backend environment variable needed. To set up notifications:

• In Slack, go to Your apps → Incoming Webhooks and create a new webhook for the desired channel.
• Copy the webhook URL (starts with https://hooks.slack.com/services/...).
• In the dashboard, open the Settings tab, paste the URL and click Save.
• Click Send test to verify the connection.

Alerts are sent for every new incident in enforcing mode. Incidents in learning mode do not trigger notifications.

Alert format

API reference

Authentication

All API requests must include the X-API-Key header with a valid API key. Keys are tenant-scoped and can be created and revoked from the dashboard.

Endpoints

eBPF mode

The production agent uses a compiled eBPF program for maximum performance and visibility. Here's what that means.

RuntimeGuard uses CO-RE (Compile Once, Run Everywhere) via the cilium/ebpf library. The eBPF bytecode is compiled once during the build pipeline and embedded in the agent binary. At runtime, the Linux kernel's BPF verifier checks and loads it — no recompilation, no kernel headers needed on the host.

Tracepoints attached

Tracepoint	Event kind	What is captured
sys_enter_execve	process_exec	Process name, arguments, PID, UID
sys_enter_openat	file_write	File path, PID, comm (when O_WRONLY/O_RDWR flags set)
sys_enter_rename	file_rename	Old path, new path, PID, comm
sys_enter_renameat2	file_rename	Old path, new path, PID, comm (modern rename syscall)

Multi-host deployment

Monitoring a fleet? Deploy the agent on each host with the same API key and a unique AGENT_HOST_ID.

Each host appears as a separate entry in the dashboard. Incidents are always tied to the originating host, so you can track which machine was affected at a glance.

Ansible example

MSP / multi-tenant

Manage multiple customer environments from a single RuntimeGuard account.

RuntimeGuard's Business tier supports multiple tenants per account. Each tenant has its own API keys, hosts, and incidents — with full data isolation between them. You can switch between tenants in the dashboard using the tenant selector.

• Create a separate tenant per customer from the Admin panel.
• Generate API keys scoped to each tenant. The agent automatically resolves the tenant from the API key — no extra configuration needed.
• Incidents and alerts are always delivered within the correct tenant scope.
• The dashboard tenant selector lets you switch context without logging out.
• The cross-tenant SOC feed (GET /v1/admin/soc) shows all open incidents across every managed tenant in a single view.

Custom detection rules

Write Sigma-compatible YAML rules alongside the 26 built-in rules.

RuntimeGuard supports custom detection rules in Sigma YAML format. Rules are written from the dashboard in the Rules → Custom tab, validated on save, and applied to every event in real time — no deployment step required.

Rule format

Supported fields

Field	Logsource category	Description
exe	process_creation	Full path to the executed binary.
comm	process_creation	Process name (basename of exe).
args	process_creation	Command-line arguments string.
path	file_event	File path involved in the event.
dst_ip	network_connection	Destination IP address.
dst_port	network_connection	Destination port number.

Field modifiers

Supported modifiers: |contains, |startswith, |endswith, |re (regex), and exact match (no modifier).

Condition syntax

• condition: selection — all criteria in the selection block must match.
• condition: selection and not filter — match selection but exclude known-good patterns defined in a filter block.
• condition: 1 of them — match if any named selection block matches (for multi-alternative rules).

RBAC roles

Three roles control what each API key (and each SSO user) can do.

Role	Access
admin	Full access: manage API keys and roles, configure integrations, host isolation, billing, view and export the audit log.
analyst	Incident triage: set status, assign incidents, add investigation notes, view playbooks and process trees. Cannot modify system configuration.
viewer	Read-only access to incidents, hosts, metrics and compliance reports. Suitable for management dashboards and external auditors.

Assigning roles

Every API key has an associated role. Roles are assigned when the key is created and can be changed by an admin at any time from Settings → API Keys in the dashboard, or via the API:

Audit log

Every state-changing request (POST, PUT, PATCH, DELETE) made by any API key is written to the audit log with the actor's key ID, role, HTTP method, path, status code and timestamp. Admins can query the audit log from the dashboard or via the API: