Dashboard Sync

Show the cases of other DFIRe installations on the Dashboard of one installation, beside its own.

How it works

Dashboard Sync lets one DFIRe installation read the Dashboard of other installations. It is not a mirror for backup, failover or high availability. The installation that reads keeps only what the Dashboard cards show, so it cannot take over from an installation that fails. For backups, see Backup and recovery.

A service provider can run one DFIRe installation for each customer and one for its own security operations center (SOC). The SOC installation is the receiving installation: it shows the cases of the others. Each customer installation is a sending installation: it lets the SOC installation read its cases. Analysts on the receiving installation see the cases of every sending installation on their own Dashboard. One click opens a case on the installation that holds it.

  • One way. The receiving installation pulls. A sending installation never contacts it, holds no credential for it and cannot change anything on it. The receiving installation cannot change anything on a sending installation either.
  • The Dashboard only. The receiving installation shows what the sending installation's Dashboard shows a reader who sees every case. Analysts open a case on the sending installation to work on it.
  • Point to point. A sending installation serves its own cases, never cases it receives from another installation. To see the cases of two sending installations, add both.

Any licensed installation can send, receive, or both. Both sides are in Settings → Dashboard Sync. Send Dashboard data to remote system configures the sending side, and Receive Dashboard data from remote system configures the receiving side.

Send Dashboard data to remote system

A superuser on the sending installation does this.

  1. Open Settings → Dashboard Sync

    Under Send Dashboard data to remote system, a badge shows whether sending is On or Off.

  2. Select Set up sending

    DFIRe issues a sync token that starts with dfire_sy_ and shows it once. Copy it and give it to the administrator of the receiving installation through a secure channel.

A sending installation has one token. Every receiving installation that pulls from it uses the same token, and they share its limit of 120 requests a minute.

Token last used shows the time and the address of the latest request with the token. Regenerate token replaces the token, and the old one stops working at once. Stop sending deletes it. Either way, every receiving installation loses access on its next pull and removes its copies of your cases. After a regeneration, a receiving installation pulls again only when its administrator enters the new token. If the receiving installation stopped pulling in the meantime, saving the new token starts the pulls again. See The circuit breaker.

The audit log records each of these actions and every failed attempt to use a token. After ten failed attempts from one address within five minutes, DFIRe blocks that address for ten minutes.

What a receiving installation gets

Sending exposes every case on the sending installation, in every status. For each case the receiving installation gets what a Dashboard card shows:

  • the case number, the external reference, the title and the first 300 characters of the description
  • status, severity, mode, playbook, phase, incident category, outcome verdict, project name and tags
  • the names and usernames of the case team, the email address of the lead investigator and the name of the person who acknowledged the case
  • open actions per assignee email address and the number of chat messages
  • counts of evidence, files and indicators
  • the dates of creation, acknowledgement, resolution, closing and archiving
  • SLA targets, SLA pauses and compliance timers

It also gets the installation ID, organization name, release version, application base URL and retention settings of the sending installation. It gets no notes, evidence, files, chat messages or indicators. The token opens nothing else: it gives no access to the rest of the API and no way to sign in.

Receive Dashboard data from remote system

A superuser on the receiving installation does this. Each sending installation it pulls from is a Dashboard Sync Sender, or sender for short, in the Dashboard Sync Senders list.

  1. Open Settings → Dashboard Sync

    Under Receive Dashboard data from remote system, select Add sender.

  2. Enter the address and the token

    Enter the address of the sending installation, such as https://dfire.customer-a.example. DFIRe refuses loopback and link-local addresses and the names of this installation. Private network addresses work, so a sending installation on your internal network or behind a tunnel can connect.

  3. Leave Require HTTPS on

    Turn it off only for a sending installation that serves DFIRe without TLS on a network you trust, such as a lab. The receiving installation then accepts an http:// address, and the token and the cases travel unencrypted. The settings page shows a warning for such a sender.

  4. Leave Verify TLS certificate on

    Turn it off only when the receiving installation cannot verify the certificate of the sending installation, for example a self-signed one. Without verification, anyone in the network path can impersonate the sending installation and capture its token.

  5. Select Add sender

    Before it saves, DFIRe reads a first page from the sending installation. The save fails and names the reason when the sending installation does not answer or rejects the token. It also fails when the sending installation has a read-only license, or serves a feed version this installation does not support.

The first successful save records which installation the address leads to. Every later pull must reach the same installation, so nobody can move an address to another installation unnoticed. A save also fails when the address leads to this installation, or to an installation that is already in the list.

Turning on Dashboard Sync Enabled for a sender runs the same check. So does a change to the address, the token or Verify TLS certificate on an enabled sender. A save that turns Require HTTPS on fails while the address still starts with http://. Disabling or deleting a sender needs no check, so it works even when the sending installation no longer answers. Either one removes the cases of that sender from the Dashboard at once.

DFIRe stores the token encrypted and never shows it again. Settings exports carry no senders and no sync token.

Sending installations behind a firewall

The receiving installation needs a network path to the address of the sending installation. A sending installation behind a firewall can open that path outbound, through a VPN or a tunnel. The receiving installation still authenticates with the token over that path. DFIRe does not ship a tunnel.

The address the receiving installation pulls from can differ from the address analysts open cases at. Links on the Dashboard use the Application base URL from the single sign-on settings of the sending installation, when that is an HTTPS address. An HTTP address also counts when the sender has Require HTTPS off. Otherwise links use the address the receiving installation pulls from. See Single sign-on.

