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 licence key, 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 is 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. You can do this through the web interface without 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 Licence Agreement.
2. License: paste a Professional or Enterprise product key (it starts with CICADA4-), or choose Continue with Community Edition. Licence keys are signed with Ed25519 and the appliance checks them offline. No internet connection is 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 licence 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): blocks and unblocks IP addresses on the gateway as a response action (it does not collect firewall logs). A UniFi console uses a self-signed certificate: paste its SHA-256 fingerprint into Certificate fingerprint when you configure the source.

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.
• AI Defender: evidence-grounded triage and response assistance. Explicit action requests resolve one exact live connector object and add it to the Response Actions approval queue. CICADA shows supporting integrity-linked evidence, uncertainty, scope, impact, reversibility, alternatives, protected-asset warnings, and whether the two-signal advisory benchmark was met. Missing signals or warnings do not discard a responder's request; AI Defender cannot approve or execute it.
• Evidence Store: search the raw normalised evidence with chain-of-custody.
• Playbooks (Enterprise tier): guided multi-step IR workflows (e.g. Credential Compromise).
• Response Actions: review, edit the rationale, approve, and execute containment actions such as block IP, disable account, and isolate endpoint. AI Defender-created actions always enter as pending recommendations, refresh their live provider target during IR-lead review, and retain a separate lifecycle audit. Available on every tier.

Step 8: Generate a report

Reporting needs a Professional orEnterprise licence. Professional generates theInvestigation reports; Compliance & Legal andStakeholder reports need Enterprise. Community users can still review every finding in the UI.

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.

Licence activation

Activation is web-only. The appliance is a closed VM and does not expose SSH or a CLI. Licence keys are signed with Ed25519, and the appliance checks the signature offline with a public key it holds, 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 licence key into the input field.
4. Click Activate. The appliance checks the key's signature and reads the tier, seat count and expiry date signed into it.

Professional trial

The appliance's licensing service supports a 14-day Professional trial, but nothing in the current interface starts it. If you need a trial, email sales@cicada-ir.ai.

Licence tiers

Each tier includes everything in the tier below. Source of truth: the pricing page.

Air-gapped activation

Because licence keys are 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 licence 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 and 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. Replace the certificate through the web interface. No shell access is needed or available because the appliance has no SSH.

Replacing with your own certificate

1. Obtain a certificate from your internal CA, Let's Encrypt, or another provider, either as PEM files (the certificate as .pem, .crt or .cer, and the private key as .pem or .key) or as one .pfx / .p12 file with its password. It needs an RSA (2048 bits or more) or ECDSA (P-256 or P-384) key, Server Authentication, and a Subject Alternative Name with the address your users type. See Certificate requirements.
2. If you have intermediate CAs and are uploading PEM files, add them to the certificate file. A PFX file usually holds them already.
3. In the web interface, navigate to Settings → General. Scroll to the TLS Certificate section.
4. Click Upload Certificate, choose PEM files or PFX / P12 file, select the files, enter the password if there is one, and click Upload. Read any warning the dialog shows before you close it.
5. Restart the VM from your hypervisor. The web server keeps serving the old certificate until it restarts.
6. Refresh your browser. The self-signed warning should now be gone.

Troubleshooting: if the upload is refused, the message says which requirement the certificate does not meet. If the web interface cannot be reached after the restart, see Web interface unreachable after uploading a certificate.

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