Configuring the appliance

Everything on this page is done from the VM console once and then from the web interface. The appliance has no SSH and no shell. If a step on this page seems to need one, you are on the wrong step.

First boot: the console network wizard

On the first boot the VM console opens a network wizard. It walks through these screens: hostname; DHCP or static; address and prefix length; gateway; up to three DNS servers; an optional search domain; a summary; the result.

The welcome screen waits 60 seconds. If nobody presses a key the appliance keeps DHCP and carries on. Keep DHCP is the focused button.
After a static address is applied the wizard waits up to 20 seconds for the address to come up and then asks Keep or Revert. If nobody answers within 90 seconds it reverts, including the hostname.
On Keep, and on every first boot, the appliance regenerates its self-signed TLS certificate for the new hostname and address. The certificate's names are the hostname, the short name, localhost, 127.0.0.1 and the address. A certificate you uploaded yourself is kept; first boot never replaces it. To replace it from the console, press [N] later (see Web interface unreachable after uploading a certificate).
To open the wizard again later, press [N] at the boot prompt. The prompt says Press [E] within 10 seconds for emergency recovery, [N] for network settings, any other key to skip.

The console banner then prints the appliance's IP address, which is what you need for the next step. It waits up to 45 seconds for DHCP and shows <awaiting DHCP> if no address has arrived by then; reboot or press [N] to set one.

Open https://<appliance-ip>. The browser warns about the self-signed certificate; accept it for now. Always sign in by IP address first, because the appliance answers to an IP address whatever else is configured (see allowed host names). A DNS name only works once it is on the allowed list or is the appliance's own hostname.

The setup wizard

The first visit runs a five-step wizard. Until it finishes, the appliance refuses every request except the wizard's own routes and /health.

EULA: accept the licence agreement.
Licence: paste a product key and press Activate, or Continue with Community Edition. See product key activation. A 14-day Professional trial exists in the licensing service, but nothing in the current interface starts it.
Admin user: username (3 to 32 characters), email, display name, password of at least 12 characters. This is the first and, until you add more, the only account.
Network: the appliance shows the outbound hosts it will need, each marked required or optional, and asks you to allow HTTPS to them. It does not probe them. The step also lets you set an outbound proxy and can generate a self-signed certificate for the hostname or FQDN your users will type plus the detected IP address. The private address ranges 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 always bypass the proxy, so domain controllers and a local Ollama host are never sent through it.
Ready: you land on the splash screen.

Getting Started has step-by-step detail of each step.

Allowed host names (Settings > General)

The appliance answers a request only when the name in the browser's address bar is one of these. The port is ignored and case does not matter.

Any IP address, v4 or v6. A DHCP change can never lock you out.
localhost.
The appliance's own hostname, as set in the console wizard, and that name with .local added.
A name an admin added under Settings > General > Allowed host names.

Anything else gets HTTP 400 with the page This appliance does not answer to the name <host>. Open it by its IP address, sign in as an admin, and add the name under Settings → General → Allowed host names.

At most 20 names. Each is a plain DNS name of up to 253 characters: letters, digits, hyphens and dots.
A scheme, port, path, wildcard or IP address is refused.
The change takes effect on the next request. No restart.
Every change is written to the security audit log with the admin's email, the old list and the new list.
Single sign-on builds its redirect address from the same rule, so add the name before you configure SSO.

Product key activation

