FAQ

RunReveal is a security platform that can function as a SIEM, a case-management system, and a place to search logs, run detections, and investigate with your team. This page answers the questions people ask when they are new to the product, including the "I want to do X, what do I click?" ones.

A step-by-step walkthrough can be found in our onboarding guide.

Find a task

Platform basics

What is RunReveal?

RunReveal is a security platform. The same workspace can function as a SIEM, a case-management system, a log search tool, and a detection pipeline. You connect the systems you already run (identity, cloud, endpoint, SaaS, and hosts), search the events with SQL, and write detections that turn matches into signals or alerts. From an alert you can open an investigation, notify Slack or on-call, ask the AI assistant, and chart the same data on a dashboard.

You write the detections, or you subscribe to ones RunReveal maintains. Search, detections, investigations, and dashboards all sit on the same data.

Logs live in ClickHouse. You can use RunReveal's cloud, keep the database in your own ClickHouse (BYODB), or run the product in your own cloud (BYOC).

How does a log become an alert?

1. A source receives the event (webhook, API poll, or object storage) or a forwarder ships it from a host.
2. A topic picks which pipeline handles it. Unmatched events use the default pipeline.
3. Pipeline steps transform, enrich, mask, filter, sample, or drop the event, then a destination writes what remains. The default destination is your workspace ClickHouse.
4. A Sigma rule can match the event while it is in the pipeline. A SQL detection runs on a schedule over data already stored.
5. A match with no notification channel is a signal. The same match with a channel attached is an alert.
6. You investigate from Investigations, Explore, or Chat. An agent can open the investigation for you when AI triage is on.

What should I do first?

1. Connect one source you already know, such as Okta, AWS CloudTrail, GitHub, or Google Workspace.
2. Confirm rows in Explore.
3. Subscribe to a Tier 1 managed detection or write one SQL detection, and leave notifications off until the results look right.
4. Attach a notification channel, then invite the rest of the team.

The full sequence is the onboarding guide.

What are the keyboard shortcuts?

These work on Mac (Command) and Windows or Linux (Ctrl):

Command+K and Command+I still work while you are typing in a field.

Where do I get help?

• This page and the onboarding guide for setup.
• The glossary when a word is unfamiliar.
• Your shared Slack channel with RunReveal, or [email protected], for general questions.

Accounts, workspaces, and access

What is an organization, and what is a workspace?

An organization is the top-level account. It holds billing, SSO, and one or more workspaces. A workspace is where sources, logs, detections, pipelines, members, and dashboards live. Queries and detections only see the workspace you have selected.

How do I invite someone?

You need permission to edit the workspace (the Admin role).

1. Go to Settings → Workspace → Members.
2. Click Invite member, enter their email, and pick a role.
3. They stay Pending until they accept the email. Then they are Active.

If SSO with just-in-time provisioning is on, a person can also appear the first time they sign in through your identity provider. See Managing users.

What do the roles allow?

RunReveal ships four roles. Admin has every permission. The others are narrower. The full matrix is Role-based access control.

Custom roles combine those permissions and can restrict which data the role sees. Create them at Settings → Workspace → Custom roles. You can assign a custom role to a person or to an API token.

How does SSO work?

SSO is SAML through WorkOS. Authentication stays with your identity provider (Okta, Azure AD, Google Workspace, and other SAML IdPs). RunReveal still decides what they can do, through workspace roles.

Contact RunReveal support with the email domains you want to allow. Support sends a WorkOS setup link. Domain ownership has to be confirmed before users can sign in that way. See Single sign-on.

What is an API token, and how is it different from a user?

An API token authenticates scripts, the CLI in CI, and the Logs API. It belongs to the workspace, not to a person. Create one at Settings → Workspace → API tokens (Generate token). Assign it a role, including a custom role, so the token cannot do more than the job needs.

User sessions are for people in the app. Tokens are for anything that is not a browser login. See the Logs API and the CLI.

Who can add a source?

Creating or editing a source requires Edit Sources, which the Admin role includes. Analysts and operators can view sources. If an analyst should connect sources, give them a custom role with that permission rather than making them an admin.

How do I change someone's role or remove them?

Go to Settings → Workspace → Members, open the person, and choose Update role. The new role applies immediately. They may need to refresh the page before the UI matches.

Remove revokes access at once. It does not delete logs, detections, or investigations they created. You need permission to edit the workspace. See Managing users.

Does SSO copy roles from my identity provider?

