Getting Started

This guide walks you through going from a downloaded VM image to your first DFIR investigation in under 30 minutes. You'll import the appliance into your hypervisor, complete the 5-step setup wizard, connect a data source like Microsoft Entra ID, Defender for Endpoint, Active Directory, log files, or PCAP — and run your first incident response workflow.

Prerequisites

Before you begin, make sure you have:

• A hypervisor installed (VMware Workstation/ESXi/Fusion, VirtualBox, Hyper-V, or Proxmox)
• The CICADA IR VM image file (.ova, .qcow2, or .vhdx depending on your platform)
• A valid CICADA IR license key — or use the free 14-day Professional trial built into the wizard, or continue with the free Community Edition
• Network access from the VM to your data sources (see Network Requirements)

Step 1: Import and boot the VM

Import the VM image into your hypervisor. For platform-specific instructions, see the Setup Guide.

Quick version for VirtualBox:

# Import the OVA
VBoxManage import cicada-ir-latest.ova

# Start the VM
VBoxManage startvm "cicada-ir" --type headless

The VM will boot and CICADA IR services start automatically. Allow 1–2 minutes for all services to initialise.

Step 2: Access the web interface

Find the VM's IP address from your hypervisor — it's also printed on the VM console at the boot login prompt. Then open your browser and navigate to:

https://<vm-ip-address>

You will see a certificate warning because the VM ships with a self-signed TLS certificate. Accept the warning to proceed. To replace the cert with your own, see the TLS Certificates section below — done entirely through the web UI, no shell access.

Step 3: Complete the setup wizard

On first access, the setup wizard runs through 5 steps in order:

1. EULA — review and accept the End User License Agreement.
2. License — choose one of three paths: paste a Professional or Enterprise product key (formatCICADA-{TIER}-S{seats}-{...}); start a 14-day free Professional trial (no key required); or continue with the free Community Edition. License keys are HMAC-signed and validate offline — no internet required for activation.
3. Admin user — create the initial local admin account: username (3-32 chars), email, display name, and a password of at least 12 characters. This is the user you'll sign in as from now on.
4. Network — the wizard verifies outbound connectivity to optional services (Ollama, threat-intel providers, cloud LLM endpoints) and lets you configure an outbound proxy if your network requires one. Internal traffic (LDAP, WinRM, on-prem Ollama) automatically bypasses the proxy.
5. Ready — you're redirected to the Splash screen with options to start a new investigation, resume one of the seeded examples, or import data.

Step 4: Configure your first data source

From the sidebar, click Sources (under Data Collection), then click Add Source. The most common starting point is Microsoft Entra ID:

1. Click Add Source in the top-right of the Sources page.
2. Select Microsoft Entra ID from the source list.
3. Enter your Tenant ID, Client ID, and Client Secret from the Azure app registration.
4. Click Test Connection to verify access.
5. Click Save. The source appears in the Configured Sources card with a green “Connected” badge.

What sources are available on each tier

Sources are grouped by license tier. The Community Edition already includes a usable IR toolkit; Professional and Enterprise add higher-licensing-cost integrations.

Community (free, included)

• Microsoft Entra ID — sign-in logs, audit logs, risky users, directory data
• Microsoft Defender for Endpoint — endpoint telemetry, detection alerts, advanced hunting
• Active Directory (on-prem) — LDAP queries, user/group data, security events via WinRM
• Log files — ingest .evtx, .log, .csv, .json dumps
• PCAP / wireless capture — packet-level analysis, link-type aware (Ethernet, 802.11, radiotap, SLL, etc.)
• Syslog · DNS logs · DHCP logs · Web access logs — log-based evidence ingestion

Professional

• CrowdStrike Falcon (Professional tier) — detection alerts, device data, IOC management
• Ubiquiti UCG (Professional tier) — gateway / network telemetry

Enterprise

• Microsoft 365 (Graph) — mail, OneDrive/SharePoint, Teams audit
• Microsoft Purview — data classification & DLP
• Sophos Taegis — XDR alerts
• Varonis, BigID — data-governance integrations

Enterprise also includes Coming-Soon integrations for SentinelOne, Splunk, Palo Alto Networks, Proofpoint, AWS CloudTrail, and Google Workspace.

Step 5: Create your first investigation

1. From the Splash screen (or the home button in the sidebar), click Start New Investigation.
2. Enter an Investigation Name (e.g. “Q1 2026 Incident Response”).
3. Set the Lookback Period — a slider from 7 to 90 days that bounds how far back the collectors pull.
4. If you have configured global sources, the modal lists them under Existing Sources Found — tick the ones you want to import for this investigation.
5. Optionally add Known Compromised Accounts upfront so the engine starts with a non-empty scope.
6. Click Create.

CICADA IR opens the investigation workspace and routes you to the Sources page where the 5-stage pipeline (Collect → Analyze → Correlate → Converge → Review) runs through to completion.

Step 6: Collect evidence

On the Sources page inside the investigation, click Run Investigation (Pipeline card). The collectors run against the connected sources for the selected lookback window. You can also upload evidence ad-hoc:

• Log files — drag-and-drop EVTX, JSON, CSV, or text logs onto the Log Files source card. Multi-file upload supported.
• PCAP — upload .pcap / .pcapng / .cap for packet analysis. Up to 3 PCAPs analyse concurrently; further uploads queue.

