# Edit your organisation details Source: https://docs.cymph.io/administration/edit_org 1. Go to your **Organisation** page. * From the navigation menu, go to the **Organisation** page and then click on the name of your organisation. 2. Click **Edit Organisation**. * In the top-right corner, click the **Edit Organisation** button. Editorgbutton 3. Edit your organisation details. * **Rename your organisation (optional):** Provide a name in the **Organisation Name** field. Organisation names are unique across the Cymph platform. If you try to provide a name that already belongs to an organisation, an error will be displayed. * **Change the visibility status (optional):** Click on the **Visibility** toggle to change the visibility status of your organisation. By default an organisation is visible to users outside the organisation. * **Update your organisation URL (optional)**: Provide a URL for your organisation * **Update your organisation logo (optional)**: Click on the **Edit** link below your current organisation logo. The user can upload a new logo for their organisation. This needs to be an image file not exceeding 5MB and supported formats are PNG, GIF and JPEG. Editorgdetails 4. Confirm your changes. * Click on the **Update** button for your changes to take effect. Only users with the **Admin** role can change the details of their organisation. For all other roles, the option to edit their organisation details will not appear. # Invite members Source: https://docs.cymph.io/administration/invite_members ## Inviting members by e-mail 1. Go to your **Organisation** page. * From the navigation menu, to the **Organisation** page. 2. Click **Invite Members**. * In the top-right corner, click the **Invite Members** button. Orginvite1 3. Add Member. * In the invitation field, enter the **email address** of the person you want to invite. * Next to the email, select the appropriate **role** for the user from the dropdown (Admin, Editor, Collaborator, Viewer). * Click on plus icon to add the member to the invite list Orginvite2 4. Add more Members (optional). * To invite multiple members, enter the details of each additional member and click the plus (+) icon. * The new member will be added to the invitation list. 5. Remove a Member from the list. * If you need to delete an entry, click the **remove (x) icon** from the invitation list Orgremoveinvitelist 6. Send your invites. * Press **Send invitations** to send your invitations. * They will receive an email invitation to join your organisation right away. ## Types of members you can invite * **Non-registered users:** * If the invitee is new to the platform, they will receive an invitation to **sign up**. * Once they complete the onboarding, they will be prompted to **join your organisation**. * **Registered users without an organisation:** * If the user already has an account but isn’t part of any organisation, they will receive an e-mail invitation to **join your organisation**. * A **notification** will also appear to remind them about the invite. **Note:** Users who have already registered to the platform and are members of another organisation cannot be invited. They will need to leave their current organisation before they can accept an invite to join yours. ## Adding members without an invitation Available in both [deployment models](/deployment/models) — a managed cloud tenant and a self-hosted deployment. Cymph deployments allow the addition of organisation members without an invitation, which is useful when accounts are provisioned centrally rather than by invite. Users with the **Administration** role can add members directly to their organisation. 1. Go to your **Organisation** page 2. Click on **Add Members** Onprem Org Add Member 3. Enter the details of the member(s) you want to add * By clicking on Add more users button additional entries will appear Onprem Org Add Member Modal 4. Click on **Add Members** once all information is keyed in 5. The Organisation table will be automatically refresh to reflect the changes * If the e-mail address provided for a user is not found in the list of registered users, a new account will be created with that address. The password for this new user will be `password` . Users will be forced to change the password upon first login. * If the e-mail address provided for a user belongs to a member of another organisation, the process will fail * If any of the e-mail addresses provided belong to an on-premises administrator, the process will fail Removing a member added this way is no different from removing any other member — see [How to remove a member from the organisation](/administration/manage_members#how-to-remove-a-member-from-the-organisation). # Manage members Source: https://docs.cymph.io/administration/manage_members ## Overview The **Organisation page** provides a view of the **Active** and **Invited** members. The **Members** **table** that gives you an overview of all members (both active and invited) in your organisation: Orgmemberstable The **Members** **table** contains seven columns: 1. **Avatar**: the member’s avatar, if uploaded, else their initials. 2. **User Name**: the name and surname of the member, as declared during their registration process. This column is empty for invited members. 3. **Email**: the email address of the member. 4. **Joined**: the time elapsed since the member joined your organisation. This column is empty for invited members, since they have not yet joined. 5. **Role**: their [role](/administration/user_roles) in your organisation. 6. **Status**: “Active” if they have joined your organisation, “Invited” if they have been invited and their response is pending. 7. **An action column**: Actions appear by clicking the triple dot icon `⫶` ## Managing active members ### How to change the role of a member 1. Go to your Organisation page. * From the main dashboard, navigate to the **Organisation** page. 2. Click the arrow next to the user’s role. * A dropdown menu will appear with all the available [roles](/administration/user_roles) (Admin, Editor, Collaborator, Viewer). Changerole1 3. Select the desired role for the member. * The corresponding member’s role will change and the Members table will be refreshed to reflect the changes. Changerole2 **Note**: Only members with the **Admin** **role** can change the role of other members. Admin users cannot change their own role. ### How to edit a member 1. Go to your Organisation page. * From the navigation menu, go to the **Organisation** page. 2. Click the **triple dot icon**`⫶` in the action column of the member you want to edit * A dropdown menu will appear containing the actions that can be performed (Edit User, Remove from organisation). Orgmemberaction 3. Click the **Edit User** option. * The **Edit User panel** will appear. Orgedituser 4. Change the visibility status of the user (optional). * Click the visibility toggle next to “Visible to others”. * Grey toggle means the user is invisible, purple toggle means they are visible. Visible users are searchable by all Cymph users in the platform. 5. Ask user to reset their password (optional). * Click **Ask user to reset their password**. * A notification will appear on the user notification centre to ask them to reset their password. **Note**: Only members with the **Admin** **role** can edit the role of other members. ### How to remove a member from the organisation 1. Go to your **Organisation** page. * From the main dashboard, navigate to the **Organisation** page. 2. Click the **triple dot icon** `⫶` in the action column of the user you want to edit. 3. Click the **Remove from organisation** option . * A confirmation dialog will appear. Orgremovemember 4. Confirm the removal of the user. * Click **Remove User** to remove the user from the organisation. * The user will be removed from the organisation and will no longer appear in the Members table. * Only members with the **Admin** **role** can remove other members. * All the playbooks created by the users while they were members of the organisation **will be transferred** to the administrator of the organisation. * **An administrator cannot remove themselves from the organisation**. ## Managing invited users Users that have been invited to your organisation but have not yet responded to your invite will appear in **Invited** table. ### How to re-send an invite 1. Go to your **Organisation** page. 2. Click on the **Invited** table 3. Click the **Re-send invite** option. * The invitation email will be re-sent to the provided e-mail address. Resendinvite ### How to revoke an invite 1. Go to your **Organisation** page. * From the main dashboard, navigate to the **Organisation** page. 2. Go the **Invited** tab 3. Click **Revoke invite** option. * A confirmation dialog will appear. 4. Confirm the revocation. * Click **OK** to revoke the invitation. * The invitation will be revoked and the invited user will no longer appear in the members table. **Note**: Only users with the **Admin** **role** can re-send or revoke invites # Organisation management Source: https://docs.cymph.io/administration/organisation_management Create and manage organisations from the on-premises administrator account. This page covers the **deployment administrator** flow, available in both [deployment models](/deployment/models). Users can also create an organisation themselves — see [Create an organisation](/settings/create_org). ## How to add an organisation Users with the On-prem Administrator role can manually add organisations. 1. Go to the **Organisations Management** page * From the navigation menu, select **On-prem** and then **Organisations** Onprem Org Navi 2. Click on **Add Organisations** button Onprem Add Org Step1 3. Enter the organisation details * Enter the organisation name (required) * Enter the e-mail address for the administrator of the organisation Onprem Add Org Modal 4. You can add more organisations by clicking on **Add more organisations** option (optional) * Enter the details for the additional organisations 5. Click on **Add Organisations** to confirm 6. The **Organisations Management** page will be automatically refreshed to show the new organisations * If any of the e-mail addresses provided during that step is not already registered in the application, a new account will be created for that address. The initial password for these accounts will be `password` and members will be forced to change it upon first login. * If any of the e-mail addresses provided already belong to an organisation, the process will fail. * If any of the e-mail addresses provided belong to an on-premises administrator, the process will fail # **How to delete an organisation** 1. Go to the **Organisations Management** page 2. Click the **Delete icon** of the organisation you want to delete Onprem Delete Org 3. Confirm the deletion by clicking on **Delete Organisation** button 4. The organisation will be removed and the **Organisation Management** table will be refreshed to reflect the changes **When you delete an organisation, all of its members and their owned playbooks will be deleted as well. Please make sure that you have taken the appropriate backup.** # Team management Source: https://docs.cymph.io/administration/team_management # Overview Organisation administrations can organise their members into teams. An organisation member can belong to one or multiple teams at once. Each team needs to have a unique name within the context of the organisation. # How to create a team 1. Go to your **Teams** page * From the navigation menu, go to Organisations and then select the **Teams** page. Teamsnav 2. Click on the **New Team** button * A popup dialog will appear for the settings of the new team Teamsnew 3. Enter details of the new team * Name: it is required and must be unique across the organisation’s teams * Members: it is required * Function: optional, states the function of your team (e.g. Security Operations team) Teamdetails 4. Click on the **Add Team** button 5. The teams page will be automatically refreshed to show the new team # How to edit a team 1. Go to your **Teams** page 2. Click the **Edit icon** for the team you want to edit * A popup dialog will appear with the team details Editteam1 3. Edit the details of the team 4. Click on the **Update Team** button to save your changes # How to delete a team 1. Go to your **Teams** page 2. Click on the **Delete icon** for the team you want to delete Teamdel1 3. Confirm the deletion by clicking the **Delete** button Teamdelconfirm 4. The team will be deleted and the **Teams** table will be automatically refreshed # User Management Source: https://docs.cymph.io/administration/user_management # Organisation members Users that belong to an organisation are called Organisation members. A user can only belong to one organisation at a time. Members of an organisation all have a specific role. Each organisation must have at least one user with the **Admin** role (see [User roles](/administration/user_roles) for more details). If a user has the appropriate permissions, they can invite other users to the organisation: * Existing Cymph users that do not belong to an organisation (they are individuals). * Non-existing Cymph users by inviting them through e-mail. At any point in time, organisation members can leave the organisation under the following scenarios: * They are not assigned the **Admin** role. * If they are the last member of the organisation. In that case, the organisation will also be deleted. * If they are not the last member of the organisation, at least one member with the **Admin** role will be left in the organisation after their departure. # Individuals Individuals do not belong to any organisation but they have all permissions required to perform all actions in the platform (see [User roles](/administration/user_roles) for more details). At any point in time, individuals can create an organisation. You can see the steps in [Create an organisation](/settings/create_org). Upon creating an organisation, the user will be automatically assigned the **Admin** role. # User roles Source: https://docs.cymph.io/administration/user_roles Every registered user in the Cymph platform has a role. ## **Roles** ### **Individual** All users that do not belong to an organisation are automatically assigned the Individual role. By default, individual users are visible to other users in the platform, unless their [visibility status is changed](/settings/account) via the account settings. ### Admin This role is available for users that belong to a Cymph organisation. Admin users have full control over the organisation. They can invite and remove members as well as edit the organisation settings. Admin users can create playbooks and share them to specific users, their own organisation, other organisations and also publicly. ### Editor This role is available for users that belong to a Cymph organisation. Users with the Editor role do not have administrative privileges over the organisation. Editors can create playbooks but can only share them to specific users and their own organisation. ### Collaborator This role is available for users that belong to a Cymph organisation. Users with the Collaborator role do not have administrative privileges over the organisation. Collaborators can create playbooks and share them to specific users, their own organisation, other organisations and also publicly. ### Viewer This role is available for users that belong to a Cymph organisation. Users with the Viewer role do not have administrative privileges over the organisation. Viewers are not able to create nor share playbooks but they are allowed to comment on playbooks they have access to. # Managed cloud tenant Source: https://docs.cymph.io/deployment/managed-cloud-tenant A dedicated Cymph instance hosted and operated by Cymph, configured by you. A managed cloud tenant is your own Cymph instance — reachable at a hostname of its own, such as `client1.cymph.io` — hosted on AWS and operated by Cymph. It is the same product as a [self-hosted](/deployment/self-hosted/architecture) deployment, built the same way and behaving the same way. The difference is who runs the infrastructure underneath it: Cymph performs the installation, operates the database and filesystem as managed services, handles DNS and certificates, and takes the backups. Everything inside the application stays yours to configure. This is not a shared multi-tenant service. Your tenant is a separate instance with its own hostname and its own data store — no other customer's data lives alongside yours. ## What Cymph operates | | Handled by | | -------------------------------------------- | ---------- | | Installation and initial provisioning | Cymph | | Hostname and DNS | Cymph | | TLS certificates and renewal | Cymph | | Database (managed PostgreSQL) and filesystem | Cymph | | Backups and restore | Cymph | | Version upgrades | Cymph | | Infrastructure monitoring and availability | Cymph | You do not need to install anything, hold TLS certificates, run a backup routine, or plan an upgrade window. The operational pages under [Self-hosted](/deployment/self-hosted/architecture) — installation, TLS, backup and restore, upgrades — do not apply to you. ## What you configure Your tenant comes with an **on-prem administrator** account, and you hold it. Despite the name, it is the deployment administrator account in both models, and it gives you full control over everything inside the application: | Area | Where | | ----------------------------------------- | ------------------------------------------------------------------ | | Outbound e-mail | [SMTP](/deployment/settings/smtp) | | AI provider | [AI configuration](/deployment/settings/ai) | | Single sign-on (Google, GitHub, Entra ID) | [Single sign-on](/deployment/settings/sso) | | Playbook Hub and Explore | [Playbook Hub & Explore](/deployment/settings/hub-explore) | | Organisations | [Organisation management](/administration/organisation_management) | | Members, roles and teams | [Administration](/administration/user_management) | | Audit logs | [Audit & logging](/security/audit-logging) | The AI provider and the SMTP server are **yours to supply**, exactly as in a self-hosted deployment. Cymph does not provide a model or a mail server on your behalf — you enter your own provider's settings, and the credentials are encrypted with your tenant's own key material. See [AI & data usage](/security/ai-data-usage). ## Networking Your tenant runs in AWS `eu-west-1` (Europe / Ireland). Because integrations connect outbound from AWS rather than from your own network, endpoints behind a source-IP allowlist need Cymph's egress addresses permitted. The addresses, and the notice policy for changing them, are in [Networking](/deployment/networking#managed-cloud-tenant). ## Getting started Onboarding is arranged with the Cymph team, who provision the tenant and hand over the administrator credentials. From there: 1. Change the administrator password at first login. 2. Configure [SMTP](/deployment/settings/smtp) — password resets and notifications depend on it. 3. Configure [single sign-on](/deployment/settings/sso) if your users authenticate through an identity provider. 4. Create your first organisation — see [Organisation management](/administration/organisation_management). 5. Allowlist the [egress addresses](/deployment/networking#managed-cloud-tenant) on any endpoint you plan to integrate with. 6. Configure an [AI provider](/deployment/settings/ai) if you want the AI features. To discuss a managed tenant, contact [support@cymph.io](mailto:support@cymph.io). # Deployment models Source: https://docs.cymph.io/deployment/models The two ways to run Cymph, and who is responsible for what in each. Cymph is delivered in two variants. Both run the same product with the same architecture, the same features and the same administrative model. What differs is **who operates the infrastructure**. A dedicated instance at its own hostname, hosted and operated by Cymph. You configure the application; Cymph runs everything underneath it. You install and operate Cymph on your own infrastructure, with Docker Compose. Nothing leaves your network unless you configure it to. Neither is a shared multi-tenant service — in both cases your deployment is a separate instance with its own data store. ## Responsibility split | | Managed cloud tenant | Self-hosted | | ------------------------------------------ | ------------------------ | --------------------------------------------------------------------- | | Installation | Cymph | You | | Hostname and DNS | Cymph | You | | TLS certificates and renewal | Cymph | [You](/deployment/self-hosted/tls-certificates) | | Database and filesystem | Cymph (managed services) | [You](/deployment/self-hosted/architecture) (containers on your host) | | Backups and restore | Cymph | [You](/deployment/self-hosted/backup-restore) | | Version upgrades | Cymph | [You](/deployment/self-hosted/upgrades) | | Encryption key custody | Cymph | You | | **Outbound e-mail (SMTP)** | **You** | **You** | | **AI provider** | **You** | **You** | | **Single sign-on** | **You** | **You** | | **Playbook Hub and Explore** | **You** | **You** | | **Organisations, members, roles, teams** | **You** | **You** | | **Integrations** | **You** | **You** | | **Firewall allowlisting for integrations** | **You** | **You** | The pattern is worth stating plainly: **infrastructure differs, application configuration does not.** Every setting inside the product is yours in both models, configured from the same screens by the same administrator account. That is why [Networking](/deployment/networking) and [Instance settings](/deployment/settings/smtp) are documented once for both, while installation, TLS, backup and upgrades live under [Self-hosted](/deployment/self-hosted/architecture). ## Choosing between them Choose **self-hosted** when data residency, network isolation or key custody has to sit inside your own boundary — for example when policy prohibits customer data leaving your infrastructure, or when your integration endpoints are only reachable from your own network. You take on installation, certificates, backups and upgrades in exchange. Choose a **managed cloud tenant** when you would rather not operate the infrastructure. You still own every application-level setting and every integration, and your data stays in the EU — but Cymph carries the installation, patching, backup and upgrade burden. If integration endpoints inside your network are reachable only from that network, note that a managed tenant connects to them from AWS. That is workable with an allowlist, but self-hosted avoids the question entirely. See [Networking](/deployment/networking). ## Where your data lives | | Managed cloud tenant | Self-hosted | | ------------------------ | ---------------------------------- | ------------------------------- | | Application and database | AWS `eu-west-1` (Europe / Ireland) | Your infrastructure | | Search embeddings | Generated inside the deployment | Generated inside the deployment | | AI processing | Your chosen provider | Your chosen provider | [Data protection](/security/data-protection) covers this in full, including encryption and key custody. `app.cymph.io` is a demo instance used for evaluation and is not a commercial deployment option. Production use is via a managed cloud tenant or a self-hosted deployment. # Networking Source: https://docs.cymph.io/deployment/networking Firewall, allowlisting and egress information for Cymph deployments. This page covers the network configuration required to run Cymph alongside the systems it connects to — SIEMs, SOAR platforms, ticketing systems and repositories. It applies to both [deployment models](/deployment/models); the parts that differ are split out below. Setting up an individual integration is covered in [Integrations](/integrations/overview). This page is for the network and firewall work that has to happen around it. ## Inbound access **Self-hosted.** The web application listens on the IP address and port you choose during [installation](/deployment/self-hosted/installation), over HTTPS. Users and API clients need to reach that address, so allow it through any host firewall, and if you front Cymph with a reverse proxy or load balancer, terminate or pass through TLS there. See [TLS certificates](/deployment/self-hosted/tls-certificates). That one port is the only one to open. The web application, API, embedding service and database are all bound to the internal Docker network and are not published on the host, so there is no second entry point to firewall off. **Managed cloud tenant.** Your tenant is reachable at its own hostname over HTTPS on port 443. DNS and certificates are handled by Cymph, so there is no inbound work on your side beyond permitting outbound HTTPS from your users to that hostname. ## Egress control Several integrations require Cymph to make **outbound** connections to an endpoint you operate — SIEM APIs (Wazuh, Microsoft Sentinel), SOAR platforms, ticketing systems, and similar. When that endpoint sits behind a firewall or a **source-IP allowlist** (standard practice in financial and government environments), the connection is refused unless Cymph's egress address is permitted. Symptoms of a missing allowlist entry: * **Test Connection** fails with `403` or a connection timeout. * A previously working integration goes dead while its status still shows **Enabled** — the only clue is the `403`s in your own endpoint's access logs. How you allowlist depends on which deployment model you run. ### Self-hosted Cymph runs inside your own environment, so its outbound traffic leaves from infrastructure you control — the API host, or the NAT gateway / egress proxy in front of it. * **Allowlist by FQDN** wherever your firewall supports it. Put the FQDN of your Cymph deployment (or its egress NAT) in the allowlist rather than a raw IP, so the rule survives host or IP changes. * If your allowlist is strictly IP-based, use the **static egress IP / CIDR** of the NAT gateway or proxy that fronts Cymph. Because you own this hop, the address is stable and already known to your network team. * No coordination with Cymph is required — the egress point is entirely within your network. ### Managed cloud tenant Managed tenants run on AWS in **`eu-west-1` (Europe / Ireland)**. Outbound connections originate from **AWS-owned IP addresses** in that region: * 34.252.152.14 * 52.19.159.74 * 54.220.85.57 All three are in use, and they are shared across managed tenants. An allowlist must contain every address, not just the ones observed in your own logs — traffic for a given sync can leave from any of them. ### Change policy for egress addresses The addresses above are stable, but infrastructure changes do occasionally require them to move. Cymph gives **at least 15 days' notice** before any change to these egress addresses, so your network team has time to update firewall rules ahead of the change. Notice is sent on the channel agreed with your organisation. New addresses are added to this page as soon as the notice goes out, so an allowlist that covers both the current and the announced addresses stays working across the transition. If your organisation routes change requests through a ticketing process with a lead time longer than 15 days, let us know at [support@cymph.io](mailto:support@cymph.io) and we can flag your organisation for earlier notice. ## Outbound connections Cymph makes Regardless of model, the deployment connects outbound only to: * The **integration endpoints** you configure. * Your **AI provider**, if you have configured one — see [AI configuration](/deployment/settings/ai). * Your **SMTP server**, if you have configured one — see [SMTP](/deployment/settings/smtp). * Your **identity provider**, if you have enabled single sign-on — see [Single sign-on](/deployment/settings/sso). Semantic search embeddings are generated by a service inside the deployment, so no outbound connection is needed for search. # Architecture Source: https://docs.cymph.io/deployment/self-hosted/architecture The services, ports and data stores that make up a self-hosted Cymph deployment. A self-hosted Cymph deployment is a single Docker Compose project named `cymph`. Everything it needs runs on one host — there are no external dependencies apart from the integrations you configure and, optionally, an AI provider. ## Services | Service | Image | Role | | --------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nginx` | `nginx:1.27-alpine` | Terminates TLS and reverse-proxies to the application. The only service that needs to be reachable from outside the host. | | `ui` | `cymph/ui:latest` | The web application, served on port 3000 inside the network as `cymph-ui`. | | `api` | `cymph/api:latest` | The application API on port 5050, as `cymph-api`. Holds the license, integration configuration and playbook data. | | `embedding-api` | `text-embeddings-inference` | Generates the vector embeddings behind semantic search, on port 8090. Runs the `all-MiniLM-L6-v2` model locally — no content leaves the deployment for search. | | `db` | `pgvector/pgvector:pg16` | PostgreSQL 16 with the `pgvector` extension, as `cymph-db`. The single data store for the deployment. | `ui`, `api` and `db` each declare a healthcheck, and Compose starts them in dependency order — `db` before `api`, `api` before `ui`, `ui` before `nginx`. Users reach the deployment through nginx, on the address and port you choose during [installation](/deployment/self-hosted/installation). Uploads are capped at 20MB. `ui`, `api`, `embedding-api` and `db` are reachable only on the internal Docker network — none of them is published on the host. The single published port is nginx's, which means every request reaching the application has passed through TLS termination. See [Networking](/deployment/networking). ## Data and volumes Four Docker volumes hold everything that survives a container restart: | Volume | Contents | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `cymph_db-data` | The PostgreSQL data directory — playbooks, executions, users, organisations, workspaces, integration configuration and audit logs. | | `cymph_api-data` | Mounted at `/var/opt/cymph` in the API container: application logs, static files and data files. | | `cymph_log-data` | nginx access and error logs. | | `cymph_embedding-data` | The cached embedding model. | These are what you snapshot — see [Backup & restore](/deployment/self-hosted/backup-restore). ## Secrets generated at setup `env.sh` generates the deployment's secrets on first run and writes them to `.env` and `db/secrets.txt`: * `NEXTAUTH_SECRET` / `CYMPH_AUTH_SECRET` — session token signing * `CYMPH_SESSION_SECRET` — session state * `CYMPH_ENCRYPTION_KEY` and `CYMPH_ENCRYPTION_IV` — encryption of sensitive integration data at rest * A Fernet key in `db/secrets.txt`, passed to the database container as a Compose secret These values are generated once and are not recoverable. If you lose `.env` or `db/secrets.txt`, encrypted data in the database cannot be decrypted — back them up alongside the volumes. ## Outbound connections The `api` service makes outbound connections to the endpoints your integrations point at, and to your AI provider if you enable one. Search embeddings are computed locally by `embedding-api`, so no content leaves the deployment for search, and product analytics is disabled in the on-prem configuration (`NEXT_PUBLIC_AMPLITUDE_ENABLED=false`). See [Networking](/deployment/networking) for allowlisting, and [AI & data usage](/security/ai-data-usage) for what an enabled AI provider receives. # Backup & restore Source: https://docs.cymph.io/deployment/self-hosted/backup-restore Back up and restore a self-hosted Cymph deployment using Docker volume snapshots. A self-hosted deployment keeps all of its state in Docker volumes plus a handful of configuration files. Backing up means archiving both; there is no separate export step inside the application. A volume backup is only usable together with the deployment's secrets. `CYMPH_ENCRYPTION_KEY` and `CYMPH_ENCRYPTION_IV` in `.env`, and the key in `db/secrets.txt`, are generated once at setup and cannot be regenerated. Without them, sensitive integration data in a restored database cannot be decrypted. Always back up the configuration files alongside the volumes. ## What to back up | Item | Why | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Volume `cymph_db-data` | The PostgreSQL data directory — playbooks, executions, users, organisations, workspaces, integration configuration, audit logs. | | Volume `cymph_api-data` | Application data and static files under `/var/opt/cymph`. | | `.env` | Deployment configuration and the encryption and signing secrets. | | `.dbenv` | The on-prem administrator e-mail used to seed the database. | | `db/secrets.txt` | The database key generated at setup. | | `nginx/nginx.conf` | Contains the `server_name` written in during setup. | `cymph_log-data` (nginx logs) is worth keeping if you retain logs for compliance reasons. `cymph_embedding-data` holds only a cached model and is re-downloaded automatically — skip it. ## Choosing a method **Volume snapshots are the recommended approach.** One mechanism captures the database and the application data together at the same point in time, and restore is a straight extraction — no schema migration, no dump-format compatibility to think about between versions. The trade-off is that copying a live PostgreSQL data directory is not crash-consistent, so **the stack has to be stopped while the archive is taken**. In practice this fits the maintenance window you already take for [upgrades](/deployment/self-hosted/upgrades). If you need backups without downtime, use `pg_dump` against the `db` container for the database and snapshot `cymph_api-data` separately. That gives you a hot backup but two restore paths to manage instead of one. ## Taking a backup 1. Stop the stack from the directory containing `compose.yaml`: ```bash theme={"system"} sudo docker compose stop ``` 2. Archive each volume through a throwaway container: ```bash theme={"system"} mkdir -p backup sudo docker run --rm \ -v cymph_db-data:/source:ro \ -v "$(pwd)/backup":/backup \ alpine tar czf /backup/db-data.tar.gz -C /source . sudo docker run --rm \ -v cymph_api-data:/source:ro \ -v "$(pwd)/backup":/backup \ alpine tar czf /backup/api-data.tar.gz -C /source . ``` 3. Copy the configuration files: ```bash theme={"system"} cp .env .dbenv db/secrets.txt nginx/nginx.conf backup/ ``` 4. Start the stack again: ```bash theme={"system"} sudo docker compose start ``` 5. Move the `backup` directory off the host, to wherever you keep encrypted backups. It contains the deployment's secrets in plaintext, so treat it accordingly. Volume names are prefixed with the Compose project name, which is `cymph`. If you renamed the project, confirm the real names with `docker volume ls`. ## Restoring Restore onto a host with the same Cymph release the backup was taken from. Restoring into a newer release is not supported — restore first, then [upgrade](/deployment/self-hosted/upgrades). 1. Extract the release bundle and put the saved configuration files back in place. Do **not** run `env.sh` — it would generate new secrets and make the backup undecryptable. ```bash theme={"system"} tar zxvf cymph_onprem.tgz cd cymph/ cp /path/to/backup/.env /path/to/backup/.dbenv . mkdir -p db && cp /path/to/backup/secrets.txt db/ cp /path/to/backup/nginx.conf nginx/ ``` 2. Make sure nothing is running, and remove the volumes that the restore will replace: ```bash theme={"system"} sudo docker compose down sudo docker volume rm cymph_db-data cymph_api-data ``` 3. Recreate the volumes and extract the archives, preserving ownership so PostgreSQL can read its data directory: ```bash theme={"system"} sudo docker volume create cymph_db-data sudo docker volume create cymph_api-data sudo docker run --rm \ -v cymph_db-data:/target \ -v /path/to/backup:/backup:ro \ alpine tar xzpf /backup/db-data.tar.gz -C /target sudo docker run --rm \ -v cymph_api-data:/target \ -v /path/to/backup:/backup:ro \ alpine tar xzpf /backup/api-data.tar.gz -C /target ``` 4. Confirm the TLS certificate and key are present at the paths recorded in `.env` — those are host paths and are not part of the volume backup. See [TLS certificates](/deployment/self-hosted/tls-certificates). 5. Start the stack: ```bash theme={"system"} sudo docker compose up -d ``` 6. Verify the restore. `docker compose ps` should show every service healthy, and you should be able to log in with the credentials that were in use when the backup was taken — user accounts and passwords come from the restored database, not from setup. If the `db` service fails its healthcheck after a restore, check its logs first — a permissions problem on the data directory is the usual cause, and it means step 3 ran without `-p` or without root: ```bash theme={"system"} sudo docker compose logs db ``` # Installation Source: https://docs.cymph.io/deployment/self-hosted/installation Install Cymph on your own infrastructure with Docker Compose. Before you start, confirm your host meets the [requirements](/deployment/self-hosted/requirements) and that your TLS certificates are in place. ## Steps The steps below refer to a command line based installation in an Ubuntu 22.04 machine. The same steps apply for MacOS. 1. Extract the tarball and go to the cymph folder ```text theme={"system"} $ tar zxvf cymph_onprem.tgz $ cd cymph/ ``` 2. Configure the .env file ```text theme={"system"} $ sudo ./env.sh ``` This step generates the deployment's secrets and writes the `.env` file. It will ask you: * The e-mail of the on-prem administrator user (default is [admin@domain.com](mailto:admin@domain.com)) * The IP address or domain where the Web application will listen (default `localhost`) * The port where the Web application will listen (default `443`) * The location of the TLS certificate (default `/etc/ssl/bundle.crt`) and of its private key (default `/etc/ssl/cert.key`) — both must already exist on the host, see [TLS certificates](/deployment/self-hosted/tls-certificates) * If SSL mode is required for Postgres (default is no) Run `env.sh` **once**. It generates the signing and encryption secrets for the deployment, and re-running it replaces them — which makes existing encrypted data unreadable. See [Backup & restore](/deployment/self-hosted/backup-restore). 3. Run docker compose ```text theme={"system"} $ sudo docker compose up -d ``` This command will run the containerized services in the background. If you have already composed the solution, then run `sudo docker compose start` If you see a message like this: > The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested feel free to ignore it. Once docker compose is complete, you should see the following on your terminal: Docker Up The setup procedure also performs certain initialisation steps: * Creates an on-prem administration account with default credentials * Populates the instance with playbook contents. The playbooks will belong to the on-prem administration account 4. Open your browser and navigate to the Cymph application * The URL should be `https://:` as configured in step 2. If you kept the defaults, the URL is `https://localhost` 5. Enter the default on-prem administration credentials and click on **Log In** button * E-mail: the email you provided on step 2 (or [admin@domain.com](mailto:admin@domain.com) if no e-mail was provided) * Password: admin Onprem First Login 6. You will be asked to change your password * Enter the current password, which is `admin` * Enter your new password that meets the password criteria. * Click on **Update** to change the password * After changing your password, you will be redirected to the login screen 7. Login with the updated credentials and you are ready! ## Next steps After you are done with the installation, you will be able to login as an on-prem administrator. From that account you will be able to: * Upload the license. You can refer to [Licensing](/deployment/self-hosted/licensing) for more details * Create the first organisation. You can read more at [Organisation management](/administration/organisation_management) * Configure e-mail, AI, single sign-on and the Playbook Hub from the on-prem settings page — see [SMTP](/deployment/settings/smtp) * Set up a backup routine before the deployment carries real data — see [Backup & restore](/deployment/self-hosted/backup-restore) If a service does not come up, see [Common issues](/deployment/self-hosted/troubleshooting). # Licensing Source: https://docs.cymph.io/deployment/self-hosted/licensing Upload and manage the license for a self-hosted Cymph deployment. # Overview Before you begin using the Cymph application, a license is required. The license defines how many users can be created globally and what features will be available. The license will be provided to you by the Cymph team through a dedicated channel (e.g. email). Your license file contents should look like the example below. ``` -----BEGIN LICENSE FILE----- eyJ1c2VyX2xpbWl0IjogNDAsICJleHBpcmF0aW9uX3RpbWUiOiAiMjAyNS0wM y0xNSAxNTo1MTowNi42NTQ1ODAiLCAicGxhbl90eXBlIjogIlByZW1pdW0iLC AiZmVhdHVyZXMiOiBbImV4cG9ydDpzdGFja3N0b3JtIl19.J+TU5An6rjwu2bs dTd2GIYdI5LaCKg6kxSKlVX1zlf4YkuX07WSC4W24szJFMLah9kfJRv8V/faAV BRcb4rhpuXJ0QmojpJp3xJorz7ZP01AiijkdlEyn4UnStqt/GzLqUshcOsJgB -----END LICENSE FILE----- ``` # How to upload a license Only users with the On-prem Administrator role can upload licenses. 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click **Settings** Account2 3. Go to **License Management** tab * Click **License** License Tab 4. Upload your license License Upload 5. Once you select the license file from the file explorer, the license will be automatically uploaded 6. Refresh the Cymph application web page to see the new license information # How to renew your license Renewing your license follows exactly the same procedure as uploading your license for the first time. # Requirements Source: https://docs.cymph.io/deployment/self-hosted/requirements Hardware, software and prerequisites for a self-hosted Cymph deployment. Check these before you begin [Installation](/deployment/self-hosted/installation). For what actually gets deployed, see [Architecture](/deployment/self-hosted/architecture). ## Hardware 1. At least 2GB of memory 2. At least 30GB of disk space for container images and application data ## Software 1. Any operating system that can run Docker. We have tested on Ubuntu 22.04LTS 2. Docker * Install the latest versions of `Docker` engine and `docker-compose`. Installation instructions are at [https://docs.docker.com/desktop/setup/install/linux/](https://docs.docker.com/desktop/setup/install/linux/) * Docker compose is also required. By default it comes with Docker desktop. If it is not installed check the documentation at [https://docs.docker.com/compose/install](https://docs.docker.com/compose/install). * We have tested our deployment with versions 27.4.0 and onwards ## Prerequisites 1. The tarball containing the Cymph installation script 2. TLS certificates. The installation hosts Cymph on a secure (HTTPS) website, so the certificate and key must be available on the host machine before you install — see [TLS certificates](/deployment/self-hosted/tls-certificates). 3. A license file, provided by the Cymph team. The license is uploaded after installation — see [Licensing](/deployment/self-hosted/licensing). 4. Network access for any integrations you plan to use — see [Networking](/deployment/networking). # Resetting the administrator password Source: https://docs.cymph.io/deployment/self-hosted/reset-admin-password Recover a forgotten or locked on-premises administrator account. # Overview In case you forgot the password for the on-premises administrator account, or it is locked due to too many failed login attempts, you can follow the procedure below to reset the password to its initial value. Note that if e-mail service is enabled you can also follow the forgotten password procedure described in [I cannot log in](/troubleshooting/cannot_login) # Resetting the on-premises administrator password 1. Login to the host running the Cymph docker instance 2. Get a shell on the API container ``` sudo docker exec -it cymph-api-1 /bin/bash ``` 3. Run the on-prem administrator password reset script ``` . /usr/src/app/etc/reset_onprem_admin_password.sh ``` **Note the space between the dot and the script path at the beginning of the command** 4. On a successful execution, you will see the following output: ``` Connected Password for 'example@example.com' reset successfully ``` (instead of `example@example.com` you will actually see the administrator email provided during setup) Once the process is complete, the on-premises administrator password will be reset to `admin` and you will be asked to change it upon first login. # TLS certificates Source: https://docs.cymph.io/deployment/self-hosted/tls-certificates Supply, mount and renew the TLS certificates that serve a self-hosted Cymph deployment. Cymph is always served over HTTPS. TLS is terminated by the `nginx` service, which reads a certificate and a private key from paths on the host that you supply during [installation](/deployment/self-hosted/installation). The certificates must exist on the host **before** you run `env.sh`. There is no HTTP fallback and no built-in certificate provisioning. ## What you need Two files on the host running Docker: | File | Contents | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Certificate bundle | Your server certificate, followed by any intermediate certificates, in PEM format. Default path `/etc/ssl/bundle.crt`. | | Private key | The matching unencrypted private key in PEM format. Default path `/etc/ssl/cert.key`. | The certificate's common name or a subject alternative name must match the domain or IP address you give during setup — that value is written into the nginx `server_name`. Any certificate authority works. Common choices: * **A public CA via certbot / ACME**, when the deployment has a resolvable public domain name. * **Your internal PKI**, which is typical for deployments on a private network. Include the full chain in the bundle so clients that already trust your internal root validate cleanly. * **A self-signed certificate via openssl**, for evaluation. Browsers will warn on every visit. ## Supplying the paths `env.sh` prompts for both locations: ```text theme={"system"} Enter the location of the SSL certificate (default: /etc/ssl/bundle.crt): Enter the location of the SSL certificate key (default: /etc/ssl/cert.key): ``` The answers are stored in `.env` as `SSL_CERTIFICATE` and `SSL_CERTIFICATE_KEY`, and Compose bind-mounts each file into the nginx container at `/etc/ssl/bundle.crt` and `/etc/ssl/cert.key`. Because these are bind mounts to host paths, the files stay under your control — Cymph never copies them into an image or a volume. ## Renewing or replacing a certificate The mount points do not change, so renewal is a file replacement plus an nginx restart: 1. Write the new certificate and key to the same host paths already recorded in `.env`. 2. Restart nginx to pick them up: ```bash theme={"system"} sudo docker compose restart nginx ``` Only the `nginx` service needs to restart — the application, API and database keep running, so there is no data-path downtime beyond the few seconds nginx takes to come back. If you renew with certbot, point its `--deploy-hook` at the restart command so renewal and reload happen together: ```bash theme={"system"} certbot renew --deploy-hook "docker compose -f /path/to/cymph/compose.yaml restart nginx" ``` To move to different paths instead of overwriting in place, edit `SSL_CERTIFICATE` and `SSL_CERTIFICATE_KEY` in `.env` and then recreate the container so the new bind mounts take effect: ```bash theme={"system"} sudo docker compose up -d --force-recreate nginx ``` ## Checking what is being served Confirm the certificate nginx has loaded, substituting your own address and port: ```bash theme={"system"} openssl s_client -connect your-cymph-host:443 -servername your-cymph-host /dev/null \ | openssl x509 -noout -subject -issuer -dates ``` If the connection fails or serves an unexpected certificate, check the nginx logs: ```bash theme={"system"} sudo docker compose logs nginx ``` A missing or unreadable file at either mounted path stops nginx from starting — see [Common issues](/deployment/self-hosted/troubleshooting). # Common issues Source: https://docs.cymph.io/deployment/self-hosted/troubleshooting Diagnose a self-hosted Cymph deployment that will not start or is not reachable. Run every command below from the directory containing `compose.yaml`. ## Start here: service status ```bash theme={"system"} sudo docker compose ps ``` Each of `db`, `api` and `ui` reports a health state, and Compose starts them in order — `db`, then `api`, then `ui`, then `nginx`. A service stuck in `starting` or marked `unhealthy` blocks everything after it, so work on the **earliest** unhealthy service first. A later service that never started is usually a symptom, not the cause. For the logs of a single service: ```bash theme={"system"} sudo docker compose logs api sudo docker compose logs -f nginx # follow ``` ## Upgrade fails with no space left on device `sudo docker compose pull` downloads a complete new set of images before the old ones are released, so an upgrade briefly needs room for **both** versions at once. On a host that has been upgraded a few times, it is usually the accumulated images from previous releases that fill the disk rather than the new release being large. A pull that runs out of space fails partway through with `no space left on device` or a write error on one of the layers. Nothing is broken by this — the running deployment is untouched and the pull can be repeated once space is available. ### Check what is actually full ```bash theme={"system"} df -h /var/lib/docker sudo docker system df ``` `df` reports the filesystem holding Docker's data; `docker system df` breaks that down into images, containers, volumes and build cache, with a **RECLAIMABLE** column showing how much can be freed without touching anything in use. Docker's data directory is not always `/var/lib/docker`. Confirm it with `sudo docker info | grep "Docker Root Dir"` and run `df -h` against that path. ### Reclaim space Start with the safe option — this removes only **dangling** images, the untagged layers left behind by previous pulls: ```bash theme={"system"} sudo docker image prune ``` If the host has ever built images locally, the build cache is worth clearing too: ```bash theme={"system"} sudo docker builder prune ``` Then confirm how much came back and retry the pull: ```bash theme={"system"} df -h /var/lib/docker sudo docker compose pull ``` ### If that did not free enough ```bash theme={"system"} sudo docker image prune -a ``` This removes every image that is not associated with a container, rather than only the untagged ones — on a host with several old releases it typically reclaims far more. Treat `-a` as a last resort, and mind your rollback path. Images are kept while a container still references them, **including a stopped one**, so running this between `docker compose stop` and `docker compose pull` leaves the current release intact. But if you have run `docker compose down`, the containers are gone, and `-a` will delete the images for your current version — rolling back would then mean re-pulling the previous tag. ### Watch it during the pull If space is tight enough that you expect the pull to be close, watch the filesystem from a second terminal while it runs: ```bash theme={"system"} watch -n 5 df -h /var/lib/docker ``` Never run `docker volume prune` or `docker system prune --volumes` on a Cymph host. Compose keeps the database and API data in named volumes, and once the containers have been removed those volumes look unused — pruning them **destroys your data**. `docker image prune` and `docker builder prune` do not touch volumes, which is why they are the commands used above. If pruning does not free enough to complete an upgrade, the host is under-provisioned for the deployment. See [Requirements](/deployment/self-hosted/requirements) for the disk sizing, and take a backup before making further changes — see [Backup & restore](/deployment/self-hosted/backup-restore). ## nginx exits immediately on startup The certificate and key are bind-mounted from host paths recorded in `.env`. If either path does not exist or is not readable, nginx fails at startup rather than serving without TLS. Check the paths Compose is using, then confirm both files exist on the host: ```bash theme={"system"} grep SSL_CERTIFICATE .env ls -l /etc/ssl/bundle.crt /etc/ssl/cert.key # substitute your own paths ``` If a path is wrong, correct it in `.env` and recreate the container so the new bind mount applies — a plain restart keeps the old mount: ```bash theme={"system"} sudo docker compose up -d --force-recreate nginx ``` See [TLS certificates](/deployment/self-hosted/tls-certificates) for the file format and renewal. ## Port already in use nginx is the only service that publishes a host port, on the address and port you chose during setup (`BIND_ADDRESS` and `BIND_PORT` in `.env`, default `0.0.0.0:443`). If something else on the host already holds that port, the container cannot bind and Compose reports an allocation failure. Find the conflict: ```bash theme={"system"} sudo ss -tlnp | grep :443 # substitute your BIND_PORT ``` Either stop the conflicting service, or change `BIND_PORT` in `.env` and recreate nginx. Note that binding below port 1024 requires the Docker daemon to run as root, which is why the install steps use `sudo`. ## The database never becomes healthy ```bash theme={"system"} sudo docker compose logs db ``` Two causes account for most of it: * **Missing or empty `db/secrets.txt`.** It is passed in as a Compose secret and holds the key generated by `env.sh`. If setup was interrupted, the file may be absent. * **Permissions on the data directory**, which typically follows a restore where ownership was not preserved. See [Backup & restore](/deployment/self-hosted/backup-restore). ## The API never becomes healthy The API healthcheck calls `/api/v1/misc/ping` inside the container. Reproduce it directly to separate an API problem from a proxy problem: ```bash theme={"system"} sudo docker compose exec api wget -qO- http://127.0.0.1:5050/api/v1/misc/ping ``` If that responds but the browser does not, the problem is in nginx or the network path, not the API. If it does not respond, read the API logs — it fails to start when it cannot reach the database or when required values are missing from `.env`. ## The page loads but every request fails This is the signature of a URL mismatch. `env.sh` writes the address you gave it into several variables (`CYMPH_APP_BASE_URL`, `NEXTAUTH_URL`, `NEXT_PUBLIC_WEBAPP_URL`, `CYMPH_BACKEND_API_ENDPOINT`, `NEXT_PUBLIC_BACKEND_API_ENDPOINT`) and into the nginx `server_name`. If you later change the hostname, port or scheme of the deployment, all of them have to agree — the browser is told to call an API address that no longer answers. ```bash theme={"system"} grep -E 'URL|ENDPOINT|BIND_' .env grep server_name nginx/nginx.conf ``` After correcting them, recreate the affected services: ```bash theme={"system"} sudo docker compose up -d --force-recreate ui api nginx ``` ## Cannot reach the deployment at all Work outward from the host: 1. **On the host**, confirm the port is listening: `sudo ss -tlnp | grep :443` 2. **From the host**, confirm TLS answers: `openssl s_client -connect localhost:443 support.txt sudo docker compose logs --tail 200 >> support.txt ``` Review `support.txt` before sending it. Logs can contain hostnames, e-mail addresses and integration endpoints from your environment. # Upgrades Source: https://docs.cymph.io/deployment/self-hosted/upgrades Update a self-hosted Cymph deployment to a newer release. # Before you begin Take a backup of the database and API volumes before you begin the update process — the stack has to be stopped for the upgrade anyway, which is the same window a consistent snapshot needs. See [Backup & restore](/deployment/self-hosted/backup-restore). Check that the host has room for the new images. The pull downloads a complete new set before the old ones are released, so the upgrade needs headroom for both versions at once: ``` df -h /var/lib/docker sudo docker system df ``` # Steps 1. Stop the current running containers ``` sudo docker compose stop ``` 2. Update the container images ``` sudo docker compose pull ``` If this step fails with `no space left on device`, the host has run out of room — usually because images from previous releases have accumulated. See [Upgrade fails with "no space left on device"](/deployment/self-hosted/troubleshooting#upgrade-fails-with-no-space-left-on-device) for how to reclaim it safely. The running deployment is unaffected, and the pull can be repeated. 3. Re-create and start the containers ``` sudo docker compose up -d --force-recreate ``` # AI configuration Source: https://docs.cymph.io/deployment/settings/ai Enable and configure the AI provider for a self-hosted deployment. Applies to both [deployment models](/deployment/models). The AI provider is supplied by you in a managed cloud tenant just as in a self-hosted deployment — see [AI & data usage](/security/ai-data-usage). ## How to modify AI settings Users with the On-prem Administrator role can modify the AI settings. By enabling AI, users will be able to use the AI capabilities of the platforms, such as playbook generation from prompts and mindmaps and autotagging. 1. Go to **On-prem settings** page * Click on **On-prem** from the navigation menu, then **Settings** Onprem Settings Navi 2. Edit the **AI Settings** * Click on the **Edit icon** next on the AI settings row Onprem Ai Edit 3. Enter the settings for your AI provider Onprem Ai Settings 4. Click **Test** to verify the connection before saving. The test sends a minimal chat completion request to the configured endpoint and model — see [How the test works](#how-the-test-works) below. ## Provider compatibility Cymph does not bundle a model. It calls whatever endpoint you configure using the **OpenAI Chat Completions API** (`POST {base URL}/chat/completions`). Any provider or gateway that implements this API can be used — including OpenAI itself, Azure OpenAI, and self-hosted servers such as vLLM, Ollama, LM Studio or LiteLLM. The three settings map directly onto that API: | Setting | What it is used for | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base URL** | The root of the API, e.g. `https://api.openai.com/v1` or `http://llm.internal:8000/v1`. Cymph appends `/chat/completions` to it. Include the version prefix (`/v1`) if your provider expects one. | | **API key** | Sent as a `Bearer` token in the `Authorization` header. Self-hosted servers that do not check keys still require a non-empty value. | | **Model** | Passed verbatim as the `model` field in every request. Use the identifier your provider expects (for Azure OpenAI this is the deployment name). | ### What the endpoint must support Cymph uses only the Chat Completions endpoint. It does not use the Responses API, the Assistants API, streaming, or an embeddings endpoint — semantic search runs on a local embedding model inside the deployment (see [AI & data usage](/security/ai-data-usage)). Within Chat Completions, the following features are required. Most features work as long as the first two are supported; the AI assistant additionally needs tool calling. | Capability | Required by | Notes | | ------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Basic chat completion with `system` and `user` messages | All AI features | | | `max_completion_tokens` parameter | All AI features | Cymph sends `max_completion_tokens`, not the deprecated `max_tokens`. Older servers that only understand `max_tokens` will reject requests. | | JSON mode — `response_format: { type: "json_object" }` | Playbook generation, mindmap generation, autotagging, translation | The model must honour JSON mode and return a valid JSON object in `choices[0].message.content`. | | Function / tool calling — `tools` and `tool_calls` | AI assistant | The assistant relies on the model choosing and invoking tools. Models or servers without tool-calling support will not work for the assistant, even if generation works. | | Completion sizes up to 8,192 output tokens | Playbook generation, AI assistant | Configure the server's output limit accordingly; a lower ceiling truncates long playbook drafts and produces malformed JSON. | A good rule of thumb: if the provider works with the official OpenAI SDKs using the same base URL, key and model, it will work with Cymph. ### Known limitations * **Non-chat endpoints** (legacy text completions, embeddings, images) are not used and cannot be configured here. * **Models that ignore JSON mode** will cause generation and autotagging to fail with parsing errors even though the connection test passes. * **Small local models** frequently lack reliable tool calling. They are fine for generation and autotagging, but expect the AI assistant to behave unpredictably. ## How the test works The **Test** button, available both before and after saving, sends a single chat completion to the configured base URL with the configured model and a one-word user message, limited to 10 output tokens. The test passes when the endpoint returns a completion. It also passes if the endpoint returns an HTTP 400 whose error message mentions `max_tokens`, because that response proves the base URL, API key and model name are all accepted and only the request size was rejected. The test fails on any other error, and the response says why. Every result carries a human-readable `message` and a `details` object so the failure can be diagnosed without server access: # Playbook Hub & Explore Source: https://docs.cymph.io/deployment/settings/hub-explore Enable or disable the public Playbook Hub and in-app Explore section. Users with the On-prem Administrator role can modify the settings for Hub and Explore sections. By enabling hub, users will be able to publish playbooks to a space in their deployment `https://demo-instance.cymph.io/hub` where published playbooks will be available without authentication to the platform. Explore playbooks setting allows users to navigate through the public playbooks from within the web application. 1. Go to **On-prem settings** page * Click on **On-prem** from the navigation menu, then **Settings** 2. Enable or disable Playbook Hub 3. Enable or disable Explore Playbooks Hub Explore # SMTP Source: https://docs.cymph.io/deployment/settings/smtp Configure outbound e-mail for notifications and account recovery. # How to modify mailer settings Users with the On-prem Administrator role can modify the mailer settings. By enabling mailer, users will be able to receive notifications for events as well as perform account recovery. 1. Go to **On-prem settings** page * Click on **On-prem** from the navigation menu, then **Settings** Onprem Settings Navi 2. Edit the **Mailer Settings** * Click on the **Edit icon** next on the mailer settings row Onprem Mailer Edit 3. Key in the settings for the mailer Onprem Mail Edit 4. **Update Settings** when all the information is there # Single sign-on Source: https://docs.cymph.io/deployment/settings/sso Configure Google, GitHub and Entra ID sign-in for a self-hosted deployment. # How to modify SSO settings Users with the On-prem Administrator role can modify the single sign-on (SSO) settings. By enabling an SSO provider, users will be able to login via their preferred identity provider. 1. Go to **On-prem settings** page * Click on **On-prem** from the navigation menu, then **Settings** 2. The SSO settings for Google, GitHub and Entra ID will be part of the settings page Sso Settings 3. You can click the **Edit** button next to the desired provider and change its settings # Google SSO setup Google SSO setup requires a client ID and a client secret from the registered OAuth application. You can see the detailed documentation [here](https://support.google.com/cloud/answer/15549257?hl=en\&visit_id=639214779272767205-531342223\&rd=1). During OAuth app registration, make sure that homepage is set to `https://demo-instance.cymph.io/` and auth callback to `https://demo-instance.cymph.io/api/auth/callback/google` Replace `demo-instance.cymph.io` with the FQDN of your installation. # GitHub SSO setup GitHub SSO setup requires a client ID and a client secret from the registered OAuth application. Go to [github.com](https://github.com) and switch context to the desired organisation. Go to Developer Settings and then to OAuth apps to register a new OAuth application. During OAuth app registration, make sure that homepage is set to `https://demo-instance.cymph.io/` and auth callback to `https://demo-instance.cymph.io/api/auth/callback/github` Replace `demo-instance.cymph.io` with the FQDN of your installation. # Entra ID SSO setup The Entra ID SSO setup requires a Client ID, Tenant ID and a Client Secret from a registered application. **1. Create an App Registration** * Go to portal.azure.com → **Microsoft Entra ID** → **App registrations** → **New registration** * Name it (e.g. "Cymph") * Supported account types: **Accounts in any organizational directory and personal Microsoft accounts** (this matches `tenantId: "common"`) * Redirect URI: `Web` → `https://demo-instance.cymph.io/api/auth/callback/azure-ad` * Replace `demo-instance.cymph.io` with the FQDN of your installation. **2. Get the Client ID and Tenant ID** * After registration, on the **Overview** page copy: * **Application (client) ID** * **Directory (tenant) ID** → not needed since you're using `"common"`, but good to note **3. Create a Client Secret** * Go to **Certificates & secrets** → **New client secret** * Set an expiry, click **Add** * Copy the **Value** immediately (it's only shown once) **4. Set Required API Permissions** (usually already set by default) * **API permissions** → ensure `Microsoft Graph` → `User.Read` is present (it is by default) No admin consent needed for `User.Read` on a public app. # Creating your first playbook Source: https://docs.cymph.io/getting-started/first_playbook # How to create your first playbook from scratch 1. Login to the Cymph platform. 2. Go to the **Playbooks** section * Click on **Library** from the sidebar menu. Library New 3. Click the **New Playbook** button and then the **From scratch** option from the menu that appears. * Alternatively, you can click on the **New Playbook** quick action from the sidebar menu New Playbook New 4. You will be redirected to the **Playbook Editor**. * Your newly created playbook will have a Start Step. 5. Edit your playbook. **Learn more:** Read the [Playbook Editor](/key-features/editor) page for more details on how to design a playbook in the **Playbook Editor** Editor New Ui 8. Save your changes. * After making all your changes, click the **Save Changes** button. **Did you know?** You can also view and [import existing playbooks](/howto/import_playbook). # How to create your first AI-assisted playbook 1. Login to the Cymph platform. 2. Go to the **Playbooks** section * Click on **Library** from the sidebar menu. 3. Click the **New Playbook** button and then the **Generate with AI** option from the menu that appears. * Alternatively, you can click on the **New Playbook** quick action from the sidebar menu 4. You will be redirected to the Cymph AI assistant 5. From there, an interactive process will start where you can describe your requirements 6. At the end of the process, a playbook draft will be available for review. By clicking on the Review button, you will be able to view the generated playbook and also edit it if necessary Ai Assisted Review 7. From the preview editor, you can save the playbook by clicking on the **"Save to..."** button Ai Draft Save 8. Before saving the playbook, a modal will appear to complete the RACI matrix and review settings for the playbook Save Ai Draft Settings 9. Once the required settings are filled in (Responsible, Accountable and Review Frequency are mandatory), you can click on the Save button. The playbook will be saved to the current workspace library as draft If the option to generate playbooks with AI does not appear, the AI settings of your instance are not configured # Navigating the Cymph platform Source: https://docs.cymph.io/getting-started/navigating # Overview The Cymph main view consists of three main areas: 1. **The top bar**: On the top right of the interface, you can find the Workspace Selector, Search bar, Notifications, light/dark theme switcher and Account Settings. 2. **The navigation menu**: On the left side of the interface, you can find your playbooks, manage your integrations, view and manage your assets, browse the mindmaps, view your documents and manage your organisations. 3. **The main display area**: The main display area shows the content from the selected navigation feature such as lists of playbooks. Nav Main With Workspaces Theme **Did you know?** By clicking on the Cymph logo on the top left corner, you will be redirected to the Playbooks sections and see all playbooks owned or shared with you. # Navigating through the platform The navigation menu includes the following sections: * The **Playbooks** section where all your playbooks reside. All users will see the Playbooks section. * The **Organisation** section, that contains the pages to view and manage organisation members and see details about available roles. * The **Manage** section, that contains the pages for managing Ensembles, Integrations, Execution History and Jobs History. * The **Mind Maps** section, where you can configure your presets for the frameworks of interest and perform you customised gap analysis * The **Assets** section, where the pages for Agents and Authentication Information management reside. * The **Workspaces** section, where you can view and manage your private and organisational workspaces The navigation menu can be collapsed to save space by clicking the Expand/Collapse button at the top of the sidebar: Nav Collapse New # Notifications By clicking on the notifications icon on the top section of the platform, a list of the most recent notifications will appear. Notifications2 From the notifications panel, you have the options to: * Show unread only. * Mark all notifications as read. * Mark an individual notification as read/unread. * Delete a notification. # Help and support To access the documentation, click the **Help & Support** link in the bottom left corner of the platform. Help2 From the menu that appears you have the option to: * Check the online documentation at [https://docs.cymph.io](https://docs.cymph.io) * Get support via e-mail. The support e-mail is [support@cymph.io](mailto:support@cymph.io) * Contact sales (demo mode only). The contact e-mail is [contact@cymph.io](mailto:contact@cymph.io) # Signing up to Cymph Source: https://docs.cymph.io/getting-started/signup # How to sign up to Cymph 1. Visit the URL of your Cymph installation 2. From the Login/Signup Page select Sign Up Signup With Entra 3. There are multiple options to create your account 1. Sign up with GitHub 2. Sign up with Google 3. Signup with Entra ID 4. Create an account with your personal email 4. Creating an account with personal email (step 3c) will require additional information to be provided a. Your name (required) and surname (optional) Signup Name Surname b. A strong password. Please refer to the password criteria guide. Signup Password c. Once the name and password steps are completed, we will send a verification email to the email address you have provided. The sender will be [noreply@cymph.io](mailto:noreply@cymph.io). Signup Verification Email d. In order to complete the signup, please click the link on the e-mail you will receive and your account will be ready to login 5. Creating an account with GitHub OAuth (step 3b) will redirect the user to login to its GitHub account and allow then continue to Cymph’s Platform Sign Up3 Github 6. Creating an account with Google OAuth (step 3c) will redirect the user to login to its Google account and allow then continue to Cymph’s Platform Sign Up3 Google 7. At the end of the signup process, the user will be redirected back to the login page so the user can login and use the Cymph platform. # Manage presets Source: https://docs.cymph.io/how-tos/create-and-manage-presets Presets allow you to customise frameworks to your organisational environment and requirements. In this guide, we are going to show you how to create and manage a preset based on the MITRE ATT\&CK for Enterprise framework. A similar process is followed for other frameworks. # How to create a preset 1. Go to the **Mindmaps** section * Click on Mind maps from the navigation menu 2. Create a preset * Click on **Create Preset** quick action from the navigation sidebar * The preset creation wizard will start Createpreset1 ## Step 1: Select a preset base You can choose to start from either scenarios (for example Phishing, Ransomware etc). or from specific frameworks. If you select to start from scenarios, you will go immediately to step 2. Preset Base ## Step 1b: Choose a framework If your preset base is a specific framework, the next step is to select the framework of interest. Currently, we support MITRE ATT\&CK for Enterprise, MITRE D3FEND, MITRE ATLAS, NIST CSF 2.0, ISO27001, ISO27002:2022, NIS2, GDPR and DORA. Frameworks are versioned so at this step you are also able to select the desired version. Choose With Version ## Step 2: Select the scope source There are four available options : 1. Select the framework elements manually 2. Import from a MITRE ATT\&CK Navigator layer (only when MITRE ATT\&CK for Enterprise or MITRE ATT\&CK for ICS framework is selected at step 1) 3. Import from SIGMA rules (only when MITRE ATT\&CK framework for Enterprise is selected at step 1) 4. Import tags from an existing detection system (only when MITRE ATT\&CK framework for Enterprise is selected at step 1). If you select that step, you will also need to select an integration. Currently, Wazuh, Microsoft Sentinel, Splunk Enterprise Security and Cortex XSIAM are supported. Scope Source New ### Importing a MITRE ATT\&CK Navigator Layer In the first step, you will need to select the files that need to be imported. At this step, you can also control the behavior of tactics expansion. By default, if a tactic ID is seen in the data, it will not be expanded to all its techniques. At this step you can also quickly change the framework version, if you suspect or verify a version mismatch. Nav Layer Step1 Once you click **Validate,** you will be redirected to the validation result page. You will be able to see potential errors with the data such as: * Wrong layer format * No tags in the data * Tags found in the data are not part of the framework * The layer belongs to a different domain (e.g. you imported a Navigator layer for ICS but the selected framework was Enterprise)
Nav Layer Success ### Importing SIGMA rules The process is the same as importing Navigator layers. For Sigma rules, the tags are extracted from the `tags` attribute and the format is expected to be `attack.`. Tactic tags are ignored during processing. For example: ```text theme={"system"} tags: - attack.credential_access - attack.t1558.003 ``` ### Configure live source In the first step, you will need to select the integrations to be used. The following integrations are supported: * Microsoft Sentinel * Wazuh * Splunk Enterprise Security * Cortex XSIAM At this step, you can also control the behavior of tactics expansion. By default, if a tactic ID is seen in the data, it will not be expanded to all its techniques. At this step you can also quickly change the framework version, if you suspect or verify a version mismatch. Scope Live Step1 Once you select one or more integrations, click **Continue.** You will then be redirected to a summary of the results. When multiple integrations are selected, Cymph combines the valid MITRE ATT\&CK identifiers returned by the selected sources. Duplicate identifiers are included only once in the resulting scope. Per-source errors will be reported. If there is at least 1 tag and no errors are found, you will be able to proceed to the next step. Tags that are not valid for the selected framework version are surfaced as validation errors and are not silently imported, remapped or discarded. If a version mismatch is detected, you can return to the previous step and select the appropriate framework version. Detection-based scopes use event-driven synchronization. Cymph refreshes the scope from the configured detection sources when the preset is accessed through the UI or API. Presets that use live detection sources do not rely on a scheduled background refresh. ## Step 3: Select the relevant elements of the framework for your preset You can select individual techniques or entire tactics that are relevant to you. If on step 2, you selected a detection-based scope (live source) Definescope You can even select individual sub-techniques. You can expand and collapse a technique to show/hide the associated sub-techniques. Expand Collapse Techniques Specifically for MITRE ATT\&CK for Enterprise, you can filter the view by product. For example, by selecting Windows only the techniques associated with the Windows platform will be displayed so you can easily select all of them by clicking on the **Select all displayed techniques.** Select Windows You can expand and collapse all techniques by clicking Expand all/Hide all from the top right corner of the matrix ## Step 4: Configure the preset settings Once you have selected the relevant techniques/sub-techniques, you need to provide additional information about the preset: * Preset name (required): a name to identify this preset. * Description (optional) * The playbooks that will be used to calculate the coverage of the preset. The available options are: * Created by me: only the playbooks created by you will be used * Shared with me: only the playbooks that are shared with you will be used * Public playbooks: only publicly shared playbooks will be used * A filter that was saved from the playbook management system. See Filter playbooks for more details * Share preset: enable it if you want to share this preset with your organisation * Use automatic framework mappings when manual mappings are not set: enable this if you want to use the AI-suggested mappings of the playbooks in case you have not manually mapped your playbooks Preset Config ## Step 5: Set coverage criteria In order for a playbook that is mapped to a technique/sub-technique to be considered that it covers that technique/sub-technique, we should define the criteria when evaluating it. Currently, we support two different criteria: 1. **Playbooks exists in your workspace**: no additional properties need to be met, the sole existence of the playbook is enough. 2. **Playbook matches selected status**: the playbook must have a certain status in order to be considered. The available statuses are Planned, In progress, In review and Completed. Preset Coverage Click on **Save Preset** and your preset is ready! # How to edit a preset 1. Go to the page of the preset * Select **Mind maps** from the navigations menu, and then select your preset from the **My Presets** dropdown menu Presetnav 2. Open the action menu of the preset * Click on the triple dot action button next to the preset name Preset Action 3. Edit your preset * Select the **Edit Preset** option Edit Preset 4. The edit process follows the same steps as the preset creation. At each individual step modify the information you want. # How to delete a preset 1. Go to the page of the preset * Select **Mind maps** from the navigations menu, and then select your preset from the **My Presets** dropdown menu 2. Open the action menu of the preset * Click on the triple dot action button next to the preset name 3. Delete your preset * Select **Remove Prese**t from the dropdown menu * Confirm that you want to remove the preset # How to duplicate a preset 1. Go to the page of the preset * Select **Mind maps** from the navigations menu, and then select your preset from the **My Presets** dropdown menu 2. Open the action menu of the preset * Click on the triple dot action button next to the preset name 3. Duplicate your preset * Select **Duplicate Preset** from the dropdown menu A copy of your preset will be created with the suffix "(copy)" appended to the original name. # Deploy playbooks Source: https://docs.cymph.io/how-tos/deploy-playbooks In order to deploy a playbook, at least one integration with deployment capabilities must be configured. See [Manage integrations](/integrations/manage) to learn how to set one up, and the [integrations overview](/integrations/overview#what-each-integration-can-do) for what each integration supports. The guides below are based on the assumption that at least one integration is present. A playbook can be deployed in two ways, depending on the target: * **As a workflow** — to a SOAR, automation, or ticketing system such as Cortex XSOAR, n8n, StackStorm, JIRA, ServiceNow, or DFIR-IRIS, where it becomes an executable workflow or a set of tickets or tasks. * **As documentation** — to a documentation system such as GitHub, GitLab, GitBook, SharePoint, or Confluence, where the playbook's documentation is published as Markdown or PDF. Publishing documentation writes to the target system, so the integration needs write credentials. If a documentation target is missing from the deploy dialog, or the deploy fails while Test Connection succeeds, the integration is most likely still configured with read-only permissions — see that integration's page for the additional permission required. ## Deploy a playbook from the playbook management system 1. Go to the **Playbook Management System** 2. Select the **Deploy** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu Deploy Menu 3. Select an integration from the dialog that appears Deploy Select Integration 4. Test for compatibility (optional). * Click the **Test Compatibility** button. If the playbook can be deployed at the selected integration, a message “Playbook can be deployed” will appear. 5. Deploy the playbook * Click the **Deploy** button Invalid playbooks cannot be deployed. For invalid playbooks, the deploy icon will be disabled Users with the Viewer role are not allowed to deploy playbooks. For those users, the deploy icon will be disabled ## Deploy a playbook from the playbook editor 1. Open the playbook you want to deploy in the editor 2. Deploy the playbook * Click the **Deploy** button from the workflow view Deploy From Editor 3. Follow the steps as described in the previous section for the deployment ## View the deployment history 1. Go to the **Deploy History** page * From the main navigation menu click **Manage** **-> Deploy History** Deploy History Menu 2. The list of deployed playbooks will appear 3. There are several options for each deployed playbook: * **Navigate the pushed playbook**: this option will open a new tab that will go to the target platform and open the deployed playbook. Not all integrations provide a direct link to playbooks * **See the deployed playbook**: see the contents of the playbooks as translated for the target integration * **See the source playbook**: see the contents of the original playbook as of the time of deployment * **Delete the history entry** Deploy Actions # Filters Source: https://docs.cymph.io/how-tos/filter-playbooks The playbook management system includes a set of filters so you can search through the list of playbooks. Note that search filters will change across views. # Filtering playbooks Available filters are displayed by clicking on the Filters bar on top of each playbook table: Filters Button You can select one or more available filters. An example that filters by the label "phishing" is shown below Filters Label Example Not all available filters are displayed at once due to space reasons. You can hover over the **Add filter** button to see more filters: All Filters Once you click on one of the filters of the Add filter menu, it will be appended to the list of filters shown. Add Filter Activated The active filters are displayed below the available filters row: Filters Active By clicking the close (x) icon next to each active filter, that filter will be removed. If you want to clear all filters at once, you can click on the **Clear All** button Filters Clear All # Saving filters If you use a set of filters frequently, you might find it convenient to save them for further use. Once a set of filters is applied, the **Save Filters** button will become active. ## Creating a new saved filter 1. Click on Save Filters button Save Filters Button 2. Provide a name for the saved filter in the dialog box that appears 3. **Save filter** Save Filter Name ## Using saved filters 1. From the filter bar, click Saved Filters * The list of your saved filters will appear Saved Filters Select 1. Select a saved filter 2. The selected filter will be immediately applied, overriding any existing filters ## Managing saved filters 1. From the filter bar, click Saved Filters * The list of your saved filters will appear 2. Hovering on a saved filter, you will see the options to: * Rename your saved filter * Delete it Saved Filter Actions # GitHub backup Source: https://docs.cymph.io/how-tos/github-backup GitHub Backup allows you to automatically back up your playbooks to a GitHub repository. This feature ensures your playbooks are safely stored and version-controlled, providing an additional layer of data protection and enabling easy recovery when needed. ### Step 1: Create a GitHub Integration Navigate to **Integrations** and select **GitHub Backup** to create a new integration. Github Integration You will need to fill the following configuration fields: **Name**: a descriptive name for this integration (e.g., "Production Playbooks Backup") **GitHub token**: Your GitHub Personal Access Token with `repo` scope ### Generating a GitHub Token If you don't have a GitHub Personal Access Token: 1. Click the **Generate Token** link below the GitHub Token field 2. You will be redirected to GitHub with the appropriate scopes pre-selected 3. Follow GitHub's instructions to create the token 4. Copy the generated token and paste it into the **GitHub Token** field Once you've entered the integration name and token, click **Next** to proceed. You can click on **Test Connection** to make sure everything is working before going to the next step ### Step 2: Configure Backup Settings 1. Select the repository you want to backup your playbooks to 2. Once you selected a repository, select a target branch 3. Select how often you want your playbooks to be backed up. Available options are: | Frequency | Description | | --------------- | ------------------------------- | | **Every hour** | Backups run once every hour | | **Every Day** | Backups run once every 24 hours | | **Every week** | Backups run once every 7 days | | **Every month** | Backups run once every 30 days | 4. Under the **Playbooks** section, select which playbooks to include in the backup: * **Individual**: Back up your personal playbooks * **Organisation**: Back up playbooks belonging to your organisation You can select both options to back up all playbooks, or select only one to back up a specific set. Github Settings ## Repository Structure Once backups are created, your GitHub repository will be organized with the following folder structure: ``` |── individual/ |── .json |── .json |── ... |── organisation/ |── .json |── .json |── ... ``` The folder `individual/` contains all your personal playbooks. The folder `organisation/` Contains all playbooks from your organisations Each playbook is saved as a JSON file with the naming format: `_.json` ### Jobs History The **Jobs History** panel provides visibility into your backup operations. You can find it under Manage -> Jobs History from the navigation menu For each backup job, you can view: * **Status** — Whether the backup completed successfully or failed * **Duration** — How long the backup operation took to complete * **Started At** — When the backup was executed * **Message** — A logging message if something went wrong Use this panel to verify your backups are running as expected and troubleshoot any issues. **Organisation membership:** If you leave an organisation, backups for that organisation's playbooks will automatically stop. You will only receive backups for organisations where you are an active member. **Token expiration:** If your GitHub Personal Access Token expires, you will receive a notification on the next scheduled backup informing you that the token is no longer valid. To resume backups, generate a new token and update the integration settings. # Asset management Source: https://docs.cymph.io/howto/asset_actions ## How to import assets from files 1. Go to the **Assets** page * Click on Assets from the navigation menu, then select **Assets**. Assets Newnav 2. Import assets from a file * Click on the **Import Assets** button at the top right corner Import Assets Nav 3. From the dialog that appears, you can download the templates and fill them in with your assets. The template is provided into three formats: XLSX, XLS and CSV Asset Templates 4. Upload the file containing the assets and proceed with validation * Click the **Validate** option Asset Import First Steps 5. There might be a case that there will be name conflicts during imports. In that case, you will need to provide the course of actions for handling the conflicts. Two possible options exists: * Create copies: in that case, the assets will be created with the suffix "\_copy" appended to their name. * Replace assets: the conflicted assets will be replaced by the ones contained in the uploaded file Assets Conflicts 6. You can see more details about the conflicts by expanding the top section of the conflict dialog box Asset Conflicts Expand 7. The next step is to review and import the assets. If there are any issues with the data, you will be able to see the errors. In that case, the import cannot continue; all the errors will need to be fixed. You can expand the relevant sections to see more details about the errors. Asset Import Errors 8. If no errors exists, you will be able to import assets. Asset names are unique per asset type, e.g. you cannot have two assets with type "FTP Server" and the same name but you can have the same name across types (for example, an asset named "Asset1" and type "FTP Server" and another one also named "Asset1" and type "SSH Server"). ### How to populate the assets file from the template The template file contains the following fields: * **Name**: this field is mandatory. Asset names are unique per asset type. * **Description**: provides a description of your asset. * **Type**: the asset type. The list of available asset types can be seen from the Asset Types page (navigate to Assets section and then choose Asset Types from the navigation sidebar). * **Labels**: this field is optional. It is a comma-separated list of labels that will be assigned to the asset. * **Domain name**: optional, denotes the domain name assigned to the asset. * **IPv4**: optional, a comma-separated list of the IPv4 address(es) assigned to the asset. * **IPv6**: optional, a comma-separated list of the IPv6 address(es) assigned to the asset. * **URL**: optional, a comma-separated list of the URL(s) assigned to the asset. * **Mac Address**: optional, a comma-separated list of the MAC address(es) assigned to the asset. * **Vlan**: optional, a comma-separated list of the VLAN tag(s) assigned to the asset. * **Port**: optional, denotes the port where the asset listens to. * **State**: optional, denotes the current state of the asset and can be: "Active", "Broken", "Don't show", "In repair", "Non-active", "Sold", "Spare", "Stock", "Stolen". * **Notes**: optional, additional notes for that asset. ## Importing Assets from Wazuh Connect your Wazuh deployment to Cymph and bring its monitored endpoints straight into your asset inventory — no manual data entry required. ### What gets imported Cymph reads your Wazuh **agents** and turns each one into a host asset in your workspace. For every agent you import, Cymph automatically captures: * Its hostname * The host's operating system and architecture * Its IPv4 and IPv6 addresses * When the agent last reported Each imported asset is tagged as coming from Wazuh, so you can always tell where it originated and re-run the import later without creating duplicates. Agents are imported as Linux, Windows or macOS hosts. An agent running any other operating system, or one that has not yet reported its system inventory to the manager, is skipped. ### How it works 1. Connect your Wazuh integration to the workspace (one-time setup). See [Wazuh](/integrations/detection/wazuh). 2. Pick the agents you want to bring in. 3. Cymph pulls them from Wazuh and adds them to your asset inventory. If an asset with the same name already exists, Cymph keeps both by importing the new one under a clearly marked name rather than overwriting your existing data. ## Importing Assets from Nessus Upload a Nessus scan report and let Cymph turn the discovered hosts and services into assets in your inventory. ### What gets imported From a Nessus report (`.nessus` file), Cymph creates: * **One asset per scanned host**, with its operating system, IP and MAC addresses, and hostname. * **An asset for each service** Nessus detected on that host — for example web servers, databases, DNS servers, mail servers, file servers, remote-access services, printers, and identity services. Where the report is specific enough, Cymph also records the product (such as MySQL, PostgreSQL, or Tomcat). This means a single host can produce several assets: the host itself plus one for each service running on it. ### How it works 1. Upload your Nessus scan report. 2. Cymph reads it and shows you what it found, sorted into assets that are ready to import, ones that need attention, and any that already exist in your inventory. 3. Review the results and confirm the import. In case of name conflicts, you will be asked how to resolve them: either by replacing the existing assets or make the newly imported assets have a unique name. ## Importing Assets from Azure Connect your Azure environment to Cymph and import your cloud resources directly into your asset inventory, keeping Cymph in sync with what you run in Azure. ### What gets imported Cymph pulls resources from your Azure subscriptions and maps them to the right Cymph asset type. Supported resources include: **Compute** * Virtual Machines * VM Scale Sets * BareMetal Instances **Apps & containers** * App Services * Container Apps * AKS (Kubernetes) Clusters * Azure Red Hat OpenShift Clusters * Azure Spring Apps **Databases & caches** * Azure SQL Server * Azure Database for PostgreSQL * Azure Database for MySQL * Cosmos DB Accounts * Cosmos DB for MongoDB (vCore) Clusters * Azure Cache for Redis **Identity** * Users * Service Principals * Managed Identities **Storage & secrets** * Storage Accounts * Key Vaults ### How it works 1. Connect your Azure integration to the workspace (one-time setup). 2. Choose the resources you want to bring in. 3. Cymph imports them and maps each one to the matching Cymph asset type. ## Importing Assets from AWS Connect your AWS environment to Cymph and import your cloud resources directly into your asset inventory, keeping Cymph in sync with what you run in AWS. ### What gets imported Cymph pulls resources from your AWS account and maps them to the right Cymph asset type. Supported resources include: **Compute** * EC2 Instances * Autoscaling Groups * Dedicated Hosts **Serverless & containers** * Lambda Services * EKS Clusters * ECS Clusters * App Runner Services **Web & Apps** * Elastic Beanstalk Environments **Databases** * RDS Instances * RDS Clusters * DynamoDB Tables * DocumentDB Clusters * ElastiCache Clusters **Storage & secrets** * S3 Buckets * Secrets (no values fetched) * KMS Keys (no values fetched) **Networking** * Load Balancers **Identity** * IAM Groups * IAM Roles * Instance Profiles ### How it works 1. Connect your Azure integration to the workspace (one-time setup). 2. Choose the resources you want to bring in. 3. Cymph imports them and maps each one to the matching Cymph asset type. ## How to create an asset manually 1. Go to the **Assets** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Add a New Asset. * Click on the **Add New Asset Manually** button at the top-right corner. Add Asset Manually 3. Choose an asset type. * Asset types are grouped into two categories, **Peoples and Places, Software Assets, Hardware Assets** and **Cloud Services.** * Select the desired category * Click on the **radio** button next to the desired type to select it. * Click **Next** once the desired type is selected. Asset Select Type 4. Create the asset. * Enter the asset details. Fields marked with an asterisk (\*) are mandatory. * Provide the **Access Type**. By default, the access status of the asset is **Private**. * **Private access** means the asset is only visible to you. * **Shared access** means the asset is visible to you and your organisation members. * **Public access** means the asset is visible to all Cymph users. * Provide a set of labels for the asset (optional) * **Location information** includes details about the asset, like name, description, network information and geolocation information. You can add multiple location information fields. * **Contact information** includes details about the people that need to be contacted for this assets * **Account information** lists information about username and roles that are related to this asset. * Provide a **state f**or the asset (optional). The state can be: active, broken, don't show, in-repair, non-active, sold, spare, stock, stolen * **Criticality**: define the criticality level of the asset. Possible values are: Low, Standard, High and Critical * **Recovery time objective** defines the RTO time in minutes * **Recovery point objective** defines the RPO time in minutes * **Environment** includes a references to the environment type the asset is used in: Test, Dev, Staging or Production * **Owned by:** one or multiple asset owners. Owners are accountable for the asset * **Managed by**: one or multiple asset managers. * **Depends on**: a list of assets that this asset depends one * **Used by**: a list of assets or team that this asset is used by * **Runs on / Hosted by:** a list of assets that are used to run or host this specific asset * **Part of / Parent**: the parent asset * Provide optional **notes** * Click **Create**. Edit Asset Details # How to update an asset 1. Go to the **Agents** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Click the **Edit** icon next to the asset that needs update. Asset Edit 3. Update asset details. * Click the **Update** button once all information is updated. 4. The list of assets is automatically updated. # How to delete an asset 1. Go to the **Agents** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Delete the asset. * Click the **Delete** icon next to the asset you want to delete. Asset Delete 3. Confirm deletion. * Click the **Delete** button on the confirmation dialog. 4. The list of assets is automatically updated. # How to duplicate an asset 1. Go to the **Agents** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Click the **triple dot** icon **⫶** to open the **actions** menu for the playbook you want to duplicate. Edit Action Menu 3. Select the **Duplicate** action 4. Duplicate the asset. * Provide a name for the asset. By default the name of the source asset will be used followed up by the “(copy)” suffix. * Click on the **Duplicate** button. Asset Duplicate 5. The list of assets will be automatically updated and show the new asset. Assets need to have unique name per asset type. For example, two assets of the Group type cannot have the same name. However, assets with different types can have different names. # How to share an asset 1. Go to the **Assets** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Click the **triple dot** icon **⫶** to open the **actions** menu for the playbook you want to duplicate. 3. Select the **Share** option. 4. Choose the access type. * From the dialog box that appears, select the share mode for your asset. * By selecting an option, the access type is changed automatically. Asset Share # How to export an asset 1. Go to the **Assets** page. * Click on Assets from the navigation menu, then select **Assets**. 2. Click the **triple dot** icon **⫶** to open the **actions** menu for the playbook you want to duplicate. 3. Export the asset. * Click the **Export** option. 4. The asset will exported as a comma-separated CSV file, named after the asset name and a .csv suffix, with the following schema: > Name,Type,Description,Labels,Domain Name,IPv4,IPv6,URL,Mac Address,Vlan,Port,State,Notes If you want to remove an asset from favorites, click the Favorites icon again. The icon will turn white. # How to view supported asset types 1. Go to the **Asset Types** page * Click on Assets from the navigation menu, then select **Asset Types** Asset Types Na 2. From there you can browse and search the existing asset types # Ownership model | Source | Owner | What is editable | | ---------------------------------------- | -------- | ----------------------------- | | Cymph | Cymph | All asset fields | | Files (templates or Nessus scan reports) | Cymph | All asset fields | | Live systems (Azure and Wazuh) | External | Labels, description and notes | # Create a playbook Source: https://docs.cymph.io/howto/create_playbook # How to create a playbook ## Creating a playbook from scratch 1. Go to the **Playbooks** section * Click on **Library** from the sidebar menu. Pb Menu2 2. Click the **New Playbook** button and then the **From Scratch** option from the menu that appears. * Alternatively, you can click on the **New Playbook** quick action from the sidebar menu Structure2 3. You will be redirected to the **Playbook Editor**. * Your newly created playbook will have a Start Step. 4. Edit your playbook. **Learn more:** Read the [Playbook Editor](/key-features/editor) page for more details on how to design a playbook in the **Playbook Editor** Blankpb2 5. Save your changes. * After making all your changes, click the **Save Changes** button. **Did you know?** You can also view and [import existing playbooks](/howto/import_playbook). ## AI-assisted playbook generation In case you dont want to start from scratch, you can provide a description of your playbook so it can be automatically created for you. 1. Go to the **Playbooks** section * Click on **Library** from the sidebar menu. 2. Click the **New Playbook** button and then the **AI-assisted Generation** option from the menu that appears. 3. Provide your instructions 4. Click on **Generate Playbook** when you are done Pb Genai The playbook generation happens at the background. You can track the generation status from the progress dialog box at the bottom right corner of the application: Genai Complete When the playbook is ready, you will be able to see it in your Playbook Management System # Manage ensembles Source: https://docs.cymph.io/howto/ensembles Ensembles are groups of organisations. Users can add or remove one or more organisations to an ensemble and then share playbooks to that ensemble. # How to create an ensemble 1. Navigate to the **Ensembles** page. * From the account settings menu, select **Ensembles.** Ensembles As 1. Click the **New Ensemble** button. Ensembles As New 2. Add the information about the ensemble in the **Add Ensemble** dialog box that appears. * Give it a name. Ensemble names are unique per user. * Enter the list of organisations that will be part of the ensemble. 3. Add the ensemble. * Click on **Add Ensemble.** * The new ensemble will appear in your list of ensembles. # How to update an existing ensemble 1. Go to the **Ensembles** page of your account settings. 2. Click the **Edit** icon next to the ensemble you want to modify. * An **Edit ensemble** dialog box with the details of the ensemble will appear. Ensembles As Edit 3. Enter the new information for the ensemble. * Provide a new name (optional). * Update the list of organisations (optional). * Click on **Update Ensemble** once the updated information is keyed in. 4. The list of ensembles will be updated with the latest information. # How to delete an ensemble 1. Go to the **Ensembles** page. 2. Click the **Delete** icon next to the ensemble you want to delete. Ensembles As Delete 3. Click **Delete** to confirm the deletion. 4. The list of ensembles will be updated automatically. # Execute playbooks Source: https://docs.cymph.io/howto/execute-playbooks Cymph supports executing playbooks that consist entirely of manual steps, giving operators a structured, trackable way to carry out procedures that don't rely on automated tooling. Rather than treating manual work as a gap in coverage, Cymph turns it into a first-class workflow: each step is acknowledged, timestamped, and recorded as part of a workbook, creating a full audit trail of what was done, by whom, and when. For further details about the execution concepts, editor and tasks overview visit the [Executions](/key-features/executions) page ## Executing via the playbook management system Playbooks can be executed either via the playbook management system or via the editor. Each execution is named. In order to execute a playbook from the management system: 1. Open the action menu for the playbook you want to execute 2. Select **Run Playbook** from the action menu * If the option is disabled, this means that the playbook is ineligible for execution. Run Playbook Menu 3. Provide a name for the execution and optionally a description in the dialog that appears * At this stage you can also change the default assignees. If you have edit access to the playbook, an **Edit Assignees** will appear. By clicking on it, a playbook editor will open in a new tab 4. Click on **Run Playbook** to start the execution. You will be redirected to the execution editor ## Executing via the playbook editor 1. From the workflow actions panel on the left side, click on Run Playbook 2. Provide a name for the execution and optionally a description in the dialog that appears Run Playbook From Editor # Import playbooks Source: https://docs.cymph.io/howto/import_playbook # Overview Cymph allows the seamless import of playbooks found in different formats and systems. The following import options are available: * Cymph playbooks - from files * Cortex XSOAR playbooks - both from files and live system * Cortex XSIAM playbooks - both from files and live system * n8n workflows - both from files and live system * MISP playbooks - from files * CACAOv2 playbooks - from files # How to import a playbook 1. Go to the **Playbooks** section * Click on **Library** from the sidebar menu. Pb Menu2 2. Start the **Import** process * Click on the **Import** button Import Button 3. Select the type of playbook you want to import Import Select Type2 The next steps will depend on the import methods supported for the selected type - from files and/or from a live system # Importing from files Let us select to import Cymph playbooks as an example for importing from files. 1. Once we select **Cymph playbooks** from the type selection modal, the file import dialog will appear 2. Select (or drag and drop) the files you want to import and then click on **Validate** Import Selected Files 3. In the validation phase, you will see summary information about all playbooks in total and for each imported playbook separately. If a playbook is valid, you will see the Valid label next to its name: Import Pb Valid If a playbook is invalid, the Issues label will appear. You can expand the section to see the detected errors. Import Pb Invalid 4. You can enable the **automatic framework mappings** to map imported playbooks to the MITRE ATT\&CK for Enterprise framework. If the playbooks are already tagged, the existing tags will be used instead. 5. Once you are ready, you can import all valid playbooks 6. A dialog box will appear to show the import progress. Once the import is complete, you can navigate to your playbooks via the **Open My Playbooks** button Import Progress # Importing from a live system For certain types, like Cortex XSOAR, Cortex XSIAM and n8n, you can also import from a live system. As a pre-requisite, a working integration must exist. In this section, we will use a live Cortex XSOAR system as an example. 1. Select **Cortex XSOAR Playbooks** from the import dialog 2. From the followup dialog, select From **Connected Cortex XSOAR Instance** Import Cortex Live 3. A list of playbooks found in the live system will be displayed. * By default, the latest integration will be used as the default target. If multiple integrations exists, select them from the dropdown menu Import Xsoar Live1 4. Select the playbooks you want to import. You can quickly filter out the displayed playbooks based on the playbook status and playbook name Import Xsoar Live Filter 5. Click the Validate button to start the validation step. 6. The validation step is exactly the same as the one described above for file imports # Ownership model Playbooks created via the editor, the AI assistant or imported from files are fully owned by the Cymph platform. If playbooks are imported from SOAR or automation platforms, only the documentation and metadata are editable; the workflow is read-only. When playbooks are imported from repositories and KMSes, we allow only the editing of workflows and metadata. | Source | Owner | What is editable | | ------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------- | | Playbook editor or AI assistant | Cymph | Workflow, documentation and all metadata | | Files | Cymph | Workflow, documentation and all metadata | | SOAR / Automation platforms
(Cortex XSOAR, Cortex XSIAM,
Splunk SOAR, Logic Apps, n8n) | External | Documentation and all metadata | | KMS / Repositories (Confluence,
SharePoint, GitHub, GitLab, GitBook) | External | Workflow and all metadata | # Modify playbook settings Source: https://docs.cymph.io/howto/modify-playbook-properties Playbooks come with certain settings that are used within their lifecycle. The settings can be modified either via the playbook editor as well as the playbook management system. # Available Settings The table below summarises the available settings for playbooks. Additionally it states from which part of the platform - editor or playbook management system (PMS) - each setting can be modified from | Setting | Description | Editable
via Editor | Editable via
PMS | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------- | | Description | A description of the playbook | Yes | No | | Alert types | Relevant alert types. It is a free-form field
and can have multiple value | Yes | Yes | | Incident types | The relevant incident type, e.g phishing,
ransomware etc. Users can also add their
own incident type | Yes | Yes | | Incident Response Stage | The incident response stage can be attack,
detection, remediation, investigation,
prevention. Users can also add their own | Yes | Yes | | Impact and Severity | The impact and severity of the playbooks.
Values can be Not Specified, Low,
Medium, High and Critical | Yes | Yes | | Asset types | The associated asset types. Users can
specify multiple asset types. For more
information about asset types look at
Asset Management documentation. | Yes | Yes | | Assets involved | The assets referenced in the playbook | Yes | No | | Review Settings | The assigned reviewer and review frequency
for the playbook. | Yes | Yes | | Valid From / Until | The validity period of the playbook. | Yes | No | | RACI matrix | The Responsible, Accountable, Consulted
and Informed matrix of the playbook. | Yes | No | | Attachments | Files attached to the playbook. | Yes | No | | External References | Any external references to this playbook. | Yes | No | # Modifying via the Playbook Management System 1. For the playbook you want to modify the settings for, hover over and open the action menu * Click on the triple dot icon on the hover panel that appears 2. Go the Playbook Settings menu and select the setting you want to modify Pb Settings Modify Pms # Modifying via the Playbook Editor 1. From the top bar, open the Playbook Settings drawer * Click on the **Playbook Settings** icon Pb Settings Editor 2. From the settings drawer that appears, modify the setting you want Pb Settings Drawer # Playbook templates Source: https://docs.cymph.io/howto/playbook-templates You can save a playbook you have access to as a template so you can re-use it in the future as a starting point. ## How to create a template 1. For the playbook you want to create a template from, hover over and open the action menu * Click on the triple dot icon on the hover panel that appears 2. Select the **Save as Template** option from the menu that appears Save As Template Menu 3. In the popup that appears, provide a name for the template and optionally a description 4. Click on **Save template** to save your template Save As Template Options Both the workflow and documentation part of the playbook will be saved into the template. Labels and IR stage are also saved. ## How to create a playbook from a template There are two ways to create a playbook from a template. The first one is via the Templates area of the Playbooks section. The second one is via the New Playbook button ### From Templates area 1. Go to the **Templates** area Templates Area Menu 2. Hover over the template you want to use. The actions menu will appear 3. Select the **Use template** action Use Template Hover 4. You will be redirected to the editor with the contents of the template being loaded ### From the New Playbook menu 1. Go to the Playbook library 2. Click on the **New Playbook** button from the top right corner and select **Start from template** New Start From Template 3. From the modal that appears, hover over the template you want to use and click on the **Select template** action Use Template Modal 4. You will be redirected to the playbook editor with the contents of the selected template loaded # Perform actions on a playbook Source: https://docs.cymph.io/howto/playbook_actions # How to add and remove labels 1. Go to the **Playbook Management System** 2. Hover over the playbook for which you want to manage labels 3. Click on the **Labels** action Labels Action The labels dialog box will open up. The existing labels will appear on the top. In the middle, you will see all the labels used across all your playbooks. In order to remove an existing label, click on the close icon next to its name: Label Delete If you want to add an existing label, click it from the middle panel and it will be appended to the list of playbook labels: Labels Add If you want to add a new label that does not exist, type its name in the top panel and then click on the create action at the bottom of the dialog box: Labels New # How to set mappings 1. Go to the **Playbook Management System** 2. Select the **Set Mappings** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. Select the framework for which you want to add a mapping 4. Select the mappings for the chosen framework you want to add 5. If you want to remove a mapping, click on the close icon next to each mapping 6. Click on **Update mappings** to save the mappings to the playbook Mappings Set ## AI suggestions If you are not sure about which mappings are appropriate, you can ask for suggestions from our AI. 1. Click the **Suggest** button 2. The suggestions will appear after a while 3. You can select to add individual suggestions or click on **Add All Mappings** to add them all at once. Mappings Add Ai # How to change playbook settings 1. Go to the **Playbook Management System** 2. Hover over the playbook for which you want to manage settings 3. Select the type of settings you want to change from the action menu There are different types of settings: * **Incident types**: select the relevant incident type that the playbook adresses, e.g. ransomware, phishing etc * **Incident response stage**: Mark the playbook as detection, mitigation, prevention or remediation (among others) * **Assets**: the linked assets. * **Asset types**: the linked asset types. * **RACI Matrix:** the responsible, accountable, consulted and informed users or teams for this playbook. * **Impact and Severity:** the impact and severity values of the playbook. The values can be Not Specified, Low, Medium, High and Critical. * **Last tested**: when the playbook was last tested and the mode of testing. * **Review Settings**: the assigned review and review frequency of the playbook # How to mark a playbook as reviewd 1. Go to the **Playbook Management System** 2. Select the **Mark as Reviewed** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. In the modal that appears, you can optionally add notes 4. Click on **Mark as Reviewed** button to complete the process # How to add a playbook to your watch list 1. Go to the **Playbook Management System** 2. Select the **Watch** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. The playbook will be added to your watch list If your playbook is already in the watch list, you will see the **Unwatch** action instead. By clicking it, the playbook will be removed from the watch list # How to remove a playbook from your watch list 1. Go to the **Playbook Management System** 2. Go to the **Watched** list Watched Menu 3. Select the playbook(s) you want to remove from the watch list 4. Select the **Unwatch** action from the bulk action bar Unwatch Action You can also remove a playbook from the watch list through each individual's playbook action menu # How to add a playbook to your favorites 1. Go to the **Playbook Management System** 2. Hover over the playbook that you want to add to favorites 3. Click on the **Favorites** action Favorites Action 4. The playbook will be added to your favorites If the playbook is already in your favorites list, you will see the Remove From Favorites icon instead. Clicking on it will remove the playbook from your favorites If you want to add multiple playbooks to your favorites at once, select them and click on the Add to Favorites action from the bulk action bar # How to remove a playbook from your favorites 1. Go to the **Playbook Management System** 2. Go to the **Favorites** list Favorites Menu 3. Select the playbook(s) you want to remove from favorites 4. Select the **Remove From Favorites** action from the bulk action bar Favorites Remove # How to duplicate a playbook 1. Go to the **Playbook Management System** 2. Select the **Duplicate** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu Duplicate Action 3. Enter a name for the duplicate playbook 4. Duplicate the playbook * Click the **Duplicate** button Duplicate Modal # How to move a playbook to trash bin 1. Go to the **Playbook Management System** 2. Select the **Move to Trash** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. Verify that you want to move the playbook to trash in the dialog that appears 4. Your playbook will move to trash bin # How to permanently delete a playbook 1. Go to the **Playbook Management System** 2. Go to **My Playbooks** area 3. Select the **Trash** tab 4. Select the playbooks you want to delete 5. Select the **Delete Permanently** action from the action bar at the bottom Delete Permanently # How to export a playbook 1. Go to the **Playbook Management System** 2. Select the **Export as** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. Choose the format you want to export from the sub-menu that appears # How to download a playbook 1. Go to the **Playbook Management System** 2. Select the **Download** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. Choose the format you want to export from the sub-menu that appears # How to mark and unmark a playbook as draft 1. Go to the **Playbook Management System** 2. Select the **Mark as Draft** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu If your playbook is already marked as draft, you can select **Go Live** action to remove its draft status # How to revoke and unrevoke a playbook 1. Go to the **Playbook Management System** 2. Select the **Revoke** action * Hover over the playbook you want to deploy * Click on the triple dot icon to open the action menu 3. Confirm that you want to revoke a playbook from the dialog box that appears If your playbook is already revoked, you can select the **Un-revoke** action to unrevoke it Revoked playbooks cannot be shared or deployed. You need to un-revoke them first. If the playbook is revoked, all its shares are removed. # Share playbooks Source: https://docs.cymph.io/howto/share_playbooks ## Overview The Cymph platform’s sharing capability allow users to share playbooks seamlessly. You can share playbooks that you have created with others and, with the right privileges, playbooks already shared by others. **Learn more**: Read the [**User roles**](/administration/user_roles) page for more details on roles are allowed to share playbooks. ## How to share a playbook 1. Search for the playbook you want to share in the **Playbook Management System** or open the playbook inside the **Playbook Editor.** ### From the Playbook Management System 1. Hover over the playbook you want to share 2. Go to the action menu * Click on the triple dot action button 3. Share your playbook * Select the Share option * The share playbook dialog will open Pb Share Table ### From the playbook editor Once a playbook is open in the playbook editor, you can share it without exiting the editor 1. Share the playbook * Click the **Share** button from the top action bar * The share playbook dialog will open Pb Share Editor ## Sharing modes 5. You can share the selected playbook with: * An **individual user**. * **Your own organisation**. * An **external organisation**. * An **ensemble of organisations**. An ensemble is a group of organisations. By sharing to an ensemble, all the organisations belonging to it will received the shared playbook. * **Publicly with all Cymph users**. This action will share the playbook with everyone using Cymph, allowing all Cymph users to see, deploy, and duplicate the shared playbook. ## # Cortex XSOAR Source: https://docs.cymph.io/integrations/automation/cortex-xsoar Deploy playbooks to a Palo Alto Cortex XSOAR instance. ## What Cymph uses it for Cymph connects to Cortex XSOAR as a deployment target — playbooks authored in Cymph are translated to the XSOAR playbook format and pushed to the instance. See [Deploy playbooks](/how-tos/deploy-playbooks). ## Requirements | Field | Description | | ---------------- | --------------------------------------------------------- | | **Instance URL** | The URL of your Cortex XSOAR instance | | **Version** | Whether the instance is XSOAR **6** or **8** | | **API key** | An API key from your instance | | **API key ID** | **XSOAR 8 only** — the numeric ID shown alongside the key | To generate an API key, follow the instructions [here](https://docs-cortex.paloaltonetworks.com/r/Cortex-XSOAR-6-API/Cortex-XSOAR-6-overview). The version you select changes both the API paths and the authentication headers. XSOAR 6 sends the key alone; XSOAR 8 additionally sends the key ID as an `x-xdr-auth-id` header, which is why the extra field appears. Selecting the wrong version fails the connection test with "Target does not seem to be a valid Cortex XSOAR *version* instance". ## Permissions An API key is assigned a role, and the key inherits that role's permissions. Rather than using an administrative key, create a custom role granting only what Cymph uses: | Component | Level | Why | | ------------- | ---------- | ------------------------------------------------------- | | **Playbooks** | Read-Write | Search and read playbooks, and save a deployed playbook | | **Incidents** | Read-Only | Search incidents when resolving deployment targets | Everything else can be set to **None** — Cymph does not run playbooks, execute automations, manage integrations, or read the War Room. Cortex XSOAR's built-in roles are broader than this. **Instance Admin** in particular grants far more than Cymph needs; a custom role with the two components above is the least-privilege option. ## What Cymph reads and writes ## Testing the connection # n8n Source: https://docs.cymph.io/integrations/automation/n8n Deploy playbooks to an n8n instance as workflows. ## What Cymph uses it for Cymph connects to n8n as a deployment target — playbooks authored in Cymph are translated to n8n workflows and pushed to the instance. See [Deploy playbooks](/how-tos/deploy-playbooks). ## Requirements | Field | Description | | ---------------- | ---------------------------- | | **Instance URL** | The URL of your n8n instance | | **API key** | An n8n API key | To generate an n8n API key, follow the instructions [here](https://docs.n8n.io/api/authentication/). ## Permissions API key **scopes are an enterprise feature**. On a non-enterprise instance, every API key has full access to all of the account's resources — there is no way to narrow it. Treat the key as an administrative credential and store it accordingly. On an enterprise instance, grant the key these scopes and nothing else: | Scope | Why Cymph needs it | | ----------------- | ----------------------------------------------------- | | `workflow:read` | Read workflows — also grants `workflow:list` | | `workflow:create` | Create a workflow when a playbook is deployed | | `execution:read` | Read execution history — also grants `execution:list` | | `user:list` | Resolve workflow owners to names | Cymph does not need `workflow:update`, `workflow:delete`, `workflow:activate`, or any credential scope. Deployed workflows are created, never modified or removed, and Cymph never reads your stored credentials. Granting `:read` automatically grants the matching `list` scope, so there is no need to add `workflow:list` or `execution:list` explicitly. ## What Cymph reads and writes ## Testing the connection # Splunk SOAR Source: https://docs.cymph.io/integrations/automation/splunk-soar Import playbooks from a Splunk SOAR instance into Cymph. ## What Cymph uses it for Cymph connects to Splunk SOAR to browse and import the playbooks already on your instance, so existing automation can be brought into Cymph. See [Import a playbook](/howto/import_playbook). All operations are currently **read-only** — Cymph never creates, modifies, or runs a playbook on the instance. Deploying playbooks **to** Splunk SOAR is not yet available. See [Limitations](#limitations). ## Requirements | Field | Description | | ---------------- | -------------------------------------------------------------------------- | | **Instance URL** | The base URL of your Splunk SOAR instance, e.g. `https://soar.example.com` | | **Token** | A Splunk SOAR automation token | ## Token setup Cymph authenticates with a **`ph-auth-token`** header, which takes a Splunk SOAR **automation user** token rather than a password. 1. Create (or choose) an automation user: **Administration → User Management → Users**, with user type **Automation**. 2. Copy the token generated for that user. 3. Give the automation user a role with read access to playbooks. Automation users exist for exactly this purpose — they are non-interactive and their activity is easy to separate from human analysts in the audit log. Do not use a personal account's token. ## Permissions The token inherits the role of the automation user it belongs to. Splunk SOAR exposes three permission types on the **Playbooks** resource — **view**, **edit**, and **execute** — and Cymph needs only the first: | Permission | Setting | Why | | ----------------------- | ------------ | ----------------------------------------------- | | Playbooks — **view** | Enabled | List playbooks and read their definitions | | Playbooks — **edit** | Not required | Cymph never modifies a playbook on the instance | | Playbooks — **execute** | Not required | Cymph never runs a playbook or an action | The default **Automation** role has a broad set of permissions — it is designed to cover whatever a service account might need. For least privilege, create a custom role with only Playbooks → view and assign that to the automation user instead. Splunk SOAR roles can also be restricted to whitelisted **repositories**. If you use that, make sure the role can reach the repositories holding the playbooks you want to import — Cymph reads the source-control repository list to disambiguate playbooks that share a name. ## What Cymph reads | Purpose | Splunk SOAR REST call | | ---------------------------------------------- | ---------------------------------------------------------- | | Test the connection | `GET /rest/version` | | List available playbooks | `GET /rest/playbook?page_size=0` | | Read a playbook by ID | `GET /rest/playbook/{playbook_id}` | | Look up a playbook by name within a repository | `GET /rest/playbook?_filter_name={name}&include_expensive` | | List source-control repositories | `GET /rest/scm/` | Playbooks can be addressed either by their numeric ID or as `{repository_id}/{playbook_name}` — Cymph resolves the repository from the source-control list so playbooks with the same name in different repositories stay distinct. ## Testing the connection **Test Connection** calls the version endpoint: | Message | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | **Authorization failed** | The instance was reached but rejected the token | | **Connection timed out** | No response within the timeout — check network reachability and any firewall or allowlist between Cymph and the instance | If Cymph reaches your instance through a source-IP allowlist, confirm the egress addresses are permitted — see [Networking](/deployment/networking#egress-control). ## Limitations Splunk SOAR is currently an **import source only**. Although the platform registers it as a workflow deployment target, the export path is not implemented, so deploying a Cymph playbook to Splunk SOAR does not work yet. If you want to read Splunk detection content instead, that is the separate [Splunk Enterprise Security](/integrations/detection/splunk-es) integration. # StackStorm Source: https://docs.cymph.io/integrations/automation/stackstorm Deploy playbooks to a StackStorm instance. ## What Cymph uses it for Cymph connects to StackStorm as a deployment target — playbooks authored in Cymph are translated to StackStorm workflows and pushed to the instance. See [Deploy playbooks](/how-tos/deploy-playbooks). ## Requirements | Field | Description | | ---------------- | ----------------------------------- | | **Instance URL** | The URL of your StackStorm instance | | **API key** | A StackStorm API key | ## API key setup All API key management is currently available via the StackStorm CLI or API. To create an API key: ```bash theme={"system"} st2 apikey create -k -m '{"used_by": "my integration"}' ``` You can read more detailed documentation [here](https://docs.stackstorm.com/authentication.html). ## Permissions A StackStorm API key inherits the permissions of the user that created it, so create the key as a dedicated user with a role granting only what Cymph uses: | Permission | Why Cymph needs it | | --------------- | ------------------------------------------------------ | | `action_list` | List the actions on the instance | | `action_create` | Create an action when a playbook is first deployed | | `action_modify` | Update the action when the same playbook is redeployed | You do **not** need `action_execute` — Cymph deploys playbooks but never runs them — and no `action_delete`. Create, modify, delete, and execute grants implicitly include the matching view permission, so `action_create` and `action_modify` already cover `action_view`. You only need to add `action_list` on top. Grants can be scoped to a specific pack by UID (`pack:my_pack`) rather than granted globally, which is the tighter option if Cymph deploys into a pack of its own. RBAC is available in StackStorm open source from **3.4** onward — it was an enterprise feature before that. On an older or non-RBAC instance, any valid API key has full access and these grants do not apply. ## What Cymph reads and writes ## Testing the connection # AWS Source: https://docs.cymph.io/integrations/cloud/aws Discover AWS resources and import them as Cymph assets. ## What Cymph uses it for The AWS integration discovers cloud resources (EC2, Lambda, RDS, S3, IAM, etc.) and imports them as Cymph assets. See [Asset actions](/howto/asset_actions). All operations are **read-only** — Cymph only calls `Describe*` / `List*` / `Get*` actions. It supports two credential modes: **Access Key** and **IAM Role**. Cross-account IAM Role is the recommended mode, because no long-lived credentials are stored by either party. ## Access Key mode You will need to supply an IAM user's access key ID and secret access key. Optionally a session token can be provided for temporary (STS) credentials. | Field | Required | Secret | Notes | | ------------------- | -------- | ------ | --------------------------------- | | `access_key_id` | yes | no | Access key ID of the IAM user | | `secret_access_key` | yes | yes | Secret access key of the IAM user | | `session_token` | no | yes | For temporary (STS) credentials | | `region` | yes | no | Default region for API calls | ## Cross-account IAM Role mode Instead of long-lived keys, the customer creates a read-only IAM role that trusts Cymph's AWS account. Cymph assumes the role via STS `AssumeRole`, so **no long-lived credentials are stored by either party** and access is easy to rotate or revoke. | Field | Required | Secret | Notes | | ------------- | -------- | ------ | --------------------------------------------------- | | `role_arn` | yes | no | ARN of the role to assume | | `external_id` | no\* | no | Shared value in the role's trust policy (see below) | | `region` | yes | no | Default region for API calls | \* Optional as far as AWS is concerned, but **strongly recommended** — see [the confused-deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). ### Setup 1. **Create the role** in the customer's AWS account with a trust policy that allows Cymph's account to assume it, gated by an external ID: ```json theme={"system"} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ] } ``` 2. **Attach a read-only policy.** The AWS managed policy `ReadOnlyAccess` (or `SecurityAudit`) covers the discovery calls; a tighter custom policy limited to the `Describe*` / `List*` / `Get*` actions used by the executor is preferable. 3. **Provide Cymph** the role ARN and the external ID. Enter them in the integration form (Authentication method → *IAM role*) and click **Test Connection** to verify the role can be assumed. ### Deployment-side IAM In `Assume Role` mode Cymph calls STS using the **API host's own identity** (the ECS task role / EC2 instance role, or ambient credentials from the environment). That identity must be allowed to call `sts:AssumeRole` on the customer roles, e.g.: ```json theme={"system"} { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::*:role/*" } ``` There is no Cymph-side config for this — it is part of the deployment's IAM setup, not the integration record. This applies to [self-hosted deployments](/deployment/self-hosted/architecture); on a managed cloud tenant it is already in place. ## What Cymph reads ## Testing the connection # Azure Source: https://docs.cymph.io/integrations/cloud/azure Discover Azure resources and Entra ID identities, and import them as Cymph assets. ## What Cymph uses it for The Azure integration discovers cloud resources and Entra ID identities and imports them as Cymph assets. See [Asset actions](/howto/asset_actions). All operations are **read-only**. Every call Cymph makes to Azure is an HTTP `GET`; the only `POST` is the OAuth token request to Entra ID. No resource, role assignment, or directory object is ever created, modified, or deleted. Azure is an asset source only — playbooks cannot be deployed to it, and it is not a content source for playbook import. ## Requirements Integrating with Azure requires the registration of an application in Microsoft Entra ID. You can see the detailed documentation [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). | Field | Description | | ----------------- | -------------------------------------------------------- | | **Tenant ID** | Your Entra ID (Azure AD) tenant ID | | **Client ID** | Application (client) ID of the registered application | | **Client secret** | A client secret generated for the registered application | There is no subscription field — Cymph enumerates every subscription the app registration can see and discovers resources across all of them. ## Permissions Cymph requests tokens using the **`.default`** scope, which means it asks for no scopes of its own: the access it gets is exactly the set of **application permissions already consented on your app registration**, plus whatever **Azure RBAC** roles its service principal has been assigned. You control access entirely from the Azure side. Two grants are needed, for two different APIs. ### Azure Resource Manager — Reader Assign the app's service principal the **Reader** role on each subscription you want discovered: open the subscription → **Access control (IAM)** → **Add role assignment** → **Reader**. Reader covers every resource call Cymph makes. A subscription with no role assignment is silently skipped — it will not appear during discovery. ### Microsoft Graph — directory read Cymph reads users, groups, and service principals from Entra ID and imports them as identity assets. Grant **one** of the following as **application** permissions with admin consent: | Option | Permissions | Notes | | --------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Simplest | `Directory.Read.All` | Single grant covering all four endpoints Cymph calls | | Least privilege | `User.Read.All`, `Group.Read.All`, `Application.Read.All` | Narrower, but `Directory.Read.All` is still required for the `directoryObjects/getByIds` lookup used to resolve role-assignment principals | Earlier versions of this page listed `Sites.Read.All` as an Azure requirement. It is **not** needed — the Azure connector makes no SharePoint calls. If you want to read SharePoint content, configure the separate [SharePoint](/integrations/content/sharepoint) integration. If you do not want to grant directory permissions at all, the integration still works for infrastructure resources — only the identity asset types (users, groups, service principals, managed identities) will come back empty. ## What Cymph reads ### Azure Resource Manager | Purpose | Resource provider | | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Enumerate subscriptions | `Microsoft.Resources/subscriptions` | | Virtual machines and scale sets | `Microsoft.Compute/virtualMachines`, `virtualMachineScaleSets` | | Network interfaces and public IPs (VM addressing) | `Microsoft.Network/networkInterfaces` | | Load balancers and application gateways | `Microsoft.Network/loadBalancers`, `applicationGateways` | | App Service, Container Apps, Spring Apps | `Microsoft.Web/sites`, `Microsoft.App`, `Microsoft.AppPlatform` | | Kubernetes and OpenShift clusters | `Microsoft.ContainerService` | | Logic Apps and their workflows | `Microsoft.Logic/workflows` | | SQL, PostgreSQL, MySQL, Cosmos DB, Mongo clusters | `Microsoft.Sql`, `Microsoft.DBforPostgreSQL`, `Microsoft.DBforMySQL`, `Microsoft.DocumentDB` | | Redis caches | `Microsoft.Cache` | | Key vaults and storage accounts | `Microsoft.KeyVault`, `Microsoft.Storage` | | Bare-metal instances | `Microsoft.BareMetalInfrastructure` | | Role assignments | `Microsoft.Authorization/roleAssignments` | | Activity log entries | `microsoft.insights/eventtypes/management` | ### Microsoft Graph | Purpose | Graph endpoint | | ------------------------------------------- | --------------------------------- | | Users | `/v1.0/users` | | Groups | `/v1.0/groups` | | Service principals and managed identities | `/v1.0/servicePrincipals` | | Resolve role-assignment principals to names | `/v1.0/directoryObjects/getByIds` | Cymph requests a fixed field selection rather than whole objects — for users, for example, it reads only display name, UPN, mail, job title, department, account status, and creation date. ## Testing the connection **Test Connection** acquires a token from Entra ID and reports: | Message | Meaning | | ----------------------------------------------- | ------------------------------------------------------------- | | **Valid Azure credentials** | Entra ID issued a token for the tenant, client ID, and secret | | **Connection timed out** | No response within 5 seconds | | **Target does not seem to be a Azure Instance** | The token request failed for a reason other than a timeout | Test Connection only verifies that the **credentials** are valid — it acquires a token and stops there. It does **not** check that the Reader role or the Graph permissions have been granted. An integration can test successfully and still discover nothing, which is almost always a missing Reader assignment or missing admin consent. # Confluence Source: https://docs.cymph.io/integrations/content/confluence Fetch pages and spaces from Atlassian Confluence. ## What Cymph uses it for Cymph connects to Confluence for two purposes: 1. **Importing content** — reads pages and spaces, so existing documentation can be brought into Cymph. *(read)* 2. **Publishing documentation** — creates a new Confluence page from a playbook's documentation. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks). A single token can serve either or both purposes. **If you only import, Cymph needs read scopes; publishing requires an additional write scope** — see [Permissions](#permissions) below. Confluence and [JIRA](/integrations/ticketing/jira) are separate integration types but share the same Atlassian API token mechanism. The token must be created for the right app and carry the scopes listed below. ## Requirements | Field | Description | | ------------------ | ------------------------------------------------------------------- | | **Instance URL** | The URL of your instance, e.g. `https://mydomain.atlassian.net` | | **E-mail address** | The e-mail address of the Atlassian user, e.g. `myuser@example.com` | | **API token** | An API token for the account (see below) | ## Token setup Follow the instructions provided [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) to generate a token. ## Permissions ### To import content ``` read:page:confluence read:space:confluence ``` Or, if you are using classic scopes: ``` read:confluence-content.all read:confluence-space.summary ``` ### To also publish documentation Add the following scope: ``` write:page:confluence ``` Or, with classic scopes: ``` write:confluence-content ``` An Atlassian API token inherits the permissions of the user it belongs to, so the account must have access to the spaces you want Cymph to read — and, for publishing, permission to add pages to the target space. Use a dedicated Atlassian service account rather than a personal one — pages created by Cymph will be attributed to whichever account owns the token. ## What Cymph reads and writes Cymph reads spaces and page content, and creates pages when you publish documentation. | Purpose | Confluence API call | | ----------------------------------------- | ------------------------- | | Create a page from playbook documentation | `POST /wiki/api/v2/pages` | Pages are created with status `current` (published, not draft) in the space you select, using Confluence's **storage format** — Cymph converts the playbook's documentation blocks to Markdown and then to storage HTML. Cymph returns the new page's URL, which becomes the "navigate to the pushed playbook" link in Deploy History. Cymph never updates or deletes existing pages — each publish creates a new page. Publishing the same playbook twice produces two pages, and Confluence rejects the second if the title collides within the space. ## Publishing formats Confluence accepts **Markdown documentation only**. PDF publishing is not supported — Confluence pages have no native PDF type, and Cymph will reject the attempt with "PDF push is not supported for Confluence". Image blocks are omitted. ## Testing the connection # GitBook Source: https://docs.cymph.io/integrations/content/gitbook Fetch documentation pages and spaces from GitBook. ## What Cymph uses it for Cymph connects to GitBook for two purposes: 1. **Importing content** — fetches documentation pages and spaces. *(read)* 2. **Publishing documentation** — adds a playbook's documentation to a space as a new page. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks). The endpoint is fixed to GitBook's SaaS API (`https://api.gitbook.com`), so no instance URL is required. **If you only import, the token's account needs read access to your spaces; publishing requires edit access** — see [Permissions](#permissions) below. ## Requirements | Field | Description | | ------------- | ------------------------------- | | **API token** | A GitBook API token (see below) | ## Token setup Create an API token from your GitBook [developer settings](https://gitbook.com/docs/developers/gitbook-api/quickstart) (**Account settings → Developer → API tokens**). ## Permissions GitBook has no per-token scope selector — a token inherits the permissions of the account that created it. What matters is the account's role on the target spaces: | If you want to | The token's account needs | | ------------------------------------ | --------------------------------------------------------------------------------------------- | | Import content only | **Read** access to the organizations and spaces you want to sync | | Import **and** publish documentation | **Edit** access on the target space, including permission to create and merge change requests | Create the token from a dedicated service account rather than a personal admin account, and grant it access only to the spaces Cymph should touch. Published pages are attributed to the token's account. ## What Cymph reads and writes Cymph reads your organizations, their spaces, and page content. Publishing goes through GitBook's **change request** workflow rather than writing to the live space directly — three calls, in order: | Step | GitBook API call | | -------------------------- | --------------------------------------------------------- | | 1. Open a change request | `POST /v1/spaces/{space_id}/change-requests` | | 2. Insert the page | `POST /v1/spaces/{space_id}/change-requests/{id}/content` | | 3. Merge it into the space | `POST /v1/spaces/{space_id}/change-requests/{id}/merge` | Because the merge is automatic, a published playbook lands in the live space — the change request is a mechanism, not a review gate. Each publish inserts a **new** page. Cymph does not update or delete existing GitBook pages, so publishing the same playbook twice produces two pages. ## Publishing formats GitBook accepts **Markdown documentation only** — PDF publishing is not supported. Image blocks are omitted. ## Testing the connection # GitHub Source: https://docs.cymph.io/integrations/content/github Import playbooks from GitHub repositories and commit playbook backups back to them. ## What Cymph uses it for Cymph uses GitHub for three purposes, all driven by a **single access token**: 1. **Fetching playbooks / content** — reads repositories, branches, and files to import playbooks and other content into Cymph. *(read)* 2. **Backups** — commits playbook backups into a repository on a schedule or on demand. *(write)* See [Back up playbooks to GitHub](/how-tos/github-backup). 3. **Publishing documentation** — commits a playbook's documentation into a repository as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks). A single token can serve any combination of these depending on which repositories you point Cymph at. Cymph connects to `github.com` (no instance URL field). Because the `repo` scope is required in all cases (see below), publishing needs **no additional permissions** beyond what the integration already asks for. ## Requirements | Field | Description | | --------- | ---------------------------------------------------- | | **Token** | A GitHub personal access token with the `repo` scope | ## Token setup Create a token with the required scope using this pre-filled link: 👉 [Create a Cymph integration token](https://github.com/settings/tokens/new?description=Cymph%20integration\&scopes=repo) This grants the **`repo`** scope, which covers both read (fetching playbooks) and write (committing backups) on private repositories. Cymph verifies that the token carries the `repo` scope when you save the integration and will reject tokens that do not have it, even if you only intend to use the read (fetch) functionality. This is required so that private repositories are accessible and backups can be committed. If you use a **fine-grained personal access token** instead, grant it **Contents: Read and write** on the target repositories. ## Permissions | Scope | Why Cymph needs it | | ------ | ---------------------------------------------------------------------------------------------- | | `repo` | Read repository contents, branches, and files; commit backup files and published documentation | ## What Cymph reads and writes ## Publishing formats GitHub accepts both documentation formats: | Format | What it contains | | --------------- | --------------------------------------------------------------------------------- | | **Markdown** | The playbook's documentation blocks, rendered as Markdown | | **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image | Image blocks are omitted from the Markdown format. ## Testing the connection Cymph validates the connection by listing the authenticated user's repositories. # GitLab Source: https://docs.cymph.io/integrations/content/gitlab Fetch playbooks and repository content from GitLab SaaS or a self-managed instance. ## What Cymph uses it for Cymph connects to GitLab (SaaS or self-managed) for two purposes: 1. **Importing content** — fetches playbooks and repository content. *(read)* 2. **Publishing documentation** — commits a playbook's documentation into a repository as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks). **If you only import, a read-only token is enough; publishing requires a write scope** — see [Permissions](#permissions) below. ## Requirements | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------- | | **Instance URL** | Base URL of your GitLab instance, e.g. `https://gitlab.com` or `https://gitlab.example.com` | | **Token** | A GitLab access token (see below) | ## Token setup Create a [Personal Access Token](https://docs.gitlab.com/api/rest/authentication/) (**Settings → Access Tokens**) with the scope matching what you intend to do. ## Permissions | If you want to | Scope | Notes | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------ | | Import content only | `read_api` | Grants read access to projects, branches, and repository files | | Import **and** publish documentation | `api` | GitLab has no write-only file scope — committing files requires the full `api` scope | For read-only use, a narrower alternative to `read_api` is `read_repository` + `read_user`. Beyond the token scope, the token's **user** must have a role on the target project that permits pushing — **Developer** or above. A protected target branch will reject the commit regardless of scope. `api` is a broad scope: it grants full read and write access to everything the token's user can reach, not just the project you publish to. If that is too much, keep the integration read-only with `read_api` and publish documentation to [GitHub](/integrations/content/github) or [SharePoint](/integrations/content/sharepoint) instead, where the write grant can be scoped more tightly. ## What Cymph reads and writes | Purpose | GitLab API call | | ----------------------------- | ---------------------------------------------------- | | Read a project's metadata | `GET /api/v4/projects/{id}` | | Commit playbook documentation | `POST /api/v4/projects/{id}/repository/files/{path}` | Commits are made to the branch you select, with the message `Cymph: Publish playbook documentation`. The publish call **creates** a file. Publishing to a path that already exists fails rather than overwriting, so re-publishing the same playbook to the same path and branch will error until the existing file is removed or a different path is chosen. ## Publishing formats GitLab accepts both documentation formats: | Format | What it contains | | --------------- | --------------------------------------------------------------------------------- | | **Markdown** | The playbook's documentation blocks, rendered as Markdown | | **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image | Image blocks are omitted from the Markdown format. ## Testing the connection ## Limitations GitLab is not available as a scheduled backup target — that is [GitHub](/integrations/content/github) only. # SharePoint Source: https://docs.cymph.io/integrations/content/sharepoint Import playbooks from SharePoint documents, and publish playbook documentation back to a site. ## What Cymph uses it for Cymph connects to SharePoint through the Microsoft Graph API for two purposes: 1. **Importing content** — browses your sites, document libraries, and pages, and reads file contents so documents can be imported as playbooks. *(read)* See [Import a playbook](/howto/import_playbook). 2. **Publishing documentation** — uploads a playbook's documentation into a document library as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks). A single app registration can serve either or both purposes. **If you only import, Cymph needs read access; publishing requires an additional write permission** — see [Permissions](#permissions) below. ## Requirements The integration requires the following information from a registered Entra ID application: | Field | Description | | ----------------- | -------------------------------------------------------- | | **Tenant ID** | Your Entra ID (Azure AD) tenant ID | | **Client ID** | Application (client) ID of the registered application | | **Client secret** | A client secret generated for the registered application | ## App registration setup You can see the steps on how to create an Entra ID application [here](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread). 1. In **Entra ID → App registrations**, create (or reuse) an app registration. 2. Under **Certificates & secrets**, create a **client secret** and copy its value. 3. Under **API permissions**, add the Microsoft Graph **application** permission for the access you need (see below) and grant admin consent. 4. Note the **Application (client) ID** and **Directory (tenant) ID** from the app's Overview page. ## Permissions Cymph requests tokens using the **`.default`** scope, which means it asks for no scopes of its own: the access it gets is exactly the set of application permissions already consented on your app registration. You control access entirely from the Azure side. | If you want to | Grant | Type | | ------------------------------------ | --------------------- | --------------- | | Import content only | `Sites.Read.All` | **Application** | | Import **and** publish documentation | `Sites.ReadWrite.All` | **Application** | `Sites.ReadWrite.All` supersedes `Sites.Read.All` — grant one or the other, not both. Either is an application permission (app-only, no signed-in user) and requires **admin consent** in your tenant. Start with `Sites.Read.All`. You can raise it to `Sites.ReadWrite.All` later without recreating the integration — the connector picks up the broader consent on its next token request. Graph's `Sites.Selected` permission — which restricts an app to individually approved sites — is **not** compatible with this integration. Cymph discovers sites by calling the tenant-wide site-search endpoint, which `Sites.Selected` does not authorise, so both Test Connection and site listing will fail. Tenant-wide access is required. Cymph never deletes anything in SharePoint. Publishing writes a file to the library path you select; nothing already in your document libraries is removed. ## What Cymph reads and writes ### Reads | Purpose | Graph endpoint | | -------------------------------- | ------------------------------------------------------ | | Test the connection | `GET /v1.0/sites?search=*&$top=1` | | List sites | `GET /v1.0/sites` | | List a site's document libraries | `GET /v1.0/sites/{site_id}/drives` | | Browse a library's contents | `GET /v1.0/drives/{drive_id}/root/children` | | Browse a folder's contents | `GET /v1.0/drives/{drive_id}/items/{item_id}/children` | | Read file metadata | `GET /v1.0/drives/{drive_id}/items/{item_id}` | | Look up an item by path | `GET /v1.0/drives/{drive_id}/root:/{path}` | | Download file content for import | `GET /v1.0/drives/{drive_id}/items/{item_id}/content` | | List site pages | `GET /v1.0/sites/{site_id}/pages` | File content is fetched on demand when you import a document — Cymph does not mirror or continuously sync your SharePoint content. ### Writes | Purpose | Graph endpoint | | ----------------------------- | --------------------------------------------------- | | Upload playbook documentation | `PUT /v1.0/drives/{drive_id}/root:/{path}:/content` | Publishing to a path that already holds a file **overwrites** it. Cymph returns the resulting item's `webUrl`, which becomes the "navigate to the pushed playbook" link in Deploy History. ## Publishing formats SharePoint accepts both documentation formats: | Format | What it contains | | --------------- | --------------------------------------------------------------------------------- | | **Markdown** | The playbook's documentation blocks, rendered as Markdown | | **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image | Image blocks are omitted from the Markdown format. ## Testing the connection **Test Connection** acquires a token and then searches for a single site, so it verifies both the credentials and read access: | Message | Meaning | | ---------------------------------------------------- | ---------------------------------------------------------------------------------- | | **Valid SharePoint credentials** | Authentication succeeded and the app can read sites | | **Authorization failed** | The token was rejected (`401`) — usually a missing or unconsented `Sites.Read.All` | | **Failed with response status *N*** | Graph answered with another error status | | **Connection timed out** | No response within 5 seconds | | **Target does not seem to be a SharePoint instance** | The request failed before a status could be read | Test Connection only exercises **read** access. If you intend to publish documentation, a successful test does not confirm that `Sites.ReadWrite.All` has been consented — the first publish attempt is what surfaces that. # Cortex XSIAM Source: https://docs.cymph.io/integrations/detection/cortex-xsiam Read Cortex XSIAM correlation rules and map their MITRE ATT&CK techniques. ## What Cymph uses it for Cymph connects to Palo Alto Networks Cortex XSIAM for two things: * **Detection scope** — it reads your **correlation rules** and collects the MITRE ATT\&CK techniques mapped on each one, so a preset's scope can be derived from what you actually detect. See [Manage presets](/how-tos/create-and-manage-presets) for the detection-based scope option. * **Playbook import** — it lists the **playbooks** on the tenant and converts the ones you pick into Cymph playbooks. See [Import playbooks](/howto/import_playbook). All operations are **read-only** — Cymph never creates, modifies, enables, or disables a rule or playbook, and never runs a query. ## Requirements | Field | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Base URL** | The tenant's **API host**, e.g. `https://api-mytenant.xdr.eu.paloaltonetworks.com`. This is the console FQDN with an `api-` prefix, not the console address itself | | **API Key** | A **Standard** API key | | **API Key ID** | The numeric ID shown next to the key in the console | Cortex XSIAM serves its public API on a dedicated host: take your console address and prefix the hostname with `api-`. Pointing the integration at the console host itself will fail the connection test. ## API key setup In the Cortex XSIAM console, go to **Settings → Configurations → Integrations → API Keys** and create a new key. Choose the **Standard** security level. Copy the key when it is shown — it cannot be displayed again — and note the **ID** column of the new row, which is the API Key ID. Cymph sends the key as the `Authorization` header and the ID as `x-xdr-auth-id` on every request, which is why both are required and both are stored encrypted. **Advanced** keys are not supported. They require a per-request nonce and timestamp signature that Cymph does not implement. Create the key with the **Standard** level. Create a dedicated key for Cymph rather than reusing one issued to a person or another tool. It keeps the key's role scoped to what Cymph needs and makes the integration's activity easy to identify in the Cortex audit log. ## Permissions The key inherits the **role** chosen when it is created. Cymph needs three permissions from that role, all read-only: | What Cymph does | Permission in the role editor | Used by | | ------------------------- | ---------------------------------------------------------------- | ---------------------------- | | Read one incident | **Incidents & Alerts → Incidents**, level *View* | The connection test | | Read correlation rules | **Detections & Threat Intel → Detections → Rules**, level *View* | Preset scope from detections | | Search and read playbooks | **Automation → Playbooks**, level *View* | Playbook import | Everything else can stay at *None*. Cymph never runs a playbook or a query, never changes a rule, and does not read alerts, endpoints, or event data. Component labels differ slightly between Cortex XSIAM console versions. Look for the Incidents, Rules, and Playbooks entries in **Settings → Configurations → Access Management → Roles** and grant *View* on each. **The correlation rules API is the exception.** Palo Alto Networks documents it as needing the Rules permission, but tenants consistently report that a custom role is refused with *403 — insufficient permissions for api key* even with Rules set to View/Edit, and that only the built-in **Instance Administrator** (or **Account Admin**) role is accepted. A feature request for granular access (CXDR-I-2505) is open. Start with the least-privilege role above; if reading rules fails with the permission error, re-issue the key with **Instance Administrator** as its role. The connection test only reads incidents, so a key with a lesser role can test green and still fail later when a preset reads correlation rules or an import lists playbooks. In both cases the error names the missing permission — see [Testing the connection](#testing-the-connection) below. On some tenants the correlation rules API is switched off server-side and returns *not found* even for an administrator. If a key with Instance Administrator still cannot read rules, ask Palo Alto Networks support to enable the endpoint for your tenant. ## What Cymph reads | Purpose | Cortex XSIAM API call | | ----------------------------------------------- | ------------------------------------------------------------ | | Test the connection | `POST /public_api/v1/incidents/get_incidents` (one incident) | | Read correlation rules and their MITRE mappings | `POST /public_api/v1/correlations/get` | | List playbooks | `POST /xsoar/public/v1/playbook/search` | | Fetch a playbook to import | `GET /xsoar/public/v1/playbook/{id}` | Rules are read in windows of 100 until every rule has been seen. For each rule Cymph looks at two fields only: * `is_enabled` — **only enabled rules contribute to scope**. Rules reported as `DISABLED` are read and ignored. * `mitre_defs` — the rule's ATT\&CK mapping, keyed by tactic with the techniques listed as `T1070.001 - Clear Windows Event Logs` style strings. Cymph keeps the technique or sub-technique ID and discards the name. Cymph does not read rule queries (XQL), alerts, incidents beyond the single one used by the connection test, or any event data. ### Playbook import Cortex XSIAM runs the same automation engine as Cortex XSOAR 8 and serves its playbook API under the XSOAR-compatible `/xsoar/public/v1` paths on the same `api-` host. Cymph therefore converts XSIAM playbooks with the **Cortex XSOAR converter** — the mapping of tasks, conditions, and embedded playbooks is identical to a [Cortex XSOAR](/integrations/automation/cortex-xsoar) import, and the same YAML files can also be uploaded directly. If a playbook carries **MITRE ATT\&CK technique IDs as tags** (for example `T1566` or `T1566.001`), Cymph recognises them during conversion and records them as the playbook's ATT\&CK for Enterprise mappings, so the imported playbook is scoped without any manual tagging. Tags that are not valid technique IDs are kept as ordinary labels. ## Testing the connection **Test Connection** asks for a single incident and reports what it found: | Message | Meaning | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | **Valid Cortex XSIAM instance** | The key and key ID were accepted and the URL is a Cortex XSIAM API host | | **Authorization failed** | The tenant was reached but rejected the key or key ID | | **API key role lacks permission to view incidents** | The credentials are right, but the key's role cannot read incidents — change the role rather than the key | | **Connection timed out** | No response within 5 seconds — check network reachability and any firewall or allowlist between Cymph and the tenant | | **Target does not seem to be a Cortex XSIAM instance** | Something answered, but not the Cortex API — usually the console host instead of the `api-` host | | **Failed with response status *N*** | The tenant answered with another error status | When a preset reads correlation rules, two further messages can appear on the scope source: | Message | Meaning | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API key role lacks permission to read correlation rules (grant Rules view, or use the Instance Administrator role)** | The key works but its role cannot read rules — see [Permissions](#permissions); in practice this usually means re-issuing the key with Instance Administrator | | **Correlation rules API not found on target** | Either the Base URL is wrong, or the endpoint is disabled on this tenant — see [Permissions](#permissions) | | **Unable to get playbooks** / **Unable to get playbook** (on import) | The playbook API refused or did not answer — usually the role lacks Playbooks *View*, or the Base URL is the console host rather than the `api-` host | Every request Cymph makes to Cortex XSIAM times out after 5 seconds. If Cymph reaches your tenant through a source-IP allowlist, confirm the egress addresses are permitted — see [Networking](/deployment/networking#egress-control). ## Limitations Cortex XSIAM is a **read-only** integration — Cymph imports playbooks from it and reads its correlation rules, but playbooks cannot be deployed to it, and it does not import assets. If you want to deploy playbooks to the Cortex platform, that is the separate [Cortex XSOAR](/integrations/automation/cortex-xsoar) integration. # Microsoft Sentinel Source: https://docs.cymph.io/integrations/detection/microsoft-sentinel Read Sentinel analytics rules and map their MITRE ATT&CK techniques. ## What Cymph uses it for Cymph connects to Microsoft Sentinel to read your analytics/detection rules and map their MITRE ATT\&CK techniques, so a preset's scope can be derived from what you actually detect. See [Manage presets](/how-tos/create-and-manage-presets) for the detection-based scope option. All operations are **read-only** — Cymph never modifies rules, incidents, or workspace configuration. Authentication uses an **Entra ID app registration** (client-credentials flow) against the Azure Resource Manager API. Access is therefore controlled by **Azure RBAC role assignments**. ## Requirements | Field | Description | | ----------------- | --------------------------------------------------------- | | **Tenant ID** | Your Entra ID (Azure AD) tenant ID | | **Client ID** | Application (client) ID of the app registration | | **Client secret** | A client secret generated for the app registration | | **Subscription** | The Azure subscription containing your Sentinel workspace | | **Workspace** | The Log Analytics workspace that Sentinel is onboarded to | After you enter the Tenant ID, Client ID, and Client secret, Cymph lists the subscriptions the app can access and, once a subscription is selected, the Log Analytics workspaces within it — so you can pick the Subscription and Workspace from a list rather than typing IDs. ## App registration setup 1. In **Entra ID → App registrations**, create (or reuse) an app registration. 2. Under **Certificates & secrets**, create a **client secret** and copy its value — this is the **Client secret** field above. 3. Note the **Application (client) ID** and **Directory (tenant) ID** from the app's Overview page. No Microsoft Graph API permissions are required for this connector. ## Permissions Grant the app's service principal the **Reader** role, at **subscription scope** (or at least on the resource group and Log Analytics workspace that host Sentinel): * **Reader** covers everything Cymph needs: listing subscriptions and workspaces, checking the Sentinel onboarding state, and reading analytics rules. Alternatively, you can assign **Microsoft Sentinel Reader** on the workspace for the Sentinel-specific reads, but **Reader** at subscription scope is the simplest option because it also lets Cymph enumerate the subscription and workspace during setup. To assign the role: open the target subscription → **Access control (IAM)** → **Add role assignment** → select **Reader** → assign it to your app registration's service principal. ## What Cymph reads | Purpose | Azure Resource Manager call | | --------------------------------------- | ------------------------------------------------------------------------------------------------- | | List subscriptions (setup) | `Microsoft.Resources/subscriptions` | | List Log Analytics workspaces (setup) | `Microsoft.OperationalInsights/workspaces` | | Verify Sentinel is onboarded | `Microsoft.SecurityInsights/onboardingStates` | | Read analytics rules & their techniques | `Microsoft.SecurityInsights/alertRules`, `Microsoft.SecurityInsights/securityMLAnalyticsSettings` | ## Testing the connection ## Limitations Sentinel is a detection source — playbooks cannot be deployed to it. # Splunk Enterprise Security Source: https://docs.cymph.io/integrations/detection/splunk-es Read Splunk ES correlation searches and map their MITRE ATT&CK techniques. ## What Cymph uses it for Cymph connects to Splunk Enterprise Security to read your **correlation searches** and collect the MITRE ATT\&CK techniques annotated on each one, so a preset's scope can be derived from what you actually detect. See [Manage presets](/how-tos/create-and-manage-presets) for the detection-based scope option. All operations are **read-only** — Cymph never creates, modifies, or disables a search, and never runs one. ## Requirements | Field | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Instance URL** | The address of the Splunk management API, e.g. `https://splunk.example.com:8089`. This is the **management** port (8089 by default), not Splunk Web (8000) | | **Token** | A Splunk authentication token | The Splunk management API listens on port **8089** by default and is separate from Splunk Web (port 8000). Pointing the integration at Splunk Web will fail the connection test. ## Token setup Cymph authenticates with a **bearer token**, not a username and password. In Splunk Web, go to **Settings → Tokens** and create a token for the account Cymph should use. Token authentication must be enabled on the instance first (**Settings → Tokens → Enable Token Authentication**). Create a dedicated Splunk account for Cymph rather than reusing an administrator's. It keeps the access read-only and makes the integration's activity easy to identify in your Splunk audit logs. ## Permissions The token inherits the roles of the Splunk user it was issued for. Splunk authorisation has **two independent layers**, and read access needs both — granting capabilities alone is the most common reason a token authenticates but returns nothing: 1. **Role capabilities** — `rest_properties_get`, which permits reading configuration objects over the REST API. 2. **Object ACLs** — the role must appear in the **read** ACL of the correlation searches themselves. In Splunk Enterprise Security these are managed on the **ES Permissions** page; a custom role shows up there within about a minute of being created. The simplest option that satisfies both is Enterprise Security's built-in read-only analyst role, **`ess_user`**, which already carries ES app access and read ACLs on correlation searches. Start with a dedicated user holding `ess_user`. If the connection test passes but no techniques come back, the gap is almost always layer 2 — the role is not in the read ACL for the correlation searches. Cymph needs no write capability of any kind: not `edit_correlationsearches`, not `schedule_search`, and no ability to dispatch searches. It reads saved-search configuration only and never runs a search. Splunk deployments vary considerably in how ES roles are customised. Treat `ess_user` as the recommended starting point rather than a guarantee, and validate against your own instance — your ES administrator may have altered the shipped roles' ACLs. ## What Cymph reads | Purpose | Splunk REST call | | ----------------------------------------------------- | ------------------------------ | | Test the connection | `GET /services/server/info` | | Read correlation searches and their MITRE annotations | `GET /services/saved/searches` | Cymph asks Splunk to do the filtering, so only the data it needs crosses the wire: * `search=action.correlationsearch.enabled=1` — **only enabled correlation searches** are returned. Disabled ones are ignored and do not contribute to scope. * `f=action.correlationsearch.annotations` — the response is restricted to the annotations field alone. Cymph does not read search queries, results, or any event data. Results are read in pages of 100 until every matching search has been seen. Only searches carrying `mitre_attack` annotations contribute techniques; searches without them are read and ignored. ## Testing the connection **Test Connection** calls the server-info endpoint and reports what it found: | Message | Meaning | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **Valid Splunk ES instance** | The token was accepted and the URL is a Splunk management API | | **Authorization failed** | The instance was reached but rejected the token | | **Connection timed out** | No response within 5 seconds — check network reachability and any firewall or allowlist between Cymph and the instance | | **Target does not seem to be a Splunk instance** | Something answered, but not a Splunk API — usually Splunk Web or the wrong port | | **Failed with response status *N*** | Splunk answered with another error status | Every request Cymph makes to Splunk times out after 5 seconds. If Cymph reaches your instance through a source-IP allowlist, confirm the egress addresses are permitted — see [Networking](/deployment/networking#egress-control). ## Limitations Splunk ES is a detection source only — playbooks cannot be deployed to it, and it does not import assets. If you want to deploy playbooks to Splunk, that is the separate [Splunk SOAR](/integrations/automation/splunk-soar) integration. # Wazuh Source: https://docs.cymph.io/integrations/detection/wazuh Read Wazuh detection rules and enrolled agents to scope presets and import assets. ## What Cymph uses it for Cymph connects to the **Wazuh server API** on your Wazuh manager for two purposes: 1. **Detection rules** — reads your ruleset and collects the MITRE ATT\&CK tags on each rule, so a preset's scope can be derived from what you actually detect. See [Manage presets](/how-tos/create-and-manage-presets) for the detection-based scope option. 2. **Assets** — reads your enrolled agents and imports them as host assets. See [Importing assets from Wazuh](/howto/asset_actions#importing-assets-from-wazuh). All operations are **read-only**. ## Requirements | Field | Description | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A descriptive name for this instance | | **Base URL** | The address of the Wazuh server API, e.g. `https://localhost:55000`. This is the **API** port (55000 by default), not the Wazuh dashboard | | **Username** | A Wazuh API user | | **Password** | The password for that user | The Base URL must not end with a trailing slash — the form rejects it. The Wazuh server API listens on port **55000** by default and is separate from the Wazuh dashboard (port 443). Pointing the integration at the dashboard will fail the connection test. ## Authentication Cymph authenticates with the username and password against `/security/user/authenticate` and receives a short-lived JWT, which it uses for the rest of the session. Your credentials are used only to obtain that token; Cymph does not hold a Wazuh session open between operations. ## Permissions Cymph needs a Wazuh API user whose role grants **read** access to rules, agents and syscollector data. The built-in read-only role is the simplest option; if you build a custom role, these are the actions Cymph uses: | Purpose | Wazuh API call | Read access needed on | | ----------------------------------------- | -------------------------------------- | ---------------------- | | Test the connection | `POST /security/user/authenticate` | — (any valid API user) | | Read detection rules and their MITRE tags | `GET /rules` | Rules | | List enrolled agents | `GET /agents` | Agents | | Read agent OS details | `GET /syscollector/{agent_id}/os` | Syscollector | | Read agent network addresses | `GET /syscollector/{agent_id}/netaddr` | Syscollector | Cymph never writes to Wazuh — no rule, agent, or configuration is modified. Create a dedicated Wazuh API user for Cymph rather than reusing an administrator account. It keeps the access read-only and makes the integration's activity easy to identify in your Wazuh logs. ## Reading the ruleset Cymph reads the full ruleset in pages of 500 rules — the maximum the Wazuh API returns per request — and continues until every rule has been read. Custom rules at the end of the ruleset are included. Only rules carrying MITRE ATT\&CK tags contribute to a detection-based scope; rules without them are read and ignored. ## Testing the connection **Test Connection** authenticates against the instance and reports what it found: | Message | Meaning | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Valid Wazuh instance** | Authentication succeeded and the URL is a Wazuh API | | **Authorization failed** | The instance was reached but rejected the username or password | | **Connection timed out** | No response within 5 seconds — check network reachability and any firewall or allowlist between Cymph and the manager | | **Target does not seem to be a Wazuh instance** | Something answered, but not a Wazuh API — usually the dashboard URL or the wrong port | Every request Cymph makes to Wazuh times out after 5 seconds. If your manager sits behind a slow link or a firewall that drops rather than rejects, the result is a timeout rather than an error. If Cymph reaches your manager through a source-IP allowlist, confirm the egress addresses are permitted — see [Networking](/deployment/networking#egress-control). ## Editing the integration When you edit an existing Wazuh integration, the password field is left blank and is optional — leave it empty to keep the stored password, or enter a new one to replace it. The **Enabled** toggle controls whether the instance is available for use. ## Limitations Wazuh is a detection source, not a deployment target — playbooks cannot be deployed to it, so it does not appear in the Deploy dialog. # Manage integrations Source: https://docs.cymph.io/integrations/manage Create, test, edit, and delete integrations in a workspace. ## How to create an integration 1. Go to the workspace you want to add an integration for * From Workspace menu, select the workspace from the navigator 2. Go to the **Integrations** tab. * Select the Manage from the navigation menu and the **Integrations** Integrations Ws 3. Click on **New Integration** from the top right corner 4. Select your integration type. The following types are available: * [Cortex XSOAR](/integrations/automation/cortex-xsoar) * [n8n](/integrations/automation/n8n) * [Microsoft Sentinel](/integrations/detection/microsoft-sentinel) * [Wazuh](/integrations/detection/wazuh) * [Splunk Enterprise Security](/integrations/detection/splunk-es) * [Cortex XSIAM](/integrations/detection/cortex-xsiam) * [Splunk SOAR](/integrations/automation/splunk-soar) * [StackStorm](/integrations/automation/stackstorm) * [Confluence](/integrations/content/confluence) * [JIRA](/integrations/ticketing/jira) * [ServiceNow](/integrations/ticketing/servicenow) * [GitHub](/integrations/content/github) * [GitLab](/integrations/content/gitlab) * [GitBook](/integrations/content/gitbook) * [SharePoint](/integrations/content/sharepoint) * [DFIR-IRIS](/integrations/ticketing/dfir-iris) * [Azure](/integrations/cloud/azure) * [AWS](/integrations/cloud/aws) * [Slack](/integrations/notifications/slack) Integration Select Type 5. Fill in the details for your integration. In the screenshot below, you see an example for n8n. Common to all integration setups is the option to share the instance with the rest of your organisation. Integration Details 6. Before adding the integration, you can test the settings via **Test Connection** 7. Click on **Add Integration** to add your integration * Integrations should have unique name per type. * When testing an integration, the backend will give up testing after 5 seconds of trying to connect to the integration instance * Depending on the integration type, you might see different options for the integration The credentials and permissions each type needs are documented on its own page — see the [integrations overview](/integrations/overview) for the full list. ## How to update an integration 1. Go to the **Integrations** tab of the workspace. 2. Edit the integration. * Select the **Edit** icon next to the integration you want to edit. Integrations Ws Edit 3. Edit the integration details. * Provide a new name for the integration (optional). * Modify the URL of the integration endpoint (optional). 4. Test the integration (optional). * Click the **Test Connection** button. * If the integration is valid, a message will appear that the integration is tested successfully. Differently, a message containing the test error will appear. 5. Update the integration. * Click the **Update Integration** button. 6. The list of integrations will be updated automatically to reflect the new changes. ## How to delete an integration 1. Go to the **Integrations** tab of the workspace. 2. Delete the integration. * Select the **Delete** icon next to the integration you want to delete. * Confirm the deletion by clicking the **Delete** button on the confirmation dialog that appears. 3. The list of integrations will be updated automatically to reflect the new changes. Integrations Ws Delete ## Egress control Several integrations require Cymph to make **outbound** connections to an endpoint you operate — SIEM APIs (Wazuh, Microsoft Sentinel, Splunk Enterprise Security, Cortex XSIAM), SOAR platforms, ticketing systems, and similar. When that endpoint sits behind a firewall or a **source-IP allowlist** (standard practice in financial and government environments), the connection is refused unless Cymph's egress address is permitted. Symptoms of a missing allowlist entry: * **Test Connection** fails with `403` or a connection timeout. * A previously working integration goes dead while its status still shows **Enabled** — the only clue is the `403`s in your own endpoint's access logs. How you allowlist depends on which deployment model you run: a self-hosted deployment egresses from your own network, while a managed cloud tenant egresses from a published set of AWS addresses. The addresses to allowlist, and the notice policy for changing them, are in [Networking](/deployment/networking#egress-control) — that is the page to hand to a network or firewall team. # Slack Source: https://docs.cymph.io/integrations/notifications/slack Send execution and task notifications from Cymph into a Slack channel. ## What Cymph uses it for Cymph connects to Slack to **send notifications** — when a playbook execution changes state, or when a task is assigned to someone. Messages are posted to a channel you choose. Slack is a notification target only. Cymph does not read your message history, and Slack is neither a content source nor a deployment target — playbooks cannot be deployed to it. ## Notification events | Event | Sent when | | ----------------------- | ------------------------------------------------ | | **Execution started** | A playbook execution begins | | **Execution completed** | An execution finishes successfully | | **Execution failed** | An execution ends in failure | | **Execution canceled** | An execution is cancelled | | **Task assigned** | A task within an execution is assigned to a user | All notifications for a single execution are posted as **replies in one thread**, so a run occupies one conversation in the channel rather than four separate messages. ## Requirements | Field | Description | | ------------- | -------------------------------------------------- | | **Bot token** | A Slack bot user OAuth token (begins with `xoxb-`) | There is no instance URL — Cymph connects to Slack's API at `https://slack.com/api`. ## App setup 1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) for your workspace. 2. Under **OAuth & Permissions**, add the bot token scopes listed below. 3. Install the app to your workspace and copy the **Bot User OAuth Token**. 4. **Invite the bot to every channel you want Cymph to post in** — see the warning below. ## Permissions Add these as **Bot Token Scopes**: | Scope | Why Cymph needs it | | --------------- | --------------------------------------------------- | | `chat:write` | Post notification messages | | `channels:read` | List public channels so you can pick a destination | | `groups:read` | List private channels so you can pick a destination | If you only ever post to public channels, `groups:read` can be omitted — private channels simply will not appear in the picker. Adding the scopes is not enough on its own: the bot must also be **a member of the destination channel**. Slack rejects `chat.postMessage` with `not_in_channel` for any channel the app has not been invited to, public ones included. In Slack, open the channel and run `/invite @YourAppName`. If a notification fails with a scope error, Cymph reports both what your token was granted and what the call required — for example `Slack API error: missing_scope (granted: chat:write; accepted: channels:read)`. That message tells you exactly which scope to add. ## What Cymph reads and writes | Purpose | Slack API method | | ---------------------------------------- | ------------------------ | | Test the connection | `POST auth.test` | | List channels for the destination picker | `GET conversations.list` | | Send a notification | `POST chat.postMessage` | Channel enumeration covers public and private channels, follows Slack's pagination to the end, and reads only each channel's name, ID, privacy flag, membership flag, and member count. Archived channels are filtered out of the picker. Cymph never reads message content and never deletes or edits messages after posting. ## Testing the connection **Test Connection** calls `auth.test` and reports: | Message | Meaning | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Valid Slack configuration for *workspace* as *user*** | The token was accepted; the workspace and bot identity are echoed back so you can confirm you connected the right one | | **Authorization failed** | The token was rejected — usually revoked, or from a different workspace | | **Slack API error: missing\_scope (granted: …; accepted: …)** | The token is valid but lacks a required scope | | **Connection timed out** | No response within the timeout | A successful test confirms the token and its scopes, but **not** channel membership. If notifications never arrive despite a green test, the bot has almost certainly not been invited to the destination channel. ## Related Per-user email notification preferences are separate and live in [Notification settings](/settings/notifications). # Integrations overview Source: https://docs.cymph.io/integrations/overview How Cymph connects to the systems you already run — and what each connector reads and writes. An integration is a connection between a Cymph workspace and a system you already operate: a SIEM, a SOAR platform, a ticketing system, a documentation space, or a cloud account. Integrations let Cymph pull context in (detection rules, assets, existing content) and push work out (deployed playbooks, published documentation, tasks, backups). Integrations are configured **per workspace**, under **Manage → Integrations**. When you create one you can choose to share it with the rest of your organisation, so other workspaces can reuse the same instance without re-entering credentials. See [Manage integrations](/integrations/manage) for creating, testing, editing, and deleting them. ## Available integrations Import playbooks and documentation from — and publish documentation back to — GitHub, GitLab, GitBook, SharePoint, and Confluence. Derive preset scope from what you actually detect, using Wazuh, Microsoft Sentinel, Splunk Enterprise Security, or Cortex XSIAM. Discover and import cloud resources as Cymph assets from AWS and Azure. Deploy playbooks as executable workflows to Cortex XSOAR, n8n, and StackStorm. Deploy playbook steps into JIRA, ServiceNow, and DFIR-IRIS. Send execution and task notifications to a Slack channel. ## What each integration can do | Integration | Import content | Deploy workflow | Publish docs | Import assets | Detection scope | Backups | | ---------------------------------------------------------------- | :------------: | :-------------: | :----------: | :-----------: | :-------------: | :-----: | | [GitHub](/integrations/content/github) | ✓ | — | ✓ | — | — | ✓ | | [GitLab](/integrations/content/gitlab) | ✓ | — | ✓ | — | — | — | | [GitBook](/integrations/content/gitbook) | ✓ | — | ✓ \* | — | — | — | | [SharePoint](/integrations/content/sharepoint) | ✓ | — | ✓ | — | — | — | | [Confluence](/integrations/content/confluence) | ✓ | — | ✓ \* | — | — | — | | [Wazuh](/integrations/detection/wazuh) | — | — | — | ✓ | ✓ | — | | [Microsoft Sentinel](/integrations/detection/microsoft-sentinel) | — | — | — | — | ✓ | — | | [Splunk Enterprise Security](/integrations/detection/splunk-es) | — | — | — | — | ✓ | — | | [Cortex XSIAM](/integrations/detection/cortex-xsiam) | ✓ | — | — | — | ✓ | — | | [AWS](/integrations/cloud/aws) | — | — | — | ✓ | — | — | | [Azure](/integrations/cloud/azure) | — | — | — | ✓ | — | — | | [Cortex XSOAR](/integrations/automation/cortex-xsoar) | ✓ | ✓ | — | — | — | — | | [n8n](/integrations/automation/n8n) | ✓ | ✓ | — | — | — | — | | [StackStorm](/integrations/automation/stackstorm) | — | ✓ | — | — | — | — | | [Splunk SOAR](/integrations/automation/splunk-soar) | ✓ | — \*\* | — | — | — | — | | [JIRA](/integrations/ticketing/jira) | — | ✓ | — | — | — | — | | [ServiceNow](/integrations/ticketing/servicenow) | — | ✓ | — | — | — | — | | [DFIR-IRIS](/integrations/ticketing/dfir-iris) | — | ✓ | — | — | — | — | \* Markdown only — GitBook and Confluence do not accept PDF.
\*\* Splunk SOAR imports playbooks but cannot yet be deployed to — see [its limitations](/integrations/automation/splunk-soar#limitations). [Slack](/integrations/notifications/slack) is not in the table because it does none of the above: it is a one-way notification target that posts execution and task updates to a channel. ## Deploying playbooks There are two distinct kinds of deployment, and an integration supports one or the other — never both: * **Workflow** — the playbook is translated into an executable artefact on the target: an XSOAR or n8n workflow, a StackStorm action, a JIRA or ServiceNow ticket, a DFIR-IRIS case task. * **Documentation** — the playbook is published as a document: either a Markdown file, or a summary report PDF including metadata, contributors, and the workflow image. Publishing documentation is a **write** operation, so it needs broader credentials than importing does. Every content-source page states its read-only requirement and the additional permission publishing needs, side by side — check the Permissions section before granting anything. ## Network access Most integrations require Cymph to make **outbound** connections to an endpoint you operate. If that endpoint sits behind a firewall or a source-IP allowlist, you will need to permit Cymph's egress addresses — see [Egress control](/integrations/manage#egress-control). # DFIR-IRIS Source: https://docs.cymph.io/integrations/ticketing/dfir-iris Read DFIR-IRIS cases and push playbook steps into a case as tasks. ## 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 | Field | Description | | ---------------- | -------------------------------------------------------------------- | | **Instance URL** | Base URL of your DFIR-IRIS instance, e.g. `https://iris.example.com` | | **API token** | A DFIR-IRIS API key (see below) | ## 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 ## Testing the connection # JIRA Source: https://docs.cymph.io/integrations/ticketing/jira Push playbook steps into JIRA as issues. ## What Cymph uses it for Cymph connects to JIRA to read project and issue metadata, and to create issues from playbook content. This connector performs both **read** and **write** operations. JIRA and [Confluence](/integrations/content/confluence) are separate integration types but share the same Atlassian API token mechanism. The token must be created for the right app and carry the scopes listed below. ## Requirements | Field | Description | | ------------------ | ------------------------------------------------------------------- | | **Instance URL** | The URL of your instance, e.g. `https://mydomain.atlassian.net` | | **E-mail address** | The e-mail address of the Atlassian user, e.g. `myuser@example.com` | | **API token** | An API token for your JIRA account (see below) | ## Token setup Follow the instructions provided [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) to generate a token. The token must be created for the **JIRA** app and have the appropriate scopes for reading and creating issues. ## Permissions The following scopes are required: ``` read:project:jira read:issue-type:jira read:field:jira write:issue:jira ``` Or, if you are using classic scopes: ``` read:jira-work write:jira-work ``` An Atlassian API token inherits the permissions of the user it belongs to, so the account must have access to the projects you want Cymph to write into. Use a dedicated Atlassian service account rather than a personal one — issues created by Cymph will be attributed to whichever account owns the token. ## What Cymph reads and writes Cymph reads projects, issue types, and field definitions so it can build a valid issue payload, then creates issues. **Cymph never deletes issues.** Nothing already in your JIRA project is removed by the integration. ## Testing the connection # ServiceNow Source: https://docs.cymph.io/integrations/ticketing/servicenow Connect Cymph to a ServiceNow instance. ## What Cymph uses it for ## Requirements | Field | Description | | ---------------- | ----------------------------------- | | **Instance URL** | The URL of your ServiceNow instance | | **API key** | An API key from ServiceNow | To generate an API key, follow the instructions [here](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/integrate/authentication/task/configure-api-key.html). ## Permissions ## What Cymph reads and writes ## Testing the connection # Mind Maps Source: https://docs.cymph.io/key-features-explained/mindmaps Gap analysis is one of the most critical functions for cybersecurity teams. Cymph provides a unified way to analyse your operational and compliance gaps based on the concept of mindmaps. Mind Maps are versions of existing frameworks tailored to your organisational requirements. Frameworks are, in general, broad in scope. For example, the MITRE ATT\&CK framework covers many different platforms that might not even exist in your infrastructure. Thus, it is important that you select what is applicable and focus your gap analysis only to what is relevant for you. We call the customised framework version **a preset**. You can have as many presets as you want. # Frameworks overview Before starting your customisation journey, you can have an overview of all the available frameworks. By navigating to the Mind Maps menu and selecting an available framework, you will be able to see the entire framework structure. Below you can see an example from MITRE ATT\&CK for Enterprises. Framework Overview For each technique/clause of each framework you can see further details. By clicking on it, you will be able to see a detailed description, references as well as detection and mitigation strategies (whenever applicable and available). Framework Technique Details If you are searching for specific information, the platform filter and quick search will help you get quicker to the framework part you are looking for. # Presets Presets are tailored versions of frameworks that provide insights and detailed overview of your coverage status. When you create a preset, you define the scope for the selected framework (which techniques/clauses are applicable) and the playbook coverage criteria (for example playbook status must be "Complete"). You can see the detailed documentation on how to create a preset [here](/how-tos/create-and-manage-presets). The coverage status of a preset is based upon the mapped playbooks found in your management system. Any changes on your playbooks are automatically reflected to your presets. Playbooks that are revoked, marked as draft or have expired are excluded from the coverage calculations. **Insights** help you quickly assess your coverage status. You can see the coverage distribution across several dimensions of the framework. In the screenshot below, you see an example from a preset of MITRE ATT\&CK framework. You can quickly identify that although 99% of the playbooks are mapped to the framework, only 68% of the relevant techniques are covered. The tactics coverage panel provides summary information per tactic, so you can see on which tactics you perform well and for which tactics your coverage falls behind. Framework Insights2 The **Detailed Overview** provides all the coverage details. From here, you can see the status of each individual technique/clause. The green color means the technique/clause is covered, gray means no playbook is associated with it. Purple color means that the technique/clause is partially covered. By clicking on a technique/clause, you can see the same level of details as in the frameworks overview page. Presets Detailed Overview # **Closing the gaps** In the example screenshot above, you will notice that some techniques are not covered. It would be great to be able to do something about, wouldn't it? The Cymph platform allows you to generate template playbooks for these gaps! Powered by AI, you can generate detection and mitigation playbooks for all the techniques. It is an easy 3-step process: 1. Click on a technique that is currently not covered 2. Browse through the detection and mitigation strategies 3. Click on Generate Playbook for a strategy that is applicable to your context and a new playbook will be automatically generated Preset Close Gap Currently, the AI-powered generation is enabled for MITRE ATT\&CK for Enterprise presets. But there is another way to start closing your gaps: recommended playbooks. In certain scenarios, there might be a template playbook linked to the technique you lack a playbook for. Duplicate the recommended playbook to your library and start from there. Preset Recommended Playbook # Frameworks supported | Framework | Version | Link | | ---------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | MITRE ATT\&CK for Enterprises | v16.1 to v19.1 | [https://attack.mitre.org/](https://attack.mitre.org/) | | MITRE D3FEND | v1.2.0 to v1.4.0 | [https://d3fend.mitre.org/](https://d3fend.mitre.org/) | | MITRE ATLAS | v2025.11.2 to v2026.06 | [https://atlas.mitre.org/](https://atlas.mitre.org/) | | NIST CSF | 2.0 | [https://nvlpubs.nist.gov/nistpubs/CSWP/NIST.CSWP.29.pdf](https://nvlpubs.nist.gov/nistpubs/CSWP/NIST.CSWP.29.pdf) | | ISO 27001 | Edition 3, 2022 | [https://www.iso.org/standard/27001](https://www.iso.org/standard/27001) | | ISO 27002:2022 | Edition 3, 2022 | [https://www.iso.org/standard/75652.html](https://www.iso.org/standard/75652.html) | | NIS2 | Directive (EU) 2022/2555 | [https://eur-lex.europa.eu/eli/dir/2022/2555](https://eur-lex.europa.eu/eli/dir/2022/2555) | | GDPR | GDPR (EU) 2016/679 — Consolidated Version 2024 | [https://eur-lex.europa.eu/eli/reg/2016/679/oj](https://eur-lex.europa.eu/eli/reg/2016/679/oj) | | DORA RTS on ICT Risk Management
Framework - Title II | Commission Delegated Regulation (EU) 2024/1774 | [https://www.springlex.eu/en/packages/dora/rts-rmf-regulation/](https://www.springlex.eu/en/packages/dora/rts-rmf-regulation/) | # Playbook Hub Source: https://docs.cymph.io/key-features-explained/playbook-hub Playbook Hub is the central place for all publicly shared playbooks. It does not require login to the Cymph platform and thus its links can be freely shared. # Viewing a playbook By clicking on an entry in the playbook Hub, you will be redirected to the public page of the playbook, like the one displayed below Hub1 From there you can see the contents of the playbook along with basic metadata like description, owner, last updated, type and labels. ## Opening a playbook in Cymph platform Once on the public page of a playbook, you can click on **Open in Cymph** button to open the playbook in the application editor. If you are not logged in, you will be redirected to the login screen. Hub2 # Filtering by playbook type From the left-side bar of the Playbook Hub select the types that will be displayed. Once a type is checked or unchecked, the contents will be automatically refreshed Hub3 # Filtering by playbook labels From the left-side bar of the Playbook Hub select the labels that will be used for filtering. Once a label is added or removed, the contents will be automatically refreshed. Hub4 # Cymph AI Source: https://docs.cymph.io/key-features/cymph-ai A conversational assistant that drafts new playbooks, proposes reviewable improvements to existing ones, and answers questions grounded in your workspace. Cymph AI is a conversational assistant built into the platform. It is grounded in the data you have access to: your playbooks and their governance, your assets, your framework mappings and your execution history. That context is what lets it go beyond generic advice and work on your actual procedures. The assistant can: * [Draft a new playbook](#drafting-a-new-playbook) from a short description, through a guided conversation. * [Propose improvements to existing playbooks](#improving-existing-playbooks) as targeted changes that you review and approve before they are applied. * [Answer questions](#asking-questions) about your workspace, summarise content and search connected sources. AI features require the AI settings of your instance to be configured. Nothing is sent to a model unless a user explicitly asks the assistant for something. See [AI & data usage](/security/ai-data-usage). ## Opening Cymph AI There are two ways to open the assistant: * Click **Cymph AI** from the left navigation menu. Ai Assistant Nav * Click the **Ask AI** button available on most screens. Ai Sidepanel ## Drafting a new playbook Describe the playbook you need, for example "I want a playbook for Windows". Rather than guessing, the assistant asks the questions it needs to shape the draft, such as whether you want an incident response runbook for a specific alert, a high-level response plan or a generic technical playbook, and lets you describe exactly what it should cover. Answer by picking an option or typing. Ai New Playbook When the draft is ready, it appears as a card in the conversation. Click **Review** to open it in the panel on the right, where the full documentation is editable in place. Add labels, adjust the content, then click **Save to Workspace**. Before the draft is saved, Cymph asks for the Responsible and Accountable persons and a review frequency, so the new playbook starts with its governance context in place. Ai Assisted Review You can also start this flow from **Playbooks → Library → New Playbook → Generate with AI**. See [Creating your first AI-assisted playbook](/getting-started/first_playbook#how-to-create-your-first-ai-assisted-playbook). ## Improving existing playbooks Ask the assistant to improve a playbook, for example "Can you suggest improvements for the playbook RANSOM-RECOVERY?", or describe what changed in your environment or what an exercise showed. The assistant uses the playbook itself and the context around it: its assets and governance, its framework mappings, and any executions with their improvements, skip and fail reasons and timings. The response is a set of proposed changes, not a rewritten playbook. The assistant summarises what it proposes, lists each affected playbook with the number of additions and removals, and marks it **For Review**. Nothing is changed until you decide. For each playbook you can: * Click **Review change** to inspect the proposal before applying it. * Click **Apply update** to apply it directly, when the summary is enough. ### Reviewing a proposed change Ai Updates Real The review panel shows the proposal against the current content of the playbook. Removed text is struck through in red and new text is highlighted in green, with a running count of additions and removals at the top. Switch between the **Documentation**, **Properties** and **Workflow** tabs to see every part of the playbook the proposal touches. * Click **Update & Next** to apply the change and move to the next proposal. * Click **Skip** to leave the playbook as it is and move on. * Click **Open in editor** if you want to adjust the proposal by hand rather than accept or skip it as a whole. When several playbooks are affected, the pager at the top of the panel shows where you are, and you can work through them one at a time. Applied changes are saved to the playbook like any other edit, so they appear in its history and are covered by the review settings you have in place. Be specific in the request. "Update the isolation step so it meets the 10 minute target from the last exercise" produces a more targeted proposal than "improve this playbook". See [Turn operational context into better response](/use-cases/operational-learning) for how this fits into a continuous improvement loop. ## Asking questions Beyond generating and improving playbooks, the assistant answers questions about your workspace, summarises playbooks and documents, and searches the sources connected to it. Answers are grounded in the content you have access to, so the assistant never reveals playbooks or assets that are not shared with you. ## Chats Conversations are saved as **chats** so you can return to them later. * Click **New chat** to start a fresh conversation. * Use the **Search chats** box at the top of the chat list to find a previous conversation. * Chats can be renamed via their inline menu action. * Chats can be deleted. ## Attachments and voice * Click the **+** button to attach a file for additional context, for example a debrief document or an existing procedure. * Click the **microphone** icon to dictate your message instead of typing. # Playbook Editor Source: https://docs.cymph.io/key-features/editor # Overview The **Playbook Editor** **view** allows you to view, edit, create, import, export and share playbooks. It consists of four main parts: 1. The **action bar** that includes key actions like commenting, sharing, downloading and saving a playbook. 2. The **workflow editor** where you create and edit a workflow for your playbooks. * The **node panel** that allows you to select and drag a step to the workflow area. * The **control buttons** panel that provide the functionality to fit view, align nodes, zoom in and out as well as pasting. * The **workflow actions** that allow you to validate, deploy, export and download the workflow 3. The **documentation editor**, a block-based editor where you can edit the text part of your playbook Editor New Layout # Document editor The document editor allows you to write documentation for the playbook. It is a block-based editor that allows you to format the text, add bullet and numbered lists, tables, images and attachments. You can show the available commands by pressing '/' Editor Commands By selecting parts of a text, you will see the text formatting toolbar Editor Text Toolbar # Workflow editor ## Creating a step 1. Drag and drop a step from the **node panel** to the **canvas area.** * The step properties drawer panel will automatically appear on the right side of your screen. Editor New Node 2. Edit the step properties. * Fill in properties with the desired information. * Mandatory fields are marked with an asterisk (\*). * Properties are automatically saved. Editor Node Properties **Note**: Playbooks can only have one start step. Once a start step is created, the **Start Step** option will be disabled from the node panel. ## Deleting a step 1. Select the node you want to delete 2. Click on the Delete option at the bottom right corner of the step Editor Node Delete 3. Confirm that you want to delete the node. 4. The node and its connections (both incoming and outgoing) will be deleted You can also press the delete key to perform the same action. However, no confirmation is displayed in this case ## Connecting steps Once you have created a step, you can connect it to other steps. Different step types have different connection options: * Start and playbook action steps have only on completion connections. * End step has no connection options. * Action steps have on completion, on success and on failure connections. * If condition step has on completion, on true and on false connections. * Switch condition step has on completion and cases (multiple) connections. * Parallel step has next steps (multiple) and on completion connections. * While condition step has on completion and on true connections. 1. Click on the source step. * The available connections will be displayed at the bottom of the step. Editor Node Edges 2. Click on the connection type tag and it will transform into a connecting line. 3. Drag to the destination step and release to connect it. Editor New Connection ## How to delete a connection 1. Select the connection. * Click on the connection you want to delete. The connection will be highlighted. * A **Delete** icon will appear next to the connection name. 2. Delete the connection. * Click on the **Delete** icon. * Confirm the deletion on the confirmation dialog that appears. * Alternatively, you can press the delete on your keyboard to delete the connection without confirmation. Editor Delete Connection ## How to edit step properties 1. Click on **Details** for the step you want to edit the properties for. * The step properties drawer panel will appear. * Alternatively, you can double click on the step. Editor Node Details 2. Edit step properties. 3. Close the properties panel. * Click on the X button on the top left corner of the properties panel. * Alternatively, press the escape (`Esc` )key on your keyboard. ## How to edit playbook properties Playbook properties include key metadata, like ID, name, date created and modified among others. 1. Open playbook properties. * Click on the **playbook properties** icon on the editor action bar. Editor Playbook Properties 2. Edit playbook properties. * Mandatory fields are marked with an asterisk (\*). 3. Close the properties panel. * Click on the X button on the top left corner of the properties panel. * Alternatively, press the escape key. ## Adding notes You can add notes to your playbook. You can drag and drop the **Note** node. Once you click inside it, you will be able to start editing the contents of your notes ## Undoing and redoing actions You can undo or redo the following actions on the editor: * Adding a node * Deleting a node * Adding a connection * Deleting a connection The undo and redo actions are found on the control buttons Editor Undo Redo ## How to handle validation errors There are two possible places where validation errors can happen: * **Playbook properties**: There errors relate to the playbook metadata. The details about these errors will appear on the playbook properties panel. A counter will also appear on the playbook properties indicating the number of validation errors. * **Playbook steps**: There errors concern the properties of the individual steps. The details about these errors will appear on the step properties panel. A warning message will also appear on the step node in the canvas area indicating the number of validation errors. ## How to check for playbook properties validation errors 1. Check for error counter on the **playbook properties** icon. * If there are any errors, a red error counter will appear. 2. Open playbook properties panel. 3. Hover over the error message. * An error message in the format of “# validation errors” appears on the top right corner of the properties panel. * A detailed list of validation errors will appear when you hover over the warning message. ## How to check for playbook step validation errors 1. Check if an error message appears in the step. * If there are any errors, a red warning message in the format “# Validation errors” will appear. Editor Node Validation 2. Open step properties panel. 3. Hover over the error message. * An error message in the format of “# Validation errors” appears on the top right corner of the properties panel. * A detailed list of validation errors will appear when you hover over the warning message. ## How to validate a workflow Although playbook steps and properties are validated continuously, you can still manually trigger validation when desired. 1. Trigger playbook validation. * Click on the **Validate** button on the workflow action bar. 2. Validation errors, if any, will appear on individual steps and/or playbook properties panel. ## How to copy and paste steps 1. Select the step you want to copy. * Click on the step. The step will be highlighted. 2. Copy the step. * Click on **Copy** link of the step. Alternatively you can press CTRL-C (Cmd+C for MacOS) on your keyboard Editor Node Copy 1. Paste the step. * Option 1: click on the **Paste** icon in the controls buttons area. * Option 2: press CTRL-V (Cmd+V for MacOS) on your keyboard Editor Node Paste 1. A new step will appear. * A step with the same properties but without any connections will appear next to the source step. # How to align, fit view and zoom The control buttons area contains three main controls: 1. **Fit view**: The canvas is zoomed out until all steps of the playbook are visible. 2. **Align**: Steps are aligned in such a way that do not overlap. 3. **Zoom in/out**: Canvas is zoomed in/out. * You can also click and drag anywhere that is empty in the canvas area to move your viewport. # How to view and manage comments 1. Open the comments panel. * Click on the **Comment** icon on the action bar of the editor. * The comments panel will appear and existing comments will be displayed. From the comments panel, there are several actions you can take on comments: * Add your comment (optional). * Write your comment in the text area on the bottom of the panel. * Click **Submit** to add your comment. * Reply to an existing comment (optional). * Click the **Reply** icon next the comment you want to reply. * Write your comment in the text area on the bottom of the panel. * Click **Submit** to add your comment. * Delete an existing comment (optional). * Click on the **Delete** icon next to the comment you want to delete. * The comment and all its replies will be deleted. * Only the author of the comment can delete it. * Edit an existing comment (optional). * Click on the **Edit** icon next to the comment you want to edit. * Enter the new text and click **Submit** to save your changes. * The suffix “(edited)” will appear next to the edited comment. * Only the authors of the comment can edit it. # How to translate a playbook A playbook can be translated on the fly on 45 languages. The description and title of the playbook properties and its nodes are translated into the target language. All other fields are left untouched. 1. From the Action menu, go to the Language option 2. Select the language you want to translate the playbook to 3. Playbook will be translated automatically Editor Translate # How to save changes 1. Click the **Save Playbook** button. * An informational message will appear when the playbook is saved. # How to exit the editor There are two options to exit the editor: * Click the **Cymph logo.** * It is located on the top left corner of the editor. * Click the **Back to main page** button. If there are unsaved changes, a prompt will appear to ask how you will like to proceed: * **Save**: Save changes and exit the editor. * **Discard changes**: Do not save changes and exit the editor. * **Cancel**: Ignore and return back to the editor. Editor Exit2 # Executions Source: https://docs.cymph.io/key-features/executions The Cymph platform offers the ability to run playbooks without the need to defer to ticketing systems or task boards. Playbooks that contain only human-in-the loop steps (manual commands) can be submitted for execution and be tracked. Each step of the playbook can be assigned to a user. When a manual playbook is executed, a workbook is created to track progress through each step. Operators acknowledge completion of each step individually, with each action recorded along with a timestamp and the identity of the operator who performed it. Steps can be marked as completed, skipped, or failed, with an optional reason captured where relevant as well as accompanying attachments. The resulting workbook serves as an immutable audit record of the execution, preserving the full sequence of actions taken. # Eligible playbooks Playbooks that meet the following criteria can be submitted for execution: * They contain only action steps that have **manual** commands or parallel steps * They do not have an validation errors * They are not revoked Only steps that are reachable are calculated against the eligibility criteria. Steps that are isolated (not incoming connections) are ignored. # Execution editor Execution editor is the central place where all major actions for an execution happen. It is split into three major areas: 1. Global status and actions panel: this panel resides on the left side and contains information about the execution, allows you to view and add global notes and attachments and see an overview of the assignees 2. The top action bar which contains options to view and ad global notes, view and add global attachments, see an overview of the assignees, the status and duration of the execution, see the source playbook and finally see the action log. 3. The workflow panel. This is the panel where the steps of the execution are visualised. From here, you can change the status of each step as long as it is assigned to you or change the assignee for a non-completed step as long as you are the execution owner Execution Editor Overview ## Initial assignees When submitting a playbook for execution, the assignees of each step in the source playbook will be respected. If no user is assigned in the source playbook or the assigned user is not found, the execution owner will be assigned to that step. ## Timers An execution has two kinds of timers: * A **global timer** for the execution as a whole, defining how long the entire procedure is expected to take. * **Step timers**, one per step, defining how long each individual activity is expected to take. By default, timers are inherited from the source playbook. The global timer comes from the playbook's **timeout** property, and each step timer comes from the **timeout** property of the corresponding step. Both are set in the playbook editor; see [How to edit playbook properties](/key-features/editor#how-to-edit-playbook-properties) and [How to edit step properties](/key-features/editor#how-to-edit-step-properties). If no timeout is defined in the source playbook, the corresponding timer is not set. While the execution is in progress, the execution editor shows the elapsed time against each timer, so you can see at a glance which steps and which executions are running over their expected duration. The global timer starts when the execution starts and stops when the execution reaches a final status. Timers are the basis for the performance metrics in the [Executions Overview](#executions-overview). Setting realistic timeouts in your playbooks makes it easy to spot the steps that consistently take longer than expected. ## Changing step status In order to change status of a step you must be assigned to it. Changing status can be done in two ways: 1. Via the status dropdown menu of the status node Status Change Node 1. Click on a node to show the details panel and change the status from the dropdown menu there Status Change Panel The following statuses are available for a step: * Not Started * Planned * In Progress * In Review * Skipped * Failed * Completed Marking a step as skipped requires a mandatory reason. Once you select one of these statuses, a dialog will appear Skippes Status Reason Marking a step as failed also requires a mandatory reason. However, a failed step also leads to a failed execution: It stops the timer and locks the status of all steps. Steps not started or waiting for other steps will be aborted If you mark a step as failed, the entire execution is marked as failed and no further changes are allowed ### Allowed status transitions The table below summarised the allowed transitions among statuses. | Initial State | Allowed Transitions | | ------------- | ------------------------------------------------------------- | | Not Started | Planned, In Progress | | Planned | Not Started, In Progress | | In Progress | Not Started, Planned, In Review, Skipped, Failed, Completed | | In Review | Not Started, Planned, In Progress, Skipped, Failed, Completed | | Skipped | *No transitions allowed. This is a final status* | | Failed | *No transitions allowed. This is a final status* | | Completed | *No transitions allowed. This is a final status* | ## Changing step assignee If you are the execution owner, you can change assignees of a step as long the step has not finished (skipped, completed, failed, canceled) You can change a step assignee in two ways: 1. By clicking on the avatar icon of the current assignee in the step node and selecting a new one Change Assignee Node 2. By clicking on a node and change the assignees from the **Assignees** tab of the step details panel Change Assignee Panel ## Adding notes to a step 1. Click on a step and its details panel will appear 2. Navigate to the **Notes** tab 3. Enter your note text and click on **Add Note** to add it Add Step Note You can add notes at any time, independent of the step and the entire execution status ## Deleting a step note If you are the author of a note, you will be able to delete it. 1. Click on the step in order for its details panel to appear 2. Navigate to the **Notes** tab 3. Click on the delete icon of the note you want to delete 4. Select **Remove** on the confirmation dialog that appears Delete Note Exec ## Editing a step note 1. Click on the step in order for its details panel to appear 2. Navigate to the **Notes** tab 3. Click on the edit icon of the note you want to edit 4. Edit the note contents and click on **Save** to save your changes Edit Note Exec ## Managing step attachments If you want to add an attachment: 1. Click on the step in order for its details panel to appear 2. Navigate to the **Attachments** tab 3. Click on **Add Attachment** and select a file to add Exec Add Attachment If you want to download an attachment, you can click on the Download button next to the entry in the attachment list. If you own an attachment, you can also delete it by clicking on the Remove icon Exec Attachment Actions You can upload any file type as an attachment. Maximum file size is 20MB. You can add attachments to a step at any time, even if the execution is complete. ## Managing global notes Adding, editing and deleting global notes (notes for the entire execution) is similar to managing step notes. By clicking on the Notes button either from the global action panel on the left or from the top action bar, the Execution Notes drawer will open. You can add notes at any time, even if the execution is complete. ## Managing global attachments Adding, editing and deleting global attachments (attachments for the entire execution) is similar to managing step notes. By clicking on the Attachments button either from the global action panel on the left or from the top action bar, the Attachments drawer will open. You can add attachments at any time ## Canceling an execution If you own an execution and if the execution is in progress, you can cancel it anytime. In order to cancel an execution: 1. Click on the More Actions button from the top action bar Exec More Actions 2. From the dropdown menu that appears click on Cancel Execution 3. Provide a reason for cancellation in the dialog box that appears 4. Click on **Mark Execution as Canceled** to cancel the execution Exec Cancel Dialog # Executions Overview A high-level summary of all playbook execution activity, including status distribution, performance insights, and per-playbook/step metrics. ## Executions Distribution by Status This section presents a donut chart summarizing the total number of executions and their current statuses. * **Total** — The aggregate count of all executions (e.g., 8). * **Status breakdown** (shown as colored legend items): * 🔵 **In Progress** — Executions currently running (e.g., 50%). * 🔴 **Canceled** — Executions that were manually stopped before completion (e.g., 12%). * 🟢 **Completed** — Executions that finished successfully (e.g., 37%). To the right of the chart, executions are further broken down by trigger type: * **Manual** — Executions started by a user, showing a count and percentage of total (e.g., 8 / 100%). * **Automated** — Executions triggered automatically by a rule or scheduler (e.g., 0 / 0.00%). Clicking the arrow (›) next to each trigger type navigates to a filtered list of those executions. ## Insights The Insights section displays key performance metrics calculated **only across completed executions** (i.e., those not currently in progress). It contains four metric cards: | Card | Description | | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------- | | **Average Duration** | The mean time to complete an execution across the measured set (e.g., 19h 1m across 4 executions). | | **Slowest Execution** | The single execution that took the longest to complete, shown with its duration and a link to the playbook (e.g., 3d 4h 3m). | | **Fastest Execution** | The single execution that completed in the shortest time, with a link to the playbook (e.g., 8s). | | **Slowest Step** | The individual step across all executions with the highest average time, with a link to the parent playbook (e.g., 12s). | Clicking on a linked playbook name in any of the Insights cards navigates directly to the relevant execution detail. ## Performance by Playbook A paginated table ranking playbooks by execution duration, sortable via the **Sort by** dropdown (e.g., Slowest to Fastest). | Column | Description | | :------------ | :------------------------------------------------------------------------------- | | **Playbook** | The name of the playbook, displayed as a clickable link. | | **Runs** | The number of completed (non-in-progress) executions recorded for that playbook. | | **Avg. Time** | The average wall-clock time across all completed runs of that playbook. | Pagination controls (‹ page indicator ›) appear below the table when there are multiple pages of results. ## Performance by Step A paginated table ranking individual playbook steps by average execution time, also sortable via a **Sort by** dropdown. | Column | Description | | :------------ | :--------------------------------------------------------------------- | | **Step** | The name or description of the step within a playbook. | | **Playbook** | The playbook the step belongs to. | | **Runs** | The number of times this step has been executed (completed). | | **Avg. Time** | The average time taken to complete this step across all recorded runs. | Pagination controls allow browsing through all steps (e.g., page 1/2). ## Execution List 1. Navigate to the Playbook Executions page * Click on **Playbooks** from the left menu * Select **Playbook Executions** from the navigation sidebar Exec Overview Navi From that page, you can see the list of all executions run by you as well as the ones you are participating in. By default, all executions are shown ungrouped. You can group them by status so it is easier to spot what is in progress and what is completed/failed: 1. Click on **Group By Status** button 2. Executions are grouped by status Exec Overview By Status # Tasks Overview 1. Navigate to the Execution Tasks page * Click on **Playbooks** from the left menu * Select **Execution Tasks** from the navigation sidebar From that page you will be able to see: * **Overview**: in this view, you will be able to see at a quick glance your tasks, their status and the recently assigned tasks to you Exec Tasks Insights * **My tasks**: this view is a list of tasks assigned to you. You can also group by status to see the tasks grouped * **Assigned By Me**: this view is a list of tasks that you assigned to either you or other users. You can also group by status to see the tasks grouped Clicking on a task in any of the lists opens a drawer that contains the task details. This is a read-only view of the step information, notes, attachments and assignee. You can click on the **Open Task in Execution** button at the bottom of the panel to be redirected to the execution. Exec Task Details Panel # Home & Your Tasks Source: https://docs.cymph.io/key-features/home **Home** is your personal starting point in Cymph. Unlike most sections, which are scoped to a single workspace, Home aggregates your work across **all** the workspaces you belong to. ## Personal View Home is part of the **Personal View** — a context that follows you rather than a specific workspace. You can switch into it from the context switcher in the top-left corner of the platform. To work inside a specific workspace again, switch back to that workspace from the same switcher. See [Navigating the Cymph platform](/getting-started/navigating) for more on the difference between the Personal View and workspace contexts. ## All Tasks A **task** is a playbook execution step that has been assigned to you. The **All Tasks** page has three tabs: * **Overview** — A distribution donut of your tasks by status, quick counts for each status (Not Started, In Progress, Completed, Waiting), and a **Recently assigned to you** list. * **My Tasks** — Every task currently assigned to you. You can group the list by status. * **Assigned By Me** — Tasks you have assigned to yourself or to other users. You can group the list by status. ## Opening a task Selecting a task opens a read-only details drawer showing the step information, notes, attachments, and assignee. Click **Open Task in Execution** at the bottom of the drawer to jump to the full execution editor. Tasks belong to executions. To learn how executions and step statuses work, see [Executions](/key-features/executions). # Playbook Management System Source: https://docs.cymph.io/key-features/kms The **Playbook Management System** is the central place of the platform where your private, shared, and community playbooks reside. From here, you can view, search, share and, in general, perform all actions around playbooks. # Playbook views There are different views for playbooks: 1. **Created by me**: Displays the playbooks created by you. This view is under **Library** (your current workspace's playbooks). 2. **Shared with me**: Playbooks shared with you, across all workspaces. This view is available directly from the navigation menu. 3. **Recent**: Lists the playbooks recently opened or edited by you. This view is directly accessible from the navigation menu. 4. **Favourites**: Shows only the playbooks marked as favorite. This view is directly accessible from the navigation menu. 5. **Watched**: Lists the playbooks added to your watch list. This view is directly accessible from the navigation menu. 6. Public: Lists all playbooks that are publicly shared. This view is under **Explore Playbooks** sections. 7. **Trash**: Lists the playbooks marked for deletion. This view is a tab of the **Library**. To access each view, select it from the Navigation menu: Pbviews1 The **Library** shows the playbooks of your currently active workspace. Its **Overview** tab is an analytics dashboard — see [Playbook Insights](/key-features/playbook-insights). The **Shared with me**, **Recent**, **Favourites**, and **Watched** views span all your workspaces. # Playbook table The playbook table lists all playbooks that match the selected view. It consists of eight columns: 1. **Name**: The playbook name. 2. **Stage**: There are 3 different stages for a playbook: * **Draft**: the playbook is marked as a draft. * **Live**: the playbook can be used * **Revoked**: the playbook is obsolete and has been revoked. 3. **Last Modified**: The relative time since the last update of the playbook. 4. **Status**: the current status of the playbook. Valid statuses can be: * **Planned** * **In progress** * **In review** * **Completed** 5. **Sharing status**: provides an indicator if the private is private, shared with others or shared publicly 6. **Labels**: This column lists the user-defined labels. 7. **Owner**: The avatar of the playbook owner. Hover over the avatar to see the name of the owner. 8. **Automation**: the automation degree of the playbook 9. **Steps**: the number of steps involved in the playbooks 10. **Links**: shows information on the source of the playbook (e.g. if it is imported from a SOAR system) and how this playbook is linked to configured presets Pbtable1 # Exploring playbooks The Explore playbook section contains playbooks that are publicly shared so you can freely browse them. ## Discover area This area proposes a set of most popular playbook collections organised around various prominent threats and incident types. It also lists the top 5 public playbooks in terms of views that can be relevant to you and your team Discoverarea ## All public playbooks This is a playbook table containing all playbooks shared publicly # Playbook Insights Source: https://docs.cymph.io/key-features/playbook-insights The **Playbook Insights** view is a dedicated analytics dashboard within **Library** that gives you a bird's-eye view of your playbook portfolio. It surfaces risk signals, coverage gaps, distribution metrics, and engagement stats so you can quickly understand the health and maturity of your playbooks at a glance. To access Playbook Insights, navigate to **Library** and select the **Overview** tab. You can export the insights dashboard to PDF using the **Export PDF** button in the top-right corner of the Library Overview. ## Filters At the top of the page you will find a **Saved Filters** selector and a **Filters** button. These work the same way as in other playbook views — they let you scope all the data on the page down to a specific subset of playbooks (e.g. by label, stage, source, or incident type). Any filter you apply affects all widgets on the page simultaneously. ## My Playbooks Distribution This summary widget shows the total number of playbooks in scope and breaks them down into two categories: * **Owned By Me Playbooks**: The count and percentage of playbooks you own. * **Shared With Me Playbooks**: The count and percentage of playbooks others have shared with you. Each category is clickable and takes you directly to the corresponding filtered view (**Owned by me** or **Shared with me**). Insights Top Level ## Risk Signals The **Risk Signals** section highlights operational gaps and governance issues across your playbooks. Each signal shows a count of affected playbooks and an action button so you can address it immediately. You can sort the signals using the **Sort by** dropdown (default: **Critical First**). The available signals are: * **Playbooks with no assigned responsible person**: Playbooks that are missing a RACI-assigned responsible owner. Click **Take an action now** to bulk-assign one. * **Playbooks with no assigned accountable person**: Playbooks without an accountable stakeholder. Click **Take an action now** to address this. * **Playbooks not tested the last 6 months**: Playbooks that have not been exercised or validated recently. Click **Review** to go through them. * **Playbooks not reviewed.** Playbooks that are due for review. * **Playbooks without review settings**. Playbook that have no assigned reviewer and review frequency. * **Orphaned playbooks**: The responsible or accountable person no longer has access to this playbook, for example the account is deleted, the user has been removed from the workspace or the playbook is unshared. Revise the RACI matrix to maintain accountability and governance of workflows. * **Playbooks with stale consulted, informed, or reviewer assignees**: A consulted, informed, or the reviewer no longer has access to this playbook. Update the RACI matrix and reviewer settings to keep stakeholders aligned * **Playbooks that include removed or retired assets**: Playbooks still referencing assets that have been deleted or retired from the platform. * **Playbooks without mappings**: Playbooks that have no framework or incident type mappings. * **Playbooks not updated the last 6 months**: Playbooks that may be stale and need a review. * **Overly complex playbooks (30+ steps)**: Playbooks that exceed 30 steps and may benefit from being split into smaller, more focused procedures. Use the **Show Less / Show More** toggle to collapse or expand the full list of signals. ## Top Framework Tags This panel lists the most-used framework technique tags across your playbooks. You can filter by framework using the dropdown (e.g. **MITRE ATT\&CK Matrix for Enterprise**) and sort the results with the **Sort by** dropdown (default: **Most Used**). The table shows two columns: * **Tag**: The technique identifier and name (e.g. *T1046 - Network Service Discovery*). Each tag is a clickable chip that filters the playbook list. * **Linked Playbooks**: The number of playbooks associated with that tag. You can page through the results using the pagination arrows at the bottom of the panel. ## Framework Mapping Overview This panel sits alongside **Top Framework Tags** and gives a per-framework summary of your mapping coverage. It shows: * **Framework**: The name of the framework (e.g. *MITRE ATT\&CK Matrix for Enterprise*). * **Linked Playbooks**: How many playbooks are mapped to that framework. Below the table, three counters show the breakdown: * **Mapped Playbooks**: Playbooks that have at least one framework tag. * **Unmapped Playbooks**: Playbooks with no framework mapping at all. * **Multimapped Playbooks**: Playbooks mapped to more than one framework. Use the pagination arrows to move between frameworks. ## Incident Type Distribution This bar chart shows how your playbooks are distributed across incident types (e.g. *Phishing*, *Data exfiltration*, *Social engineering*, *Spoofing*). Use the **Sort by** dropdown to change the ordering of the bars. Hovering over each bar reveals the exact playbook count for that incident type. Pagination arrows allow you to browse incident types if there are more than can fit on one page. ## Insights (Quick Stats) Below the distribution charts, four highlight cards surface the most important single-value metrics from your current playbook set: * **Top Incident Type**: The incident type with the most linked playbooks, along with the count of linked playbooks. * **Main Source**: The source (e.g. *Cymph*) that contributes the largest number of playbooks to your library. * **Most Targeted Asset**: The asset referenced most frequently across your playbooks, along with the number of playbooks that reference it. * **Most Viewed Playbook**: The individual playbook that has been opened the most times, along with the total open count. ## Labels The **Labels** widget renders a word cloud of all labels assigned to playbooks in the current view. Labels that appear more frequently are displayed in a larger font. This gives you a quick visual summary of the most common themes, tactics, and categories across your playbook library. ## Playbook Source Origin This donut chart shows the percentage breakdown of your playbooks by source origin (e.g. *Cymph*, imported from a SOAR, etc.). Hovering over each segment reveals the source name and its percentage. ## Automation Degree This bar chart shows how many playbooks fall into each automation bracket: * **0%**: No automation * **1–25%**: Low automation * **26–50%**: Moderate automation * **51–75%**: High automation * **76–100%**: Fully or near-fully automated This helps you understand how much of your playbook portfolio can run without manual intervention and where investment in automation could be most impactful. ## Stage Distribution This horizontal stacked bar chart shows the proportion of playbooks in each lifecycle stage: * **Live** (green): The playbook is active and usable. * **Draft** (purple): The playbook is a work in progress. * **Revoked** (red): The playbook has been retired and is no longer in use. The percentage for each stage is displayed directly on the bar. ## Impact and Severity Distribution Two horizontal bar charts show the distribution of your playbooks by their assigned **Impact** and **Severity** values. The scale for both ranges across: **Not Specified**, **Low**, **Medium**, **High**, and **Critical**. These fields are set on each individual playbook and help you understand the overall risk posture of your library. ## Incident Response Stage Distribution This bar chart shows how your playbooks are distributed across incident response stages (e.g. *Containment*, *Recovery*, *Preparation*, *etc.*). Use the **Sort by** dropdown to change the ordering of the bars. Hovering over each bar reveals the exact playbook count for that incident type. Pagination arrows allow you to browse incident types if there are more than can fit on one page. ## Last Test Distribution This bar chart shows the period where your playbooks were last tested / exercised. Ranges are split into the following periods: * Never tested * Last month * 1–6 months ago * 6–12 months ago * Over a year ago ## Linked With Assets Breakdown This pie chart shows how many playbooks are linked with assets, either directly or via asset types. # Workspaces Source: https://docs.cymph.io/key-features/workspaces Create and manage workspaces within your organisation Workspaces allow you to organise your work within Cymph. They provide isolated environments for playbooks, executions, assets, integrations and presets, making it easy for teams to collaborate without interfering with each other. **Multi-tenancy model:** Data isolation (logical isolation), not hardware isolation. Tenants share the same platform infrastructure while their data remains strictly segregated. ## Overview Every user and every organisation has at least one workspace: * **Individual workspace**: A private workspace created automatically for each user. Only the owner can access it — nobody else can be added to an individual workspace. * **Organisation default workspace**: A workspace automatically created for each organisation. All current organisation members are auto-joined to this workspace, and they are auto-removed when they leave the organisation. Organisation admins can create additional workspaces beyond the default one. These additional workspaces have their own member lists that are managed independently of the organisation's membership. Only users with the Admin role in the organisation can create or delete workspaces. In the free plan, no additional workspaces can be created. ## The Workspaces page The Workspaces page lists all workspaces you have access to. To navigate to it, go to the **Organisation** section from the navigation menu and select **All Workspaces**. Each workspace is shown as a card with the following information: * The workspace name and logo * The organisation it belongs to (and a **Default** tag if it is the organisation's default workspace, or an **Individual** tag if it is a personal workspace) * A summary of resources: Playbooks, Executions, Assets, and Presets * The list of members (for organisation workspaces) Clicking on a workspace card opens the workspace detail page, which contains the following tabs: **General**, **Members**, **Integrations**, **Deploy History**, and **Backup**. ## How to create a workspace 1. Go to the **Workspaces** page. * From the navigation menu, go to **Organisation** and then select **All Workspaces**. 2. Click the **New Workspace** button in the top-right corner. 3. Enter the workspace details. * **Workspace Name** (required): must be unique within the organisation. * **Description** (optional): a short description of the workspace's purpose. * **Workspace Logo** (optional): upload a logo in PNG, GIF, or JPEG format, up to 5 MB in size. 4. In the next step, add the initial members of the workspace * Select a role for each member you add. By default, if the user is an organisation member, their initial role in the workspace is inherited from their organisation role. If the user is not part of the organisation, they are added as viewers by default. 5. Click **Create Workspace**. The new workspace will appear on the Workspaces page and in the workspace switcher. Only organisation admins can create new workspaces Did you know? You can also create a workspace directly from the workspace switcher in the top-left corner of the platform by clicking **Create workspace** ## How to delete a workspace 1. Go to the **Workspaces** page. * From the navigation menu, go to **Organisation** and then select **All** **Workspaces**. 2. Hover over the workspace you want to delete. 3. Click the **Delete Workspace** button from the menu in the top-right corner. 4. A confirmation dialog will appear. Confirm the deletion. The workspace will be permanently deleted and will no longer appear on the Workspaces page or in the workspace switcher. The organisation's default workspace cannot be deleted. Individual workspaces cannot be deleted. Only organisation admins can delete workspaces ## How to add members to a workspace Member management applies to additional (non-default) organisation workspaces. For the default workspace, membership is managed automatically based on organisation membership. 1. Go to the **Workspaces** page and click on the workspace you want to manage. 2. Select the **Members** tab. 3. Click the **Manage Members** button in the top-right corner. 4. Enter the details of the member(s) you want to add. * Select the member(s) you want to grant access to this workspace. * Set the role that each member will have to this workspace 5. Click **Update Members** to confirm. The Members table will be automatically refreshed to reflect the changes. You can also add external users to the workspace. By default, the Viewer role is assigned to external users. Only organisation admins can manage workspace members. ## How to remove members from a workspace 1. Go to the **Workspaces** page and click on the workspace you want to manage. 2. Select the **Members** tab. 3. Click the **Manage Members** button in the top-right corner. 4. Locate the member you want to remove from the list. 5. Click the remove icon next to their entry. 6. Confirm the removal. The member will be removed from the workspace and the Members table will be refreshed. ## The Members table The **Members** tab of a workspace shows a table with the following columns: * **Name**: the name of the member. * **E-mail Address**: the member's email address. * **Joined**: the time elapsed since the member joined the workspace. * **Role**: the member's role in the organisation (e.g. Admin, Editor, Collaborator, Viewer). * **Access**: indicates how the member gained access to the workspace. Members who joined through organisation membership are shown as **Org. Member**. ## How to switch between workspaces You can switch between workspaces at any time from the workspace switcher in the top-left corner of the platform. 1. Click the workspace name displayed in the top-left corner of the dashboard. * A dropdown will appear listing all workspaces available to you, grouped by owner. 2. Click on the workspace you want to switch to. The platform will reload in the context of the selected workspace. Alternatively, you can switch to a workspace from its detail page: 1. Go to the **Workspaces** page and click on the workspace you want to switch to. 2. Click the **Switch to Workspace** button in the top-right corner. Did you know? The currently active workspace is always shown in the top-left corner of the platform, next to the Cymph logo. # AI & data usage Source: https://docs.cymph.io/security/ai-data-usage Which Cymph features use AI, what data reaches a model, and how the provider is configured. Cymph's AI features are additive: the platform is fully usable with AI disabled, and in a self-hosted deployment it is disabled until an administrator turns it on. ## Which features use AI | Feature | Uses an AI provider | | --------------------------------------------------------------------------- | ------------------------------------------------------- | | Playbook generation from a prompt | Yes | | Mindmap generation | Yes | | Autotagging | Yes | | Semantic search over playbooks | **No** — embeddings are generated inside the deployment | | Everything else — editing, execution, sharing, integrations, administration | No | Semantic search is worth calling out because it looks like an AI feature and is often assumed to be one. It runs on a local embedding service (`all-MiniLM-L6-v2`) that ships as part of the deployment, so **playbook content is never sent to an external provider in order to be searchable**. Search works whether or not AI is enabled. ## Who provides the model **You do — in both deployment models.** Cymph does not bundle, resell or operate a model on your behalf. An administrator enters a base URL, an API key and a model name, and Cymph calls that endpoint using an OpenAI-compatible API. See [AI configuration](/deployment/settings/ai). Because the base URL is yours to choose, you can point Cymph at a commercial API, at a provider in a specific jurisdiction, or at a model hosted inside your own network. If you need AI processing to stay in a particular region for GDPR or data-residency reasons, you satisfy that by choosing a provider that meets the requirement — it is not a property of the Cymph deployment. This has a direct consequence for your data-processing analysis: **the relationship for AI features is between you and the provider you select.** Cymph is not a processor in that path and cannot see the requests. This holds for a [managed cloud tenant](/deployment/managed-cloud-tenant) exactly as it does for a self-hosted deployment — the AI provider is a customer-configured setting in both. ## What reaches the model Only the content needed for the feature you invoked: * **Playbook generation** — the prompt you write, and the context of the playbook being generated. * **Mindmap generation** — the prompt or source material you supply. * **Autotagging** — the playbook content being tagged. AI features are invoked explicitly by a user action. There is no background process that sends stored playbooks, execution records, assets or integration credentials to a model, and nothing is sent from a workspace nobody has asked the AI to act on. ## Provider credentials The AI provider's API key is stored in the deployment's database encrypted with that deployment's own key material, and decrypted only in memory when a request is made. In a self-hosted deployment it never leaves your infrastructure. See [Data protection](/security/data-protection#encryption-at-rest). ## Turning AI off Leave the AI settings unconfigured, or clear them. Without a base URL and API key the AI features are unavailable and no outbound calls are made — in either deployment model. Semantic search continues to work. This is the default state of a new deployment: AI is off until an administrator configures a provider, so no content reaches a model unless someone has deliberately enabled it. # Security architecture Source: https://docs.cymph.io/security/architecture How Cymph is deployed, where the trust boundaries sit, and how tenant data is separated. This page is a summary of Cymph's security posture for security reviewers, architects and procurement teams. It covers both deployment models; where they differ, the difference is called out. ## Deployment models Cymph is delivered as a **managed cloud tenant** or as a **self-hosted** deployment. Both are dedicated single-instance deployments running the same product — neither is a shared multi-tenant service. What differs is who operates the infrastructure. | | Managed cloud tenant | Self-hosted | | ---------------------------------------------- | ---------------------------------- | ------------------------------------------ | | Infrastructure operated by | Cymph | You | | Location | AWS `eu-west-1` (Europe / Ireland) | Your infrastructure | | Database | AWS managed PostgreSQL | PostgreSQL container inside the deployment | | TLS certificates, DNS, backups, upgrades | Cymph | You | | Encryption key custody | Cymph | You | | Network path to integrations | Cymph's egress addresses | Entirely within your network | | AI provider | Supplied by you, or disabled | Supplied by you, or disabled | | Application configuration, users, integrations | You | You | [Deployment models](/deployment/models) has the full responsibility split. A self-hosted deployment has no runtime dependency on Cymph: it does not call home for licensing, updates or telemetry — see [Architecture](/deployment/self-hosted/architecture) for the full service inventory. ## Trust boundaries A deployment has exactly one externally exposed entry point: the `nginx` service, which terminates TLS and reverse-proxies to the application. The web application, API, embedding service and database are bound to an internal network only — none of them is published on the host — so every request that reaches the application has passed through TLS termination. There is no second, unencrypted path in. See [Networking](/deployment/networking) for the inbound and outbound specifics. Outbound, Cymph connects only to the integration endpoints you configure and to an AI provider if one is enabled. Semantic search embeddings are generated by a service inside the deployment, so playbook content is not sent anywhere for search to work. ## Tenant and data isolation Each customer deployment — managed or self-hosted — is a **separate instance with its own database**. There is no shared data store across customers. Within a deployment, Cymph uses **logical data isolation**: users and organisations share the instance while their data remains segregated. The isolation boundary is the **workspace**. Playbooks, executions, assets, integrations and presets all belong to a workspace, and access is determined by workspace membership: * Every user has a private **individual workspace** that nobody else can be added to. * Every organisation has a **default workspace** that all members join automatically, and which they leave automatically when they leave the organisation. * Organisation admins can create **additional workspaces** with independently managed member lists, so a subset of the organisation can work in isolation from the rest. [Workspaces](/key-features/workspaces) covers the model in full, including how membership is managed. Organisation membership is a separate axis: a user belongs to one organisation at a time, and their [role](/administration/user_roles) within it determines what administrative actions they can take and how widely they can share playbooks. ## Encryption **In transit.** All browser and API traffic is served over HTTPS. In a self-hosted deployment you supply the certificate and key and TLS is terminated at nginx — see [TLS certificates](/deployment/self-hosted/tls-certificates); in a managed tenant Cymph provisions and renews them. Connections from the application to PostgreSQL can additionally require SSL, and are configured to do so whenever the database is not on the same host as the application. **At rest.** Sensitive integration data — the credentials, tokens and endpoint secrets you enter when configuring a SIEM, SOAR platform, ticketing system or repository — is encrypted before it is stored, using key material generated at random when the deployment is created. In a self-hosted deployment that key material (`CYMPH_ENCRYPTION_KEY` and `CYMPH_ENCRYPTION_IV`) is generated on your host and never leaves it. See [Data protection](/security/data-protection) for what this means for backups and key custody. ## Authentication and authorisation Accounts authenticate with a password plus optional TOTP multi-factor authentication, or through an external identity provider. Authorisation is role-based at the organisation level and membership-based at the workspace level. See [Authentication & access control](/security/authentication-access-control). ## Auditability Administrative and product activity is recorded and reviewable in the application, with actor, target and metadata per event. See [Audit & logging](/security/audit-logging). # Audit & logging Source: https://docs.cymph.io/security/audit-logging Review administrative and product activity in the Audit Logs page. The **Audit Logs** page (**On-premises Administration → Audit Logs**) lets administrators review administrative and product activity across the on-premise deployment. Common fields are shown in the table, while action-specific actor, target and metadata details are available per entry. ## Layout overview The page is organised, top to bottom, into four regions: 1. **Summary cards** — headline counts for the currently visible entries. 2. **Timeline filter bar** — a histogram of activity over time with a range selector. 3. **Filter & Action bar** — search, dropdown filters, and actions (refresh, reset, export). 4. **Log entries** — the paginated, sortable, expandable table of events. All filters compose: the numbers in the summary cards and every row in the table always reflect the combined result of the timeline window **and** the filter bar. Audit Log Interface ## 1. Summary cards Four cards summarise the **currently filtered** set of entries (not the full dataset): | Card | Meaning | | ------------------ | ------------------------------------------------------------------------------------------ | | **Visible events** | Total number of entries matching the active filters. | | **Successful** | Count of entries with status `success`. | | **Failed** | Count of entries with status `fail`. Rendered in the danger colour when greater than zero. | | **Unique actors** | Number of distinct actor emails among the visible entries. | Because these are computed from the filtered result, narrowing the timeline or applying a filter updates the counts immediately. *** ## 2. Timeline filter bar A daily activity histogram that doubles as a time-range control. * **Bars** — one bar per day that has activity; bar height is the event count for that day. Hovering a bar shows a tooltip with the date and count. Bars inside the selected window are highlighted (purple); bars outside are muted (grey). * **Timeline preset dropdown** — quick presets: **All**, **Today**, **Last month**, **Last 3 months**, **Last 6 months**, **Last year**, and **Custom**. Selecting a preset snaps the range slider to the matching window. * **Range slider** — the dual-handle slider below the histogram lets you drag either end to set a custom start/end day. Dragging it automatically switches the preset to **Custom**. * **Range label** — the timestamp on the right (e.g. `2026-06-11 00:00:00 - 2026-08-04 23:59:59`) shows the exact start and end of the selected window. Only entries whose timestamp falls within the selected window are counted and listed. *** ## 3. Filter & Action bar A row of controls that filter the table and drive page actions. Every filter is combined with **AND** logic and layered on top of the timeline window. | Control | Behaviour | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search box** | Free-text search across action, actor, target, IP and metadata. Matching is case-insensitive and runs over the full serialised entry, so it also matches nested metadata values. | | **All actions** | Filter to a single action type. Options are derived from the actions present in the data. | | **All actors** | Filter to a single actor by email. Searchable dropdown. | | **All IP addresses** | Filter to a single source IP. Searchable dropdown. | | **All statuses** | Filter by `Success` or `Failed`. | | **Failures only** | Toggle button — a shortcut that pins the status filter to `fail` (turns red when active). Click again to clear. | | **Reset filters** | Clears the search box, all dropdown filters, and resets the timeline back to **All**. | | **Refresh** | Manually re-fetches the audit logs and restarts the auto-refresh countdown. | | **Export** | Dropdown to download the **currently filtered** entries as **CSV** or **JSON**. Disabled when there is nothing to export. | ### Auto-refresh The page automatically re-fetches every **30 seconds**. The `Next update in Ns` label next to the actions counts down to the next refresh; clicking **Refresh** resets the countdown. *** ## 4. Log entries The main table lists individual events. Rows with a `fail` status are tinted with the danger background so failures stand out. ### Columns | Column | Notes | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Timestamp** | Formatted `YYYY-MM-DD HH:mm:ss`; hover shows the raw value. Default sort is newest-first; the column is sortable. | | **Action** | The action identifier (e.g. `user.update-dark-mode`). Sortable. | | **Status** | A pill: `Success`, `Failed`, or a capitalised fallback for other values. Sortable. | | **Actor** | The actor's email plus `User #`, or **System** when there is no user id. | | **Target** | The object the action affected. Resolved to a human-readable label (email, org name, `Playbook #…`, `User #…`, etc.) or `-` when absent. | | **IP Address** | Source IP of the request. | | **User Agent** | Client user-agent string, truncated with ellipsis. | ### Row expansion Every row is expandable (the **`+`** control on the left). Expanding a row reveals the complete entry as pretty-printed JSON — including the full actor, target, and any action-specific metadata that isn't shown in the columns. ### Pagination The table paginates at **10 rows per page**. ### Export format Exports contain the same filtered rows as the table: * **CSV** — columns: Timestamp, Action, Status, Actor Email, Actor User ID, Target, IP Address, User Agent, Metadata (metadata serialised as JSON). Filename: `audit-logs-.csv`. * **JSON** — the raw entries (minus the internal row key). Filename: `audit-logs-.json`. # Authentication & access control Source: https://docs.cymph.io/security/authentication-access-control Sign-in methods, multi-factor authentication, session handling and the permission model. ## Sign-in methods Users authenticate in one of two ways: * **E-mail and password**, with optional multi-factor authentication. * **An external identity provider** — Google, GitHub or Microsoft Entra ID. Accounts created through an identity provider have no password until one is set. Because multi-factor authentication requires a password, users who signed up with Google or GitHub are prompted to set one before they can enable MFA. The procedure is in [Security settings](/settings/security-setting). In a self-hosted deployment, each identity provider is off by default and enabled by the on-prem administrator with a client ID and secret from the registered OAuth application — see [Single sign-on](/deployment/settings/sso). Enabling a provider is deployment-wide; there is no per-organisation provider configuration. ## Multi-factor authentication MFA uses time-based one-time passwords (TOTP) and works with any standard authenticator app, such as Google Authenticator or Microsoft Authenticator. Users enrol by scanning a QR code (or entering the key manually) and confirming a 6-digit code. Enrolment is **per user and self-service** — each user enables it from their own [security settings](/settings/security-setting). Disabling it also requires a valid code, so an attacker holding only the password cannot turn it off. There is no organisation-level setting to require MFA for all members. If your policy mandates MFA, enforce it through your identity provider by making SSO the only sign-in path for your users. ## Sessions and password lifecycle The values below are the defaults for a self-hosted deployment, set in the environment file at install time: | Setting | Default | | ----------------------------- | ------- | | Session expiry | 2 hours | | Password reset token validity | 7 days | | Password expiration | 60 days | Password expiration means users are required to change their password periodically rather than indefinitely reusing one. Password reset relies on outbound e-mail, so a self-hosted deployment must have [SMTP configured](/deployment/settings/smtp) for self-service recovery to work — without it, an administrator has to intervene. Administrators can also prompt a user to reset their password from the members table, which raises a notification in that user's notification centre. See [Manage members](/administration/manage_members). ## The permission model Access is governed on two independent axes. ### Organisation role Every user has one [role](/administration/user_roles), which determines their administrative rights and how widely they can share playbooks: | Role | Administrative rights | Sharing scope | | ---------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | **Admin** | Full control: invite and remove members, edit organisation settings, create and delete workspaces, manage teams | Specific users, own organisation, other organisations, publicly | | **Editor** | None | Specific users, own organisation | | **Collaborator** | None | Specific users, own organisation, other organisations, publicly | | **Viewer** | None | — | | **Individual** | Applies to users with no organisation | Full permissions over their own content | Each organisation must retain at least one Admin. An admin cannot change their own role or remove themselves from the organisation, which prevents an organisation from being left without an administrator. ### Workspace membership Role governs *what* a user can do; workspace membership governs *which data* they can do it to. Playbooks, executions, assets, integrations and presets are scoped to a workspace, and only its members can reach them — an organisation Admin does not implicitly see the contents of a workspace they are not a member of. [Workspaces](/key-features/workspaces) has the details. ## Administrative access in self-hosted deployments Self-hosted deployments have an additional **on-prem administrator** account, created during [installation](/deployment/self-hosted/installation) and separate from any organisation. It manages licensing, deployment-wide settings, organisations and audit logs. This account is created with a default password that must be changed at first login. It has no organisation membership and therefore no access to any workspace's playbook data. Treat the on-prem administrator as a break-glass account. It can create organisations and add members without invitation, and its recovery procedure requires shell access to the host — see [Resetting the administrator password](/deployment/self-hosted/reset-admin-password). Self-hosted deployments can also add members to an organisation directly, without an e-mail invitation. Accounts created this way start with a known default password and are forced to change it at first login. The behaviour and its failure cases are documented in [Invite members](/administration/invite_members#adding-members-without-an-invitation). ## API access The REST API authenticates with an API key sent in the `x-cymph-api-key` header. Keys are created by individual users from their own settings, are named, and are issued with an expiration period. A key acts on behalf of the user who created it, so it inherits that user's role and workspace membership — revoking a user's access revokes what their keys can reach. See [API access](/settings/api-access). # Data protection Source: https://docs.cymph.io/security/data-protection Where Cymph data lives, how sensitive data is encrypted, and who holds the keys. ## Where data lives | | Managed cloud tenant | Self-hosted | | ----------------- | ----------------------------------- | -------------------------------------- | | Application | AWS `eu-west-1` (Europe / Ireland) | Your infrastructure | | Database | AWS managed PostgreSQL, same region | PostgreSQL container in the deployment | | Search embeddings | Generated inside the deployment | Generated inside the deployment | | AI processing | Your provider, or none | Your provider, or none | Each deployment is a dedicated instance with its own database — there is no shared data store across customers. In a managed tenant, data stays in the EU. In a self-hosted deployment, data never leaves your infrastructure except over connections you configure: the integration endpoints you point at, your SMTP server, your identity provider, and an AI provider if you enable one. ## What Cymph stores A deployment's PostgreSQL database holds playbooks and their contents, execution records, assets, presets, user accounts, organisations, workspaces and their membership, integration configuration, and audit logs. Application logs, static files and data files live alongside it on disk. In a self-hosted deployment this maps to two Docker volumes, `cymph_db-data` and `cymph_api-data`. [Architecture](/deployment/self-hosted/architecture) breaks down what is in each. In a managed tenant the same data sits on managed AWS database and filesystem services. ## Encryption in transit All browser and API traffic is served over HTTPS. Self-hosted deployments terminate TLS at nginx using a certificate you supply — see [TLS certificates](/deployment/self-hosted/tls-certificates). Managed tenants use certificates provisioned and renewed by Cymph. Connections from the application to PostgreSQL can require SSL. In a self-hosted deployment this is off by default, because the bundled database runs on the same host over an internal Docker network — enable it if you place the database anywhere else. Managed tenants use a managed database reached over the network, with SSL required. Outbound integration connections use whatever transport the target endpoint offers — for HTTPS endpoints, that traffic is encrypted end to end between Cymph and your system. ## Encryption at rest Sensitive integration data is encrypted before it is written to the database. This covers the credentials and secrets you supply when configuring an integration — API keys, tokens, passwords and endpoint secrets for SIEMs, SOAR platforms, ticketing systems and repositories. Encryption uses a key and initialisation vector held in the deployment's configuration (`CYMPH_ENCRYPTION_KEY` and `CYMPH_ENCRYPTION_IV`), generated at random when the deployment is created. Each deployment has its own. **In a self-hosted deployment, you hold this key material.** It is generated on your host, stored in the deployment's environment file, and is never transmitted to Cymph. This means: * Cymph cannot decrypt your integration credentials, and cannot recover them for you. * Anyone with read access to the host's configuration files can read the key. Restrict access to the deployment directory accordingly. * The key cannot be regenerated. Losing it makes existing encrypted data permanently unreadable. Key custody is the single most consequential operational detail in a self-hosted deployment. A database backup taken without `.env` and `db/secrets.txt` is not a complete backup — it restores, but its integration credentials cannot be decrypted. See [Backup & restore](/deployment/self-hosted/backup-restore). Passwords are not stored recoverably; account recovery issues a reset rather than returning an existing password. ## Backups **Self-hosted.** Backups are yours to run, and yours to protect. The recommended method is a Docker volume snapshot taken during a maintenance window, archived together with the deployment's configuration files. Because those files contain the encryption key and signing secrets in plaintext, a Cymph backup archive is itself sensitive material and should be stored encrypted with access restricted. The full procedure, including restore, is in [Backup & restore](/deployment/self-hosted/backup-restore). **Managed cloud tenant.** Backups are taken and retained by Cymph, within the same AWS region as your tenant. There is nothing for you to configure or run. ## Deleting data Users can delete their own account, which removes it from the platform — see [Delete your account](/settings/delete_account). When the last member of an organisation leaves, the organisation is deleted with them. Removing a member from an organisation does not delete the playbooks they created: those are **transferred to the organisation's administrator**, so work does not disappear when someone leaves. This applies both to removals and to voluntary departures. See [Manage members](/administration/manage_members). ## Auditability Administrative and product activity is recorded with actor, target and metadata per event, and is reviewable and exportable in the application. See [Audit & logging](/security/audit-logging). # Account settings Source: https://docs.cymph.io/settings/account ## How to edit your account settings 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click **Settings.** Account2 3. Go to the account settings. * Click the **Account** tab of the settings panel, if not selected already. 4. Edit your basic account settings. * **Change your name (optional)**. Click on the pencil icon next to the **Name** field to edit your name. Press **Enter** to submit your changes. * **Change your job title (optional)**. Click on the pencil icon next to the **Job Title** field to edit your name. Press **Enter** to submit your changes. * **Change your company name**. Click on the pencil icon next to the **Company field** to edit your name. Press **Enter** to submit your changes Changeacc1 5. **Update or remove your profile picture (optional)**. Click on your current profile picture displayed on the left of the panel. From the panel that appears you can select to either remove your profile picture or upload a new one. You can upload PNG and JPG pictures up to 2MB large. Your profile picture will be updated once the upload is successful. You will also be able to scale and rotate your picture before it is saved. Changeprofilepic 6. **Change your profile visibility (optional)**. By default, your account is discoverable by all Cymph users. You can turn this behavior off. 7. **Export your data**. By clicking on Export Data you will receive a compressed file with all your playbooks for your records. Export # API Access Source: https://docs.cymph.io/settings/api-access You can access the Cymph platform via API from your applications. Cymph exposes a REST API so you can programmatically perform the same functionality as the Web application. ## Authentication Authentication is achieved via the **x-cymph-api-key** HTTP header. ## Create an API key 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. 2. Go to your settings. * Click **Settings.** 3. Go to API access management page * Click on **API Keys** tab 4. Create a new key * Click on **New Key** button New Api Key 5. Enter a name and select an expiration period Api Key Setup 6. The API key will be created and displayed. Make sure you copy the key because it will not be displayed again! Api Key Copy ## Deleting an API key The generated API keys are listed in the API key management page. Only the last five characters of the key are displayed to help you locate the key. If you want to delete it, press the Delete button of the key's entry Delete Api Key # Create an organisation Source: https://docs.cymph.io/settings/create_org If you are not part of an organisation, e.g., you did not create an organisation during sign-up or have left an organisation, you can create an organisation at any time. # How to create an organisation 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. 2. Go to your settings. * Click **Settings.** 3. Go to the **Organisation** tab 4. Click on **Create Organisation.** 1. The new organisation wizard will start. Createorg1 5. Fill in the organisation details. * **Organisation name** is mandatory. Organisation names in Cymph are case insensitive, they must be at least 3 characters long and are unique across the platform. * You can upload a logo for your organisation. Supported formats are PNG, GIF and JPEG and the maximum file size is 5MB. Createorg2 6. Provide additional information for the organisation * **Sector (optional).** The sector where the organisation belongs * **URL (optional).** A URL for the organisation. 7. Click **Create Organisation.** * The organisation will be created and you will be automatically assigned as Administrator for the organisation. Createorg3 8. As a last step, you can optionally invite members to your newly created organisation * You can skip that part by clicking **Invite later** option. Orginviteaftercreation You can cancel the process at any point by clicking on **Cancel** on the top right corner # Delete your account Source: https://docs.cymph.io/settings/delete_account ## How to delete your account 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click on **Settings.** Account2 3. Go to the account settings. * Click on the **Account** tab of the settings panel, if not selected already. 4. Delete your account. * Click on the **Delete account** button. * A confirmation dialog will appear. Deleteacc1 5. **Confirm** that you want to delete your account. Type "DELETE" in the input box and click on the **Delete Account** button * Upon confirmation, you will be redirected to the login / signup screen. Deleteaccconfirm * You cannot delete your account if you are the last user with an Admin role for that organisation and there are other users in the organisation. Assign the Admin role to another member in order to proceed with your account deletion. * When you delete your account and there are other users in your organisation, all the playbooks created while a member of that organisation will be **inherited** by the first available user in the organisation with the Admin role. * If the user is the last member of the organisation then the **organisation will be deleted** and all their playbooks will be **deleted permanently.** * All the playbooks created by the user while not in an organisation will be **deleted permanently**. # Language settings Source: https://docs.cymph.io/settings/language-settings ## How to edit your language settings 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click **Settings.** Account2 3. Go to **Preferences** 4. Select the language to be used for the user interface Account Ui Lang2 5. The user interface will be automatically refreshed upon selection of a language # Leave your organisation Source: https://docs.cymph.io/settings/leave_org This section describes how to leave your current organisation. If you are not part of an organisation, the relevant options in your account settings panel will not appear. ## How to leave your current organisation 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click on **Settings.** Account2 3. Go to the organisation settings. * Click on the **Organisation** tab of the settings panel, if not selected already. 4. Leave your organisation. * Click on the **Leave Organisation** button. * A confirmation dialog will appear. Leaveorg1 5. **Confirm** that you want to leave the organisation. Leaveorgconfirm * You cannot leave your organisation if you are the last user with an Admin role for that organisation. * When you leave an organisation, all the playbooks created while a member of that organisation will be inherited by the first available user in the organisation with the Admin role. # Notification settings Source: https://docs.cymph.io/settings/notifications ## How to edit your notification settings 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click **Settings.** Account2 3. Go to the notification settings. * Click the **Notifications** tab of the settings panel, if not selected already. 4. Edit your notification settings. * **Change your email notification settings.** Check or uncheck the box next to “**Enable all notifications by email**” to opt-in or opt-out from email notifications respectively. * **Change your product notification settings**. Check or uncheck the box next to “**Send me occasional emails with updates and promotions from Cymph**” to opt-in or opt-out from email regarding product tips and news respectively. Notifsettings These settings control **your own** email notifications. Notifications sent to a Slack channel are configured for the whole organisation — see the [Slack integration](/integrations/notifications/slack). # Security settings Source: https://docs.cymph.io/settings/security-setting From the security settings you can setup multi-factor authentication ## Enable multi-factor authentication It is recommended that you enable multi-factor authentication for your account. 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. 2. Go to your settings. * Click **Settings.** 3. Go to security settings * Click on **Security** tab 4. Start the multi-factor authentication enablement process * Click on the **Enable** button Mfa Enable If a password is not set for your account, you will be asked at this stage to set one. In the setup dialog that appears: 1. Enter your current password Mfa Enter Password 2. Scan the QR code from the authenticator application of your choice (e.g. Google, Microsoft authenticators) * If you cannot scan the QR code, you can also enter the key manually 3. Once the Cymph app is setup on your authenticator app, enter a 6-digit OTP 4. Click **Confirm** and if the code is valid, the setup will finish Mfa Setup2 ## Disable multi-factor authentication In case that multi-factor authentication is no longer desired, you can disable it by clicking on the Disable button: Mfa Disable You will be asked for a 6-digit OTP from the authenticator app. If the code is valid, MFA will be disabled. ## Setting up a password In case you have signed up via Google or GitHub, a password will not be set for your account. You can manually set a password for your account from the Security settings page. You will be asked for your e-mail address. You will receive an e-mail to reset your password. By clicking on the link on that e-mail you will be redirected to the password reset form and there you will be able to enter your password. # Update your password Source: https://docs.cymph.io/settings/update_password Users who have registered via e-mail during signup or have manually set up a password can change their password following the procedure described in this section. ## How to update your password 1. Go to your profile menu. * **Click your profile picture** on the top right corner of the dashboard. Account1 2. Go to your settings. * Click on **Settings.** 3. Go to the security settings. * Click on the **Security** tab of the settings panel 4. Click on Change Password * The change password dialog will appear Changepass1 5. Update your password. * **Provide your** **current password** in the first input. * **Provide your new password** in the second input. * **Confirm your new password** by typing it again in the third input. * Click on the **Update** button once the password security criteria described below are met and the Password and Confirm Password fields match. If the password change is successful, a popup message will be displayed. Changepass2 **Did you know?** You can see the password you type by clicking on the eye icon inside each password input field. ## Password Security Criteria User password must meet the following criteria in order to be accepted by the Cymph platform: * They must be **at least 12 characters long**. * They must include at least **one special character** (:;,.?\\-=+|!@#\$%^&()\[]/). * They must include at least **one digit** (0-9). * They must include at least **one capital letter** (A-Z). * They must include at least **one lowercase letter** (a-z). * They **must not be the same as the last** **24 passwords** used. # Reporting a bug Source: https://docs.cymph.io/troubleshooting/bug_reporting If you encounter an issue or a bug, you can file a bug report via the web application. 1. Open the **Account** menu. * Click on your avatar in the top right corner. Account1 2. Go to **About** dialog box. About1 3. Click the **Bug Report** button. * The **Bug Report** form will appear. Bugreport1 4. Insert a title and a description for your issue. 5. Add tags to your issue (optional). 6. Click the **Submit** button. Bugsubmit # I cannot login Source: https://docs.cymph.io/troubleshooting/cannot_login If you have trouble logging in, check the following: * If you are logging in via email and password, make sure you have entered the correct credentials. In case of invalid credentials, you should see an error message just below the password field: Wrongpass * Make sure your account is not locked due to too many password failures. * Try to reset your password: 1. From the login screen, click on **Forgot Password?** Forgotpass1 2. Enter the e-mail address that you have used upon registration. Resetpass1 An e-mail will be sent with further instructions on how to reset your password. **Need more help?** Send our support team a note at [support@cymph.io](mailto:support@cymph.io)! # General troubleshooting tips Source: https://docs.cymph.io/troubleshooting/general * Check if you are using a supported browser. The Cymph application has been tested on the latest Chrome, Firefox and Safari web browsers. * Check if the domain is resolvable from your machine. You can use a tool like [https://mxtoolbox.com/DNSLookup.aspx](https://mxtoolbox.com/DNSLookup.aspx) to perform a DNS lookup. If no results are returned from the lookup, check your DNS settings and connectivity. * Clear the application data on your browser (cookies, local and session storage) for the webpage and try again. **Need more help?** Send our support team a note at [support@cymph.io](mailto:support@cymph.io)! # I have problem registering Source: https://docs.cymph.io/troubleshooting/registering This section lists potential issues and errors that can happen during registration: 1. **I have provided the wrong e-mail address**. Please check that your e-mail address is correct. 2. **I have not received a verification e-mail**. Check your spam folder. Verification e-mails come from [noreply@cymph.io](mailto:noreply@cymph.io). **Need more help?** Send our support team a note at [support@cymph.io](mailto:support@cymph.io)! # Playbook governance Source: https://docs.cymph.io/use-cases/governance Bring playbooks from any source under one governance layer, add the context Cymph needs, and act on the risk signals it surfaces. Response playbooks rarely live in one place. Some are built in Cymph, others sit in GitHub, Confluence or SharePoint, and others run inside a SOAR platform. Cymph brings all of them into a single governance layer without forcing you to migrate the underlying content: ownership of the workflow stays at the source, while Cymph tracks who is responsible, when it was last reviewed, which assets it protects and how it maps to your frameworks. This use case walks through the full loop: 1. [Bring your playbooks together](#1-bring-your-playbooks-together) by importing or creating them. 2. [Understand what is missing](#2-new-content-has-no-governance-context) on freshly imported or created content. 3. [Add governance context](#3-add-governance-context) such as the RACI matrix, review settings, assets and framework mappings. 4. [Turn context into risk signals](#4-turn-governance-into-risk-signals) from the Library overview and take action from there. # 1. Bring your playbooks together Start by getting every playbook that matters into your workspace. Go to **Playbooks → Library** and click **Import**. The import dialog lists all supported sources: Cymph playbook files, SOAR platforms such as Cortex XSOAR, Cortex XSIAM, Splunk SOAR, Logic Apps and n8n, documents in PDF, DOC, Markdown or plain text, and knowledge repositories such as GitHub, GitLab, GitBook, Confluence and SharePoint. Use Case Governance Import You can, of course, also build playbooks directly in Cymph using the editor or the AI assistant. Governance applies the same way regardless of where a playbook came from. **Ownership stays at the source.** Playbooks imported from a SOAR keep a read-only workflow, and playbooks imported from a repository or knowledge management system remain linked to their origin. In both cases you still add and edit all Cymph metadata. See the [ownership model](/howto/import_playbook#ownership-model) for the details per source. Useful references for this step: * [Import playbooks](/howto/import_playbook) covers file-based and live-system imports and the validation step. * The [content source integrations](/integrations/content/github) explain how to connect GitHub, GitLab, GitBook, SharePoint and Confluence. * [Creating your first playbook](/getting-started/first_playbook) covers building a playbook from scratch or with AI. # 2. New content has no governance context An imported playbook arrives with its workflow and documentation, but nothing else. It has no responsible or accountable person, no reviewer or review frequency, no linked assets and, unless you enabled automatic framework mapping during import, no framework mappings. The same is true for a playbook created from scratch in the editor. This is by design. The source system knows how to run the playbook, but it does not know who owns it in your organisation, how often it must be reviewed, or which parts of your environment it protects. That context is what Cymph needs in order to govern the playbook, and it is what the rest of this use case adds. Playbooks generated with the AI assistant are the one exception. Before an AI draft is saved, Cymph asks for the Responsible and Accountable persons and a review frequency, so those playbooks start with a minimum of governance context already in place. See [Creating your first AI-assisted playbook](/getting-started/first_playbook#how-to-create-your-first-ai-assisted-playbook). # 3. Add governance context Take the imported playbook, for example a ransomware response playbook, and add the settings that describe how it is governed. All of them can be set from the **Playbook Management System** by hovering over the playbook, opening the action menu and choosing the setting under **Playbook Settings**. Most can also be set from the settings drawer inside the editor. See [Modify playbook settings](/howto/modify-playbook-properties) for the full list and where each one is editable. For a typical ransomware playbook, the governance context looks like this: | Setting | Example | What it gives you | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **RACI matrix** | Responsible: SOC team. Accountable: Head of Incident Response. Consulted: IT, Legal. Informed: Management. | Clear ownership and a named person for every stakeholder role. | | **Review settings** | Reviewer: SOC lead. Frequency: quarterly. | A review cadence Cymph can track and flag when it lapses. | | **Assets and asset types** | Active Directory, Windows endpoints. | Knowledge of which parts of your environment this playbook covers. | | **Incident type and response stage** | Ransomware, containment. | Classification used by filters, presets and the overview dashboards. | | **Framework mappings** | MITRE ATT\&CK techniques such as T1486 Data Encrypted for Impact. | Coverage tracking against the frameworks you care about. | | **Stage** | Live. | Signals that the playbook is production-ready. Draft and revoked playbooks are excluded from coverage. | | **Last tested** | Date of the last tabletop exercise. | Evidence that the playbook has been exercised, not just written. | How to set each of these: * **RACI matrix, review settings, assets, incident type, response stage and last tested** are all under **Playbook Settings** in the action menu. See [How to change playbook settings](/howto/playbook_actions#how-to-change-playbook-settings). * **Framework mappings** are set with the **Set Mappings** action. If you are unsure which techniques apply, ask for [AI suggestions](/howto/playbook_actions#ai-suggestions). See [How to set mappings](/howto/playbook_actions#how-to-set-mappings). * **Stage** is changed with the mark as draft and revoke actions. See [How to mark and unmark a playbook as draft](/howto/playbook_actions#how-to-mark-and-unmark-a-playbook-as-draft). * When a review takes place, record it with the **Mark as Reviewed** action so the review clock resets. See [How to mark a playbook as reviewed](/howto/playbook_actions#how-to-mark-a-playbook-as-reviewd). Assets must exist in your workspace before you can link them to a playbook. You can add them manually, import them from a file, or discover them from Wazuh, Nessus, AWS or Azure. See [Asset management](/howto/asset_actions). # 4. Turn governance into risk signals Once the context is in place, Cymph evaluates it continuously. Go to **Playbooks → Library** and open the **Overview** tab. The **Risk Signals** panel lists every governance and readiness gap across the playbooks in your workspace, with a count of affected playbooks and an action button next to each one. Use Case Governance Overview The signals that matter most for governance are: * **Playbooks with no assigned responsible person** and **Playbooks with no assigned accountable person**. Nobody owns the playbook. * **Playbooks without review settings** and **Playbooks not reviewed**. Either no review cadence exists, or a review is overdue. * **Playbooks not tested the last 6 months**. The playbook has never been exercised, or not recently. * **Orphaned playbooks** and **Playbooks with stale consulted, informed, or reviewer assignees**. Someone in the RACI matrix no longer has access, for example because they left the workspace. * **Playbooks that include removed or retired assets**. The playbook references parts of your environment that no longer exist. * **Playbooks without mappings**. The playbook is invisible to your framework coverage analysis. To act on a signal, click **Take an action now** or **Review** next to it. This opens the affected playbooks, so you can assign an owner, set a reviewer or add mappings for several playbooks at once. As soon as the gap is fixed, the count drops and the signal disappears from the list. Use **Filters** and **Saved Filters** at the top of the Overview to scope the signals to a subset of playbooks, for example only ransomware playbooks or only playbooks imported from a specific source. The whole dashboard follows the filter. See [Filter playbooks](/how-tos/filter-playbooks). The rest of the Overview tab complements the risk signals. **Framework Mapping Overview** and **Top Framework Tags** show where your coverage is thin, **Stage Distribution** shows how much of your library is actually live, and **Last Test Distribution** shows how recently playbooks were exercised. All of these are described in [Playbook Insights](/key-features/playbook-insights). # Keeping governance current Governance is not a one-off exercise. Your environment changes, people move, and playbooks age. A few habits keep the signals green: * **Review the Overview regularly.** Make the Risk Signals panel part of your weekly or monthly routine, and export it to PDF with **Export PDF** when you need to report on readiness. * **Keep assets in sync.** When new infrastructure appears, for example a new Azure production environment, import it as an asset and check which playbooks should cover it. See the [Azure](/integrations/cloud/azure) and [AWS](/integrations/cloud/aws) integrations. * **Use presets for coverage.** Risk signals tell you what is wrong with the playbooks you have. [Mind Maps](/key-features-explained/mindmaps) presets tell you which techniques or controls have no playbook at all, and can generate template playbooks to close those gaps. * **Ask Cymph AI for help.** When a playbook needs to be adapted to a new asset or scenario, [Cymph AI](/key-features/cymph-ai) can draft the changes using the context already in the platform. Cymph does not replace where your response knowledge lives. It provides the governance layer that keeps it owned, measurable and relevant as your environment changes. # Turn operational context into better response Source: https://docs.cymph.io/use-cases/operational-learning Keep playbooks, assets, coverage and exercise results together in one place, and let Cymph AI turn what changed and what you learned into targeted playbook updates. Your response environment never stands still. Infrastructure changes, teams change, exercises reveal weaknesses and new response gaps appear. The hard part is not noticing that something changed. It is knowing exactly what that change means for your response procedures, and updating them before the next incident finds out for you. Cymph brings the context needed to answer that question into one place, and uses it to propose changes that are grounded in your organisation rather than in a generic template. The loop looks like this: 1. [Bring the context together](#1-bring-the-context-together): playbooks and their governance, assets and their relationships, framework coverage and execution history. 2. [Keep the context current](#2-keep-the-context-current) so Cymph can tell which procedures a change affects. 3. [Learn from executions](#3-learn-from-executions): timings, deviations and improvements captured during exercises. 4. [Turn context into targeted changes](#4-turn-context-into-targeted-changes) with Cymph AI, on the specific step that needs to change. 5. [Create what is missing](#5-create-what-is-missing) when the answer is a new playbook rather than an update. 6. [Keep people in control](#6-keep-people-in-control) by reviewing and approving every proposed change before it reaches the playbook. This page builds on the three previous use cases. [Playbook governance](/use-cases/governance) adds the context, [Identify and close response gaps](/use-cases/response-gaps) measures coverage, and [Test and train your response](/use-cases/test-and-train) produces the execution results this page learns from. # 1. Bring the context together A recommendation is only as good as the context behind it. A generic checklist can tell you that a ransomware playbook should include endpoint isolation. It cannot tell you that your isolation step is assigned to a team that no longer exists, that it references an EDR console you replaced last quarter, or that it took eighteen minutes in the last exercise. Cymph holds all of that in one workspace: | Context | What Cymph knows | Where it comes from | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Playbooks and their governance** | The workflow and documentation of every procedure, who is responsible and accountable, when it was last reviewed and tested, and its stage. | [Playbook governance](/use-cases/governance), [Modify playbook settings](/howto/modify-playbook-properties) | | **Assets and relationships** | The systems a playbook protects, their criticality, owners, environment, and what depends on, runs on or is used by what. | [Asset management](/howto/asset_actions) | | **Framework coverage** | Which techniques and controls each playbook is mapped to, and which ones have no procedure at all. | [Mind Maps](/key-features-explained/mindmaps), [Identify and close response gaps](/use-cases/response-gaps) | | **Executions** | What actually happened when the team tested a procedure: who did what, how long each step took, what was skipped or failed and why, and the improvements recorded afterwards. | [Executions](/key-features/executions), [Test and train your response](/use-cases/test-and-train) | Because these objects are linked to each other, a change in one of them has a visible effect on the others. A playbook links to the assets it covers, an execution links to the playbook it tested, and a framework mapping links the playbook to the coverage of a preset. This is the context [Cymph AI](/key-features/cymph-ai) draws on when you ask it to improve a procedure. The more context a playbook carries, the more targeted the recommendations become. If your playbooks still lack assets, RACI assignments or framework mappings, start with the [governance use case](/use-cases/governance). The **Risk Signals** panel in the Library overview shows exactly which playbooks are missing what. # 2. Keep the context current Context that is six months old is barely better than no context. Playbooks and assets in Cymph stay aligned with the systems they came from, so the picture Cymph reasons about reflects your environment as it is now rather than as it was when the playbook was written. That alignment is what turns a change in the environment into a response question. When an asset is retired or replaced, when a procedure is updated at its source, or when the people in a RACI matrix move on, Cymph can identify which response procedures are affected. Go to **Playbooks → Library → Overview** and check the **Risk Signals** panel: * **Playbooks that include removed or retired assets** lists the procedures that reference infrastructure which no longer exists. * **Orphaned playbooks** and **Playbooks with stale consulted, informed, or reviewer assignees** list the procedures whose owners or stakeholders have left the workspace. * **Playbooks not tested the last 6 months** and **Playbooks not reviewed** list the procedures whose evidence has gone stale. Each signal opens the affected playbooks, so the question "what does this change mean for our response?" has a concrete list as its answer. See [Playbook Insights](/key-features/playbook-insights). # 3. Learn from executions The second source of context is what happened when the team tested a procedure. Open a completed exercise, for example the ransomware tabletop from the [test and train use case](/use-cases/test-and-train), in **Playbook Executions**. The workbook holds: * **Improvements** recorded on a step or on the whole execution, such as "Escalation contact in this step is outdated" or "Nobody was sure who could authorise a shutdown". * **Skipped and failed steps**, each with the mandatory reason entered at the time. * **Timings** per step and for the execution as a whole, compared against the timers that were set. * **Performance metrics** across executions, including the slowest steps and the slowest playbooks. Exec Overview By Status Together they describe what worked, what did not, where the team struggled and how long activities actually took. A typical finding reads like this: > **Endpoint isolation procedure took 18 minutes. Target: 10 minutes.** The analyst had to request approval from the on-call manager before isolating the host, and the EDR console path was not documented in the step. On its own, that finding says that the playbook needs work. Combined with the rest of the context, it says exactly which step, which asset and which responsibility are involved. See [Capture what needs to improve](/use-cases/test-and-train#5-capture-what-needs-to-improve) for how to record findings during and after an exercise. # 4. Turn context into targeted changes This is where the context pays off. Open [Cymph AI](/key-features/cymph-ai) and describe what changed or what the exercise showed, for example "Endpoint isolation took 18 minutes in the last exercise against a 10 minute target; update the procedures that rely on it". The assistant already has access to your playbooks, their governance and assets, their framework mappings and the execution history. It does not need you to paste the findings in. Ai Updates Real Instead of a general statement that a playbook needs improvement, the assistant works out which procedures are affected and proposes a change to a specific place in each of them. For the finding above, the chain looks like this: | | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Finding** | Endpoint isolation exceeded its target duration because of a manual approval and an undocumented console path. | | **Affected procedures** | Every playbook that references the endpoint isolation step, such as Ransomware Response, Phishing Email Triage & Response and BEC Response. | | **Proposed change** | Insert a pre-authorised EDR isolation path, document the console location, and reserve the approval for critical assets only. | Depending on what the context shows, a proposed change can: * **Modify an instruction** that was unclear or outdated, for example the console path or the escalation contact. * **Insert a missing step**, for example a pre-authorised containment path or a notification that was performed ad hoc during the exercise. * **Update the relevant context**, for example replacing a retired asset with the one that took its place, or adjusting a step timer to a realistic target. * **Address a responsibility that caused a delay**, for example reassigning a step or adding the approver to the RACI matrix so the decision is pre-agreed. The assistant lists the affected playbooks with the number of proposed changes in each, and marks every one **For Review**. The proposals are scoped to the finding and to your environment. They name your assets, your roles and your existing steps, because those are what the assistant was given. Be specific in the request. "Update the isolation step so it meets the 10 minute target from the last exercise" gives a better proposal than "improve this playbook". You can also attach a debrief document or paste a finding that was not captured in the execution. # 5. Create what is missing Sometimes the answer is not an update. When the context reveals a response capability that does not exist yet, the right move is a new playbook. The most common trigger is a coverage gap. In a Mind Maps preset, an uncovered technique means a threat you can detect, or have decided matters, but have no procedure for. From the technique details, click **Generate Playbook** on the strategy that fits your context, and Cymph AI drafts a playbook for that technique and maps it to the framework. See [Close the gap](/use-cases/response-gaps#4-close-the-gap). Use Case Gaps Generate Playbook Other triggers come from the same context: a new production environment imported as assets that no playbook covers, or an exercise that showed the team improvising a procedure that was never written down. In both cases, ask Cymph AI to generate the playbook from the assistant. The draft is grounded in the assets, procedures and response requirements already in your workspace, and Cymph asks for the Responsible and Accountable persons and a review frequency before it is saved, so the new playbook starts with governance context in place. See [Creating your first AI-assisted playbook](/getting-started/first_playbook#how-to-create-your-first-ai-assisted-playbook). # 6. Keep people in control AI proposes. Your team decides. No AI-proposed change becomes part of your response knowledge until someone has reviewed and approved it. Each affected playbook in the assistant's list offers two actions: **Apply update**, which applies the proposal directly, and **Review change**, which opens it for inspection first. In the review panel, Cymph shows the proposal against the current content of the playbook: removed text is struck through and new text is highlighted, with a count of additions and removals, across the **Documentation**, **Properties** and **Workflow** tabs. From there each change can be: * **Approved**, with **Update & Next**, which applies the change and moves on to the next playbook. * **Skipped**, with **Skip**, which leaves the playbook as it is. * **Edited**, with **Open in editor**, when the intent is right but the detail needs adjusting by hand. Once a change is approved, close the loop the same way as after an exercise. Record the review with **Mark as Reviewed**, set **Last tested** if the change was driven by an exercise, and check that the relevant risk signals have cleared. The next execution then measures whether the change actually made the response faster. See [Reviewing a proposed change](/key-features/cymph-ai#reviewing-a-proposed-change) and [Close the learning loop](/use-cases/test-and-train#6-close-the-learning-loop). AI features require the AI settings of your instance to be configured. See [AI & data usage](/security/ai-data-usage). # The loop Context → Learn → Adapt → Test → Context. Every change in your environment updates the context. Every exercise adds what the team learned. Cymph AI turns both into targeted changes that your team reviews, and the next exercise tests whether they worked. Response readiness stops being a document you wrote once and becomes something that improves with every change and every exercise. # Identify and close response gaps Source: https://docs.cymph.io/use-cases/response-gaps Define what you should be ready for, measure your playbook coverage against it, and generate the procedures you are missing. Are your response procedures actually covering the threats that matter to your organisation? Cymph gives you a structured way to answer that question using established cybersecurity frameworks such as MITRE ATT\&CK, D3FEND, ATLAS and NIST CSF 2.0, and compliance standards such as ISO 27001, NIS2, GDPR and DORA. The model is simple: 1. [Decide what you should be ready for](#1-define-the-scope) by defining a scope, either by hand or derived from what your security stack actually detects. 2. [Measure response coverage](#2-measure-response-coverage) by mapping your playbooks to that scope. 3. [Find the gaps](#3-find-the-detection-to-response-gap), in particular the techniques you can detect but cannot yet respond to. 4. [Close them](#4-close-the-gap) by generating the missing playbook, then reassess. All of this happens in the **Mind Maps** section. If you are new to it, read [Mind Maps](/key-features-explained/mindmaps) first: it explains frameworks, presets and coverage. # 1. Define the scope A framework such as MITRE ATT\&CK is deliberately broad. It covers platforms, tactics and techniques that may have nothing to do with your environment. A **preset** is your tailored version of a framework: the subset of techniques or controls that you want to measure readiness against. Cymph gives you two ways to establish that subset. ## Path 1: Custom scope Start from what you decide matters. Create a preset, pick a framework and version, and select the techniques yourself. For example, a preset named **Ransomware Readiness** based on MITRE ATT\&CK for Enterprise would include initial access, credential access, lateral movement and impact techniques typically seen in ransomware campaigns. You do not have to click through the matrix manually. The scope can also be imported from a **MITRE ATT\&CK Navigator layer** or from a set of **Sigma rules**, which is useful when a threat intelligence team or an assessment has already produced a technique list. Cymph also offers ready-made **scenarios**, such as phishing or ransomware, as a starting point. Custom scopes suit questions like: are we ready for this threat, this customer environment, or this audit? See [Manage presets](/how-tos/create-and-manage-presets) for the full wizard, and in particular [Step 2: Select the scope source](/how-tos/create-and-manage-presets#step-2-select-the-scope-source). ## Path 2: Detection-derived scope Or start from your live environment. Connect Cymph to your SIEM and let your detection capabilities define the scope. Cymph reads the detection rules from the integration, collects the MITRE ATT\&CK technique tags on each rule, and turns the result into the preset scope. When several integrations are selected, their techniques are merged. Supported detection sources are [Wazuh](/integrations/detection/wazuh), [Microsoft Sentinel](/integrations/detection/microsoft-sentinel), [Splunk Enterprise Security](/integrations/detection/splunk-es) and [Cortex XSIAM](/integrations/detection/cortex-xsiam). The integration must exist in the workspace before you can pick it in the wizard. See [Configure live source](/how-tos/create-and-manage-presets#configure-live-source). Detection-derived scopes stay in sync with your SIEM. Cymph refreshes the scope from the configured sources whenever the preset is opened, so a rule added or removed in your SIEM is reflected the next time you look at the preset. Both paths produce the same thing: a set of techniques that should have response coverage. | | Custom scope | Detection-derived scope | | ----------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | | **Answers** | What do we decide matters? | What can our security stack actually detect? | | **Source** | Manual selection, Navigator layer, Sigma rules or scenario | Detection rules from Wazuh, Sentinel, Splunk ES or Cortex XSIAM | | **Best for** | Threat, customer or assessment-driven readiness | Detection-to-response gap analysis | | **Maintained by** | You | Your SIEM, refreshed automatically | # 2. Measure response coverage When you save the preset, you also choose which playbooks count towards coverage and what "covered" means. In the preset settings you scope the playbook set, for example only playbooks created by you or only those matching a saved filter, and in the coverage criteria you decide whether a mapped playbook is enough on its own or whether it must also have a certain status, such as Completed. See [Step 4: Configure the preset settings](/how-tos/create-and-manage-presets#step-4-configure-the-preset-settings) and [Step 5: Set coverage criteria](/how-tos/create-and-manage-presets#step-5-set-coverage-criteria). Cymph then maps your playbooks to the scope through their framework mappings and shows you the result: * **Insights** summarise coverage across the preset, for example the share of techniques covered and a per-tactic breakdown, so you can see at a glance where you perform well and where you fall behind. * **Detailed Overview** shows every technique in scope. Green means covered, purple means partially covered, and grey means no playbook is mapped to it. Coverage depends on playbooks being mapped to the framework. If your playbooks are not mapped yet, enable **Use automatic framework mappings when manual mappings are not set** in the preset settings, or set mappings on the playbooks with [AI suggestions](/howto/playbook_actions#ai-suggestions). Playbooks that are draft, revoked or expired never count towards coverage, so keep the stage of your playbooks accurate. See the [governance use case](/use-cases/governance) for how to keep that metadata in order. # 3. Find the detection-to-response gap With a detection-derived scope, the Detailed Overview becomes a direct comparison between what you detect and what you can respond to. Every technique in the preset is one your SIEM has a rule for. Every grey technique is therefore a place where you can detect an attack but have no defined procedure to respond to it. Click a technique to see its details. For example, **T1548.003 Sudo and Sudo Caching** might show a detection rule in Wazuh but no mapped playbook. That is the gap this use case is about: you can detect it, but can you respond to it? The same view answers the question for custom scopes, where a grey technique means a threat you decided matters but have not prepared a response for. # 4. Close the gap Identifying the gap is only the beginning. From an uncovered technique, Cymph can help create the missing procedure. 1. In the Detailed Overview, click the uncovered technique. 2. Browse the **detection** and **mitigation** strategies listed for it. 3. Click **Generate Playbook** on the strategy that applies to your context. Cymph AI drafts a playbook for that technique and maps it to the framework. Use Case Gaps Generate Playbook The generated playbook is a starting point, not a finished procedure. From here the workflow continues as with any other playbook: * **Review and refine** it in the editor, and add the governance context described in the [governance use case](/use-cases/governance): responsible and accountable persons, review settings and linked assets. * **Deploy** it to your SOAR or ticketing system if it should run there. See [Deploy playbooks](/how-tos/deploy-playbooks). * **Reassess.** Any change to your playbooks is reflected in your presets automatically. Once the new playbook meets the coverage criteria, the technique turns green. AI-powered playbook generation is available for MITRE ATT\&CK for Enterprise presets and requires the AI settings of your instance to be configured. For techniques where a template playbook already exists, the technique details also offer a **recommended playbook** that you can duplicate into your library instead. See [Closing the gaps](/key-features-explained/mindmaps#closing-the-gaps). # Frameworks without framework maintenance Whichever path you use, Cymph provides the underlying framework structure and keeps it up to date. Frameworks are versioned, and you choose the version when you create a preset, so a new release of MITRE ATT\&CK never silently changes the meaning of an existing preset. When imported tags do not match the selected version, the wizard reports them as validation errors instead of remapping or dropping them, and lets you switch version. The currently supported frameworks and versions are listed under [Frameworks supported](/key-features-explained/mindmaps#frameworks-supported). Define what matters yourself, or derive it from what you actually detect. Cymph shows you where you are ready and where response gaps remain. # Test and train your response Source: https://docs.cymph.io/use-cases/test-and-train Run your playbooks as exercises, measure how the team performs, and turn what you learn into better procedures. Having a response playbook does not mean your team is ready to use it. Procedures need to be tested, teams need to practise their roles, and when something does not work you need to know exactly what to improve. Cymph lets you take the same operational playbooks your team maintains and run them as exercises. The loop looks like this: 1. [Turn a playbook into an exercise](#1-turn-a-playbook-into-an-exercise) by starting an execution. 2. [Test roles and responsibilities](#2-test-roles-and-responsibilities) by assigning steps to the people who would perform them. 3. [Run the exercise](#3-run-the-exercise) against the timers and collect evidence while it happens. 4. [Measure performance](#4-measure-performance) across exercises. 5. [Capture what needs to improve](#5-capture-what-needs-to-improve) as findings tied to the procedure. 6. [Close the learning loop](#6-close-the-learning-loop) by updating the playbook and recording the test. The mechanics of executions are documented in [Executions](/key-features/executions) and [Execute playbooks](/howto/execute-playbooks). This page focuses on how to use them for exercises. # 1. Turn a playbook into an exercise Pick the playbook you want to test, for example a ransomware response playbook, and start an execution. From the **Playbook Management System**, open the playbook's action menu and select **Run Playbook**. You can also start one from inside the editor. Give the execution a name that identifies the exercise, such as "Ransomware tabletop, Q3", and optionally a description of the scenario. Cymph creates a **workbook** for the execution: a copy of the workflow where every step carries a status, an assignee, notes and attachments. This becomes the collaborative workspace for the exercise. Every participant sees the same procedure and works through it exactly as they would during a real event. An exercise should also test whether the team can respond fast enough. Set a **timer** on the execution as a whole to give the exercise a time limit, and set timers on individual steps to define how long each activity should take, for example fifteen minutes to isolate the affected endpoints or one hour to notify the data protection officer. The execution editor shows the elapsed time against each timer, so both participants and the exercise owner can see when a step or the whole exercise is running over. By default, timers are inherited from the timeout properties of the playbook and its steps, so a well-maintained playbook already carries the expectations the exercise is measured against. See [Timers](/key-features/executions#timers). Execution Editor Overview Only playbooks that consist entirely of manual steps, have no validation errors and are not revoked can be executed. If **Run Playbook** is greyed out, check the [eligibility criteria](/key-features/executions#eligible-playbooks). Playbooks that combine manual and automated steps are better exercised on the SOAR side; see [Deploy playbooks](/how-tos/deploy-playbooks). # 2. Test roles and responsibilities An exercise tests the team as much as the procedure. Assign each step to the person who would actually perform it during an incident: the SOC analyst for triage and containment, the incident commander for decisions and escalation, IT operations for recovery, and communications or legal for notifications. Assignees come from the source playbook. If a step in the playbook already has an assignee, the execution keeps it. Otherwise the step is assigned to the execution owner. You can change the default assignees before starting, from the **Run Playbook** dialog, or reassign any unfinished step during the exercise by clicking the assignee avatar on the step. Change Assignee Node From then on, each participant sees what they are responsible for. Their assigned steps appear as **tasks** under **Execution Tasks** and on their **Home** page, across all workspaces, while the execution owner follows progress across the whole procedure from the execution editor. Exec Tasks Insights If a step ends up with the wrong person, or nobody knows who should own it, that is a finding in itself. Record it and fix the RACI and step assignees in the playbook afterwards. See [Home & Your Tasks](/key-features/home) and [Changing step assignee](/key-features/executions#changing-step-assignee). # 3. Run the exercise As the exercise progresses, participants work through their steps and record what happened. Each step moves through a small set of statuses: Not Started, Planned, In Progress, In Review, and then one of the final states Completed, Skipped or Failed. Only the assignee can change a step's status. Status Change Panel Two things make executions useful as exercises rather than checklists: * **Evidence is captured while it happens.** Every status change is recorded with a timestamp and the identity of the operator. Participants add notes and attachments to a step, such as a screenshot of the isolation command, the ticket that was raised or the message that was sent. See [Adding notes to a step](/key-features/executions#adding-notes-to-a-step) and [Managing step attachments](/key-features/executions#managing-step-attachments). * **Deviations are recorded with a reason.** If a step cannot be performed as documented, mark it **Skipped** and enter why. If it blocks the exercise, mark it **Failed** with a reason. Both reasons are mandatory, so the gap between the procedure and reality is written down at the moment it is discovered. Skippes Status Reason Instead of reconstructing the exercise afterwards from chat logs and memory, the workbook already contains who did what, when, with what evidence and with which deviations. # 4. Measure performance Cymph times every execution and every step. While an exercise is running, the duration is shown in the top action bar of the execution editor. Once exercises complete, the **Overview** of the **Playbook Executions** page turns those timings into performance metrics: * **Average Duration**, **Slowest Execution** and **Fastest Execution** across completed executions. * **Slowest Step**, the individual step with the highest average time across all runs. * **Performance by Playbook**, ranking procedures by average run time. * **Performance by Step**, ranking individual steps so you can spot the ones that consistently take the longest, for example an approval that always waits on legal. Exec Overview By Status Compare these numbers with the timers you set. A step that regularly exceeds its target duration, or an exercise that overruns its time limit, points at a bottleneck in the procedure or in the team rather than a one-off delay. Over repeated exercises of the same playbook, the numbers show whether response performance is actually improving, not just whether people showed up. See [Executions Overview](/key-features/executions#executions-overview) for a description of every card and table. Metrics are calculated only across completed executions. If you cancel an exercise, it is excluded, so cancel rather than abandon executions that did not run properly. # 5. Capture what needs to improve Most importantly, capture what you learn. Missing information, unclear responsibilities, outdated instructions and process bottlenecks should become concrete findings tied to the procedure that was tested. Cymph has a dedicated place for this: **improvements**. An improvement is a distinct entry, separate from notes, that records something the exercise showed should change. Improvements can be captured on a specific step, for example "Escalation contact in this step is outdated" or "EDR isolation procedure unclear, analyst had to look up the console path", or on the execution as a whole, for example "Legal approval caused a 40-minute delay" or "Nobody was sure who could authorise a shutdown". Because they are tied to the step and the execution where they were observed, they do not get lost in a chat thread or a post-exercise document. Improvements sit alongside the other evidence the workbook already holds: * **Notes** on a step or on the execution, for context and observations that are not findings in themselves. * **Attachments** as evidence of what was done. * **Skip and fail reasons**, which are findings by definition. * **Timers**, which show where the procedure ran over. Add Step Note Improvements, notes and attachments can be added at any time, including after the execution has completed, so the debrief can be recorded against the same workbook. The **action log** in the top action bar preserves the complete sequence of actions taken during the execution, and platform-wide activity is available to administrators in the [audit log](/security/audit-logging). # 6. Close the learning loop The exercise does not end with a report. Turn the findings into changes to the playbook and record that the test took place: 1. **Let Cymph AI propose the improvements.** Open the [Cymph AI](/key-features/cymph-ai) assistant and ask it to improve the playbook based on the exercise. The assistant already has the context it needs: the playbook itself and the execution with its improvements, notes, skip and fail reasons and timer results. It can turn the captured improvements into concrete changes such as updated contacts, clearer instructions, missing steps or more realistic step timers. Review the proposal, refine it in the editor and save it once the team agrees. 2. **Fix ownership.** If the exercise showed that responsibilities were unclear, update the RACI matrix and the step assignees so the next execution starts with the right people. See the [governance use case](/use-cases/governance). 3. **Record the test.** Set **Last tested** in the playbook settings with the date and mode of testing, and mark the playbook as reviewed if the review covered it. See [How to change playbook settings](/howto/playbook_actions#how-to-change-playbook-settings). 4. **Check the signals.** The **Playbooks not tested the last 6 months** risk signal in the Library overview clears for this playbook, and the **Last Test Distribution** chart reflects the exercise. See [Playbook Insights](/key-features/playbook-insights). 5. **Run it again.** Schedule the next exercise and compare the performance metrics with the previous run. Every exercise makes the next response better. Test your procedures, train your team, and continuously improve your readiness.