No. Your IdP proves who the person is. RunReveal roles are assigned in the workspace. With just-in-time provisioning, the first SSO login creates the account at the default role you configured. Without it, an admin still has to invite them. Groups in Okta or Azure AD do not become RunReveal roles. See Single sign-on.

How do I switch workspaces?

Use the workspace switcher in the app. Sources, queries, detections, and chat history belong to the workspace you have open. An API token is created inside one workspace and only works there. The CLI uses a profile for the same reason. See Using the CLI.

Sources

How do I add a source?

1. Open Sources and choose Connect a new source (Command+Shift+S or Ctrl+Shift+S).
2. Search the catalog and click Connect on the product tile.
3. Finish the wizard. For an API source, enter a least-privilege credential, click Test Connection, then save.
4. Open the source and check Health Checks for a recent receipt time.
5. In Explore, confirm events:

SELECT
  sourceType,
  eventName,
  count() AS event_count
FROM logs
WHERE sourceType = 'okta'
  AND receivedAt > now() - INTERVAL 10 MINUTE
GROUP BY sourceType, eventName
ORDER BY event_count DESC
LIMIT 20

Change okta to your source type. The catalog and per-product setup are on Sources.

Which ingest method should I use?

Some products offer more than one. Prefer polling or object storage when you have the choice. A webhook drops events if the sender does not retry a failed HTTP call. Polling and object storage can catch up after an outage.

Object storage setup, including S3 with RunReveal's SNS topic or your own SQS queue, is under Sources.

There is no tile for my product. What do I do?

If you can POST JSON or drop files in S3, GCS, Azure Blob, Cloudflare R2, or MinIO, use Custom Source or Generic.

• Custom Source walks you through the connection, shows a preview of the JSON, and can map fields onto normalized columns.
• Generic is the bucket-notification path into the generic pipeline.
• Structured webhooks expect the body to already look like a normalized RunReveal event. A generic webhook stores the body in rawLog and leaves mapping to a transform.

If the only option is an API RunReveal would have to poll, contact support with the API documentation and a sample export.

How do I collect logs from a host?

There is no syslog tile. Run a forwarder on the machine and point it at a webhook source you create first.

• reveald is RunReveal's forwarder. It tails files, journald, syslog, and Windows Event Logs, and can parse on the host before it ships.
• Fluent Bit, Vector, Logstash, and the OTLP and Datadog forwarders can POST to the same webhook.

reveald is the shipper. The runreveal CLI is a different binary. It talks to the API. It does not collect logs.

Kubernetes and Nginx have their own guides: Kubernetes logs and Nginx logs.

How do I send a test event?

1. Sources → Connect a new source → Webhook (generic or structured).
2. Copy the webhook URL and the bearer token.
3. POST one JSON event:

curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -d '{
    "timestamp": "2026-01-15T18:30:00Z",
    "eventName": "suspicious_login",
    "user": "test-user",
    "srcIP": "192.168.1.100"
  }'

You can edit the source and remove the bearer token if you want unauthenticated requests. Leave the token on for anything that is not a local test. The hands-on version of this flow is Detections, signals, and alerts.

How do I know a source is healthy?

Open the source and look at Health Checks. You can add a Log Volume check with a minimum count, a time window, and a schedule. The default schedule is every 15 minutes (@15m).

Attach a notification channel if you want a message when the check fails. With no channel, the check still records status and does not alert. Failure threshold is how many consecutive failures are required before it alerts. The default is 1. Raise it when a source is bursty.

You can silence a health check for a window (maintenance, a known upstream outage). The check keeps evaluating. It stops notifying until the silence ends. The same idea exists for destination health checks.

Also look at Sources → Source Errors when setup succeeds and events still do not arrive. See Health checks.

The vendor wants an IP allowlist. Which addresses do I add?

Polling sources call out from RunReveal. If the vendor or your firewall only allows known IPs, add every address on Network connectivity, including the fallbacks. Allowing only the primary addresses fails during failover.

Can I connect the same product more than once?

Yes. A source is one connection: one AWS account, one Okta org, one GitHub org, one bucket. Create a separate source for staging and production. Give each a name you will recognize in queries (sourceType is the product, the source name is the instance).

Sigma rules can be limited to one of those names with sourcenames, or to a product with sourcetypes. See Sigma streaming.

Why is a source missing from my catalog?

Each integration has a plan: Free, Pro, or Enterprise. The app offers the sources your workspace plan includes. Filter the Sources catalog by plan to see what a higher tier adds.