Sign-in logs, audit logs, endpoint telemetry, and detection alerts flow into the unified investigation timeline. IOCs are auto-extracted and (if you've configured threat-intel providers) enriched against VirusTotal, AbuseIPDB, Shodan, URLhaus, ThreatFox, and OTX AlienVault.

Step 7: Review and analyse

The investigation sidebar gives you several lenses on the same evidence:

• Dashboard — KPI rail (configured sources, uploaded files, events ingested, alerts, actions taken), recent activity, key findings.
• Timeline — every event in chronological order with severity badges (Low, Medium, High, Critical) and MITRE ATT&CK technique IDs. The “Why this severity” expander shows the engine's reasoning.
• Incidents (Professional tier) — hierarchical view of grouped kill chains, compromised accounts, and tactic flow (Persistence → Privilege Escalation → Defense Evasion etc.).
• Case Narrative (Professional tier) — auto-generated incident write-up plus the interactive Entity Graph that visualises relationships between users, devices, IPs, and files.
• LLM Assistant — natural-language Q&A over the investigation. Quick prompts for “Summarize IOCs”, “Build Timeline”, “Lateral Movement”, and “MITRE Mapping”. Available on every tier — runs on a local LLM by default; cloud LLMs (Anthropic, OpenAI, Google Gemini) are opt-in across all tiers.
• Evidence Store — search the raw normalised evidence with chain-of-custody.
• Playbooks (Professional tier) — guided multi-step IR workflows (e.g. Credential Compromise).
• Response Actions — queue and approve containment actions (block IP, disable account). Available on every tier.

Step 8: Generate a report

Reporting is a Professional-tier feature. Community Edition users can still review every finding in the UI; formal exportable reports require a Professional or Enterprise license (or an active 14-day trial).

1. Open Reports in the investigation sidebar.
2. The page lists 15 report types across three categories: Investigation (Executive Summary, Technical Report, MITRE ATT&CK Mapping, Attack Path Visualisation, Blast Radius), Compliance & Legal (NDB Assessment, Regulatory Submission, Legal Hold Package, Insurance Report, Affected-Files Listing), and Stakeholder reports.
3. Click Run on the report you want, or Generate All at the top.
4. When the badge flips to Ready, download in PDF, DOCX, HTML, JSON, or Markdown depending on the report.

AI-Enhanced report variants (full investigation context analysed by a local LLM) require a reachable local LLM — cards grey out with a “Local LLM required” badge when none is configured.

License activation

Activation is web-only — the appliance is a closed VM and does not expose SSH or a CLI. License keys are HMAC-signed and the appliance validates them offline by signature, so activation works without internet access.

Activating in the web UI

1. Open the CICADA IR web interface at https://<vm-ip>.
2. If setup is incomplete, the wizard's License step appears automatically. Otherwise navigate to Activation in the sidebar (under System).
3. Paste your license key into the input field.
4. Click Activate. The appliance verifies the HMAC and reads the embedded tier and seat count.

Free 14-day Professional trial

On a fresh appliance with no license key, the wizard offers a 14-day Professional trial. Click Start Trial; all Professional features (Reporting, Incidents, Playbooks, Case Narrative, Blast Radius, CrowdStrike, Ubiquiti UCG) unlock for 14 days. After the trial expires the appliance falls back to Community Edition unless you activate a key.

License tiers

Tiers are additive — each tier includes everything in the tier below. Source of truth: the pricing page.

Air-gapped activation

Because license keys are HMAC-signed and self-contained, no external call is required to activate them. On an air-gapped appliance: complete the EULA, paste the key in the License step of the wizard (or in the Activation page later), and click Activate. The appliance verifies the signature locally and reads the embedded tier and seat count from the key payload.

Checking license status

Open Activation in the sidebar (under System). The page shows the active tier, seat count, key prefix, expiry, and a Phone Home panel that reports whether the appliance can reach the licensing service for usage telemetry (optional — skipped silently in offline environments).

TLS certificates

CICADA IR ships with a self-signed TLS certificate for immediate HTTPS access. For production deployments, replace it with a certificate signed by your organisation's CA or a public CA. Certificate replacement is done through the web interface — no shell access required (and not possible: the appliance has no SSH).

Replacing with your own certificate

1. Obtain a certificate in PEM format from your internal CA, Let's Encrypt, or another provider. You'll need the certificate file (.pem or .crt) and the private key file (.pem or .key).
2. If you have intermediate CAs, concatenate them with the server certificate first, then intermediates, into a single .pem file before uploading.
3. In the web interface, navigate to Settings → General. Scroll to the TLS Certificate section.
4. Upload the certificate and private key files, then click Save. The appliance applies the new certificate automatically — no service restart needed.
5. Refresh your browser — the self-signed warning should now be gone.

Troubleshooting: if the upload fails, check the accepted formats shown on the upload page and verify the key matches the certificate. If the appliance doesn't pick up the new certificate, restart the VM from your hypervisor.

Next steps

• Network requirements — firewall rules, FQDNs, and ports
• Local LLM & AI Setup — Ollama, LM Studio, llama.cpp, or litellm on your network
• Troubleshooting — common issues and fixes