Pulls and health

The receiving installation pulls from each enabled sender once a minute. Sync now on the Dashboard starts a pull at once, at most once every ten seconds for each sender. A sender never has two pulls at the same time.

A pull reads the whole feed. Only a complete pull replaces what the receiving installation holds, so a pull that fails halfway changes nothing. A case deleted on the sending installation disappears from the receiving installation with the next complete pull.

In the Dashboard Sync Senders list, each sender shows the last error and its time. A Stale badge marks a sender whose cards are stale, and Stopped marks an open circuit.

When a sending installation stops answering

  • Access withdrawn. The receiving installation deletes its copies of the cases at once when the sending installation rejects the token or has stopped sending. The same applies when the address has no feed, or when the license of the sending installation is read-only.
  • Other failures. After a timeout, a network error or a server error, the cards stay. Three minutes after the last complete pull, they show as stale, with the time of that pull. At five minutes they disappear. The next complete pull brings them back. When the sending installation answers that it receives too many requests, the next pull waits for the time it asks for, up to one hour.

The circuit breaker

After ten failed pulls in a row, the receiving installation stops pulling from that sender. Pulls from the other senders continue. The Dashboard shows a warning that names the sending installation to everyone who sees remote cases, even when none of its cases are left. A superuser starts the pulls again with Reset on the sender in Settings → Dashboard Sync → Receive Dashboard data from remote system. The audit log records the reset. Saving a new token or address on an enabled sender also starts the pulls again when the check succeeds. Disabling or deleting the sender also removes the warning, and enabling it again starts the pulls after the check.

Read-only license

Sync stops on either side when its license is read-only. A read-only sending installation refuses every receiving installation, and they delete its cases. A read-only receiving installation pulls nothing, and its copies disappear five minutes after the last pull.

Who sees remote cases

On the receiving installation, the cases of sending installations are remote cases. They need two permissions. core.view_case is the permission every role that reads cases has. core.view_remotecase, Remote cases in the role editor, covers the cases of every sending installation. It adds no local cases: a reader with both still sees only the local cases their own access allows. core.view_all_cases widens local access only and gives no remote cases. Archived remote cases also need core.view_archived_cases, as archived local cases do. The chat message count on a remote card needs core.view_casechatmessage. Superusers see everything.

No shipped role has core.view_remotecase. Add it to the roles that should see remote cases. See Users and roles.

Only superusers configure senders and reset a circuit. Readers with remote access see the name, health and filter options of each sending installation, and can use Sync now.

Analyst accounts on the sending installations

Analysts open remote cases on the sending installation, so each analyst needs an account there. Single sign-on creates it on the analyst's first click. See SOC analysts on sending installations.

What stays local

Remote cases appear in the case list, counts and filters of the Dashboard. See Cases from other installations. Their cards and table rows show each tag from the sending installation that follows the case tag rules. The Tags filter and Search cases match those tags as they match local ones.

Everything else on the receiving installation shows local cases only. This includes the Daily Summary, tag suggestions, the Projects tab and project pages, Analytics, global search, the MCP server, Slack and exports. Remote cases start no automation, webhook, notification or SLA alert on the receiving installation. Each sending installation sends its own.

Task workers

Pulls run on the task service, which also runs every other background job. Its number of workers sets how many jobs run at once. The default is 2. Set it with DFIRE_Q_WORKERS in .env:

DFIRE_Q_WORKERS=4

Use a whole number of 1 or more. With any other value, the task service does not start. Then apply it with this command, which recreates the task container. A restart keeps the old value.

docker compose up -d --wait

Start with 4 on a receiving installation. We measured one that pulls from 20 sending installations, two of them slow and one not answering. With 500 cases on each sending installation and 2 workers, one minute's pulls took up to 45 seconds. They kept the workers busy 59 percent of the time, and backups, notifications and other jobs waited. With 4 workers the same pulls took 24 seconds, set by the slowest sending installation, and used 29 percent. With 2,000 cases on each sending installation, 2 workers fell behind and 4 workers kept up.

Consider 6 only when your sending installations hold several thousand cases each or answer slowly, and the host has memory and database connections to spare. Each worker is a process and takes memory. More workers do not replace the circuit breaker: a sender that keeps failing still stops after ten pulls.

Upgrades, installation and backups

Upgrade the receiving installation first

A sending installation keeps serving a feed version that the receiving installation understands. A newer receiving installation also reads what an older sending installation serves. When a sending installation runs a later DFIRe release than the receiving installation, its sender shows Incompatibility risk in Settings → Dashboard Sync → Receive Dashboard data from remote system. Sync keeps working, but upgrade the receiving installation to stay ahead.

Install each sending installation fresh

Every installation has its own installation ID. Do not build a sending installation by restoring the backup of another installation. The copy carries the same installation ID, which the license also uses. A receiving installation refuses a second sender for an installation ID it already knows.

Backups

A database backup of the receiving installation includes its senders and the remote cases it holds. After a restore, ordinary pulls replace the restored cases, and a withdrawn token deletes them. If the sending installation does not answer, they disappear five minutes after the last pull the backup recorded.

Restoring a sending installation from an older backup brings back the sync token that was valid then. This applies even if someone regenerated the token or stopped sending later. Regenerate the token after such a restore to keep the old one revoked.