What does the transform on a source do?

Official sources ship a default transform that maps vendor JSON onto shared columns such as eventName, actor, and src. Leave the transform blank to keep that default. Pick another transform when you have already written one under Sources → Source Transforms.

Custom and generic sources do not transform anything until you map fields. The original payload is always kept in rawLog.

How do I backfill old logs?

It depends on the source.

• Many polling sources load a vendor-specific window on first connect (hours or days). The source's own page states the window.
• If the history is already in a bucket, add a Backfill source, point it at that prefix, and let it drain. Large buckets can take hours or days. See Backfill.

Backfill does not rewrite events that are already stored. Fix a bad compression or format setting, then re-deliver the objects that failed.

What happens if I disable a source?

Ingestion stops. The configuration stays in the inactive list and you can turn it back on. Logs already stored stay until retention expires (550 days by default, or the TTL you set). Disabling a source does not delete those logs.

How do I delete logs?

Storage is append-only. A workspace admin cannot delete rows from the UI. That is deliberate: an auditor can see that an admin did not erase evidence from the product.

Contact support (your shared Slack channel or [email protected]) with the workspace, the source, a description of the logs, the time range, and the reason. RunReveal confirms the scope with you before deleting anything. Deletion is permanent.

To stop new events without deleting history, disable the source.

Where are source credentials stored?

Polling and object-storage sources keep the keys you enter so RunReveal can collect on your behalf. They are stored encrypted. Use a dedicated credential with the minimum read access the source page asks for, and rotate it at the vendor when someone who knew it leaves.

Can one forwarder send different logs to different places?

Yes. A single reveald install can tail several inputs and route them. Routes override the default "every source goes to every destination," so audit logs can go to one webhook and application logs to another, or some inputs can archive to S3 while others go to RunReveal. See the routes section of reveald configuration.

How do I see how much a source is sending?

Open the source's health check, or chart volume in Explore:

SELECT
  toStartOfHour(receivedAt) AS hour,
  count() AS events
FROM logs
WHERE sourceType = 'cloudtrail'
  AND receivedAt > now() - INTERVAL 1 DAY
GROUP BY hour
ORDER BY hour

runreveal_source_volumes in Explore is the same idea as a platform table. A health check is the right tool when you want an alert that the count dropped, not just a chart.

Searching logs

How do I search logs?

Open Explore in the sidebar (the docs also call this Explore Logs). Pick a time range and run SQL. Filter on receivedAt and, when you are using the logs table, on sourceType.

SELECT eventTime, eventName, actor.email, src.ip
FROM logs
WHERE sourceType = 'okta'
  AND receivedAt > now() - INTERVAL 1 HOUR
ORDER BY receivedAt DESC
LIMIT 50

Prefer the source-specific table when you know the product (okta_logs, aws_cloudtrail_logs). It is laid out for that source. logs is every source in the workspace. See Explore Logs and Queries.

Do I have to write SQL?

Explore and SQL detections are SQL. You can also:

• Ask the assistant (Command+I or Ctrl+I, or Chat) to write the query. You bring your own model provider. See How do I use AI chat?.
• Save a query from Explore and rerun it later. Saved queries keep version history.
• Open Query history to get back a SQL, PQL, or AI-generated query you already ran.

Share the Explore URL when you want someone else to land on the same table, time range, and query.

What is the difference between receivedAt and eventTime?

Use receivedAt in WHERE clauses. It is when RunReveal ingested the event, it is indexed, and it still finds events that arrived late.

eventTime is when the source says the activity happened. Use it in the SELECT list when a person needs the original timestamp. Filtering on it is slower and some sources leave it empty.

Scheduled detections should bound the window with receivedAt and the from and to parameters. See Queries.

What is rawLog, and when do I use it?

rawLog is the original payload. Normalized columns are for the fields you filter and group on. When a vendor field was not promoted, extract it:

SELECT JSONExtractString(rawLog, 'eventName') AS event_name
FROM logs
WHERE sourceType = 'webhook'
  AND receivedAt > now() - INTERVAL 1 HOUR
LIMIT 20

If you extract the same path often, add a custom view so the column exists at query time without rewriting stored events. Custom views are created under Settings → Custom Views. The table name is your workspace name, an underscore, then the view name.

Which other tables are in Explore?

Besides source logs, Explore has platform tables. The ones you will use first:

The full list, including source errors and health check results, is on Explore Logs.

How do I read a field inside actor or src?

actor and src are maps. Read a key by name:

SELECT actor.email, src.ip, src.country
FROM logs
WHERE sourceType = 'okta'
  AND actor.email != ''
  AND receivedAt > now() - INTERVAL 1 DAY
LIMIT 50

UEBA baselines only include events where the actor email is set. If a query by user returns nothing, check that the source's transform actually fills actor.email. The raw address may still be inside rawLog.

When should I create a custom view?

Create one when you keep extracting the same JSON path, or when you want a table scoped to one source. A custom view does not copy or rewrite events. It adds columns at query time. Create it under Settings → Custom Views. In Explore the name is your workspace name, an underscore, then the view name.

Use a source-specific table (okta_logs) when RunReveal already built one. Use a custom view for fields that table does not have. See Custom views.

How do I share what I found?

Copy the Explore URL. It keeps the table, the time range, and the query. To keep the evidence on an incident, use Add to Investigation on the results. Saved queries are for queries you will run again. They keep version history.

Pipelines

Do I need to build a pipeline?

No. Events that match no custom topic use the default pipeline, which writes to workspace ClickHouse. Add a topic and a pipeline when you want to drop noise, mask a field, sample a firehose, change retention, run Sigma, or copy events to a bucket you own.

Open Pipelines in the sidebar. Topics are evaluated top to bottom. An event that matches a topic does not also run through the other topics. See Pipelines.

How do I drop events I do not want?

Two tools, used for different jobs:

• A Filter is a reusable regex against the raw log. Attach the same filter to more than one pipeline, or apply it globally. Manage them under Sources → Data Filters. See Filtering.
• A Drop step lives on one pipeline. Use it for a single route, for example health checks on one webhook. See Dropping.

Both discard the event before storage. You cannot get it back. Put the step after any transform that the match depends on, and test the condition in Explore against data you already have before you drop the live stream.

Sample keeps a percentage instead of deleting everything. Use it for high-volume sources where a subset is enough. See Sampling.

How do I mask sensitive fields?

Add a Mask step to the pipeline. It can redact, hash, or partially mask a field before the event is stored. Put Mask before the Destination step. A value that reaches storage unmasked stays there until retention expires. See Masking.

How do I add context to an event?

Enrichments add fields from a lookup or a rule you write. RunReveal maintains a set of managed enrichments. Your own rules are custom enrichments. Both are in the sidebar under Enrichments.

In the pipeline, put Enrich after Transform and before Detect, so Sigma rules see the normalized fields. See Enrichments.

How do I send logs to my own storage?

Creating a destination does not send anything. You also add a Destination step on the pipeline.

1. Create the destination (another ClickHouse cluster, or S3, R2, GCS, or Azure).
2. Edit the pipeline and add a Destination step that selects it.
3. Add a second Destination step if the same event should also land in workspace ClickHouse.

RunReveal Backend is only the workspace ClickHouse. A failure on one destination does not cancel the others. See Destinations.

How do I keep some logs for less time?

Default retention is 550 days. A Set TTL step sets sourceTTL on matching events to anywhere from 1 to 550 days. It only affects events written to RunReveal Backend, so the pipeline still needs a Destination step. See Set TTL.

Why did my Sigma rule not run?

Sigma streaming runs inside the pipeline, on a Detect step. A pipeline without that step never evaluates Sigma rules for events on that topic. Copy the default pipeline, or order the steps Transform, Enrich, then Detect, then Destination. Detect by itself is not enough. See Pipelines.

What order should pipeline steps run in?

Top to bottom. A step only sees events that reached it.

1. Transform, so fields have stable names.
2. Enrich, so lookups land on those names.
3. Mask, if a later step or destination must not see the raw value.
4. Filter, Drop, or Sample, once you know the event is noise.
5. Detect, so Sigma runs on the normalized event.
6. Set TTL, if this traffic should expire sooner than 550 days.
7. Destination, at least one, or the event has nowhere to land.

Put Mask before Destination. Put Detect after Transform. A pipeline with only Detect does not store the event and does not normalize it.

What is a precondition?

A condition on a topic or a step that decides which events it applies to. A topic precondition might be "source type is webhook." A step precondition might be "event name matches a health check." Events that miss every custom topic use the default pipeline. Events that miss a step's precondition skip that step and continue down the pipeline. See Pipelines.

I edited a pipeline and a different source changed. Why?

