Skip to main content

What Cymph uses it for

Cymph connects to a DFIR-IRIS instance to read cases and users, and to push playbook steps into a case as tasks. This connector performs both read operations (listing cases and users) and write operations (adding tasks to a case).

Requirements

API token setup

Every DFIR-IRIS user is issued an API key. To find it, log in to the DFIR-IRIS web interface and open My Settings (left panel, under your username). Copy the API key shown there. If the key is ever exposed, use the Renew option to generate a new one.

Permissions

A DFIR-IRIS API key inherits the permissions of the user it belongs to, so use a token from a user account that has:
  • Access to the cases you want Cymph to read and push tasks into (case list and task creation).
  • Administrative rights, if you want Cymph to list all users when assigning tasks — the user-list endpoint is a management operation.
For a full-featured integration, an account with administrative privileges is the simplest choice; for least privilege, ensure at minimum the account has access to the relevant cases.

What Cymph reads and writes

All calls are made against the configured instance URL with the API key as a bearer token. Reads. Cymph only lists cases and users so you can choose where the tasks go and who owns them. It does not read case contents, existing tasks, notes, assets or IOCs. Writes. Deploying a playbook creates tasks in the case you select, one per action step. Start, parallel and end steps structure the workflow and create nothing. Each task is populated as follows: Only steps with manual commands can be deployed. A playbook containing any other command type, or a nested playbook, fails translation before anything is written.
Deploying the same playbook into the same case again creates a second set of tasks. Cymph does not look for tasks it created earlier, and it never updates or deletes tasks. The deploy history entry links to the case’s task list, not to individual tasks.

Testing the connection

Test Connection calls GET /api/versions with the API key. Failures are shown as Test failed: followed by one of the messages below. Self-signed certificates are accepted; Cymph does not reject a DFIR-IRIS instance because its certificate is untrusted.
Test Connection only verifies that the key authenticates. It does not check that the key’s user can see any cases or list users. If the key belongs to a non-administrative account, Test Connection passes but the Deploy dialog reports Authorization failed when it tries to load the assignee list, because the user-list endpoint requires administrative rights (see Permissions).