Skip to content

Getting Started

Quick start

Choose one option. Windows and Linux users should start with the release download. Docker suits servers and teams. Building from source is for developers.

Download dfir-companion-<version>-win-x64.zip from the latest GitHub release, extract it, and run dfir-companion.exe. No Node.js required. Cases and an optional .env live next to the EXE.

The EXE is not code-signed, so Windows SmartScreen warns on first run. Check the zip against SHA256SUMS.txt from the same release first: run Get-FileHash dfir-companion-*-win-x64.zip -Algorithm SHA256 and compare the hash with the matching line.

choco install dfir-companion

Installs the same portable Windows build and bundles the capture extension on disk for offline "Load unpacked". Data is stored in %LOCALAPPDATA%\DFIR-Companion.

Download dfir-companion-<version>-x86_64.AppImage from the latest GitHub release, make it executable, and run it.

chmod +x dfir-companion-*-x86_64.AppImage
./dfir-companion-*-x86_64.AppImage

Set DFIR_ENV_FILE to point to your .env if you need the config file outside the AppImage mount.

The AppImage is not code-signed. Verify it against SHA256SUMS.txt from the same release: run sha256sum -c SHA256SUMS.txt --ignore-missing in the download folder.

The simplest way is Docker Compose with the prebuilt image. You need only the compose file, not the whole repo:

mkdir dfir-companion && cd dfir-companion
curl -fsSLO https://raw.githubusercontent.com/hasamba/DFIR-Companion/master/docker-compose.yml
docker compose pull && docker compose up -d --no-build

--no-build stops Compose from falling back to a source build, which fails without the repo. Cases persist in ./cases, server sets in ./server-sets and team-mode accounts in ./auth, beside the compose file. Everything else the server saves persists in ./data: the Settings file (companion.env, holds API keys), dashboard views, report templates, tagger rules, notifications, Sigma rules and logs. Back up all four folders.

Upgrading from a compose file without ./data? Your saved settings are still inside the running container. The first docker compose up -d with the new file recreates the container and deletes them. Copy them out first, while the old container still runs:

mkdir -p data
for d in companion.env dashboard-views report-templates tagger notifications \
  templates incident-types whitelist tools; do
  docker cp -q dfir-companion:/data/$d data/
done

A "Could not find the file" line only means that you never saved that item. Then download the new docker-compose.yml and run docker compose up -d.

To run the image without Compose:

docker run -p 127.0.0.1:4773:4773 \
  --security-opt no-new-privileges:true \
  --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE \
  --cap-add FOWNER --cap-add SETGID --cap-add SETUID \
  -v /your/data:/data \
  -v /your/cases:/data/cases \
  -v /your/server-sets:/data/server-sets \
  -e DFIR_CASES_ROOT=/data/cases \
  -e DFIR_ALLOW_UNAUTHENTICATED_REMOTE=container-loopback-proxy \
  ghcr.io/hasamba/dfir-companion:latest

Dashboard is then at http://127.0.0.1:4773/dashboard. Mount all three volumes. The server keeps the server sets (IRIS / Timesketch / Velociraptor connections, keys encrypted) in a server-sets folder beside the cases folder, and the Settings file, dashboard views, report templates, tagger rules, notifications and logs directly in /data. Without those mounts, they are lost when the container is removed.

The --security-opt and --cap-* flags are optional hardening: the container keeps only the permissions it needs to hand your case folder to an unprivileged user, and the server can never get root back. The bundled docker-compose.yml sets the same options.

For developers, or if you want to customise prompts. Most users should pick another tab.

  1. Install Node.js 22.19 or later (required by the indexed case store).
  2. Clone or download the repository.
  3. Run: 
    cd companion
npm install
cp .env.example .env
npm run dev
  4. The server starts on http://127.0.0.1:4773. Open the dashboard at http://127.0.0.1:4773/dashboard.

Port already in use?

If the dashboard says "companion offline", the server is not running. If you see EADDRINUSE, another instance is already running — just use that one, or free the port: 