Topics can share one pipeline. The editor asks you to unlock a shared pipeline before you save, because the change hits every topic that points at it. If only one source should change, copy the pipeline and point that topic at the copy.

Detections, signals, and alerts

What is a detection, a signal, and an alert?

All three result sets are queryable. detections is every returned row. signals and alerts are the split by whether a channel was configured. See Detections, signals, and alerts.

Should I write SQL or Sigma?

Use SQL when the question needs a count, a join, a baseline, or any window of history. The rule runs on a cron schedule over stored data.

Use Sigma when you want a single-event pattern checked as the event is ingested. You can build the rule in the UI (Detections → Create Detection → Streaming Detection) or upload Sigma YAML. RunReveal's engine is a Sigma superset. See Writing detections and Sigma streaming.

Most teams use both.

How do I create an alert?

1. Prove the events exist. Run the filter in Explore before you save a rule.
2. Create the detection. For SQL, include the schedule parameters so each run has a window:

SELECT
  actor.email AS user,
  src.ip AS source_ip,
  count() AS failed_count
FROM logs
WHERE sourceType = 'okta'
  AND eventName = 'user.session.start'
  AND eventOutcome = 'FAILURE'
  AND receivedAt >= {from:DateTime}
  AND receivedAt < {to:DateTime}
GROUP BY actor.email, src.ip
HAVING count() >= 5

3. Set a name, severity, description, and categories. A first schedule of every 5 minutes (*/5 * * * *) is a reasonable start. Leave notification channels empty.
4. Let it run, or run it once. Check signals.
5. When the rows are what you meant, edit the detection and attach a channel. The next match is an alert.

from and to are supplied by RunReveal on every scheduled run. You can add your own parameters (office IPs, an allowlist of accounts) under Detections → Query Parameters. See Writing detections.

How do I know a detection ran?

Query scheduled_query_runs. An empty error and a recent executionTime means the schedule fired. recordsReturned is how many rows matched.

SELECT queryName, executionTime, recordsReturned, error
FROM scheduled_query_runs
WHERE queryName = 'okta-failed-logins-by-ip'
  AND executionTime > now() - INTERVAL 1 DAY
ORDER BY executionTime DESC
LIMIT 20

If it ran and you expected a Slack message, look in signals first. No channel means a signal, not an alert. Failures are also listed under Detections → Errors.

What are managed detections?

The Detection Query Library is a catalog of SQL and Sigma rules RunReveal maintains. You subscribe instead of writing the rule.

1. Go to Detections → Detection Query Library.
2. Open a rule and read the description, severity, MITRE mapping, and which source types it needs.
3. Subscribe. Set notifications, parameters, and AI triage on the subscription.

Tier 1 rules are the high-signal set recommended for sources you have already connected. The library banner shows how many of those you subscribe to. View Unsubscribed lists the rest. Tier 1 subscriptions turn AI triage on by default where the pack is configured that way.

You can attach notification channels to a managed detection without cloning it. Clone when you need an editable copy of your own. Subscriptions show up next to your custom detections, and their results still land in detections, signals, and alerts.

Sigma managed rules are under Sigma Detection Library. See Detections.

What should I fill in besides the query?

How do I manage detections as code?

Write and tune in the UI. When the rule is stable, export it and review changes in git.

brew tap runreveal/runreveal
brew trust --formula runreveal/runreveal/runreveal
brew install runreveal
 
runreveal init
runreveal detections export -d ./detections/
runreveal detections sync -d ./detections --dry-run
runreveal detections sync -d ./detections

Rules created from the CLI stay view-only in the UI. Edit them in the repo and sync again. Managed detection packs can be synced from the public detection packs repository. See Detection as code.

How do I catch behavior that is unusual for that person?

There is no UEBA switch. Events that include actor.email are rolled up automatically into ueba_actor_hourly (counts, IPs, countries, event names, per hour). Write a SQL detection that compares a principal to their own baseline. See UEBA with actor baselines.

How do I tune a noisy detection?

Leave the notification channel off and read signals until the rows are worth a person's time. Then:

• Raise the threshold (HAVING count() >= 5 instead of 1).
• Exclude known-good actors or IPs with a query parameter so the exception is data, not a rewritten query.
• Narrow sourcenames on a Sigma rule so it runs on production only.
• Turn on Group alerts so one noisy run becomes one investigation.

Do not drop the underlying events just to quiet a rule. Dropping is permanent. Silencing a health check is the right tool when the noise is "this source is quiet on purpose," not when the detection logic is wrong.