Activation happens in step 2 of the wizard or later on the Activation page (under System). Activating needs the Manage licence and features permission (Admin by default).
It works offline. The key is signed and the appliance checks the signature locally with a public key it ships with. Nothing is sent anywhere. Current keys (format version 3 and later) are Ed25519-signed; version 4 keys also carry their expiry date. Older HMAC-signed keys are refused on a production appliance.
The key carries the tier and the seat count. The appliance reads both from the key.
A redeemed key is bound to the VM it was activated on (the hardware UUID, the machine id and the first network adapter's MAC address). A reboot, an IP change, a resize or a live migration do not change that. A clone, a replaced network adapter or a restore into a freshly created VM do: the appliance then reports This key was activated on a different machine. Enter the key again on this appliance. Entering the same key again re-binds it, and the re-bind is written to the security audit log.
If more than one key has been redeemed, the seat count comes from the most recently redeemed one. Redeeming a smaller key after a larger one lowers the seat count.
The Activation page shows the tier, seats, key prefix and expiry.

Outbound proxy (Settings > Proxy)

Fields: Enable Outbound Proxy, proxy host, port, username, password and Bypass Proxy (a comma-separated list). Saving sets the proxy for every connector and every threat intelligence provider at once; no restart. The password is stored encrypted and is never shown again. The form's default bypass list is localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16, and the appliance always adds those private ranges whatever you enter, so a domain controller or local LLM host on a private address needs no entry. Add public names that must not go through the proxy. The same settings are reachable from the wizard's Network step.

TLS certificate (Settings > General)

Upload Certificate takes either PEM files (a certificate file, .pem, .crt or .cer, Base-64 or binary DER, and its private key, .pem or .key) or one PFX / P12 file with its password, as exported from Windows. If a PEM key is encrypted, enter its password in the upload form. Intermediates can go in the certificate file in any order; the appliance puts the server certificate first.
The appliance writes the certificate and key in its own clean PEM format, never the bytes you uploaded, so text around the PEM blocks (a byte order mark, or the Bag Attributes lines OpenSSL adds when it exports a PFX) does no harm.
The web server keeps serving the old certificate until it restarts. After a successful upload the dialog says Certificate saved. Restart the appliance to start using it. Restart the VM from your hypervisor.
Generate self-signed makes a new self-signed certificate for a name and the appliance address, which is enough to stop the browser warning on a private name you trust.
The console wizard regenerates only self-signed certificates after a network change. If an uploaded certificate is in use, pressing [N] first asks whether to replace it with a self-signed one. The default answer is No.

Certificate requirements

The upload refuses a certificate that browsers would refuse, and nothing is changed. Each refusal says which rule failed:

Key type. RSA of 2048 bits or more, or ECDSA on P-256 or P-384. Browsers do not accept other key types for a web site. P-521 is refused too: Chrome and Edge fail the connection to a P-521 certificate with no way to continue.
Server Authentication. If the certificate lists Extended Key Usages, Server Authentication must be one of them. A certificate made for client authentication or code signing only, such as one from a Windows “Special Purpose” template, is refused because browsers refuse it with no way to continue. Ask your certificate authority for one with Server Authentication.
Key Usage. If the certificate lists Key Usages, it needs Digital Signature (or, for RSA, Key Encipherment).
Subject Alternative Name. The certificate must have one. Browsers ignore the Common Name, so a certificate without a Subject Alternative Name fails in every browser. See Put every name users type in the Subject Alternative Name.
Server certificate, not a CA. A certificate authority's own certificate is refused.
Dates. The certificate must already be valid and not expired. A certificate that starts in the future is often a sign the appliance clock is wrong.
Matching key. The private key must belong to one of the certificates in the file.
Encoding the web server can load. The serial number must be positive, and the public key must be in its standard form (not a compressed elliptic-curve point, not an RSA-PSS key). The appliance's web server cannot start with such a certificate. The appliance also loads every upload in its web server before saving it, and refuses the upload if the web server does.
Size. Each file must be 256 KB or smaller.

Address warning. If the certificate does not include the address in your browser's address bar, the upload is still accepted and the dialog lists the names the certificate does cover. Browsers will warn on any address that is not in that list, so sign in using one of those names, or get a certificate that includes the address users type.

Put every name users type in the Subject Alternative Name

The appliance's full name (FQDN), such as cicada.ad.example.com, must be in the certificate's Subject Alternative Name. Having it as the Subject name (the Common Name) is not enough. This is a browser rule, not a CICADA one: Chrome and Edge (since Chrome 58, 2017), Firefox (since Firefox 101, 2022) and Safari (since macOS 10.15 and iOS 13) read only the Subject Alternative Name when they check the name, and ignore the Common Name.

If the name in the address bar is missing from the Subject Alternative Name, Chrome and Edge show NET::ERR_CERT_COMMON_NAME_INVALID, even when the Common Name matches and the certificate chains to a root the computer trusts. For example, a certificate with the Subject name CICADA.ad.example.com and only CICADA in the Subject Alternative Name works at https://CICADA but fails at https://cicada.ad.example.com. Upper and lower case do not matter.

To check a certificate, open it in the browser and look at Details > Subject Alternative Name. List every name users will type:

the FQDN, for example DNS Name=cicada.ad.example.com
the short name, if anyone uses it, for example DNS Name=CICADA
the IP address, if anyone signs in by address, as an IP Address entry (an address entered as a DNS name does not match)

With Active Directory Certificate Services, add the names when you request the certificate: in the Certificates console enrollment, open the request's Properties > Subject, choose Alternative name type DNS, and add each name. The certificate template must allow the subject to be supplied in the request. Export the new certificate as a PFX with Include all certificates in the certification path selected, upload it, and restart the appliance.

Getting Started has the step-by-step version.

Users and roles (Settings > Users, Settings > Roles)

Every user has one role, and a role is a set of permissions that an admin can edit. CICADA starts with three roles: Analyst, IR lead and Admin. An admin can rename them, add more, and tick the permissions each one has on Settings > Roles. Admin always has every permission. The page Users and roles lists every permission and what each built-in role has by default.

When you create a user on the Users tab, the Role list starts on the default role for new users. An admin can pick any role. Someone who manages users but is not an admin sees only the roles they may give out.
Only active users count against the seat count. Disabling a leaver frees the seat.
A password reset by someone with Manage users (Admin by default) sets a temporary password that the user must change at their next sign-in; the appliance refuses everything else until they do.
Each user row has two key icons: Reset password and Personal access tokens. The Edit user form has a Require MFA for this user switch.
Someone with the Manage users permission can use the Users tab without being an admin, within limits. See delegating user management.

Multi-factor authentication

TOTP only: a six-digit code every 30 seconds from an authenticator app. No SMS, no hardware keys.
Each user enrols under Settings > Security > Personal two-factor authentication. Enrolment issues ten backup codes, shown once.
An admin sets the policy under Settings > Security > MFA policy: Choose Voluntary (no forced enrolment), Required for Admin only, or Required for [role] and every role above it. To require MFA for everyone, choose the role furthest left on the Roles page. See role order. Setting the policy needs the Set the MFA policy permission, which only Admin has. The rule is enforced by the server, not just the login screen: a user who must enrol is refused everything except the enrolment screens.
Re-enrolling, regenerating codes or turning MFA off asks for the current password and a current code. Someone with Manage users (Admin by default) can clear another user's MFA from the Users tab without either.
A sign-in through SSO does not ask for a code, but an MFA policy still applies from the next request.

Personal access tokens

For scripts and automation. A user whose role has Create personal access tokens (Analyst, IR lead and Admin by default) can create one under Settings > Security > Personal access tokens.

The token starts with cicada_pat_ and is shown once, at creation. It is stored hashed.
Default expiry 90 days, at most 365, or never.
Send it as Authorization: Bearer cicada_pat_.... The caller is the token's owner, with that user's permissions at the time of the call.
A password change, an admin password reset, disabling the user, or the user signing out of the browser ends every token that user has.
Someone with Manage users (Admin by default) can list and revoke another user's tokens from the key icon on the Users tab.

Single sign-on (Professional tier)

SAML 2.0 and OpenID Connect are both supported, under Settings > Security > Single sign-on. The high-level shape:

OIDC needs the issuer URL (for Entra ID, https://login.microsoftonline.com/<tenant-id>/v2.0), a client ID, a client secret and the scopes (default openid email profile; add groups if you will map roles from a groups claim). SAML needs the IdP entity ID, the IdP SSO URL and the IdP signing certificate.
After you save a provider, the card shows the Redirect URI (OIDC) or ACS / callback URL (SAML) to paste into your identity provider. It is built from the name the browser used, so add that name under allowed host names first.
Role mapping: name the claim that carries groups (for example groups), then map claim values to roles. When a user matches several mappings the role furthest right on the Roles page (the highest) wins. A user with no match gets the provider's default role. With a role claim set, the role is re-read at every sign-in.
First sign-in: the appliance matches the identity provider's subject to an existing account; failing that it matches on email, but never takes over an admin account and only when the provider says the email is verified; failing that it creates an account with the mapped role, or the provider's default role if none matches. An admin can link or unlink an account from the Users tab by hand.
An account linked to SSO signs in through the identity provider only. It cannot use a local password. See SSO roles and sign-in.
Deprovisioning a user in the identity provider does not disable their CICADA account. Disable it on the Users tab.

Backups (Settings > General > System Backup & Restore)

Professional tier. Needs the Back up and restore permission, which only Admin can have.
Create Encrypted Backup asks for a password of at least 12 characters and downloads a .cicada-backup file to your browser. The archive is not kept on the appliance; it only records the time of the last backup. So there is no schedule and no retention to manage. Keep the file and the password somewhere else. There is no way to recover a backup without its password.
The archive holds settings, the system database, the credential store with its key, the sign-in secrets file (so restored passwords still work), appliance-wide connector settings, the investigation data and the uploaded evidence files. It does not hold the TLS certificate, trial state, or the signing key for evidence chains, which lives outside the data directory.
Restore from Backup checks the archive before touching anything, refuses a restore that would leave no account able to sign in, and merges the rest over the current data. The result ends IMPORTANT: Restart cicada-backend so the restored state.json, system.db, and secrets.db are re-read. On the sealed appliance the way to do that is to restart the VM from your hypervisor.
Restoring onto a different VM: passwords carry over; the product key is refused because it is bound to the old machine, so enter it again; evidence chains verify only if the signing key the result names is configured on the new appliance, which is a support task. The result reports the chain outcome and the missing key id.