Getting Started

This guide walks you through going from a downloaded VM image to your first investigation in under 30 minutes.

Prerequisites

Before you begin, make sure you have:

• A hypervisor installed (VMware Workstation/ESXi, VirtualBox, Hyper-V, or Proxmox)
• The CICADA IR VM image file (.ova, .qcow2, or .vmdk depending on your platform)
• A valid CICADA IR license key (or start a free trial)
• 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

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 install your own certificate, see the TLS Certificates section below.

To find the VM's IP address, log in to the VM console with username cicada-admin and run:

ip addr show | grep inet

Step 3: Complete the setup wizard

On first access, the setup wizard will guide you through initial configuration:

1. Accept the EULA — Review and accept the End User License Agreement
2. Activate your license — Enter your product key, start a free trial, or continue with the Community edition
3. Network check — The system verifies outbound connectivity to your configured services
4. Ready — You are redirected to the main dashboard

Step 4: Configure your first data source

Navigate to Settings > Data Sources and configure at least one data source. The most common starting point is Microsoft Entra ID:

1. Click Add Data Source
2. Select Microsoft Entra ID
3. Enter your Tenant ID, Client ID, and Client Secret
4. Click Test Connection to verify access
5. Click Save

Supported data sources include:

• 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
• CrowdStrike Falcon — Detection alerts, device data, IOC management

Step 5: Create your first investigation

1. Click New Investigation from the main dashboard
2. Enter a name and description (e.g., "Suspicious login activity — John Smith")
3. Select the investigation type (e.g., Compromised Account, Malware, Data Exfiltration)
4. Click Create

CICADA IR will open the investigation workspace with the guided workflow panel.

Step 6: Collect evidence

In the investigation workspace:

1. Navigate to the Evidence Collection tab
2. Enter the user principal name, hostname, or IP address you want to investigate
3. Select which data sources to query
4. Click Collect

CICADA IR will pull sign-in logs, audit logs, endpoint telemetry, and detection alerts into your investigation timeline.

Step 7: Review and analyse

• Timeline view — See all events in chronological order across all data sources
• Entity graph — Visualise relationships between users, devices, IPs, and files
• AI Analysis — Click Analyse with AI to get an LLM-generated summary of findings, identified attack patterns, and suggested next steps

Step 8: Generate a report

When your investigation is complete:

1. Navigate to the Reports tab
2. Select the report type (Executive Summary, Technical Report, IOC List, and more)
3. Click Generate
4. Download the report as PDF or Markdown

License activation

Activating via the web UI

1. Open the CICADA IR web interface at https://<vm-ip>
2. On first access, the license activation screen appears automatically
3. Paste your license key into the input field
4. Click Activate

Activating via the CLI

# SSH into the VM
ssh cicada-admin@<vm-ip>

# Activate the license
cd /opt/cicada
.venv/bin/python -m cicada.licensing.activate --key "YOUR-LICENSE-KEY-HERE"

License tiers

Offline activation (air-gapped environments)

For environments without internet access:

1. Generate an activation request from the VM:

   cd /opt/cicada
   .venv/bin/python -m cicada.licensing.activate --offline --key "YOUR-LICENSE-KEY-HERE"

2. Transfer the generated activation-request.json file to a machine with internet access
3. Email the file to licensing@cicada-ir.ai
4. You will receive an activation-response.json file
5. Transfer the response back to the VM and apply it:

   .venv/bin/python -m cicada.licensing.activate --offline-response /path/to/activation-response.json

Checking license status

cd /opt/cicada
.venv/bin/python -m cicada.licensing.status

Or in the web UI, navigate to Settings > License.

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.

Replacing with your own certificate

1. Obtain a certificate in PEM format from your internal CA, Let's Encrypt, or another provider
2. Upload to the VM:

   scp your-cert.pem cicada-admin@<vm-ip>:/tmp/cert.pem
   scp your-key.pem cicada-admin@<vm-ip>:/tmp/key.pem

3. Install the certificate:

   ssh cicada-admin@<vm-ip>
   
   # Back up existing certificate
   sudo cp /opt/cicada/data/tls/cert.pem /opt/cicada/data/tls/cert.pem.bak
   sudo cp /opt/cicada/data/tls/key.pem /opt/cicada/data/tls/key.pem.bak
   
   # Install new certificate
   sudo cp /tmp/cert.pem /opt/cicada/data/tls/cert.pem
   sudo cp /tmp/key.pem /opt/cicada/data/tls/key.pem
   
   # Set correct permissions
   sudo chmod 644 /opt/cicada/data/tls/cert.pem
   sudo chmod 600 /opt/cicada/data/tls/key.pem
   sudo chown cicada-admin:cicada-admin /opt/cicada/data/tls/cert.pem /opt/cicada/data/tls/key.pem
   
   # Clean up
   rm /tmp/cert.pem /tmp/key.pem

4. Restart services:

   sudo systemctl restart cicada-backend
   sudo systemctl restart cicada-frontend

Certificate chain

If your certificate requires intermediate CA certificates, concatenate them:

cat your-cert.pem intermediate-ca.pem > /opt/cicada/data/tls/cert.pem

Order: server certificate first, then intermediate certificates.

Self-signed with custom hostname

openssl req -x509 -newkey rsa:4096 \
  -keyout /opt/cicada/data/tls/key.pem \
  -out /opt/cicada/data/tls/cert.pem \
  -days 365 -nodes \
  -subj "/CN=cicada-ir.yourcompany.com/O=Your Company/OU=Security Operations" \
  -addext "subjectAltName=DNS:cicada-ir.yourcompany.com,IP:<vm-ip>"

Next steps

• Review network requirements for firewall whitelisting
• Troubleshooting if you run into issues