What is the difference between subscribing and cloning a managed detection?

Subscribe turns on RunReveal's copy. The query stays the library rule, which you do not edit. You can still set channels, parameters, enabled state, and AI triage on the subscription.

Clone makes a detection you own. Edit the SQL or Sigma freely. It no longer follows the library copy. Clone when the rule is close but the environment needs a change you cannot express with a parameter.

You can attach channels to a subscription without cloning. See Notifications.

Can one detection look at the results of another?

Yes. signals and alerts are tables. A scheduled SQL detection can count high-severity signals for the same actor in a window and only then notify. Keep the first rule as a signal (no channel) and put the channel on the rule that decides it is worth paging. See Detections.

Notifications

How do I notify Slack, email, or on-call?

1. Go to Notifications → Channels → Add Channel.
2. Create the channel and send the test notification.
3. Edit the detection or managed-detection subscription and attach the channel.
4. Save. The next match notifies that channel.

A detection with no channel still records a signal.

Channels: email, Slack incoming webhook, Slack bot, Discord, Google Chat, PagerDuty, Splunk On-Call (VictorOps), Jira, Linear, incident.io, Tines, and a generic webhook. Templates control the message body. Notifications → History is the delivery log. See Notifications.

What is the difference between the Slack webhook, the Slack bot channel, and the Slack bot?

Three different things:

• A Slack incoming webhook channel posts an alert into one channel. You paste a webhook URL.
• A Slack bot notification channel posts an alert through the installed RunReveal app, with Block Kit formatting. You pick a channel. No webhook URL. This can be feature-gated. Contact RunReveal if you do not see it.
• The Slack bot (Settings → AI Settings → Slack bot) is for asking questions. People DM the bot or mention it. That is chat, not an alert channel. Each Slack user links their RunReveal account. See Slack bot.

How do I change the alert message?

Create a template under Notification Channels → Templates. Templates use Handlebars-style fields from the detection result (title, severity, rows, and so on). Assign the template on the channel or on the detection. Without one, the channel uses its default body. See Notification templates.

How do I open a ticket from an alert?

Add a Jira, Linear, or incident.io channel, then attach it to the detection the same way you attach Slack. One detection can have several channels, so a high-severity rule can page PagerDuty and open a ticket. Tines and a generic webhook are the path when the system you want is not in the list. See Jira, Linear, and Webhooks.

How do I tell whether a notification was sent?

Open Notifications → History. A row there means RunReveal handed the message to the channel. If history shows success and Slack is empty, the webhook URL or channel permissions are on the Slack side. If history has no row, the detection had no channel, the run returned no rows, or the run failed. Check signals versus alerts, then scheduled_query_runs.

The history is also available from the notification history API.

Investigations

How do I investigate an alert?

1. Open Investigations and create one (Command+Shift+I or Ctrl+Shift+I).
2. Attach the alert, the Explore query that explains it, the AI chat transcript, and a note on what you decided.
3. Add indicators (an IP, user, domain, or hash) so later investigations and the triage agent can find the same entity.
4. Share the investigation URL. Everyone with access sees one timeline.

Status changes and added artifacts are recorded with a timestamp and the person who made them. See Investigations.

Can an agent open the investigation for me?

Yes. AI triage is a setting on a detection. When an alert fires, RunReveal opens an investigation and runs the agent you assigned. Group alerts puts every alert from one detection run on a single investigation and a single triage run, which is what you want for a noisy rule.

Tier 1 managed detections enable triage by default where the pack is configured that way. Detection notes are the instructions the agent sees. They are not the same as notes you type on the investigation. See Agents and Automated investigations.

What can I attach to an investigation?

From the investigation page, or from Add to Investigation on the thing you are looking at:

• A note (Markdown)
• An indicator: IP, user, domain, hash, or similar
• A query, or a captured query result
• An alert
• A chat thread, or one message from it
• An external link
• A graph

Status changes and a closing resolution are added for you. Those system entries stay on the timeline. See Investigations.

What do the statuses mean?

Severity on the investigation (low through critical) is separate from the detection's severity. You can set both. Investigations → Metrics shows Detect, Respond, Investigate, and Resolve times for the workspace.

Who can delete an investigation?

Anyone who can edit investigations can add notes and artifacts. Deleting an investigation, including bulk delete, is an admin action. Closing it is the normal end of the work. Closing keeps the timeline. See Role-based access control.