# Windows
Get-NetTCPConnection -LocalPort 4773 -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

# Linux / macOS
kill $(lsof -ti tcp:4773)
# Linux only, if lsof isn't installed
fuser -k 4773/tcp

First-Run Setup Wizard

When you open the dashboard for the first time with no AI provider configured, a Setup Wizard appears automatically. It walks you through everything in a guided, multi-step flow:

Step What you configure
AI analysis Provider (OpenAI, Anthropic/Claude, OpenRouter, Gemini, Ollama, LiteLLM), model name, API key. A "Save & test" button confirms the key works before you proceed.
Presidio PII scan Optional analyzer URL, confidence floor and timeout for the extra PII detector in front of the AI. Save, then restart — these keys are read at startup.
Velociraptor API config path for hunt-and-collect integration. The path and GUI URL go into the default server set; the binary path stays global.
DFIR-IRIS URL + key for bidirectional case sync. Saved to the default server set.
Timesketch URL + credentials to push the timeline to Timesketch. Saved to the default server set.
Notion API token for exporting cases to Notion pages.
ClickUp API token for pushing the response playbook to ClickUp.
Threat-intel enrichment API keys for VirusTotal, AbuseIPDB, Hunting.ch, CrowdStrike, Shodan, MISP, YETI, OpenCTI, RockyRaccoon, GeoIP.
Customer exposure Keys for LeakCheck, HIBP, DeHashed.
Push ingest Token for the webhook endpoint.
NSRL Path to a known-good hash database.
Notifications Slack/Teams/Mattermost/Discord webhook, or a Telegram bot (token + chat ID), for alert notifications.

Tip

Everything is optional. You can dismiss the wizard and add things later from Settings. You can reopen the wizard any time from Settings → General → Open setup wizard.

Installing the Browser Extension

The capture extension lets you screenshot any browser tab with a keyboard shortcut.

Install directly from the Chrome Web Store — no developer mode needed:

DFIR Companion — Evidence Capture & Push

Click Add to Chrome, confirm the permissions, and the extension icon appears in your toolbar.

For Chocolatey installs (extension is pre-built on disk) or if building from source:

  1. In Chrome (or any Chromium browser), go to chrome://extensions/.
  2. Enable Developer mode (top-right toggle).
  3. Click Load unpacked and select the extension/dist/ folder (run npm run build inside extension/ first if building from source; Chocolatey installs it pre-built on disk).
  4. The extension icon appears in the toolbar.

Needs Firefox 140 or later. There is no Mozilla Add-ons listing yet, so it loads as a temporary add-on:

  1. Download dfir-capture-extension-firefox-*.zip from the latest GitHub release and unzip it. (Building from source instead? Run npm run build:firefox inside extension/ — it writes the same files to extension/dist-firefox/.)
  2. In Firefox, go to about:debugging#/runtime/this-firefox.
  3. Click Load Temporary Add-on… and select the manifest.json inside the unzipped folder — the manifest file, not the folder. (Chrome asks for a folder here; Firefox asks for the manifest inside it.)

What it collects, since a temporary load never asks

Firefox shows its data-collection notice only for a signed add-on installed normally; about:debugging grants everything silently. The extension declares browsing activity (a capture carries the tab's URL and title) and website content (the screenshot, and the rows a Push scrapes). The extension sends it to the companion address you configure and nowhere else; what that companion forwards afterwards — a vision model reads the screenshots, AI synthesis reads the rows, enrichment queries reputation services — is the companion's own configuration.

  1. The extension icon appears in the toolbar.

Temporary add-ons don't survive a restart

Firefox removes a temporary add-on when the browser restarts, so repeat step 3 each session. That is how unsigned add-ons work — the release zip is not signed by Mozilla, so it cannot be installed permanently until there is an AMO listing. Nothing you captured is lost either way: evidence is sent to the Companion server as you capture it and lives in the case, not in the browser.

Keyboard shortcut: Ctrl+Shift+S (Windows/Linux) toggles capture mode on/off. When capture is active, a floating push button appears on the page.

Next Steps