AI

How do I use AI chat?

1. Go to Settings → AI Settings and add a provider: Anthropic, OpenAI, Google AI, or Amazon Bedrock. Google Vertex AI is available on request.
2. An admin sets the default model for new chats.
3. Open Chat, or press Command+I or Ctrl+I from any page. The assistant knows which page you are on.

Ask for something you can check: "Which users failed Okta login more than 10 times today?" or "Which sources sent the most events in the last 24 hours?" Queries run in your workspace. Copy SQL you trust into a detection or a dashboard. See Native AI Chat.

The Verify button on the AI settings page does not send tools. A model can pass Verify and still fail on a real chat. Try a real question in Chat.

What are agents?

Agents run on a schedule, query the workspace, and deliver a write-up to a notification channel. Use them for a morning summary, a weekly access review, or triage when an alert fires.

1. Open Agents and create one.
2. Write the prompt, pick a model, and set a cron schedule.
3. Choose the notification channel for the report.

You can silence an agent until a time you choose. The schedule remains. It does not deliver during the silence. Run history is under Agents → Run History. See Agents.

What is the difference between a prompt and a skill?

A prompt is a reusable template. It can take arguments ("summarize this user"). Prompts are shared by chat and by MCP clients.

A skill is a body of instructions an agent or MCP client loads when it needs them. Skills do not take runtime arguments. They show up under Agents → Skills when that feature is enabled for the workspace.

See Prompts and Agent skills.

Can I use Claude or Cursor instead of the in-app chat?

Yes. Connect them to RunReveal's MCP server. They can query logs and manage detections with your workspace login. The runreveal CLI can also expose that server. See Model Context Protocol.

An external MCP server is the opposite direction: your workspace calls another product's tools from chat and agents. See External MCP.

Does my log data leave the workspace?

Queries run in RunReveal. The model provider you configure receives the prompt and the tool results the assistant needs to answer, which can include rows from those queries. Pick the provider your policy allows (including Bedrock in your own AWS account). Chat and agent actions are written to the audit log. See Native AI Chat.

How do I ask a question from Slack?

Install the RunReveal Slack app under Settings → AI Settings → Slack bot, choose the bot's role, and have each person link their Slack user to their RunReveal account. Then DM the bot or mention it in a channel. The bot acts as the linked user, limited to both that person's permissions and the bot's role.

This is separate from a Slack notification channel, which only receives alerts. Mutating actions the agent wants to take from Slack ask for a confirmation. See Slack bot.

How do I give an agent a playbook?

Write an agent skill: a markdown instruction set with no runtime arguments, for a triage checklist or a detection-authoring guide. Agents, chat, and MCP clients can load the skills you mark visible. A prompt is the better fit when the text changes every run ("summarize this user"), because prompts take arguments.

Skills appear under Agents → Skills when the feature is on for the workspace. See Agent skills.

Dashboards and other tools

How do I build a dashboard?

1. Go to Dashboards → Graphs and create a graph from a SQL query.
2. Go to Dashboards → Create Layout, add panels, and place the graphs.

Use receivedAt with the dashboard time parameters so the chart follows the range picker. Visualization types include line, area, column, bar, and single metrics. See Dashboards.

The same SQL can feed Grafana or a Jupyter notebook if the team already lives there.

How do I query from code?

• CLI: runreveal after runreveal init. It runs queries, syncs detections, and calls the API. See Using the CLI.
• Logs API: HTTP SQL with the API token as basic auth (empty username). See Logs API.
• REST: the generated API reference. Pass the workspace id as a query parameter. Copy it from workspace settings.

What is a graph, a panel, and a layout?

A graph is one SQL query drawn as a chart or a number. A panel holds a graph and sets its size. A layout is the dashboard: the arrangement of panels. Build graphs first (Dashboards → Graphs), then place them (Dashboards → Create Layout). You can also ask Chat to draft the SQL for a graph. See Dashboards.

Can I use Grafana or a notebook instead?

Yes. The Grafana plugin uses RunReveal as a data source, including pre-built dashboards. The Jupyter package runs a query and returns a dataframe. Both authenticate with a workspace API token. In-app dashboards are enough when the audience already has a RunReveal login.

Data, retention, and deployment

Where does my data live?

Federated search is a fourth option for data you do not want to ingest. A federated view reads an S3-compatible bucket at query time. Files stay in the bucket. It is available on Pro and Enterprise, and it is not available for BYODB workspaces. Create it under Settings → Custom Views and choose external S3-compatible storage.

How long are logs kept?

550 days, unless a Set TTL step sets a shorter sourceTTL (1 through 550 days) on the events it matches. Dropped or filtered events are never stored. Disabling a source does not shorten retention of what is already there. UEBA hourly rollups use the same 550-day window.

Can I see who changed a source or ran a query?

Yes. RunReveal writes an audit event for API and UI actions. Query runreveal_audit_logs in Explore, or open the audit log view. Useful fields are actorEmail, eventName, readOnly, and responseError. Creating a source, inviting a user, subscribing to a managed detection, and creating a token each have their own event name. See Audit logs.

What is the difference between BYOC and BYODB?

BYODB means the logs you query sit in ClickHouse you run. The RunReveal app can still be the shared cloud. BYOC means the RunReveal services themselves (ingest, the query engine, the scheduler) run in your cloud. On-prem is the product in your own environment, outside that shared cloud. Federated search is available on Pro and Enterprise SaaS workspaces and is not available on BYODB. See Bring your own cloud.

Can I query data I do not want to ingest?

Yes, with a federated view. The files stay in an S3-compatible bucket (NDJSON, CSV, TSV, Parquet, or ORC). Explore and SQL detections query the view at read time. Nothing is copied into logs. Create it under Settings → Custom Views and choose external storage. It is slower than ingested data and depends on how the bucket is partitioned. See Federated search.

Troubleshooting

I connected a source and Explore is empty

1. Open the source's health check. A failed test usually means the credential, role, bucket notification, or allowlist is wrong.
2. Widen the time range. A new source only has events from when ingestion started, plus whatever backfill that source performs.
3. Check sourceType. It has to match the source you created.
4. For a webhook, confirm the sender got a success response. Without retries, a failed POST is gone.
5. For polling, wait through one poll interval after a successful test. Many sources poll about once a minute. Some are slower. The source page states the interval.
6. Open Sources → Source Errors and Sources → Transform Errors.

My detection never matches

1. Run the same filters in Explore without the schedule parameters. If that returns nothing, the rule does not match your data.
2. Check scheduled_query_runs for a non-empty error, and Detections → Errors.
3. Confirm the schedule has had time to fire.
4. For Sigma, confirm the pipeline that handles this source includes a Detect step, and that sourcetypes or logsource matches the source.
5. Look in signals if you have not attached a channel.

I expected a Slack message and only see a signal

The detection has no notification channel, or delivery failed. Edit the detection, attach a channel, and read Notifications → History. A health check with no channel behaves the same way: it records status and does not message anyone.

A pipeline change had no effect

Topics are evaluated top to bottom, and an event uses one topic. If a broader topic sits above the one you edited, your pipeline never sees the event. Reorder the topics. If the pipeline is shared, saving it changes every topic that points at it.

Queries are slow

Filter on receivedAt first. Prefer the source-specific table over logs when you know the product. Avoid functions on the columns you filter by. Pull unmapped fields from rawLog only when there is no normalized column. See Queries.

A health check flaps between healthy and alerting

The source is bursty, or the threshold is tighter than the real gap between batches. Raise the failure threshold so a single quiet interval does not page, widen the window, or lower the minimum count. Silence the check for a maintenance window. Silencing does not stop the evaluation. It stops the notification.

Someone signed in with SSO and cannot see the workspace

SSO only proves the email. They still need a workspace membership. If just-in-time provisioning is off, invite them. If it is on, confirm their email domain is one you registered and that the default role is the one you expect. IdP groups are not consulted. See Single sign-on.

An API token gets unauthorized

The token is scoped to the workspace it was created in, and to the role you assigned. Confirm the request uses that workspace id, the Authorization header is basic auth with the token, and the role includes the action (a CIBot token can edit detections and cannot edit sources). Generate a new token when the old one might have leaked. The previous value cannot be displayed again.

Related documentation

• Onboarding guide — Account through detection as code
• Sources — Catalog and ingest methods
• Pipelines — Topics, steps, and routing
• Explore Logs — Tables, saved queries, and the explorer
• Detections — SQL, Sigma, and the managed library
• Notifications — Channels, templates, and history
• Investigations — Timeline, artifacts, and triage
• AI Chat — Chat, agents, skills, and MCP
• Dashboards — Graphs and layouts
• Role-based access control — Roles and custom roles
• Glossary — Short definitions