# Agent tool execute kql Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-execute-kql /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/kql/query # Agent tool get device timeline Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-get-device-timeline /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/devices/{deviceId}/timeline # Agent tool get kql table columns Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-get-kql-table-columns /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/kql/tables/columns # Agent tool get user details Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-get-user-details /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/users/{userId} # Agent tool list directory logs Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-list-directory-logs /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/users/{userId}/directory-logs # Agent tool list kql tables Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-list-kql-tables /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/kql/tables # Agent tool list signin logs Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-list-signin-logs /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/users/{userId}/signin-logs # Agent tool related incidents Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-related-incidents /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/related-by-entity # Agent tool submit gamebook Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-submit-gamebook /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/gamebooks # Agent tool submit investigation Source: https://docs.contraforce.com/api-reference/agent-tools/agent-tool-submit-investigation /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/investigation # Check azure subscription owner Source: https://docs.contraforce.com/api-reference/azure-resources/check-azure-subscription-owner /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/is-owner # List azure nsgs Source: https://docs.contraforce.com/api-reference/azure-resources/list-azure-nsgs /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/{subscriptionId}/network-security-groups # List azure resource groups Source: https://docs.contraforce.com/api-reference/azure-resources/list-azure-resource-groups /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/{subscriptionId}/resource-groups # List azure sentinels Source: https://docs.contraforce.com/api-reference/azure-resources/list-azure-sentinels /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/sentinels # List azure subscriptions Source: https://docs.contraforce.com/api-reference/azure-resources/list-azure-subscriptions /api-reference/openapi.json get /api/v2/azure-resources/subscriptions # List azure workspaces Source: https://docs.contraforce.com/api-reference/azure-resources/list-azure-workspaces /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces # Update analytical rule Source: https://docs.contraforce.com/api-reference/azure-resources/update-analytical-rule /api-reference/openapi.json put /api/v2/azure-resources/analytical-rules/{ruleId} # Validate azure workspace Source: https://docs.contraforce.com/api-reference/azure-resources/validate-azure-workspace /api-reference/openapi.json get /api/v2/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces/{workspaceName}/validate # Get datasource workspaces across workspaces Source: https://docs.contraforce.com/api-reference/cross-workspace-data-sources/get-datasource-workspaces-across-workspaces /api-reference/openapi.json get /api/v2/datasources/across-workspaces # List datasource anomalies across workspaces Source: https://docs.contraforce.com/api-reference/cross-workspace-data-sources/list-datasource-anomalies-across-workspaces /api-reference/openapi.json post /api/v2/datasources/across-workspaces/anomalies # List gamebooks history across workspaces Source: https://docs.contraforce.com/api-reference/cross-workspace-gamebooks/list-gamebooks-history-across-workspaces /api-reference/openapi.json get /api/v2/gamebooks/across-workspaces/history # Bulk update incidents across workspaces Source: https://docs.contraforce.com/api-reference/cross-workspace-incidents/bulk-update-incidents-across-workspaces /api-reference/openapi.json post /api/v2/incidents/across-workspaces/bulk-update # List incidents across workspaces Source: https://docs.contraforce.com/api-reference/cross-workspace-incidents/list-incidents-across-workspaces /api-reference/openapi.json post /api/v2/incidents/across-workspaces # Get connected datasources Source: https://docs.contraforce.com/api-reference/data-sources/get-connected-datasources /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/datasources # REST API v2 Endpoint Reference Source: https://docs.contraforce.com/api-reference/endpoints Browse ContraForce v2 REST API endpoints by scope, with the base URL, HTTP Basic auth, cross-workspace pagination, and how to sync incident updates. The v2 API is REST + JSON over HTTPS. Every request authenticates with a [service account](/guides/general-support/service-accounts) using HTTP Basic, every response is wrapped in a standard envelope, and every error is RFC 7807 [ProblemDetails](/api-reference/errors). **Base URL** ``` https://portal.contraforce.com/api/v2 ``` **Authentication** ``` Authorization: Basic ``` **Conventions** * `Content-Type: application/json` (or `multipart/form-data` for operating procedure uploads) * Property names are camelCase; enum values are PascalCase (`Sentinel`, `High`, `TwentyFourHours`) * Workspace IDs and most other identifiers are GUIDs * Source segment values: `Sentinel`, `DefenderXDR`, `CrowdStrike`, `QRadar`, `Splunk`, `SentinelOne`, `SumoLogic`. The segment is case-insensitive, so the lowercased `source` from a [webhook event](/api-reference/webhook-events) can be used as is. Any other value returns `400 VALIDATION_ERROR` with the accepted values listed under `errors.source`. *** ## Workspace-Scoped Endpoints Path prefix: `/workspaces/{workspaceId}/...` The workspace ID is a GUID and identifies the customer environment the request operates against. The credential's service account must have a role on the target workspace, otherwise the request returns `403 INSUFFICIENT_WORKSPACE_ROLE`. **incidents:read** Every incident is the child of one SIEM source — the source is encoded as a route segment, not a query parameter. | Method | Path | Description | | - | - | - | | `GET` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}` | Get the full incident detail, including alerts, entities, investigation details, and evidence. | | `GET` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/evidence` | Get the evidence table for an incident. | | `GET` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/last-gamebook` | Get the last gamebook run for an incident, or `404` if none has run. | | `GET` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments` | List comments on an incident. | | `GET` | `/workspaces/{workspaceId}/incidents/{source}/by-entity` | Find incidents in this source related to a specific entity. | **incidents:write** | Method | Path | Description | | - | - | - | | `PUT` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/status` | Change the incident's status. Body: `status` (`New`, `Active`, `Closed`), optional `comment`, and, when closing, `classification` and `classificationReason` (see **Closing an incident** below). Set `updateTicket: true` with `ticketId` to mirror the change to a linked service ticket. Returns `204`. | | `PUT` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/assignee` | Assign the incident. Body: `userId` (the ContraForce user id) or `email`. Returns `204`. | ### Closing an incident Setting `status` to `Closed` requires a `classification` and a `classificationReason` for every detection module. The reason must belong to the chosen classification; ContraForce uses the same pairs for every source and translates them to each vendor's vocabulary (see [Incident Classification](/concepts/incident-classification)). | `classification` | Accepted `classificationReason` values | | - | - | | `TruePositive` | `MultistagedAttack`, `Malware`, `MaliciousUserActivity`, `UnwantedSoftware`, `Phishing`, `CompromisedUser`, `Apt`, `SuspiciousActivity`, `Other` | | `FalsePositive` | `NotMalicious`, `NoEnoughDataToValidate`, `InaccurateData`, `IncorrectAlertLogic`, `Other` | | `BenignPositive` | `SecurityTesting`, `ConfirmedUserActivity`, `LineOfBusinessApplication`, `SecurityPersonnel`, `SuspiciousButExpected`, `Other` | | `Undetermined` | `Unknown`, `Other` | `Other` is accepted with every classification. ```json theme={null} PUT /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/DefenderXDR/55022/status { "status": "Closed", "comment": "Closed after review; no malicious activity confirmed.", "classification": "Undetermined", "classificationReason": "Other" } ``` A reason that does not belong to the classification (for example `Undetermined` with `InaccurateData`) is rejected with `400 VALIDATION_ERROR`: ```json theme={null} "errors": { "ClassificationReason": ["Classification reason does not apply to the selected classification"] } ``` **incidents:comments** | Method | Path | Description | | - | - | - | | `POST` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments` | Add a comment. Body: `{ "content": "..." }`. Returns `201` with the created comment. | | `PUT` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId}` | Replace a comment's text. Body: `{ "content": "..." }`. Returns `204`. | | `DELETE` | `/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId}` | Delete a comment. Supported for `Sentinel` and `SentinelOne`. Returns `204`. | The source in the route decides where the comment is written. Comments on a Defender XDR incident go to Defender XDR; comments on a Sentinel incident go to Sentinel, and Microsoft syncs them to the paired Defender XDR incident where one exists. An `extensionId` property or query parameter is accepted and ignored. ```json theme={null} POST /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/DefenderXDR/55025/comments { "content": "Escalated to the on-call analyst." } ``` **gamebooks:read** | Method | Path | Description | | - | - | - | | `GET` | `/workspaces/{workspaceId}/gamebooks/rules/{incidentTitle}` | Get playbooks matching an incident title. | | `GET` | `/workspaces/{workspaceId}/gamebooks/history` | List gamebook execution history. Supports `?query=` and `?pageToken=`. | | `GET` | `/workspaces/{workspaceId}/gamebooks/history/{gamebookId}/playbooks` | Get the playbooks recorded against a specific gamebook run. | | `GET` | `/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}` | List all gamebooks that have run for an incident. `?withUserDetails=` (`true` or `false`) is required; `?source=` picks the incident's source. | **gamebooks:execute** | Method | Path | Description | | - | - | - | | `POST` | `/workspaces/{workspaceId}/gamebooks/run` | Submit a new gamebook run for an incident in the workspace. | `gamebooks:execute` does not imply `gamebooks:read`. Grant both to look up playbooks and poll the result. To run immediately, the service account needs the **Owner** or **Incident Responder** role on the route workspace; any other workspace role can only request approval with `"isQueued": true`. See [Running Gamebooks with a service account](/guides/general-support/service-accounts#running-gamebooks-with-a-service-account) for setup. **Request** ```json theme={null} POST /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/gamebooks/run { "incidentId": "", "source": "Sentinel", "incidentTitle": "Suspicious sign-in activity", "incidentNumber": 4182, "isQueued": false, "playbooks": [ { "id": "scanendpoint", "entityId": "", "entityType": "Endpoint", "sequence": 1 } ] } ``` | Field | Required | Description | | - | - | - | | `incidentId` | Yes | Incident ID. The incident must belong to the route workspace. | | `incidentTitle` | Yes | Incident title. Must not be empty. | | `source` | Yes | Incident source, such as `Sentinel` or `DefenderXDR`. | | `incidentNumber` | No | Incident display number. | | `isQueued` | No | `true` submits the run for approval. Defaults to `false`. `false` never skips an approval that a policy or partner setting requires. | | `playbooks` | Yes | One or more actions to run. | | `playbooks[].id` | Yes | A playbook ID from the [playbook catalog](#playbook-catalog) below, for example `scanendpoint`. | | `playbooks[].entityType` | Yes | The playbook's `entityType` from the [playbook catalog](#playbook-catalog). This is not the incident entity kind (use `Endpoint`, not `Host`). | | `playbooks[].entityId` | For targeted actions | The `id` of the incident entity to act on, from `investigationDetails.entities[]` in the incident detail response. See [Finding the entityId](#finding-the-entityid). General actions need no target. | | `playbooks[].sequence` | Yes | Execution order. The values across the request must be exactly `1` to `N` with no gaps or duplicates. | | `playbooks[].parameters` | No | Action-specific settings. | Validation rules: * Any field not listed above returns `400`, including Portal-only fields such as `reason`, `gamebookId`, and `isRetryGamebook`. * **Quarantine File** (`quarantinefile`) needs a `File` entity that carries its own device ID and SHA-1 hash. * **Delete Email** (`deleteemail`) needs an email entity that carries both the message ID and the mailbox's Entra object ID. A UPN alone is not enough. * **Block IP** (`blockip`) is not available to service accounts and returns `403`, even with `"isQueued": true`. **Playbook catalog** This is the full set of playbook IDs. Send the `id` and `entityType` exactly as listed. A playbook does not have to be mapped to the incident's analytic rule to run, but it still needs the matching integration on the workspace and must pass the workspace's run policies. The `kind` column is the kind of incident entity that `entityId` must point to; see [Finding the entityId](#finding-the-entityid). | `id` | Name | `entityType` | Entity `kind` to target | What it does | | - | - | - | - | - | | `acknowledgeresponse` | Acknowledge Response | `General` | None (omit `entityId`) | Adds a comment to the incident with a timestamp and the name of whoever ran it. | | `invalidateexistingsessions` | Invalidate Existing Sessions | `User` | `Account` | Ends the user's signed-in sessions. | | `lockoutuser` | Lockout User | `User` | `Account` | Disables the user's account so they cannot sign in. Undo with `unlockuser`. | | `unlockuser` | Unlock User | `User` | `Account` | Re-enables the user's account so they can sign in again. | | `resetmfa` | Reset MFA | `User` | `Account` | Deletes the user's registered MFA methods, so they must register MFA again at their next sign-in. | | `resetuserpassword` | Reset User Password | `User` | `Account` | Forces the user to reset their password at their next sign-in. | | `isolateendpoint` | Isolate Endpoint | `Endpoint` | `Host` | Disables the device's external network access. Undo with `unisolateendpoint`. | | `unisolateendpoint` | Release From Isolation | `Endpoint` | `Host` | Restores an isolated device's external network access. | | `scanendpoint` | Scan Endpoint | `Endpoint` | `Host` | Runs an antivirus scan on the device. | | `quarantinefile` | Quarantine File | `Endpoint` | `File` | Stops the file from being used and deletes it, on the device recorded on the file entity. | | `deleteemail` | Delete Email | `Email` | `MailMessage` | Deletes the email from the user's mailbox. | | `blockip` | Block IP | `Network` | `IP` | Not available to service accounts. | To list the playbooks ContraForce suggests for an incident's analytic rule, call `GET /workspaces/{workspaceId}/gamebooks/rules/{incidentTitle}` with `gamebooks:read`. **Finding the entityId** Get the incident with `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}` (`incidents:read`). Its `investigationDetails.entities[]` lists every entity on the incident. Pick the entity whose `kind` matches the playbook's row in the catalog, and send its `id` as `entityId`, exactly as returned. ```json theme={null} "investigationDetails": { "entities": [ { "id": "", "kind": "Host", "displayName": "WIN-FINANCE-07", "deviceId": "" } ] } ``` * Use the entity `id`, not `deviceId`, `userUpn`, or another identifier on the entity. * The `id` must match exactly one entity on the incident. If the run returns `400` for the target, fetch the incident again and use the current `id`. * `quarantinefile` needs a `File` entity that has a `deviceId` and a SHA-1 `fileHash`. * `deleteemail` needs a `MailMessage` entity whose `internetMessageId` and `aadUserId` are both present. **Response** ```json theme={null} { "data": { "id": "", "status": "Running", "isQueued": false } } ``` * `"status": "Running"`, `"isQueued": false`: sent for execution. Poll `GET /workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}?source={source}&withUserDetails=false` and match on `id` for the outcome. * `"status": "Pending"`, `"isQueued": true`: waiting for approval in the Portal. It has not run. **Errors** | Status | Code | Cause | | - | - | - | | `400` | `VALIDATION_ERROR` | Invalid or unsupported fields, bad `sequence` values, missing target data, a blocking run policy, or unmet integration prerequisites. | | `403` | `INSUFFICIENT_SCOPE` | The credential lacks `gamebooks:execute`. | | `403` | `INSUFFICIENT_WORKSPACE_ROLE` / `FORBIDDEN` | No role on the route workspace, a non-queued run without Owner or Incident Responder, or a Block IP action. | | `404` | `NOT_FOUND` | The workspace or incident was not found. | | `415` | `UNSUPPORTED_MEDIA_TYPE` | Missing `Content-Type: application/json`. | > [!WARNING] > > Runs are not idempotent. Retrying the same request can start a second run. After a timeout, check the incident's gamebook history before resubmitting. Approving, retrying, denying, and cancelling a gamebook remain Portal-only. **datasources:read** | Method | Path | Description | | - | - | - | | `GET` | `/workspaces/{workspaceId}/datasources` | List data sources connected to the workspace. | **tickets:read / tickets:manage** **Read** (`tickets:read`): | Method | Path | Description | | - | - | - | | `GET` | `/workspaces/{workspaceId}/tickets/search` | Search service tickets. Supports `?groupingId=` and `?ticketNumber=`. | **Manage** (`tickets:manage`): | Method | Path | Description | | - | - | - | | `POST` | `/workspaces/{workspaceId}/tickets/link` | Link a service ticket to an incident. | | `POST` | `/workspaces/{workspaceId}/tickets/unlink` | Unlink a service ticket from an incident. | | `PUT` | `/workspaces/{workspaceId}/tickets/priority` | Update ticket priority. | > [!NOTE] > > `ticketId` in a link request is the ticketing system's record id, not the ticket number: the ServiceNow `sys_id` (not `INC0049162`), the Jira issue id or key, or the numeric Autotask ticket id. If you only have the number, look it up with `GET /workspaces/{workspaceId}/tickets/search?ticketNumber=` and send the `id` of the matching ticket. An unknown id returns `400` "Unable to find the selected ticket". **investigation:read** | Method | Path | Description | | - | - | - | | `GET` | `/workspaces/{workspaceId}/investigation/users/signin-logs` | List user sign-in logs. | | `GET` | `/workspaces/{workspaceId}/investigation/users/directory-logs` | List directory audit logs. | > [!NOTE] > > Separate endpoints for the incident summary, entities, alert rules, bulk updates and the high-severity list are not on the v2 surface yet. They will be added once their handlers operate against an explicit source rather than implicitly defaulting to Sentinel. An incident's entities are already returned in `investigationDetails.entities` by `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}`. *** ## Cross-Workspace Endpoints These endpoints span every workspace your service account can see — no workspace ID in the path. The handlers filter results to the workspaces the credential has been mapped to. | Scope | Method | Path | Description | | - | - | - | - | | `incidents:read` | `POST` | `/incidents/across-workspaces` | List incidents across all visible workspaces. | | `gamebooks:read` | `GET` | `/gamebooks/across-workspaces/history` | List gamebook history across visible workspaces. Supports `?workspaces=`, `?statuses=`, `?currentPage=`, `?query=`. | | `datasources:read` | `POST` | `/datasources/across-workspaces/anomalies` | List data connector anomalies across visible workspaces. | | `datasources:read` | `GET` | `/datasources/across-workspaces` | Group connected data sources by workspace. Repeat `?workspaceIds=` for each workspace ID. | ### Paginating `/incidents/across-workspaces` The cross-workspace incidents list uses opaque continuation tokens. The first request leaves the token map empty; every subsequent request echoes the previous response's tokens back unchanged. Tokens are server-encrypted strings — treat them as a single blob the API gave you, never parse or construct one yourself. **First request:** ```json theme={null} POST /api/v2/incidents/across-workspaces { "isFirstCall": true, "workspacePageTokens": [], "sources": ["Sentinel"], "timeFilterSelection": { "type": "TwentyFourHours" } } ``` **Response (truncated):** ```json theme={null} { "data": { "incidents": [ /* ...page of incidents... */ ], "sourcePageTokens": [ { "workspaceId": "6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1", "sourceTokens": { "Sentinel": "Gd41DJgGnsDnbYHEdqbFaAKzlIbg6NVK...CQM8=" } } ], "moreIncidentsAvailable": true } } ``` **Next-page request — set `isFirstCall: false` and pass `sourcePageTokens` back verbatim as `workspacePageTokens`:** ```json theme={null} POST /api/v2/incidents/across-workspaces { "isFirstCall": false, "workspacePageTokens": [ { "workspaceId": "6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1", "sourceTokens": { "Sentinel": "Gd41DJgGnsDnbYHEdqbFaAKzlIbg6NVK...CQM8=" } } ], "sources": ["Sentinel"], "timeFilterSelection": { "type": "TwentyFourHours" } } ``` Iterate until the response returns `moreIncidentsAvailable: false`. A workspace that has finished paging drops out of `sourcePageTokens` on subsequent responses; do not synthesize entries for it. Page size is server-controlled. A token that has been modified or hand-built returns `400 VALIDATION_ERROR` with the message `One or more pagination tokens are invalid. Use the tokens from the previous response unmodified.` Recover by restarting from the first call with an empty `workspacePageTokens` array. ### Syncing incident updates with `filterByLastModified` By default `timeFilterSelection` bounds the incident's **creation** time, so a list call cannot tell you which existing incidents changed. If you mirror incidents into an external system and need to pick up updates, set `filterByLastModified: true`. The same window then bounds the incident's **last-modified** time as recorded by the vendor (Microsoft Sentinel `lastModifiedTimeUtc`, Microsoft Defender XDR `lastUpdateDateTime`), and the page is ordered by last-modified time descending. Sentinel and Defender XDR move that timestamp on every change recorded on the incident: an alert grouped in, a severity change, a status change, an owner change, a label, or a comment. Incidents created long before the window are returned as soon as they are touched. Note that the two modes are not equivalent for a bounded window: an incident created inside the window but modified after its end matches the creation-time query and not the last-modified one. In a polling loop whose windows end at the time of each call, that incident simply shows up in the next poll. **Polling pattern:** ```json theme={null} POST /api/v2/incidents/across-workspaces { "isFirstCall": true, "workspacePageTokens": [], "filterByLastModified": true, "timeFilterSelection": { "type": "Custom", "customStartUtc": "2026-09-15T15:30:00Z", "customEndUtc": "2026-09-15T15:45:00Z" } } ``` Poll on a fixed cadence, set `customStartUtc` to your previous `customEndUtc` minus a short overlap (one or two minutes), page until `moreIncidentsAvailable` is `false`, then fetch by id only the incidents whose `lastModificationTime` differs from the copy you stored. An unchanged incident returned twice because of the overlap compares equal and costs nothing. Things to know: * The filter uses the vendor's last-modified time, **not** `lastActivityTime`. `lastActivityTime` is the event time of the latest alert and is usually earlier than the incident's creation time; it does not move when an analyst edits the incident. * The response carries the incident as it is now, not the fields that changed. Keep comparing against your stored copy. * Supported for `Sentinel` and `DefenderXDR`. Leave `sources` empty to query both; naming any other source together with `filterByLastModified` returns `400 VALIDATION_ERROR` (`FilterByLastModified is supported for Sentinel, DefenderXDR only; …`). * Changes that exist only inside ContraForce and are not written to the vendor incident do not move the vendor timestamp. * In this mode each workspace's window is returned in full in one call unless it exceeds the server's page cap (several hundred incidents per workspace). If `moreIncidentsAvailable` comes back `true`, narrow the window and call again rather than paging: vendor continuations are positional, and an incident edited past the window's end between two calls can shift them. A short polling window never hits the cap. * Each page is ordered by last-modified time descending. Sources are merged per page, so if you do page, read every page before assuming you have the full window. *** ## Organization-Scoped Endpoints These endpoints operate on the organization (service provider). The credential's service account must hold the relevant org-level scope; workspace mappings are not required. **webhooks:read / webhooks:manage** **Read** (`webhooks:read`): | Method | Path | Description | | - | - | - | | `GET` | `/webhooks` | List all webhook configurations. | | `GET` | `/webhooks/{id}` | Get a webhook by ID. | | `GET` | `/webhooks/{id}/delivery-logs` | List delivery logs. Supports `?from=`, `?to=`, `?pageSize=`, `?continuationToken=`. | | `GET` | `/webhooks/{id}/delivery-logs/{logId}?createdAt=` | Get a single delivery log entry. `createdAt` is the ISO-8601 partition key and is required. | **Manage** (`webhooks:manage`): | Method | Path | Description | | - | - | - | | `POST` | `/webhooks` | Create a webhook configuration. | | `PUT` | `/webhooks/{id}` | Update a webhook configuration. | | `DELETE` | `/webhooks/{id}` | Delete a webhook configuration. | | `POST` | `/webhooks/{id}/pause` | Pause delivery. | | `POST` | `/webhooks/{id}/resume` | Resume a paused webhook. | | `POST` | `/webhooks/{id}/enable` | Re-enable a webhook auto-disabled by repeated delivery failures. | | `POST` | `/webhooks/{id}/credentials` | Update webhook authentication credentials. | | `POST` | `/webhooks/{id}/regenerate-secret` | Replace the webhook's signing secret. The response's `data.secret` is the only time the new secret is returned. The previous secret stops working immediately; authentication credentials are not changed. | | `POST` | `/webhooks/{id}/test` | Send a test event. | | `POST` | `/webhooks/{id}/delivery-logs/{logId}/redeliver?createdAt=` | Redeliver a previously failed event. | **org:service-accounts:read / manage** **Read** (`org:service-accounts:read`): | Method | Path | Description | | - | - | - | | `GET` | `/service-accounts` | List service accounts. | | `GET` | `/service-accounts/{id}` | Get a service account by ID. | **Manage** (`org:service-accounts:manage`): | Method | Path | Description | | - | - | - | | `POST` | `/service-accounts` | Create a service account. Also needs the Admin organizational role. | | `PUT` | `/service-accounts/{id}` | Update a service account. Also needs the Admin organizational role. | | `DELETE` | `/service-accounts/{id}` | Delete a service account. | | `POST` | `/service-accounts/{id}/disable` | Disable a service account. | | `POST` | `/service-accounts/{id}/enable` | Re-enable a disabled service account. Also needs the Admin organizational role. | | `POST` | `/service-accounts/{id}/credentials` | Issue a new credential. The `clientSecret` is returned once. Also needs the Admin organizational role. | | `POST` | `/service-accounts/{id}/credentials/{credentialId}/revoke` | Revoke a credential. | **org:users:read / manage / roles** **Read** (`org:users:read`): | Method | Path | Description | | - | - | - | | `GET` | `/users` | List organization users. | | `GET` | `/users/profile` | Get the calling principal's profile. | | `POST` | `/users/workspace/users` | Get users for a specific workspace. | **Manage** (`org:users:manage`): | Method | Path | Description | | - | - | - | | `POST` | `/users` | Add users to the organization. A caller without the Admin organizational role can only add new users as Member, with no workspace access. | | `PUT` | `/users` | Update a user. Needs the Admin organizational role. | | `DELETE` | `/users/{id}` | Remove a user from the organization. Removing a user above Member needs the Admin organizational role, and the organization's last Admin cannot be removed. | **Roles** (`org:users:roles`): | Method | Path | Description | | - | - | - | | `PUT` | `/users/organization/role` | Change a user's organizational role. Needs the Admin organizational role. | **org:azure:read / manage** **Read** (`org:azure:read`): | Method | Path | Description | | - | - | - | | `GET` | `/azure-resources/subscriptions` | List Azure subscriptions visible to the org's tenant. | | `GET` | `/azure-resources/subscriptions/is-owner?subscriptionId=` | Check whether the calling principal is an Owner of the subscription. | | `GET` | `/azure-resources/subscriptions/{subscriptionId}/network-security-groups` | List NSGs in a subscription. | | `GET` | `/azure-resources/subscriptions/{subscriptionId}/resource-groups` | List resource groups in a subscription. | | `GET` | `/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces` | List Log Analytics workspaces in a resource group. | | `GET` | `/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/sentinels` | List Sentinel instances in a resource group. | | `GET` | `/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces/{workspaceName}/validate` | Validate a Sentinel-attached workspace. | **Manage** (`org:azure:manage`): | Method | Path | Description | | - | - | - | | `PUT` | `/azure-resources/analytical-rules/{ruleId}?enabled=true` | Enable or disable an analytical rule. | *** ## What Comes Back Every successful response is wrapped in the standard envelope: ```json theme={null} { "data": { /* … endpoint-specific payload … */ }, "meta": { "requestId": "0HN8Q3V0001", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } } ``` List endpoints add a `pagination` block; see the [object models](/api-reference/models) page for shapes per endpoint family. Error responses are RFC 7807 ProblemDetails (`application/problem+json`) with a stable `code` extension you can switch on — the [error reference](/api-reference/errors) lists every code. # API Error Code Reference Source: https://docs.contraforce.com/api-reference/errors Look up any ContraForce v2 API error code, such as INSUFFICIENT_SCOPE or UPSTREAM_ERROR, with its HTTP status and what to do, plus the RFC 7807 shape. The v2 API surfaces every error as an [RFC 7807 ProblemDetails](https://datatracker.ietf.example/doc/html/rfc7807) document, served as `application/problem+json`. Switch on the `code` extension — it's part of the contract and won't move under your feet. The `title` and `detail` strings are human-readable and may be reworded between releases. ## Response shape ```json theme={null} { "type": "https://docs.contraforce.com/api-reference/errors", "title": "Resource not found", "status": 404, "detail": "Incident 'INC-12345' not found", "instance": "/api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/Sentinel/INC-12345", "code": "NOT_FOUND", "requestId": "0HNLBAGCRD4RN:00000003", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } ``` | Field | Source | Description | | - | - | - | | `type` | RFC 7807 | URI identifying the problem class. Points at this reference page (`https://docs.contraforce.com/api-reference/errors`); the `code` extension is the programmatic discriminator. | | `title` | RFC 7807 | Short, stable per-`code` summary. | | `status` | RFC 7807 | HTTP status code, mirrored in the response status line. | | `detail` | RFC 7807 | Per-instance message describing what went wrong. | | `instance` | RFC 7807 | URI of the failing request. | | `code` | extension | **Stable identifier you should switch on.** See the catalogue below. | | `requestId` | extension | Trace identifier for the failed request. Quote this when contacting support. | | `timestamp` | extension | UTC ISO-8601 timestamp the failure was generated at. | | `target` | extension, optional | Field or identifier the error refers to. | | `errors` | extension, optional | Field-keyed validation error map. Empty key means an object-level error. | ## Validation responses When binding fails or a [FluentValidation](https://docs.fluentvalidation.example/) rule rejects, the response includes an `errors` map: ```json theme={null} { "type": "https://docs.contraforce.com/api-reference/errors", "title": "Validation failed", "status": 400, "detail": "One or more validation errors occurred.", "instance": "/api/v2/workspaces/.../incidents/Sentinel/INC-12345/comments", "code": "VALIDATION_ERROR", "errors": { "content": ["'Content' must not be empty."], "": ["At least one of source or workspaceId must be provided."] }, "requestId": "0HNLBAGCRD4RN:00000007", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } ``` Keys are JSON property paths; the empty key carries object-level errors that aren't tied to a specific field. A route or query value that names an enum member is matched without regard to case. One that matches no member is rejected the same way, keyed by the parameter name and listing what is accepted: ```json theme={null} { "type": "https://docs.contraforce.com/api-reference/errors", "title": "Validation failed", "status": 400, "detail": "One or more validation errors occurred.", "instance": "/api/v2/workspaces/.../incidents/DefXDR/55022", "code": "VALIDATION_ERROR", "target": "source", "errors": { "source": ["'DefXDR' is not a valid value. Accepted values: Sentinel, DefenderXDR, QRadar, Splunk, CrowdStrike, SentinelOne."] }, "requestId": "0HNLBAGCRD4RN:00000009", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } ``` A JSON body the API cannot read is rejected before any handler runs. The empty key in `errors` says what was wrong: the missing required properties, the JSON path of a value with the wrong type, or the line and position of malformed JSON. ```json theme={null} { "type": "https://docs.contraforce.com/api-reference/errors", "title": "Validation failed", "status": 400, "detail": "The request body could not be read as JSON.", "instance": "/api/v2/workspaces/.../incidents/DefenderXDR/55025/comments", "code": "VALIDATION_ERROR", "errors": { "": ["Missing required properties: content."] }, "requestId": "0HNLBAGCRD4RN:0000000B", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } ``` A request with no body at all on an endpoint that needs one returns the same code with `detail` set to `A JSON request body is required.` and `target` naming the parameter. A value that cannot be read from the route or query string returns `detail` `A route or query value could not be read.` A wrong `Content-Type` returns `415 UNSUPPORTED_MEDIA_TYPE`, and a wrong verb `405 METHOD_NOT_ALLOWED`, each with this envelope. *** ## Error code catalogue **4xx — caller errors** | Code | Status | When you see it | What to do | | - | - | - | - | | `VALIDATION_ERROR` | 400 | A required field is missing, malformed, or rejected by validation. The `errors` extension carries the per-field detail. | Inspect the `errors` map. Empty keys map to object-level errors; named keys map to JSON paths. | | `BAD_REQUEST` | 400 | A 400 not classified as a validation failure (e.g. a malformed body the framework couldn't parse at all). | Inspect `detail`. Confirm the body matches the documented shape. | | `UNAUTHORIZED` | 401 | Missing or invalid `Authorization` header, revoked or rotated `clientSecret`, or a disabled service account. | Re-authenticate with valid credentials. If you rotated, update both halves of the credential. | | `FORBIDDEN` | 403 | Authenticated, but the calling principal can't perform this action on this resource. | Check that the credential carries the scope the endpoint requires and that the service account has the right workspace role. Some actions, such as changing organizational roles or creating service accounts, also need the service account's organizational role to be Admin; the `detail` then reads like "Only an organization Admin can ...". | | `INSUFFICIENT_SCOPE` | 403 | The credential is missing one of the scopes required by the endpoint. | Add the scope to the credential in the portal. Scopes follow the `{resource}:{action}` convention. | | `INSUFFICIENT_WORKSPACE_ROLE` | 403 | The calling principal has no role on the target workspace. | Have an organization admin assign a workspace role to the service account. | | `MFA_REQUIRED` | 403 | The user-flow path requires MFA from the configured IdP. | Complete the MFA challenge in the portal. Service accounts do not encounter this code. | | `USER_NOT_REGISTERED` | 403 | The authenticated user is not registered in the ContraForce user store. | An organization admin must sync or invite the user before they can call the API. | | `EXTENSION_NOT_ENABLED` | 400 | The endpoint requires an integration (e.g. Defender XDR, Jira) that hasn't been consented and enabled for this workspace. | Enable the integration via the workspace configuration endpoints or in the portal. | | `NOT_FOUND` | 404 | A workspace, incident, gamebook, or other addressed resource doesn't exist or isn't visible to the credential. | Verify the IDs in the path. For workspace-scoped routes, confirm the workspace is mapped to the service account. | | `METHOD_NOT_ALLOWED` | 405 | Wrong HTTP verb on the route. | Check the [endpoint reference](/api-reference/endpoints) for the correct verb. | | `CONFLICT` | 409 | The resource version on the server differs from yours, the same operation was already performed, or two concurrent writes collided. | Refetch the resource and retry with the latest state. | | `UNSUPPORTED_MEDIA_TYPE` | 415 | Wrong `Content-Type` header for the body shape. | Use `application/json` for JSON requests, `multipart/form-data` for operating procedure uploads. | | `RATE_LIMITED` | 429 | Too many requests in the rolling window. | Honor `Retry-After` if present, otherwise back off exponentially. | **5xx — service errors** | Code | Status | When you see it | What to do | | - | - | - | - | | `INTERNAL_ERROR` | 500 | An unhandled exception. | Retry once; if persistent, contact support and quote the `requestId`. | | `UPSTREAM_ERROR` | 502 | A downstream SIEM or EDR returned a 5xx, or our credential to the upstream is broken. Authentication failures from upstream services are also collapsed onto this code so we don't leak which side of the integration is misconfigured. | Retry after a short backoff. If persistent, contact support — only we can resolve broken upstream credentials. | | `TIMEOUT` | 504 | An upstream operation didn't finish within our timeout window, or our HTTP client to the upstream timed out. | Retry after a short backoff. For long-running queries (KQL, advanced hunting), narrow the time window. | *** ## Mapping behavior A few specific cases are worth calling out because they affect how you should design retries and surface failures to your own users. > **Upstream 4xx is translated to a caller-facing 4xx** > > When a downstream SIEM rejects a request with a 4xx (404 for an unknown ID, 400 for an unparseable filter, 409 for a conflict, 429 for rate-limit, 408/504 for timeout), the v2 API surfaces that as the matching 4xx — `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`, `RATE_LIMITED`, `TIMEOUT` — rather than collapsing onto an opaque 502. That way your retry logic can act on what's actually wrong. > > Only opaque or 5xx upstream failures stay as `UPSTREAM_ERROR`. Upstream 401/403 also stay opaque (they mean *our* credential to the upstream is broken; that's not something you can fix). > **Client-aborted requests do not produce a body** > > When the caller disconnects mid-request, the response is an empty `499` and no ProblemDetails body is written. Treat 499 as "request was cancelled before we could respond" — your client probably already knows. > **Use requestId, not traceId** > > Some development-mode payloads previously carried a `traceId` extension from ASP.NET. The v2 contract is `requestId` only. Quote the `requestId` value when contacting support — we can correlate it to backend logs without you needing to share anything else. *** ## Correlating with our logs Every `requestId` is also recorded in our backend logs. Including it in support requests dramatically shortens triage: > Hello, I'm seeing intermittent 502 `UPSTREAM_ERROR` on `POST /api/v2/incidents/across-workspaces`. Example `requestId`: `0HNLBAGCRD4RN:00000003` at `2026-04-15T20:00:00Z`. We can pull the full backend trace and pinpoint the failure without needing the request body or your credentials. # Export audit events Source: https://docs.contraforce.com/api-reference/export/export-audit-events /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/export/audit # Get playbooks by gamebook id Source: https://docs.contraforce.com/api-reference/gamebooks/get-playbooks-by-gamebook-id /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/gamebooks/history/{gamebookId}/playbooks # Get playbooks by incident title Source: https://docs.contraforce.com/api-reference/gamebooks/get-playbooks-by-incident-title /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/gamebooks/rules/{incidentTitle} # List gamebooks history Source: https://docs.contraforce.com/api-reference/gamebooks/list-gamebooks-history /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/gamebooks/history # List incident gamebooks Source: https://docs.contraforce.com/api-reference/gamebooks/list-incident-gamebooks /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId} # Run a gamebook Source: https://docs.contraforce.com/api-reference/gamebooks/run-a-gamebook /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/gamebooks/run Requires gamebooks:execute and access to the route workspace. Service accounts may submit new gamebooks only: only documented inputs are accepted; portal approval, retry, and internal state fields are rejected. Playbook sequence values must contain exactly 1..N without duplicates or gaps. Workspace policies and partner approval settings apply. A 200 response with isQueued=true and status=Pending means the plan awaits portal approval; it has not executed. Use gamebooks:read to poll history. Service accounts cannot approve, retry, deny, or cancel gamebooks. # Assign incident Source: https://docs.contraforce.com/api-reference/incidents/assign-incident /api-reference/openapi.json put /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/assignee # Create incident comment Source: https://docs.contraforce.com/api-reference/incidents/create-incident-comment /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments # Delete incident comment Source: https://docs.contraforce.com/api-reference/incidents/delete-incident-comment /api-reference/openapi.json delete /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId} # Get incident by id Source: https://docs.contraforce.com/api-reference/incidents/get-incident-by-id /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId} # Get incident comments Source: https://docs.contraforce.com/api-reference/incidents/get-incident-comments /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments # Get incident evidence Source: https://docs.contraforce.com/api-reference/incidents/get-incident-evidence /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/evidence # Get incident last gamebook Source: https://docs.contraforce.com/api-reference/incidents/get-incident-last-gamebook /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/last-gamebook # Get incidents by entity Source: https://docs.contraforce.com/api-reference/incidents/get-incidents-by-entity /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/incidents/{source}/by-entity # Ingest incident Source: https://docs.contraforce.com/api-reference/incidents/ingest-incident /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/incidents/ingest # Update incident comment Source: https://docs.contraforce.com/api-reference/incidents/update-incident-comment /api-reference/openapi.json put /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId} # Update incident status Source: https://docs.contraforce.com/api-reference/incidents/update-incident-status /api-reference/openapi.json put /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}/status # List directory logs Source: https://docs.contraforce.com/api-reference/investigation/list-directory-logs /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/investigation/users/directory-logs # List signin logs Source: https://docs.contraforce.com/api-reference/investigation/list-signin-logs /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/investigation/users/signin-logs # API Object Models and JSON Examples Source: https://docs.contraforce.com/api-reference/models Copy JSON request and response examples for the ContraForce v2 API: envelopes, incidents, comments, webhooks, delivery logs, service accounts, and users. Use these models as a reference when building integrations. Request and response bodies use `application/json` (or `multipart/form-data` for operating procedure uploads). Successful responses are wrapped in the standard envelope; error responses follow RFC 7807 ProblemDetails — see the [error reference](/api-reference/errors) for the full catalogue. *** ## Response Envelopes ### Success response ```json theme={null} { "data": { ... }, "meta": { "requestId": "0HN8Q3V0001", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } } ``` ### Paginated response ```json theme={null} { "data": [ ... ], "pagination": { "continuationToken": "eyJjb250...", "hasMore": true }, "meta": { "requestId": "0HN8Q3V0001", "timestamp": "2026-04-15T20:00:00.0000000+00:00" } } ``` ### Error response Errors are RFC 7807 ProblemDetails, served as `application/problem+json`. Switch on the stable `code` extension; the `title` and `detail` strings are human-readable and may be reworded between releases. ```json theme={null} { "type": "about:blank", "title": "Resource not found", "status": 404, "detail": "Incident 'INC-12345' not found", "instance": "/api/v2/workspaces/.../incidents/Sentinel/INC-12345", "code": "NOT_FOUND", "requestId": "0HN8Q3V0002", "timestamp": "2026-04-15T20:01:00.0000000+00:00" } ``` The full set of `code` values, validation `errors` map shape, and resolution guidance live on the [error reference](/api-reference/errors) page. *** ## Incidents ### Incident object Returned by `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}`: ```json theme={null} { "source": "Sentinel", "incident": { "id": "INC-12345", "title": "Suspicious sign-in from anonymous IP address", "severity": "High", "status": "Active", "workspaceId": "ws-abc123", "createdAt": "2026-04-15T10:30:00Z", "updatedAt": "2026-04-15T14:22:00Z" }, "investigationDetails": { "entities": [ ], "alerts": [ ] }, "evidence": { }, "gamebookCatalog": { } } ``` **Enum values:** | Field | Values | | - | - | | `source` | `Sentinel`, `DefenderXDR`, `CrowdStrike`, `QRadar`, `Splunk`, `SentinelOne`, `SumoLogic` | | `severity` | `Informational`, `Low`, `Medium`, `High` | | `status` | `New`, `Active`, `Closed` | ### Incident comment Response object from `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments`: ```json theme={null} { "id": "comment-001", "message": "Confirmed this was a legitimate admin action.", "createdTime": "2026-04-15T16:00:00Z", "authorEmail": "analyst@contoso.example", "authorName": "Jane Doe", "isActivityComment": false, "isAgentComment": false, "agentName": null, "isClosingComment": false, "ticketNoteId": null, "ticketId": null } ``` ### List incidents across workspaces Request body for `POST /incidents/across-workspaces`: ```json theme={null} { "severities": ["High", "Medium"], "statuses": ["New", "Active"], "sources": ["Sentinel", "DefenderXDR"], "timeFilterSelection": { "type": "TwentyFourHours" }, "filterByLastModified": false, "isFirstCall": true, "query": "malware", "assigneeEmails": ["analyst@contoso.example"], "includeUnassigned": true } ``` **Time filter enum values for `type`:** `ThreeHours`, `SixHours`, `TwelveHours`, `TwentyFourHours`, `FortyEightHours`, `Custom`. Any other value is rejected. **`filterByLastModified`** (boolean, default `false`): when `true`, `timeFilterSelection` bounds the incident's vendor last-modified time instead of its creation time and the page is ordered by last-modified time descending. Supported for `Sentinel` and `DefenderXDR` only; an empty `sources` list selects those two. See [Syncing incident updates](/api-reference/endpoints#syncing-incident-updates-with-filterbylastmodified). When using `Custom`, include `customStartUtc` and `customEndUtc`: ```json theme={null} { "timeFilterSelection": { "type": "Custom", "customStartUtc": "2026-04-01T00:00:00Z", "customEndUtc": "2026-04-15T23:59:59Z" } } ``` *** ## Webhooks For the full list of event types, their payload schemas, and delivery behavior, see the [Webhook Event Reference](/api-reference/webhook-events). ### Webhook configuration Response object from `GET /webhooks/{id}`: ```json theme={null} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "serviceProviderId": "00000000-0000-0000-0000-000000000001", "targetAccountId": "00000000-0000-0000-0000-000000000001", "targetAccountName": "Contoso MSP", "workspaceId": null, "name": "SIEM-ingest-prod", "url": "https://siem.contoso.example/api/webhook", "status": "Active", "eventTypes": ["incident.created.v1", "incident.closed.v1"], "monitoredAccountIds": [ "11111111-1111-1111-1111-111111111111", "22222222-2222-2222-2222-222222222222" ], "authenticationType": "Bearer", "hasSigningToken": true, "disableReason": null, "disabledAt": null, "createdAt": "2026-03-01T12:00:00Z", "lastModifiedAt": "2026-04-10T09:30:00Z" } ``` ### Create webhook Request body for `POST /webhooks`: ```json theme={null} { "name": "SIEM-ingest-prod", "url": "https://siem.contoso.example/api/webhook", "eventTypes": ["incident.created.v1", "incident.closed.v1"], "monitoredAccountIds": [ "11111111-1111-1111-1111-111111111111" ], "authenticationType": "Bearer", "token": "your-bearer-token", "signingToken": "your-hmac-signing-secret" } ``` **Enum values for `authenticationType`:** `None`, `Bearer`, `Basic`, `ApiKey` ### Delivery log Response object from `GET /webhooks/{id}/delivery-logs/{logId}?createdAt=`. The list endpoint returns the same object per entry, always with `eventPayload` set to `null`. ```json theme={null} { "id": "5f1c2c1e-6b0f-4a1a-9c3d-2e8b7a6d5c40", "webhookConfigurationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "eventId": "9d2f0a7b-3c4e-4f5a-8b6c-1d2e3f4a5b6c", "eventType": "incident.created.v1", "status": "Failed", "httpStatusCode": 503, "errorMessage": "HTTP 503 Service Unavailable", "latencyMs": 812, "attemptNumber": 3, "originalDeliveryId": "0c9e8d7f-6a5b-4c3d-2e1f-0a9b8c7d6e5f", "isTest": false, "eventSourceAccountId": "11111111-1111-1111-1111-111111111111", "eventSourceAccountName": "Contoso Retail", "eventSubjectId": "6f2a9c1d-0b3e-4a5f-8c7d-1e2f3a4b5c6d", "eventSubjectDisplayName": "Incident #1042", "eventSubjectAttributes": { "source": "Sentinel", "severity": "High", "status": "Active", "number": "1042" }, "eventPayload": "{\"type\":\"incident.created.v1\", ... }", "responseSnippet": null, "eventOccurredAt": "2026-08-03T14:21:55Z", "completedAt": "2026-08-03T14:22:09Z", "redeliveryRequestedAt": null, "createdAt": "2026-08-03T14:22:08Z" } ``` **Enum values for `status`:** `Pending`, `Succeeded`, `Failed` | Field | Notes | | - | - | | `eventPayload` | Not stored. The single-entry endpoint rebuilds it from the incident's **current** state for `incident.created.v1`; it is `null` for other event types and when the incident is no longer available. | | `responseSnippet` | Not stored. Always `null` for entries written after 2026-08-27. | | `eventSubjectDisplayName` | The label `Incident #`, or `null` when the source has no incident number. The incident title is not stored. | | `originalDeliveryId` | Set on retries and redeliveries; points at the first attempt for the event. | | `redeliveryRequestedAt` | Set once a redelivery has been requested for the entry; a second request returns `409`. | See [Delivery logs](/api-reference/webhook-events#delivery-logs) for what is retained and how redelivery works. *** ## Service Accounts ### Service account Response object from `GET /service-accounts/{id}`: ```json theme={null} { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "accountId": "00000000-0000-0000-0000-000000000001", "name": "Jira-incident-sync-prod", "description": "Syncs incidents to Jira Service Management", "isActive": true, "organizationalRole": "Member", "clientSecretPrefix": "cf_sa_", "credentialExpirationDate": "2027-04-15T00:00:00Z", "workspaceAssignments": [ { "workspaceId": "ws-abc123", "workspaceName": "Contoso Prod", "role": "IncidentAnalyst" } ], "credentials": [ { "id": "cred-001", "scopes": ["incidents:read", "incidents:write"], "status": "Active", "expiresAt": "2027-04-15T00:00:00Z", "lastUsedAt": "2026-04-15T19:00:00Z", "createdAt": "2026-04-01T12:00:00Z" } ], "lastUsedAt": "2026-04-15T19:00:00Z", "createdAt": "2026-04-01T12:00:00Z", "lastModifiedAt": "2026-04-10T09:30:00Z" } ``` ### Create service account Request body for `POST /service-accounts`: ```json theme={null} { "name": "Jira-incident-sync-prod", "description": "Syncs incidents to Jira Service Management", "organizationalRole": "Member", "workspaceAssignments": [ { "workspaceId": "ws-abc123", "role": "IncidentAnalyst" } ], "scopes": ["incidents:read", "incidents:write"], "expirationDate": "2027-04-15T00:00:00Z" } ``` ### Credential created (shown once) Response from `POST /service-accounts/{id}/credentials`: ```json theme={null} { "clientId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "clientSecret": "cf_sa_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678==", "id": "cred-002", "scopes": ["incidents:read"], "status": "Active", "expiresAt": "2027-04-15T00:00:00Z", "lastUsedAt": null, "createdAt": "2026-04-15T20:00:00Z" } ``` > [!WARNING] > > The `clientSecret` is returned **only once** in this response. Store it immediately in a secrets manager. *** ## Users ### User object Each item returned by `GET /users`: ```json theme={null} { "id": "61eec97d-57b2-5b00-686e-8544a1b2c3d4", "displayName": "Jane Doe", "email": "jane.doe@contoso.example", "organizationalRole": "Member", "isActive": true } ``` # Create service account Source: https://docs.contraforce.com/api-reference/service-accounts/create-service-account /api-reference/openapi.json post /api/v2/service-accounts # Create service account credential Source: https://docs.contraforce.com/api-reference/service-accounts/create-service-account-credential /api-reference/openapi.json post /api/v2/service-accounts/{id}/credentials # Delete service account Source: https://docs.contraforce.com/api-reference/service-accounts/delete-service-account /api-reference/openapi.json delete /api/v2/service-accounts/{id} # Disable service account Source: https://docs.contraforce.com/api-reference/service-accounts/disable-service-account /api-reference/openapi.json post /api/v2/service-accounts/{id}/disable # Enable service account Source: https://docs.contraforce.com/api-reference/service-accounts/enable-service-account /api-reference/openapi.json post /api/v2/service-accounts/{id}/enable # Get service account Source: https://docs.contraforce.com/api-reference/service-accounts/get-service-account /api-reference/openapi.json get /api/v2/service-accounts/{id} # List service accounts Source: https://docs.contraforce.com/api-reference/service-accounts/list-service-accounts /api-reference/openapi.json get /api/v2/service-accounts # Provision sentinel ingest credential Source: https://docs.contraforce.com/api-reference/service-accounts/provision-sentinel-ingest-credential /api-reference/openapi.json post /api/v2/service-accounts/sentinel-ingest/deployment-card # Revoke service account credential Source: https://docs.contraforce.com/api-reference/service-accounts/revoke-service-account-credential /api-reference/openapi.json post /api/v2/service-accounts/{id}/credentials/{credentialId}/revoke # Update service account Source: https://docs.contraforce.com/api-reference/service-accounts/update-service-account /api-reference/openapi.json put /api/v2/service-accounts/{id} # Link ticket Source: https://docs.contraforce.com/api-reference/service-tickets/link-ticket /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/tickets/link Links an existing ticket in the workspace's connected ticketing system to an incident. `ticketId` must be the ticketing system's record id, not the ticket number people see: | Ticketing system | Send | Not | | --- | --- | --- | | ServiceNow | The incident `sys_id` (32 hex characters) | The incident number, such as `INC0049162` | | Jira Service Management | The issue id or the issue key, such as `SUP-123` | | | Autotask | The numeric ticket id | The ticket number, such as `T20261007.0001` | If you only have the ticket number, call `GET /api/v2/workspaces/{workspaceId}/tickets/search?ticketNumber=` first and send the `id` of the matching ticket (`serviceNowTicket.id`, `jiraTicket.id` or `autotaskTicket.id`). When the ticketing system cannot find a ticket with the given id, the request returns `400` with "Unable to find the selected ticket". # Search tickets Source: https://docs.contraforce.com/api-reference/service-tickets/search-tickets /api-reference/openapi.json get /api/v2/workspaces/{workspaceId}/tickets/search # Unlink ticket Source: https://docs.contraforce.com/api-reference/service-tickets/unlink-ticket /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/tickets/unlink # Update ticket priority Source: https://docs.contraforce.com/api-reference/service-tickets/update-ticket-priority /api-reference/openapi.json put /api/v2/workspaces/{workspaceId}/tickets/priority # Add user Source: https://docs.contraforce.com/api-reference/users/add-user /api-reference/openapi.json post /api/v2/users # Add workspace users Source: https://docs.contraforce.com/api-reference/users/add-workspace-users /api-reference/openapi.json post /api/v2/users/workspace # Get user profile Source: https://docs.contraforce.com/api-reference/users/get-user-profile /api-reference/openapi.json get /api/v2/users/profile # Get workspace users Source: https://docs.contraforce.com/api-reference/users/get-workspace-users /api-reference/openapi.json post /api/v2/users/workspace/users # List users Source: https://docs.contraforce.com/api-reference/users/list-users /api-reference/openapi.json get /api/v2/users # Remove user Source: https://docs.contraforce.com/api-reference/users/remove-user /api-reference/openapi.json delete /api/v2/users/{id} # Update org role Source: https://docs.contraforce.com/api-reference/users/update-org-role /api-reference/openapi.json put /api/v2/users/organization/role # Update user Source: https://docs.contraforce.com/api-reference/users/update-user /api-reference/openapi.json put /api/v2/users # Webhook Event Reference Source: https://docs.contraforce.com/api-reference/webhook-events Look up every webhook event ContraForce sends, such as incident.created.v1, with payload schemas, HMAC-SHA256 signature verification, and retry rules. ContraForce delivers events to your endpoint over HTTPS as signed JSON. This page lists every event type the platform can send, the exact body shape for each, and the delivery rules that apply to all of them. Webhooks are managed under **Settings → Developers** in the portal (see [Setting Up Webhooks](/guides/technical/configure-webhooks)), or through the [`/webhooks` endpoints](/api-reference/endpoints) with the `webhooks:read` and `webhooks:manage` scopes. The portal shows the same sample deliveries as this page: use the info button next to an event when creating or editing a webhook to view and copy its sample payload. *** ## Event Types | Event type | Display name | Routing | Fires when | | - | - | - | - | | `webhook.test.v1` | Webhook Test | Manual | You use **Send test** on a webhook to verify connectivity. | | `incident.created.v1` | Incident Created | Subscription | A new incident is ingested into a monitored workspace. Also used by the manual **Trigger webhook** action on an incident. | | `incident.closed.v1` | Incident Closed | Subscription | An incident reaches Closed, including closures performed in the vendor's own portal. A close also fires `incident.status.changed.v1`. | | `incident.status.changed.v1` | Incident Status Changed | Subscription | An incident moves to any status, including pauses, reopens and **closes**. Carries the previous and new status and the current owner. | | `incident.assignee.changed.v1` | Incident Assignee Changed | Subscription | An incident is assigned, reassigned or unassigned, by an analyst, a bulk update, or the AI agent. | | `incident.comment.added.v1` | Incident Comment Added | Subscription | An analyst, the AI agent, or a Gamebook adds a comment to an incident. Carries the full comment. | | `gamebook.run.v1` | Gamebook Run | Subscription | A Gamebook is dispatched against an incident, by an analyst or by the AI agent. | | `agent.investigation.completed.v1` | Agent Investigation Completed | Externally configured | A Security Delivery Agent finishes an investigation and reaches a verdict whose classification card points at a webhook. | ### Routing models > **Subscription routing** > > The webhook lists the event type in its `eventTypes` array. Every active webhook in scope receives the event. > > Scope resolution covers the incident's own account plus any managing service provider accounts. A service provider webhook with a non-empty `monitoredAccountIds` list only receives events from the accounts it lists; an empty list means all managed accounts. > **Externally configured routing** > > Subscribing alone does not opt a webhook in. An owning entity has to name the webhook explicitly. Today this applies only to `agent.investigation.completed.v1`, where an Agent Configuration's classification card selects the target webhook. > > The webhook must *also* keep `agent.investigation.completed.v1` in its `eventTypes`. If it is unsubscribed while still bound to a classification card, the delivery is recorded as **Failed** in the delivery log rather than dropped silently. > **Manual routing** > > `webhook.test.v1` is only produced by the **Send test** action against one specific webhook. It is not a subscribable event. > > The incident **Trigger webhook** action is also manual, but it reuses `incident.created.v1` so that existing receivers process it without code changes. Subscription matching is bypassed for that fire, though `monitoredAccountIds` is still enforced. *** ## The Delivery Envelope Every event, regardless of type, is delivered as the same outer envelope. The event-specific schema lives under `data`. ```json theme={null} { "type": "incident.created.v1", "timestamp": "2026-08-03T14:22:07.881Z", "isTest": false, "occurredAt": "2026-08-03T14:21:55.000Z", "data": { } } ``` | Field | Type | Description | | - | - | - | | `type` | string | The event type. Matches the `X-CF-Schema` header. | | `timestamp` | string | ISO 8601 time the delivery attempt was built. | | `isTest` | boolean | `true` for test deliveries only. | | `occurredAt` | string | ISO 8601 time the underlying event happened, which can be earlier than `timestamp`. | | `data` | object | The event payload. Shape depends on `type`. | > [!WARNING] > > Verify the signature over the full raw body, envelope included. Do not sign or hash only the `data` object. All payload property names are camelCase. *** ## Request Headers | Header | Value | Notes | | - | - | - | | `Content-Type` | `application/json` | Body is UTF-8 encoded JSON. | | `X-CF-Schema` | The event type | Branch on this. Default-ignore types you do not recognize. | | `X-CF-Event-Id` | GUID | Stable per logical event. Use it to deduplicate. | | `X-CF-Timestamp` | ISO 8601 timestamp | Reject if more than 5 minutes from your clock. | | `X-CF-Signature` | Base64 HMAC-SHA256 | See below. | | `X-CF-Test` | `true` or `false` | `true` only for test deliveries. | | `Authorization` | `Bearer ` or `Basic ` | Present only if you configured authentication on the webhook. | *** ## Verifying the Signature The signature covers the timestamp and the exact raw request body: ``` signature = Base64( HMAC_SHA256( signing_key, X-CF-Timestamp + "." + raw_body ) ) ``` The `signing_key` is the secret shown once when the webhook was created, unless you supplied your own signing token override when setting bearer-token credentials, in which case it is that token. If you lose the secret, regenerate it in the Portal or with [`POST /webhooks/{id}/regenerate-secret`](/api-reference/endpoints#organization-scoped-endpoints) and update your endpoint. ```python verify.py theme={null} import base64, hashlib, hmac, time from datetime import datetime, timezone def verify(signing_key: str, headers: dict, raw_body: bytes) -> bool: ts = headers["X-CF-Timestamp"] sent = headers["X-CF-Signature"] signed = ts.encode() + b"." + raw_body expected = base64.b64encode( hmac.new(signing_key.encode(), signed, hashlib.sha256).digest() ).decode() if not hmac.compare_digest(expected, sent): return False age = abs(time.time() - datetime.fromisoformat(ts).replace(tzinfo=timezone.utc).timestamp()) return age <= 300 ``` ```csharp Verify.cs theme={null} static bool Verify(string signingKey, string timestamp, string sentSignature, byte[] rawBody) { var signed = System.Text.Encoding.UTF8.GetBytes(timestamp + ".") .Concat(rawBody).ToArray(); using var hmac = new System.Security.Cryptography.HMACSHA256( System.Text.Encoding.UTF8.GetBytes(signingKey)); var expected = Convert.ToBase64String(hmac.ComputeHash(signed)); var match = System.Security.Cryptography.CryptographicOperations.FixedTimeEquals( System.Text.Encoding.UTF8.GetBytes(expected), System.Text.Encoding.UTF8.GetBytes(sentSignature)); var age = Math.Abs((DateTimeOffset.UtcNow - DateTimeOffset.Parse(timestamp)).TotalSeconds); return match && age <= 300; } ``` *** ## `webhook.test.v1` A synthetic connectivity check, sent only by the **Send test** action on a single webhook. It carries `X-CF-Test: true` and `isTest: true`, and is signed exactly like a live event, so you can validate your verification code end to end before any real traffic arrives. The payload mirrors the `incident.created.v1` shape with fixed sample values. Both vendor blocks are populated in the test event so you can build against the full shape; a real incident carries whichever blocks apply to it. ```json theme={null} { "type": "webhook.test.v1", "timestamp": "2026-08-03T14:22:07.881Z", "isTest": true, "occurredAt": "2026-08-03T14:22:07.881Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "test-00000000-0000-0000-0000-000000000000", "incidentNumber": 0, "title": "Test Incident — Webhook Connectivity Verification", "description": "This is a test event generated by ContraForce to verify your webhook endpoint is configured correctly and receiving events.", "severity": "Informational", "source": "contraforce", "sourceDisplayName": "ContraForce", "createdAt": "2026-08-03T14:22:07.881Z", "lastActivityAt": "2026-08-03T14:22:07.881Z", "alertProductNames": ["ContraForce EventCast"], "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-resource-group/providers/Microsoft.OperationalInsights/workspaces/test-workspace/providers/Microsoft.SecurityInsights/incidents/00000000-0000-0000-0000-000000000000", "incidentId": "00000000-0000-0000-0000-000000000000", "subscriptionId": "00000000-0000-0000-0000-000000000000", "resourceGroupName": "test-resource-group", "workspaceName": "test-workspace", "incidentNumber": 0, "portalUrl": "https://portal.azure.com/#example-test-incident" }, "defender": { "incidentId": "0", "tenantId": "00000000-0000-0000-0000-000000000000", "portalUrl": "https://security.microsoft.com/incidents/0" } }, "alerts": [ { "title": "Webhook Test Alert", "severity": "Informational", "productName": "ContraForce EventCast", "vendorName": "ContraForce" } ], "owner": { "displayName": "ContraForce Test User", "email": "test-user@example.com" }, "entities": [ { "type": "account", "displayName": "test-account@example.com" }, { "type": "host", "displayName": "DESKTOP-TEST001" }, { "type": "ip", "displayName": "192.0.2.1" } ] } } ``` > [!NOTE] > > Test deliveries are excluded from the auto-disable circuit breaker, so a failing test never takes a live webhook offline. *** ## `incident.created.v1` Fires when a new incident is ingested into a workspace the webhook monitors. The same event type is emitted by the incident **Trigger webhook** action so that receivers do not need a separate code path for a manually replayed incident. ```json theme={null} { "type": "incident.created.v1", "timestamp": "2026-08-03T14:22:07.881Z", "isTest": false, "occurredAt": "2026-08-03T14:21:55.000Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Suspicious sign-in from impossible travel", "description": "Multiple sign-ins from geographically distant locations within a short window.", "severity": "High", "source": "sentinel", "sourceDisplayName": "Microsoft Sentinel", "owner": { "displayName": "Jane Doe", "email": "jdoe@contoso.example" }, "createdAt": "2026-08-03T14:21:55.000Z", "lastActivityAt": "2026-08-03T14:21:58.000Z", "occurredAt": "2026-08-03T14:21:55.000Z", "alertProductNames": ["Microsoft Entra ID Protection"], "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/#blade/Microsoft_Azure_Security_Insights/IncidentBlade" }, "defender": { "incidentId": "9915", "tenantId": "33333333-3333-3333-3333-333333333333", "portalUrl": "https://security.microsoft.com/incidents/9915" } }, "alerts": [ { "title": "Impossible travel activity", "severity": "High", "productName": "Microsoft Entra ID Protection", "vendorName": "Microsoft" } ], "entities": [ { "type": "Account", "displayName": "jdoe@contoso.example" }, { "type": "IP", "displayName": "198.51.100.24" } ] } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string | Incident title. | | `description` | string | Incident description, empty string when the source provides none. | | `severity` | string | `Informational`, `Low`, `Medium`, `High`, or `Critical`. | | `source` | string | Detection source, **lowercased** for this event, for example `sentinel`, `defenderxdr`, `crowdstrike`. | | `sourceDisplayName` | string | Human-readable source name. | | `owner` | object \| null | Assigned owner at creation, omitted when unassigned. The same person is called `assignee` on every later incident event; this name predates them and is kept for compatibility. | | `createdAt` | string | ISO 8601 creation time. | | `lastActivityAt` | string \| null | ISO 8601 time of the most recent activity. | | `occurredAt` | string | Duplicate of `createdAt`, retained for receivers that read it from `data`. | | `alertProductNames` | string\[] | Distinct product names across the incident's alerts. | | `vendorIdentifiers` | object | Vendor identifiers for this incident. See [Vendor identifiers](#vendor-identifiers). Absent when none could be resolved. | | `alerts[]` | array | Each with `title`, `severity`, `productName`, `vendorName`. | | `entities[]` | array | Each with `type` and `displayName`. `Ip` and `Url` are normalized to `IP` and `URL`. | > [!NOTE] > > Null fields are omitted from this payload rather than serialized as `null`. Treat a missing `owner` or `lastActivityAt` as absent. *** ## Vendor identifiers `incident.created.v1` carries an `vendorIdentifiers` object holding the identifiers of every vendor system known to hold a record of the incident. It exists because `incidentId` alone is not always enough to act: addressing a Microsoft Sentinel incident over ARM needs the full resource id, and one real-world incident can exist in both Defender XDR and Sentinel under different ids. The same object rides on `incident.created.v1`, `incident.closed.v1`, `incident.status.changed.v1`, `incident.assignee.changed.v1` and `incident.comment.added.v1`, and is exposed on the incident representation in the [REST API](/api-reference/endpoints), so a receiver resolves an incident the same way whichever surface it came from. ```json theme={null} "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/incidents/{incidentId}", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/..." }, "defender": { "incidentId": "9915", "tenantId": "33333333-3333-3333-3333-333333333333", "portalUrl": "https://security.microsoft.com/incidents/9915" } } ``` | Field | Type | Description | | - | - | - | | `sentinel.armId` | string | Full ARM resource id. This is what Azure automation, Logic Apps, and the Sentinel REST API address the incident by. | | `sentinel.incidentId` | string | The Sentinel incident GUID, the last segment of `armId`. | | `sentinel.subscriptionId` | string | Subscription holding the Log Analytics workspace. | | `sentinel.resourceGroupName` | string | Resource group holding the Log Analytics workspace. | | `sentinel.workspaceName` | string | Log Analytics workspace name. Not the ContraForce workspace name. | | `sentinel.incidentNumber` | number | Incident number within the Sentinel workspace. | | `sentinel.portalUrl` | string | Link to the incident in the Microsoft Sentinel portal. | | `defender.incidentId` | string | The Defender XDR incident id. | | `defender.tenantId` | string | Entra tenant the Defender incident belongs to. | | `defender.portalUrl` | string | Link to the incident in the Microsoft Defender portal. | ### Which blocks are present Every block and every field inside it is conditional. Treat an absent block as "not resolvable for this incident", not as an error. | Incident source | `sentinel` | `defender` | | - | - | - | | Sentinel, generated by a Sentinel analytics rule | Yes | No. The incident exists only in Sentinel. | | Sentinel, forwarded in from Defender XDR | Yes | Yes, read from Sentinel's own `providerIncidentId`. | | Defender XDR, workspace also running Sentinel | Usually, once the Sentinel counterpart exists | Yes | | Defender XDR, workspace with no Sentinel module | No | Yes | | CrowdStrike, SentinelOne, and other sources | No | No. The `vendorIdentifiers` object is omitted entirely. | > [!WARNING] > > For a Defender XDR incident, the `sentinel` block depends on Microsoft having already created the Sentinel counterpart. Immediately after an incident is created that copy may not exist yet, so the block can be absent on `incident.created.v1` and present when the same incident is later read over the REST API. Branch on the field you need being present rather than assuming it always will be. > [!NOTE] > > This object is additive. Existing fields, including the top-level `incidentId`, are unchanged and continue to carry the identifier of the source the incident was ingested from. *** ## `incident.closed.v1` Fires when an incident reaches Closed, whichever route got it there: the portal, a bulk close, the AI agent, or the public API. Closures performed directly in the vendor's own console are also picked up by reconciliation and delivered here, distinguished by `closedBy.origin`. > [!WARNING] > > A close also fires [`incident.status.changed.v1`](#incident-status-changed-v1) for webhooks subscribed to it. The two are separate deliveries with different event IDs. Handle closes from one of them: this event when you need the verdict and closing comment, the status event when you mirror every status. ```json theme={null} { "type": "incident.closed.v1", "timestamp": "2026-08-03T16:04:12.117Z", "isTest": false, "occurredAt": "2026-08-03T16:04:12.117Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Suspicious sign-in from impossible travel", "severity": "High", "source": "Sentinel", "sourceDisplayName": "Microsoft Sentinel", "classification": "TruePositive", "classificationReason": "SuspiciousActivity", "comment": "Confirmed credential theft. User reset and sessions revoked.", "assignee": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "displayName": "Jane Doe", "email": "jdoe@contoso.example", "isAgent": null }, "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/..." } }, "closedAt": "2026-08-03T16:04:12.117Z", "closedBy": { "displayName": "Jane Doe", "origin": "analyst" } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string | Incident title. | | `severity` | string | Incident severity at close. | | `source` | string | Detection source in PascalCase for this event, for example `Sentinel`. | | `sourceDisplayName` | string | Human-readable source name. | | `classification` | string \| null | Canonical ContraForce classification: `TruePositive`, `FalsePositive`, `BenignPositive`, or `Undetermined`. | | `classificationReason` | string \| null | Canonical reason name, when one was recorded. | | `comment` | string \| null | Free-text closing comment, when one was provided. | | `assignee` | object \| null | Who was working the incident when it closed, with `id`, `displayName`, `email` and `isAgent`. `null` when unassigned. `isAgent` is always `null` here: the owner comes from the vendor record, which does not say whether it is an agent. Distinct from `closedBy`, which is who performed the close. | | `vendorIdentifiers` | object \| null | Vendor identifiers for this incident. See [Vendor identifiers](#vendor-identifiers). Unlike `incident.created.v1`, this event serializes nulls, so the key is present and `null` when nothing resolved. | | `closedAt` | string | ISO 8601 close time. | | `closedBy.displayName` | string | Closing analyst, or the upstream source label for vendor-portal closures. | | `closedBy.origin` | string | `analyst` for closures through ContraForce, `upstream` for closures detected in the vendor's portal. | > [!TIP] > > Branch on `classification`, not on vendor strings. ContraForce normalizes every source's closure vocabulary into the four canonical values, so your integration does not have to track vendor enum changes. See [Incident classification](/concepts/incident-classification). *** ## `incident.status.changed.v1` Fires on every status transition an incident goes through in ContraForce: the portal, a bulk update, the AI agent, or the public API. Closures picked up from the vendor's own console by reconciliation are delivered too, with `changedBy.origin` set to `upstream`. > [!WARNING] > > **This event fires on close as well.** A close produces both this event (with `status: "Closed"`) and [`incident.closed.v1`](#incident-closed-v1), as two separate deliveries with different event IDs. Subscribe to this event to mirror every status into another system, and to `incident.closed.v1` when you only care about the verdict and the closing comment. Subscribing to both means handling each close twice. ```json theme={null} { "type": "incident.status.changed.v1", "timestamp": "2026-08-03T15:40:21.004Z", "isTest": false, "occurredAt": "2026-08-03T15:40:21.004Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Suspicious sign-in from impossible travel", "severity": "High", "source": "Sentinel", "sourceDisplayName": "Microsoft Sentinel", "previousStatus": "Active", "status": "WaitingOnCustomer", "classification": null, "classificationReason": null, "assignee": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "displayName": "Jane Doe", "email": "jdoe@contoso.example", "isAgent": null }, "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/..." } }, "changedAt": "2026-08-03T15:40:21.004Z", "changedBy": { "displayName": "Jane Doe", "origin": "analyst" } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string | Incident title. | | `severity` | string | Incident severity at the time of the change. | | `source` | string | Detection source in PascalCase for this event, for example `Sentinel`. | | `sourceDisplayName` | string | Human-readable source name. | | `previousStatus` | string \| null | Status before the transition. `null` for closures detected in the vendor's console, where ContraForce does not know the prior status. | | `status` | string | Status after the transition: `New`, `Active`, `Closed`, `OnHold`, or `WaitingOnCustomer`. | | `classification` | string \| null | Canonical ContraForce classification, present only when `status` is `Closed`. | | `classificationReason` | string \| null | Canonical reason name, present only on a close that recorded one. | | `assignee` | object \| null | The incident's owner when the change happened, with `id`, `displayName`, `email` and `isAgent`. `null` when unassigned. `isAgent` is always `null` here: the owner comes from the vendor record, which does not say whether it is an agent. | | `vendorIdentifiers` | object \| null | Vendor identifiers for this incident. See [Vendor identifiers](#vendor-identifiers). The key is present and `null` when nothing resolved. | | `changedAt` | string | ISO 8601 time of the change. For upstream closures, the vendor's own modification time. | | `changedBy.displayName` | string | The acting analyst or agent, or the upstream source label for vendor-console changes. | | `changedBy.origin` | string | `analyst` for changes through ContraForce, `upstream` for changes detected in the vendor's portal. | > [!NOTE] > > `OnHold` and `WaitingOnCustomer` are ContraForce statuses. They pause the SLA clocks and never propagate to the vendor, so a receiver mirroring status into a PSA should map them to its own waiting states rather than expect to find them in Sentinel or Defender. *** ## `incident.assignee.changed.v1` Fires when an incident is assigned, reassigned or unassigned through ContraForce, whether by an analyst, a bulk update, or a Security Delivery Agent assigning itself. Ownership changes made directly in the vendor's console are not detected. ```json theme={null} { "type": "incident.assignee.changed.v1", "timestamp": "2026-08-03T14:25:03.512Z", "isTest": false, "occurredAt": "2026-08-03T14:25:03.512Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Suspicious sign-in from impossible travel", "severity": "High", "source": "Sentinel", "sourceDisplayName": "Microsoft Sentinel", "previousAssignee": null, "assignee": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "displayName": "Jane Doe", "email": "jdoe@contoso.example", "isAgent": false }, "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/..." } }, "changedAt": "2026-08-03T14:25:03.512Z", "changedBy": { "displayName": "Jane Doe", "origin": "analyst" } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string | Incident title. | | `severity` | string | Incident severity at the time of the change. | | `source` | string | Detection source in PascalCase for this event, for example `Sentinel`. | | `sourceDisplayName` | string | Human-readable source name. | | `previousAssignee` | object \| null | The owner before the change. `null` when the incident was unassigned. | | `assignee` | object \| null | The owner after the change. `null` when the incident was unassigned. | | `*.id` | string | ContraForce user or agent id. Can be empty on `previousAssignee` when the vendor record carries only a name or email. | | `*.displayName` | string | Owner display name. | | `*.email` | string \| null | Owner email, when known. | | `*.isAgent` | boolean \| null | `true` for a Security Delivery Agent, `false` for a portal user. `null` on `previousAssignee`, which comes from the vendor record and does not say which it was. | | `vendorIdentifiers` | object \| null | Vendor identifiers for this incident. See [Vendor identifiers](#vendor-identifiers). The key is present and `null` when nothing resolved. | | `changedAt` | string | ISO 8601 time of the change. | | `changedBy.displayName` | string | The analyst or agent that made the change. | | `changedBy.origin` | string | Always `analyst` today; reserved for changes detected in the vendor's portal. | > [!TIP] > > A `previousAssignee` of `null` with an `assignee` is a first assignment, and an `assignee` of `null` is an unassignment. Use `assignee.isAgent` to skip the agent's own self-assignment when your ticketing sync should only follow human owners. *** ## `incident.comment.added.v1` Fires when a comment is added to an incident through ContraForce by an analyst, a Security Delivery Agent, or a Gamebook. Comments written directly in the vendor's console are not detected, and the closing comment entered on a close travels on `incident.closed.v1` rather than here. ```json theme={null} { "type": "incident.comment.added.v1", "timestamp": "2026-08-03T14:31:40.220Z", "isTest": false, "occurredAt": "2026-08-03T14:31:39.870Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Suspicious sign-in from impossible travel", "severity": "High", "source": "Sentinel", "sourceDisplayName": "Microsoft Sentinel", "vendorIdentifiers": { "sentinel": { "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "subscriptionId": "22222222-2222-2222-2222-222222222222", "resourceGroupName": "rg-security", "workspaceName": "law-contoso", "incidentNumber": 4242, "portalUrl": "https://portal.azure.com/..." } }, "comment": { "id": "3d2f7b1c-9e8a-4f65-b0c4-1a2b3c4d5e6f", "content": "Confirmed with the user; the sign-in was not theirs. Resetting the password and revoking sessions.", "createdAt": "2026-08-03T14:31:39.870Z", "author": { "displayName": "Jane Doe", "email": "jdoe@contoso.example", "type": "analyst", "agentName": null }, "ticketId": "T0012345", "ticketNoteId": "N-77" } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string \| null | Incident title. | | `severity` | string \| null | Incident severity when the comment was added. | | `source` | string | Detection source in PascalCase for this event, for example `Sentinel`. | | `sourceDisplayName` | string \| null | Human-readable source name. | | `vendorIdentifiers` | object \| null | Vendor identifiers for this incident. See [Vendor identifiers](#vendor-identifiers). | | `comment.id` | string | The comment id in the source system, or a ContraForce id for sources that do not expose a stable comment id. | | `comment.content` | string | The full comment text as submitted. | | `comment.createdAt` | string | ISO 8601 time the comment was created. | | `comment.author.displayName` | string | Who wrote the comment. | | `comment.author.email` | string \| null | Author email, when the author is a portal or API user. | | `comment.author.type` | string | `analyst` for a portal or API user, `agent` for a Security Delivery Agent. | | `comment.author.agentName` | string \| null | The agent's name when `type` is `agent`. | | `comment.ticketId` | string \| null | The PSA ticket the comment was mirrored to as a note, when the workspace has a ticketing integration. | | `comment.ticketNoteId` | string \| null | The note created on `ticketId`, when one was. Use it to avoid posting the same note a second time. | > [!WARNING] > > The incident block (`incidentNumber`, `title`, `severity`, `sourceDisplayName`, `vendorIdentifiers`) is read from the source system when the event is built. If that read fails, the event is still delivered with those fields `null`. `incidentId`, `source` and `comment` are always present, so key your handler on those. *** ## `gamebook.run.v1` Fires when a Gamebook is dispatched to the executor against an incident, whether an analyst started it from the portal or public API, or the AI agent did. > [!NOTE] > > Gamebooks awaiting approval do not fire this event while queued. The event is emitted when the run is actually dispatched. ```json theme={null} { "type": "gamebook.run.v1", "timestamp": "2026-08-03T15:10:44.502Z", "isTest": false, "occurredAt": "2026-08-03T15:10:44.502Z", "data": { "accountId": "11111111-1111-1111-1111-111111111111", "accountName": "Contoso Production", "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "incidentNumber": 4242, "title": "Compromised account containment", "source": "Sentinel", "gamebookId": "3c9d1b7e-2f44-4a86-8c11-9e0f7d5a2b31", "gamebookTitle": "Compromised account containment", "playbooks": ["Disable user", "Revoke sign-in sessions"], "runAt": "2026-08-03T15:10:44.502Z", "runBy": { "displayName": "Jane Doe" } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `accountId` / `accountName` | string | The workspace the incident belongs to. | | `incidentId` | string | The source system's incident identifier. | | `incidentNumber` | number \| null | The incident number shown in the portal. | | `title` | string | The gamebook title. Duplicates `gamebookTitle`; it is not the incident title. | | `source` | string | Detection source of the incident in PascalCase, for example `Sentinel`. | | `gamebookId` | string | GUID of the gamebook that ran. | | `gamebookTitle` | string | Display title of the gamebook. | | `playbooks` | string\[] | Display names of the playbooks in the dispatched gameplan. | | `runAt` | string | ISO 8601 dispatch time. | | `runBy.displayName` | string | The triggering identity: an analyst's name, or the AI agent's service identity. | *** ## `agent.investigation.completed.v1` Fires once per investigation, when a Security Delivery Agent completes and reaches a classification whose card has a webhook custom action configured. > [!NOTE] > > This event is configured per classification on an Agent Configuration card, not as a broadcast subscription. Set it up under [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) by enabling **Advanced** mode and choosing a webhook as the **custom action** for a classification. Full walkthrough and troubleshooting: [Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook). ```json theme={null} { "type": "agent.investigation.completed.v1", "timestamp": "2026-08-03T14:31:09.740Z", "isTest": false, "occurredAt": "2026-08-03T14:31:02.310Z", "data": { "workspace": { "id": "11111111-1111-1111-1111-111111111111", "alias": "contoso", "name": "Contoso Production" }, "agent": { "id": "5b2e9c4a-77d1-4c0b-a8f3-2d6e1c9b0a55", "name": "Tier 1 Triage Agent" }, "incident": { "id": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d", "number": 4242, "source": "Sentinel", "title": "Suspicious sign-in from impossible travel", "severity": "High", "status": "Active" }, "verdict": { "classificationBucket": "TruePositive", "classificationReason": "SuspiciousActivity", "classificationReasonComment": "Confirmed credential theft", "comment": "Sign-in originated from a known-malicious ASN minutes after a login from the user's usual location.", "maliciousScore": 87 }, "gamebookRecommendation": { "incidentNumber": 4242, "incidentTitle": "Suspicious sign-in from impossible travel", "playbooks": [ { "playbookId": "disable-user", "affectedEntity": "Account", "entityId": "jdoe@contoso.example", "sequence": 1 } ] } } } ``` ### Fields | Field | Type | Description | | - | - | - | | `workspace.id` / `alias` / `name` | string | The ContraForce workspace the incident belongs to. | | `agent.id` / `name` | string | The Security Delivery Agent that ran the investigation. | | `incident.id` | string | The source system's incident identifier. | | `incident.number` | number | The incident number shown in the portal. | | `incident.source` | string | Detection source in PascalCase, for example `Sentinel`. | | `incident.title` | string | Incident title. | | `incident.severity` | string | Incident severity. | | `incident.status` | string | Incident status at completion. | | `verdict.classificationBucket` | string | The agent's verdict. One of `TruePositive`, `BenignPositive`, `FalsePositive`, `Undetermined`. | | `verdict.classificationReason` | string \| null | Reason code for the classification. | | `verdict.classificationReasonComment` | string \| null | Free-text reason detail. | | `verdict.comment` | string | The agent's investigation summary comment. | | `verdict.maliciousScore` | number \| null | How malicious the agent judged the incident, 0-100. See [Malicious score](#malicious-score). | | `gamebookRecommendation` | object \| null | Present only when the agent recommended gamebooks. | | `gamebookRecommendation.playbooks[]` | array | Each with `playbookId`, `affectedEntity`, `entityId`, and `sequence`. | ### Malicious score `verdict.maliciousScore` reports how malicious the agent judged the incident to be, on a 0-100 scale. It lets you branch on degree rather than only on the four-value `classificationBucket`, for example auto-closing below a threshold while escalating above one. > [!WARNING] > > The score is a **maliciousness** reading, not a confidence reading. A verdict the agent is completely certain is a False Positive scores near **0**, not near 100. Reading it as confidence inverts the meaning of every benign verdict. | Range | Meaning | | - | - | | 0-34 | Judged benign. | | 35-69 | Ambiguous, worth a human look. | | 70-100 | Judged malicious. | The bands above match how the portal colors the score. They are guidance for reading a value, not thresholds the platform enforces. `maliciousScore` is `null` when the investigation came through the legacy agent path, which does not collect a score. The key is always present on this payload, so check for `null` rather than for absence. *** ## Delivery Rules These apply to every event type. ### Retries Delivery is at-least-once. A failed attempt is retried with a fixed backoff, up to **10 attempts** within a **5 minute** window from the first attempt. Whichever limit is hit first ends the retry budget and the event is dead-lettered. | Next attempt | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | | - | - | - | - | - | - | - | - | - | - | | Backoff | 5s | 10s | 15s | 20s | 30s | 30s | 40s | 50s | 60s | Retries are triggered by HTTP `408`, `429`, `500`, `502`, `503`, and `504`, and by connection or timeout errors. Any other non-success status is treated as a permanent failure and is not retried. A `Retry-After` header is honored when it is longer than the scheduled backoff, clamped to the 5 minute retry window. > [!WARNING] > > Retries reuse the same `X-CF-Event-Id`. Make your handler idempotent and deduplicate on that value. ### Event IDs `incident.created.v1`, `incident.closed.v1`, `gamebook.run.v1` and `incident.comment.added.v1` derive a deterministic event ID from the underlying subject (the comment, for comment events), so a republished event produces the same ID and can be deduplicated. `incident.status.changed.v1` and `incident.assignee.changed.v1` get a fresh ID per transition. The same transition can happen more than once on one incident (pause, resume, pause again), and each occurrence is a distinct event that a subject-derived ID would wrongly collapse. Test events and manually triggered incident fires get a fresh ID per fire, which is what distinguishes a manual replay from the original automatic event. ### Auto-disable If **5 or more distinct incidents** fail final delivery to the same webhook within a rolling **24 hours**, the webhook is automatically disabled and stops receiving events. Test deliveries never count toward this threshold. Re-enable it with `POST /webhooks/{id}/enable` or from the webhook detail page in the portal, after fixing the endpoint. ### Delivery logs Every delivery attempt is recorded as a delivery-log entry on the webhook. Entries are listed on the webhook's **Events** tab under **Settings → Developers** in the portal and through `GET /webhooks/{id}/delivery-logs`. A delivery-log entry is delivery metadata, not a copy of the event. Incident content is processed in memory while the event is built and sent, and none of it is written to the log. | Retained | Not retained | | - | - | | Event ID, event type, and when the event occurred | The event body that was sent | | Outcome (`Pending`, `Succeeded`, `Failed`), HTTP status code, latency, and the HTTP reason phrase on failure | The response body your endpoint returned | | Attempt number and, for retries, the ID of the original delivery | The incident title | | Source workspace ID and name | | | Incident ID, source, severity, status, and the label `Incident #` | | Entries are kept for a bounded period and expire automatically; they are not retained for the life of the account. Opening an entry in the portal, or calling `GET /webhooks/{id}/delivery-logs/{logId}`, shows the incident as it stands **now**, fetched live from the source system. It is not a snapshot of what was sent. When the incident no longer exists, the entry shows its delivery metadata and no body. See the [delivery log model](/api-reference/models#delivery-log) for the response shape. > [!NOTE] > > Entries written before 2026-08-27 may still carry a stored body and response snippet until they expire or are purged. ### Redelivery A `Failed` entry can be sent again with `POST /webhooks/{id}/delivery-logs/{logId}/redeliver?createdAt=` or from the entry's details in the portal. Because the body is not stored, redelivery rebuilds it from the source incident at the moment you redeliver. * The envelope keeps the original `X-CF-Event-Id` and `occurredAt`, so deduplication treats it as the same event. * `data` reflects the incident's **current** state. Status, owner, severity, and alerts can differ from what the original attempt carried. * Only `incident.created.v1` can be rebuilt. `incident.closed.v1`, `gamebook.run.v1`, and `agent.investigation.completed.v1` cannot be redelivered. When redelivery is not possible the response is a `422` with `code` `VALIDATION_ERROR`, or a `409` with `code` `CONFLICT`. The `detail` field says why: | Status | `detail` | What to do | | - | - | - | | `422` | Delivery is not in Failed status | Only `Failed` entries can be redelivered. | | `409` | Redelivery already in progress | Wait for the in-flight redelivery to finish; the entry's `redeliveryRequestedAt` is set. | | `422` | This delivery cannot be rebuilt for redelivery | The event type has no rebuild path, or the entry predates payload rebuild. | | `422` | The incident that produced this event is no longer available | The incident was deleted, or its workspace was offboarded or the detection module disconnected. | | `422` | Webhook configuration status is `Paused` or `Disabled` | Resume or re-enable the webhook, then redeliver. | ### Requirements for your endpoint * Must be reachable over HTTPS. Plain HTTP, localhost, and private network addresses are rejected at configuration time. * Must respond within **30 seconds**. Acknowledge with a 2xx immediately and do the real work asynchronously. * Response bodies are read up to 1 MB and then discarded. The delivery log records the HTTP status code and latency, never the body. * Should default-ignore unknown values of `X-CF-Schema` so new event types do not break your handler. *** ## Subscribing Set the event types when you create or update a webhook. At least one is required. ```json theme={null} { "name": "SIEM-ingest-prod", "url": "https://siem.contoso.example/api/webhook", "eventTypes": [ "incident.created.v1", "incident.status.changed.v1", "incident.assignee.changed.v1", "incident.comment.added.v1", "incident.closed.v1", "gamebook.run.v1" ], "monitoredAccountIds": [ "11111111-1111-1111-1111-111111111111" ], "authenticationType": "Bearer", "token": "your-bearer-token", "signingToken": "your-hmac-signing-secret" } ``` `webhook.test.v1` is not subscribable. `agent.investigation.completed.v1` must be listed here *and* selected on an Agent Configuration classification card before it delivers anything. Delivery outcomes for every event are visible on each webhook's **Events** tab under **Settings → Developers**, and through `GET /webhooks/{id}/delivery-logs`. > [!NOTE] > > Questions about webhook events? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Create webhook Source: https://docs.contraforce.com/api-reference/webhooks/create-webhook /api-reference/openapi.json post /api/v2/webhooks # Delete webhook Source: https://docs.contraforce.com/api-reference/webhooks/delete-webhook /api-reference/openapi.json delete /api/v2/webhooks/{id} # Enable webhook Source: https://docs.contraforce.com/api-reference/webhooks/enable-webhook /api-reference/openapi.json post /api/v2/webhooks/{id}/enable # Get webhook Source: https://docs.contraforce.com/api-reference/webhooks/get-webhook /api-reference/openapi.json get /api/v2/webhooks/{id} # Get webhook delivery log Source: https://docs.contraforce.com/api-reference/webhooks/get-webhook-delivery-log /api-reference/openapi.json get /api/v2/webhooks/{id}/delivery-logs/{logId} # List webhook delivery logs Source: https://docs.contraforce.com/api-reference/webhooks/list-webhook-delivery-logs /api-reference/openapi.json get /api/v2/webhooks/{id}/delivery-logs # List webhooks Source: https://docs.contraforce.com/api-reference/webhooks/list-webhooks /api-reference/openapi.json get /api/v2/webhooks # Pause webhook Source: https://docs.contraforce.com/api-reference/webhooks/pause-webhook /api-reference/openapi.json post /api/v2/webhooks/{id}/pause # Redeliver webhook Source: https://docs.contraforce.com/api-reference/webhooks/redeliver-webhook /api-reference/openapi.json post /api/v2/webhooks/{id}/delivery-logs/{logId}/redeliver # Regenerate webhook secret Source: https://docs.contraforce.com/api-reference/webhooks/regenerate-webhook-secret /api-reference/openapi.json post /api/v2/webhooks/{id}/regenerate-secret # Resume webhook Source: https://docs.contraforce.com/api-reference/webhooks/resume-webhook /api-reference/openapi.json post /api/v2/webhooks/{id}/resume # Test webhook Source: https://docs.contraforce.com/api-reference/webhooks/test-webhook /api-reference/openapi.json post /api/v2/webhooks/{id}/test # Update webhook Source: https://docs.contraforce.com/api-reference/webhooks/update-webhook /api-reference/openapi.json put /api/v2/webhooks/{id} # Update webhook credentials Source: https://docs.contraforce.com/api-reference/webhooks/update-webhook-credentials /api-reference/openapi.json post /api/v2/webhooks/{id}/credentials # After the Breach: Data Breach Recovery and Communication Source: https://docs.contraforce.com/blog/after-the-breach Use this data breach recovery plan to confirm containment, map notification deadlines, communicate with stakeholders, and run a post-incident review. > [!NOTE] > > **Who is this for?** Security Leaders, CISOs, MSP/MSSP Partners **February 27, 2026** · ContraForce Team · 8 min read Most cybersecurity content focuses on prevention and detection. But what happens in the days, weeks, and months after an incident is what determines whether your organization recovers or spirals. This playbook covers the full post-incident journey — from immediate stabilization through long-term recovery — including the communication, legal, and operational steps that most organizations aren't prepared for. *** ## The First 72 Hours: Stabilize and Assess The period immediately following incident containment is chaotic. Your security team is exhausted, leadership wants answers, and every stakeholder has a different urgent question. Having a structured approach prevents the response from creating new problems. ### Confirm Containment Before Pivoting to Recovery Before any recovery work begins, verify with your incident response team (internal or external) that the attacker has been fully evicted from your environment. Premature recovery — rebuilding systems while the attacker still has access — is one of the most common and costly mistakes in incident response. Confirm that attacker access has been revoked across all affected accounts and systems, that compromised credentials have been reset, that the initial access vector has been identified and closed, and that monitoring is in place to detect any re-entry attempts. ### Establish a Recovery Command Structure Incident response and business recovery require different skills and different leadership. Designate a Recovery Lead — ideally someone from operations or business leadership, not your security team — to coordinate the recovery effort. Your security team should remain focused on forensic investigation and monitoring while the Recovery Lead manages the restoration of business operations. Create a clear chain of communication. Who reports to whom? Who authorizes decisions about system restoration priority? Who speaks to customers, regulators, and the press? Establishing this structure before the chaos peaks is essential. ### Assess the Blast Radius Work with your incident response team to document exactly what was affected. Determine which systems, data, and services were compromised, encrypted, destroyed, or accessed without authorization. Categorize the impact into operational impact (which business processes are disrupted), data impact (what data was accessed, exfiltrated, or destroyed), and financial impact (revenue loss, recovery costs, potential fines). This assessment drives every decision that follows — what to restore first, who to notify, and what to tell stakeholders. ## Week 1: Begin Restoration and Notification ### Prioritize System Restoration by Business Impact Not all systems are equally critical. Work with business unit leaders to rank systems by their impact on revenue, customer commitments, and safety. Restore the systems that keep your business running first, then work outward to supporting systems and lower-priority services. For each system, decide whether to restore from backup, rebuild from scratch, or implement a temporary workaround. Restoring from backup is faster but requires confidence that your backups are clean and weren't compromised. Rebuilding takes longer but ensures a known-good state. Document every restoration decision and the rationale behind it. ### Activate Your Legal and Regulatory Notification Obligations Data breach notification laws vary by jurisdiction, and failing to notify on time carries its own penalties. In the United States, 50 states plus the District of Columbia, Guam, Puerto Rico, and the U.S. Virgin Islands all have separate breach notification laws. Notification timelines range from 30 to 90 days depending on the state, with some states requiring notification "without unreasonable delay." At the federal level, HIPAA requires notification within 60 days for breaches affecting 500 or more individuals. The SEC requires publicly traded companies to disclose material cybersecurity incidents within four business days of determining materiality. Defense contractors have 72-hour notification requirements under DFARS. If you have EU customers or employees, GDPR requires notification to the relevant Data Protection Authority within 72 hours of becoming aware of a breach involving personal data, and notification to affected individuals "without undue delay" if the breach poses a high risk to their rights and freedoms. Engage your breach counsel early. They will help you map your notification obligations based on the data involved, the jurisdictions affected, and the nature of the incident. Getting this wrong creates legal exposure on top of the operational disruption you're already managing. ### Notify Your Cyber Insurance Carrier If you haven't already, formally notify your carrier in writing. Provide a summary of what happened, what data was affected, and what response actions have been taken. Request approval for any recovery expenditures that you expect the policy to cover. Keep your carrier informed throughout the recovery process — surprises during the claims process rarely end well. ## Weeks 2 Through 4: Communicate with Stakeholders Communication after a breach is where many organizations do the most lasting damage — not from the breach itself, but from how they handle the message. Silence, deflection, and corporate jargon erode trust far more than the incident itself. ### Communicating with Customers Customers want to know three things: what happened, how it affects them, and what you're doing about it. Tell them clearly and directly. Avoid vague language like "a security event" when what happened was a ransomware attack or data exfiltration. Acknowledge the impact honestly, explain what steps you've taken to contain and remediate the incident, describe what you're doing to prevent recurrence, and provide specific actions they should take (change passwords, monitor accounts, enroll in credit monitoring if applicable). Provide a dedicated channel for questions — a phone number, email address, or web page — and staff it with people who can actually answer questions. Nothing frustrates an affected customer more than being routed to a generic support queue. ### Communicating with Employees Your employees are stakeholders too, and they're often the most anxious. They want to know whether their personal data was affected, whether their jobs are at risk, and what the company is doing. Be transparent with your workforce. If employee data was compromised, tell them immediately with the same specificity and support you'd offer customers. Provide clear guidance on what they should do to protect themselves. Also address operational concerns. If workflows have changed, systems are unavailable, or processes are disrupted, give employees clear instructions on interim procedures. The faster you reduce uncertainty, the faster productivity recovers. ### Communicating with Regulators Regulatory communications should be factual, precise, and managed by your legal team. Provide the information required by the relevant notification statute and nothing more. Voluntary over-disclosure can create additional legal exposure. Your breach counsel will advise on the appropriate level of detail for each jurisdiction and regulator. ### Communicating with the Media If your breach attracts media attention, designate a single spokesperson and prepare a written statement. Keep the statement factual, empathetic, and forward-looking. Acknowledge what happened, express concern for affected individuals, and outline the steps you're taking. Avoid speculation about the attacker, the scope of the breach (until you're confident in your assessment), or blame. Do not say "we take security seriously" — it has become a meaningless cliche that signals the opposite of what you intend. If you have a communications or PR team, activate them immediately. If you don't, your cyber insurance policy likely includes access to crisis communications professionals. Use them. ### Communicating with Partners and Vendors If the breach affects data you share with partners or vendors, or if it originated through a supply chain compromise, those partners need to be notified promptly. Beyond legal obligations, maintaining trust with business partners requires honesty and speed. Provide them with enough technical detail to assess their own exposure and take protective action. ## Months 1 Through 3: Recover and Rebuild ### Conduct a Post-Incident Review Once the immediate crisis has passed, conduct a thorough post-incident review (sometimes called a "lessons learned" or "after-action" review). This should involve everyone who participated in the response, including IT, security, legal, communications, executive leadership, and any external parties (forensics firms, breach counsel, insurance carrier). The review should document the full timeline of the incident from initial compromise to detection to containment to recovery. Identify what worked well in the response and what didn't. Assess where detection was too slow and why. Evaluate whether the incident response plan was followed and where it broke down. Catalog specific improvements needed in technology, process, and people. The output of this review should be a prioritized action plan, not a shelf document. Assign owners and deadlines to every improvement item. ### Address Root Causes, Not Just Symptoms If the attacker gained access through an unpatched VPN appliance, patching that appliance is necessary but insufficient. The root cause question is: why wasn't it patched? Was there no vulnerability management program? Was there a program but no enforcement? Was there enforcement but no visibility into that asset? Dig until you find the systemic issue and fix that. Otherwise, the next incident will follow a different path to the same outcome. ### Rebuild Trust Through Visible Action Customers, partners, and employees will judge your organization not by the breach, but by your response to it. Organizations that communicate transparently, act decisively, and demonstrably improve their security posture often emerge with stronger relationships than they had before. Consider publishing a summary of the improvements you've made (without revealing specific vulnerabilities). Offer affected customers ongoing monitoring or protection. If appropriate, share anonymized lessons learned with your industry peers or through ISACs (Information Sharing and Analysis Centers). ## Building Long-Term Resilience ### Update Your Incident Response Plan If your plan didn't work perfectly during the incident — and no plan survives first contact — update it based on what you learned. Test the updated plan through a tabletop exercise within 90 days of the incident. ### Invest in Detection and Response Gaps The post-incident review will almost certainly reveal gaps in your detection and response capabilities. Whether that means deploying managed detection and response, improving log retention and analysis, or adding identity threat detection, invest in closing the gaps that allowed the incident to progress as far as it did. ### Establish a Regular Cadence of Testing Tabletop exercises should happen at least twice a year, with at least one involving executive leadership and external partners (legal, insurance, communications). Penetration testing should occur annually at minimum. Backup restoration tests should happen quarterly. Recovery readiness isn't something you build once. It's something you practice continuously. *** ## Quick Summary * The breach itself is rarely what destroys an organization; the slow, fumbled, opaque response that follows is. * A recovery playbook, clear communication templates, and a practiced command structure turn a crisis into a manageable business challenge. * Prepare for the aftermath with the same rigor you apply to prevention. *ContraForce helps organizations detect, respond to, and recover from security incidents with clarity and speed. [Explore the ContraForce platform](https://www.contraforce.com).* > **[Security Incident Management](/guides/getting-started/incident-management)** > > Triage, assign, and close incidents across workspaces > **[What Are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > No-code incident response workflows > **[Cyber Insurance Buying Guide](/blog/complete-cyber-insurance-buying-guide)** > > How to file a claim and maximize recovery > **[Meeting Cyber Insurance Requirements](/guides/contraforce-and-compliance/contraforce-and-cyber-insurance)** > > Answer insurer questions about incident response > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # 10 Ways to Automate Multi-Tenant Microsoft Sentinel Source: https://docs.contraforce.com/blog/agentic-ai/10-ways-multi-tenant-automation See 10 ways to automate multi-tenant Microsoft Sentinel and Defender for Endpoint management: one incident queue, Gamebooks, and response in any workspace. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Engineers **April 25, 2025** · ContraForce Team · 5 min read Managing Microsoft Sentinel and Defender for Endpoint across multiple customer tenants presents significant operational challenges. Here are 10 ways ContraForce uniquely automates multi-tenant security operations. ## 1. Unified Incident Queue All incidents from all customer workspaces flow into a single, prioritized queue: * No portal pivoting between customer environments * Severity-based prioritization across the entire portfolio * Context-aware grouping of related incidents ## 2. Cross-Tenant Entity Enrichment When investigating an entity, ContraForce automatically enriches it with data from the relevant customer tenant: * User sign-in history from Microsoft Entra ID * Device details from Defender for Endpoint * Activity logs from Microsoft 365 ## 3. Gamebook-Driven Response Pre-built response workflows execute consistently across all workspaces: * Same investigation steps regardless of customer * Consistent documentation and audit trails * Reduced training burden for analysts ## 4. Automated Gamebook Mapping Incidents automatically map to appropriate Gamebooks based on type and severity: * No manual selection required * Consistent handling of similar incidents * Faster time to first action ## 5. Security Delivery Agents AI agents autonomously handle investigation and response: * Triage incidents at machine speed * Execute response actions with supervision * Document findings automatically ## 6. Centralized Detection Management (Content Management Center) Deploy and manage detection rules across all customer Sentinel workspaces: * Versioned rule repositories deployed to the workspaces you choose * Bulk operations across workspaces * Version control and rollback ## 7. Multi-Tenant Response Actions Execute response actions in any customer workspace without context switching: * Isolate devices across workspaces * Disable accounts in any customer Microsoft Entra ID * Block threats portfolio-wide ## 8. Unified Reporting Generate reports across your entire customer portfolio: * Incident trends across all customers * Response time metrics * Coverage and gap analysis ## 9. Customer-Aware Context Every action is performed in the context of the right customer: * Automatic tenant selection * Customer-specific configurations respected * Audit trails per customer ## 10. Scalable Architecture The platform scales with your customer base: * Add customers without adding complexity * Consistent performance as you grow * No per-tenant infrastructure to manage ## The Cumulative Effect These 10 capabilities combine to enable: | Metric | Without ContraForce | With ContraForce | | - | - | - | | **Customers per analyst** | 10-15 | 100+ | | **Mean time to investigate** | 30+ minutes | Minutes | | **Response consistency** | Variable | 100% | | **Portal pivoting** | Constant | Eliminated | ## Quick Summary * Unified incident queue eliminates portal pivoting with severity-based prioritization across all customers. * Gamebooks and Security Delivery Agents ensure consistent, automated investigation and response. * Centralized Detection Management (Content Management Center) deploys versioned detection rules to the workspaces you choose, with drift detection and rollback. * Multi-tenant response actions and customer-aware context enable portfolio-wide threat blocking. * The result: 100+ customers per analyst, minutes to investigate, and 100% response consistency. > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore multi-tenant capabilities > **[Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Configure AI automation > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # How MSSPs Can Implement CISA SIEM and SOAR Guidance Source: https://docs.contraforce.com/blog/agentic-ai/cisa-siem-soar-guidance See how MSSPs can apply CISA SIEM and SOAR guidance on log collection, automated response, and threat intelligence, with a phased implementation roadmap. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Engineers **June 10, 2025** · ContraForce Team · 4 min read CISA has released new guidance for organizations implementing SIEM and SOAR solutions. For MSSPs managing security operations across multiple customers, this guidance has significant implications for how you deliver services. ## Key CISA Recommendations The guidance emphasizes several critical areas: ## 1. Centralized Log Collection CISA recommends organizations centralize security logs from all critical systems. For MSSPs, this means: * Ensuring comprehensive log coverage across customer environments * Normalizing data for consistent analysis * Maintaining appropriate retention periods ## 2. Automated Detection and Response The guidance strongly advocates for automation to reduce response times: * Automated triage of common alert types * Pre-defined response playbooks for known threats * Reduced mean time to respond (MTTR) ## 3. Threat Intelligence Integration CISA emphasizes the importance of threat intelligence: * Integration with threat intel feeds * Automated correlation with known indicators * Context-aware alerting ## How ContraForce Helps MSSPs Comply ContraForce is designed to help MSSPs implement these recommendations across their entire customer base: ## Centralized Operations * Unified view of all customer Microsoft Sentinel and Defender for Endpoint environments * Consistent log ingestion and normalization * Multi-tenant visibility without portal pivoting ## Automated Response * Gamebooks provide pre-defined response workflows * Security Delivery Agents automate investigation and response * Consistent outcomes across all customer environments ## Built-in Intelligence * Entity enrichment with threat intelligence * Automated correlation of indicators * Risk-based prioritization ## Implementation Roadmap For MSSPs looking to align with CISA guidance: | Phase | Focus Area | ContraForce Capability | | - | - | - | | **1** | Log centralization | Microsoft Sentinel integration | | **2** | Detection deployment | Content Management Center for rule management | | **3** | Response automation | Gamebook workflows | | **4** | Continuous improvement | Security Delivery Agents | ## Quick Summary * CISA guidance emphasizes centralized log collection, automated detection/response, and threat intelligence integration. * MSSPs must implement these capabilities across their entire customer base. * ContraForce provides centralized operations, Gamebook-driven automation, and built-in threat intelligence. * A phased implementation roadmap helps MSSPs align with CISA recommendations using ContraForce capabilities. > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel > **[Content Management Center](/guides/content-management-center/overview)** > > Deploy detection content > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # How to Become an MSSP: 7 Essential Features Source: https://docs.contraforce.com/blog/agentic-ai/mssp-essential-features Moving from MSP to MSSP? See the 7 capabilities you need, from multi-tenant visibility and incident triage to response automation, reporting, and scale. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Leaders **March 4, 2025** · ContraForce Team · 5 min read Transitioning from a traditional MSP to a managed security service provider (MSSP) requires specific capabilities. Here are the 7 essential features you need to successfully deliver managed security services. ## 1. Multi-Tenant Security Visibility You need to see security events across all customer environments: * **Unified dashboard** — Single view of all customer incidents * **Cross-tenant search** — Find threats portfolio-wide * **Customer context** — Understand each customer's environment Without multi-tenant visibility, you'll spend more time switching between environments than actually securing them. ## 2. Incident Detection and Triage You need the ability to detect and prioritize security incidents: * **SIEM integration** — Connect to customer security tools * **Alert correlation** — Group related alerts into incidents * **Priority scoring** — Focus on what matters most Detection is the foundation of security services. Without it, you're reacting to customer complaints, not proactively protecting them. ## 3. Investigation Capabilities When incidents occur, you need tools to investigate: * **Entity enrichment** — Context about users, devices, IPs * **Timeline views** — Understand the sequence of events * **Log search** — Dig into raw data when needed Investigation speed directly impacts your ability to contain threats before they cause damage. ## 4. Response Automation You need the ability to take action on threats: * **Containment actions** — Isolate devices, disable accounts * **Remediation workflows** — Standardized response procedures * **Supervised automation** — AI-assisted response with oversight Manual response doesn't scale. Automation is essential for profitable security delivery. ## 5. Reporting and Documentation You need to demonstrate value to customers: * **Incident reports** — Documentation of what happened and what you did * **Trend analysis** — Show improvement over time * **Compliance support** — Help customers meet requirements Reporting justifies your value and supports customer compliance needs. ## 6. Customer Communication You need efficient ways to communicate with customers: * **Notification automation** — Keep customers informed without manual effort * **Escalation procedures** — Clear paths for critical issues * **Self-service portals** — Let customers see their security status Good communication builds trust and reduces support burden. ## 7. Operational Scalability You need an operating model that scales: * **Standardized processes** — Consistent delivery across all customers * **Automation** — Reduce manual effort per customer * **Platform leverage** — Technology that multiplies analyst effectiveness Scalability is what makes security services profitable. ## Building Your MSSP Practice | Feature | DIY Approach | Platform Approach | | - | - | - | | **Multi-tenant visibility** | Per-tenant portals | Unified platform | | **Detection** | Custom per customer | Centralized management | | **Investigation** | Manual, tool-hopping | Integrated workflow | | **Response** | Custom playbooks | Standardized Gamebooks | | **Reporting** | Manual reports | Automated dashboards | | **Communication** | Email/phone | Integrated notifications | | **Scalability** | Linear growth | Exponential leverage | ## Quick Summary * MSSPs need multi-tenant visibility, strong detection and triage, and fast investigations to protect all customers effectively. * Scalable response automation and standardized workflows are critical to keeping security services profitable. * Clear reporting, documentation, and communication prove ongoing value and support customer compliance. * Operational scalability, powered by automation and a unified platform, turns linear effort into leveraged growth. * A platform approach replaces fragmented DIY tools with integrated capabilities across visibility, response, and reporting. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore multi-tenant capabilities > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Security Delivery Platforms: Reimagining the MSSP Model Source: https://docs.contraforce.com/blog/agentic-ai/security-delivery-platform-reimagining See how a Security Delivery Platform reimagines the MSSP model, replacing per-customer portals and headcount-driven growth with multi-tenant automation. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Leaders **February 28, 2025** · ContraForce Team · 5 min read The managed security services market is evolving. Traditional approaches that worked a decade ago are struggling to scale with modern threats and customer expectations. Security Delivery Platforms represent a fundamental reimagining of how security services are delivered. ## The Problem with Traditional MSSP Models Traditional MSSP delivery models face significant challenges: ## Scale Limitations * **Analyst-dependent** — Every customer requires human attention * **Linear growth** — Adding customers means adding headcount * **Margin pressure** — Labor costs erode profitability ## Consistency Challenges * **Knowledge silos** — Expertise concentrated in individuals * **Variable quality** — Outcomes depend on who's working * **Training burden** — Constant investment in skill development ## Technology Fragmentation * **Portal pivoting** — Jumping between customer environments * **Inconsistent tooling** — Different approaches per customer * **Integration overhead** — Custom work for each deployment ## The Security Delivery Platform Approach Security Delivery Platforms fundamentally rethink service delivery: ## Multi-Tenant by Design * Single platform, all customers * No portal pivoting * Consistent visibility and control ## Automation First * AI agents for investigation and response * Gamebook workflows for consistency * Human oversight, not human dependency ## Platform Native * Deep integration with security ecosystems * Native capabilities, not bolt-ons * Continuous improvement through platform updates ## Key Capabilities of a Security Delivery Platform | Capability | Traditional MSSP | Security Delivery Platform | | - | - | - | | **Customer visibility** | Per-tenant portals | Unified multi-tenant view | | **Investigation** | Manual, analyst-driven | AI-assisted, automated | | **Response** | Custom per customer | Standardized Gamebooks | | **Scale** | Linear with headcount | Exponential with automation | | **Consistency** | Varies by analyst | Enforced by platform | ## The Economic Impact Security Delivery Platforms change the economics of managed security: * **More customers per analyst** — 10x improvement possible * **Lower cost per incident** — Automation reduces unit economics * **Higher margins** — Scale without proportional cost increase * **Better outcomes** — Consistency improves customer satisfaction ## Getting Started For service providers considering a Security Delivery Platform: 1. **Assess current model** — Understand your scale limitations 2. **Evaluate platforms** — Look for multi-tenant, automation-first design 3. **Start with core use cases** — Don't try to transform everything at once 4. **Measure outcomes** — Track improvements in efficiency and quality ## Quick Summary * Traditional MSSP models face scale, consistency, and technology fragmentation challenges. * Security Delivery Platforms are multi-tenant by design with automation-first architecture. * Key benefits: 10x more customers per analyst, lower cost per incident, and consistent outcomes. * Platform-native integration eliminates portal pivoting and custom per-customer work. * Start by assessing your current model and evaluating platforms with multi-tenant automation. > **[Platform Overview](/overview)** > > Learn about ContraForce > **[Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Explore AI-powered automation > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # SIEM Market Consolidation: What It Means for MDR Providers Source: https://docs.contraforce.com/blog/agentic-ai/siem-vendor-landscape See how SIEM market consolidation and XDR convergence affect MDR providers, from choosing platforms to protecting margins and staying platform-agnostic. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Leaders **May 13, 2024** · ContraForce Team · 4 min read The SIEM market is undergoing significant transformation. Major acquisitions, new entrants, and evolving technology are reshaping how organizations approach security information and event management. For MDR providers, these changes present both challenges and opportunities. ## What's Changing ## Market Consolidation We've seen significant M\&A activity in the SIEM space: * Major vendors acquiring complementary technologies * Cloud-native SIEM platforms gaining market share * Traditional on-premises solutions facing migration pressure ## Technology Evolution SIEM capabilities are expanding: * **XDR convergence** — SIEM and XDR boundaries blurring * **Cloud-native architectures** — Scalability without infrastructure management * **AI/ML integration** — Automated detection and investigation * **SOAR convergence** — Response automation built-in ## Customer Expectations End customers expect more from their security investments: * Faster time to value * Reduced operational complexity * Better outcomes, not just more alerts ## Implications for MDR Providers ## Platform Strategy MDR providers need to consider: * Which SIEM platforms to support * How to manage multi-platform environments * Investment in platform-specific expertise ## Service Differentiation As SIEM capabilities become more commoditized: * Outcomes matter more than technology * Operational excellence becomes differentiator * Customer experience drives retention ## Economic Considerations Changing economics affect profitability: * Cloud SIEM pricing models vary significantly * Platform consolidation may reduce complexity * Automation is essential for margin protection ## How to Navigate the Change ## Build on Strong Foundations Focus on platforms with: * Strong market position and investment * Clear roadmap and vision * Robust partner ecosystem ## Invest in Operations Regardless of underlying SIEM: * Standardize your operational model * Automate repetitive tasks * Focus on outcomes over activities ## Stay Platform-Agnostic Maintain flexibility: * Abstract your operations from specific platforms * Build expertise across multiple technologies * Use multi-platform tools for consistency ## ContraForce Approach ContraForce helps MDR providers navigate this changing landscape by providing: * **Multi-platform support** — Work across Microsoft, Splunk, CrowdStrike, and IBM * **Consistent operations** — Same Gamebooks and workflows regardless of platform * **Microsoft focus** — Deepest integration with the fastest-growing ecosystem ## Quick Summary * The SIEM market is transforming through consolidation, cloud-native platforms, and XDR/SOAR convergence. * MDR providers must decide which platforms to support and how to differentiate on outcomes, not technology. * Automation is essential for protecting margins as cloud SIEM pricing models evolve. * ContraForce provides multi-platform support with consistent operations and deep Microsoft integration. > **[Platform Overview](/overview)** > > Learn about ContraForce > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore multi-tenant capabilities > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Agentic AI in Security Operations: Agents vs. Copilots Source: https://docs.contraforce.com/blog/agentic-ai/what-are-security-delivery-agents See how agentic AI in security operations differs from copilots, and how Security Delivery Agents investigate and respond with progressive autonomy. > [!NOTE] > > **Who is this for?** Security Engineers, CISOs, and Technical Decision-Makers **February 2026** · ContraForce Team · 6 min read The term "AI" gets applied to everything from simple automation to sophisticated reasoning systems. In security operations, understanding the difference matters — because the gap between a chatbot and an autonomous agent is the gap between answering questions and actually solving problems. ## Copilots vs. Agents: A Critical Distinction Most AI tools in security today are **copilots** — they assist humans but don't act independently. A copilot might suggest a query, summarize an alert, or draft a response. But the human still makes decisions and executes actions. **Agents** are different. An agent: * Perceives its environment (incoming incidents, entity data, historical context) * Reasons about what to do (investigation steps, response actions) * Takes action autonomously (executes queries, runs playbooks, updates incidents) * Learns from outcomes (refines recommendations based on results) Security Delivery Agents in ContraForce are true agents. They don't wait for you to ask questions — they investigate incidents, gather context, and execute responses based on your configured policies. ## Why Security Operations Needs Agents Security operations has a structural problem: the volume of incidents exceeds human capacity to investigate them thoroughly. Most SOC teams operate in triage mode, quickly classifying alerts and hoping the important ones get attention. Copilots don't solve this problem. They make individual analysts slightly faster, but they don't change the fundamental math. You still need a human in the loop for every incident. Agents change the equation by handling incidents end-to-end: | Capability | Copilot | Agent | | - | - | - | | Analyze an incident | Suggests analysis steps | Performs analysis automatically | | Gather context | Recommends what to look up | Queries sign-in logs, device timelines, related incidents | | Determine response | Suggests actions to take | Executes response actions through Gamebooks | | Document findings | Drafts notes for review | Writes incident comments automatically | | Handle volume | One incident at a time | Processes incidents in parallel across workspaces | ## What "Agentic" Actually Means The term "agentic AI" describes systems that act with autonomy toward goals. Key properties include: **Goal-directed behavior** — Agents work toward objectives (investigate this incident, contain this threat) rather than responding to individual prompts. **Persistent context** — Agents maintain awareness of the environment across multiple interactions, understanding how entities relate and how incidents connect. **Tool use** — Agents invoke external systems (query APIs, execute playbooks, update records) to accomplish their goals. **Adaptive execution** — Agents adjust their approach based on what they discover, rather than following rigid scripts. Security Delivery Agents exhibit all these properties. When an incident arrives, the agent determines what investigation is needed, gathers relevant context, decides on appropriate response actions, and executes them — all without human intervention for routine cases. ## The Trust Question Autonomous agents raise an obvious concern: how do you trust an AI to take security actions in production? ContraForce addresses this through progressive autonomy: 1. **Start manual** — Run agent investigations on-demand and review every output 2. **Automate investigation** — Let agents analyze incidents automatically, but review before action 3. **Enable response** — Allow agents to execute Gamebooks, with confidence thresholds controlling when actions proceed This phased approach lets you build confidence in agent behavior before granting broader autonomy. You also maintain human-in-the-loop controls for sensitive actions and comprehensive audit trails for everything agents do. ## The Future of Security Operations Agentic AI represents a fundamental shift in how security operations can work. Instead of humans doing repetitive investigation with AI assistance, agents handle routine work while humans focus on judgment calls, exception handling, and strategic improvements. This isn't about replacing analysts. It's about making analyst capacity go further — handling the incident volume that would otherwise be impossible to address thoroughly. ## Quick Summary * Copilots assist humans; agents act autonomously toward goals * Security Delivery Agents investigate incidents, gather context, and execute responses * Agentic AI properties: goal-directed, persistent context, tool use, adaptive execution * Progressive autonomy lets you build trust before enabling full automation * Agents handle volume; humans handle judgment and strategy > **[Configuring SDAs](/guides/getting-started/configuring-security-delivery-agents)** > > Configure Security Delivery Agents in your environment > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy the infrastructure that powers autonomous agents > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Named 2025 Security Orchestration Solution of the Year Source: https://docs.contraforce.com/blog/company/cybersecurity-breakthrough-awards-2025 ContraForce was named Security Orchestration Solution of the Year in the 2025 CyberSecurity Breakthrough Awards, which drew thousands of nominations. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **October 9, 2025** · ContraForce Team · 2 min read ContraForce today announced it has been named "Security Orchestration Solution of the Year" in the 2025 CyberSecurity Breakthrough Awards program conducted by CyberSecurity Breakthrough, a leading independent market intelligence organization that recognizes the top companies, technologies, and products in the global information security market today. The CyberSecurity Breakthrough Awards program is devoted to honoring excellence and recognizing the innovation, hard work, and success in a range of information security categories, including Cloud Security, Threat Detection, Risk Management, Fraud Prevention, Mobile Security, Email Security, and many more. "We are incredibly honored to receive this recognition from CyberSecurity Breakthrough," said Stan Golubchik, CEO and Co-Founder of ContraForce. "This award validates our approach to security orchestration — making it possible for service providers to automate and scale their security operations without the complexity typically associated with traditional SOAR platforms." ContraForce's Security Delivery Platform enables MSPs and MSSPs to orchestrate security operations across Microsoft Sentinel, Defender for Endpoint, and other security tools through a unified, multi-tenant platform. The platform's Gamebook-driven workflows and Security Delivery Agents automate incident investigation and response, reducing manual effort and improving consistency across customer environments. The mission of the CyberSecurity Breakthrough Awards is to honor excellence and recognize innovation in the information security industry. This year's program attracted thousands of nominations from across the globe. ## About ContraForce ContraForce is an AI-powered Security Delivery Platform built to help service providers deliver scalable MXDR and security outcomes across every customer they support. ContraForce operationalizes Microsoft Sentinel, Defender for Endpoint, Microsoft Entra ID, and Azure AI into a unified, multi-tenant platform that enables service providers to investigate, respond, and automate security faster and more cost effectively. > **[What Are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Learn about Gamebook automation > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # US Distribution Agreement with Ingram Micro Source: https://docs.contraforce.com/blog/company/ingram-micro-distribution A US distribution agreement lets US-based MSPs access ContraForce through Ingram Micro to operationalize Microsoft Sentinel and Defender for Endpoint. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners in the United States **December 17, 2024** · ContraForce Team · 2 min read ContraForce is pleased to announce a new US distribution agreement with Ingram Micro, one of the world's largest technology distributors. This partnership will allow US-based MSPs to access the ContraForce Security Delivery Platform through Ingram Micro's extensive distribution network. "Partnering with Ingram Micro represents a significant expansion of our go-to-market capabilities in the United States," said Stan Golubchik, CEO and Co-Founder of ContraForce. "Ingram Micro's extensive network and deep relationships with MSPs will help us reach more service providers who are looking to scale their security operations." ## What This Means for MSPs Through this distribution agreement, US-based MSPs can: * **Access ContraForce through Ingram Micro** — Leverage existing Ingram Micro relationships * **Maximize Microsoft investment** — Operationalize Microsoft Sentinel and Defender for Endpoint * **Scale security delivery** — Deliver consistent security outcomes across all customers ## About Ingram Micro Ingram Micro is a leading technology distributor with a global presence and deep expertise in helping partners deliver value to their customers. Their Cloud platform provides access to a curated marketplace of cloud solutions. ## About ContraForce ContraForce is an AI-powered Security Delivery Platform built to help service providers deliver scalable MXDR and security outcomes across every customer they support. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore multi-tenant capabilities > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Selected for the Microsoft for Startups Pegasus Program Source: https://docs.contraforce.com/blog/company/microsoft-pegasus-program ContraForce was selected for the Microsoft for Startups Pegasus Program, gaining deeper Microsoft integration and closer work with Microsoft product teams. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **March 26, 2025** · ContraForce Team · 2 min read ContraForce is excited to announce our selection for the Microsoft for Startups Pegasus Program. This elite program is designed for high-growth B2B startups that are building innovative solutions on Microsoft technology. The Pegasus Program provides advanced support, resources, and access to Microsoft's enterprise customer network, helping selected startups accelerate their growth and market presence. "Being selected for the Pegasus Program is a significant recognition of ContraForce's commitment to building enterprise-grade security solutions on Microsoft technology," said Stan Golubchik, CEO and Co-Founder of ContraForce. "This partnership will help us accelerate our mission of making enterprise-grade security accessible to service providers of all sizes." ## What This Means for Partners ContraForce's participation in the Pegasus Program strengthens our Microsoft relationship and provides: * **Deeper Microsoft integration** — Enhanced collaboration with Microsoft product teams * **Enterprise resources** — Access to advanced technical and business support * **Market acceleration** — Opportunities to reach more enterprise customers ## Built on Microsoft ContraForce is purpose-built for the Microsoft security stack: | Integration | Capability | | - | - | | **Microsoft Sentinel** | Incident ingestion, log search, CMS detection rules | | **Defender for Endpoint** | Defender incidents, device isolation, file quarantine | | **Microsoft Entra ID** | Sign-in logs, user account actions, session revocation | | **Microsoft Foundry** | Infrastructure for Security Delivery Agents | > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy Defender for Endpoint integration > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Named a Microsoft Security Excellence Awards Finalist Source: https://docs.contraforce.com/blog/company/microsoft-security-excellence-finalist ContraForce was named a Microsoft Security Excellence Awards finalist for Security Software Development Company, chosen from hundreds of submissions. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **November 19, 2025** · ContraForce Team · 2 min read Dallas, Texas, United States — ContraForce today announced it is a Security Software Development Company award finalist in the Microsoft Security Excellence Awards. The company was honored among a global field of industry leaders that demonstrated exceptional innovation, engineering excellence, and customer impact across the security landscape over the past 12 months. "We are incredibly proud to be recognized as a finalist for Security Software Development Company," said Stan Golubchik, CEO and Co-Founder of ContraForce. "Our team has built with purpose from day one, focused on helping service providers deliver security at scale with automation and AI. This recognition reflects our deep alignment with Microsoft's security vision and our commitment to making high-quality security delivery accessible for all." At the Microsoft Security Excellence Awards on January 26, 2026, Microsoft will honor finalists in six award categories that highlight partner trailblazers, solution innovators, customer and technology champions, and changemakers. This is the sixth year Microsoft has recognized partners for outstanding contributions in the global security ecosystem. All finalists are members of the Microsoft Intelligent Security Association (MISA), a community of leading security vendors whose solutions integrate with Microsoft's security technologies to protect customers against evolving threats. "I am very pleased to extend my warmest congratulations to this year's finalists for the Microsoft Security Excellence Awards. These are presented each year to recognize the outstanding achievements of our Microsoft Intelligent Security Association members as they improve customers' ability to identify and respond to security threats. Our community is made up of the most reliable and trusted security vendors worldwide. This year we received hundreds of quality submissions from partners and Microsoft stakeholders, so this year's finalists stood out in a crowd of exceptional talent. It is my pleasure to acknowledge and celebrate their work over the past year," said Maria Thomson, Director, Microsoft Intelligent Security Association. MISA was created to bring together Microsoft leaders, software development companies, and services partners to collaborate in defending against sophisticated security threats and making the world safer. MISA members and Microsoft security leaders will vote to determine this year's winners, providing an opportunity for peers to recognize exceptional contributions to shared customers. ## About ContraForce ContraForce is an AI-powered Security Delivery Platform built to help service providers deliver scalable MXDR and security outcomes across every customer they support. ContraForce operationalizes Microsoft Sentinel, Defender for Endpoint, Microsoft Entra ID, and Azure AI into a unified, multi-tenant platform that enables service providers to investigate, respond, and automate security faster and more cost effectively. The company's mission is to make enterprise-grade security accessible for all businesses through automation, AI, and Microsoft-native integrations. Learn more at [contraforce.com](https://www.contraforce.com). > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel to ContraForce > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy Defender for Endpoint integration > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Honored as a 2024 SC Awards Winner Source: https://docs.contraforce.com/blog/company/sc-awards-winner-2024 ContraForce was named a 2024 SC Awards winner. Its platform stood out for its approach to multi-tenant security operations and AI-driven automation. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **September 18, 2024** · ContraForce Team · 2 min read ContraForce is proud to announce that we have been honored as a winner in the 2024 SC Awards. The SC Awards are one of the most prestigious recognitions in the cybersecurity industry, celebrating the best solutions, services, and professionals who work to protect organizations from cyber threats. This recognition reflects ContraForce's commitment to innovation in security service delivery and our focus on helping MSPs and MSSPs scale their security operations effectively. "Being recognized as an SC Awards winner validates the hard work our team has put into building a platform that truly serves the needs of managed security service providers," said Stan Golubchik, CEO and Co-Founder of ContraForce. "We're honored to be recognized alongside so many innovative companies in the cybersecurity space." The SC Awards evaluate solutions across multiple criteria including innovation, customer satisfaction, and real-world impact. ContraForce's platform stood out for its unique approach to multi-tenant security operations and AI-driven automation. ## About ContraForce ContraForce is an AI-powered Security Delivery Platform built to help service providers deliver scalable MXDR and security outcomes across every customer they support. > **[Platform Overview](/overview)** > > Learn about the ContraForce platform > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore multi-tenant capabilities > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Completes Fourth Consecutive SOC 2 Type II Audit Source: https://docs.contraforce.com/blog/company/soc-2-type-ii-fourth-time ContraForce completed its fourth consecutive SOC 2 Type II audit, and its SOC 3 summary report is available for partners' compliance documentation. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **December 5, 2024** · ContraForce Team · 2 min read ContraForce is proud to announce the successful completion of our fourth consecutive SOC 2 Type II audit. This achievement demonstrates our continued commitment to maintaining the highest standards of security, availability, and confidentiality. SOC 2 Type II is a rigorous third-party audit that evaluates an organization's controls over an extended period, typically 6-12 months. Unlike a Type I audit, which evaluates controls at a specific point in time, Type II provides assurance that controls are not only designed properly but are also operating effectively over time. "Completing our fourth SOC 2 Type II audit reflects our unwavering commitment to security and trust," said Stan Golubchik, CEO and Co-Founder of ContraForce. "Our partners and their customers can be confident that ContraForce maintains the highest standards of operational security." ## Continuous Security Commitment This fourth successful completion demonstrates: * **Consistent excellence** — Four consecutive years of meeting SOC 2 Type II requirements * **Operational maturity** — Controls that work effectively day in and day out * **Partner confidence** — Assurance that data is protected by proven security practices ## About SOC 2 Type II The SOC 2 framework, developed by the American Institute of CPAs (AICPA), evaluates controls related to: * Security * Availability * Processing integrity * Confidentiality * Privacy ContraForce's SOC 3 report, which provides a summary of our SOC 2 Type II audit results, is available for partners who require it for their own compliance documentation. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Complete Cyber Insurance Buying Guide: Coverage to Claims Source: https://docs.contraforce.com/blog/complete-cyber-insurance-buying-guide Before you buy cyber insurance, see what it covers and excludes, how premiums are set, how to compare quotes, and how to file a claim to maximize recovery. > [!NOTE] > > **Who is this for?** Security Leaders, CISOs, MSP/MSSP Partners **February 27, 2026** · ContraForce Team · 6 min read Cyber insurance has gone from a niche product to a business necessity in just a few years. But buying the right policy is confusing, filing a claim is stressful, and too many organizations discover gaps in their coverage only after an incident. This guide covers the entire lifecycle — from understanding what cyber insurance actually covers to navigating the claims process when things go wrong. *** ## What Cyber Insurance Actually Covers Cyber insurance policies generally fall into two broad categories of coverage: first-party and third-party. **First-party coverage** protects your organization directly. This typically includes incident response costs (forensics, legal counsel, crisis communications), business interruption losses caused by a cyber event, data restoration expenses, ransomware payments and negotiation costs (where legally permitted), notification costs for informing affected individuals, and credit monitoring services for impacted customers or employees. **Third-party coverage** protects you against claims from others. This includes legal defense costs if you're sued after a breach, regulatory fines and penalties (where insurable by law), settlements or judgments from affected parties, and media liability related to data breaches. Some policies bundle both into a single package. Others are modular, letting you select coverage areas individually. The specifics vary significantly between carriers, which is why reading the actual policy language — not just the marketing summary — matters. ## What Cyber Insurance Typically Does Not Cover Understanding exclusions is just as important as understanding coverage. Common exclusions include: **Prior known incidents.** If you were aware of a vulnerability or breach before the policy period and didn't disclose it, the resulting claim will almost certainly be denied. **Failure to maintain minimum security standards.** Many policies include a "minimum security requirements" clause. If you represented that you had multi-factor authentication deployed but didn't, or claimed you patched critical vulnerabilities within 30 days but didn't, the carrier can deny the claim. **Nation-state attacks.** Some policies include a "war exclusion" or "hostile act" exclusion that can apply to cyberattacks attributed to foreign governments. This has been tested in court multiple times with inconsistent outcomes, making it one of the most contested areas in cyber insurance. **Infrastructure outages caused by third parties.** If your cloud provider has an outage that disrupts your business, your cyber policy may not cover the resulting losses unless you have specific "system failure" or "dependent business interruption" coverage. **Intentional or criminal acts by the insured.** If the breach was caused by an employee acting maliciously with the knowledge of management, coverage is typically excluded. **Improvements and upgrades.** Cyber insurance pays to restore you to your pre-incident state. It won't fund security upgrades, new tools, or improvements to your infrastructure — even if those improvements are desperately needed after the breach. ## How Premiums Are Calculated Insurers evaluate your organization across several dimensions to set your premium. Understanding these factors gives you leverage to reduce costs. **Industry and size** form the baseline. Healthcare, financial services, and retail tend to pay higher premiums due to the volume and sensitivity of the data they handle. Revenue and employee count further refine the estimate. **Security posture** is increasingly the biggest variable. Carriers now routinely assess whether you have multi-factor authentication across all remote access and privileged accounts, endpoint detection and response deployed on all devices, a tested incident response plan, regular employee security awareness training, immutable or air-gapped backups, a vulnerability management program with defined patching SLAs, and email authentication controls (DMARC, DKIM, SPF). Organizations that can demonstrate strong controls in these areas typically see significantly lower premiums. Those that can't may struggle to get coverage at all. **Claims history** matters. Prior incidents, especially recent ones, will increase your premium or narrow your coverage terms. **Coverage limits and deductibles** are the final lever. Higher limits cost more. Higher deductibles cost less. Most small and mid-sized businesses carry between $1M and $5M in coverage, though the right amount depends on your risk exposure. ## How to Buy Cyber Insurance: A Step-by-Step Process **Start with a broker who specializes in cyber.** General insurance brokers can place a cyber policy, but a specialist broker understands the nuances of policy language, knows which carriers are paying claims reliably, and can negotiate terms that a generalist won't think to ask for. Ask for references from companies in your industry. **Get your security house in order before applying.** The application process has become a security assessment in its own right. Carriers will ask detailed questions about your security controls, and your answers become representations — essentially warranties. If you overstate your security posture and later file a claim, the carrier can deny it based on material misrepresentation. Be honest, even if it means your premium is higher. **Compare at least three quotes.** Policies vary dramatically in coverage terms, exclusions, sub-limits, and retroactive dates. Don't compare on price alone. Look at the scope of incident response services included, whether the policy covers regulatory investigations, how "computer system" and "security failure" are defined, whether social engineering and funds transfer fraud are covered, and what the waiting period is for business interruption claims. **Negotiate the panel.** Most cyber policies include a pre-approved panel of breach counsel, forensics firms, and crisis communications agencies. If you already have relationships with specific providers, ask the carrier to add them to the panel. Using off-panel vendors can reduce or eliminate reimbursement. **Review the policy annually.** Your risk profile changes as your business grows, adopts new technology, enters new markets, or faces new regulatory requirements. An annual review ensures your coverage keeps pace. ## How to File a Claim and Maximize Your Recovery When an incident happens, the first 48 hours determine whether your claim succeeds or fails. Here's how to navigate it. **Notify your carrier immediately.** Most policies require notification within a specific timeframe — often 72 hours of discovering the incident. Late notification is one of the most common reasons claims are denied or reduced. When in doubt, notify early and provide details later. **Engage your breach counsel first.** Before you call your IT team, your PR agency, or your forensics firm, call the breach counsel on your policy's panel. Communications routed through legal counsel may be protected by attorney-client privilege, which can be critical if litigation follows. Your breach counsel will quarterback the entire response and ensure everything is documented properly for the claim. **Document everything.** Every cost, every decision, every communication should be recorded. Carriers require detailed documentation to process claims, and gaps in your records create gaps in your reimbursement. Keep receipts, invoices, time logs, and a running timeline of the incident and response. **Don't authorize major expenditures without carrier approval.** If you need to hire a forensics firm, engage a crisis communications agency, or make a ransomware payment, get your carrier's written approval first. Unauthorized expenses may not be reimbursed, even if they were reasonable and necessary. **Track business interruption losses carefully.** If your operations are disrupted, document the financial impact daily. Compare actual revenue to projected revenue using historical data. Track the costs of any temporary workarounds, overtime, or manual processes. Business interruption claims are often the largest component of a cyber insurance payout, and they require the most rigorous documentation. ## Red Flags That Your Policy May Not Protect You Review your current policy for these warning signs: A retroactive date that doesn't cover your full history with the carrier. If your retroactive date resets each year, incidents that began before the current policy period may not be covered. Sub-limits that are too low to be meaningful. A policy with a $5M aggregate limit but a $100K sub-limit on ransomware payments or business interruption doesn't provide the protection the headline number suggests. Vague definitions of "security failure" or "computer system" that could allow the carrier to argue your specific incident doesn't qualify. No coverage for dependent or contingent business interruption. If a vendor, supplier, or cloud provider is compromised and your business is disrupted as a result, you need this coverage. Exclusions for "failure to maintain" security controls without clearly defining what those controls are. *** ## Quick Summary * Cyber insurance is a critical layer of your risk management strategy, but it's not a substitute for strong security. * The best outcomes happen when your security program reduces the likelihood and impact of incidents, and your policy covers the residual risk that remains. * Buy thoughtfully, document relentlessly, and review your policy annually. *ContraForce helps organizations strengthen their security posture — which also happens to reduce your cyber insurance premiums. [Explore the ContraForce platform](https://www.contraforce.com).* > **[Meeting Cyber Insurance Requirements](/guides/contraforce-and-compliance/contraforce-and-cyber-insurance)** > > How ContraForce maps to common insurer requirements > **[Help Customers Lower Cyber Insurance Costs](/blog/outcomes-value/msp-cyber-insurance-costs)** > > Five ways MSPs can reduce customers' premiums > **[After the Breach](/blog/after-the-breach)** > > A recovery and communication plan for the days after an incident > **[Fourth SOC 2 Type II Audit](/blog/company/soc-2-type-ii-fourth-time)** > > How ContraForce documents its own security controls > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # How to Build a Cybersecurity Budget and Justify ROI Source: https://docs.contraforce.com/blog/how-to-build-a-cybersecurity-budget Build your cybersecurity budget step by step: assess risk, benchmark spend, set categories, calculate ROI with the ALE model, and present it to the board. > [!NOTE] > > **Who is this for?** Security Leaders, CISOs **February 27, 2026** · ContraForce Team · 5 min read When a breach costs the average organization millions in damages, lost revenue, and reputational harm, cybersecurity spending isn't optional — it's a business imperative. Yet for many security leaders, the hardest part isn't choosing the right tools. It's convincing the CFO and the board that the investment is worth it. This guide walks you through building a cybersecurity budget from scratch, calculating return on investment, and presenting a compelling business case to non-technical decision-makers. *** ## Why Cybersecurity Budgeting Is Different Unlike most business investments, cybersecurity ROI doesn't show up as revenue growth. It shows up as risk reduction — the breach that didn't happen, the downtime you avoided, the regulatory fine you never paid. That makes it harder to quantify, but not impossible. The key shift is framing cybersecurity as risk management rather than a cost center. Every dollar you spend should map to a specific risk you're reducing, and that risk should be expressed in language your board already understands: financial exposure, operational disruption, and regulatory liability. ## Step 1: Assess Your Current Risk Exposure Before you can build a budget, you need to understand what you're protecting and what happens if you fail. Start by cataloging your organization's critical assets: customer data, intellectual property, financial systems, operational technology, and employee records. For each asset category, estimate the financial impact of a compromise. Consider direct costs like incident response, legal fees, and regulatory fines. Factor in indirect costs like business interruption, customer churn, and reputational damage. Industry benchmarks can help here — IBM's annual Cost of a Data Breach Report provides median costs segmented by industry, company size, and breach type. Document your current security controls alongside each asset. Where you have gaps, you have risk. Where you have risk, you need budget. ## Step 2: Benchmark Against Your Industry Cybersecurity spending varies significantly by industry, company size, and regulatory environment. As a starting point, most industry analysts recommend allocating between 5% and 15% of total IT budget to cybersecurity, with regulated industries (healthcare, finance, defense contractors) trending toward the higher end. However, benchmarks are just that — benchmarks. A 200-person manufacturing company with operational technology exposure has a very different risk profile than a 200-person SaaS company. Use benchmarks to sanity-check your budget, not to set it. Key benchmarking sources include Gartner's annual IT spending forecasts, the SANS Institute's security spending surveys, and Deloitte's CISO survey data. Your cyber insurance carrier may also provide industry-specific guidance. ## Step 3: Build Your Budget by Category A well-structured cybersecurity budget typically breaks down into five categories: **Prevention and protection** covers endpoint protection, firewalls, email security, identity and access management, vulnerability management, and patch management. This is your first line of defense and usually accounts for the largest share of spending. **Detection and response** includes security monitoring (SIEM or MDR), threat intelligence feeds, incident response retainers, and forensics capabilities. If you're outsourcing to a managed detection and response provider, this line item may consolidate several sub-categories. **People and training** encompasses security team salaries, security awareness training for all employees, certifications, and any outsourced security operations (vCISO, managed SOC). For smaller organizations without a dedicated security team, this category might be entirely outsourced. **Compliance and governance** covers audit preparation, compliance tooling, policy development, penetration testing, and risk assessments. If your organization is subject to frameworks like HIPAA, PCI DSS, SOC 2, or CMMC, budget here tends to be non-negotiable. **Business continuity and recovery** includes backup and disaster recovery solutions, cyber insurance premiums, tabletop exercises, and incident response plan development. ## Step 4: Calculate ROI Using the Risk Reduction Model The most effective way to calculate cybersecurity ROI is the Annualized Loss Expectancy (ALE) model. It works like this: First, estimate the Single Loss Expectancy (SLE) — how much a single security incident would cost your organization. Use your risk assessment from Step 1 and industry breach cost data to arrive at a realistic number. Next, estimate the Annualized Rate of Occurrence (ARO) — how likely that incident is to happen in a given year. Threat intelligence data, your industry's breach frequency, and your current security posture all inform this number. Multiply SLE by ARO to get your Annualized Loss Expectancy. This is the expected cost of doing nothing. Now compare that number to the cost of the security investment that would reduce that risk. If a $150,000 MDR deployment reduces your expected annual loss from $800,000 to $200,000, you've generated $450,000 in risk-adjusted value — a 3x return. Present this calculation for each major risk area, and your board has a clear, financially grounded picture of why the budget matters. ## Step 5: Present It in Language Your Board Speaks Technical jargon kills budget requests. Your board doesn't need to understand the difference between EDR and XDR. They need to understand three things: what's the risk, what does the investment cost, and what happens if we don't invest. Structure your presentation around these elements: **The threat landscape** in two minutes or less. Use one or two statistics relevant to your industry. Keep it brief and alarming without being alarmist. **Your current exposure** expressed as financial risk. "We currently have \$4.2M in unmitigated cyber risk based on our assessment" is more compelling than a list of missing controls. **The proposed budget** tied to specific risk reductions. Each line item should answer the question "what risk does this eliminate or reduce?" **The cost of inaction** compared to the cost of investment. If your ALE exceeds your proposed budget, the math makes the case for you. **A phased approach** if the full budget is too large to approve at once. Prioritize the investments that address the highest-risk gaps first and propose a multi-year roadmap. ## Step 6: Track and Report on Effectiveness Once your budget is approved, your job isn't done. Boards expect to see that the money was well spent. Establish key performance indicators that demonstrate the value of your security program over time. Useful KPIs include mean time to detect and respond to threats, number of incidents prevented or contained, reduction in vulnerability exposure over time, employee phishing simulation click rates, and audit or compliance findings resolved. Report on these quarterly, and tie improvements directly back to the investments that enabled them. This builds credibility for future budget requests and keeps cybersecurity visible at the board level. *** ## Quick Summary * Cybersecurity budgeting isn't about buying tools — it's about managing business risk with financial discipline. * Map every dollar to a risk and express that risk in financial terms. * Present the investment as what it is: protection of revenue, reputation, and operational continuity. * When you speak the board's language, the budget conversation gets much easier. *ContraForce helps organizations build and operate security programs that deliver measurable results. [Explore the ContraForce platform](https://www.contraforce.com).* > **[How to Build a Cybersecurity Stack](/blog/how-to-build-your-cybersecurity-stack)** > > Choose the tools your budget should cover first > **[Cyber Insurance Buying Guide](/blog/complete-cyber-insurance-buying-guide)** > > What a policy covers and how premiums are set > **[Scaling Security Delivery](/blog/outcomes-value/scale-security-delivery)** > > Grow coverage without a matching rise in headcount > **[Incident Report](/guides/getting-started/incident-report)** > > Share closed-incident results with customers and leadership > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # How to Build a Cybersecurity Stack for Small Businesses Source: https://docs.contraforce.com/blog/how-to-build-your-cybersecurity-stack Plan a cybersecurity stack for your small or mid-sized business: the tools you need, how to vet vendors, what to ask in demos, and what to build first. > [!NOTE] > > **Who is this for?** Security Leaders, CISOs, MSP/MSSP Partners **February 27, 2026** · ContraForce Team · 10 min read Every cybersecurity vendor will tell you their platform is the one you need. This guide takes a different approach. Instead of pitching products, it walks you through the categories of security tools your organization actually needs, how to evaluate vendors in each category, what questions to ask in demos, and how to build a stack that works together — all without telling you which brand to buy. *** ## Why "Best of Breed" vs. "Platform" Is the Wrong Starting Question The cybersecurity industry loves this debate: should you pick the best individual tool in each category, or consolidate onto a single platform? The honest answer is that it depends entirely on your team's size, skills, and capacity to manage multiple tools. A 5,000-person company with a 15-person security team can manage and integrate best-of-breed tools across categories. A 200-person company with one IT generalist who also handles security cannot — and shouldn't try. For most SMBs, fewer tools that work well together will outperform a collection of best-in-class products that nobody has time to configure, tune, or monitor. Start with your team's operational capacity, not with a product comparison spreadsheet. ## The Core Categories Every Organization Needs Regardless of your size or industry, your security stack needs to cover these fundamental areas. You don't need a separate tool for each one — many products span multiple categories — but you need coverage in all of them. ### 1. Endpoint Protection **What it does:** Protects laptops, desktops, servers, and mobile devices from malware, ransomware, and other threats. Modern endpoint protection goes beyond traditional antivirus to include behavioral detection, machine learning-based analysis, and automated response capabilities. **What to look for:** Detection capabilities that go beyond signature-based matching, automated response actions (isolate a compromised device, kill a malicious process), integration with your operating systems and device management tools, a cloud-based management console that doesn't require on-premises infrastructure, and clear reporting that shows you what's being blocked and why. **Questions to ask vendors:** What's your detection rate for novel (zero-day) threats, and how is that measured? How does the agent perform on older or lower-powered hardware? What happens when a device is offline — does protection continue? How are false positives handled, and what's the typical false positive rate your customers see? Can your tool integrate with our existing device management or IT ticketing system? **Common mistakes:** Deploying endpoint protection but never reviewing the alerts it generates. An endpoint tool that fires 200 alerts a day and nobody triages them is providing a false sense of security. If you don't have the staff to monitor alerts, pair your endpoint tool with a managed detection and response service. ### 2. Identity and Access Management **What it does:** Controls who can access what across your organization. This includes single sign-on (SSO), multi-factor authentication (MFA), directory services, privileged access management, and lifecycle management (onboarding and offboarding users). **What to look for:** Support for MFA across all applications, not just some. Phishing-resistant MFA methods (hardware keys, passkeys) in addition to push notifications and SMS. Integration with your existing directory (Active Directory, Microsoft Entra ID, Google Workspace). Automated provisioning and deprovisioning tied to your HR system or onboarding process. Clear audit logs showing who accessed what and when. **Questions to ask vendors:** How do you handle MFA for legacy applications that don't natively support it? What's the user experience for employees — how many extra clicks or steps does authentication add? How quickly can we deprovision access when someone leaves the organization? Do you support conditional access policies (different requirements based on location, device, risk level)? What happens if the MFA service itself goes down — is there a secure fallback? **Common mistakes:** Deploying MFA for email and VPN but not for cloud applications, admin consoles, or remote desktop. Attackers will find and exploit the gaps. Also, failing to revoke access promptly when employees leave — orphaned accounts are one of the most common attack vectors in SMB breaches. ### 3. Email Security **What it does:** Protects your organization from phishing, business email compromise (BEC), malware delivered via email, and spam. Email remains the number one attack vector, making this category non-negotiable. **What to look for:** Inbound filtering that catches phishing, malware, and impersonation attempts. Protection against business email compromise, including detection of display name spoofing, look-alike domains, and vendor impersonation. URL rewriting and time-of-click analysis (checking links when the user clicks, not just when the email arrives). DMARC, DKIM, and SPF configuration and monitoring to prevent spoofing of your own domain. Outbound DLP (data loss prevention) to catch sensitive data leaving via email. **Questions to ask vendors:** How do you detect BEC attempts that don't contain malware or malicious links — pure social engineering? Can you show me examples of phishing emails your product caught that native Microsoft or Google security missed? How do you handle encrypted attachments? What's your approach to quarantine — who reviews quarantined messages and how quickly can legitimate emails be released? Do you provide any user-facing tools (report phishing button, real-time warnings on suspicious emails)? **Common mistakes:** Relying solely on the built-in security features of Microsoft 365 or Google Workspace. These provide a baseline, but dedicated email security solutions consistently catch threats that native controls miss — particularly sophisticated BEC and targeted phishing. ### 4. Backup and Recovery **What it does:** Ensures you can restore your data and systems after a ransomware attack, accidental deletion, hardware failure, or any other destructive event. **What to look for:** Automated, regular backups of all critical data and systems. At least one copy that is immutable (cannot be modified or deleted, even by an administrator) or air-gapped (physically or logically separated from your production network). Tested restoration capabilities — not just backup jobs that complete, but confirmed ability to restore data and bring systems back online. Granular recovery (restore a single file, mailbox, or database) in addition to full system recovery. Clear recovery time objectives (RTO) and recovery point objectives (RPO) that match your business requirements. **Questions to ask vendors:** How are backups protected from ransomware that specifically targets backup systems? Can you demonstrate a full system restore? How long does it take? What's the retention policy, and can we customize it? Are backups encrypted in transit and at rest? If your backup service goes down, can we still access our backup data? **Common mistakes:** Having backups but never testing restoration. The time to discover that your backups are corrupted, incomplete, or too slow to restore is not during a ransomware incident. Test quarterly at minimum. ### 5. Security Monitoring and Detection **What it does:** Watches your environment for suspicious activity, correlates events across multiple data sources, and alerts you (or responds automatically) when something looks wrong. **What to look for:** For most SMBs, this means either a SIEM (Security Information and Event Management) system or a managed detection and response (MDR) service — or both. The critical question is whether you have staff to monitor and respond to alerts 24/7. If you do, a SIEM with well-tuned detection rules may work. If you don't — and most SMBs don't — an MDR service provides the security operations center (SOC) capability you need without building one in-house. Look for coverage across your key data sources: endpoint, identity/authentication, email, cloud, and network. Correlation capabilities that connect related events into a coherent picture rather than firing isolated alerts. Low noise — the ratio of actionable alerts to false positives matters more than the total number of detections. And clear escalation and response procedures, whether that's your internal team acting on alerts or a managed service taking response actions on your behalf. **Questions to ask vendors:** What data sources do you ingest, and what's the cost model (per device, per GB, flat rate)? What's your median time to detect a real threat in your customer base? If you're an MDR provider, what response actions can you take on my behalf — and what requires my approval first? How do you handle after-hours alerts? Can you show me an example of a real incident you detected and resolved for a customer similar to us? **Common mistakes:** Buying a SIEM and expecting it to work out of the box. SIEMs require significant tuning, rule development, and ongoing maintenance to be effective. If you don't have a security analyst to manage it, the SIEM becomes an expensive log storage system. ### 6. Vulnerability Management **What it does:** Identifies known vulnerabilities in your systems, applications, and infrastructure so you can patch or mitigate them before attackers exploit them. **What to look for:** Automated scanning of internal and external assets on a regular cadence. Accurate asset discovery — you can't patch what you don't know about. Risk-based prioritization that accounts for exploitability, exposure, and business context, not just CVSS scores. Integration with your patch management or IT operations workflow. Reporting that helps you track remediation progress over time. **Questions to ask vendors:** How do you prioritize vulnerabilities — is it just CVSS score, or do you factor in real-world exploitability and asset criticality? How do you handle assets that can't be patched (legacy systems, OT devices)? What's the false positive rate on your scans? Can you integrate with our ticketing system to automatically create remediation tasks? How do you handle cloud assets and containers? **Common mistakes:** Running vulnerability scans but not acting on the results. A scan that identifies 500 vulnerabilities is useless if nobody triages, prioritizes, and remediates them. Pair your scanning tool with a clear remediation workflow and SLAs. ### 7. Security Awareness Training **What it does:** Educates your employees to recognize and report phishing attempts, social engineering, and other threats that target human behavior rather than technology. **What to look for:** Engaging, regularly updated content that reflects current threats — not annual compliance videos from five years ago. Simulated phishing campaigns that test employees with realistic scenarios and provide immediate feedback. Reporting that identifies high-risk individuals and departments. Short, frequent training modules (5 to 10 minutes monthly) rather than annual hour-long sessions. Content that's available in the languages your workforce needs. **Questions to ask vendors:** How often is your content library updated? Can you customize phishing simulations to mimic the specific threats our industry faces? What happens when an employee fails a simulation — is the follow-up training automatic? Do you provide metrics we can report to leadership (click rates over time, reporting rates, training completion)? Can the platform integrate with our email security tool so reported phishing goes to the right place? **Common mistakes:** Treating security awareness as a check-the-box compliance exercise. The goal isn't 100% training completion — it's measurable behavior change. Track phishing simulation click rates, reporting rates, and time-to-report over time. ## How to Evaluate Vendors: A Practical Framework When comparing products in any category, evaluate across five dimensions: **Effectiveness** is the most important and hardest to assess. Ask for third-party test results (AV-TEST, MITRE ATT\&CK evaluations, SE Labs), customer references in your industry, and proof-of-concept trials in your environment. Marketing claims are not evidence. **Operational fit** means the tool works with your team's skills, your existing infrastructure, and your operational cadence. A powerful tool that requires a dedicated full-time analyst to operate is the wrong tool for a team of two. **Integration** determines whether the tool plays well with the rest of your stack. Ask specifically about API availability, pre-built integrations with tools you already use, and data export capabilities. Siloed tools that don't share data create blind spots. **Total cost of ownership** goes beyond the license fee. Factor in implementation time, training, ongoing management effort, and any infrastructure requirements. A tool that costs $10,000 per year but requires $30,000 in staff time to operate costs \$40,000. **Vendor viability** matters because you're entering a relationship, not making a one-time purchase. Assess the vendor's financial stability, customer retention rates, product roadmap, and support quality. A startup with a great product that goes out of business in two years leaves you rebuilding. ## What Order to Build In If you're starting from scratch, build in this order. Each layer provides the foundation for the next. **First**, deploy MFA everywhere and get your identity and access management under control. Identity compromise is the leading attack vector, and no other security investment matters if attackers can log in with stolen credentials. **Second**, deploy endpoint protection across all devices. This gives you visibility into your most common attack surface and the ability to contain threats at the device level. **Third**, implement email security beyond your native provider's built-in protections. This addresses the most common delivery mechanism for phishing and malware. **Fourth**, establish backup and recovery with at least one immutable or air-gapped copy. This is your safety net for when everything else fails. **Fifth**, add security monitoring — either a managed service or, if you have the staff, a SIEM — to gain visibility across your environment and detect threats that bypass your preventive controls. **Sixth**, implement vulnerability management to systematically identify and remediate weaknesses before attackers find them. **Seventh**, launch security awareness training to address the human element that technology alone can't solve. This order isn't rigid — your specific risk profile may shift priorities. But for most SMBs, it represents the highest-impact sequence. *** ## Quick Summary * Building a cybersecurity stack isn't about buying the most expensive tools or checking the most boxes. * Cover the fundamentals well, choose tools that match your team's capacity, and make sure everything works together. * Start with identity, build outward, and never deploy a tool you don't have the capacity to operate. *ContraForce provides a unified security operations platform that integrates across your existing stack. [Explore the ContraForce platform](https://www.contraforce.com).* > **[How to Build a Cybersecurity Budget](/blog/how-to-build-a-cybersecurity-budget)** > > Fund the stack and justify ROI to your board > **[SIEM Market Consolidation](/blog/agentic-ai/siem-vendor-landscape)** > > What SIEM and XDR convergence means for your choices > **[How to Become an MSSP](/blog/agentic-ai/mssp-essential-features)** > > Seven capabilities managed security providers need > **[ContraForce Documentation](/overview)** > > See how ContraForce works with Microsoft Sentinel and Defender > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Blog: Agentic AI, Managed Security, and Product News Source: https://docs.contraforce.com/blog/index Read the ContraForce blog for product announcements, agentic AI thought leadership, MSP and MSSP outcome stories, and company awards and partnerships. ## Product Announcements The latest features, modules, and platform capabilities shipping to ContraForce partners. > **[Operating Procedures](/blog/product-announcements/sop-knowledge-base)** > > Upload your operating procedures and link them to Security Delivery Agents > **[The ContraForce Security Delivery Platform](/blog/product-announcements/security-delivery-platform-launch)** > > A new operating model for managed security delivery > **[Introducing Security Delivery Agents](/blog/product-announcements/security-delivery-agents)** > > AI agents that automate incident investigation and response at scale > **[Incident Investigation Improvements](/blog/product-announcements/incident-investigation-improvements)** > > Enhanced investigation for Microsoft Sentinel and Defender for Endpoint > **[Multi-Platform SIEM/XDR Support](/blog/product-announcements/siem-xdr-platform-support)** > > Support for Splunk, CrowdStrike Falcon XDR, and IBM QRadar > **[Detection Content Management](/blog/product-announcements/detection-content-management)** > > A better way to manage detection content across workspaces > **[Gamebook Automation and Mapping](/blog/product-announcements/gamebook-automation-mapping)** > > Improved incident response efficacy with automation > **[Global Hosting Regions](/blog/product-announcements/global-hosting-regions)** > > Platform hosted in more regions worldwide > **[Autotask PSA Integration](/blog/product-announcements/autotask-psa-integration)** > > Streamline case management with Datto Autotask ## Outcomes & Value How service providers are transforming security delivery — real metrics, real operational impact. > **[Scaling Security Delivery](/blog/outcomes-value/scale-security-delivery)** > > How to manage more customers without hiring more analysts > **[Reduce Cyber Insurance Costs](/blog/outcomes-value/msp-cyber-insurance-costs)** > > 5 ways to help customers lower their cyber insurance premiums ## Agentic AI & Security Thought leadership on autonomous AI agents in cybersecurity and what it means for service providers. > **[What Are Security Delivery Agents?](/blog/agentic-ai/what-are-security-delivery-agents)** > > Understanding agentic AI in security operations > **[10 Ways ContraForce Automates Multi-Tenant Management](/blog/agentic-ai/10-ways-multi-tenant-automation)** > > Unique multi-tenant automation for Microsoft Sentinel and Defender > **[Security Delivery Platforms: Reimagining Security](/blog/agentic-ai/security-delivery-platform-reimagining)** > > How Security Delivery Platforms transform managed security > **[CISA SIEM/SOAR Guidance for MSSPs](/blog/agentic-ai/cisa-siem-soar-guidance)** > > Implementing new CISA guidance with ContraForce > **[The SIEM Landscape Is Changing](/blog/agentic-ai/siem-vendor-landscape)** > > What market changes mean for MDR providers > **[7 Essential MSSP Features](/blog/agentic-ai/mssp-essential-features)** > > Essential capabilities to become a successful MSSP ## Company & Ecosystem Awards, partnerships, certifications, and milestones from the ContraForce team. > **[Microsoft Security Excellence Finalist](/blog/company/microsoft-security-excellence-finalist)** > > Recognized for Security Software Development Company > **[CyberSecurity Breakthrough Awards 2025](/blog/company/cybersecurity-breakthrough-awards-2025)** > > Named Security Orchestration Solution of the Year > **[SC Awards Winner 2024](/blog/company/sc-awards-winner-2024)** > > Honored in the 2024 SC Awards program > **[Microsoft Pegasus Program](/blog/company/microsoft-pegasus-program)** > > Selected for Microsoft for Startups Pegasus > **[SOC 2 Type II (Fourth Time)](/blog/company/soc-2-type-ii-fourth-time)** > > Fourth consecutive SOC 2 Type II completion > **[Ingram Micro Distribution Agreement](/blog/company/ingram-micro-distribution)** > > New US distribution partnership with Ingram Micro ## Industry Intelligence Vendor-neutral guides on cyber insurance, security budgets, breach recovery, and building a security stack. > **[Cyber Insurance Buying Guide](/blog/complete-cyber-insurance-buying-guide)** > > What a policy covers, how premiums are set, and how to file a claim > **[How to Build a Cybersecurity Budget](/blog/how-to-build-a-cybersecurity-budget)** > > Build a budget and justify ROI to your board > **[After the Breach](/blog/after-the-breach)** > > A recovery and communication plan for the days after an incident > **[How to Build a Cybersecurity Stack](/blog/how-to-build-your-cybersecurity-stack)** > > A vendor-neutral guide for small and mid-sized businesses > [!NOTE] > > Questions or feedback? Reach us at [support@contraforce.com](mailto:support@contraforce.com). # 5 Ways MSPs Can Help Customers Lower Cyber Insurance Costs Source: https://docs.contraforce.com/blog/outcomes-value/msp-cyber-insurance-costs See 5 ways MSPs using ContraForce can help customers lower cyber insurance costs, from faster threat response to incident documentation and SOC services. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners **July 2, 2025** · ContraForce Team · 4 min read ## The Situation In recent years, companies purchasing cyber insurance have faced a rapidly evolving landscape marked by rising premiums, stricter underwriting requirements, and increased scrutiny of cybersecurity practices. Insurers are now demanding detailed evidence of risk mitigation efforts – such as the existence of threat detection and response capabilities – before issuing or renewing policies. Coverage limits have tightened, and exclusions for certain types of attacks, like ransomware, have become more common. As a result, businesses are increasingly focused on strengthening their security posture not only to reduce the likelihood of a breach but also to qualify for more favorable insurance terms and lower premiums. This shift has made cybersecurity a strategic priority as part of a company's risk management and financial planning. ## MSPs Can Play a Critical Role MSPs (Managed Service Providers) can play a critical role in helping companies navigate the evolving cyber insurance landscape. By delivering robust, managed security services, MSPs can help their clients meet insurers' stricter requirements—such as threat detection and response capabilities. MSPs can also provide documentation and reporting that demonstrate a strong security posture, which is often required during the underwriting process. Furthermore, they can help businesses rapidly respond to threats and reduce dwell time, a key factor insurers consider when assessing risk. Ultimately, by partnering with an MSP, companies can not only improve their chances of obtaining cyber insurance but also potentially reduce premiums and avoid policy exclusions through measurable, ongoing risk reduction. ## ContraForce Helps MSPs ContraForce can help Managed Service Providers (MSPs) reduce their customers' cyber insurance costs by improving their cybersecurity posture and demonstrating measurable security controls. Here's how: ## 1. Centralized Security Posture Management ContraForce aggregates and normalizes security data from various endpoint and SIEM tools, with SIEM tools themselves collecting data from many security data sources, giving MSPs a unified view of a customer's security landscape. This makes it easier to: * Identify and remediate security incidents faster * Show continuous compliance with security frameworks like NIST, CIS, and ISO 27001 * Provide evidence of risk mitigation strategies during insurance underwriting or renewal processes ## 2. Real-Time Threat Detection and Response ContraForce enables rapid detection and response across Microsoft Defender, Microsoft Sentinel, and other integrated tools. Insurance providers favor businesses that: * Can detect and contain breaches quickly * Use automated response workflows to limit damage * Maintain audit logs and incident documentation These capabilities lower the perceived risk, which insurers consider when calculating premiums. ## 3. Demonstrable Risk Reduction ContraForce quantifies improvements in risk posture over time, for example fewer active threats. MSPs can report on these results for their customers so they can: * Proactively communicate security maturity to insurance underwriters * Justify reduced premiums or qualify for better coverage terms ## 4. Compliance Mapping and Reporting Cyber insurance providers often require evidence of controls like endpoint detection and response (EDR) tools. ContraForce helps MSPs: * Continuously monitor for gaps in required controls * Generate compliance-ready reports for policy applications or audits ## 5. Cost-Effective, Scalable SOC Services By delivering SOC-as-a-Service capabilities through ContraForce, MSPs can offer enterprise-grade security to small and mid-sized businesses (SMBs) without them having to build their own SOC. This enhances their customers' security profile at a fraction of the cost. Having SOC capabilities can positively influence insurance rates for SMBs. ## Lower Insurance Costs As a result of outsourcing security services to an MSP powered by ContraForce, customers can lower their cyber insurance costs by demonstrating: **Enhanced visibility and response** — Real-time visibility into threats and faster incident response significantly reduce the likelihood and severity of breaches. Insurers recognize this as a strong indicator of lower risk, which can lead to better premiums and policy terms. This is especially true when it comes to ransomware. Breaches are a precursor to ransomware. By reducing the likelihood of breaches, organizations can mitigate their ransomware exposure and materially influence their premiums. **Compliance and reporting** — Compliance tracking ensures critical security controls are continuously monitored and documented. This makes it easier to prove compliance with insurer requirements, reducing the underwriting burden and potentially qualifying the business for discounts. **Quantifiable and demonstrated cyber risk reduction** — By showing measurable improvements – like increased control coverage, and a reduction in active threats – companies can demonstrate lower risk to insurers. This data-driven approach helps justify lower premiums and improved coverage. **Meeting insurer-required controls more effectively** — Insurers often mandate specific security measures (e.g., endpoint protection). Ensuring these controls are properly implemented and maintained, reducing the chance of coverage denials or surcharges. For customers working with MSPs who use ContraForce, these measures should lead to lower risk, fewer incidents, reduced claims and lower cyber insurance costs. ## Quick Summary * Cyber insurance underwriting now requires evidence of threat detection and response capabilities. * MSPs can help customers meet these requirements through ContraForce-powered security services. * Five key capabilities: centralized posture management, real-time detection, demonstrable risk reduction, compliance reporting, and scalable SOC services. * ContraForce provides documentation and metrics that support insurance applications and renewals. * The result: lower premiums, better coverage terms, and reduced policy exclusions for customers. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > **[Incident Management](/guides/getting-started/incident-management)** > > Learn about incident workflows > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Scaling Security Delivery Without Scaling Headcount Source: https://docs.contraforce.com/blog/outcomes-value/scale-security-delivery See how MSPs and MSSPs use Security Delivery Agents, Gamebooks, and the Command Dashboard to cover more customers without a matching rise in headcount. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners and Security Team Leadership **February 2026** · ContraForce Team · 5 min read The economics of managed security have always been challenging: more customers means more incidents, and more incidents means more analysts. ContraForce breaks this pattern by automating the work that used to require human attention at every step. ## The Scaling Problem Traditional security operations scale linearly. Add 10 new customers, and you need proportionally more analyst capacity to handle their incidents. This creates a ceiling on growth — you can only expand as fast as you can hire and train. The bottleneck isn't technology. It's the manual work between detection and resolution: triaging alerts, gathering context, investigating entities, executing response actions, and documenting outcomes. ## How ContraForce Changes the Math ContraForce automates each stage of the incident lifecycle: | Stage | Traditional Approach | ContraForce Approach | | - | - | - | | **Triage** | Analyst reviews each alert manually | Security Delivery Agents analyze automatically | | **Context Gathering** | Analyst queries multiple tools | Entity Insights aggregate sign-in logs, device timelines, and threat intel | | **Investigation** | Analyst correlates data across systems | Agents correlate related incidents and entity activity | | **Response** | Analyst executes actions in each tenant | Gamebooks execute consistent response actions across workspaces | | **Documentation** | Analyst writes incident notes | Agents document findings and actions automatically | ## Multi-Tenant Operations at Scale Managing security across dozens or hundreds of customer workspaces introduces complexity that compounds the scaling problem. ContraForce addresses this directly: * **Command Dashboard** provides a unified view of incidents across all workspaces — no switching between customer portals * **Workspace filters** persist across pages, letting you focus on specific customers without reconfiguring views * **Gamebooks** execute the same response actions consistently across every workspace * **Security Delivery Agents** operate across your entire customer base from a single deployment ## Operational Efficiency in Practice Service providers using ContraForce report measurable operational improvements: * **Incident triage time** drops from minutes to seconds with automated agent analysis * **Response consistency** improves because Gamebooks enforce standardized workflows * **Analyst capacity** increases as routine investigation work shifts to agents * **Customer coverage** expands without proportional team growth ## The Role of Automation Automation doesn't replace your analysts — it amplifies them. SDAs handle the repetitive investigation work while your team focuses on complex incidents, customer relationships, and strategic improvements. The goal isn't fewer people. It's more customers served at higher quality without burning out your team. ## Quick Summary * Traditional security operations scale linearly with headcount * ContraForce automates triage, context gathering, investigation, response, and documentation * Multi-tenant features eliminate the overhead of managing separate customer environments * Security Delivery Agents handle routine work so analysts focus on high-value activities * Service providers scale customer coverage without proportional team growth > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Unified incident visibility across all customer workspaces > **[What Are Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Automated response workflows for consistent security operations > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Datto Autotask PSA Integration Improves Case Management Source: https://docs.contraforce.com/blog/product-announcements/autotask-psa-integration Connect Datto Autotask PSA to ContraForce to create Autotask tickets for security incidents and track your security case work in the PSA you already use. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners **April 29, 2024** · ContraForce Team · 2 min read ContraForce is pleased to announce our integration with Datto Autotask PSA, enabling MSPs to streamline their security case management workflows. ## Unified Case Management Many MSPs use Autotask PSA as their central ticketing system. This integration allows you to: * **Create tickets automatically** — Security incidents in ContraForce create corresponding tickets in Autotask * **Sync status updates** — Changes in ContraForce reflect in Autotask and vice versa * **Maintain single source of truth** — All work tracked in your existing PSA ## How It Works 1. Configure the Autotask integration in ContraForce workspace settings 2. Map incident severities to Autotask priority levels 3. Define which incident types should create tickets 4. Enable automatic ticket creation When a security incident is processed in ContraForce, a corresponding ticket is created in Autotask with: * Incident summary and details * Affected customer information * Link back to ContraForce for investigation * Severity-appropriate priority level ## Benefits for MSPs | Benefit | Description | | - | - | | **Reduced duplication** | No need to manually create tickets | | **Improved tracking** | All security work visible in PSA | | **Consistent workflows** | Same process for all incident types | | **Better reporting** | Security metrics in your existing reports | ## Getting Started The Autotask integration is available now for all ContraForce partners: 1. Navigate to workspace integrations 2. Select Datto Autotask PSA 3. Complete the authorization flow 4. Configure ticket creation rules ## Quick Summary * ContraForce now integrates with Datto Autotask PSA for streamlined case management. * Security incidents automatically create corresponding tickets in Autotask. * Status updates sync bidirectionally between ContraForce and Autotask. * MSPs get unified tracking, consistent workflows, and security metrics in their existing PSA reports. > **[Notifications Module](/guides/onboarding/notifications-module)** > > Configure notification settings > **[Incident Management](/guides/getting-started/incident-management)** > > Learn about incident workflows > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # A Better Way to Manage Microsoft Sentinel Detection Content Source: https://docs.contraforce.com/blog/product-announcements/detection-content-management Deploy and roll back detection rules across customer Microsoft Sentinel workspaces in bulk, a capability that now lives in the Content Management Center. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Engineers > [!NOTE] > > Cross-workspace rule deployment, versioning, and drift detection now live in the [Content Management Center](/guides/content-management-center/overview). The in-workspace Detection Rules page is the [Content Management System](/guides/getting-started/content-management-system). **October 16, 2024** · ContraForce Team · 3 min read ContraForce is excited to announce significant improvements to how service providers manage detection content across their customer Microsoft Sentinel workspaces. ## The Challenge of Detection Content at Scale Managing detection rules across dozens or hundreds of customer Sentinel workspaces presents significant challenges: * **Inconsistent coverage** — Different rules enabled in different workspaces * **Manual deployment** — Time-consuming process to deploy or update rules * **No centralized visibility** — Difficult to see what's deployed where * **Change management overhead** — Tracking which customers have which versions ## Introducing ContraForce CMS The ContraForce Content Management System (CMS) provides a toggle-based interface for deploying and managing detection rules across all your customer Sentinel workspaces: ## Centralized Rule Management * View all available detection rules in a single dashboard * See deployment status across all customer workspaces * Toggle rules on or off for individual or multiple customers ## Curated Detection Library * Access ContraForce's curated library of detection rules * Rules optimized for common threat scenarios * Regular updates as new threats emerge ## Bulk Operations * Deploy rules to multiple workspaces simultaneously * Update rule configurations across your entire customer base * Roll back changes if needed ## How It Works 1. Navigate to the CMS module in your ContraForce workspace 2. Browse available detection rules 3. Select target customer workspaces 4. Toggle rules on to deploy Rules are deployed directly to customer Sentinel workspaces, ensuring they run natively within Microsoft's infrastructure. ## Quick Summary * Centralize management of detection rules across all customer Microsoft Sentinel workspaces. * Use a toggle-based CMS interface to deploy, update, and roll back rules at scale. * Leverage a curated, regularly updated library of ContraForce detection content. * Perform bulk operations to keep coverage consistent and reduce manual change management. > **[CMS Module Setup](/guides/content-management-center/overview)** > > Deploy the Content Management System > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Gamebook Automation and Mapping for Faster Incident Response Source: https://docs.contraforce.com/blog/product-announcements/gamebook-automation-mapping Incidents map to the right Gamebook automatically by type and severity. Choose how much of the response is automated and see every action before it runs. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, SOC Analysts **October 15, 2024** · ContraForce Team · 3 min read ContraForce is pleased to announce enhanced Gamebook automation and mapping capabilities, designed to improve incident response efficacy across your customer workspaces. ## What Are Gamebooks? Gamebooks are ContraForce's incident response workflows guided by your operating procedures. They guide analysts through investigation and response steps, ensuring consistent outcomes regardless of who is handling the incident. ## Automated Gamebook Mapping ContraForce now automatically maps incidents to the appropriate Gamebook based on incident type, severity, and other characteristics. This means: * **Faster time to action** — No manual Gamebook selection required * **Consistent response** — Same incident types handled the same way * **Reduced training burden** — Analysts don't need to memorize which Gamebook to use ## Enhanced Automation Modes Gamebooks now support three automation levels: | Mode | Behavior | | - | - | | **Manual** | Analyst reviews and approves each step | | **Automatic** | Steps execute automatically with analyst supervision | | **Autonomous** | Full automation with minimal analyst involvement | ## Improved Action Visibility * See exactly which actions will be taken before execution * Clear indicators for reversible vs. irreversible actions * Detailed logs of all actions taken ## Getting Started Gamebook automation is available now in all ContraForce workspaces: 1. Navigate to workspace settings 2. Configure Gamebook automation preferences 3. Set default automation levels per incident type 4. Monitor automated actions in the activity log ## Quick Summary * Gamebooks are workflows, guided by your operating procedures, that ensure consistent incident response across all analysts. * Automated Gamebook mapping assigns the right workflow to each incident based on type and severity. * Three automation modes (Manual, Automatic, Autonomous) let you control the level of human oversight. * Improved visibility shows exactly which actions will be taken before execution. > **[What Are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Learn about Gamebook fundamentals > **[Configure SDAs](/guides/getting-started/configuring-security-delivery-agents)** > > Set up Security Delivery Agents > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # More Hosting Regions for EU, UK, and APAC Data Residency Source: https://docs.contraforce.com/blog/product-announcements/global-hosting-regions Hosting expands beyond the US to Europe, the UK, and Asia-Pacific, so you can meet customer data residency needs. Ask your account team about availability. > [!NOTE] > > **Who is this for?** All ContraForce partners and customers **November 25, 2024** · ContraForce Team · 2 min read ContraForce is pleased to announce the expansion of our platform hosting to additional regions around the world, enabling partners to serve customers with data residency requirements more effectively. ## Global Platform Availability As ContraForce grows internationally, we're investing in infrastructure to support partners worldwide: * **Regional data processing** — Data stays within specified geographic boundaries * **Lower latency** — Faster response times for regional users * **Compliance support** — Meet local data residency requirements ## New Regions In addition to our existing US hosting, ContraForce is expanding to: * **Europe** — EU-based infrastructure for European customers * **United Kingdom** — Dedicated UK hosting * **Asia-Pacific** — Regional presence for APAC partners ## What This Means for Partners Partners can now: * **Select hosting region** when onboarding new workspaces * **Meet customer requirements** for data locality * **Expand internationally** with confidence ## Data Residency For customers with specific data residency requirements: | Region | Data Processing | Storage | | - | - | - | | **United States** | US | US | | **Europe** | EU | EU | | **United Kingdom** | UK | UK | | **Asia-Pacific** | APAC | APAC | ## Getting Started Partners interested in regional hosting options should contact their ContraForce account team to discuss requirements and availability. ## Quick Summary * ContraForce is expanding platform hosting beyond the US to multiple global regions. * New regions include Europe, the United Kingdom, and Asia-Pacific to support local customers. * Regional hosting improves data residency alignment, latency, and compliance support. * Partners can choose hosting regions per workspace to meet customer and regulatory requirements. * Contact your ContraForce account team to enable or discuss regional hosting options. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with ContraForce > **[Workspace Onboarding](/guides/onboarding/workspace-onboarding)** > > Set up new workspaces > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Easier Sentinel and Defender for Endpoint Investigations Source: https://docs.contraforce.com/blog/product-announcements/incident-investigation-improvements Investigate Microsoft Sentinel and Defender for Endpoint incidents in the Workbench with entity enrichment, then respond without leaving the incident. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, SOC Analysts **June 17, 2025** · ContraForce Team · 3 min read ContraForce is pleased to announce significant improvements to incident investigation capabilities for Microsoft Sentinel and Microsoft Defender for Endpoint incidents. ## Faster, More Intuitive Investigation The latest updates to the ContraForce Workbench make it easier than ever to investigate security incidents: ## Unified Incident View * All related alerts consolidated into a single incident view * Timeline of events across all data sources * Entity relationships visualized in the Entity Context Graph ## Enhanced Entity Enrichment When you investigate an entity, ContraForce now automatically enriches it with: * **User entities** — Sign-in logs, audit history, group memberships, risk signals * **Device entities** — Device details, installed software, recent activity * **IP addresses** — Geolocation, threat intelligence, historical activity * **Files** — Hash lookups, prevalence data, detection history ## Streamlined Actions Take response actions directly from the investigation view: * Isolate devices without leaving the incident * Disable user accounts with a single click * Block IPs or URLs across customer workspaces * Quarantine files and soft-delete malicious emails ## Improved Context The Workbench now provides more context to help analysts make faster, more informed decisions: | Enhancement | Benefit | | - | - | | **Related incidents** | See other incidents involving the same entities | | **Historical patterns** | Understand if this behavior is normal | | **Threat intelligence** | Automatic correlation with known threats | | **Customer context** | Relevant information about the affected workspace | ## Quick Summary * Unified incident view consolidates all related alerts and shows entity relationships in the Entity Context Graph. * Enhanced entity enrichment automatically adds sign-in logs, device details, threat intelligence, and more. * Streamlined response actions let you isolate devices, disable accounts, and block threats without leaving the incident. * Improved context includes related incidents, historical patterns, and threat intelligence correlation. > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > Learn about the investigation interface > **[Entity Insights](/entity-insights)** > > Explore entity enrichment > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Security Delivery Agents: AI Incident Response at Scale Source: https://docs.contraforce.com/blog/product-announcements/security-delivery-agents Now generally available: AI agents that investigate incidents and run Gamebooks within confidence thresholds you set. Start manual, then add automation. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners and Security Team Leadership **February 2026** · ContraForce Team · 4 min read Security Delivery Agents (SDAs) are now generally available in ContraForce. These AI agents automatically investigate incidents, enrich context with sign-in logs and device timelines, and execute response actions through Gamebooks — giving your team the capacity to handle more incidents without adding headcount. ## What Security Delivery Agents Do SDAs handle the repetitive, time-consuming work of incident investigation. When an incident arrives, the agent: * **Analyzes the incident context** using sign-in logs, audit trails, device timelines, and related incidents * **Enriches entity information** by pulling threat intelligence and historical activity patterns * **Recommends or executes response actions** based on your configured confidence thresholds * **Documents findings** with detailed comments for analyst review This isn't a chatbot or copilot. SDAs are autonomous agents that take action on your behalf, following the same workflows your analysts would — just faster and at scale. ## A Phased Approach to Automation ContraForce designed SDAs with a progressive adoption model. You control how much automation to enable: | Phase | Mode | What Happens | | - | - | - | | **Phase 1** | Manual | You select incidents and trigger agent investigation on demand | | **Phase 2** | Automatic by Status | Agents run automatically on new, active, or closed incidents | | **Phase 3** | Automatic Gamebooks | Agents execute response playbooks based on confidence thresholds | Start with manual execution to see how agents analyze your incident types. Once you trust the outputs, enable automatic execution. When you're confident in agent accuracy, allow Gamebook execution for full autonomous response. ## Human-in-the-Loop Controls Even with full automation enabled, you maintain control: * **Confidence thresholds** determine when agents can take action versus when they require approval * **Status filters** control which incidents trigger automatic processing * **Gamebook authorization** must be explicitly granted before agents can execute response actions * **Audit trails** capture every agent action for compliance and review ## Why This Matters for Service Providers For MSPs and MSSPs managing multiple customer workspaces, SDAs change the math on security operations: * **Scale without headcount** — Handle 10x the incident volume with the same team * **Consistent quality** — Every incident gets the same thorough investigation * **Faster response** — Automated triage means faster time-to-resolution * **Multi-tenant ready** — Agents work across all your customer workspaces from day one ## Quick Summary * Security Delivery Agents automate incident investigation and response * Three-phase adoption: manual → automatic by status → automatic Gamebooks * Agents use sign-in logs, device timelines, and threat intelligence for context * Confidence thresholds and human-in-the-loop controls keep you in charge * Deploy once, scale across all customer workspaces > **[Configuring SDAs](/guides/getting-started/configuring-security-delivery-agents)** > > Step-by-step guide to configuring Security Delivery Agents > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy the Microsoft Foundry infrastructure that powers SDAs > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Launching the Security Delivery Platform for AI-Driven MXDR Source: https://docs.contraforce.com/blog/product-announcements/security-delivery-platform-launch Microsoft-focused MSPs and MSSPs can deliver AI-driven MXDR with Security Delivery Agents: 60x faster investigations and 93% lower cost per incident. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, IT Service Providers, Security Service Providers **November 17, 2025** · Stan Golubchik · 3 min read ## Introducing the ContraForce Security Delivery Platform **A new operating model for managed security has arrived.** For years, we've been building toward one vision: Enable every Microsoft-focused service provider to deliver enterprise-grade MXDR to every customer without needing a massive SOC or enterprise-scale team. Today, that vision becomes real. We're officially launching the ContraForce Security Delivery Platform. This brings Microsoft's next-generation security and AI capabilities directly inside ContraForce, and gives service providers the ability to deliver fully automated, scalable MXDR services across their entire customer base. This is not an add-on. This is not an iteration. This is a new operating model for managed security delivery. ## Why the industry needs a new model Service providers are being asked to deliver more with less: * More customers * More incidents * More compliance * More 24/7 coverage * More visibility * More expectations All while battling staffing shortages, shrinking margins, and the complexity of managing dozens or hundreds of distinct customer environments. Traditional SOC models built for single-tenant enterprise teams simply do not scale for the multi-tenant realities of MSPs and MSSPs. So we built something that does. ## The ContraForce Security Delivery Platform What this means for Service Providers (and your customers): ## Microsoft-native, deeply integrated security foundation Built directly on Microsoft Azure and Microsoft Foundry. Deep integrations with Microsoft Sentinel, Defender for Endpoint, and Microsoft Entra ID. No extra overhead, no extra infrastructure, no patchwork tools. This is Microsoft-powered security, operationalized for Service Providers. ## Autonomous Security Delivery Agents Our Security Delivery Agents powered by Microsoft Foundry and Microsoft's emerging agent frameworks autonomously handle: * Triage * Investigation * Disposition * Response * Documentation For every customer workspace, with supervised or autonomous execution. Think of them as always-on security analysts with precision consistency and no fatigue. ## 60× faster investigations and response What used to take 30 minutes of investigation, disposition, and response now takes 30 seconds. Faster outcomes. Fewer escalations. Fewer breaches. This is what "AI-delivered security" actually looks like. ## 10× more customer capacity per analyst Onboard more customers without hiring more analysts. Scale service delivery without scaling overhead. This is how you grow margins while growing your customer base. ## 93% lower cost-per-incident Shift unit of labor work from human to AI compute economics. Labor-driven costs drop dramatically with AI agent incident processing. Human incident management costs go from $15 per incident to under $1 per incident in AI compute cost. We've seen cost-per-incident fall under \$0.25 per incident. This is how MXDR becomes truly profitable at scale. ## Global MXDR delivery from a single control plane Deploy Security Delivery Agents across any workspace, anywhere. Unify operations across Sentinel, Defender for Endpoint, and more with no portal pivoting. Your analysts stay in one place. Your customers get faster outcomes. Your economics flip in your favor. ## Why this matters This launch isn't just great news for the businesses our service providers protect. It transforms the economics and scalability of managed security itself. With the ContraForce Security Delivery Platform, Service Providers can: * Scale accounts without scaling teams * Launch high-value MXDR offerings in days, not months * Deliver consistent outcomes across all workspaces * Strengthen recurring revenue and margins * Operate with predictable, automated workflows * Become strategic security advisors — not reactive responders This is the first time AI-driven, multi-tenant MXDR has been built for Service Providers, not retrofitted to them. ## A milestone years in the making This platform reflects the combined effort of two teams: * **ContraForce** — designing and scaling a platform purpose-built for multi-tenant security operations. * **Microsoft** — powering the foundational security architecture and AI frameworks that make agentic security delivery possible. Thank you to every engineer, partner manager, architect, and early design partner who helped bring this to life. Together, we are enabling Service Providers to deliver security in a way that simply wasn't possible a few years ago. ## This is only the beginning The launch of the ContraForce Security Delivery Platform marks the start of a new era where: * AI agents deliver consistent, autonomous operations * Multi-tenant orchestration becomes standard * Unit economics improve dramatically * Service Providers can finally scale security delivery without scaling complexity More capabilities. Deeper integrations. Expanding service provider support. All coming next. If you're a Microsoft-aligned Service Provider looking to scale MXDR, accelerate response, and transform margins — this is your moment. Let's build the future of security delivery together. **Stan Golubchik** CEO & Co-Founder, ContraForce ## Quick Summary * The ContraForce Security Delivery Platform is a new operating model for managed security built on Microsoft Azure and AI. * Security Delivery Agents autonomously handle triage, investigation, response, and documentation. * Achieve 60× faster investigations, 10× more customer capacity per analyst, and 93% lower cost-per-incident. * Designed for Microsoft-focused MSPs and MSSPs to scale MXDR services without scaling headcount. * Deep integrations with Microsoft Sentinel, Defender for Endpoint, and Microsoft Entra ID with no extra infrastructure required. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Get started with the ContraForce platform > **[Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Configure autonomous security agents > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Splunk, CrowdStrike Falcon, and IBM QRadar Support Added Source: https://docs.contraforce.com/blog/product-announcements/siem-xdr-platform-support In July 2024, ContraForce added Splunk ES, CrowdStrike Falcon XDR, and IBM QRadar SIEM support, extending Gamebook workflows across SIEM and XDR platforms. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, Security Engineers **July 23, 2024** · ContraForce Team · 3 min read ContraForce is excited to announce expanded platform support, now including Splunk Enterprise Security, CrowdStrike Falcon XDR, and IBM QRadar SIEM alongside our existing Microsoft Sentinel and Defender for Endpoint integrations. ## Multi-Platform Security Operations Service providers often manage customers with diverse security technology stacks. This expansion allows you to: * **Consolidate operations** — Manage incidents from multiple platforms in one place * **Apply consistent workflows** — Use Gamebooks across all supported platforms * **Scale efficiently** — Same operational model regardless of underlying technology ## New Platform Integrations ## Splunk Enterprise Security * Ingest notable events from Splunk ES * Correlate Splunk data with other security sources * Execute response actions through Splunk's SOAR capabilities ## CrowdStrike Falcon XDR * Receive detections from Falcon platform * Leverage Falcon's endpoint response actions * Integrate with existing Falcon deployments ## IBM QRadar SIEM * Pull offenses from QRadar * Enrich with QRadar's event context * Coordinate response across hybrid environments ## Why This Matters Many MSPs and MSSPs support customers with non-Microsoft security stacks. With this expansion: * **No more portal pivoting** — Work from a single interface * **Consistent service delivery** — Same quality of service regardless of platform * **Flexible customer support** — Onboard customers without forcing technology changes ## Microsoft Remains Core While we're expanding platform support, Microsoft Sentinel and Defender for Endpoint remain our core focus: * Deepest integration with Microsoft security stack * Full Security Delivery Agent support * CMS for detection content management ## Quick Summary * ContraForce now supports Splunk Enterprise Security, CrowdStrike Falcon XDR, and IBM QRadar SIEM. * Consolidate incidents from multiple security platforms into a single operational interface. * Apply consistent Gamebook workflows regardless of underlying technology. * Microsoft Sentinel and Defender for Endpoint remain the core focus with the deepest integration. > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy Defender for Endpoint integration > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Operating Procedures Now Power Your Security Delivery Agents Source: https://docs.contraforce.com/blog/product-announcements/sop-knowledge-base Upload Classification and Response operating procedures, map them to MITRE ATT&CK, and link them to Security Delivery Agents to guide incident response. > [!NOTE] > > **Who is this for?** MSP/MSSP Partners, SOC Leaders, and Security Team Leadership > [!NOTE] > > This feature launched as the SOP Knowledge Base and is now called Operating Procedures. **March 2026** · ContraForce Team · 4 min read Every security team builds institutional knowledge over years of operational experience. Classification criteria. Response procedures. Escalation paths. Remediation steps. That knowledge lives in documents scattered across SharePoint, Confluence, Google Drive, and shared folders. Until today, none of it was accessible to your Security Delivery Agents. That changes now. ## Introducing Operating Procedures Operating Procedures is a new capability inside ContraForce that lets you upload your operating procedures and associate them directly with Security Delivery Agents. Two operating procedure types. Two purposes. **Classification operating procedures** define how incidents get categorized and prioritized. You can associate multiple Classification operating procedures with a Security Delivery Agent, but only one is activated per investigation — ensuring consistent severity decisions while giving you flexibility across different scenarios. **Response operating procedures** define how incidents get investigated and remediated. Each Security Delivery Agent supports multiple Response operating procedures, so the right procedures are available regardless of incident type. Upload your documents. Tag them. Map them to MITRE ATT\&CK techniques. Associate them with the agents that need them. Done. ## Why This Matters Security Delivery Agents are powerful. They triage, investigate, enrich, and recommend actions at machine speed. But speed without context is not delivery. It is automation. Delivery means the agent follows your procedures. It classifies incidents the way your team classifies them. It responds the way your team responds. It applies the institutional knowledge your analysts have built over years. Operating Procedures bridges that gap. Your agents stop operating with generic patterns and start operating with your patterns. For MSPs and MSSPs managing multiple workspaces, this is the difference between a tool that runs fast and a platform that delivers consistently. Every workspace gets its own operating procedure library. Every agent gets the procedures that match the client's requirements. Every incident gets handled according to the operating procedures you defined. ## How It Works Operating Procedures lives inside the ContraForce Agent Center as a dedicated section in the left navigation. **Upload.** Drag and drop your operating procedure documents. Launch formats include Markdown and plain text, with PDF, Word, HTML, and RTF coming soon. ContraForce extracts and indexes the content automatically. **Categorize.** Assign each operating procedure as either Classification or Response. Add tags for organization. Map to MITRE ATT\&CK techniques so the right operating procedure surfaces for the right threat. **Associate.** Link operating procedures to Security Delivery Agents from either direction. Navigate from the operating procedure detail view to add agents, or from the agent detail page to add operating procedures. Changes take effect immediately. **View.** Read operating procedure content directly inside ContraForce without switching to external systems. See which agents use each operating procedure. See which operating procedures each agent has. Full visibility into the connection between your procedures and your delivery. All operating procedure data is workspace-scoped. Tenant isolation is enforced at the infrastructure level. No cross-tenant data exposure. No shared indexes. ## What This Unlocks This release is the foundation for agent execution guided by your operating procedures. Security Delivery Agents now have access to your procedures at runtime, enabling context-aware incident handling that follows your organization's specific guidelines. For teams already running ContraForce: * Your agents get smarter without retraining. Upload the operating procedures. Associate them. The agents reference them during incident handling. * New analyst onboarding accelerates. The operating procedures that define how your team operates are now embedded in the platform, not buried in a folder. * Governance gets concrete. Auditors and clients can see exactly which procedures govern each agent's decisions. For MSPs evaluating ContraForce: * This is how you standardize delivery across every client without building custom runbooks per tenant. * This is how you prove to clients that their security operations follow documented, auditable procedures. * This is how you scale a security practice without scaling tribal knowledge. ## Built for the Way You Already Work You do not need to rewrite your operating procedures. You do not need to learn a proprietary format. Upload the documents your team already maintains. ContraForce handles the parsing, indexing, and association. At launch, ContraForce supports Markdown and plain text files — the formats security teams already use for version-controlled docs and lightweight playbooks. Support for Word, PDF, HTML, and RTF is coming soon. ## Available Now Operating Procedures is available to all ContraForce customers as part of the Phase 2: Trust and Control release. No additional cost. No configuration required. Log in to Agent Center and start uploading. Security Delivery Agents work on their first alert from any connected tool. Now they work on that first alert with your operating procedures guiding every decision. **AI that acts. Humans who decide. Now with your procedures built in.** *** Ready to see it in your tenant? [Book a demo](https://cal.com/contraforce/30-minutes-with-stan) or reach out to your ContraForce account representative. > **[Operating Procedures Documentation](/guides/agent-center/operating-procedures)** > > Full setup guide, file formats, association workflows, and best practices. > **[Introducing Security Delivery Agents](/blog/product-announcements/security-delivery-agents)** > > Learn how Security Delivery Agents automate incident response at scale. # Incident Classification Mapping Across Vendors Source: https://docs.contraforce.com/concepts/incident-classification See how your incident classification and reason map to Microsoft Sentinel, Defender XDR, and SentinelOne, and how closing a CrowdStrike incident works. ContraForce records a closing classification on every classified incident using one canonical taxonomy, regardless of which detection module the incident came from. Analysts pick from the same four verdicts and the same reason list everywhere; ContraForce translates to each vendor's native vocabulary behind the scenes. ## Canonical classifications | Order | Classification | Meaning | Color | | - | - | - | - | | 1 | True Positive | Confirmed malicious activity | Red | | 2 | False Positive | The detection was wrong; no suspicious activity occurred | Orange | | 3 | Benign Positive | Real activity that was confirmed benign, expected, or authorized | Green | | 4 | Undetermined | No firm verdict was reached | Blue | This order and color scheme appear consistently across the close dialogs, the Incidents inbox classification column and filters, and the [Command Dashboard](/guides/getting-started/command-dashboard) Classification Trends widget. ## Classification reasons Each reason applies to specific classifications. The reason list shown when closing an incident is scoped to the classification you pick; it is the same list for every detection module. | Classification | Valid reasons | | - | - | | True Positive | Multistage Attack, Malware, Malicious User Activity, Unwanted Software, Phishing, Compromised User, APT, Suspicious Activity, Other | | False Positive | Not Malicious, Not Enough Data To Validate, Inaccurate Data, Incorrect Alert Logic, Other | | Benign Positive | Security Testing, Confirmed User Activity, Line Of Business Application, Security Personnel, Suspicious But Expected, Other | | Undetermined | Unknown, Other | A reason is required whenever a classification is set. Your exact choice is always preserved in ContraForce, even when the vendor's own vocabulary cannot store it (see the per-module tables below). ## Per-module translation ContraForce writes your verdict back to the vendor when the vendor supports it, translating to the nearest native value. The tables below show the write-back mapping per module. ### Microsoft Sentinel Sentinel's classifications match the canonical four one to one. Its reason vocabulary is fixed per classification, so canonical reasons outside that set degrade to Sentinel's default for the classification. | Canonical | Sentinel classification | Sentinel reason | | - | - | - | | True Positive (any reason) | TruePositive | SuspiciousActivity | | False Positive + Inaccurate Data | FalsePositive | InaccurateData | | False Positive + Incorrect Alert Logic | FalsePositive | IncorrectAlertLogic | | False Positive (other reasons) | FalsePositive | InaccurateData | | Benign Positive (any reason) | BenignPositive | SuspiciousButExpected | | Undetermined | Undetermined | none | ### Microsoft Defender XDR All fifteen Defender determinations are canonical ContraForce reasons, so most verdicts round-trip exactly. | Canonical | Defender classification | Defender determination | | - | - | - | | True Positive | TruePositive | The chosen reason (Multistage Attack, Malware, Malicious User Activity, Unwanted Software, Phishing, Compromised User, APT, Other) | | False Positive | FalsePositive | The chosen reason (Not Malicious, Not Enough Data To Validate, Other) | | Benign Positive | InformationalExpectedActivity | The chosen reason (Security Testing, Confirmed User Activity, Line Of Business Application, Security Personnel, Other) | | Undetermined | Unknown | none | Reasons Defender cannot store for the mapped classification (for example a Sentinel-origin reason like Inaccurate Data) are written as Other; the canonical reason stays intact in ContraForce. ### SentinelOne SentinelOne records an analyst verdict and has no reason concept. Reasons are preserved in ContraForce only. | Canonical | SentinelOne analyst verdict | | - | - | | True Positive | true\_positive | | False Positive | false\_positive | | Benign Positive | false\_positive | | Undetermined | undefined | When reading from SentinelOne, both `suspicious` and `undefined` map to Undetermined. ### CrowdStrike Falcon Closing a CrowdStrike incident in ContraForce closes it in Falcon too: ContraForce sets the alert's status to `closed` (or the case's, for incidents that are Falcon cases), so no one has to close it a second time in the Falcon console. The verdict itself stays in ContraForce, because CrowdStrike's unified Alerts API has no classification field to write it to. | ContraForce | CrowdStrike Falcon | | - | - | | Close (any classification) | Status set to `closed` | | Classification, reason, and close comment | Not written; stored and displayed by ContraForce | The full canonical taxonomy is available when closing a CrowdStrike incident, and the verdict, reason, and comment appear on the incident in ContraForce and in the `incident.closed.v1` webhook. ## Closures made in the vendor's portal When an incident is closed in the vendor's own console instead of through ContraForce, ContraForce reconciles the closure: the vendor's classification is translated to the canonical taxonomy, an activity entry attributed to the upstream source is added to the incident's audit trail, closure metrics are recorded, and the `incident.closed.v1` webhook fires with `closedBy.origin` set to `upstream`. ## Webhooks The `incident.closed.v1` webhook event carries the canonical classification and reason names, never raw vendor vocabulary. See the [Webhook Event Reference](/api-reference/webhook-events) for the payload schema. ## Historical data Before this taxonomy unified, ContraForce carried vendor-specific classification values. Historical data is translated on read: | Legacy value | Canonical value | | - | - | | InformationalExpectedActivity | Benign Positive | | Unknown | Undetermined | | NonIssue | Benign Positive | | PolicyViolation | Benign Positive | | QradarFalsePositive | False Positive | | Undefined | Undetermined | | Suspicious | Undetermined | API consumers see canonical names in all responses; requests that still send legacy names are accepted and translated. *** ## Related Guides > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > Choose True Positive, Benign Positive, False Positive, or Undetermined when you close an incident. > **[Incident Management](/guides/getting-started/incident-management)** > > Triage, assign, investigate, and close incidents across your workspaces. > **[Setting Up Webhooks](/guides/technical/configure-webhooks)** > > Send signed incident events, such as closed incidents, to your ticketing system, SIEM, or chat tools. > **[Incident Report](/guides/getting-started/incident-report)** > > Filter closed incidents by classification, severity, source, or reason, and save a PDF. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Defender for Endpoint Permissions and Consent Source: https://docs.contraforce.com/defender-for-endpoint-module Review the permissions and licenses the Defender for Endpoint enterprise application needs, then grant, verify, or revoke consent for your workspace. The Microsoft Defender for Endpoint enterprise application enables ContraForce to access Microsoft Defender for Endpoint (MDE) data. Once consented, you gain visibility into endpoints across your managed workspaces and can perform response actions directly from ContraForce. > [!NOTE] > > This enterprise application is required for device insights and endpoint-related Gamebook actions in ContraForce. ## What This Application Enables > **Endpoint Visibility** > > View all devices managed by Defender for Endpoint across your workspaces > **Device Details** > > Access device information including OS, health state, and exposure level > **Incident Correlation** > > See device-related incidents and timeline data during investigations > **Response Actions** > > Execute endpoint Gamebooks (with additional consent) *** ## Features Enabled Once consented, the Microsoft Defender for Endpoint enterprise application enables the following capabilities: ### Entity Insights During incident investigation, access device-related insights: | Insight | Description | | - | - | | **Device Timeline** | Chronological view of events on the endpoint | | **Device Info** | Detailed hardware and software information | | **Related Incidents** | Other incidents involving the same device | ### Incident Data The application also enables: * Bi-directional incident streaming from Defender for Endpoint * Fetching incident entities and evidence * Alert timelines and investigation audit trails > [!TIP] > > For full endpoint response capabilities (isolate, scan, quarantine), you'll also need to consent the **Gamebooks for Defender for Endpoint** enterprise application. *** ## Permissions The Microsoft Defender for Endpoint enterprise application requests the following Microsoft Graph and Defender API permissions: ### Required Permissions | Permission | Type | Purpose | | - | - | - | | **Machine.Read.All** | Application | Read device information from MDE | | **Machine.ReadWrite.All** | Delegated | Access device details during user sessions | | **SecurityIncident.Read.All** | Application, Delegated | Read Microsoft Defender XDR incidents and their alerts | | **SecurityIncident.ReadWrite.All** | Application, Delegated | Update incident status, assignment, classification, and comments | | **SecurityAlert.Read.All** | Application, Delegated | Read security alerts | > [!WARNING] > > These permissions grant read access to endpoint data across the tenant. Ensure you have proper authorization before consenting on behalf of customers. ### Permission Types Explained | Type | Description | Use Case | | - | - | - | | **Application** | Runs without user context | Background data synchronization | | **Delegated** | Runs on behalf of signed-in user | Interactive portal access | *** ## Prerequisites Before consenting this enterprise application: **1. Microsoft Defender for Endpoint** MDE must be deployed and active in the target tenant **2. Appropriate Licensing** Microsoft 365 Business Premium, E3, or E5 (or standalone MDE license) **3. Admin Permissions** **Global Administrator** or **Privileged Role Administrator** in the target tenant. Cloud Application Administrator and Application Administrator cannot grant consent for Microsoft Graph application permissions. **4. ContraForce Workspace** The workspace must be created and the tenant onboarded *** ## How to Consent ### Step 1: Navigate to Workspace Modules **1. Open Workspaces** Go to the **Workspaces** page in ContraForce **2. Select Workspace** Find the workspace you want to configure **3. Open Modules** Click the **gear icon** or **Modules** to access workspace settings ### Step 2: Add the Module **1. Click Add Module** Click the **Add Module** button **2. Select Microsoft Defender for Endpoint** Choose **Microsoft Defender for Endpoint** from the list **3. Confirm** Click **Confirm** to add the module to the workspace ### Step 3: Consent Permissions **1. Open the Module** Click on the **Microsoft Defender for Endpoint** module you just added **2. Review Permissions** Scroll down to see the list of permissions required **3. Click Consent** Click the **Consent** button to start the consent flow **4. Authenticate** Sign in with a **Global Administrator** or **Privileged Role Administrator** account from the target tenant **5. Accept Permissions** Review and accept the requested permissions > [!NOTE] > > The consent flow is a 3-step process. Ensure you complete all steps for the application to function correctly. *** ## Verifying Consent After consenting, verify the application is working: ### In ContraForce 1. Navigate to the **Endpoints** page 2. Select the workspace you just configured 3. Confirm devices are populating in the list ### In Microsoft Entra ID 1. Go to **Azure Portal** > **Microsoft Entra ID** > **Enterprise Applications** 2. Search for "ContraForce" or the application name 3. Verify the application appears with **Enabled** status 4. Check **Permissions** to confirm grants are in place *** ## Capability Matrix The Microsoft Defender for Endpoint integration capabilities vary by license: | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | **Incident Management** | | | | | Bi-directional incident streaming | ✓ | ✓ | ✓ | | Fetch incident entities | ✓ | ✓ | ✓ | | Fetch incident evidence | ✓ | ✓ | ✓ | | Alert timelines | ✓ | ✓ | ✓ | | **Device Insights** | | | | | Device info | ✓ | ✓ | ✓ | | Device timeline | ✓\* | ✓\* | ✓ | | Related incidents | ✓\* | ✓\* | ✓ | | **Endpoint Management** | | | | | View device list | ✓ | ✓ | ✓ | | View device info | ✓ | ✓ | ✓ | \*Requires Microsoft Defender for Endpoint Plan 2 add-on > **[Full Capabilities Matrix](/guides/technical/microsoft-defender-capability-matrix)** > > View the complete Defender capability matrix including Gamebook actions *** ## Related Enterprise Applications The Microsoft Defender for Endpoint application works alongside other ContraForce enterprise applications: | Application | Purpose | | - | - | | **[Gamebooks for Defender for Endpoint](/guides/technical/enterprise-applications#contraforce-gamebooks-for-mde)** | Endpoint response actions (isolate, scan, quarantine) | | **[Gamebooks for Identity](/guides/technical/enterprise-applications#contraforce-gamebooks-for-identity)** | User response actions (disable, reset password) | | **[Gamebooks for Email (Microsoft 365 Response)](/guides/technical/enterprise-applications#contraforce-gamebooks-for-email-microsoft-365-response)** | Email response actions (delete email) | > [!TIP] > > For a complete MXDR setup, consent all relevant enterprise applications based on the response capabilities you need. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **No devices showing** | Consent incomplete | Re-run the consent flow and complete all steps | | **Consent fails** | Insufficient permissions | Use a **Global Administrator** or **Privileged Role Administrator** account. Cloud Application Administrator and Application Administrator cannot grant Microsoft Graph application permissions and will end at "approval required" | | **Partial data** | MDE not fully deployed | Verify MDE is active on target devices | | **Stale device data** | Sync delay | Wait 15-30 minutes for initial sync | | **Permission denied errors** | Consent revoked | Check Microsoft Entra ID enterprise apps and re-consent | ### Checking Consent Status In the workspace modules view, consented applications show a green checkmark or "Consented" status. If you see "Not Consented" or a warning icon, re-run the consent process. ### Revoking Consent If you need to revoke consent: 1. Go to **Azure Portal** > **Microsoft Entra ID** > **Enterprise Applications** 2. Find the ContraForce Defender for Endpoint application 3. Go to **Properties** and set **Enabled for users to sign-in** to **No** 4. Or delete the application entirely > [!WARNING] > > Revoking consent will disable MDE data access in ContraForce for that workspace. *** ## Best Practices > **Consent during onboarding** > > Add and consent the Microsoft Defender for Endpoint module during initial workspace onboarding for a smoother setup experience. > **Use a dedicated admin account** > > Create a dedicated admin account for consenting enterprise applications across customer tenants. It needs Global Administrator or Privileged Role Administrator, since those are the only roles Entra allows to grant Microsoft Graph application permissions. Activate the role just-in-time with Privileged Identity Management (PIM) and deactivate afterward rather than leaving it standing. > **Document consent status** > > Track which enterprise applications are consented for each workspace to simplify troubleshooting. > **Consent related applications together** > > If you need Gamebook response actions, consent both Microsoft Defender for Endpoint and Gamebooks for Defender for Endpoint at the same time. > **Verify after consent** > > Always verify Defender for Endpoint data is flowing into ContraForce after completing the consent flow. *** ## Related Guides > **[Enterprise Applications Overview](/guides/technical/enterprise-applications)** > > Overview of all ContraForce enterprise applications > **[Gamebooks for Defender for Endpoint](/guides/technical/enterprise-applications#contraforce-gamebooks-for-mde)** > > Enable endpoint response actions > **[Defender Capability Matrix](/guides/technical/microsoft-defender-capability-matrix)** > > Full Defender feature capabilities *** > [!NOTE] > > Questions about the Microsoft Defender for Endpoint enterprise application? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Entity Insights Source: https://docs.contraforce.com/entity-insights Enrich your investigations with sign-in and audit logs, device timelines, threat intelligence, and related incidents for users, devices, IPs, and files. Entity Insights provide rich context during incident investigations. Instead of switching between tools to gather information about affected users, devices, or IP addresses, ContraForce surfaces relevant data directly within the incident view. > [!NOTE] > > Available insights vary by entity type and your connected data sources. The more integrations you have enabled, the richer your entity insights will be. ## Why Entity Insights Matter > **Faster Investigations** > > Access critical context without leaving ContraForce > **Complete Picture** > > See related incidents, logs, and threat intel in one place > **Better Decisions** > > Make informed response choices with full entity context *** ## Available Insights by Entity Type ContraForce provides different insights depending on the entity type associated with an incident. **User** **User entities** include accounts, identities, and mailboxes. | Insight | Description | | - | - | | **Related Incidents** | Other incidents involving this user | | **Sign-In Logs** | Authentication history including locations, devices, and outcomes | | **Audit Logs** | Administrative actions and changes made by or to this user | | **User Insights** | Account details, group memberships, risk score, and profile information | *Use cases: Investigating compromised accounts, tracking lateral movement, understanding user behavior patterns* **Device** **Device entities** include endpoints, servers, and mobile devices. | Insight | Description | | - | - | | **Timeline** | Chronological view of events and activities on the device | | **Related Incidents** | Other incidents involving this device | | **Device Insights** | Hardware details, OS version, security state, exposure level | *Use cases: Tracking malware spread, understanding attack chains, assessing device health* **IP Address** **IP entities** include source and destination addresses from network activity. | Insight | Description | | - | - | | **Related Incidents** | Other incidents involving this IP address | | **IP Insight Logs** | Geolocation, reputation, ASN, and historical activity | *Use cases: Identifying malicious infrastructure, tracking C2 communications, investigating data exfiltration* **Email** **Email entities** include messages, attachments, and sender/recipient information. | Insight | Description | | - | - | | **Email Insights** | Message details, headers, attachments, and delivery information | | **Related Incidents** | Other incidents involving this email or sender | *Use cases: Investigating phishing campaigns, tracking malicious attachments, analyzing email-based attacks* **File** **File entities** include executables, documents, scripts, and their hashes. | Insight | Description | | - | - | | **Related Incidents** | Other incidents involving this file or hash | | **File Insights** | File metadata, hash values, detection ratios, and threat intelligence | *Use cases: Tracking malware variants, identifying suspicious files, correlating file-based IOCs* **URL** **URL entities** include web addresses and domains involved in incidents. | Insight | Description | | - | - | | **Related Incidents** | Other incidents involving this URL or domain | | **URL Insights** | Domain reputation, registration details, and threat intelligence | *Use cases: Investigating phishing links, blocking malicious domains, tracking web-based threats* *** ## Accessing Entity Insights Follow these steps to view insights for any entity in an incident. **1. Open the Incident** From the Command Dashboard, click the **Incident ID** in the Incidents table to open the compact incident overview **2. Expand to Detailed View** Click the **diagonal arrows** icon (next to the X) in the top right corner to open the detailed incident view **3. Select Entities Tab** Click the **Entities** tab to see all associated entities **4. Open Entity Menu** Click the **three dots (⋮)** on any entity row to see available insights **5. Select Insight Type** Choose the insight you want to view from the dropdown menu ![Entity insights menu for a user](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/entityinsights.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=0ec0e591ccb48eb4da4122f3a89f3408) *** ## Working with Insights ### Multiple Insights You can open multiple insights simultaneously: * Each insight opens in its own **tab** within the popup window * Switch between tabs to compare information * The popup window can be **resized** for better viewing ![Multiple entity insight tabs](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/entityinsightdrawer.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=0e606492dbe6fede601379edb9d954d9) ### Insight Details Each insight type displays relevant information in an organized format: > **Sign-In Logs** > > **Columns typically include:** > > * Timestamp > * Sign-in status (Success/Failure) > * IP address and location > * Device and browser information > * Conditional access results > * Risk level > > **Filter by:** Date range, status, location, risk level > **Audit Logs** > > **Columns typically include:** > > * Timestamp > * Activity type > * Target resource > * Initiated by (user/service) > * Result (Success/Failure) > > **Filter by:** Date range, activity type, target > **User Insights** > > **Information displayed:** > > * Display name and UPN > * Job title and department > * Manager > * Group memberships > * Account status > * Risk score > * Last sign-in > **Device Insights** > > **Information displayed:** > > * Device name and ID > * OS platform and version > * Health state > * Exposure level > * Last seen timestamp > * Compliance status > * Logged-on users > **IP Insight Logs** > > **Information displayed:** > > * Geolocation (country, city) > * ASN and ISP > * Reputation score > * Associated domains > * Historical activity > * Threat intelligence matches > **File Insights** > > **Information displayed:** > > * File name and path > * SHA256, SHA1, MD5 hashes > * File size > * First/last seen > * Detection ratio > * Threat intelligence enrichment *** ## Related Incidents The **Related Incidents** insight is available for all entity types and shows other incidents where the same entity appears. ### Why This Matters * **Pattern Detection** — Identify if an entity is repeatedly involved in security events * **Attack Chain Analysis** — Understand how an attacker moved through your environment * **Scope Assessment** — Determine the full impact of a compromise * **False Positive Identification** — Recognize legitimate activity that triggers multiple alerts ### Using Related Incidents | Column | Description | | - | - | | **Incident ID** | Click to open the related incident | | **Title** | Brief description of the incident | | **Severity** | High, Medium, Low, Informational | | **Status** | Current state of the incident | | **Created** | When the incident was detected | > [!TIP] > > If you see the same entity in multiple high-severity incidents, prioritize investigating that entity—it may indicate an active compromise. *** ## Threat Intelligence Enrichment Some entity insights include threat intelligence from integrated sources. ### Supported Enrichments | Entity Type | Threat Intel Data | | - | - | | **IP Address** | Reputation, malicious activity history, blocklist status | | **File/Hash** | VirusTotal detections, malware family, first seen date | | **URL/Domain** | Reputation, phishing indicators, domain age | | **User** | Compromised credential alerts, risk indicators | > [!NOTE] > > Threat intelligence enrichment requires integration with tools like VirusTotal or Microsoft Defender Threat Intelligence. Contact your administrator to enable additional enrichment sources. *** ## Integration-Specific Insights Available insights depend on which integrations are connected to your workspace. ### Microsoft Defender for Endpoint * Device timeline and alerts * User sign-in and audit logs * Email trace and threat detection * File and URL analysis ### Microsoft Sentinel * Log Analytics query results * Custom entity enrichments * Watchlist matches * Threat intelligence indicators ### Third-Party Integrations Additional insights may be available based on your connected tools: * **CrowdStrike** — Device details, detection history (see [CrowdStrike Falcon Integration](/guides/technical/crowdstrike-falcon-integration) for what each Falcon tier provides) * **SentinelOne** — Agent status, threat indicators *** ## Best Practices > **Start with Related Incidents** > > Always check Related Incidents first. If an entity appears in multiple incidents, it may be the key to understanding the attack scope. > **Correlate sign-in anomalies** > > Compare sign-in logs with the incident timeline. Look for unusual locations, impossible travel, or authentication failures before the incident. > **Use audit logs for privilege escalation** > > When investigating compromised accounts, review audit logs for privilege changes, group membership modifications, or unusual administrative actions. > **Check device timeline for malware** > > For device-based incidents, the timeline shows the sequence of events leading to detection—crucial for understanding initial access and lateral movement. > **Document key findings** > > Copy important insight data to incident comments for team visibility and post-incident documentation. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **No insights available** | Entity type not supported | Check the Capabilities Matrix for supported entities | | **Missing sign-in logs** | Microsoft Entra ID integration not connected | Verify Microsoft Entra ID connector status | | **Empty device timeline** | Defender for Endpoint not onboarded | Confirm MDE integration is enabled | | **No threat intel data** | Enrichment source not configured | Contact admin to enable VirusTotal or other TI sources | *** ## Related Guides > **[Incident Management Guide](/guides/getting-started/incident-management)** > > Complete incident investigation workflow > **[Security Workbench](/guides/getting-started/workbench-overview)** > > Deep dive investigation interface > **[Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Take action on entities after investigation *** > [!NOTE] > > Questions about entity insights? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Agent Execution History Source: https://docs.contraforce.com/guides/agent-center/agent-execution-history Audit every run of your Security Delivery Agents, troubleshoot failures, and track AI token usage per run in each agent's Execution History tab. View a complete audit trail of Security Delivery Agent executions to monitor agent performance, troubleshoot failures, and demonstrate compliance with response policies. The Execution History tab on the Agent Details page provides a sortable table of every time an agent has processed an incident. Each row captures when the execution occurred, who triggered it, which incident was processed, the data source, severity, token consumption, and the outcome — giving you full visibility into automated response activity. *** ## What Can You Do Here? > **Audit Agent Activity** > > Review every execution an agent has performed, with timestamps and outcomes. > **Troubleshoot Failures** > > Identify failed executions and investigate causes using status and token data. > **Monitor Token Usage** > > Track AI token consumption per execution to understand cost and complexity. *** ## Prerequisites | Requirement | Description | | - | - | | **Agent Center Deployed** | Microsoft Foundry infrastructure must be provisioned. See [Deploying Agent Center](/guides/onboarding/agent-center-deployment). | | **Security Delivery Agent Configured** | At least one agent must be created and configured. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). | | **ContraForce Roles** | Organizational Admin or Agent Admin role required. | *** ## Accessing Execution History **1. Navigate to Agent Center** From the left navigation menu, select **Agent Center**. **2. Select Your Agent** Click the name of the agent you want to review. This opens the Agent Details page. **3. Open the Execution History Tab** On the Agent Details page, click the **Execution History** tab (next to the **Configuration** tab). ![Agent details page, Run History tab, listing runs with date, incident, source, severity, tokens, cost, and status](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/agent-execution-history.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=495c402f7b2040409bbf0225b84b0e26) You will see a table displaying all past executions for that agent, sorted by date with the most recent entries at the top. *** ## Understanding the Execution History Table The Execution History table contains the following columns: | Column | Description | | - | - | | **Date** | Timestamp of when the agent execution occurred (e.g., `Feb 19, 2026 03:10 PM`). | | **Triggered By** | The user or process that initiated the execution. Displays the name of the user for manual triggers (e.g., via the Actions menu) or auto-trigger events. | | **Incident** | The incident number the agent processed. Displayed as a clickable link (e.g., `#149631`) that navigates directly to the incident detail page. | | **Source** | The data source the incident originated from (e.g., `Microsoft Sentinel`, `Microsoft Defender for Endpoint`). | | **Severity** | The severity level of the incident: **High**, **Medium**, **Low**, or **Informational**. | | **Tokens** | The number of AI tokens consumed during the execution. Displays `—` if the execution did not complete successfully. | | **Status** | The current state of the execution, displayed as a color-coded badge. | ### Execution Statuses | Status | Color | Description | | - | - | - | | **Completed** | 🟢 Green | The agent successfully finished processing the incident. | | **Running** | 🔵 Blue | The agent is currently processing the incident. | | **Failed** | 🔴 Red | The execution encountered an error and did not complete. Token count will show `—`. | *** ## Using Execution History ### Investigate a Processed Incident Click any **Incident** link (e.g., `#149631`) in the table to navigate directly to that incident's detail page. From there, you can review the full incident timeline, entity context graph, and any Gamebook actions that were executed. ### Identify Failed Executions Filter or scan for rows with a **Failed** status. Failed executions typically show `—` in the Tokens column, indicating the agent did not complete its analysis. Common causes include: | Possible Cause | What to Check | | - | - | | Agent Center infrastructure issue | Verify the Logic App is enabled in the Azure Portal | | Connectivity to data source | Confirm the workspace module consent is active | | Token or rate limit exceeded | Review token consumption trends in recent executions | | Incident no longer available | Check if the incident was deleted or merged in the source system | If failures persist, contact [support@contraforce.com](mailto:support@contraforce.com) with the agent name, affected incident numbers, and the timestamps of the failed executions. ### Monitor Token Consumption The **Tokens** column shows how many AI tokens were consumed per execution. This helps you understand the complexity of agent processing and monitor usage. Executions that involve larger incidents with more entities and evidence will typically consume more tokens. To see token usage across your workspaces for the billing cycle and set a monthly token budget, use the [Cost Management Center](/guides/general-support/cost-management-center). > [!TIP] > > Compare token counts across similar incidents to establish a baseline. Unusually high token usage on a routine incident may indicate the agent is processing excessive data or encountering retry loops. *** ## Best Practices > **Review execution history regularly** > > Check the Execution History tab periodically to confirm agents are processing incidents as expected. Look for patterns in failures, unexpected token spikes, or gaps in execution activity. > **Investigate repeated failures on the same incident** > > If the same incident appears multiple times with a Failed status, the issue is likely environmental (permissions, connectivity) rather than incident-specific. Check the troubleshooting table above. > **Use execution data for compliance reporting** > > The Execution History table serves as an audit trail for automated response activity. Use it to demonstrate that incidents were triaged and processed within your SLA requirements. > **Correlate with Gamebook activity** > > Cross-reference Execution History entries with the Gamebook Activity widget on the Command Dashboard to verify that agent-initiated Gamebooks completed successfully. *** ## Troubleshooting | Issue | Possible Cause | Solution | | - | - | - | | No entries in Execution History | Agent has not processed any incidents yet | Verify the agent Mode is set to **On Queue**, or manually trigger an investigation from an incident's **Actions** menu | | All executions show Failed | Agent Center infrastructure issue | Check that the Logic App is enabled in the Azure Portal and that Microsoft Foundry resources are healthy | | Incident link returns an error | Incident was deleted or merged | Verify the incident exists in the source system (Sentinel or Defender for Endpoint) | | Token column shows `—` | Execution failed before completion | Review the Status column — failed executions do not record token usage | | Execution History tab not visible | Feature not available in your environment | Confirm Agent Center is deployed and you have the required roles | *** ## Related Guides > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up and configure agents using the three-phase adoption model. > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy the Microsoft Foundry infrastructure required for agents. > **[Incident Management](/guides/getting-started/incident-management)** > > Learn how incidents flow through ContraForce. > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Monitor agent activity and incident trends from mission control. > **[SOPs](/guides/agent-center/operating-procedures)** > > Upload Classification and Response SOPs and link them to your agents. > **[Agent Shifts](/guides/agent-center/agent-shifts)** > > Set the weekly hours when an agent investigates incidents on its own. *** Questions about Agent Execution History? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Agent Investigation Completed Webhook Source: https://docs.contraforce.com/guides/agent-center/agent-investigation-webhook Verify and parse the agent.investigation.completed.v1 webhook, then route a Security Delivery Agent's verdict to your SIEM, ticketing, or on-call tools. When a Security Delivery Agent finishes investigating an incident, ContraForce can send a signed webhook to an endpoint you control. Use it to escalate true-positive incidents into your SIEM, ticketing, or on-call tooling at the moment the agent reaches a verdict. > [!NOTE] > > This event is configured per classification on an Agent Configuration card, not as a broadcast subscription. It is delivered **only** to the webhook a classification card points to. Set it up under [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) by enabling **Advanced** mode and choosing a webhook as the **custom action** for a classification. *** ## When It Fires The event fires once per investigation, when the agent completes and reaches a classification, for any classification whose policy has a webhook custom action configured. The event type (schema) is: ``` agent.investigation.completed.v1 ``` *** ## Request Headers Every delivery includes these headers. Use them to verify authenticity before trusting the body. | Header | Value | Notes | | - | - | - | | `X-CF-Schema` | `agent.investigation.completed.v1` | The event type. | | `X-CF-Event-Id` | A unique event identifier (GUID) | Use it to deduplicate retries. | | `X-CF-Timestamp` | ISO 8601 timestamp | Reject if it is more than 5 minutes from your clock. | | `X-CF-Signature` | Base64-encoded HMAC-SHA256 signature | See verification below. | | `X-CF-Test` | `true` | Present only for test deliveries. | | `Authorization` | `Bearer ` or `Basic ` | Present only if you configured authentication on the webhook. | > [!WARNING] > > Retries reuse the same `X-CF-Event-Id`. Treat delivery as at-least-once and make your handler idempotent. *** ## Verifying the Signature The signature covers the timestamp and the exact raw request body: ``` signature = Base64( HMAC_SHA256( signing_key, X-CF-Timestamp + "." + raw_body ) ) ``` The `signing_key` is the secret shown once when the webhook was created, unless you supplied your own signing token override when setting bearer-token credentials, in which case it is that token. **1. Read the raw body** Compute the signature over the unparsed request body bytes, before any JSON deserialization. **2. Recompute** Concatenate the `X-CF-Timestamp` value, a literal `.`, and the raw body. HMAC-SHA256 it with your signing key and Base64-encode the result. **3. Compare in constant time** Compare your value to `X-CF-Signature` using a constant-time comparison. Reject on mismatch. **4. Check the timestamp** Reject the request if `X-CF-Timestamp` is more than 5 minutes from current time, to limit replay. ```python verify.py theme={null} import base64, hashlib, hmac, time from datetime import datetime, timezone def verify(signing_key: str, headers: dict, raw_body: bytes) -> bool: ts = headers["X-CF-Timestamp"] sent = headers["X-CF-Signature"] signed = ts.encode() + b"." + raw_body expected = base64.b64encode( hmac.new(signing_key.encode(), signed, hashlib.sha256).digest() ).decode() if not hmac.compare_digest(expected, sent): return False age = abs(time.time() - datetime.fromisoformat(ts).replace(tzinfo=timezone.utc).timestamp()) return age <= 300 ``` ```csharp Verify.cs theme={null} static bool Verify(string signingKey, string timestamp, string sentSignature, byte[] rawBody) { var signed = System.Text.Encoding.UTF8.GetBytes(timestamp + ".") .Concat(rawBody).ToArray(); using var hmac = new System.Security.Cryptography.HMACSHA256( System.Text.Encoding.UTF8.GetBytes(signingKey)); var expected = Convert.ToBase64String(hmac.ComputeHash(signed)); var match = System.Security.Cryptography.CryptographicOperations.FixedTimeEquals( System.Text.Encoding.UTF8.GetBytes(expected), System.Text.Encoding.UTF8.GetBytes(sentSignature)); var age = Math.Abs((DateTimeOffset.UtcNow - DateTimeOffset.Parse(timestamp)).TotalSeconds); return match && age <= 300; } ``` *** ## Payload The body is JSON with camelCase fields. Like every ContraForce webhook, the event-specific payload is nested under `data` inside a common envelope: ```json theme={null} { "type": "agent.investigation.completed.v1", "timestamp": "2026-08-03T14:31:09.740Z", "isTest": false, "occurredAt": "2026-08-03T14:31:02.310Z", "data": { "workspace": { "id": "00000000-0000-0000-0000-000000000000", "alias": "contoso", "name": "Contoso Production" }, "agent": { "id": "agent-identifier", "name": "Tier 1 Triage Agent" }, "incident": { "id": "source-system-incident-id", "number": 4242, "source": "Sentinel", "title": "Suspicious sign-in from impossible travel", "severity": "High", "status": "Active" }, "verdict": { "classificationBucket": "TruePositive", "classificationReason": "MaliciousActivity", "classificationReasonComment": "Confirmed credential theft", "comment": "Sign-in originated from a known-malicious ASN minutes after a login from the user's usual location.", "maliciousScore": 87 }, "gamebookRecommendation": { "incidentNumber": 4242, "incidentTitle": "Suspicious sign-in from impossible travel", "playbooks": [ { "playbookId": "disable-user", "affectedEntity": "Account", "entityId": "jdoe@contoso.example", "sequence": 1 } ] } } } ``` > [!WARNING] > > Sign and verify the full raw body, envelope included. Do not compute the signature over the `data` object alone. ### Fields Field paths below are relative to `data`. | Field | Type | Description | | - | - | - | | `workspace.id` / `alias` / `name` | string | The ContraForce workspace the incident belongs to. | | `agent.id` / `name` | string | The Security Delivery Agent that ran the investigation. | | `incident.id` | string | The source system's incident identifier. | | `incident.number` | number | The incident number shown in the portal. | | `incident.source` | string | Detection source, for example `Sentinel`. | | `incident.title` | string | Incident title. | | `incident.severity` | string | Incident severity, for example `High`. | | `incident.status` | string | Incident status at completion. | | `verdict.classificationBucket` | string | The agent's verdict. One of `TruePositive`, `BenignPositive`, `FalsePositive`, `Undetermined`. | | `verdict.classificationReason` | string \| null | Reason code for the classification. | | `verdict.classificationReasonComment` | string \| null | Free-text reason detail. | | `verdict.comment` | string | The agent's investigation summary comment. | | `verdict.maliciousScore` | number \| null | How malicious the agent judged the incident, on a 0-100 scale. `null` when the investigation came through the legacy agent path, which collects no score. | | `gamebookRecommendation` | object \| null | Present only when the agent recommended Gamebooks. | | `gamebookRecommendation.playbooks[]` | array | Recommended Gamebooks, each with `playbookId`, `affectedEntity`, `entityId`, and `sequence`. | > [!TIP] > > Branch on `verdict.classificationBucket`. It is a stable, vendor-neutral value, so your integration does not need to handle source-specific classification strings. Use `verdict.maliciousScore` when you need degree rather than category, for example auto-closing below a threshold and paging above one. > [!WARNING] > > `maliciousScore` measures **maliciousness**, not the agent's confidence. A verdict the agent is completely certain is a False Positive scores near **0**, not near 100. See the [webhook event reference](/api-reference/webhook-events#malicious-score) for the score bands. *** ## Testing Use the **Send test** action on the webhook in **Developers** to deliver a synthetic event (see [Setting Up Webhooks](/guides/technical/configure-webhooks#send-a-test-and-check-the-delivery)). Test deliveries carry `X-CF-Test: true` and use sample data. They are signed identically to live events, so you can validate your verification code end to end. *** ## Troubleshooting | Symptom | Likely cause | Resolution | | - | - | - | | No events arrive | The classification card does not point to this webhook, or Advanced mode is off | Confirm the webhook is set as the custom action for the classification and that Advanced mode is enabled and saved | | Events stop arriving | The webhook was deleted, paused, disabled, or unsubscribed | The classification card shows a binding warning. Fix the webhook in Developers. Skipped deliveries are recorded as **Failed** in the delivery log, not dropped silently | | Signature check fails | Verifying a parsed body instead of the raw bytes, or using the wrong key | Sign the raw request body, and use the signing token override if one was set | | Duplicate events | Normal retry behavior | Deduplicate on `X-CF-Event-Id` | *** ## Other Event Types This is one of five events ContraForce can deliver. For the complete list, including incident creation, incident closure, and Gamebook runs, see the [Webhook Event Reference](/api-reference/webhook-events). *** ## Related Guides > **[Setting Up Webhooks](/guides/technical/configure-webhooks)** > > Create a webhook in Settings → Developers, send a test, and manage deliveries > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Configure agents and choose a webhook as a classification's custom action > **[Webhook Event Reference](/api-reference/webhook-events)** > > Every event type, the delivery envelope, headers, and retry rules > **[Classification Mapping](/concepts/incident-classification)** > > How each classification maps to Sentinel, Defender XDR, and SentinelOne values *** > [!NOTE] > > Questions about the agent investigation webhook? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Agent Shifts: Schedule AI Agent Working Hours Source: https://docs.contraforce.com/guides/agent-center/agent-shifts Schedule when a Security Delivery Agent investigates on its own by painting working hours on a weekly grid. Off shift, new incidents wait for your team. Agent Shifts answer a simple question: **when should this agent investigate on its own?** For an agent already configured to pick up incidents automatically, paint its working hours on a weekly grid, and outside those hours new incidents wait for your team instead. Anyone can still start an investigation manually at any time. > [!NOTE] > > A shift bounds automatic pickup; it does not enable it. An agent investigates on its own only when its own configuration says to process incidents automatically for the incident's severity, and a shift then decides **when** that happens. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) for the automatic-processing configuration itself. > [!NOTE] > > **Who is this for?** Workspace Owners create and manage shifts. Everyone using Agent Center benefits from the visibility: each agent shows whether it is on shift right now, so an untouched incident reads as "off shift by design" rather than "something is broken". Shifts are managed with the workspace's investigation policies: in **Workspace Center** on the workspace's **Agents** tab, or directly on an agent's **Policies** tab. The on-shift and off-shift state appears in **Agent Center**. *** ## Creating a shift **1. Open the investigation policies** In **Workspace Center**, open the workspace and select the **Agents** tab, or open the agent in **Agent Center** and select its **Policies** tab. **2. Add a shift** Click **Add policy**, then choose **Add a shift**. The shift editor opens with the most common schedule already painted: Monday to Friday, 9:00 to 17:00. **3. Paint the working hours** Click an hour to toggle it, or click and drag to paint a range. The **Weekdays 9:00 to 17:00** button restores the standard week, and **Clear** empties the grid. **4. Pick the timezone** The schedule keeps these wall-clock hours year round in the timezone you choose, which defaults to your own. Daylight saving changes never shift the working hours. **5. Name it and save** The live preview reads the schedule back in plain words, for example "Investigates on its own between 09:00 and 17:00 on weekdays (Berlin time)." Save, and the shift appears as a row in the policy list. > [!NOTE] > > A shift with **no hours painted** means the agent never investigates on its own; your team triggers every investigation manually. A shift covering **every hour of the week** cannot be saved, because it would not limit anything. *** ## How shifts behave * **Outside the shift, new incidents wait for people.** An automatically triggered investigation outside the painted hours is skipped, the incident stays in your queue, and the skip is recorded in the workspace audit trail. Nothing re-runs it automatically when the shift resumes; off-shift work belongs to your team. * **Manual triggering always works.** A person can start an investigation at any hour, on or off shift. Shifts schedule the agent's autonomy, never your team's access to it. * **Shifts are policy rows.** Each shift appears in the investigation policy list with a **Shift** badge and its schedule sentence, and can be reordered, turned off, or deleted like any policy. See [Workspace Policies](/guides/getting-started/workspace-policies) for how ordering works. > [!TIP] > > Because the list is checked top to bottom and the first fit wins, an **Allow** policy placed above a shift can let specific incidents through even off shift. For example, allow incidents whose title contains "impossible travel" around the clock, while everything else waits for the morning. *** ## Editing and converting a shift **Editing** a shift always reopens the schedule grid with the stored hours painted exactly as saved. If a schedule stops being enough, convert the shift into a general policy: open the shift and choose **Edit as a general policy**. Conversion keeps what the policy does but swaps the grid for the condition builder, where you can add incident conditions alongside the schedule. Conversion is one way; a converted policy cannot become a shift again, which the confirmation states before anything changes. *** ## On-shift and off-shift in Agent Center Agent Center shows each agent's current state wherever the agent appears: * **The agents table** shows a subtle **On shift** or **Off shift** chip next to the agent's status. Hover it for the full sentence, including when the state next changes, for example "Off shift. New incidents wait for people until Monday 09:00 (Berlin time); anyone can still start an investigation." * **The agent's overview** shows the same chip beside the deployment status, plus a **Shift** row with the full sentence. The state is computed from the same rules that govern the agent, so what the badge says is what the agent will do. A few deliberate behaviors: * **Agents without shifts show nothing.** No badge, no noise. Most agents run around the clock, and the absence of a chip means exactly that. * **Only operational agents show a state.** A paused or undeployed agent is not working regardless of the clock, so its shift state is not shown. * **The state is read at page load.** It refreshes when you reload or revisit the page; there is no live ticker. *** ## Roles and permissions | Role | Permissions | | - | - | | Workspace Owner | Create, edit, reorder, enable or disable, delete, and convert shifts | | Organizational Admin, Agent Admin | See shift state in Agent Center; read the agent's policy list | | Other roles | See shift state in Agent Center | *** ## Frequently asked questions > **What happens to incidents that arrive off shift?** > > They stay in your incident queue like any other incident, and the skipped automatic investigation is recorded in the workspace audit trail. When the shift resumes, the agent picks up newly arriving incidents; it does not go back through the queue on its own. > **Can I trigger an investigation while the agent is off shift?** > > Yes, always. Manual triggering is never blocked by a shift. That is the point of a shift: it schedules autonomy, not access. > **Does creating a shift make my agent start picking up incidents automatically?** > > No. Automatic pickup comes from the agent's own configuration, which says which incident severities it processes automatically. A shift bounds when an agent configured that way works on its own; for an agent without automatic processing, a shift changes nothing. > **Can one agent have multiple shifts?** > > Yes. Each shift is its own policy row, and the agent investigates on its own only in hours every shift allows. Most workspaces need exactly one. > **How do daylight saving changes affect a shift?** > > They do not change the working hours. A 9:00 to 17:00 shift stays 9:00 to 17:00 on the wall clock of its timezone all year. > **Why does an agent show no shift chip?** > > Either its workspace has no shifts, in which case the agent runs around the clock and no state is shown by design, or the agent is currently paused or not deployed. > **Can I turn a general policy into a shift?** > > No. Conversion is one way, from shift to general policy. To schedule with the grid again, create a new shift. *** ## Related guides > **[Workspace Policies](/guides/getting-started/workspace-policies)** > > The ordered allow and block rules that shifts are part of. > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up and configure agents using the three-phase adoption model. > **[Agent Execution History](/guides/agent-center/agent-execution-history)** > > Monitor and audit agent activity with a complete execution trail. > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy the Microsoft Foundry infrastructure required for agents. *** Questions about Agent Shifts? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # On Queue Agents for Defender for Endpoint Source: https://docs.contraforce.com/guides/agent-center/defender-for-endpoint-on-queue Your On Queue Security Delivery Agents pick up new Defender for Endpoint incidents within about 2 minutes, with no Microsoft Sentinel forwarding required. Agent On-Queue for Defender for Endpoint allows ContraForce Security Delivery Agents to automatically detect and respond to incidents originating directly from Microsoft Defender for Endpoint with no Microsoft Sentinel forwarding required. Previously, agents could only auto-trigger on incidents ingested through Sentinel. Customers using Defender for Endpoint directly had to manually trigger agent actions. With this update, ContraForce polls Defender for Endpoint for new incidents approximately every **2 minutes**, automatically triggering your agent to triage and respond in order to deliver the autonomous SOC experience with minimal time-to-respond. > [!TIP] > > If your environment already forwards Defender for Endpoint incidents to Microsoft Sentinel (`FetchToSentinel = true`), your existing agent workflow is unaffected. This feature is designed for environments where Sentinel forwarding is **not** configured. ## How It Works ContraForce continuously polls the Microsoft Defender for Endpoint security API for new incidents across all eligible customer accounts. When a new incident is detected: 1. The platform identifies the incident and checks it against previously processed incidents to prevent duplicates. 2. A notification is queued for processing. 3. ContraForce validates that the account has a deployed agent with the appropriate severity capability for the incident. 4. The agent is automatically triggered on-queue to investigate and respond — just as it would for Sentinel-ingested incidents. The entire pipeline runs automatically. No manual intervention is required once configured. ## Prerequisites Before Agent On-Queue for Defender for Endpoint can activate for a workspace, **all** of the following must be true: **1. Active Subscription** The account must have an **Active** or **Trial** ContraForce subscription. **2. Defender for Endpoint Module Enabled** The Defender for Endpoint security provider must be enabled for the workspace. See [Defender for Endpoint Module Deployment](/guides/onboarding/defender-for-endpoint-module-deployment) for setup instructions. **3. Module Consent Granted** Microsoft consent must be granted for the Defender for Endpoint module. This is the same single **Consent** action completed on the **Modules** tab when deploying the Defender module, granted by a **Global Administrator**. **4. Sentinel Forwarding Disabled** The workspace must **not** be configured to forward Defender for Endpoint incidents to Sentinel. If `FetchToSentinel` is enabled, incidents are ingested through the existing Sentinel pipeline instead. **5. Agent Deployed with ProcessIncident Capability** A Security Delivery Agent must be deployed via [Agent Center](/guides/onboarding/agent-center-deployment) with the **ProcessIncident** capability enabled for the target incident severity levels (High, Medium, Low, Informational). > [!TIP] > > Not sure if your workspace meets these requirements? Select **Agents** in the left navigation (the Agent Center) and verify the agent's **Mode** is **On Queue** for the severities it should handle. If the agent is deployed but not processing Defender for Endpoint incidents, review the prerequisites above. ## What Changes for You ### If you use Defender for Endpoint without Sentinel This is the feature for you. Once the prerequisites are met, your agent will begin automatically processing Defender for Endpoint incidents within approximately 2 minutes of their creation. No configuration changes are needed on your end — the platform handles everything. ### If you already forward to Sentinel Nothing changes. Your incidents continue to flow through the Sentinel ingestion pipeline as before. The Defender for Endpoint polling pipeline automatically excludes accounts with Sentinel forwarding enabled. ### If you use both Accounts are evaluated individually. Workspaces with Sentinel forwarding enabled use the Sentinel pipeline. Workspaces without Sentinel forwarding use the new Defender for Endpoint polling pipeline. There is no overlap or duplicate processing. ## Configuring Your Agent for Defender for Endpoint Incidents If you already have a Security Delivery Agent deployed and configured, no additional setup is required. The platform automatically detects eligible workspaces and begins polling. To deploy or configure an agent: 1. Select **Agents** in the left navigation to open the Agent Center. 2. Deploy your agent following the [Agent Center Deployment](/guides/onboarding/agent-center-deployment) guide. 3. Open the agent's configuration and set **Mode** to **On Queue** for each severity the agent should handle automatically. 4. Set the agent mode to **On Queue**. Once the agent is on-queue with ProcessIncident enabled, ContraForce will begin polling Defender for Endpoint and triggering the agent for matching incidents. > [!TIP] > > For a phased rollout, start with the agent in **Manual** mode where the agent suggests actions and you approve. Once you're confident in the response quality, move to **Automatic** or **Full Autonomous** mode. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) for details on agent modes. ## Verifying It's Working After setup, confirm that the pipeline is active: 1. **Check Agent Center** — Verify your agent status shows **On Queue** and the mode is set to your preferred level (Manual, Automatic, or Autonomous). 2. **Monitor the Command Dashboard** — New Defender for Endpoint incidents should appear on the [Command Dashboard](/guides/getting-started/command-dashboard) within approximately 2 minutes of creation in Defender. 3. **Review Gamebook Activity** — When the agent processes an incident, you'll see corresponding Gamebook activity in the [Gamebook Activity](/guides/getting-started/what-are-gamebooks) widgets and the incident's Workbench. 4. **Check Agent Execution History** — Navigate to Agent Center to review the agent's [execution history](/guides/agent-center/agent-execution-history) and confirm incidents are being processed. ## Incident Detection Timing ContraForce polls Defender for Endpoint approximately every **2 minutes**. This means: * New incidents are typically detected within 2 minutes of appearing in Defender for Endpoint. * The agent is triggered immediately after detection and validation. * End-to-end time from incident creation to agent response initiation is typically **under 5 minutes**. ## Troubleshooting | Issue | Likely Cause | Resolution | | - | - | - | | Agent not processing Defender for Endpoint incidents | Agent not set to "On Queue" mode | In the Agent Center (**Agents** in the left navigation), set **Mode** to **On Queue** for the severity | | Incidents not appearing from Defender for Endpoint | Module consent not granted | Re-run the **Consent** action from the workspace **Modules** tab using **Global Administrator** credentials | | Duplicate incidents appearing | Sentinel forwarding is also enabled | Verify the workspace is not forwarding Defender for Endpoint incidents to Sentinel. Only one ingestion path should be active | | Agent triggers for wrong severity levels | ProcessIncident capability misconfigured | Review the agent's severity capability settings in **Agent Center** and adjust which severity levels are handled | | No incidents detected despite active Defender for Endpoint incidents | Account eligibility not met | Verify all [prerequisites](#prerequisites) are satisfied — subscription status, module enablement, module consent, and agent deployment | | Agent was working but stopped processing | Subscription lapsed or consent revoked | Confirm subscription is still Active/Trial and re-grant module **Consent** if needed | If the issue persists after reviewing the above, contact [**support@contraforce.com**](mailto:support@contraforce.com) or [submit a support ticket](/submit-ticket) with: * Workspace name * Agent status screenshot from Agent Center * Approximate timestamp of the incident that was not processed * Any error messages visible in the portal ## Frequently Asked Questions **Do I need to change anything if I'm already using Sentinel?** No. If your workspace forwards Defender for Endpoint incidents to Sentinel, your existing pipeline continues to work. The Defender for Endpoint polling pipeline automatically skips your account. **Can I use both Sentinel and direct Defender for Endpoint ingestion for the same workspace?** No. Each workspace uses one ingestion path. If Sentinel forwarding is enabled, incidents come through Sentinel. If it's disabled, incidents come through the Defender for Endpoint polling pipeline. This prevents duplicate processing. **What response actions are available for Defender for Endpoint incidents?** The same Gamebook response actions available for any incident — device isolation, account disabling, password resets, IP/URL blocking, file quarantine, email deletion, and more. See the [Microsoft Defender Capability Matrix](/guides/technical/microsoft-defender-capability-matrix) for the full list based on your license. **Is there any additional cost for this feature?** No. Agent On-Queue for Defender for Endpoint is included with your existing ContraForce subscription and agent deployment. No additional modules or licenses are required beyond the standard Defender module and Agent Center. **What happens if the polling service restarts?** Polling state is persisted per account. If the service restarts, it resumes from the last known position with a configurable overlap window to ensure no incidents are missed. *** ## Related Guides > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set each agent's Mode per severity and when it can run Gamebooks > **[Defender Native Automations](/guides/technical/microsoft-defender-native-automations)** > > How Security Delivery Agents defer to Defender AIR, ZAP, and attack disruption > **[Agent Shifts](/guides/agent-center/agent-shifts)** > > Schedule the hours when an agent picks up incidents on its own > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy the Defender for Endpoint module and confirm incidents sync > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # SOPs for Security Delivery Agents Source: https://docs.contraforce.com/guides/agent-center/operating-procedures Upload Classification and Response SOPs or start from templates, then link them to Security Delivery Agents so they follow your policies. Upload your team's standard operating procedures (SOPs) directly into ContraForce, then associate them with AI Agents so every incident is handled according to your organization's specific policies. > [!NOTE] > > **Who is this for?** Organizational Admins and Agent Admins who manage Security Delivery Agents and want to standardize incident classification and response procedures. Select **SOPs** in the left navigation menu. The page has three tabs: **My SOPs** (your library), **Templates** (ready-made procedures to start from), and **Audit** (a history of changes). *** ## SOP Types ContraForce supports two types of SOPs, each designed for a different phase of incident handling. ### Classification SOPs Classification SOPs define how incidents should be categorized and prioritized. These contain your organization's specific severity definitions, escalation criteria, and triage procedures. Each AI Agent can have **multiple** Classification SOPs associated with it, but only **one** Classification SOP is activated per investigation. This ensures that every incident processed by that Agent follows a single, consistent classification standard while giving you the flexibility to maintain several classification approaches for different scenarios. ### Response SOPs Response SOPs cover how to respond to and remediate security incidents. These include containment steps, investigation workflows, communication protocols, and recovery steps. Each AI Agent can have **multiple** Response SOPs associated with it, and each Response SOP can be shared across **multiple** Agents. This many-to-many relationship means you can assign your phishing response playbook to three different Agents without duplicating the document. *** ## Supported File Formats You can upload the following document formats: | Format | Extensions | | - | - | | Markdown | `.md` | | Plain Text | `.txt` | Additional formats (PDF, Word, HTML, RTF) are coming soon. Maximum file size is 10 MB per document. *** ## Uploading an SOP **1. Open SOPs** Select **SOPs** in the left navigation menu. **2. Start the upload** Select **Add SOP**. **3. Select the SOP type** Choose either **Classification** or **Response** to categorize the SOP. This determines how it can be associated with AI Agents. **4. Upload the file** Drag and drop your file into the upload area, or click to browse and select a file from your computer. **5. Add metadata** Enter a **title** for the SOP. Optionally, add **tags** for easier searching and organization, and map it to relevant **MITRE ATT\&CK** techniques. **6. Save** Click **Save** to upload the SOP. ContraForce extracts and indexes the document content automatically. *** ## Viewing SOP Content After uploading, you can view the full content of any SOP directly within ContraForce without switching to an external application. 1. Open **SOPs** from the left navigation menu. 2. Click on any SOP in the list to open the detail view. 3. The detail panel displays the extracted document content, metadata (type, tags, MITRE ATT\&CK mappings, version), and timestamps. You can also download the original file at any time from the detail view. *** ## Associating SOPs with AI Agents You can create these associations from either direction. ### From the SOP detail page 1. Open the SOP you want to associate. 2. Select the **Linked Agents** tab. 3. Click **Add Agent** and select one or more AI Agents from the list. 4. The association takes effect immediately. ### From the Agent detail page 1. Select **Agents** in the left navigation (the Agent Center) and configure the agent from the **Agents** tab. 2. Select the **SOPs** tab. It lists the agent's **Classification SOP** and **Response SOPs**. 3. Select **Manage in SOPs** to associate SOPs from the SOPs page. 4. You can associate multiple Classification SOPs with an Agent, but only one will be activated per investigation. > [!NOTE] > > Changes to these associations take effect immediately. There is no separate publish or deploy step. *** ## Updating an SOP In-place editing is not supported. To update an SOP, upload a new version of the file. All existing Agent associations are preserved when you update the document. Use the **version** field on the SOP to track changes over time. *** ## Searching and Filtering SOPs The SOP list view provides several ways to find the right document quickly: * **Search** by title or content keywords. * **Filter by type** to show only Classification or Response SOPs. * **Sort** by last updated date, title, or associated agent count. Each card in the list displays the type, associated agent count, tags, and last updated timestamp. *** ## Roles and Permissions SOP access follows the ContraForce role-based access control model. | Role | Permissions | | - | - | | Organizational Admin | Full access: create, view, update, and delete SOPs | | Agent Admin | Full access: create, view, update, and delete SOPs | | Workspace roles (for example Incident Analyst, Incident Responder) | View SOPs associated with Agents they have access to | *** ## How AI Agents Use SOPs When an AI Agent processes an incident, it retrieves the content from its associated SOPs to inform its investigation and response decisions. This means the Agent follows your organization's specific procedures rather than relying on generic response patterns. * **Classification SOPs** guide how the Agent categorizes incident severity and priority. * **Response SOPs** guide the specific containment, investigation, and remediation steps the Agent recommends or executes. > [!TIP] > > For best results, write your SOPs with clear, structured headings and step-by-step procedures. The more structured your document, the more effectively the AI Agent can reference the relevant section during incident handling. *** ## Best Practices **Start with your most critical playbooks.** Upload the SOPs your team uses most frequently first, such as phishing response, ransomware containment, and business email compromise procedures. **Use tags consistently.** Apply tags like `phishing`, `ransomware`, `insider-threat`, or `data-exfiltration` so they are easy to find and can be matched to relevant incidents. **Map to MITRE ATT\&CK techniques.** Associating SOPs with specific techniques helps surface the right procedure when an incident involves those techniques. **Keep each procedure focused.** Rather than uploading one massive document covering everything, split your procedures by incident type or response phase. This makes Agent associations more precise and retrieval more effective. **Review and update regularly.** Upload new versions as your procedures evolve. ContraForce preserves all Agent associations when you update a document. *** ## Frequently Asked Questions > **Is there a limit to how many SOPs I can upload?** > > There is no hard limit on the number of SOPs per workspace. We recommend organizing them thoughtfully and associating only the most relevant procedures with each Agent. > **Can I associate one SOP with multiple Agents?** > > Yes. Both types support many-to-many associations, so a single SOP can be linked to multiple Agents. For Classification SOPs, multiple can be associated with an Agent, but only one is activated per investigation. > **What happens if I delete an SOP that is associated with an Agent?** > > The association is removed automatically. The Agent will continue to function but will no longer reference that procedure during incident handling. > **Can I share SOPs across workspaces?** > > SOPs are scoped to individual workspaces. To use the same procedure in multiple workspaces, upload the document to each workspace separately. > **Do I need to redeploy my Agent after associating an SOP?** > > No. These associations take effect immediately. There is no redeployment or restart required. *** ## Related Guides > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up and configure agents using the three-phase adoption model. > **[Agent Execution History](/guides/agent-center/agent-execution-history)** > > Monitor and audit agent activity with a complete execution trail. > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy the Microsoft Foundry infrastructure required for agents. > **[Incident Management](/guides/getting-started/incident-management)** > > Learn how incidents flow through ContraForce. *** Questions about SOPs? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Detection Rule Change Requests and Approvals Source: https://docs.contraforce.com/guides/content-management-center/change-requests Review, approve, and merge detection rule change requests in a protected repository, with field-level diffs, required approvals, and audit evidence. In a repository with [baseline protection](/guides/content-management-center/repositories#baseline-protection) enabled, changes do not take effect when you make them. They collect as work in progress, get grouped into a change request, and require approval before merging. This gives detection content the same review discipline as code, and gives you an evidence trail when someone asks who approved a change and on what basis. ## The flow ``` edit ──> work in progress ──> change request ──> review ──> merge │ │ │ └──> changes requested ──┐ │ │ └───────────────────────────────────────┘ ``` **1. Make a change** Import, author, edit, or reconcile a rule. In a protected repository the result lands in **Work in progress** rather than changing the rule. **2. Group into a change request** From **Work in progress**, add one or more items to a new or existing change request. Give it a title and description. **3. Submit for review** Submitting moves it from **Draft** to **Open** and makes it visible to approvers. **4. Review** Approvers read the diff, comment, then **approve** or **request changes**. **5. Merge** Once it has enough approvals, merging commits every item to the repository. ## Work in progress The **Work in progress** tab holds edits that have not yet been proposed. Each item records the rule, the kind of change (**added**, **modified**, or **removed**), and its current revision. An item is editable while it is work in progress: open it, keep refining, and it stays out of everyone's way until you add it to a change request. **Discard** it if you change your mind and nothing about the baseline has changed. Items show as **Unassigned** until they belong to a change request. Select several and **Add to change request** to bundle them, which is the usual shape: one request carrying a set of related edits rather than one per rule. ![Work in progress tab with two modified rules selected, showing Add to change request and Discard actions](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/work-in-progress.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=3e81e3906ad8c40d81b10ec14d7a49db) ## Change request states | State | Meaning | | - | - | | **Draft** | Being assembled. Not yet visible for review. | | **Open** | Submitted and awaiting review. | | **Changes requested** | A reviewer wants revisions before approving. | | **Approved** | Has the approvals it needs and can be merged. | | **Merging** | Merge in progress. | | **Merged** | Committed to the repository. | | **Closed** | Abandoned without merging. | | **Conflicted** | The repository moved underneath it and it can no longer merge cleanly. | > [!NOTE] > > **Conflicted** usually means another change request touching the same rule merged first. > Resolve it by revising the affected items against the current state of the rule. ## Reviewing A change request shows: * **Changes** — a field-level diff for every item, old value beside new, plus the rule query * **Review summary** — the approval count against the requirement, the author, and a box for an optional review note * **Audit evidence** — the sequence of what happened: revisions added, work items attached, submissions for review, each stamped with who and when * **Conversation** — comments, including comments anchored to a specific item or revision A **Merge requirements** banner states plainly whether the request can merge yet, so a reviewer is never left guessing why the merge action is unavailable. ![An open change request showing a merge requirements banner, field-level diffs for a modified rule, a review summary with approvals 0 of 1, and an audit evidence panel](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/change-request-review.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=20222513f5a341ee6c86a09e1f4569ca) A reviewer can **approve** or **request changes**, each with a comment. Requesting changes moves the request to **Changes requested** and blocks the merge until it is revised. **Edit change** on an item lets a reviewer revise it in place rather than sending it back. ### Who can approve Approvers are configured per repository under [protection settings](/guides/content-management-center/repositories#protection-settings). Two constraints apply: * The change request needs at least the **required approval count**. * The author may only approve their own request if **allow author approval** is enabled, which it is not by default. > [!WARNING] > > If your change request is stuck in **Open** with nobody able to approve it, check the > repository's approver list. A repository with required approvals set higher than the number > of configured approvers cannot merge anything. ## External change references A change request can carry an **external CAB reference** for organizations that track detection changes in a separate change-management system. Record the ticket identifier there and the two records stay tied together. ## Merging Merging applies every item in the request to the repository, committing each as a new version of its rule. From that point the changes behave like any other committed content: they can be deployed, rolled back, and compared. Merging changes the repository, not your workspaces. Deploy afterwards to push the merged content out. See [Deploy](/guides/content-management-center/rules#deploy). ## Reviewing across repositories The Content Management Center's top-level **Change requests** tab lists open requests across every repository you can see, so reviewers do not have to visit each repository to find what is waiting on them. *** ## Related Guides > **[Repositories](/guides/content-management-center/repositories)** > > Turn on baseline protection, set required approvals, and choose repository approvers. > **[Rules](/guides/content-management-center/rules)** > > Deploy merged rules to covered workspaces, review version history, and roll back. > **[Workspace coverage and drift](/guides/content-management-center/workspace-coverage)** > > Scan workspaces for drift and reconcile rules changed outside ContraForce. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Detection Rule Template Marketplace Source: https://docs.contraforce.com/guides/content-management-center/marketplace Browse ContraForce-maintained detection rule templates by data source, preview a template, pull it into your repository, and tune it before you deploy. The marketplace is a catalog of detection rule templates maintained by ContraForce. Use it to stand up coverage for a data source quickly rather than writing every rule yourself. ## Browsing by data source The catalog is organized **by data source** rather than by rule, because the question driving it is usually "we just connected Azure Key Vault, what should we be detecting?" Each data source shows how many templates it carries. Select one to see its templates. ![Marketplace tab showing data source cards such as AWS CloudTrail, Azure Activity and Microsoft Entra ID, each with a template count](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/marketplace-sources.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=20cd3df3e18fbe05281019e9462c76bd) For each template you can see its **name**, **severity**, **MITRE ATT\&CK tactics**, and **version**, and open a **preview** of the full rule content before taking it. ## Pulling a template into a repository **1. Preview the rule** Read the query and the entity mappings. A template is a starting point, not something to deploy unread. **2. Choose a destination repository** Select the repository the rule should land in. You need the **Author** permission on it. **3. Add to repository** In an unprotected repository the rule is added immediately. In a protected one it arrives as work in progress and needs a [change request](/guides/content-management-center/change-requests). Once pulled, the rule is yours: it is an ordinary rule in your repository, and you can edit it, version it, fork it, and deploy it like any other. ## Templates and versions Templates are versioned, and the catalog lists the latest version of each. Pulling takes a copy at that version. > [!NOTE] > > A pulled rule does not stay linked to the template. A later template version does not flow > into repositories that already pulled it, and your edits are never overwritten by a catalog > update. To take a newer template version, pull it again and compare. ## Tuning before you deploy Marketplace templates are written to be broadly correct, not tuned to any one environment. Before deploying to a customer: * Run the **test query** against the target workspace and confirm it returns what you expect * Check the **severity** matches how the customer triages * Check **entity mappings** resolve against their data * Consider whether the rule belongs in a shared repository or as a [fork](/guides/content-management-center/rules#forks) for this customer A template that fires constantly in one workspace and never in another is normal. The marketplace gives you the detection logic; the calibration is yours. *** ## Related Guides > **[Rules](/guides/content-management-center/rules)** > > Test, edit, fork, and deploy a pulled template like any other rule. > **[Change requests](/guides/content-management-center/change-requests)** > > Review and merge templates pulled into a protected repository. > **[Repositories](/guides/content-management-center/repositories)** > > Create the destination repository and choose the workspaces it covers. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Content Management Center for Detection Rules Source: https://docs.contraforce.com/guides/content-management-center/overview Version Microsoft Sentinel and Defender XDR detection rules in the Content Management Center, deploy them to the workspaces you choose, and catch drift. The Content Management Center (CMC) is where detection content lives before it reaches a customer. Rules are stored in **repositories**, versioned as they change, deployed to the workspaces you choose, and continuously compared against what is actually running. It replaces the pattern of editing rules directly in each Microsoft Sentinel or Microsoft Defender XDR tenant, where the only record of a change is the change itself. ## What a repository gives you > **One source of truth** > > A rule has one definition and a version history. Every workspace running it is > running a known version, not a copy that someone edited in place. > **Deployment you control** > > Choose which workspaces a repository covers, deploy a rule to some or all of them, > and roll back to an earlier version. > **Drift detection** > > Scan a workspace and CMC reports the rules that no longer match the baseline, so an > edit made in a vendor console does not stay invisible. > **Review before change** > > Turn on protection and edits stop committing directly. They collect as work in > progress, get bundled into a change request, and require approval. ## The one rule that shapes everything else A repository's rule set is its **baseline**. Baseline protection is either on or off, and that single setting changes how every change behaves. > **Require change requests off** > > A change hits the baseline immediately as a new version. Fast, and appropriate for a > repository one person maintains. > **Require change requests on** > > Additions, edits, removals, imports and marketplace pulls all become **work-in-progress** > items instead. Nothing changes until one is added to a **change request**, approved, and > merged. Everything in [Change requests](/guides/content-management-center/change-requests) follows from that. If you are wondering why your edit did not appear in the rule list, protection is almost always the answer. ## Supported platforms CMC manages two rule platforms, and a repository can hold both. | Platform | Shown as | Deployed to | | - | - | - | | `SentinelAnalytics` | Microsoft Sentinel | Sentinel analytics rules in the target workspace | | `DefenderCustomDetection` | Microsoft Defender XDR | Defender XDR custom detection rules | Each rule carries its platform, and the platform decides how the rule is validated, where its query runs, and which target it deploys to. See [Sentinel and Defender](/guides/content-management-center/platforms). ## How the pieces fit ``` Marketplace ──┐ ├──> Repository ──> Change request ──> Deploy ──> Workspace Import ──────┤ (rules, (when │ Author ──────┘ versions) protected) │ ▲ │ └──────── Drift scan ────────────────────┘ ``` Content enters a repository three ways: pulled from the [Marketplace](/guides/content-management-center/marketplace), imported from a workspace that already runs it, or authored from scratch. It leaves through a deployment. The drift scan closes the loop by reading back what is really running. ## Where to start > **[Create a repository](/guides/content-management-center/repositories)** > > Set one up, choose the workspaces it covers, and configure protection. > **[Add rules](/guides/content-management-center/rules)** > > Import from a workspace, pull from the marketplace, or write your own. > **[Track coverage and drift](/guides/content-management-center/workspace-coverage)** > > See what each workspace is running and reconcile what does not match. > **[Review changes](/guides/content-management-center/change-requests)** > > Work in progress, change requests, approvals, and merges. ## Permissions Access is governed by three organizational content permissions. | You can | Requires | Roles | | - | - | - | | Browse repositories, rules, and the marketplace | Read | Every organization member | | Import, author, and edit rules; deploy; raise and merge change requests | Author | Content Operator, Content Admin, Org Admin | | Create and delete repositories; change baseline protection, covered workspaces, and Sentinel settings | Manage | Content Admin, Org Admin | The practical split: a **Content Operator** can change content, a **Content Admin** can change the rules about how content is changed. # Microsoft Sentinel and Defender XDR Rule Platforms Source: https://docs.contraforce.com/guides/content-management-center/platforms Import, test, and deploy Sentinel analytics rules and Defender XDR custom detections in the Content Management Center, and see which platform a rule needs. CMC manages two rule platforms. A repository can hold both, and each rule carries the platform it targets. | Platform | Shown as | Target | | - | - | - | | `SentinelAnalytics` | Microsoft Sentinel | Analytics rules in a Log Analytics workspace | | `DefenderCustomDetection` | Microsoft Defender XDR | Custom detection rules in the Defender tenant | The platform is set when a rule is created or imported and determines how the rule is validated, which schema its query is checked against, and where a deployment writes. ## Microsoft Sentinel ### Importing Importing lists the analytics rules in the selected workspace and brings the ones you choose into the repository. Scheduled and near-real-time (NRT) rules can be imported, edited and deployed. Other rule types, such as Fusion and Microsoft security incident creation rules, import as read-only content. NRT rules run on a fixed cadence, so they have no query frequency, lookback period or alert threshold. Sentinel ignores those settings on an NRT rule, and drift scans do too. ### Deploying Deployments write analytics rules into the target workspace. A repository can set a **default target workspace** so deployments that do not name one have somewhere to go. See [Sentinel settings](/guides/content-management-center/repositories#sentinel-settings). ### Testing queries The rule editor can run a query against the workspace before you save, so schema and syntax errors surface while you are still writing. > [!NOTE] > > Sentinel rule writes are performed by the ContraForce application, not with your personal > Azure credentials. Your own Azure RBAC on the workspace is not what authorizes the write, > so a rule can deploy successfully even where you personally lack permission to edit it in > the Azure portal. ## Microsoft Defender XDR ### Consent Defender access requires consent to be granted for the tenant before CMC can read or write custom detections. Until it is, the Defender options prompt for consent rather than listing rules. ### Managed tenants Where you manage several Defender tenants, CMC lists the ones available to you so imports and deployments target the right one. ### Importing Importing lists the custom detection rules in the selected Defender tenant. The importable list and the fields shown differ from Sentinel, because the two products model detections differently. ### The hunting schema Defender custom detections run advanced hunting queries. CMC exposes the hunting schema so the editor can validate table and column references while you write, and the test-query action runs the query against Defender before you save. ## Choosing a platform for a rule The platform is not a preference, it follows the data. A rule that queries tables only present in Defender advanced hunting must be a Defender custom detection; one that queries Log Analytics tables must be a Sentinel analytics rule. Where the same detection idea applies to both, it is two rules, one per platform, not one rule with two targets. Tag them the same way so they stay findable together. ## Mixed repositories A repository can hold both platforms, and the **Rules** tab can filter by platform. Whether to split them is an organizational choice: * **One repository, both platforms** suits a customer or customer group who run both, so their content lives in one place with one review process. * **Separate repositories** suit teams where different people own Sentinel and Defender content, since protection settings and approvers are per repository. *** ## Related Guides > **[Rules](/guides/content-management-center/rules)** > > Import, author, test, and deploy rules for either platform. > **[Repositories](/guides/content-management-center/repositories)** > > Set a default Sentinel target workspace and per-repository protection and approvers. > **[Content Management System](/guides/getting-started/content-management-system)** > > Manage the Sentinel analytics rules and Defender XDR custom detections running in one workspace. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Detection Rule Repositories Source: https://docs.contraforce.com/guides/content-management-center/repositories Create a detection rule repository, choose the workspaces it covers, set baseline protection and required approvals, and review its audit log. A repository is a library of detection rules plus the settings that decide where it deploys and how it changes. Most organizations need very few: one per detection stack, or one per group of customers who should run the same content. ## Create a repository Requires the **Manage** content permission (Content Admin or Org Admin). **1. Open the Content Management Center** Select **Content Management** in the left navigation (the Content Management Center) and stay on the **Repositories** tab. **2. Select New repository** Give it a **Name** and an optional **Description**. That is all the dialog asks for, and both are editable later. **3. Add rules** A new repository is empty. [Import](/guides/content-management-center/rules#import-from-a-workspace), [pull from the marketplace](/guides/content-management-center/marketplace), or author rules. **4. Configure it** Covered workspaces and baseline protection are set **after** creation, from the repository's tabs. Populate the repository first, then turn protection on before other people start editing. ![Content Management Center Repositories tab listing repositories with name, description and created date](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/repositories-list.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=16a37092bd2bd623e23f6d2e27f67cae) Click anywhere on a repository's row to open it. The settings icon at the end of the row opens the repository straight on its **Settings** tab. ![New repository dialog asking for a name and description](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/new-repository.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=8295accd5700d1505646c7069a01dc3e) ## Inside a repository | Tab | What it is for | | - | - | | **Rules** | The content itself. Filter by platform, severity, and tags. | | **Workspaces** | Which workspaces this repository covers, and the [coverage state](/guides/content-management-center/workspace-coverage) of each. | | **Work in progress** | Edits waiting to be added to a [change request](/guides/content-management-center/change-requests). Appears when protection is on. | | **Change requests** | Proposed changes under review. | | **Settings** | Name and description, protection, and Sentinel defaults. | | **Audit** | Every action taken in this repository, with actor and timestamp. | ![A repository showing the Rules, Workspaces, Work in progress, Change requests, Settings and Audit tabs, with Import rules and Add rule actions](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/repository-tabs.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=3bc9d98e9347e7de212b2a6954b8e19c) The **Rules** tab carries the repository's content, with search and filters for severity, type and platform, plus **Import rules** and **Add rule**. ## Covered workspaces A repository only deploys to workspaces you have added to it. This is deliberate: it stops a rule intended for one customer reaching every workspace you manage. Set this under **Settings**, or from the **Workspaces** tab. Only workspaces your organization manages are eligible. The **Workspaces** tab shows each workspace's coverage at a glance: | Column | Meaning | | - | - | | **In sync** | Rules that match the repository baseline. | | **Drifted** | Rules changed in the workspace that still need a decision. | | **Accepted** | Drifted rules an operator has accepted as they are. These are not counted under **Drifted**. | | **Outdated** | Rules running an older baseline version. | | **Not deployed** | Repository rules missing from the workspace. | Rules deleted from the repository are not counted in any column, even where a workspace still runs them. Use **Drifted** and **Accepted** together to check that every client is aligned with the repository without opening each workspace. See [workspace coverage and drift](/guides/content-management-center/workspace-coverage). ### See which repositories manage a workspace Open a workspace from the Workspace Center and select its **Repository** tab. It lists the repositories that manage the workspace's analytic rules, with **View coverage** to see the workspace's coverage in that repository and **Open repository** to go to the repository. The tab appears for service provider accounts. > [!NOTE] > > Removing a workspace from a repository does not remove rules already deployed there. It > stops future deployments and stops the workspace being scanned for drift. Remove the > deployed rules first if you want them gone. ## Baseline protection The repository's rule set is its **baseline**. Baseline protection is what turns a repository from a shared folder into a reviewed one, and it is configured under **Settings**. With **Require change requests** off, an edit changes the baseline immediately. With it on, additions, edits, removals, imports and marketplace pulls are all staged for review instead: each becomes a **work-in-progress item**, which must be added to a **change request** and approved before it changes the baseline. ### Protection settings | Setting | Effect | | - | - | | **Require change requests** | Stages every change for review. Off means changes hit the baseline directly. | | **Required approvals** | How many approvals a change request needs before it can merge. | | **Allow authors to approve** | Lets a change request author count their own approval toward the required total. | | **Repository approvers** | Only approvals from these people count toward merge. | ![Repository Settings showing repository details and the Baseline protection panel with required approvals, author approval and the approver list](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/baseline-protection-settings.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=b1a2c25ed27719b83cd6bc11cc92708b) > [!WARNING] > > Turning protection on does not retroactively review anything. Rules already in the baseline > stay exactly as they are. It changes what happens to the **next** change. > [!WARNING] > > **Required approvals** and **Repository approvers** are set independently, and nothing stops > you requiring more approvals than you have approvers. A repository configured that way > accepts change requests it can never merge. Check the two together. > [!NOTE] > > While protection is on, a single change request is capped at a fixed number of items. If you > are migrating a large rule set, do it before you turn protection on, or split it across > several change requests. ## Sentinel settings A repository can carry a **default target workspace** for [Microsoft Sentinel](/guides/content-management-center/platforms#microsoft-sentinel). When a deployment does not name a workspace explicitly, this is where it goes. Set it under **Settings** if most of the repository's content is destined for one workspace. Leave it unset to be asked every time. ## Audit The **Audit** tab records every action against the repository: rules created, imported, edited, deployed and rolled back; change requests opened, approved and merged; settings changed. Each entry names the actor and the time. This is a read-only record and cannot be edited or cleared. ## Deleting a repository Requires the **Manage** permission. > [!WARNING] > > Deleting a repository removes its rules and their version history from ContraForce. It > does **not** remove rules already deployed to workspaces. Those keep running, and are no > longer tracked by anything, so drift on them will stop being reported. *** ## Related Guides > **[Rules](/guides/content-management-center/rules)** > > Import, author, version, deploy, and roll back the rules in a repository. > **[Change requests](/guides/content-management-center/change-requests)** > > Review, approve, and merge changes in a protected repository. > **[Workspace coverage and drift](/guides/content-management-center/workspace-coverage)** > > See what each covered workspace is running and resolve drift. > **[Sentinel and Defender](/guides/content-management-center/platforms)** > > How Sentinel analytics rules and Defender XDR custom detections are imported and deployed. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Import, Version, and Deploy Detection Rules Source: https://docs.contraforce.com/guides/content-management-center/rules Import or author Sentinel and Defender XDR detection rules, deploy them to covered workspaces, track every version, and roll back a bad change. A rule in a repository has a definition, a platform, a version history, and a record of where it has been deployed. This page covers getting rules in and moving them out. ## Ways to add a rule > **Import** > > Bring in rules already running in a Sentinel or Defender workspace. > **Marketplace** > > Pull a ContraForce-maintained template. See [Marketplace](/guides/content-management-center/marketplace). > **Author** > > Write a new rule directly in the editor. All three require the **Author** content permission, and all three respect protection: in a protected repository the result is a work-in-progress item, not a committed rule. ## Import from a workspace Importing adopts rules that already exist in a customer's workspace, so they become managed content instead of untracked configuration. **1. Open Import rules** From the repository's **Rules** tab, select **Import rules**. **2. Choose the source** Pick a **source platform** ([Microsoft Sentinel or Microsoft Defender XDR](/guides/content-management-center/platforms)) and then the **source workspace** to read from. The importable list and the fields shown differ by platform. **3. Select the rules** Filter by type and severity or search by name, then select what you want. **Select all** takes everything matching the current filter, and the count tells you how many that is. For Sentinel, the list includes scheduled and near-real-time (NRT) analytics rules. A rule this repository already manages is marked **Already in this repository** and can't be selected, so the same live rule is never imported twice. In a protected repository, a rule someone has already imported but that is still waiting for review is marked **Pending in this repository** and can't be selected either. **Select all** skips both. **4. Import** In an unprotected repository the rules join the baseline immediately. In a protected one they arrive as work in progress. ![Import rules page with source platform and source workspace selectors and a list of available rules with checkboxes](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/import-rules.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=ffbdb339d3ac0e99c17dcebfbf728fcc) > [!NOTE] > > Importing copies the rule into the repository. It does not take over the live rule. Until > you deploy the repository's copy back out, the workspace keeps running what it was already > running, and the two can [drift apart](/guides/content-management-center/workspace-coverage). ## The rule list The **Rules** tab lists each rule with its type, platform, severity and version, plus an **Added** column showing when the rule entered the repository. Hover it to see who added it. Sort by **Added** to tell apart two rules with the same name. ## Author a rule Select **Add rule** from the repository's **Rules** tab to open the rule editor. To start from a rule you already have, drop a single exported rule `.json` file onto the editor, or click the drop area to browse. For Sentinel, export the rule from the Sentinel analytics page. For Defender, use a custom detection export. The editor fills in the fields from the file so you can review them before saving. A file that holds several rules is rejected: export one rule at a time. The rule editor captures: * **Name**, **description**, and **severity** * **Platform**, which determines validation and the deployment target * The **query**, with a test-query action to run it before saving * **MITRE ATT\&CK** tactics, techniques and sub-techniques * **Entity mappings**, so detections resolve to accounts, hosts and other entities. A Sentinel rule can have up to 10 entity mappings, each with up to 3 identifiers, matching Microsoft Sentinel's limits. * **Tags**, used for filtering and grouping Use the test-query action before saving. It runs the query against the target platform and surfaces syntax and schema errors while you can still fix them cheaply. ## Versions and history Every change to the baseline creates a new version. Open a rule and its detail view carries three tabs: | Tab | Shows | | - | - | | **Deployments** | Which workspaces this rule has been deployed to, and when. | | **Forks** | Variants derived from this rule. | | **History** | Every version, with the change type, author, timestamp and message. | ![A rule's History tab listing versions v1 to v3 with change type, author, date and message](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/rule-history.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=541a7d7c8f6ef8e2dcf8e2cecc5d7ff2) The **message** records why a version exists, and it is written for you: an import records what it came from, and a merge records the [change request](/guides/content-management-center/change-requests) it came through. That turns the history into a readable account rather than a list of timestamps. Nothing is overwritten in place. An older version stays retrievable, which is what makes rollback possible. ## Forks A fork is a workspace-specific variant of a base rule. Today, forks are created by [drift scans](/guides/content-management-center/workspace-coverage): when a scan finds that a workspace runs a changed copy of a repository rule, it records that copy as a fork of the base rule, so the difference is captured instead of lost. A forked rule keeps a link to its base, and the rule's **Forks** tab lists each fork with its workspace and a **diff against the base**, so the divergence stays visible instead of becoming folklore. If a workspace's change is an improvement everyone should get, adopt it into the baseline from the coverage view instead of keeping it as a fork. ## Deploy Deployment pushes a rule from the repository to one or more covered workspaces. **1. Validate** CMC validates the rule against the target before writing. Validation failures are reported per workspace, so one bad target does not hide the rest. **2. Deploy** Deploy a single rule, or use the repository's deploy view to push a set. **3. Confirm** The rule's **Deployments** list records each workspace it reached and when. A deployment records provenance in the target. That provenance is what later lets a drift scan match a live rule back to its repository rule with certainty rather than by guessing at the name. ## Rollback Rollback redeploys an earlier version of a rule to the workspaces running it. Use it when a deployed change turns out to be wrong, rather than hand-editing the rule in the vendor console, which creates drift. ## Delete A rule can be deleted from a repository individually or in bulk. Deleting a rule ends its management. It does not touch any workspace: the rule keeps running in every workspace it was deployed to, exactly as deployed. From then on: * It leaves [workspace coverage](/guides/content-management-center/workspace-coverage). It is no longer counted as in sync, drifted, accepted, outdated, or not deployed anywhere, and neither is any workspace fork of it. * Its live copies count as unmanaged in the next drift scan. You can import one again if you want it managed. * It can no longer be deployed or rolled back, and neither can its forks. Their pages say **No longer managed**. > [!WARNING] > > To remove the rule from a workspace as well, delete it there (in Microsoft Sentinel or > Microsoft Defender XDR). Otherwise it keeps running as an unmanaged rule. *** ## Related Guides > **[Workspace coverage and drift](/guides/content-management-center/workspace-coverage)** > > See which deployed rules are in sync, outdated, drifted, or not deployed. > **[Change requests](/guides/content-management-center/change-requests)** > > How work-in-progress edits are reviewed, approved, and merged in a protected repository. > **[Sentinel and Defender](/guides/content-management-center/platforms)** > > How the rule's platform decides validation, the query schema, and the deployment target. > **[Repositories](/guides/content-management-center/repositories)** > > Create a repository, choose the workspaces it covers, and set baseline protection. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Detection Rule Drift and Workspace Coverage Source: https://docs.contraforce.com/guides/content-management-center/workspace-coverage Scan your workspaces for detection rule drift, see which rules are in sync, outdated, or not deployed, and resolve edits made outside ContraForce. Coverage answers a question the repository alone cannot: **what is running out there, and does it still match the baseline?** Rules changed directly in a vendor console show up here instead of staying invisible. This page is written for fleet operators managing many workspaces, though the mechanics are the same for one. ## What the coverage view is reading > [!WARNING] > > Coverage shows what this repository **recorded** as live in the workspace. It is read from > deployment history, so it reflects the last synchronize or deploy rather than a fresh read > of the workspace. **Last recorded** is when ContraForce last wrote that record, not when > the rule last changed in the workspace. > > To compare against what is running right now, use **Scan workspace**. That distinction matters operationally. If someone edited a rule in the Azure portal an hour ago and nobody has scanned since, the coverage view will still show it in sync. Scan before you trust a clean board. ## Coverage states Open a repository's **Workspaces** tab and select a workspace. Rules are grouped into five views, each with a count: | View | Meaning | | - | - | | **All** | Every rule in this record, whatever its state, including the ones not deployed. | | **In sync** | Matches the repository baseline. Nothing to do. | | **Drifted** | The workspace copy no longer matches the baseline. Someone changed it outside ContraForce. | | **Outdated** | Running an older baseline version. Nobody changed it; it simply has not been redeployed. | | **Not deployed** | In the repository, absent from this workspace. | Coverage only counts rules the repository still manages. A rule [deleted from the repository](/guides/content-management-center/rules#delete), and any workspace fork of it, leaves every view. The workspace keeps running it, and the next scan counts it as unmanaged. The distinction that matters most is **drifted** versus **outdated**. Outdated is a gap you close by deploying. Drifted means someone made a change you have not read yet, and deploying over it destroys their work sight unseen. ![Workspace coverage for a workspace, showing the All, In sync, Drifted, Outdated and Not deployed filters with counts](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/workspace-coverage-filters.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=97dd1f7949867a8da8303138f29f0b7b) Each row shows the rule, its status, the baseline **version** it corresponds to, its **platform**, and when it was **last recorded**. Rows offer **View rule**, or **View diff** where the workspace copy differs from the baseline. A rule whose difference has been deliberately accepted shows a **Drift accepted** status and a **Synced copy** link to the live rule, so an intentional divergence stays visibly different from an unreviewed one. The **Drifted** view here lists both kinds. On the repository's **Workspaces** tab they are counted separately: **Drifted** counts only drift that still needs a decision, and **Accepted** counts the rest, so the two columns add up to this view's **Drifted** count. If the workspace changes an accepted rule again, the acceptance lapses and the rule moves back to **Drifted**. ## Resolving drift Select one or more drifted rules and choose an action. The same three actions are available in bulk from the toolbar and per row from the row menu. | Action | What it does | When to use it | | - | - | - | | **Accept drift** | Records that the difference is known and intended, and stops flagging it. | A deliberate local difference you want to keep. | | **Adopt as baseline** | Takes the workspace's current definition and makes it the repository baseline. | The out-of-band change was an improvement worth giving everyone. | | **Deploy baseline** | Overwrites the workspace copy with the repository baseline. | The out-of-band change was unwanted. | ![Drifted tab with bulk Accept drift, Adopt as baseline and Deploy baseline actions, and a row menu open](https://mintcdn.com/contraforce/HQrSzge5Tt9yuYjk/images/content-management-center/drift-actions.png?fit=max\&auto=format\&n=HQrSzge5Tt9yuYjk\&q=85\&s=4ea13c2c4b6984588540b812242db3ec) > [!NOTE] > > **Accept drift** silences a row, it does not make the two definitions match. The workspace > keeps running its own version. Accepting drift on a rule you actually wanted standardised > is how a fleet quietly diverges, so read the diff before reaching for it. Once drift has been accepted on a rule, the row menu shows **Drift already accepted** and offers the two remaining actions, so you can still change your mind later. ### Protection applies here too Reconciliation is a change to the baseline like any other. In a repository with [baseline protection](/guides/content-management-center/repositories#baseline-protection) enabled, adopting a drifted rule does not silently rewrite the baseline: it becomes a work-in-progress item and goes through a [change request](/guides/content-management-center/change-requests). ## Scanning **Scan workspace** reads the workspace and refreshes the record. Run one when you want current state rather than the last thing ContraForce wrote. Scanning is scoped to a repository's covered workspaces. A workspace nobody added to a repository is never scanned, which is the usual reason drift appears to be missing: [add the workspace to the repository](/guides/content-management-center/repositories#covered-workspaces) first. ## A working rhythm **1. Scan before you judge** The board reflects the last recorded state. Scan the workspaces under active change so you are reading current reality. **2. Clear outdated first** It is unambiguous: deploy the current baseline and the gap closes. **3. Read every drifted rule before acting** Open the diff. Someone made that change for a reason. Decide whether it becomes the new baseline, gets accepted as a local difference, or gets overwritten. **4. Work through not deployed** Decide whether each rule belongs in this workspace, and deploy the ones that do. *** ## Related Guides > **[Rules](/guides/content-management-center/rules)** > > Deploy rules to covered workspaces and roll back to an earlier version. > **[Change requests](/guides/content-management-center/change-requests)** > > Review and merge baseline changes, including adopted drift, in a protected repository. > **[Repositories](/guides/content-management-center/repositories)** > > Add covered workspaces and configure baseline protection. > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Meeting Cyber Insurance Requirements Source: https://docs.contraforce.com/guides/contraforce-and-compliance/contraforce-and-cyber-insurance See how ContraForce maps to cyber insurance requirements like 24/7 monitoring, EDR, SIEM, and incident response, and how to answer application questions. Cyber insurance applications have gotten harder. Carriers have moved beyond simple checklists. They now want verified controls, documented response timelines, and real evidence that your security stack is doing what you say it does. If you're using ContraForce, you're already covered on most of what they're asking for. This article breaks down exactly how. *** ## What Carriers Are Looking For Every insurance provider structures their application differently, but the core requirements have converged around the same set of controls. Here's what shows up on virtually every application in 2025: * 24/7 security monitoring with a SOC or equivalent * Endpoint detection and response (EDR or XDR) * Centralized log management (SIEM) * A documented and tested incident response plan * Vulnerability management and patching * MFA enforcement and identity monitoring * Email security and anti-phishing controls ContraForce addresses these through a single platform, except vulnerability management and patching, which stay with your vulnerability-management tooling. Here's how each one maps. *** ## 24/7 MXDR: Your SOC Answer The most common question on any cyber insurance form: *"Do you have 24/7 security monitoring with detection and response capabilities?"* ContraForce runs AI-powered Managed Extended Detection and Response around the clock. Our AI agents monitor, triage, investigate, and respond to threats across endpoints, identity, email, and cloud workloads without gaps in coverage. When something malicious is detected, the platform can isolate endpoints, disable compromised accounts, and contain the threat automatically, all with timestamped audit trails. That documented "alert-to-action timeline" is exactly what underwriters are looking for when they evaluate SOC maturity. *** ## Microsoft Sentinel: SIEM in Your Tenant Carriers are increasingly requiring SIEM as a baseline control, especially for larger policies. ContraForce deploys Microsoft Sentinel directly in your Azure tenant, collecting and correlating logs from across your environment: endpoints, identity, email, cloud workloads, and network sources. Our AI layer cuts through the noise so real threats get surfaced fast. Log retention is configurable to meet whatever window your carrier requires (90, 180, or 365 days), and because everything lives in your tenant, your data stays under your control. *** ## Microsoft Defender for Endpoint: EDR That's Actually Managed Nearly every carrier requires EDR on all in-scope endpoints. ContraForce manages Microsoft Defender for Endpoint as a fully managed service, providing real-time detection, automated response, and forensics. Defender telemetry flows directly into Sentinel, so your detection and response pipeline is unified rather than siloed. You get endpoint coverage reports showing exactly which devices are protected, which is the evidence carriers want to see. *** ## Incident Response: Documented by Default Carriers don't just want to know you have an incident response plan. They want to see that it's structured, tested, and produces real documentation. ContraForce handles this natively. Every incident follows a structured lifecycle (detection, triage, investigation, containment, eradication, recovery) and each step is documented automatically. The platform generates post-incident reports with full timelines, indicators of compromise, and actions taken. No scrambling to assemble evidence after the fact. *** ## Vulnerability Management: Where ContraForce Fits ContraForce doesn't scan for vulnerabilities, deploy patches, or track patch remediation. Vulnerability scanning and patching stay with your organization's or your MSP's vulnerability-management tooling, which is where the patch cadence documentation carriers ask about comes from. ContraForce covers the incident response side: when a threat is detected, it can isolate devices, disable accounts, block IPs and URLs, quarantine files, delete malicious email, and revoke sessions, with a timestamped evidence trail for every incident. *** ## Identity Monitoring: Watching the Front Door MFA enforcement is configured in Microsoft Entra ID, but ContraForce adds the monitoring layer on top. Through Sentinel and Defender for Identity, the platform detects suspicious sign-in patterns, brute force attempts, impossible travel events, and MFA bypass techniques. If an identity-based threat is detected, ContraForce can trigger automated responses (password resets, account disablement) before an attacker can move laterally. *** ## Certifications That Back It Up Some carriers ask about the certifications of your security providers. ContraForce is **SOC 2 Type II** certified, was named **Microsoft Security ISV of the Year 2024**, and is listed on the **Azure Marketplace** as an IP co-sell eligible, MACC-decrementable solution. These aren't just badges. They're independently verified proof that the platform meets enterprise-grade security and operational standards. *** ## Cheat Sheet: Application Questions and ContraForce | **They Ask** | **You Answer** | | - | - | | 24/7 SOC or managed monitoring? | ContraForce AI-powered MXDR, continuous and automated with escalation paths | | EDR/XDR on all endpoints? | Managed Microsoft Defender for Endpoint with coverage reporting | | SIEM in place? | Microsoft Sentinel deployed in your Azure tenant | | Incident response plan? | Built into the platform with structured workflows and automatic documentation | | Vulnerability scanning? | Your vulnerability-management tooling; ContraForce doesn't scan or patch | | MFA monitoring? | Identity threat detection through Sentinel + Defender for Identity | | Email security? | Managed Microsoft Defender for Office 365 | | Provider certifications? | SOC 2 Type II · Microsoft Security ISV of the Year 2024 | *** ## A Few Tips When Filling Out Applications **Be specific.** Generic answers like "yes, we have EDR" leave money on the table. Describe the product, who manages it, and what happens when a threat is detected. The more context you give, the better your quote. **Use the appendix.** If the form doesn't give you enough space, attach additional documentation. Dashboards, incident reports, and coverage summaries all strengthen your application. **Be honest.** Misrepresenting your controls doesn't just risk a denied application. It can void your coverage when you need it most. **Start early.** Most carriers need 60 to 90 days when controls need to be implemented. ContraForce deploys in about an hour into your existing Azure tenant, which compresses that timeline significantly. *** ## Bottom Line ContraForce covers the technical controls that show up on virtually every cyber insurance application (SOC, SIEM, EDR, incident response, identity monitoring) through a single platform built on the Microsoft security stack. If you need help mapping ContraForce to a specific carrier's form, reach out to our team. We've been through the process and we're happy to help you get it right. *** ## Related Guides > **[Incident Report](/guides/getting-started/incident-report)** > > Open the closed incidents behind your dashboard totals and save a PDF copy for a customer. > **[SLA Tracking](/guides/getting-started/sla-tracking)** > > Set SLA targets per workspace and severity, then track Time to First Response and Time to Resolution. > **[Workspace Environments](/guides/getting-started/workspace-environments)** > > Review a workspace's endpoint and license inventory and find devices not yet onboarded to Defender. > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Track closed incidents, classification trends, and Gamebook runs across your workspaces. *** *ContraForce is SOC 2 Type II certified, Microsoft Security ISV of the Year 2024, and available on the Azure Marketplace.* > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Onboarding Workspaces at Scale with CSV Import Source: https://docs.contraforce.com/guides/fleet-management/onboarding-workspaces-at-scale Bulk import up to 200 customer workspaces from a CSV file, track each row's result, and pick a Workspace Profile so new workspaces land already configured. Onboard customers one at a time or hundreds at once, and have each new workspace land already configured. Pick a **Workspace Profile** during onboarding and ContraForce applies its access, module, notification, and Gamebook settings as soon as the workspace exists. > [!NOTE] > > **Who is this for?** > > * MSP/MSSP partners bringing on new customers > * Organizational Admins and Workspace Admins responsible for onboarding *** ## What Can You Do Here? > **Onboard One Customer** > > Add a workspace and pick the profile that should configure it. > **Import a Batch** > > Upload a CSV and pre-onboard up to 200 workspaces in one action. > **Watch Every Row** > > Track each import row's outcome and re-import only what failed. *** ## Prerequisites | Requirement | Description | | - | - | | **Organizational Admin or Workspace Admin** | Required to onboard workspaces and run imports. | | **Customer tenant IDs** | You need each customer's Microsoft Entra tenant ID. | | **A Workspace Profile (optional)** | Only needed if you want new workspaces configured automatically. See [Workspace Profiles](/guides/fleet-management/workspace-profiles). | *** ## Onboarding a Single Workspace with a Profile **1. Open the Onboarding tab** From the left navigation, select **Workspaces**, then click the **Onboarding** tab. **2. Click Add workspace** The **Add a workspace** panel opens. **3. Identify the customer tenant** | Field | Description | | - | - | | **Workspace name** | Display name for this workspace. Enter a domain and ContraForce looks up the tenant ID for you | | **Tenant ID** | The customer's Microsoft Entra tenant ID | | **Customer admin email** (optional) | Where the invite link is sent. You can use your own email | | **Workspace profile** (optional) | The profile that should configure this workspace once it is created | **4. Finish the wizard** Choose the modules to seed on the next step and send the invite. The workspace appears on the **Onboarding** tab with a pending badge. ![Add a workspace panel with the Workspace profile dropdown selected](https://mintcdn.com/contraforce/VGCdp5T8nvIgjDl-/images/fleet-management/onboard-with-profile.png?fit=max\&auto=format\&n=VGCdp5T8nvIgjDl-\&q=85\&s=35729bf5de2f0dbf6743e46e565158cc) Choosing a Workspace Profile while adding a workspace The profile's access, notification, Gamebook approver, and module settings are applied once the workspace is created. You do not need to apply the profile by hand. > [!NOTE] > > If the profile's modules would move the workspace onto a higher-priced plan, that part is left for you to confirm. Open the profile, click **Apply**, and acknowledge the charge. Creating a workspace is never treated as consent to a recurring charge. > [!TIP] > > Agent policy lands after an agent exists for the workspace. If the profile is set to **Provision**, ContraForce creates the agent for you. See [Agents in a Profile](/guides/fleet-management/workspace-profiles#agents-in-a-profile). *** ## Importing a Batch from CSV Use an import when you are bringing on many customers at once. Every row is pre-onboarded exactly as if you had typed it into the form. **1. Open the import dialog** From the **Workspaces** page, choose **Import workspaces**. **2. Download the template** Click **Download template** to get a CSV with the right columns and a sample row. **3. Fill in one workspace per row** Replace the sample row with your customers. The sample tenant ID is intentionally an all-zero placeholder, so a file saved without editing fails loudly instead of onboarding the wrong tenant. **4. Upload the file and import** Select the file and click **Import workspaces**. ContraForce validates the whole file before anything is created. **5. Watch the import** The import runs in the background, one row at a time. Open it to see each row's status and result. ![Import workspaces dialog with template download and file picker](https://mintcdn.com/contraforce/VGCdp5T8nvIgjDl-/images/fleet-management/bulk-import-with-csv.png?fit=max\&auto=format\&n=VGCdp5T8nvIgjDl-\&q=85\&s=97f08413fd979408bb6d750f646a3883) Import workspaces dialog ### CSV columns | Column | Required | Description | | - | - | - | | **Tenant name** | Yes | The customer's display name in ContraForce | | **Tenant ID** | Yes | The customer's Microsoft Entra tenant ID, as a GUID | | **Profile name** | No | The Workspace Profile that should configure this workspace. Must match a profile name exactly | | **Admin email** | No | Where the invite link is sent for this customer | ```csv theme={null} Tenant name,Tenant ID,Profile name,Admin email Contoso Ltd,3f2504e0-4f89-11d3-9a0c-0305e82c3301,Managed XDR baseline,admin@contoso.example Fabrikam Inc,7c9e6679-7425-40de-944b-e07fc1f90ae7,Managed XDR baseline,admin@fabrikam.example ``` > [!TIP] > > Column **order does not matter**, and ContraForce recognizes the usual header spellings (`Tenant ID`, `tenantid`, `Directory ID`, and similar). Comma, semicolon, and tab-separated files all work, so a spreadsheet exported from a European locale imports without editing. ### Limits | Limit | Value | | - | - | | Rows per import | 200 | | File size | 512 KB | | Tenant name length | 200 characters | ### What is validated before anything is created | Check | Behavior | | - | - | | **Missing name or tenant ID** | That row fails; the rest of the file still imports | | **Tenant ID is not a valid GUID** | That row fails rather than being guessed at | | **Duplicate tenant ID in the file** | Flagged against the later row, naming the earlier row it duplicates | | **Row numbers** | Count the header as row 1, so they match your spreadsheet's row numbers | | **Tenant not recognized in Microsoft Entra** | Shown as a warning only. The row still imports | *** ## Tracking an Import Each import has its own activity page listing every row with its outcome. | Row status | Meaning | | - | - | | **Queued** | Waiting its turn | | **Running** | Being created now | | **Succeeded** | The workspace was created and appears on the **Onboarding** tab | | **Failed** | The row could not be created, with the reason shown on the row | Rows are processed one at a time, so a large import takes a few minutes. Successful rows are created immediately, so you do not have to wait for the whole file to finish before working with them. If an import stops making progress, a **Resume** option appears after a few minutes. Resuming picks up where the import left off and never re-creates a workspace that already exists. > [!WARNING] > > Do not re-upload the whole file to fix a few failures. Create a new CSV containing only the failed rows. Re-importing an existing tenant is rejected as a duplicate. *** ## What Happens Next Importing pre-onboards each customer. The customer admin still completes their own setup wizard using the invite link. **1. The customer admin accepts the invite** They grant ContraForce access to their Microsoft tenant. See [Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding). **2. The workspace goes live** The card moves from the **Onboarding** tab to the **Workspaces** tab. **3. Verify the profile landed** Open the profile and check the **Activity** tab. Anything still waiting shows as not yet on the current version. Click **Apply now**. *** ## Troubleshooting | Issue | Cause | Solution | | - | - | - | | "Missing Tenant ID column" | The header row was not recognized | Start from **Download template** and keep the header row intact | | Every row failed with a tenant ID error | The tenant ID column holds names or truncated values | Confirm each value is a full Microsoft Entra tenant GUID | | Profile name not matched | The name in the CSV does not match a profile exactly | Copy the name from the **Profiles** tab, including spacing and capitalization | | Row failed with a plan charge message | The workspace is beyond your plan's included allowance | Re-import that row once the additional charge is acknowledged | | Import stuck at Running | The import stalled | Wait for the **Resume** option to appear, then resume it | | Workspaces created but not configured | The profile has not been applied yet | Open the profile and click **Apply**, acknowledging any charge in the preview | Still stuck? Contact [support@contraforce.com](mailto:support@contraforce.com) with the import file and the row numbers that failed. *** ## Related Guides > **[Workspace Profiles](/guides/fleet-management/workspace-profiles)** > > Build the template that configures every new workspace. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Monitor workspace health and manage per-workspace settings. > **[Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding)** > > What your customer admin sees after they receive the invite. > **[Onboarding Verification](/guides/onboarding/workspace-onboarding-checklist)** > > Confirm a new workspace is fully live and ingesting. *** Questions about onboarding at scale? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Workspace Profiles: Standardize Workspace Settings Source: https://docs.contraforce.com/guides/fleet-management/workspace-profiles Set access, modules, notifications, Gamebook approvers, and agent policy once in a Workspace Profile, then preview and apply it to all attached workspaces. A **Workspace Profile** is a reusable template of workspace settings. Configure it once, attach the workspaces it should manage, and apply it. ContraForce pushes the same configuration to every workspace on the profile. Without profiles, every configuration change is multiplied by the size of your fleet: 200 workspaces means 200 manual edits. With a profile, it is one edit and one apply. > [!NOTE] > > **Who is this for?** > > * MSP/MSSP partners managing more than a handful of customer workspaces > * Organizational Admins who set access, notification, and module standards across the fleet ![Profiles tab in Workspace Center showing a profile card](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/fleet-management/workspace-profiles.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=96f6ae970ea56cc6a1b77901c39fe650) Workspace Center → Profiles *** ## What Can You Do Here? > **Standardize Your Fleet** > > Define one baseline for access, modules, notifications, Gamebooks, and agents. > **Roll Out in One Action** > > Push a change to every attached workspace without opening any of them. > **See What Is Out of Sync** > > Every profile shows which workspaces are still on an older version. *** ## Prerequisites | Requirement | Description | | - | - | | **Service provider account** | Profiles are available to MSP/MSSP partner accounts that manage customer workspaces. | | **Organizational Admin** | Required to view, create, edit, and apply profiles. One apply reconfigures every attached workspace, so this is held at the Org Admin level. | | **Agent Center (optional)** | Only required if you want a profile to deploy or assign Security Delivery Agents. See [Deploying Agent Center](/guides/onboarding/agent-center-deployment). | *** ## What a Profile Covers A profile is made up of five sections. Configure only the ones you need. A section you leave empty is left alone on every workspace. | Section | What it sets | | - | - | | **IAM** | Users and groups that should have access to the workspace, and the role each one gets | | **Modules** | Detection and response modules the workspace should have | | **Notifications** | Notification preferences and the recipients for incident, Gamebook, and agent run notifications | | **Gamebooks** | The Gamebook approvers responsible for authorizing manual response actions | | **Agent** | Security Delivery Agent policy, and optionally whether ContraForce should create an agent where the workspace has none | > [!WARNING] > > Notification recipients must be **your own people**: your team members, your groups, or any email address. A person who exists only inside one customer's tenant has no identity in the other workspaces on the profile, so their notifications would silently go nowhere. *** ## Creating a Profile **1. Open the Profiles tab** From the left navigation, select **Workspaces**, then click the **Profiles** tab. **2. Click New Profile** Give the profile a **name**, an optional **description**, and optional **tags**. Tags make profiles easier to find as your library grows. **3. Configure the sections you need** Move through the **IAM**, **Modules**, **Notifications**, **Gamebooks**, and **Agent** tabs and set the values you want every workspace on this profile to have. **4. Save** There is one save bar for the whole profile. Everything you edited across the tabs publishes together as a single new version. You should see a confirmation such as "1 section saved. Profile is now v2." > [!TIP] > > Editing the name, description, or tags does **not** create a new version. Only section changes do, because only section changes need to be pushed to workspaces. *** ## Attaching Workspaces Attaching declares which workspaces the profile manages. It does not configure anything on its own. **1. Open the profile** Click the profile card on the **Profiles** tab. **2. Click Attach workspaces** Select the workspaces this profile should manage and confirm. **3. Expect them to show as not yet applied** Newly attached workspaces carry the profile's label but not yet its configuration. That is correct. Applying is the next, separate step. > [!NOTE] > > Detaching a workspace stops the profile from managing it, but it does **not** remove configuration the profile already applied. Removing settings across a fleet is a deliberate action, not a side effect of detaching. *** ## Previewing and Applying Applying is what makes attached workspaces match the profile. ![Profile detail page showing the waiting to be applied banner and the Apply button](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/fleet-management/workspace-profile-apply.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=c23a46073ba0dfbcb198f6de24a7d3e6) A profile with workspaces waiting to be applied **1. Click Apply** ContraForce shows a preview before anything changes. **2. Read the preview** The preview lists, workspace by workspace, exactly what will be added, updated, or removed. For example, "removes 2 approvers, adds 1". It also calls out any workspace where the profile's modules would change the workspace's plan and add a recurring charge. **3. Acknowledge any charges** If the preview names workspaces that would be repriced, you must acknowledge that before those workspaces are configured. Nothing billable happens without your confirmation. **4. Confirm** The apply runs in the background. You can leave the page. Progress is recorded as each workspace finishes. > [!TIP] > > Applying the same profile twice is safe. ContraForce brings each workspace towards the profile rather than duplicating what is already there, and settings a workspace admin added by hand are left untouched. *** ## Versions and Sync Status Every profile carries a version number, and every workspace records the version it last received. | What you see | What it means | | - | - | | **All in sync** | Every attached workspace is on the profile's current version | | **Waiting to be applied** | The profile has moved ahead of one or more workspaces. Click **Apply now** | | **N of M workspaces not yet on vX** | The exact count still waiting for the current version | A workspace shows as waiting whenever it was just attached, whenever you save a section change, or whenever an apply did not fully land on it. *** ## Tracking a Rollout The **Activity** tab on a profile records every apply as a numbered run, with the version that was pushed, who pushed it, and the result for each workspace. ![Profile Activity tab showing Run 1 applied to one workspace](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/fleet-management/workspace-profile-activity.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=b0056615a5e004bf85a9c72ad3e0dc84) Activity tab showing an apply run and its per-workspace result ### Run and workspace statuses | Status | Meaning | | - | - | | **Queued** | The run has been accepted and is about to start | | **Running** | ContraForce is working through the workspaces | | **Applied** | Everything in the run landed successfully | | **Partially applied** | Most workspaces succeeded; the ones that did not are named on their own rows. This is a successful push with notes, not a failure | | **Skipped** | Nothing was attempted, with a stated reason you can act on | | **Failed** | The workspace could not be configured | | **Provisioning** | An agent deployment started by this run is still finishing. The result settles automatically once the deployment completes | > [!TIP] > > A run tells you what changed as well as whether it worked. A run showing `+0 ~0 -0` with "Already matched. Nothing to change" means the workspace was already exactly as the profile describes. ### Retrying Use **Retry** on a run to pick up the workspaces that did not fully succeed, including skipped ones, which are often waiting on something you have since fixed. A retry is a new run, and it pushes the **same version the original run pushed**, not whatever you have edited since. Workspaces that already succeeded are never touched again. *** ## Agents in a Profile The **Agent** tab sets the Security Delivery Agent policy for every workspace on the profile, and can create the agent where a workspace does not have one yet. | Setting | What it does | | - | - | | **Enabled** | Turns the agent section on for this profile | | **Triage policy** | The agent behavior every workspace on the profile should use | | **Model** (optional) | Preferred AI model. If it is not available in your Agent Center's region, ContraForce uses the default model and says so in the preview | | **Provisioning** | **Configure only** (default): a workspace with no agent is skipped. **Provision**: ContraForce creates the agent, then applies the policy | ### Before a profile can create agents Your environment must have committed an agent deployment model in **Agent Center**. Until it has, agent provisioning is skipped with a message telling you so. That choice is permanent, so ContraForce never makes it for you from a profile. | Deployment model | What you need | | - | - | | **ContraForce Cloud** | ContraForce Cloud agents enabled for your environment, and an available pool agent | | **Your Cloud** | An Agent Center in a **Deployed** state, and Owner rights on its Azure subscription for the person applying the profile | > [!WARNING] > > Provisioning creates billable infrastructure. It happens only when the profile is set to **Provision** and the preview showed it. The preview names the action and the number of workspaces affected before anything is committed. Agent deployments take minutes. The run reports those workspaces as **Provisioning** and settles them automatically once the deployment finishes. A single apply deploys up to **50** agents; anything beyond that is skipped with a reason and picked up by your next apply. *** ## Troubleshooting | Message or symptom | Cause | What to do | | - | - | - | | Profiles tab not visible | Not a service provider account, or not an Organizational Admin | Confirm your role, or contact support to check availability for your environment | | "This workspace has no agent yet" | Profile provisioning is set to **Configure only** | Set provisioning to **Provision** and apply again, or deploy the agent from Agent Center | | "This environment has not chosen its agent deployment model yet" | No deployment model committed | Commit your agent deployment model in **Agent Center**, then apply again | | "Your Agent Center is not deployed yet" | Agent Center is missing or still deploying | Finish [Agent Center deployment](/guides/onboarding/agent-center-deployment), then retry the run | | Owner rights required | The person applying the profile is not an Owner on the Agent Center subscription | Have a subscription Owner run the apply, or grant Owner and retry | | "An agent deployment is already running for this workspace" | A deployment from an earlier action is still in flight | Wait for it to finish, then retry the run | | Workspace stays out of sync after a run | The run was partially applied, so the version was not recorded | Open the **Activity** tab, read the workspace's reason, resolve it, and retry | | Modules section skipped | Applying the modules would reprice the workspace | Apply again and acknowledge the charge when prompted | If a workspace keeps failing across multiple runs, contact [support@contraforce.com](mailto:support@contraforce.com) with the profile name, the run number, and the workspace name. *** ## Best Practices > **Start with one baseline profile per customer type** > > Most fleets need only a few profiles, for example one per detection stack or per service tier. Tags make them easy to find later. > **Batch your edits into one save** > > Everything you change across the tabs publishes as one version and one rollout. Six separate saves means six versions and six pushes. > **Always read the preview** > > The preview is produced by the same engine that performs the apply, so what it shows is what will happen. Pay particular attention to removals and to any workspace flagged for repricing. > **Attach first, apply when you are ready** > > Attaching is reversible and configures nothing, so you can stage a profile's reach and review it before anything fans out. > **Clear skips before your next big rollout** > > Skips almost always point at a prerequisite: an undeployed Agent Center, a missing permission, or an unacknowledged charge. Resolving them once makes every future apply cleaner. *** ## Related Guides > **[Onboarding Workspaces at Scale](/guides/fleet-management/onboarding-workspaces-at-scale)** > > Onboard one customer with a profile, or import a whole batch from a CSV. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage individual workspaces, health, and per-workspace settings. > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up agents and choose an adoption mode. > **[Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Understand which role can do what across the platform. *** Questions about Workspace Profiles? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Shared Teams Channel with the Success Team Source: https://docs.contraforce.com/guides/general-support/contraforce-success-teams-channel Set up a shared Teams channel with the ContraForce Success Team by allowing outbound B2B direct connect in Microsoft Entra cross-tenant access settings. This guide walks you through configuring your Microsoft 365 tenant to enable a shared Teams channel with the ContraForce Success Team. Using shared channels allows direct collaboration without guest accounts or switching tenants. ## Overview Microsoft Teams shared channels use B2B direct connect, which enables seamless collaboration between organizations. Once configured, you can participate in a shared channel directly within your own Teams environment. ## Prerequisites * **Security Administrator** or **Global Administrator** role in Microsoft Entra. Cross-tenant access settings are managed by Security Administrator; application-management roles such as Cloud Application Administrator and Application Administrator cannot change them ([Microsoft reference](https://learn.microsoft.com/entra/external-id/cross-tenant-access-settings-b2b-direct-connect#before-you-begin)) * Microsoft 365 subscription with Teams enabled * Access to the Microsoft Entra admin center ## Configuration Steps ### Step 1: Access Cross-Tenant Settings 1. Navigate to the [Microsoft Entra admin center](https://entra.microsoft.com) 2. Go to **External Identities** → **Cross-tenant access settings** Direct link: `https://entra.microsoft.com/#view/Microsoft_AAD_IAM/CompanyRelationshipsMenuBlade/~/CrossTenantAccessSettings` ### Step 2: Add ContraForce as a Partner Organization 1. Click **Add organization** 2. Enter the domain: `contraforce.com` 3. Click **Add** ### Step 3: Configure Outbound Access 1. Locate **contraforce.com** in your list of organizations 2. Click **Inherited from default** in the **Outbound access** column 3. Select the **B2B direct connect** tab 4. Configure the following settings: | Setting | Recommended Value | Notes | | - | - | - | | **Users and groups** | Allow access | Select "Select users and groups" if you need to limit which users can collaborate | | **External applications** | Allow access | Enables access to Teams shared channels | 5. Click **Save** ### Step 4: Wait for Propagation Cross-tenant access changes can take up to 24 hours to fully propagate across Microsoft's systems. If the shared channel doesn't appear immediately, check again the following day. ## Accepting the Shared Channel Invitation Once your tenant is configured and ContraForce sends a shared channel invitation: 1. Open Microsoft Teams 2. Look for a notification about the shared channel invitation 3. Accept the invitation 4. The shared channel will appear in your Teams sidebar ## Troubleshooting ### Shared channel not appearing * Verify B2B direct connect settings are saved correctly * Confirm the changes have had time to propagate (up to 24 hours) * Ensure the user accepting the invitation is included in the allowed users/groups ### Access denied errors * Check that **Outbound access** is configured (not just Inbound) * Verify **External applications** is set to **Allow access** ## Additional Resources * [Microsoft: Collaborate with external participants in a shared channel](https://learn.microsoft.com/en-us/microsoft-365/solutions/collaborate-teams-direct-connect) * [Microsoft: Allow B2B direct connect with all organizations](https://learn.microsoft.com/en-us/microsoft-365/solutions/allow-direct-connect-with-all-organizations) ## Need Help? If you encounter issues during setup, [submit a support ticket](/submit-ticket) to ContraForce Support and include: * Screenshot of your Cross-tenant access settings for contraforce.com * Any error messages you're receiving * The email address of the user attempting to join the shared channel *** ## Related Guides > **[Submit a Support Ticket](/submit-ticket)** > > Open a support ticket, choose a category and priority, and track your organization's requests. > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Onboard your MSP or MSSP organization, from admin consent to connecting detection sources. > [!NOTE] > > Need help? Contact the ContraForce Support team at [support@contraforce.com](mailto:support@contraforce.com). # Cost Management Center Source: https://docs.contraforce.com/guides/general-support/cost-management-center Use the Cost Management Center to see your plan, XDR and XDR + SIEM licenses, agent token usage, and billing, then set usage budgets and spend controls. The Cost Management Center shows what your organization is licensed for and what its agents consume, and lets you set alerts and approval rules for charges. > [!NOTE] > > **Who is this for?** Admins and finance or operations owners who manage ContraForce licensing and agent spend. Select **Cost Management** in the left navigation. The header shows your plan, for example **Bring Your Own Cloud (BYOC)**, and where you are in the current billing cycle. *** ## What Each Tab Shows **Overview** The billing cycle and days elapsed, investigations and tokens this cycle, runs per day, token usage against a forecast for the cycle, and the five workspaces with the most runs. **Licenses** Your workspace licenses (**XDR** or **XDR + SIEM**) and what each costs per month. The **Cost impact** panel shows the monthly price of adding an XDR workspace, adding an XDR + SIEM workspace, or upgrading a workspace to SIEM. Select **Upgrade to SIEM** on a workspace to upgrade it. Prices are read live from your billing provider, and changes take effect on your next invoice. **Usage** Runs and tokens this cycle, how many workspaces ran at least one investigation, your busiest workspace, and each workspace's share of runs and tokens. **Cost Alerts** Choose who receives cost alerts: workspace members or any email address. Set a **Usage budget** (a monthly token budget and the percentages to notify at, for example `80, 100`), and turn on the alert for when a workspace license is added or upgraded. Investigations keep running when a budget is reached. **Spend Controls** **Auto-approve charges** approves plan-driven charges without a confirmation prompt; every auto-approved charge is still recorded in your audit log. **SIEM license escalations** auto-approves the reprice when connecting a SIEM source upgrades a workspace to an XDR + SIEM license. **Billing** Your plan, payment method, and invoices, once billing is active for your organization. *** ## Self-Hosted Agents (BYOC) On the **Bring Your Own Cloud (BYOC)** plan, which is the **Your Agents** hosting model on [contraforce.com/pricing](https://www.contraforce.com/pricing), agents run in your own Azure subscription. The Agent Center shows this deployment model as **Your Cloud**. Token volume in the Cost Management Center is shown for visibility: Azure bills the Microsoft Foundry usage to your subscription, and ContraForce doesn't bill per run on this plan. > [!TIP] > > Set a **Usage budget** under **Cost Alerts** so you hear about unusual token consumption before your Azure bill arrives. *** ## Related Guides > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Where self-hosted agents run > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Add and manage workspaces *** > [!NOTE] > > Questions about billing or licensing? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Offboarding: Remove ContraForce Apps and Resources Source: https://docs.contraforce.com/guides/general-support/offboarding-contra-force Offboard ContraForce by removing its enterprise apps from Microsoft Entra ID, Azure resources, role assignments, and any Azure Lighthouse delegation. This guide covers the steps required to fully offboard ContraForce from your environment. Follow these procedures to remove all ContraForce enterprise applications, Azure resources, and role assignments. > [!WARNING] > > Offboarding removes all ContraForce functionality from your environment. Ensure you have exported any data you need before proceeding. This action cannot be undone without re-onboarding. ## Offboarding Overview During onboarding, ContraForce deploys resources to your environment. Complete offboarding requires removing: > **Enterprise Applications** > > ContraForce service principals in Microsoft Entra ID > **Azure Resources** > > Resource groups, Logic Apps, and API connections > **Role Assignments** > > RBAC permissions granted to ContraForce > **Agent Infrastructure** > > AI agent resource groups (if deployed) *** ## Before You Begin ### Prerequisites **1. Admin Access** Ensure you have **Cloud App Admin**, **Application Admin**, or **Global Admin** access to Microsoft Entra ID **2. Azure Permissions** Ensure you have **Owner** or **Contributor** access to the Azure subscription **3. Document Current State** Note which ContraForce modules and features are currently deployed **4. Export Data** Export any incident data, reports, or configurations you need to retain ### What Was Deployed? The resources you need to remove depend on your deployment: | Deployment Type | Resources to Remove | | - | - | | **Defender Module Only** | Enterprise applications only | | **XDR + SIEM Module** | Enterprise applications + Apollo resources + Sentinel resources | | **With AI Agents** | All above + Agent Center resource groups | *** ## Step 1: Remove Enterprise Applications Enterprise applications consented during onboarding must be removed from Microsoft Entra ID. ### Accessing Enterprise Applications **Microsoft Entra Admin Center** **1. Navigate to Admin Center** Go to [entra.microsoft.com](https://entra.microsoft.com) **2. Open Enterprise Applications** Navigate to **Identity** > **Applications** > **Enterprise applications** **3. Search for ContraForce** Use the search box to find "ContraForce" **Azure Portal** **1. Open Azure Portal** Go to [portal.azure.com](https://portal.azure.com) **2. Navigate to Microsoft Entra ID** Click **Microsoft Entra ID** in the left navigation **3. Open Enterprise Applications** Click **Enterprise applications** under Manage **4. Search for ContraForce** Use the search box to find "ContraForce" ### Applications to Remove Remove the following enterprise applications: | Application Name | Application ID | | - | - | | **ContraForce API** | `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` | | **ContraForce Portal** | `8b7cb435-9526-47ee-b79a-34433f0daad2` | | **ContraForce Sentinel Hunting** | `6bf1c74d-7ade-4671-a507-166936f89a1f` | | **ContraForce for MDE** | `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` | | **ContraForce Gamebooks for MDE** | `ad7b0e79-3c37-4408-bf8f-eb89522cc920` | | **ContraForce Gamebooks for Identity** | `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` | | **ContraForce Gamebooks for Email** | `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` | ### Deleting an Enterprise Application For each application in the list above: **1. Select the Application** Click on the application name in the list **2. Open Properties** Click **Properties** in the left navigation **3. Delete Application** Click **Delete** at the top of the page **4. Confirm Deletion** Confirm when prompted > [!NOTE] > > Not all applications may be present—only delete applications that exist in your directory. The applications present depend on which modules and features were enabled during onboarding. *** ## Step 2: Remove Azure Resources (Sentinel Deployments) If you deployed the **XDR + SIEM module** with Microsoft Sentinel, remove the following Azure resources. > [!WARNING] > > Skip this step if you only deployed the Defender module without Sentinel integration. ### Remove Apollo Resource Group The Apollo resource group contains the infrastructure for real-time incident notifications. **1. Open Azure Portal** Go to [portal.azure.com](https://portal.azure.com) **2. Navigate to Resource Groups** Click **Resource groups** in the left navigation **3. Find Apollo Resource Group** Search for `rg-contraforce-apollo` **4. Delete Resource Group** Click the resource group, then click **Delete resource group** **5. Confirm Deletion** Type the resource group name to confirm, then click **Delete** #### Resources in Apollo Resource Group The following resources are removed when you delete this resource group: | Resource Type | Name | | - | - | | Log Analytics Workspace | contraforce-apollo-\* | | Application Insights | contraforce-apollo-\* | | Function App | contraforce-apollo-\* | | App Service Plan | contraforce-apollo-\* | | Storage Account | contraforceapollo\* | ### Remove Sentinel Workspace Resources Resources were also deployed to the resource group containing your Microsoft Sentinel workspace. **1. Navigate to Sentinel Resource Group** Find the resource group containing your Sentinel workspace **2. Delete API Connection** Find and delete: `microsoftsentinel-Publish-Incident-To-Apollo` **3. Delete Logic App** Find and delete: `Publish-Incident-To-Apollo` **4. Delete Automation Rule** In Sentinel, go to **Automation** and delete: `Run-Playbook-Publish-Incident-To-Apollo` #### Deleting Individual Resources For each resource: **1. Select Resource** Click on the resource name **2. Click Delete** Click **Delete** in the toolbar **3. Confirm** Confirm deletion when prompted *** ## Step 3: Remove Role Assignments ContraForce was granted RBAC permissions on your Azure resources. These should be removed. ### Finding Role Assignments **1. Navigate to Resource Group** Go to the resource group containing your Sentinel workspace **2. Open Access Control** Click **Access control (IAM)** in the left navigation **3. View Role Assignments** Click the **Role assignments** tab **4. Find ContraForce** Search for "ContraForce" in the list ### Role Assignments to Remove | Service Principal | Role | Scope | | - | - | - | | **ContraForce API** | Sentinel Contributor | Sentinel resource group | | **ContraForce API** | Reader | Sentinel resource group | ### Removing a Role Assignment **1. Select Assignment** Check the box next to the role assignment **2. Click Remove** Click **Remove** in the toolbar **3. Confirm** Click **Yes** to confirm removal > [!TIP] > > You can also use Azure CLI to remove role assignments: > > ```bash theme={null} > az role assignment delete --assignee "24d97bc0-8f2b-45d5-8e0b-7fe286732ef2" --resource-group "your-sentinel-rg" > ``` *** ## Step 4: Remove Agent Resource Groups (If Applicable) If you deployed ContraForce AI Agents, additional resource groups must be removed. > [!WARNING] > > Skip this step if you did not deploy AI Agents. Most deployments do not include agents. ### Agent Center Resource Group **1. Find Agent Center** Search for resource group: `cf-rg-agent-center` **2. Delete Resource Group** Click **Delete resource group** **3. Confirm** Type the name and confirm deletion #### Resources in Agent Center | Resource Type | Description | | - | - | | Microsoft Foundry | AI model hosting | | CosmosDB | Agent data storage | | Container Apps Environment | Agent runtime | | Virtual Network | Network isolation | | Key Vaults | Secret management | | Storage Accounts | Agent file storage | ### Per-Agent Resource Groups Each deployed agent has its own resource group: **1. Search for Agent Groups** Search for resource groups matching: `cf-rg-agent-*` **2. Delete Each Group** Delete each agent resource group individually **3. Confirm Each Deletion** Confirm each deletion when prompted *** ## Step 5: Remove Azure Lighthouse Delegation (If Applicable) If Azure Lighthouse was configured for cross-tenant management, remove the delegation. **1. Navigate to Service Providers** In Azure Portal, search for **Service providers** **2. View Delegations** Click **Service provider offers** to see active delegations **3. Find ContraForce** Locate the ContraForce delegation **4. Remove Delegation** Click the delegation, then click **Delete** *** ## Offboarding Checklist Use this checklist to ensure complete removal: ### Enterprise Applications * [ ] ContraForce API removed * [ ] ContraForce Portal removed * [ ] ContraForce Sentinel Hunting removed * [ ] ContraForce for MDE removed * [ ] ContraForce Gamebooks for MDE removed * [ ] ContraForce Gamebooks for Identity removed * [ ] ContraForce Gamebooks for Email removed ### Azure Resources (Sentinel Deployments) * [ ] `rg-contraforce-apollo` resource group deleted * [ ] `microsoftsentinel-Publish-Incident-To-Apollo` API connection deleted * [ ] `Publish-Incident-To-Apollo` Logic App deleted * [ ] `Run-Playbook-Publish-Incident-To-Apollo` Automation Rule deleted * [ ] ContraForce API role assignments removed ### Agent Resources (If Applicable) * [ ] `cf-rg-agent-center` resource group deleted * [ ] All `cf-rg-agent-*` resource groups deleted ### Azure Lighthouse (If Applicable) * [ ] ContraForce delegation removed *** ## Verifying Complete Removal After completing the offboarding steps, verify removal: ### Check Enterprise Applications **1. Search Applications** In Microsoft Entra ID, search Enterprise applications for "ContraForce" **2. Verify Empty Results** Confirm no ContraForce applications appear ### Check Azure Resources **1. Search Resources** In Azure Portal, use the global search for "contraforce" **2. Verify Empty Results** Confirm no ContraForce resources appear ### Check Role Assignments **1. Review IAM** Check Access Control (IAM) on your Sentinel resource group **2. Verify No ContraForce** Confirm no ContraForce service principals have assignments *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Can't delete enterprise app** | Insufficient permissions | Ensure you have Cloud App Admin, Application Admin, or Global Admin role | | **Resource group won't delete** | Resources have locks | Remove resource locks before deleting | | **Role assignment won't remove** | Permission denied | Ensure you have Owner access to the subscription | | **Can't find Apollo resource group** | Different naming | Search for "contraforce" in all resource groups | | **Logic App deletion fails** | Automation rule dependency | Delete the automation rule first | ### Resource Locks If you encounter "Cannot delete due to resource locks": **1. Navigate to Resource Group** Open the resource group in Azure Portal **2. Open Locks** Click **Locks** in the left navigation **3. Delete Locks** Delete any locks on the resource group **4. Retry Deletion** Attempt to delete the resource group again *** ## Re-Onboarding After Offboarding If you need to reconnect ContraForce in the future: 1. Contact the ContraForce team for a new workspace invite link 2. Follow the standard onboarding process from the **Workspace Center** 3. All resources will be recreated 4. Historical data from before offboarding will not be available > [!NOTE] > > Offboarding is permanent. If you think you may reconnect in the future, consider disabling functionality instead of fully removing it. Contact [support@contraforce.com](mailto:support@contraforce.com) to discuss options. *** ## Getting Help If you encounter issues during offboarding: > **[Email Support](mailto:support@contraforce.com)** > > [support@contraforce.com](mailto:support@contraforce.com) > **[Submit a Ticket](https://help.contraforce.com/helpcenter/support/contact-us)** > > Open a support ticket *** ## Related Guides > **[Enterprise Applications](/guides/technical/enterprise-applications)** > > Overview of all service principals > **[Azure Resources Deployed](/guides/technical/azure-resources-deployed)** > > Complete resource documentation > **[XDR Onboarding](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Re-onboarding the Defender module > **[Sentinel Onboarding](/guides/onboarding/microsoft-sentinel-module)** > > Re-onboarding the SIEM module *** > [!NOTE] > > Questions about offboarding? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # User Roles & Permissions Source: https://docs.contraforce.com/guides/general-support/roles-and-permissions-reference See the permissions of every ContraForce organization role and workspace role, who can grant roles and API keys, and who can run or approve Gamebooks. This reference lists every ContraForce role, what it allows, and who can hand it out. > [!NOTE] > > ContraForce uses two kinds of roles. An **organization role** controls what someone can manage across your organization. A **workspace role** controls what they can do inside one customer workspace. Most people need both. *** ## How roles work together > **Organization roles** > > One per user, set in **Settings → User Management**. Controls users, groups, workspaces, billing, agents and content across the organization. > **Workspace roles** > > One per user per workspace, set in the workspace's **IAM** tab, directly or through a group. Controls incidents, Gamebooks, modules and settings in that workspace. ``` Organization role → what you can manage across the organization + Workspace role → what you can do inside each workspace you are assigned to ``` > [!WARNING] > > To work inside a workspace, a user needs a workspace role there. An Org Admin or Workspace Admin can open any workspace your organization manages to set it up, but the incident list and the actions inside a workspace still follow their workspace role. Everyone else can open only the workspaces where they hold a workspace role. *** ## Organization roles | Role | In one line | Typical users | | - | - | - | | **Org Admin** | Runs the organization and decides who gets access | Business owners, platform administrators | | **User Admin** | Manages people: adds and removes Members, syncs from Entra, manages groups | Team leads, IT administrators | | **Workspace Admin** | Adds and manages customer workspaces and who can access them | Onboarding and delivery leads | | **Agent Admin** | Runs the AI agents and their standard operating procedures (SOPs) day to day | Automation and SOC engineering leads | | **Content Admin** | Governs detection content in the Content Management Center | Detection engineering leads | | **Content Operator** | Authors detection content in the Content Management Center | Detection engineers | | **Member** | Uses the portal in the workspaces they are assigned to | SOC analysts, engineers, account managers | > [!NOTE] > > **Content Admin** and **Content Operator** are offered only when the [Content Management Center](/guides/content-management-center/overview) is enabled for your organization. ### What each organization role can do | Capability | Org Admin | User Admin | Workspace Admin | Agent Admin | Content Admin / Operator | Member | | - | :-: | :-: | :-: | :-: | :-: | :-: | | Add new users as **Member** | ✓ | ✓ | — | — | — | — | | Add users with any other role, or with workspace access | ✓ | — | — | — | — | — | | Change a user's organization role | ✓ | — | — | — | — | — | | Remove Members, sync users from Entra | ✓ | ✓ | — | — | — | — | | Remove users above Member | ✓ | — | — | — | — | — | | Create groups, rename them, remove members | ✓ | ✓ | — | — | — | — | | Add people to a group that gives workspace access | ✓ | Only an Owner of every workspace of the group | — | — | — | — | | Import an Entra group (members join as Member) | ✓ | ✓ | — | — | — | — | | Import an Entra group with a higher role | ✓ | — | — | — | — | — | | Add, onboard and remove customer workspaces | ✓ | — | ✓ | — | — | — | | Assign users and groups to any workspace | ✓ | — | ✓ | — | — | — | | Subscribe or reactivate [billing](/guides/general-support/cost-management-center) | ✓ | — | ✓ | — | — | — | | Create, change or re-enable service accounts and API keys | ✓ | — | — | — | — | — | | Disable or delete service accounts, revoke API keys | ✓ | ✓ | — | — | — | — | | Create, change and delete organization webhooks, read their delivery logs | ✓ | — | — | ✓ | — | — | | Deploy and configure agents | ✓ | — | — | ✓ | — | — | | Delete an agent deployment | ✓ | — | — | — | — | — | | Workspace profiles | ✓ | — | — | — | — | — | | Author detection content | ✓ | — | — | — | ✓ | — | | Govern detection content (approvals, repository settings) | ✓ | — | — | — | Content Admin only | — | | See every workspace your organization manages in the Workspaces list | ✓ | — | ✓ | — | — | — | | Open a workspace without holding a workspace role there | ✓ | — | ✓ | — | — | — | > [!NOTE] > > Every other role sees, in the Workspaces list, only the workspaces where it holds a workspace role, because those are the ones it can open. To give someone a workspace, an Org Admin or Workspace Admin assigns them a workspace role there. > [!NOTE] > > **You can only grant what you hold.** Only an Org Admin gives out a role above Member, workspace access or an API key. A User Admin manages *people* (who is in the organization) but not *access* (what they can do), much like the User Administrator role in Microsoft Entra ID. ### Org Admin > **Use cases** > > * Platform administrators responsible for ContraForce setup > * Business owners who need full control > * The people who decide who gets elevated access > **Assignment guidelines** > > * Keep at least two Org Admins for continuity. ContraForce never lets the last working Org Admin be demoted or removed. > * Limit the role to a few trusted people and review it quarterly. > * Org Admin does not include workspace data: give yourself a workspace role where you need to work. ### User Admin > **Can** > > * Add new users to the organization as **Member**, without workspace access > * Remove Members and sync users from Microsoft Entra ID > * Create, rename and delete groups, and remove members from groups > * Add people to a group that does not give workspace access, or to one where they are an Owner of every workspace the group is assigned to > * Import Entra groups whose members join as **Member** > * Disable or delete service accounts and revoke their API keys > **Cannot** > > * Change anyone's organization role, including their own > * Add users with a role above Member, or with a workspace assignment > * Change or reactivate an existing user through **Add Users** > * Create, change, re-key or re-enable service accounts > * Make an Entra or SCIM group grant a role above Member > * Open a workspace where they hold no workspace role ### Workspace Admin > **Can** > > * Add, onboard, bulk-import and remove customer workspaces > * Assign users and groups to any workspace and set their workspace roles > * Open any workspace your organization manages, even without a workspace role there > * Subscribe or reactivate billing > **Cannot** > > * Manage organization users, roles or groups > * Use workspace profiles (Org Admin only) ### Agent Admin > **Can** > > * Deploy and configure agents and choose which workspaces they serve > * Manage SOPs > * Create, change and delete organization webhooks and read their delivery logs > **Cannot** > > * Delete an agent deployment (Org Admin only) > * Manage users, roles or workspaces > * Open a workspace where they hold no workspace role ### Content Admin and Content Operator > **Details** > > These organization roles govern the [Content Management Center](/guides/content-management-center/overview#permissions): a **Content Operator** authors content; a **Content Admin** also governs it (approvals and repository settings). An Org Admin can do both. They are different from the **Content Admin** *workspace* role below, which manages analytic rules inside one workspace. ### Member > **Details** > > * Sees only the workspaces they are assigned to, with the access their workspace role gives > * Default role for most team members; combine it with workspace roles *** ## Workspace roles | Role | In one line | | - | - | | **Owner** | Full control of the workspace, including its users, modules and settings | | **Content Admin** | Manages the workspace's analytic rules and works incidents | | **Incident Responder** | Works incidents and runs Gamebooks and response actions | | **Incident Analyst** | Works incidents; requests approval to run Gamebooks | | **Workspace Reader** | Read-only access to the workspace | ### What each workspace role can do **Incidents** | Capability | Owner | Content Admin | Responder | Analyst | Reader | | - | :-: | :-: | :-: | :-: | :-: | | View incidents and their details | ✓ | ✓ | ✓ | ✓ | ✓ | | Change status, assign, classify and close | ✓ | ✓ | ✓ | ✓ | — | | Add, edit and delete comments | ✓ | ✓ | ✓ | ✓ | — | | Send an email or webhook from an incident | ✓ | ✓ | ✓ | ✓ | — | | Create and update tickets | ✓ | ✓ | ✓ | ✓ | — | | Log Search | ✓ | ✓ | ✓ | ✓ | — | **Response** | Capability | Owner | Content Admin | Responder | Analyst | Reader | | - | :-: | :-: | :-: | :-: | :-: | | Run Gamebooks and response actions | ✓ | Request approval | ✓ | Request approval | — | | Approve or deny a queued Gamebook (approvers are chosen from the workspace's Owners) | ✓ | — | — | — | — | | Choose the workspace's Gamebook approvers | ✓ | — | — | — | — | | Start an agent investigation manually | ✓ | — | ✓ | — | — | **Configuration** | Capability | Owner | Content Admin | Responder | Analyst | Reader | | - | :-: | :-: | :-: | :-: | :-: | | Configure modules and data connectors | ✓ | — | — | — | — | | Add modules, refresh environments | ✓ | ✓ | — | — | — | | Notification settings | ✓ | — | — | — | — | | Create, edit, enable and deploy analytic rules | ✓ | ✓ | — | — | — | | View analytic rules | ✓ | ✓ | ✓ | ✓ | ✓ | | Manage workspace policies | ✓ | — | — | — | — | | Configure the workspace's agents | ✓ | — | — | — | — | **Administration** | Capability | Owner | Content Admin | Responder | Analyst | Reader | | - | :-: | :-: | :-: | :-: | :-: | | Add and remove workspace users and groups, change their roles | ✓ | — | — | — | — | | View workspace settings | ✓ | ✓ | ✓ | ✓ | ✓ | | Change workspace settings | ✓ | — | — | — | — | > [!NOTE] > > Org Admins and Workspace Admins can also manage any workspace's users and groups without being its Owner. The last Owner of a workspace cannot be demoted. *** ## Common role assignments | Team member | Organization role | Typical workspace role | | - | - | - | | SOC manager | Org Admin | Owner | | Team lead who manages people | User Admin | Owner or Incident Responder | | Onboarding lead | Workspace Admin | Owner | | Tier 2 analyst | Member | Incident Responder | | Tier 1 analyst | Member | Incident Analyst | | Detection engineer | Member (or Content Operator) | Content Admin | | Account manager | Member | Workspace Reader | | Customer stakeholder | Member (customer's organization) | Workspace Reader or Incident Analyst | *** ## Best practices > **Apply least privilege** > > Start people as **Member** with **Incident Analyst** or **Workspace Reader**, and raise access only when their work needs it. > **Separate people management from access** > > Give day-to-day user management to **User Admins**. Keep role changes and API keys with a small group of **Org Admins**. > **Use groups for consistent workspace access** > > Assign groups like "SOC Tier 1" to workspaces with a fixed role. Remember that adding someone to such a group gives them that access, so only an Org Admin (or an Owner of every workspace the group covers) can add people to it. > **Review regularly** > > Review Org Admins, API keys and workspace Owners every quarter. *** ## Frequently asked questions > **Why can't a User Admin change roles?** > > Every role above Member includes permissions a User Admin does not have, so changing roles, giving workspace access and creating API keys are reserved for Org Admins. A User Admin who tries sees "Only an organization Admin can…" and nothing is changed. > **Can a user have different roles in different workspaces?** > > Yes. Each user has one role per workspace, and it can differ between workspaces. > **What's the difference between Owner and Incident Responder?** > > Both work incidents and run Gamebooks. Only an Owner configures the workspace: modules, notifications, policies, approvers and its users. > **Why can't I see a workspace's incidents as an Org Admin?** > > Organization roles don't include workspace data. Assign yourself a workspace role in that workspace's **IAM** tab. > **Can I create custom roles?** > > Not currently. Contact support if the predefined roles don't fit your needs. *** ## Related guides > **[User Management](/guides/general-support/user-group-management)** > > Add users, groups and roles > **[User & Group Management for Partners](/guides/onboarding/user-group-management-for-providers)** > > Set up users and groups across customer workspaces > **[Service Accounts](/guides/general-support/service-accounts)** > > API keys and their scopes > **[Content Management Center](/guides/content-management-center/overview)** > > Detection content and its permissions *** > [!NOTE] > > Questions about roles and permissions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Service Accounts and API Keys Source: https://docs.contraforce.com/guides/general-support/service-accounts Create service accounts for the ContraForce v2 API, authenticate with a client ID and secret, scope each credential, and rotate secrets with zero downtime. Service accounts are non-human identities that your applications, scripts, and integrations use to call the ContraForce v2 API. Each service account authenticates with a Client ID and Client Secret, and every credential carries its own set of granular API scopes that determine exactly what it can do across the organization. > [!NOTE] > > **Who is this for?** Organization Admins and security engineers who need to connect external tools, SIEM pipelines, ticketing systems, or custom automations to ContraForce without using a human user account. ## Prerequisites * **Org Admin** role to create a service account, change it, issue it a credential, or re-enable it. An API caller needs to be a service account whose own organizational role is **Admin**. * The `org:service-accounts:manage` API scope (or, in the portal, the Org Admin or User Admin role) to disable a service account, revoke a credential, or delete a service account * A clear understanding of the API scopes the integration needs — start with the minimum and expand as required > [!WARNING] > > Service accounts can only call the **v2 API** (`https://portal.contraforce.com/api/v2/...`). Requests to the v1 API are rejected with `403 Forbidden`. ## How Authorization Works Authorization for service accounts is driven by **API scopes on each credential**. Scopes define what a credential is allowed to call. * **Scopes decide *what*** — each scope (for example, `incidents:read`) authorizes a specific class of API action. * **Cross-workspace by default** — v2 endpoints that span workspaces (such as `POST /api/v2/incidents/across-workspaces`) run as scope-authorized calls and return data from every workspace the service account can see in one request. There is no need to target a single workspace per call. * **Multiple credentials per account** — a single service account can carry several credentials, each with a different scope set and expiration. This enables zero-downtime rotation and lets one integration hold read-only scopes while another carries write scopes. * **Granting access also needs the Admin role**: scopes decide what a credential can call, but actions that grant access (changing organizational roles, creating service accounts, or issuing them credentials) also need the service account's own organizational role to be **Admin**. ## Where to Find Service Accounts Navigate to **Settings → Developers** in the ContraForce Portal. Service accounts appear in the **Integrations** table alongside [webhooks](/guides/technical/configure-webhooks), marked with a key icon and the type **Service Account**. ## Creating a Service Account **1. Open the Developers tab** In the Portal, go to **Settings → Developers** and click **Add Integration → Service Account**. **2. Enter basic details** Provide a **Name** (up to 200 characters) and an optional **Description** (up to 1000 characters). Use a name that identifies the calling system — for example, `SIEM-ingest-prod` or `Ticketing-bridge`. **3. Select API scopes for the initial credential** Pick the scopes the first credential should carry. Scopes follow the `{resource}:{action}` pattern and are grouped into **Workspace Scopes** (operate on workspace-owned resources such as incidents and Gamebooks) and **Organization Scopes** (operate on org-level resources such as users and webhooks). > [!TIP] > > Follow least-privilege. Grant only the scopes the integration actually calls. You can always issue a second credential with broader scopes later. **4. Optional — set credential expiration** Choose an expiration date if the credential should automatically stop working after a certain point. Leave blank for a credential that never expires. **5. Create and capture the secret** Click **Create**. ContraForce returns the **Client ID** and a **Client Secret**. > [!WARNING] > > The Client Secret is shown **once** and cannot be retrieved again. Copy it immediately into your secret store (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, etc.). If you lose it, revoke the credential and issue a new one. ## Authenticating to the v2 API Service accounts use **HTTP Basic authentication** (RFC 7617). Encode `ClientId:ClientSecret` in Base64 and send it in the `Authorization` header. ```bash theme={null} curl https://portal.contraforce.com/api/v2/incidents/across-workspaces \ -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \ -H "Content-Type: application/json" \ -d '{"isFirstCall": true}' ``` On success, ContraForce records usage metadata on the credential (`LastUsedAt`) and writes an entry to the service account's **Request Logs**. ### Authentication failures | Response | Likely cause | | - | - | | `401 Unauthorized` | Invalid Client ID, invalid Client Secret, or malformed `Authorization` header | | `403 Forbidden` | Credential is revoked, expired, or the service account is disabled | | `403 Forbidden` | Request targets a v1 route (`/api/...` without `/v2/`) — service accounts are v2-only | | `403 Forbidden` | Authenticated but the credential is missing the scope the endpoint requires, or the action needs a service account whose organizational role is Admin | ## API Scopes Reference Scopes are granted **per credential**. A service account can hold multiple credentials with different scope sets. ### Workspace scopes Authorize actions against workspace-owned resources. Cross-workspace endpoints use these scopes and automatically return only data from workspaces the service account is allowed to see. | Scope | Grants | | - | - | | `incidents:read` | View incidents, entities, evidence, alert rules, and comments | | `incidents:write` | Assign incidents, update status, and perform bulk updates | | `incidents:comments` | Create, update, and delete incident comments | | `gamebooks:read` | View Gamebooks, Gamebook history, and incident Gamebooks | | `gamebooks:execute` | Submit new Gamebook runs, subject to workspace policies and approvals. See [Running Gamebooks](#running-gamebooks-with-a-service-account) | | `datasources:read` | View connected data sources | | `tickets:read` | Search service tickets | | `tickets:manage` | Link and unlink tickets to incidents | | `investigation:read` | View user sign-in logs and directory logs | ### Organization scopes Authorize actions on org-level resources. | Scope | Grants | | - | - | | `webhooks:read` | View webhook configurations and delivery logs | | `webhooks:manage` | Create, update, delete, pause, resume, and test webhooks | | `org:users:read` | View organization users and profiles | | `org:users:manage` | Add, update, and remove users (a service account that is not an Admin can only add new users as Member, with no workspace access) | | `org:users:roles` | Assign and modify organizational roles (also needs the Admin organizational role) | | `org:service-accounts:read` | View service accounts and credentials | | `org:service-accounts:manage` | Disable and delete service accounts and revoke credentials. Creating, updating, issuing credentials, and re-enabling also need the Admin organizational role | | `org:azure:read` | View the Azure subscriptions and resources used for workspaces | | `org:azure:manage` | Use the Azure lookups and validation that workspace onboarding relies on | > [!NOTE] > > Write scopes imply their matching read scope. Granting `incidents:write` automatically authorizes `incidents:read` on the same endpoint set. `gamebooks:execute` does **not** imply `gamebooks:read`; grant both to submit runs and poll their results. > **[Endpoint Reference](/api-reference/endpoints)** > > Every v2 endpoint grouped by scope with full route paths > **[Object Models](/api-reference/models)** > > Copy-pasteable JSON request and response examples ## Running Gamebooks with a Service Account A service account can start an incident-response Gamebook from your own tools, such as a SOAR platform or a ticketing workflow. The run goes through the same workspace Gamebook policies, integration permissions, and approval settings as a run started in the Portal, and the service account is recorded as the initiator in Gamebook history and the incident audit. ### Set up the service account **1. Give the service account a workspace role** To run a Gamebook right away, the service account needs the **Owner** or **Incident Responder** role on the target workspace. With any other workspace role, it can only submit a run for approval (`"isQueued": true`). A role on a different workspace does not count. **2. Add the Gamebook scopes to the credential** When you create or edit the credential, select **Gamebooks → Execute** (`gamebooks:execute`). Also select **Gamebooks → Read** (`gamebooks:read`) to poll for results, and **Incidents → Read** (`incidents:read`) to look up the incident's entities. **3. Review the workspace's Gamebook policies** [Run policies](/guides/getting-started/workspace-policies) treat a service-account run like one from a service provider managing the workspace, so policies that apply to anyone or to service providers also apply to it. **Block the action** stops the run, and **Ask an approver first** queues it for a person to approve in the Portal. Partner approval settings can also queue it. ### Submit a run 1. Pick the playbooks to run from the [playbook catalog](/api-reference/endpoints#playbook-catalog). Each entry lists the `id` and `entityType` to send and the kind of incident entity it acts on. 2. Get the incident with `GET /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId}` (`incidents:read`) and take the target's `id` from `investigationDetails.entities[]`. See [Finding the entityId](/api-reference/endpoints#finding-the-entityid). 3. Submit the run with `POST /api/v2/workspaces/{workspaceId}/gamebooks/run`. See the [Endpoint Reference](/api-reference/endpoints) for the request fields and validation rules. 4. Store the returned `data.id` and poll `GET /api/v2/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}?source={source}&withUserDetails=false` until that Gamebook finishes. ```bash theme={null} curl https://portal.contraforce.com/api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/gamebooks/run \ -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \ -H "Content-Type: application/json" \ -d '{ "incidentId": "", "source": "Sentinel", "incidentTitle": "Suspicious sign-in activity", "playbooks": [ { "id": "scanendpoint", "entityId": "", "entityType": "Endpoint", "sequence": 1 } ] }' ``` The response tells you what happened to the run: | `data.status` | `data.isQueued` | Meaning | | - | - | - | | `Running` | `false` | Sent for execution. It has not necessarily finished; poll history for the result. | | `Pending` | `true` | Accepted and waiting for a person to approve it in the Portal. It has **not** run. Do not submit it again to try to release it. | ### What a service account cannot do * **Approve, retry, deny, or cancel** a Gamebook. These stay in the Portal. * **Run Block IP.** Block IP is not available to service accounts yet, including runs submitted for approval. * **Add an approval reason.** Reasons are added as incident comments and are only available in the Portal. > [!WARNING] > > Submitting a run is not idempotent: sending the same request twice can start two runs. After a timeout, check the incident's Gamebook history before you resubmit, especially for containment actions. ## Managing the Service Account Open a service account's detail page from **Settings → Developers** to manage it. The page has three tabs: **General**, **Request Logs**, and **Audit**. ### General tab * **Disable** — Blocks all credentials on the service account from authenticating. Use this for a temporary freeze (for example, during an incident). * **Enable** — Re-activates a disabled service account. * **Delete** — Permanently removes the service account and all its credentials. Cannot be undone. * **Edit** — Update name and description. > [!WARNING] > > Deleting a service account breaks every integration using its credentials. Disable first and monitor **Request Logs** for any stragglers before deleting. ### Credential management Each credential shows its prefix (first 6 characters), status, expiration, scopes, last-used timestamp, and creation date. | Action | What it does | | - | - | | **New Credential** | Issues an additional credential with its own scopes and expiration. Use for rotation or to split read vs. write integrations. | | **Revoke** | Immediately invalidates a credential. Cannot be undone. | ### Request Logs tab Shows every API call made using any credential on the service account: timestamp, HTTP method, path, response status, latency, and source IP. Use this to audit integration behavior or troubleshoot `403` failures. ### Audit tab Shows lifecycle events — creation, updates, credential issuance, revocation, disable/enable, and deletion — attributed to the Portal user who performed each action. ## Rotating a Credential (Zero Downtime) Because a service account can hold multiple active credentials, you can rotate secrets without an outage. **1. Issue a new credential** On the service account's **General** tab, click **New Credential**. Select the same scopes as the credential you're rotating and copy the new Client Secret immediately. **2. Deploy the new secret** Update your integration's secret store with the new Client Secret. Deploy the configuration change. **3. Verify traffic on the new credential** Check **Request Logs** and confirm that requests are coming in. The new credential's **Last used** timestamp updates within seconds of the first authenticated call. **4. Revoke the old credential** Once all traffic has shifted, click **Revoke** on the old credential. Any residual caller using the old secret will receive `403 Forbidden`. ## How Service Accounts Work * **Identity** — Each service account is an organization member with `IsServiceAccount = true`. It is not visible in **Settings → User Management** and cannot sign in to the Portal. * **Client ID** — The stable GUID of the service account. Safe to share. * **Client Secret** — 32 cryptographically random bytes, Base64-encoded. Stored as a SHA-256 hash (for authentication lookups) and as AES-256-GCM ciphertext wrapped by an RSA key in Azure Key Vault (envelope encryption). The plaintext is shown only at creation. * **Authorization** — Every v2 endpoint declares a required scope. On each request, the authentication middleware resolves the credential, confirms it is active and unexpired, and projects its scopes onto the request principal. The endpoint's scope filter then allows or denies. Endpoints that span workspaces filter returned data to the set of workspaces the service account is entitled to see. * **Isolation** — Service accounts are deliberately restricted to the v2 API. The v2 design uses resource-based routing with per-request scope authorization, removing an authorization bypass that existed in v1. ## Best Practices * **One service account per integration.** Don't share credentials across systems — it fragments audit trails and breaks rotation. * **Split read and write.** Issue separate credentials for read-only monitoring and write automations on the same service account, so a leak of the monitoring secret can't mutate state. * **Minimum scopes.** Grant read-only scopes first. Add write scopes only when an integration actually needs to mutate state. * **Expiration everywhere.** Set a credential expiration for anything non-critical and renew on a schedule. * **Name for humans.** Future-you will grep the audit log. `Jira-incident-sync-prod` beats `sa-3`. * **Monitor the Request Logs.** A sudden drop in traffic usually means a rotation went wrong. A sudden spike may mean a runaway script. ## Troubleshooting | Symptom | Fix | | - | - | | `401 Unauthorized` immediately after creation | Verify the `Authorization` header is `Basic ` with no whitespace | | `403 Forbidden` with "Service accounts must use the v2 API" | Change the URL to `/api/v2/...` | | `403 Forbidden` on a specific endpoint only | The credential is missing the required scope: issue a new credential with the correct scope. If the detail says "Only an organization Admin can...", the action needs a service account whose organizational role is Admin. | | `403 Forbidden` with "credential is not active" | The credential was revoked or expired. Issue a new credential. | | `403 Forbidden` with "service account is disabled or not found" | Re-enable the service account under **Settings → Developers** | | Cross-workspace endpoint returns an empty list | The service account has no visible workspaces, or no data matched the filters in visible workspaces. | | Credential works intermittently | Confirm no other integration is rotating the same credential. Use one credential per integration. | *** ## Related Guides > **[Setting Up Webhooks](/guides/technical/configure-webhooks)** > > Send signed incident events to your ticketing system, SIEM, or chat tools from the same Developers tab. > **[User Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > See which organization roles can create, disable, and delete service accounts and API keys. > **[Error Reference](/api-reference/errors)** > > Look up v2 API error codes, such as INSUFFICIENT\_SCOPE, with their HTTP status and what to do. > [!NOTE] > > If you have questions about service accounts or need help planning an integration, contact us at [support@contraforce.com](mailto:support@contraforce.com). # User Management: Add Users and Groups Source: https://docs.contraforce.com/guides/general-support/user-group-management Add users from Microsoft Entra ID, organize them into groups, assign workspace roles in each workspace's IAM tab, and change or remove a user's access. ContraForce provides flexible user management with role-based access control. Add users from your Microsoft Entra ID directory, assign organizational and workspace roles, and control exactly what each team member can access. > [!NOTE] > > ContraForce integrates with Microsoft Entra ID (formerly Azure AD) to pull user identities. Users must exist in Microsoft Entra ID before they can be added to ContraForce. ## How Users, Roles, and Groups Fit Together > **Organizational Roles** > > Control who can manage users, groups, and workspace settings across your organization > **Workspace Roles** > > Define what users can do within specific customer workspaces *** ## User Roles at a Glance ContraForce uses a two-tier role system: **Organizational Roles** control administrative access, while **Workspace Roles** control operational access. ### Workspace Roles Quick Reference | Role | View Incidents | Work Incidents | Run Gamebooks | Configure Modules | Manage Workspace Users | | - | :-: | :-: | :-: | :-: | :-: | | **Owner** | ✓ | ✓ | ✓ | ✓ | ✓ | | **Content Admin** | ✓ | ✓ | Request approval | Add modules only | — | | **Incident Responder** | ✓ | ✓ | ✓ | — | — | | **Incident Analyst** | ✓ | ✓ | Request approval | — | — | | **Workspace Reader** | ✓ | — | — | — | — | > **[Complete Role Reference](/guides/general-support/roles-and-permissions-reference)** > > View detailed permissions for all organizational and workspace roles *** ## When to Add Users Adding users is **not** part of module onboarding. First, sign in at [portal.contraforce.com](https://portal.contraforce.com), grant the core ContraForce app consents, and deploy your modules. Once your organization is set up, add and manage users at any time from **Settings**. > [!TIP] > > Add at least one Org Admin early. This ensures you always have full access to manage users, groups, and workspaces. *** ## Adding and Managing Users You add and manage users through the **Settings** page. User and group management is handled entirely within the ContraForce portal — no separate enterprise application consent is required. ### Step 1: Access User Management **1. Open Settings** Click **Settings** in the navigation menu **2. Select User Management** Click the **User Management** tab **3. View Current Users** The user list displays all users with access to ContraForce ![Settings, User Management tab](https://mintcdn.com/contraforce/pIE5AEAm59CXnImm/images/user-management-settings-tab.png?fit=max\&auto=format\&n=pIE5AEAm59CXnImm\&q=85\&s=e183fd1d61184944f0be7d1ae84125ec) ### Step 2: Add New Users **1. Click Add User** Click the **Add User** button in the top right corner **2. Search for User** Search for the user by name or email in the Microsoft Entra ID directory **3. Select User** Click the user to select them **4. Choose the Organization Role** New users start as **Member**. Only an Org Admin can choose a higher role. Give workspace access afterwards from each workspace's **IAM** tab or through a group. **5. Save** Click **Add** to complete the process ![Invite people to the organization dialog](https://mintcdn.com/contraforce/pIE5AEAm59CXnImm/images/user-management-invite-users.png?fit=max\&auto=format\&n=pIE5AEAm59CXnImm\&q=85\&s=cfc9360fdef3e1fddd6b48f975df8f3d) > [!NOTE] > > The **Add User** button appears for Org Admins and User Admins. A User Admin can add new users as **Member** only; adding someone with a higher role, or changing an existing user, needs an Org Admin. *** ## Understanding Role Types ### Organizational Roles Organizational roles control administrative functions across your organization: | Role | Add Members | Change Roles | Manage Groups | Add Workspaces | Manage Workspace Access | API Keys | | - | :-: | :-: | :-: | :-: | :-: | :-: | | **Org Admin** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | **User Admin** | ✓ | — | ✓ | — | — | — | | **Workspace Admin** | — | — | — | ✓ | ✓ | — | | **Agent Admin** | — | — | — | — | — | — | | **Content Admin / Content Operator** | — | — | — | — | — | — | | **Member** | — | — | — | — | — | — | Agent Admins run the AI agents, and the content roles work in the Content Management Center. See the [roles reference](/guides/general-support/roles-and-permissions-reference) for every role's full permissions. ### Workspace Roles Workspace roles control what users can do within specific customer workspaces: **Owner** **Full control of the workspace** * Work incidents and run Gamebooks * Configure modules, data connectors, notifications and policies * Manage the workspace's users, groups and Gamebook approvers *Best for: Team leads, senior analysts, workspace owners* **Content Admin** **Detection content focus** * Work incidents; request approval to run Gamebooks * Create, edit, enable and deploy analytic rules * Add modules and refresh environments *Best for: Detection engineers* **Incident Responder** **Operational access for active response** * Work incidents (status, assignment, comments, tickets) * Run Gamebooks and response actions * Cannot configure modules or manage users *Best for: SOC analysts who need to take action* **Incident Analyst** **Investigation and triage** * Work incidents (status, assignment, comments, tickets) * Request approval to run Gamebooks * Cannot configure the workspace *Best for: Tier 1 analysts who triage and escalate* **Workspace Reader** **Read-only access** * View incidents, rules and settings * Cannot change anything *Best for: Stakeholders and account managers* *** ## User Groups Simplify access management by organizing users into groups. ### Benefits of Groups > **Bulk Assignment** > > Assign workspace access to multiple users at once > **Easier Management** > > Update group membership instead of individual users > **Consistent Access** > > Ensure team members have the same permissions ### Recommended Default Groups Setting up default groups during initial configuration saves time and ensures consistent access patterns. #### Suggested Partner Groups | Group Name | Description | Suggested Workspace Role | | :- | :- | :- | | SOC Tier 1 | Front-line analysts handling initial triage | Incident Analyst | | SOC Tier 2 | Senior analysts with response capabilities | Incident Responder | | SOC Managers | Team leads overseeing operations | Owner | | Detection Engineers | Staff tuning analytic rules | Content Admin | | Account Managers | Customer relationship managers | Workspace Reader | ### Creating Groups Groups are managed on the **Group Management** tab under **Settings**. ![Settings, Group Management tab with the Add Group button](https://mintcdn.com/contraforce/pIE5AEAm59CXnImm/images/settings-group-management-tab.png?fit=max\&auto=format\&n=pIE5AEAm59CXnImm\&q=85\&s=263f5cf78399611af3af205237274e25) **1. Navigate to Group Management** Go to **Settings** > **Group Management** **2. Create New Group** Click **Add Group** and enter a name **3. Add Members** Search for and add users to the group. Members get the group's workspace roles, so adding people to a group that is assigned to workspaces needs an Org Admin, or an Owner of every workspace the group is assigned to. **4. Assign to Workspaces** Assign the group to workspaces with appropriate roles *** ## Assigning Users to Workspaces Users need workspace assignments to access customer data. ### Individual Assignment 1. Open the workspace settings 2. Navigate to **Users** or **Access** 3. Click **Add User** 4. Select the user and assign a workspace role 5. Save changes ### Group Assignment 1. Open the workspace settings 2. Navigate to **Groups** or **Access** 3. Click **Add Group** 4. Select the group and assign a workspace role 5. All group members inherit access > [!TIP] > > Use groups for teams that need access to the same set of workspaces. This makes onboarding new team members faster—just add them to the appropriate group. *** ## Managing Existing Users ### Viewing User Details Click any user in the User Management list to view: * Assigned organizational role * Workspace assignments and roles * Group memberships * Last login time ### Editing User Roles **1. Organization role** In **Settings → User Management**, pick the new role in the user's **Organizational Role** column. Only Org Admins can change organization roles; for everyone else the column is read-only. **2. Workspace role** Open the workspace's **IAM** tab and change the user's or group's role. Workspace Owners, Org Admins and Workspace Admins can do this. > [!NOTE] > > An organization always keeps at least one working Org Admin: the last one cannot be demoted. Roles of users provisioned from Microsoft Entra ID through [SCIM provisioning](/guides/technical/scim-provisioning) come from their Entra groups and cannot be changed in the portal. ### Removing Users **1. Select User** Click the user you want to remove **2. Click Remove** Click the **Remove User** or **Delete** button **3. Confirm** Confirm the removal when prompted > [!WARNING] > > Removing a user revokes all their access to ContraForce immediately. This action cannot be undone—you'll need to re-add the user if you want to restore access. *** ## Best Practices > **Follow the principle of least privilege** > > Assign the minimum role necessary for each user's job function. Start with Incident Analyst or Workspace Reader and escalate to Responder or Owner only when needed. > **Use groups for team-based access** > > Create groups that mirror your team structure (e.g., "Tier 1 Analysts", "Senior Responders"). This simplifies access management as team members change. > **Audit user access regularly** > > Review user assignments quarterly to ensure former team members have been removed and current roles are still appropriate. > **Document role assignments** > > Maintain records of who has access to which workspaces and why. This helps with compliance audits and access reviews. > **Separate admin duties** > > Don't give everyone Org Admin or Owner access. Keep role changes and API keys with a few Org Admins, and use User Admins for day-to-day user management. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Can't see Add User button** | Missing User Admin or Org Admin role | Contact your administrator for elevated permissions | | **User not found in dropdown** | User doesn't exist in Microsoft Entra ID | Verify user exists in Microsoft Entra ID | | **Consent flow fails** | Insufficient admin privileges | Admin consent for ContraForce enterprise applications requires a **Global Administrator** account | | **User can't access workspace** | No workspace assignment | Assign user directly or via group to the workspace | | **User has wrong permissions** | Incorrect role assignment | Edit user and assign correct workspace role | | **"Only an organization Admin can…"** | Your organization role can't make this change | Ask an Org Admin. User Admins can add and remove Members, but not remove other roles, change roles or give access | | **Role column is read-only** | You are not an Org Admin, or the user is provisioned through SCIM | Ask an Org Admin, or change the user's Entra groups | *** ## Related Guides > **[User Roles Reference](/guides/general-support/roles-and-permissions-reference)** > > Complete permissions for all roles > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings > **[Enterprise Applications](/guides/technical/enterprise-applications)** > > Service principals and consent > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Managing multiple customers *** > [!NOTE] > > Questions about user management? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Command Dashboard: SOC Metrics Across Workspaces Source: https://docs.contraforce.com/guides/getting-started/command-dashboard Track closed incidents, classification trends, detection rule activity, and Gamebook runs across all your workspaces in one multi-tenant SOC dashboard. The Command Dashboard is ContraForce's mission control center—a unified dashboard that gives you complete visibility into security incidents, Gamebooks queued, and human and agent actions that are audited—across all your managed workspaces. By default, it displays data for all onboarded workspaces, and you can use the [workspace filter](#workspace-filtering) to focus on specific workspaces. ![Command Dashboard showing the Closed Incident Tracker, Classification Trends, Closures by Workspace, and Team Member tables](https://mintcdn.com/contraforce/Tne2Yr5NXQ4PXg82/images/Command-q95.png?fit=max\&auto=format\&n=Tne2Yr5NXQ4PXg82\&q=85\&s=e17b146c663297605daf726e47615619) The Command Dashboard is designed for MSPs, MSSPs, and security teams managing tenants and environments. All data updates in real-time as incidents are detected and resolved. ## Dashboard Cards The Command Dashboard summarizes closures and activity for the workspaces and time window you've selected: > **Closed Incident Tracker** > > Closed incidents by severity. Filter workspaces to see incidents per workspace. Click the total or any severity to open the [Incident Report](/guides/getting-started/incident-report). > **Classification Trends** > > Closed incidents by classification (True Positive, False Positive, Benign Positive, Undetermined) with trends, broken down **By reason** or **By module**. Click a classification to open the [Incident Report](/guides/getting-started/incident-report). > **Closures by Workspace** > > Closed incidents per workspace, by severity. > **Team Member Closed Incident Trends** > > Closures per analyst and agent, by severity. Incidents closed directly in a security tool appear under that tool, for example **DefenderXDR (upstream)**. > **Detection Rule Activity** > > The detection rules that fired, with detection counts, when each was last seen, and the trend. > **Gamebook Activity** > > Gamebooks run in the selected window. > **Gamebook History** > > View all queued Gamebooks that are processing or awaiting for approval. Click any incident to review and approve Gamebook runs. ## Drilling into the Numbers Totals on the Command Dashboard are links. Clicking one opens the **Incident Report**, which lists the closure records behind that number and carries your current time filter and workspace selection with it. > **Closed Incident Tracker** > > Click the donut for every closed incident in the period, or a **High**, **Medium**, **Low**, or **Info** row for that severity alone. > **Classification Trends** > > Click the arrow on a classification card for that classification, or a row inside the **By reason** and **By module** tabs to narrow the report further. ![Severity rows linking to the Incident Report](https://mintcdn.com/contraforce/7eCKFG28WsYKEaUd/images/incident-report/closed-incident-tracker.png?fit=max\&auto=format\&n=7eCKFG28WsYKEaUd\&q=85\&s=f1354a2a9f495d1f10ad17367308ef93) From the report you can adjust the filters, review each closure, open an incident, and print or save the result as a PDF. See [Incident Report](/guides/getting-started/incident-report). ## Where the Incidents Are The incident queue lives on the **Incidents** page in the left navigation, not on the Command Dashboard. There you can: * Search by title or ID, and filter by **Source**, **Severity**, **Status**, **Classification**, **Reason**, and **Assignee** * Filter on the statuses **New**, **Active**, **On Hold**, **Waiting on Customer**, and **Closed** (the page starts on **New** and **Active**) * Show, hide, reorder, and resize columns, including the SLA columns **Time to First Response** and **Time to Resolution** (see [SLA Tracking](/guides/getting-started/sla-tracking)) See [Incident Management](/guides/getting-started/incident-management). ### Incident Handling at Scale Rather than updating incidents manually in batches, **Security Delivery Agents** running **on queue** automatically triage and act on incidents as they arrive. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). Agents set to **On Queue** also pick up incidents that come straight from Defender for Endpoint, with no Microsoft Sentinel forwarding required. See [Defender for Endpoint On Queue](/guides/agent-center/defender-for-endpoint-on-queue). ## Workspace Filtering The workspace filter at the top of the Command Dashboard allows you to customize your view: 1. Click the **Workspace Filter** dropdown 2. Select one or more workspaces to display 3. Your selection persists as you navigate to other pages in ContraForce > [!TIP] > > Your workspace filter selection is maintained across all ContraForce pages during your session. This allows you to focus on specific customers without re-selecting filters on each page. ## Accessing Incident Details To view detailed information about any incident: 1. Open the **Incidents** page and click an incident 2. A quick view opens with the incident's **Summary**, **Comments**, and **Audit** 3. Select **View full details** for the full incident page From the full incident page, you can: * Review the **Summary**, **Comments**, **Rule**, **Entities**, **Logs**, and **Audit** tabs * Run the agent or other actions from the **Actions** menu * Build and run Gamebook response actions * Change the status and assignee ## Next Steps > **[Incident Management](/guides/getting-started/incident-management)** > > A complete workflow for triaging, investigating, and resolving incidents. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings from one central location. > **[Incident Report](/guides/getting-started/incident-report)** > > Drill into any dashboard total to see, filter, and print the closures behind it. > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > Learn how to properly classify incidents to improve detection accuracy. > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Explore all multi-tenant management capabilities. > **[Quick Actions](/guides/getting-started/quick-actions)** > > Press Ctrl + K to jump to portal pages and workspace settings. *** > [!NOTE] > > Need help? Contact the ContraForce Support team at [support@contraforce.com](mailto:support@contraforce.com). # Configuring Security Delivery Agents Source: https://docs.contraforce.com/guides/getting-started/configuring-security-delivery-agents Configure Security Delivery Agents to investigate on demand or On Queue by severity, run Gamebooks at a confidence threshold, and escalate True Positives. Security Delivery Agents (SDAs) automate incident investigation and response within ContraForce. This guide walks you through configuring agents using a phased approach, allowing you to gradually increase automation as you become comfortable with agent capabilities. > [!NOTE] > > Security Delivery Agents follow a three-phase adoption model: manual execution, automatic execution based on severity, and automatic Gamebook execution. This progressive approach helps you build confidence in agent behavior before enabling full automation. ## What Can You Do Here? > **Run Manual Investigations** > > Trigger agent analysis on individual incidents > **Automate by Severity** > > Configure agents to run automatically based on incident status > **Enable Gamebook Execution** > > Allow agents to execute response playbooks automatically > **Set Confidence Thresholds** > > Control when automated actions are permitted > **Apply a True-Positive Policy** > > Use Advanced mode to act differently per classification *** ## Prerequisites Before configuring Security Delivery Agents, ensure you meet the following requirements. | Requirement | Description | | - | - | | **Agent Center Deployed** | Microsoft Foundry infrastructure must be provisioned | | **ContraForce Roles** | Org Admin or Agent Admin, and the Owner role on the workspace | > [!WARNING] > > Prerequisites to Configure Security Delivery Agents: > > * Agent Center must be fully deployed in your environment > * ContraForce Role: Org Admin or Agent Admin > * ContraForce Workspace Role: Owner *** ## Phase 1: Manual Agent Execution In this initial phase, you manually select individual incidents and trigger the agent to run investigations. This allows you to evaluate agent performance before enabling automation. ### Running Agent Investigation **1. Open an Incident** Navigate to the incident you want to investigate **2. Access Actions Menu** Select **Actions** from the incident toolbar **3. Choose Investigation Type** Select one of the following options: * **Run Agent Investigation** — Agent analyzes the incident and provides findings without taking remediation actions * **Run Agent Investigation and Response** — Agent analyzes the incident, compiles a Gamebook from the entities it identifies, and executes the recommended response actions **4. Review Results** Examine the agent's findings and recommendations ### Investigation Options | Option | Description | When to Use | | - | - | - | | **Run Agent Investigation** | Analysis only, no response actions | When you want to review findings before taking action | | **Run Agent Investigation and Response** | Analysis plus automated response | When you trust the agent to execute appropriate responses | > [!TIP] > > Start with investigation-only runs to understand how the agent analyzes your specific incident types before enabling response actions. *** ## Phase 2: Automatic Execution Based on Severity Once you're comfortable with agent behavior, switch the severities you want handled automatically to **On Queue**. On Queue is fully autonomous: the agent picks up incidents of that severity as they arrive. New agents default to On Queue. ### Configuring Automatic Execution **1. Open the Agent** Select **Agents** in the left navigation to open the Agent Center, then configure the agent from the **Agents** tab **2. Set Mode to On Queue** On each severity card (**High**, **Medium**, **Low**, **Info**), set **Mode** to **On Queue** for the severities the agent should process on its own. Leave the others on **Manual** **3. Choose What Happens After a Run** Set **Status after run** (**No Change**, **Active**, **New**, or **Closed**) and turn on **Assign agent to incident** if the agent should become the incident's owner **4. Save Configuration** Select **Save configuration** > [!TIP] > > On Queue also picks up Defender for Endpoint incidents that aren't forwarded to Microsoft Sentinel; see [On Queue Agents for Defender for Endpoint](/guides/agent-center/defender-for-endpoint-on-queue). For Defender XDR incidents, the agent defers to Defender's own automations and skips incidents Defender already resolved; see [Defender Native Automations](/guides/technical/microsoft-defender-native-automations). ### Per-Severity Settings | Setting | What it does | | - | - | | **Mode** | **Manual** runs the agent only when someone triggers it from the incident **Actions** menu. **On Queue** runs it automatically on every incident of that severity | | **Status after run** | The status the incident moves to after the agent finishes | | **Assign agent to incident** | Makes the agent the incident's owner | | **Allow agent to run gamebooks** | Lets the agent run Gamebook response actions (see Phase 3) | | **Confidence to respond** | The 0–100 confidence the agent needs before it runs Gamebooks (see Phase 3) | On Queue decides whether the agent picks up a severity on its own. To limit when it does, set working hours with [Agent Shifts](/guides/agent-center/agent-shifts); outside a shift, new incidents wait for your team. > [!NOTE] > > With **Advanced options** on, **Status after run** and **Assign agent to incident** move from the severity cards to a per-classification policy. See [Advanced Configuration](#advanced-configuration-true-positive-policy). *** ## Phase 3: Automatic Gamebook Execution In this advanced phase, you enable the agent to automatically execute Gamebooks based on confidence thresholds. ### How the Agent Compiles a Gamebook Before it executes anything, the agent builds an **investigation graph** of the incident — the same Entity Context Graph you see in the [Workbench](/guides/getting-started/workbench-overview) — to determine which users, devices, IPs, files, and emails the incident impacted. It then compiles the Gamebook by mapping the appropriate response actions to each impacted entity, based on entity type and the incident's classification. The confidence threshold below decides whether that compiled Gamebook runs automatically or waits for you. ### Enabling Automatic Gamebook Execution **1. Open the Agent** Select **Agents** in the left navigation to open the Agent Center, then configure the agent from the **Agents** tab **2. Enable Gamebook Execution** On each severity card, turn on **Allow agent to run gamebooks** **3. Set Confidence to Respond** Drag the **Confidence to respond** slider (0–100) to the confidence the agent needs before it runs Gamebook actions **4. Save Configuration** Apply your settings to activate automatic Gamebook execution ### Understanding Confidence to Respond **Confidence to respond** is set per severity on a 0–100 scale. The agent runs Gamebook actions only when its confidence meets the threshold; below it, it leaves the actions for an analyst. A higher threshold is more conservative. Each agent investigation comment also shows the agent's **malicious confidence** (0–100) for the incident. Workspace Gamebook run policies (**Workspaces → \[workspace] → Gamebooks**) still apply, so an action can be blocked or sent to an approver even when the agent is confident. See [Workspace Policies](/guides/getting-started/workspace-policies). > [!WARNING] > > Lower confidence thresholds result in more aggressive automation. Start with higher thresholds and adjust based on observed accuracy and your risk tolerance. *** ## Advanced Configuration: True-Positive Policy By default, every agent investigation ends in one post-investigation flow regardless of the agent's verdict. **Advanced** mode replaces that single flow with a policy that acts on the agent's classification, so a True Positive can be escalated for analyst action while a False Positive is closed out. > [!NOTE] > > Advanced mode is opt-in and reversible. While it is **disabled**, agent behavior is exactly as described in Phases 1 to 3, with no change. Enabling it only adds the trigger and per-classification settings below. ### Enabling Advanced Mode **1. Open Agent Configuration** Select **Agents** in the left navigation to open the Agent Center, then configure the agent from the **Agents** tab. **2. Turn on Advanced** Turn on **Advanced options**. The **Classification policy** cards appear below the severity cards. **3. Configure the severities** Severity still drives the agent's **Mode** (**On Queue** or **Manual**), **Allow agent to run gamebooks**, and **Confidence to respond** on each severity card. **4. Configure the policy per classification** For each classification, set what happens when the agent reaches that verdict (see below). **5. Save** Apply your settings. Save is blocked until the webhook list has loaded, so a policy is never saved against an unverified webhook. ### Per-Classification Policy When Advanced mode is on, each of the four classifications has its own policy. For an explanation of the classifications themselves, see [Incident Classifications](/guides/getting-started/incident-classifications). | Setting | Description | | - | - | | **Status after run** | The status the incident moves to (for example, keep a True Positive open for analyst action instead of closing it). | | **Assign agent to incident** | Makes the agent the incident's owner when it reaches this classification. | | **Custom action** | An optional webhook fired when the agent reaches this classification. Use this to escalate into your own SIEM, ticketing, or on-call tooling. | > [!TIP] > > The common True-Positive Policy pattern: for **True Positive**, keep the incident open and set a webhook custom action so your team is paged. For **False Positive** and **Benign Positive**, close the incident with no webhook. ### The Custom Action Webhook The custom action sends the **Agent investigation completed** event (`agent.investigation.completed.v1`) the moment the investigation finishes. The payload carries the agent's verdict and the incident context, signed so your endpoint can verify it. This event is **selected here, on the classification card**. It is not a broadcast subscription: only the webhook a classification card points to receives it. For the payload schema, headers, and signature verification, see [Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook). > [!WARNING] > > If the webhook a card points to is later deleted, paused, disabled, or unsubscribed from the event, the card shows a warning with a link to fix it in **Developers**, and the skipped delivery is recorded as **Failed** rather than dropped silently. Check the card if escalations stop arriving. *** ## Configuration Summary **Phase 1** **Manual Execution:** * User selects individual incidents * User triggers agent via Actions menu * User reviews results before any response * Best for: Initial evaluation and building trust **Phase 2** **Automatic by Severity:** * Agent runs automatically on incidents of the severities set to On Queue * Mode set per severity * Status after run controls where the incident lands * Best for: Scaling investigation capacity **Phase 3** **Automatic Gamebooks:** * Agent executes response playbooks automatically * Confidence to respond controls the action threshold * Full automation of investigation and response * Best for: Mature environments with validated agent accuracy *** ## Best Practices > **Progress through phases sequentially** > > Start with Phase 1 to understand agent behavior before enabling automation. Each phase builds on the previous one. > **Review agent outputs during manual execution** > > Use Phase 1 to validate that agent analysis aligns with your expectations and incident handling procedures. > **Set conservative confidence levels initially** > > Begin with higher confidence thresholds and lower them gradually based on observed accuracy. > **Monitor automated actions regularly** > > Even with full automation enabled, periodically review agent actions to ensure expected behavior. > **Document your configuration choices** > > Keep records of which phases are enabled and your confidence threshold settings for troubleshooting and auditing. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | Agent not processing incidents | Mode not set to On Queue | Set Mode to On Queue for the incident's severity | | Gamebooks not executing | Feature not enabled | Confirm "Allow Agent to run gamebooks" is toggled on | | Too many automated actions | Confidence threshold too low | Raise **Confidence to respond** | | Agent missing incidents | Severity on Manual, agent off shift, or a policy blocks it | Check each severity's Mode, the agent's shifts, and the workspace's investigation policies | | Investigation not starting | Missing permissions | Verify the Org Admin or Agent Admin role, and the Owner role on the workspace | | Escalation webhook not arriving | Card's webhook deleted, paused, disabled, or unsubscribed | Check the classification card for a binding warning; fix the webhook in Developers. Skipped deliveries appear as Failed in the delivery log | | Advanced settings have no effect | Advanced toggle disabled | Enable the Advanced toggle and save; without it the standard Phase 1 to 3 behavior applies | > [!NOTE] > > If you encounter persistent issues with Security Delivery Agent configuration, contact [support@contraforce.com](mailto:support@contraforce.com) with your configuration details and observed behavior. *** ## Related Guides > **[Deploying Agent Center](/guides/onboarding/agent-center-deployment)** > > Deploy Microsoft Foundry infrastructure to manage your AI agents > **[Understanding Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Learn about automated response actions driven by your standard operating procedures (SOPs) > **[SOPs](/guides/agent-center/operating-procedures)** > > Link Classification and Response SOPs to agents so they follow your policies > **[Incident Management](/guides/getting-started/incident-management)** > > Overview of incident handling in ContraForce > **[User Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Understanding ContraForce role requirements > **[Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook)** > > Payload, headers, and signature verification for the custom action event *** > [!NOTE] > > Questions about Security Delivery Agent configuration? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Content Management System: Detection Rules Source: https://docs.contraforce.com/guides/getting-started/content-management-system Manage a workspace's Microsoft Sentinel analytics rules and Defender XDR custom detections: search, add, and bulk enable, disable, or delete rules. The Content Management System (CMS) is a workspace's **Detection Rules** page. It lists the detection rules running in that workspace's Microsoft Sentinel and Microsoft Defender XDR, and lets you add, enable, disable, and delete them without leaving ContraForce. > [!NOTE] > > **Who is this for?** Workspace Owners, Content Admins, and security engineers who manage the detection rules for a single customer workspace. > [!NOTE] > > The CMS and the [Content Management Center](/guides/content-management-center/overview) are different features. The CMS works inside **one workspace**, on the rules running there. The Content Management Center is the top-level, cross-workspace library that versions detection content in repositories and deploys it to the workspaces you choose. *** ## Opening the CMS Open a workspace's CMS in any of these ways: * In **Workspaces**, select the flask icon on the workspace's card. * In **Workspaces → \[workspace] → Modules**, select the flask icon on the **Microsoft Sentinel** or **Microsoft Defender XDR** module. * Press **Ctrl + K** to open [Quick Actions](/guides/getting-started/quick-actions) and choose **Go to \[workspace] analytics**. The page opens as **Workspaces → \[workspace] → Detection Rules**. *** ## Detection Rules Tabs | Tab | What it lists | | - | - | | **Sentinel Analytical Rules** | The analytics rules in the workspace's Microsoft Sentinel | | **Defender Custom Detections** | The custom detection rules in the workspace's Microsoft Defender XDR, including how often each runs (for example, **Continuous (NRT)** or **Daily**) | Each tab shows how many rules it holds, and the **Severity**, **Name**, **Last modified** date, and **Status** of each rule. A **Managed** chip next to a rule's name means a [Content Management Center repository](/guides/content-management-center/repositories) manages that rule in this workspace. Hover the chip to see which repository. Make lasting changes to a managed rule in its repository: an edit made here is recorded as [drift](/guides/content-management-center/workspace-coverage) from the repository's version. A rule deleted from its repository, or a fork of one, loses the chip, because the repository no longer manages it. > [!NOTE] > > Workspaces with the [Sumo Logic Detection Module](/guides/onboarding/sumo-logic-module) connected also have a **Sumo Logic Monitors** tab on this page, listing the Sumo Logic organization's monitors. *** ## Finding Rules * Search by rule name. * Filter by **Severity** (High, Medium, Low, Info, plus Other for analytics rules) and **Status** (Enabled or Disabled). * Select the refresh icon to reload the list. * Select the view icon on a row to see the rule's details. *** ## Adding a Rule Select **Add rule** on the **Sentinel Analytical Rules** tab, or **Add detection** on the **Defender Custom Detections** tab. *** ## Enabling, Disabling, and Deleting Rules in Bulk **1. Select the Rules** Select the checkbox on each rule, or **Select all** to select every rule that matches the current filters. **2. Open Actions** Select **Actions (N)**, where N is the number of rules selected. **3. Choose the Action** Choose **Enable selected**, **Disable selected**, or **Delete selected**. > [!WARNING] > > **Delete selected** removes the rules from the workspace, not just from this list. Check your selection first, especially after using **Select all**. *** ## CMS or Content Management Center? | Use the CMS when | Use the Content Management Center when | | - | - | | You're working on one customer's rules | You want the same rules across many workspaces | | You need a quick change to what's running now | You want versions, rollback, and change-request review | | You want to see what's live in a workspace | You want to detect [drift from a baseline](/guides/content-management-center/workspace-coverage) | The Content Management Center manages the same two rule types as the CMS: Microsoft Sentinel analytics rules and Microsoft Defender XDR custom detections. See [Sentinel and Defender in the Content Management Center](/guides/content-management-center/platforms). *** ## Related Guides > **[Content Management Center](/guides/content-management-center/overview)** > > Version and deploy detection content across workspaces > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Sentinel to a workspace > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings and modules > **[Roles & Permissions Reference](/guides/general-support/roles-and-permissions-reference)** > > Which roles can manage detection rules *** > [!NOTE] > > Questions about the Content Management System? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # How to Classify Incidents: True vs False Positive Source: https://docs.contraforce.com/guides/getting-started/incident-classifications Choose a classification when you close an incident: True Positive, Benign Positive, False Positive, or Undetermined, with examples and a decision tree. Properly classifying incidents is essential for accurate reporting, tuning detection rules, and understanding your security posture. This guide explains when to use each classification type. ## Classification vs Status Before diving into classifications, it's important to understand the difference between **Status** and **Classification**: > **Status** > > **Work state** of the investigation > > * **New** — Not yet reviewed > * **Active** — Under investigation > * **Closed** — Investigation complete > **Classification** > > **Outcome** of the investigation > > * True Positive > * False Positive > * Benign Positive > * Undetermined > [!NOTE] > > **Status** tracks *where you are* in the investigation process. **Classification** documents *what you found* when the investigation is complete. *** ## Classification Types ### True Positive > **True Positive** > > The incident represents an **actual security threat** that required response. **When to use:** * Confirmed malicious activity was detected * A real attack or compromise occurred * Threat actor activity was identified * Malware, phishing, or unauthorized access was verified **Examples:** * User credentials were actually compromised * Malware was confirmed running on an endpoint * Data exfiltration attempt was verified * Unauthorized access to sensitive resources occurred > [!TIP] > > True Positives validate that your detection rules are working correctly. Document the threat details in comments for future reference. *** ### Benign Positive > **Benign Positive** > > The detection was **technically correct**, but the activity was **legitimate** and authorized. **When to use:** * Suspicious-looking activity was actually authorized * A user performed unusual but legitimate actions * IT/Admin activities triggered security alerts * Penetration testing or security assessments caused alerts **Examples:** * Admin legitimately accessed multiple systems during maintenance * User traveled and logged in from an unusual location * Authorized penetration test triggered alerts * New software deployment caused unusual process behavior > [!TIP] > > Benign Positives help identify opportunities for tuning. Consider creating exceptions or adjusting detection thresholds for known legitimate activities. *** ### False Positive > **False Positive** > > The incident was **incorrectly triggered** due to flawed detection logic or bad data. **When to use:** * Detection rule logic is flawed or too broad * Inaccurate or corrupted data triggered the alert * Misconfiguration caused incorrect detection * The alert has no basis in actual activity **Sub-classifications:** | Reason | Description | | - | - | | **Inaccurate data** | The data used to generate the alert was incorrect, incomplete, or corrupted | | **Incorrect alert logic** | The detection rule itself is flawed and needs to be modified or disabled | **Examples:** * Alert triggered on a non-existent user due to log parsing error * Detection rule matches normal business activity too broadly * Time zone misconfiguration caused false temporal correlation * Deprecated system generated alerts for decommissioned resources > [!WARNING] > > False Positives indicate detection problems that should be addressed. Report patterns of False Positives to improve detection quality. *** ### Undetermined > **Undetermined** > > The investigation was **inconclusive**—the cause or outcome couldn't be determined. **When to use:** * Insufficient evidence to reach a conclusion * Logs or data needed for investigation are unavailable * The incident doesn't fit other classification categories * Investigation was abandoned due to resource constraints **Examples:** * Relevant logs expired before investigation completed * Activity was suspicious but couldn't be verified either way * Source system was decommissioned, preventing further analysis * Alert context was insufficient for determination > [!TIP] > > When using Undetermined, always add detailed comments documenting what was discovered during the investigation. This helps if the incident needs to be revisited later. *** ## Quick Reference | Classification | Meaning | Action | | - | - | - | | **True Positive** | Real threat confirmed | Document threat details, validate response actions | | **Benign Positive** | Correct detection, authorized activity | Consider tuning or adding exceptions | | **False Positive** | Incorrect detection | Report for rule improvement | | **Undetermined** | Inconclusive investigation | Document findings in comments | *** ## Classification Decision Tree Use this flow to determine the correct classification: ```mermaid theme={null} flowchart TD A[Incident Investigation Complete] --> B{Was there actual\nmalicious activity?} B -->|Yes| C[True Positive] B -->|No| D{Was the detection\ntechnically correct?} D -->|Yes| E{Was the activity\nauthorized?} D -->|No| F[False Positive] E -->|Yes| G[Benign Positive] E -->|No/Unknown| H{Can you determine\nthe cause?} H -->|No| I[Undetermined] H -->|Yes| B ``` *** ## Best Practices > **Always add comments** > > Document your investigation findings regardless of classification. This creates an audit trail and helps with future investigations of similar incidents. > **Be consistent** > > Work with your team to establish classification guidelines. Consistent classification improves metrics accuracy and detection tuning. > **Review patterns** > > Regularly review classification trends. High False Positive rates indicate detection rules that need tuning. High Benign Positive rates suggest exception lists need updating. > **Don't default to Undetermined** > > Use Undetermined only when you genuinely cannot determine the outcome. Overuse of Undetermined reduces the value of your classification data. *** ## Related Guides > **[Incident Management](/guides/getting-started/incident-management)** > > Complete workflow for managing incidents. > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > Complete workbench to manage your incident resolution. *** > [!NOTE] > > Questions about classifications? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Security Incident Management: Triage to Closure Source: https://docs.contraforce.com/guides/getting-started/incident-management Triage, assign, investigate, and close security incidents across your workspaces, with bulk close and reassign, Gamebook responses, and approval workflows. This guide walks you through the recommended workflow for managing security incidents in ContraForce—from initial triage to resolution. > [!NOTE] > > ContraForce empowers analysts to efficiently manage incidents across multiple workspaces and data sources. This workflow is designed to help you resolve incidents faster and deliver better service to your customers. ## Workflow Overview **1. Filter Incidents** Focus on specific workspaces or assignees, or view all incidents across your environment **2. Assign Incidents** Route incidents to the appropriate analyst **3. Investigate** Review the incident summary, entities, timeline, and evidence **4. Respond with Gamebooks** Execute automated response actions with one click **5. Close the Incident** Document findings and close with proper classification ## 1. Filtering Incidents The **Incidents** page lets you filter the incidents it shows by workspace, source, severity, status, classification, reason, and assignee. The workspace selection persists as you navigate between pages in ContraForce. ### Setting Your Workspace Filter **1. Open the Filter** Click the workspace selector in the top bar **2. Select Workspaces** Choose one or more workspaces to display **3. View Filtered Results** The Incidents table updates to show only data from selected workspaces ![All workspaces dropdown open with a workspace search box, workspace checkboxes, and an Apply button](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/images/Workspace-filter-command-page.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=efd22f5d65f41b4da51afaa1a785e59e) ### Filtering by Assignee **1. Open the Assignee Filter** On the **Incidents** page, open the **Assignee** filter **2. Select Assignees** Choose one or more assignees to display **3. View Filtered Results** The Incidents table updates to show only incidents from selected assignees ![Incidents page with the Assignee filter dropdown open, showing Unassigned at the top of a list of analysts](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/FilterIncidentsbyOwner.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=f81b8c653dca97021ed8c03cea31a8e2) ### Additional Filters Beyond workspace filtering, you can further refine your view: | Filter | Options | Use Case | | - | - | - | | **Severity** | High, Medium, Low, Informational | Focus on critical incidents first | | **Status** | New, Active, On Hold, Waiting on Customer, Closed | View only incidents requiring action | | **Module** | Sentinel, Defender for Endpoint | Filter by security product | > [!TIP] > > When filtering by status, you'll see statuses organized by module (Sentinel, Defender for Endpoint, etc.). This helps you quickly identify incidents by source. In a workspace with both the Microsoft Sentinel and Defender XDR detection modules connected, an incident that Microsoft mirrors between the two appears in your queue once, not twice. See [Incident Deduplication](/guides/technical/parallel-incident-deduplication). *** ## 2. Incident Assignment Proper incident assignment ensures the right analyst handles each incident and provides clear ownership for tracking. ### Individual Assignment To assign a single incident: 1. Locate the incident in the Incidents table 2. Click the dropdown in the **Owner** column 3. Select an analyst from the list of portal users > [!NOTE] > > Ownership is recorded in ContraForce for every incident source, including SentinelOne and CrowdStrike, whose APIs cannot carry a ContraForce analyst as the assignee. For SentinelOne this is ContraForce-only: the threat stays unassigned in the SentinelOne console (see [SentinelOne Detection and Response Modules](/guides/onboarding/sentinelone-module)). For CrowdStrike you can optionally mirror assignments onto the Falcon alert as a bound service account — see [Assignment Writeback](/guides/onboarding/crowdstrike-detection-and-response-modules). ### Handling Incidents at Scale Select multiple incidents in the Incidents table to close or reassign them in one action. A bulk close applies a single classification, reason, and optional comment across the selection; a bulk reassign sets one owner, or unassigns. Both work across a selection that spans workspaces and incident sources. For hands-off triage, **Security Delivery Agents** running **on queue** automatically triage and act on incidents in bulk as they arrive, so you don't have to process them batch by batch. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). *** ## 3. Incident Summary The Incident Summary provides a complete view of an incident with all the context you need for investigation. ### Accessing the Summary Click an incident in the Incidents table to open a quick view with its **Summary**, **Comments**, and **Audit**. Use the arrows to step to the previous or next incident in the queue, and select **View full details** for the full incident page with all of the tabs below. ![Full incident page with an AI-generated agent comment under Investigation and a finished Gamebook under Response](https://mintcdn.com/contraforce/n2V4XUDWFOitCP6z/expanded-incident-workbench.jpeg?fit=max\&auto=format\&n=n2V4XUDWFOitCP6z\&q=85\&s=a9c26847a652444b38f03ca3ba446292) ### Incident Tabs **Summary** **Summary** – Overview of the incident including severity, status, affected assets, and key details at a glance. **Rule** **Rule** – Shows the detection rule that triggered the incident, including rule logic, conditions, and configuration. **Entities** **Entities** – Lists all related entities (users, devices, IPs, domains, files) involved in or affected by the incident. **Logs** **Logs** – Raw log data and events associated with the incident for deeper investigation. To run your own KQL queries against a workspace's Microsoft Sentinel logs, use [Log Search](/guides/getting-started/log-search). **Comments** **Comments** – Collaboration space for analysts and AI agents. Each agent run adds an **AI Generated** comment with the classification, a malicious confidence score (0–100), the standard operating procedures (SOPs) it matched (under **Knowledge**), its reasoning, and recommendations. **Audit** **Audit** – Track record of all changes made to the incident (status updates, assignments, modifications) with timestamps and user attribution. ## 4. Gamebook Responses Gamebooks are AI-generated and human-created response actions, driven by your SOPs, that let you quickly respond to incidents. > [!NOTE] > > Available Gamebook actions are determined by the entity types present in the incident. Agents automatically suggests relevant actions based on the output of the investigation and incident classification. ### Using Suggested Gamebooks If a Gamebook has been previously executed for similar incidents, agents suggest it automatically: ![Gamebook response panel with completed actions](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/gamebook-suggestion.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=47645a4ea5eda0fa2d0af846c234e90a) ### Creating a Custom Gamebook **1. Open the Workbench** On the full incident page, select the Gamebooks Workbench icon next to **Actions**, or use the **Gamebook** builder in the incident's **Response** section **2. Explore Available Actions** Click entity icons in the Entity Graph to see available response actions **3. Build Your Response** * Use the arrows to navigate through action options * Click the green **+** icon to add an action * Click the red **-** icon to remove an action **4. Execute** Click **Approve Gamebook** to execute all selected actions ### Gamebook Approval Workflow Some Gamebook actions require approval before execution: > [!WARNING] > > Actions with a **red lock icon** require approval from a user with appropriate permissions in the workspace. **To request approval:** 1. Build your Gamebook as usual 2. Click **Request Gamebook Approval** (instead of Run Gamebook) 3. The request is sent to authorized approvers **To approve a Gamebook:** * Approvers can approve directly from the incident, or * Use the **Gamebook Activity** tab to review and approve pending requests *** ## 5. Incident Closure After completing your investigation and response, close the incident with proper documentation. ![Close Incident modal](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/images/close-incident-modal-2.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=886f7b1b14a8998c19e1b5b222dcab8c) ### Quick Close from Gamebook After a Gamebook completes, a green **Close Incident** button appears at the bottom of the Gamebook context group. ### Closure Fields | Field | Options | Purpose | | - | - | - | | **Classification** | True Positive, False Positive, Benign Positive, Undetermined | Required. Categorizes the incident outcome | | **Comment** | Free text | Optional note about why you're closing the incident | > [!TIP] > > Need help understanding classifications? See [Incident Classifications](/guides/getting-started/incident-classifications) for detailed guidance. *** ## Putting It Together The ContraForce incident management workflow is designed to help you: > **Triage Faster** > > Filter and prioritize incidents across all your workspaces from one dashboard > **Respond Automatically** > > Execute proven response actions with Gamebooks instead of manual remediation > **Document Everything** > > Maintain complete audit trails with comments, classifications, and history *** ## Related Guides > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Track closures, classification trends, and Gamebook activity across your workspaces. > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Deep dive into automated response actions driven by your SOPs. > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > Learn how to manage incidents in your workbench. > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > Understand True Positive, False Positive, and more. > **[SLA Tracking](/guides/getting-started/sla-tracking)** > > Set response and resolution targets and track Time to First Response and Time to Resolution. *** > [!NOTE] > > Questions about this workflow? Contact us at [support@contraforce.com](mailto:support@contraforce.com). We're happy to help optimize your incident management process. # Incident Report: Closed Incidents and PDF Export Source: https://docs.contraforce.com/guides/getting-started/incident-report Open the closed incidents behind a Command Dashboard total, filter by classification, severity, source, or reason, and save a PDF copy for a customer. The Incident Report turns the totals on the Command Dashboard into the records behind them. Click a number on the dashboard and the report opens already filtered to that number's time range, workspaces, and slice of the data, so you can see which incidents were counted, how they were classified, and who reported them. ![Incident Report page](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/incident-report/incident-report-overview.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=3b1066e2075377186660d7c600807741) ## Opening the report from the Command Dashboard Every entry point carries your current dashboard **time filter** and **workspace selection** into the report. You never have to re-apply them. ### From the Closed Incident Tracker ![Closed Incident Tracker with linked donut and severity rows](https://mintcdn.com/contraforce/7eCKFG28WsYKEaUd/images/incident-report/closed-incident-tracker.png?fit=max\&auto=format\&n=7eCKFG28WsYKEaUd\&q=85\&s=f1354a2a9f495d1f10ad17367308ef93) | Click | Opens | | - | - | | The **donut** (total closed incidents) | Every closed incident in the selected period and workspaces | | A severity row: **High**, **Medium**, **Low**, or **Info** | The same report, pre-filtered to that severity | Each severity row shows the count, its share of the total, and an arrow indicating that the row is a link. Rows are not clickable while the dashboard is still loading. The record count above the summary confirms what carried over, for example `336 available records · 336 in dashboard totals`. ### From Classification Trends ![Classification Trends cards and tabs](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/incident-report/classification-trends.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=eadeafd2f2d6c09528c47b92e4558b08) * Click the **arrow** on a classification card (True Positive, False Positive, Benign Positive, Undetermined) to open the report filtered to that classification. * Inside the **By reason** and **By module** tabs, click a row to add that reason or source to the filter as well. > [!TIP] > > Selecting a classification card filters the tabs in place without leaving the dashboard. Use the arrow button when you want the full report instead. ## Reading the report ### Header controls | Control | What it does | | - | - | | **Time filter** | Changes the reporting period. Supports presets from 3 hours to 180 days, or a custom range | | **Refresh** | Re-runs the query with the current filters | | **Print / Save as PDF** | Produces a print-ready copy of the report | ### Report filters Below the header, four filters narrow the report further. Changing any of them reloads the report and updates the page address, so the filtered view can be bookmarked or shared. > **Classifications** > > Pick any combination of True Positive, Benign Positive, False Positive, and Undetermined, or choose **All classifications**. > **Severity** > > High, Medium, Low, Informational, or **Not retained** for records where severity was not kept. > **Source** > > Microsoft Sentinel, Microsoft Defender XDR, CrowdStrike, or SentinelOne. > **Reason** > > The closure reason recorded by the analyst or agent, plus **No reason recorded**. A summary line under the filters restates the exact period, the number of workspaces in scope, the source, and the reason currently applied. ### Report summary ![Report summary cards and closure chart](https://mintcdn.com/contraforce/7eCKFG28WsYKEaUd/images/incident-report/report-summary.png?fit=max\&auto=format\&n=7eCKFG28WsYKEaUd\&q=85\&s=d00c945701841cefabb73e9ab12f3a75) | Card | What it counts | | - | - | | **Unique incidents** | Distinct incidents, identified by workspace, source, and incident ID | | **Closure records** | Individual closure events. One incident closed twice counts twice | | **By classification** | Closure records grouped by the classification recorded at closure | | **By severity** | Closure records grouped by severity | | **By source** | Closure records grouped by the detection module that raised the incident | Below the cards, **Recorded closures by day** plots the same records as a stacked bar chart, one bar per UTC day, so you can see when activity clustered inside the period. ### Workspace breakdown A table repeats the same summary per workspace, so a provider managing many workspaces can see which ones drove the totals without changing the workspace filter. ### Incident list ![Incident list with closure details](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/incident-report/incident-list.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=048814c509eb780a68b116dade95775e) | Column | Description | | - | - | | **ID** | The incident ID. Click it to open the incident workbench | | **Closed at** | Local closure time. Marked `(approx.)` when only the closure hour was retained | | **Title at closure** | The incident title as it read when the incident was closed | | **Workspace** | The workspace the incident belongs to | | **Source** | The detection module that raised it | | **Severity** | Severity at closure, or **Not retained** | | **Classification at closure** | The outcome recorded by the analyst or agent | | **Reason** | The closure reason, or **No reason recorded** | | **Rules** | **View rules** opens the detection rules behind Sentinel and Defender XDR incidents | The list is paginated. Column layout persists between visits. > [!NOTE] > > Rule navigation is available for Microsoft Sentinel and Microsoft Defender XDR incidents. CrowdStrike and SentinelOne incidents show a message instead. ## Print or save as PDF Select **Print / Save as PDF** in the report header to generate a clean, branded copy for a customer or a compliance file. ![Print options dialog](https://mintcdn.com/contraforce/7eCKFG28WsYKEaUd/images/incident-report/print-options.png?fit=max\&auto=format\&n=7eCKFG28WsYKEaUd\&q=85\&s=b8de7f73399f677d54b2d9ca70b26559) The printed report always contains your filters, the summary statistics, the closure chart, and the workspace breakdown. Select **Include the incident list** to append every matching closure record. > [!WARNING] > > The incident list includes every record that matches your filters, not just the current page, and can add many pages to the output. Leave it unchecked for a summary report. Your provider name appears in the footer of every page, alongside the generation timestamp in the header. ## How the numbers are counted > **Classification is recorded at closure** > > The report shows the classification, severity, and title as they were when the incident was closed. Later edits in the source product are not reflected. > **Incidents can appear on more than one day** > > Each incident is counted once per UTC day. An incident closed, reopened, and closed again appears on each of those days in the chart, which is why closure records can exceed unique incidents. > **Some closure details are not retained** > > Where the closure hour was kept but the exact minute was not, the time is marked `(approx.)`. Where severity was not kept, the record shows **Not retained**. Choose **Not retained** in the Severity filter to see those records, as specific severity filters exclude them. > **Coverage notices** > > If the dashboard total is higher than the number of retained records, the report shows a notice explaining that only the available records are listed. The record count above the summary states both numbers. ## Related guides > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > The dashboard the report is launched from. > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > What each classification means and when to use it. > **[Incident Management](/guides/getting-started/incident-management)** > > The workflow for triaging, investigating, and closing incidents. > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > What opens when you click an incident ID in the report. *** > [!NOTE] > > Need help? Contact the ContraForce Support team at [support@contraforce.com](mailto:support@contraforce.com). # Log Search: Run KQL Queries on Workspace Logs Source: https://docs.contraforce.com/guides/getting-started/log-search Query a workspace's logs with KQL in ContraForce, browse the schema, export results, and let Ask IRIS turn a plain-language question into KQL. Log Search lets you query a workspace's logs with KQL (Kusto Query Language) without leaving ContraForce, so you can hunt or dig into an incident from the same place you triage it. > [!NOTE] > > **Who is this for?** SOC analysts and security engineers who hunt or investigate across customer workspaces. Log Search is included with the **XDR + SIEM Module**. *** ## Running a Query **1. Open Log Search** Select **Log Search** in the left navigation. **2. Choose the Workspace** Pick the workspace and data source from the **Workspace** list, for example **\[workspace] — Microsoft Sentinel**. **3. Write the Query** Type KQL in the editor. Use the **Schema** panel to browse the tables available in the workspace. **4. Run It** Select **Run** or press **Ctrl + Enter**. Results appear in the **Results** panel. *** ## Ask IRIS Not fluent in KQL? Select **Ask IRIS** and describe what you're looking for in plain language. IRIS turns your description into KQL, which you can review before you run it. *** ## Exporting Results After a query returns results, select **Export** to download them. *** ## Opening Log Search from an Incident On a full incident page, select the Log Search icon (**Go to log search**) next to **Actions** to jump to Log Search while you investigate. *** ## Related Guides > **[Incident Management](/guides/getting-started/incident-management)** > > Investigate incidents end to end > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > Connect Sentinel to a workspace *** > [!NOTE] > > Questions about Log Search? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Multi-Tenant Security for MSPs and MSSPs Source: https://docs.contraforce.com/guides/getting-started/multi-tenant-features See incidents, Gamebook activity, and approvals for every customer workspace in one place. Multi-tenant security management built for MSPs and MSSPs. ContraForce is purpose-built for MSPs and MSSPs managing multiple customer environments. View incidents, run response actions, and monitor security posture across all your workspaces—without switching between portals. > [!NOTE] > > Whether you manage 5 workspaces or 500, ContraForce scales with your business. All multi-tenant features are included in the platform at no additional cost. ## Why Multi-Tenant Matters Traditional security tools force analysts to log into each customer environment separately. ContraForce eliminates this friction: > **Single Pane of Glass** > > View all customer incidents in one unified dashboard. > **Consistent Workflows** > > Standard operating procedure (SOP) workflows automated across every workspace. > **Efficient Staffing** > > One analyst can manage more customers effectively. *** ## Command Dashboard: Your Central Hub The **Command Dashboard** is the heart of ContraForce's multi-tenant capabilities. It provides a unified view of all security incidents across your managed workspaces. ![Command Dashboard showing the Closed Incident Tracker, Classification Trends, Closures by Workspace, and Team Member tables](https://mintcdn.com/contraforce/Tne2Yr5NXQ4PXg82/images/Command-q95.png?fit=max\&auto=format\&n=Tne2Yr5NXQ4PXg82\&q=85\&s=e17b146c663297605daf726e47615619) ### What You Can See | Function | Multi-Tenant Capability | | - | - | | **Multi-Tenant Dropdown** | Filter down on one or many workspaces in seconds | | **Closed Incident Trends** | Closed incidents trends across workspaces | | **Incident Rule Trends** | Detections triggered by rules across workspaces | | **Latest Gamebook Activity** | Recent response actions across workspaces | ### Default Behavior By default, the Command Dashboard displays data for all onboarded workspaces. This gives you immediate visibility into your entire customer base without any configuration. > [!TIP] > > Start your day on the Command Dashboard to quickly identify which customers need attention. Trends and recent activity allow you to focus where it matters. *** ## Workspace Filtering While seeing everything is powerful, sometimes you need to focus. The **Workspace Filter** lets you customize your view. ### How It Works **1. Open the Filter** Click the workspace dropdown in the top navigation bar **2. Select Workspaces** Check the workspaces you want to display (one, several, or all) **3. View Filtered Data** All dashboard cards and tables update to show only selected workspaces ![Workspace filter selection](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/images/Workspace-filter-command-page.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=efd22f5d65f41b4da51afaa1a785e59e) ### Filter Persistence Your workspace selection **persists as you navigate** between pages in ContraForce: * Command Dashboard → Incidents Page → Gamebooks Page * Your selected workspaces remain active throughout your session * No need to re-select filters on each page > [!NOTE] > > This persistence is especially useful when you're focused on a specific customer's issues and need to investigate across multiple ContraForce features. ### Additional Filters Beyond workspace filtering, you can further refine the Incidents table by: | Filter | Options | Use Case | | - | - | - | | **Severity** | High, Medium, Low, Informational | Prioritize critical incidents | | **Status** | New, Active, On Hold, Waiting on Customer, Closed | Focus on open investigations | | **Module** | Sentinel, Defender for Endpoint | Filter by security product | *** ## Multi-Tenant Incident Management Managing incidents across workspaces follows the same workflow—but with added context about which customer is affected. ### Incident Table Columns The Incidents table includes workspace identification: | Column | Description | | - | - | | **Severity** | Incident severity level | | **Workspace** | Which customer/workspace the incident belongs to | | **Incident Title** | Description of the incident | | **Incident ID** | Unique identifier (click to investigate) | | **Creation Time** | When the incident was detected | | **Status** | Current investigation state | | **Owner** | Assigned analyst | ### Incident Handling Across Workspaces You don't process cross-tenant incidents with a manual bulk action. **Security Delivery Agents** running **on queue** triage and act on incidents across all your workspaces automatically as they arrive. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). *** ## Multi-Tenant Gamebook Activity Track automated response actions across your entire customer base. ### Gamebook Activity Card The Command Dashboard shows **Latest Gamebook Activity** with: * **Workspace** — Which customer the action was performed on * **Status** — Success, Failed, Pending Approval * **Incident** — Linked incident ID * **Owner** — Who initiated the action ### Approval Workflows When Gamebook actions require approval, you can manage all pending requests from one location: 1. Navigate to the **Gamebook Activity** tab 2. View pending approvals across all workspaces 3. Approve or reject with full context ## Workspace Management The **Workspace Center** provides administrative control over your workspaces. ### Pre-Onboarding Prepare customer environments before full deployment: * Create workspace placeholders * Configure initial settings * Streamline the onboarding process ### Post-Onboarding Management After onboarding, manage workspace configurations: * View onboarding status * Access workspace settings * Monitor integration health > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Complete guide to the Workspace Center. *** ## Best Practices for Multi-Tenant Operations > **Establish naming conventions** > > Use consistent workspace names that clearly identify customers. This makes filtering and incident triage faster. > **Create tiered response procedures** > > Define which incident types require immediate attention vs. scheduled review. Use severity filtering to prioritize. > **Assign dedicated analysts per customer segment** > > For large deployments, consider assigning analysts to specific workspace groups to build customer familiarity. > **Review the Command Dashboard daily** > > Start each day with a Command Dashboard review across all workspaces to catch emerging issues early. > **Monitor connector health proactively** > > Don't wait for incidents to reveal data flow problems. Check Data Connector Anomalies regularly. *** ## Related Guides > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Deep dive into the central dashboard. > **[Incident Management](/guides/getting-started/incident-management)** > > Complete incident workflow guide. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace configurations. > **[User & Group Management](/guides/onboarding/user-group-management-for-providers)** > > Manage Users and Groups. > **[Workspace Profiles](/guides/fleet-management/workspace-profiles)** > > Apply the same workspace settings to many workspaces at once. > **[Quick Actions](/guides/getting-started/quick-actions)** > > Press Ctrl + K to jump between pages and workspace settings. *** > [!NOTE] > > Questions about multi-tenant features? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Platform Permissions: Microsoft Entra ID Consent Source: https://docs.contraforce.com/guides/getting-started/platform-permissions-and-consent See which Microsoft Entra ID apps ContraForce uses, what each one does, and which admin roles can grant core consent at sign-in and module consent later. Before ContraForce can operate in your Microsoft Entra tenant, a sufficiently privileged user must grant permission for ContraForce applications to access tenant data. This article explains which permissions ContraForce requires, when they're requested, and why. ## How ContraForce Connects to Your Environment ContraForce uses a modular set of Microsoft Entra ID applications to securely connect with your environment. Each application is purpose-built for a specific function and requests only the permissions it needs. This design follows the **principle of least privilege**—you only grant permissions for the capabilities you actually use. For example, if you don't use Gamebooks to respond to endpoint threats, you never need to consent to the ContraForce Gamebooks for MDE application. ## ContraForce Applications | Application | Purpose | | - | - | | ContraForce API | Core platform connectivity and coordination | | ContraForce Portal | Secure sign-in with your Microsoft account | | ContraForce Sentinel Hunting | Query logs and investigate incidents in Sentinel | | ContraForce for MDE | View and manage Defender for Endpoint devices | | ContraForce Gamebooks for Identity | Automated response actions for user accounts | | ContraForce Gamebooks for MDE | Automated response actions for endpoints | | Microsoft 365 Response | Automated response actions for email threats | During onboarding, you'll consent to **ContraForce API** and **ContraForce Portal**. The remaining applications can be consented to later from **Settings → Permissions** based on the capabilities you need. ## Application Details ### ContraForce API The core connection that allows ContraForce to communicate with your Microsoft environment. This application coordinates all platform operations—from onboarding your workspace to managing Azure resources—and securely connects the other ContraForce services. ### ContraForce Portal Enables secure sign-in to ContraForce using your Microsoft work account. This application verifies your identity and displays your basic profile information (name and email) within the platform. ### ContraForce Sentinel Hunting Allows ContraForce to query your Microsoft Sentinel workspace for deeper investigation. This powers the Advanced Hunting feature and retrieves raw log evidence to give analysts full context behind security incidents. ### ContraForce for Defender for Endpoint (MDE) Connects ContraForce to Microsoft Defender for Endpoint so you can view and manage protected devices. This provides visibility into device health, alerts, and security posture across your environment. ### ContraForce Gamebooks for Identity Powers automated response actions for user-related threats. When a Gamebook runs, this application can lock out compromised accounts, reset passwords, and revoke active sessions—containing identity-based attacks in seconds instead of hours. ### ContraForce Gamebooks for MDE Powers automated response actions for endpoint threats through Defender for Endpoint. When a Gamebook runs, this application can isolate compromised devices from your network, quarantine malicious files, and trigger antivirus scans—stopping threats before they spread. ### Microsoft 365 Response Powers automated response actions for email-based threats. When a Gamebook runs, this application can delete malicious emails from user mailboxes, block dangerous senders, and purge phishing messages across your organization—neutralizing email attacks before users can click. ## Onboarding and Consent Flow 1. Sign in at [portal.contraforce.com](https://portal.contraforce.com) with a Microsoft work account 2. Consent to **ContraForce API** permissions 3. Consent to **ContraForce Portal** permissions These two core consents are presented as **two separate** Microsoft consent prompts. Additional application permissions can be granted later as needed from **Settings → Permissions**. > [!WARNING] > > **Two different roles apply, depending on which consent you're granting.** > > The two **core** consents above (ContraForce API and ContraForce Portal) can be granted by a **Global Administrator**, **Privileged Role Administrator**, **Application Administrator**, or **Cloud Application Administrator**. > > **Module** consents (Microsoft Defender XDR, the Microsoft response modules, and the Sentinel Hunting add-on) request Microsoft Graph **application** permissions, which Entra grants only to a **Global Administrator** or a **Privileged Role Administrator**. Application Administrator and Cloud Application Administrator will reach a screen that ends in "approval required". The first time anyone from your tenant signs in at [portal.contraforce.com](https://portal.contraforce.com), a Global Administrator consents the core ContraForce applications. You first sign in with a Microsoft work account and consent to the **ContraForce API**, then you're prompted to consent the permissions requested for the **ContraForce Portal** application. After these consents, you land on the **Command** page, where a **Get started** checklist guides you through any remaining setup. ## Learn More For detailed information about Microsoft's consent framework, see Microsoft's [Application model overview](https://learn.microsoft.com/en-us/entra/identity-platform/application-model) and [consent experience documentation](https://learn.microsoft.com/en-us/entra/identity-platform/application-consent-experience). To independently verify which permissions your tenant has granted to ContraForce enterprise applications, run the read-only scripts in [Auditing Enterprise App Permissions](/guides/technical/auditing-enterprise-app-permissions). > **[Workspace Permissions and Consent](/guides/onboarding/workspace-onboarding)** > > Understanding the Microsoft Entra ID permissions and enterprise applications required for ContraForce workspace deployments. ## Getting Help > **[Contact Support](mailto:support@contraforce.com)** > > Email the ContraForce support team for assistance > **[Request Onboarding Support](/submit-ticket)** > > Submit a support ticket to request hands-on help with your first deployment # Quick Actions: Command Palette (Ctrl + K) Source: https://docs.contraforce.com/guides/getting-started/quick-actions Use the Ctrl + K keyboard shortcut to open Quick Actions, a command palette that takes you to portal pages, workspace settings, and common tasks. Quick Actions is a command palette for the ContraForce portal. Open it from anywhere to jump to a page or a workspace's settings without clicking through the navigation. > [!NOTE] > > **Who is this for?** Everyone who uses the portal, especially analysts and admins who move between many workspaces. *** ## Opening Quick Actions Press **Ctrl + K**, or select **Quick Actions** in the top bar. Press **Ctrl + K** again or **Esc** to close it. Start typing to filter the list, use the **↑** and **↓** arrow keys to move through it, and press **Enter** to select. *** ## What You Can Do | Action | Takes you to | | - | - | | **Go to Command Dashboard**, **Incidents**, **Log Search**, **Gamebooks**, **Workspaces**, **Agent Center**, **SOPs**, or **Settings** | That page | | **Manage Users** or **Manage Groups** | **Settings → User Management** or **Group Management** | | **Manage Ticketing Systems** | **Workspaces → Ticketing** | | **Manage Integrations** or **Create new webhook integration** | **Settings → Developers** | | **Search Incidents** | The Incidents page | | **Go to \[workspace] settings**, **modules**, **IAM**, or **notification settings** | That workspace's **General**, **Modules**, **IAM**, or **Notifications** tab | | **Go to \[workspace] analytics** | That workspace's [Content Management System](/guides/getting-started/content-management-system) | > [!TIP] > > Type part of a customer's workspace name to jump straight to its settings, modules, or notifications. *** ## Related Guides > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Your starting point in the portal > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings *** > [!NOTE] > > Questions about Quick Actions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Incident SLA Tracking: Response and Resolution Source: https://docs.contraforce.com/guides/getting-started/sla-tracking Set incident SLA targets per workspace and severity, then track Time to First Response and Time to Resolution as live countdowns with an at-risk threshold. SLA tracking measures how quickly your team responds to and resolves incidents against targets you set. Define the targets in an **SLA configuration**, assign it to workspaces, and the Incidents page tracks **Time to First Response** and **Time to Resolution** for every incident in those workspaces. > [!NOTE] > > **Who is this for?** Service providers and SOC managers who commit to response and resolution times with their customers. *** ## Where SLAs Live Select **Workspaces** in the left navigation, then the **SLA** tab in the Workspace Center. **SLA Configurations** lists each configuration with its time to first response, its time to resolution, and how many workspaces it applies to. Select the settings icon on a row to edit it. *** ## Creating an SLA Configuration **1. Add a Configuration** On the **SLA** tab, select **Add SLA configuration**. **2. Name It** Enter a **Name** and an optional **Description**. **3. Set the Targets** Enter the targets described below. Turn on **Advanced options** to set different targets for each severity (High, Medium, Low, Info). With it off, the same targets apply to every severity. **4. Assign Workspaces** Under **Workspaces**, search for and add the workspaces this configuration covers. **5. Save** Select **Save changes**. > [!WARNING] > > A configuration with no workspaces assigned has no effect. SLA tracking stays off for incidents in its scope until you assign at least one workspace. *** ## Targets | Setting | What it means | | - | - | | **Time to first response (minutes)** | How long the team has to respond, counted from when the incident is detected | | **Time to resolution (minutes)** | How long the team has to resolve the incident, counted from when it is detected | | **At-risk threshold (%)** | The share of a target's time after which the incident is flagged as at risk. At 80, an incident is at risk once 80% of its time has elapsed | | **Response definition** | What counts as the first response | | **Resolution definition** | What counts as resolution | ### Response Definition | Option | Counts as the first response | | - | - | | **First assignment** | The first time the incident is assigned an owner | | **First status change away from New** | The first time the status moves off **New** | | **Either, whichever first (recommended)** | Whichever of the two happens first | | **Any CF principal action** | Any action on the incident by a ContraForce principal, such as an analyst or agent | ### Resolution Definition | Option | Counts as resolution | | - | - | | **CF analyst sets to Closed (recommended)** | An analyst closes the incident in ContraForce | | **Vendor reaches terminal Closed** | The incident is closed in its source tool, such as Microsoft Sentinel | | **Whichever comes first** | Whichever of the two happens first | > [!TIP] > > If your analysts sometimes close incidents directly in Microsoft Sentinel or Defender XDR, choose **Whichever comes first** so those closures still stop the resolution clock. *** ## Tracking SLAs on Incidents For incidents in workspaces with an SLA configuration, the **Incidents** page shows **Time to First Response** and **Time to Resolution** columns with a live countdown on each row. If the columns are hidden, turn them on with the column picker above the table. ### How the Clocks Run Both clocks start when the incident is detected. **Time to first response** stops at the first response, and **Time to resolution** stops when the incident is resolved. Setting an incident to **On Hold** or **Waiting on Customer** pauses whichever clocks are still running, and setting it back to another status resumes them. Paused time doesn't count toward either target, and each clock excludes only the paused time that fell while it was running. ### SLA Tab Open an incident and select the **SLA** tab to see the targets it's measured against and a timeline of what moved its clocks: detection, the first response, each pause and resume with the status that caused it, any at-risk or breached crossings, and the resolution. *** ## Related Guides > **[Incident Management](/guides/getting-started/incident-management)** > > Triage, investigate, and close incidents > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings > **[Incident Report](/guides/getting-started/incident-report)** > > Review and print closures > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Work across all your customers *** > [!NOTE] > > Questions about SLA tracking? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # What Are Gamebooks? No-Code Incident Response Source: https://docs.contraforce.com/guides/getting-started/what-are-gamebooks Gamebooks are no-code, SOP-driven incident response workflows. Run one to isolate endpoints, reset MFA, block IPs, or delete email. Gamebooks are incident response workflows driven by your standard operating procedures (SOPs) and powered by ContraForce's response engine, IRIS. Instead of manually logging into multiple consoles to contain a threat, you can execute proven response actions with a single-click across any workspace. > [!NOTE] > > Think of Gamebooks as your incident response playbook—automated. No API mapping, no coding, no scripting. Select the response actions you need, click run, and ContraForce handles the execution across your integrated security tools. AI agents can autonomously choose the correct response actions based on entity types and the classification of the incident. ## Why Gamebooks? Traditional incident response requires analysts to: 1. Identify affected entities (users, devices) 2. Log into each security tool separately 3. Manually execute containment actions 4. Document what was done **Gamebooks compress this into seconds:** > **One Click** > > Execute multiple actions across tools instantly > **Consistent** > > The right response every time > **Auditable** > > Complete history of every action taken ### Compiled Automatically by Your AI Agents You don't have to assemble the response yourself. When a [Security Delivery Agent](/guides/getting-started/configuring-security-delivery-agents) investigates an incident, it builds an **investigation graph** — the same Entity Context Graph you see in the Workbench — to determine exactly which entities the incident impacted. The agent then compiles the Gamebook for you, mapping the appropriate response actions to each impacted entity based on entity type and the incident's classification. You can still add or remove actions before it runs. > [!TIP] > > What happens to a compiled Gamebook depends on the agent's mode. In manual runs it waits for you to review and run it; with **Allow Agent to run gamebooks** enabled, the agent executes it once its confidence threshold is met. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). *** ## Available Gamebook Actions Gamebook actions are organized by entity type. ContraForce automatically shows relevant actions based on the entities involved in each incident. ### User Actions | Action | Description | Use Case | | - | - | - | | **Invalidate Existing Sessions** | Terminates all active sessions | Compromised account, suspicious activity | | **Lockout User** | Prevents user from signing in | Confirmed account compromise | | **Reset User Password** | Forces password reset on next login | Credential theft suspected | | **Reset MFA** | Removes all registered MFA methods, forcing re-registration at next sign in | Attacker-registered MFA, lost or compromised authenticator | | **Unlock User** | Re-enables a locked account | After remediation is complete | > [!TIP] > > **Reset MFA vs. Reset User Password.** These are complementary, not interchangeable. *Reset User Password* invalidates the credential the user types; *Reset MFA* deletes the second factors they present (Microsoft Authenticator, phone/SMS, FIDO2 security keys, software OATH tokens, Windows Hello for Business, Temporary Access Pass, and email/platform methods). It does **not** change the password. When you suspect an attacker has enrolled their *own* authenticator on a compromised account, a password reset alone leaves that rogue factor in place: run **Reset MFA** to strip it, and pair it with **Reset User Password** for full credential containment. After the reset the user re-registers MFA on their next sign in, so confirm an enrollment path (and any Conditional Access / registration-campaign policies) is in place before running it. ### Endpoint Actions | Action | Description | Use Case | | - | - | - | | **Isolate Endpoint** | Disconnects device from network (except Defender) | Active malware, lateral movement | | **Scan Endpoint** | Triggers antivirus/EDR scan | Suspicious file activity | | **Release from Isolation** | Restores network connectivity | After threat is contained | | **Quarantine File** | Moves malicious file to quarantine | Known malware detected | ### Network Actions | Action | Description | Use Case | | - | - | - | | **Block Cloud IP** | Adds IP to Azure Network Security Group (NSG) blocklist | C2 communication, malicious source | ### Email Actions | Action | Description | Use Case | | - | - | - | | **Delete Email** | Removes malicious email from mailbox | Phishing, malware delivery | > [!TIP] > > Available actions depend on your connected modules. For example, endpoint actions require Microsoft Defender for Endpoint module to be configured. *** ## How to Access Gamebooks **1. Open an Incident** From the **Incidents** page, open an incident and select **View full details** **2. Open the Gamebook Workbench** Select the Gamebooks Workbench icon next to **Actions**. You can also build a response plan in the incident's **Response → Gamebook** builder. **3. Start Building** The Gamebook Workbench opens with the Entity Context Graph ![Incident Gamebook view with an Investigation graph of eight entities on the left and the Response panel on the right](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/gamebook-workbench-blank.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=6b15dbd022589bdfb685bf2e700b16f8) ## Building a Gamebook Creating a Gamebook is intuitive—select entities, choose response actions, and execute. ### Step 1: Select an Entity **Left-click** an entity in the Entity Context Graph (user, device, IP, etc.). The response action menu appears showing available response actions. ![Investigation graph with a device entity's action menu open: Isolate Endpoint, Scan Endpoint, Release From Isolation](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/gamebook-page-response-menu.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=8c27ce4ca8482911e432247b16940036) ### Step 2: Add Actions * With the **left-click** menu open, select available response actions * Click a response action to load it into the Gamebook * Click the **red - icon** to remove an action ### Step 3: Repeat for Other Entities Select additional entities and add their actions. You can build comprehensive response workflows targeting multiple entity types. ### Step 4: Review & Execute Your selected actions appear in the **Gamebook Card**: ![Response panel Gamebook tab showing Scan Endpoint and Isolate Endpoint both Finished, with a 100% Run Complete bar](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/gamebook-workbench-page.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=87f2d389d66d494e5536409b2f66a16b) | Column | Description | | - | - | | **Action** | The response action to be performed | | **Entity** | Target of the action | | **Status** | "Pending" before execution | Click **Run Gamebook** to execute all actions. ## Gamebook Execution Status After clicking Run Gamebook, monitor the execution: | Status | Meaning | | - | - | | **Pending** | Action queued, not yet started | | **Running** | Action currently executing | | **Finished** | Action completed successfully | | **Failed** | Action encountered an error | > [!WARNING] > > If an action fails, check the Gamebook Activity page for error details. Common causes include permission issues or connectivity problems with the target system. ## Gamebook Approval Workflow Manage the team members responsible for approving Gamebooks that require manual authorization. Only users with the **Workspace Owner** role can be assigned as Gamebook approvers. ### Gamebook Approval Configuration Open **Workspaces → \[workspace] → Gamebooks** and configure the **Gamebook configuration** based on your SOPs for that workspace: * **Allow service providers to run gamebooks** — lets the service providers that manage the workspace run Gamebooks on its behalf * **Approvers** — the Workspace Owners who approve Gamebooks that require manual authorization * **Run policies** — ordered rules, checked top to bottom, that block an action, allow it, or send it to an approver first; if none match, the action is allowed. See [Workspace Policies](/guides/getting-started/workspace-policies) to build and order them ![Gamebook configuration panel: Allow service providers to run gamebooks toggle on, Approvers list, and Add Approver button](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/service-provider-gamebook-approval-config.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=410e5557dfd5a25f34145295171894cd) > [!WARNING] > > Some response actions (Reset user password) require the end user of the workspace to have the **Global Administrator** or **Privileged Role Administrator** role — enabling the add-on assigns an Entra directory role, which only those two roles can do. As a Service Provider, you can approve this action on your end without the end user consent. ### Approving Gamebooks Users with approval permissions can approve from: > **Incident Summary** > > Open the incident and approve directly from the Gamebook status > **Gamebooks Page** > > Review all pending approvals in one centralized queue Once approved, the Gamebook executes automatically. ## Gamebook History Track all Gamebook activity across your environment from the dedicated **Gamebooks Page**. ### Accessing Gamebook History Click the **Gamebooks icon** (triangle) in the navigation bar—it's the 2nd icon from the top. ![Gamebooks Activity page listing Gamebook runs by status, workspace, incident, and triggered by, with status filters](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/gamebooks-page-overview.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=ed6c8bc93e09250ef7e01096fb9750f3) ### What You Can See The Gamebooks page shows: | Filter | Description | | - | - | | **Completed** | Successfully executed Gamebooks | | **Waiting Approval** | Pending approval requests | | **Failed** | Gamebooks with errors | ### Viewing Details Click the **dropdown arrow** on any row to expand and see: * Individual action results * Execution timestamps * Error messages (if failed) * Entity details ![Gamebook history expanded view](https://mintcdn.com/contraforce/NNBi_vTAW-iJTdQh/gamebook-activity-dropdown-menu.png?fit=max\&auto=format\&n=NNBi_vTAW-iJTdQh\&q=85\&s=e228b4abea8ee4b56f226f4d313d8216) > [!TIP] > > Use the workspace filter to view Gamebook history for specific workspaces. This is useful when reviewing activity for a particular customer. ## Unsupported Entities Not all entity types support Gamebook actions due to technical limitations with module integrations. **Common reasons:** * Integration doesn't expose response APIs * Entity type not yet supported * Permissions not configured for response actions > [!NOTE] > > If you need specific response capabilities, contact [support@contraforce.com](mailto:support@contraforce.com) to discuss your requirements. ## Best Practices > **Start with containment** > > Prioritize actions that stop the threat from spreading—isolate devices, disable compromised accounts, block malicious IPs. > **Use approval workflows for high-impact actions** > > Configure approval requirements for actions like device isolation that could impact business operations. > **Review before running** > > Always verify the Gamebook Card shows the correct entities and actions before clicking Run. > **Monitor the Gamebooks page** > > Check the Gamebooks page regularly for failed actions that may need manual intervention. > **Document with comments** > > After running a Gamebook, add comments to the incident explaining what actions were taken and why. ## Gamebook Actions Quick Reference | Entity | Actions Available | | - | - | | **User** | Invalidate Sessions, Lockout, Reset Password, Reset MFA, Unlock | | **Endpoint** | Isolate, Scan, Release from Isolation, Quarantine File | | **Network** | Block IP | | **Email** | Delete Email | ## Related Guides > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > Your toolset for security delivery > **[Incident Management](/guides/getting-started/incident-management)** > > Complete incident workflow guide > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > Classify incidents after response > **[User Management](/guides/general-support/user-group-management)** > > Configure approval permissions *** > [!NOTE] > > Questions about Gamebooks? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Workbench: Incident Investigation and Response Source: https://docs.contraforce.com/guides/getting-started/workbench-overview Use the Workbench for incident investigation and response: explore affected entities in the Entity Context Graph, then build, approve, and run Gamebooks. The Security Workbench is your investigation and response command center. Visualize affected entities, build custom response workflows, and execute remediation actions—all from a single interface. ![Incident Workbench with the incident header, Investigation panel tabs, and a Response panel showing a finished Gamebook](https://mintcdn.com/contraforce/n2V4XUDWFOitCP6z/expanded-incident-workbench.jpeg?fit=max\&auto=format\&n=n2V4XUDWFOitCP6z\&q=85\&s=a9c26847a652444b38f03ca3ba446292) ## What is the Workbench? The Workbench combines investigation and response into one powerful experience: > **AI-Mapped Response Actions** > > Automatically recommended response actions based on affected entity types > **Entity and Context Graph Visualization** > > See all related entities in an interactive context graph > **No-Code Queries** > > Click-through investigation for entities without writing queries > **Custom Workflows** > > Chain multiple actions into comprehensive Gamebooks > [!NOTE] > > The Workbench is where investigation meets action. Instead of switching between tools, you can analyze the threat and respond to it in the same place. *** ## Accessing the Workbench **1. Open an Incident** From the **Incidents** page, open an incident and select **View full details** **2. View the Summary** The Incident Summary opens with overview information **3. Open the Workbench** Select the Gamebooks Workbench icon next to **Actions** *** ## Workbench Layout The Security Workbench is organized into several key areas: ### Incident Header At the top of the Workbench, you'll find: | Element | Description | | - | - | | **Incident Title** | Name and ID of the incident | | **Status** | Current state (New, Active, Closed)—editable inline | | **Owner** | Assigned analyst—editable inline | | **Severity** | Incident severity level | > [!TIP] > > You can update the Status and Owner directly from the Workbench without leaving the page. ### Entity Graph The central visualization showing all entities involved in the incident: * **Users** — Accounts that were affected or involved * **Devices** — Endpoints implicated in the incident * **IPs** — Network addresses related to the activity * **Files** — Suspicious files or hashes detected * **URLs/Domains** — Web resources involved Click any entity icon to: * View entity details * See other incidents involving this entity * Access available response actions This is also the **investigation graph** your Security Delivery Agents traverse. When an agent investigates an incident, it walks these same relationships to determine which entities the incident impacted. ### Workbench Tabs **Summary** Overview of the incident including description, timeline summary, and key indicators. **Entities** Detailed list of all affected entities with expandable details and cross-incident correlation. **Comments** Team collaboration space. Add investigation notes and view comments from other analysts. **History** Complete audit trail of all actions taken on this incident, including previously run Gamebooks. *** ## Building a Gamebook Gamebooks are response workflows made up of response actions for each affected entity — you build them yourself, or a Security Delivery Agent compiles one for you. > [!NOTE] > > An agent-compiled Gamebook arrives already populated: the agent identifies the impacted entities from the graph above and maps the appropriate response actions to each one. It loads into the same **Gamebook card**, so you review and run it exactly as described below. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents). The steps below cover building one by hand. ### Step 1: Select an Entity Left-click an entity icon in the Entity Context Graph. The response actions appear already mapped to the entity type selected. ![Device entity action menu with Isolate Endpoint, Scan Endpoint and Release From Isolation, each with an add (+) button](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/left-click-entity-graph.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=a3af45f80a0b87fa76b835e33ad540d9) ### Step 2: Browse Available Actions By left-clicking entities, you will be able to utilize the following response actions: | Entity Type | Response Actions | | - | - | | **User** | Invalidate sessions, lockout user, reset user password, reset MFA, and unlock user | | **Device** | Isolate device, run AV scan, unisolate device | | **IP** | Block Azure Network Security Group (NSG) | | **File** | Quarantine file, block hash | > [!NOTE] > > Available actions depend on the entity type and your connected modules. Gamebook response actions automatically map to actions that are relevant and executable. ### Step 3: Add Actions to Gamebook * Click the **+ icon** to add a response action to your Gamebook * Hover over the action in the Gamebook and the **red - icon** will remove a response action * Repeat for each entity you want to take action on ![Gamebook with actions added](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/gamebook-add-remove.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=8b31d989445b2b91e2ef39b10636e98e) ### Step 4: Review Your Gamebook As you add actions, they load in the **Gamebook card**. ### Step 5: Execute the Gamebook **1. Review Response Actions** Verify all actions in the Gamebook are correct **2. Click Run Gamebook** Execute all actions in the Gamebook **3. Monitor Progress** Status updates from "Pending" to "Running" to "Finished" ![Gamebook execution complete](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/finished-gamebook.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=231eae089ab36941059193acf0c09243) *** ## Gamebook Approval Workflow Some Gamebooks require approval before execution, indicated by an **Approve** button in the Gamebooks page or in the Gamebook within the Workbench. > [!WARNING] > > Actions with approval requirements are typically high-impact operations like device isolation or reset user password. This prevents accidental execution. ### Requesting Approval 1. Build your Gamebook as usual (including locked actions) 2. Click **Request Gamebook Approval** instead of Run Gamebook 3. The request is sent to users with approval permissions ### Approving Gamebooks Approvers can approve requests from: * **The incident itself** — Open the incident and approve directly * **Gamebook Activity tab** — Review all pending approvals in one place ![Incident Response panel Activity tab showing a Gamebook run with a Waiting Approval badge](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/images/gamebook-activity-approval.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=b2ba1d1486251293073fbb9bcf1ab6c0) * **Gamebook Activity page** — Review all pending approvals in one place ![Gamebooks Activity page with the Queued filter selected, listing queued Gamebook runs](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/gamebook-page-approvals.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=2012da4bf1c41f72b6ebb67cf9438373) > [!TIP] > > Loading previous Gamebooks is especially useful for recurring incident types. Build a response once, reuse it across similar incidents. ## Gamebook Activity Page Track all Gamebooks in one queue across every workspace from the dedicated **Gamebooks Page**. ![Gamebooks Activity page listing queued Gamebook runs across all workspaces, with status filter chips](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/gamebook-page-approvals.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=2012da4bf1c41f72b6ebb67cf9438373) ### What You Can See | Column | Description | | - | - | | **Status** | Success, Failed, Pending Approval | | **Incident** | Linked incident ID | | **Actions** | What actions were performed | | **Time to Run** | Execution duration | | **Workspace** | Which workspace the actions ran against | ### Expanding Details Click any row to expand and see: * Individual action results * Error messages (if any failed) * Timestamps for each step * Entity details ## Best Practices > **Start with high-impact entities** > > Focus your initial response on the most critical entities—compromised users, infected devices, or malicious IPs that pose immediate risk. > **Use comments to document findings** > > Add comments as you investigate. This creates a record for your team and helps with post-incident review. > **Review before executing** > > Always review the complete Gamebook Card before clicking Run. Verify you're taking action on the correct entities. > **Check History for patterns** > > Before building a new Gamebook, check the History tab. A previous response may already exist that you can reuse or adapt. > **Monitor the Gamebook Activity page** > > Regularly check the Gamebook Activity page to ensure actions completed successfully and catch any failures early. *** ## Related Guides > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Deep dive into Gamebook capabilities. > **[Incident Management](/guides/getting-started/incident-management)** > > Complete incident workflows. > **[Entity Insights](/entity-insights)** > > Available entity enrichment data. > **[Incident Classifications](/guides/getting-started/incident-classifications)** > > Classify incidents after resolution. > **[Log Search](/guides/getting-started/log-search)** > > Run KQL queries against a workspace's Microsoft Sentinel logs. *** > [!NOTE] > > Need help with the Security Workbench? Contact us at [support@contraforce.com](mailto:support@contraforce.com) # Workspace Environments: Endpoints and Licenses Source: https://docs.contraforce.com/guides/getting-started/workspace-environments Review a workspace's endpoint and license inventory, find devices not yet onboarded to Defender, and see which response actions each connection supports. The **Environments** tab on a workspace's settings page shows what ContraForce can actually see inside that customer's tenant: which identities and licenses exist, which endpoints are onboarded, and which response actions the current connections support. > [!NOTE] > > Environments is a read-only view. Nothing on this tab changes a customer's configuration, and no user or device data is stored by ContraForce. Every list is fetched live from the provider when you open the page. ## When to use it > **Verify an onboarding** > > Confirm endpoints are onboarded and licenses are in place before declaring a workspace live > **Explain a blocked action** > > See at a glance whether a response action is unavailable because of licensing or a missing module > **Spot coverage gaps** > > Find devices that could be onboarded to Defender but are not > **Check seat usage** > > See how many seats of each security license are assigned ## Opening the tab **1. Open the workspace** From the [Workspace Center](/guides/getting-started/workspace-manager), click a workspace card to open its settings page **2. Go to Environments** Select the **Environments** tab **3. Open an environment** Click any row to drill into that provider's detail view The landing view lists every connected environment for the workspace. | Column | What it shows | | - | - | | **Environment** | Microsoft, CrowdStrike, or SentinelOne | | **Connections** | Which products that environment contributes | | **Status** | **Connected** when the underlying module is configured, otherwise **Not connected** | | **Last updated** | When inventory for that environment was last collected | > [!NOTE] > > Only providers with a configured detection module appear. If a workspace shows **No environments connected**, no detection module has been set up for it yet. *** ## Microsoft The Microsoft environment is split into two cards. ### Microsoft Entra ID Three counters summarise the directory: | Counter | Meaning | | - | - | | **Total users** | Every user account in the tenant directory | | **Enabled users** | Accounts that are not disabled | | **Licensed users** | Accounts holding at least one license of any kind | Below the counters are two tabs. **Licenses** lists the tenant's security-relevant subscriptions with seat usage, for example *Microsoft 365 E5 — 7 of 7 assigned*. Assigned seat counts come from Microsoft's own tenant-wide totals, so they match what the Microsoft 365 admin center reports. The list is deliberately filtered to security-relevant SKUs; unrelated subscriptions are not shown. **Users** lists directory accounts with their user principal name, enabled state, and whether they hold a license. Filter by **Licensed** or **State**, or search by name or user principal name. > [!TIP] > > Search queries the complete directory, not just the rows on screen. Large tenants show a sample in the table with a note saying so, but searching still finds any matching user. The card also reports **Product Detected** for Microsoft Entra ID Protection, and lists the **Identity gamebook capabilities** available in this workspace: invalidate existing sessions, lockout user, reset MFA, reset user password, and unlock user. ### Microsoft Defender Three counters summarise endpoint coverage: | Counter | Meaning | | - | - | | **Total endpoints** | Devices known to Defender | | **Onboarded** | Devices reporting into Defender | | **Can be onboarded** | Devices Defender has discovered but that are not yet reporting | > [!TIP] > > **Can be onboarded** is the most useful number on this tab for finding coverage gaps. These are real devices Defender already knows about that are not yet protected. The endpoint table lists each device with its operating system, health, onboarding state, and last seen time, and is searchable by name, OS, or status. Underneath, the card shows **Defender products detected**, the state of **Native automations** (AIR, ZAP, and attack disruption), and the **Defender gamebook capabilities** available: isolate endpoint, release from isolation, scan endpoint, and quarantine file. ## CrowdStrike and SentinelOne Each shows total, active, and contained endpoint counts, a searchable endpoint table with platform, agent version, status, and last seen, and the response Gamebook capabilities its connection supports. ## Reading capability states Every capability row carries a state. | State | Meaning | | - | - | | **Available** | The action can be dispatched in this workspace today | | **Not connected** | The Gamebook module providing the action is not connected | | **Not licensed** | The tenant's licensing does not include the action | | **Not observed** | Applies to native automations: ContraForce has not seen this mechanism act | > [!WARNING] > > A capability marked **Not licensed** cannot be enabled from ContraForce. It requires a licensing change in the customer's Microsoft tenant. ## Refreshing Each card has a **Refresh** button that re-collects inventory immediately, and a **Last collected** timestamp beneath it. Refresh requires the **Owner** or **Content Admin** workspace role; everyone who can open the workspace settings page can read the tab. *** ## Permissions and consent Directory inventory reads through the **Microsoft Defender XDR** module's connection, so that module must be connected before the Microsoft Entra ID card shows anything. If it is not, the card explains that instead of showing counters. ContraForce reads the directory with two Microsoft Graph application permissions on the Defender XDR app registration: | Permission | Used for | | - | - | | `Organization.Read.All` | License subscriptions and seat counts | | `User.Read.All` | User counts and the directory listing | Both are read-only. Neither allows ContraForce to modify users, licenses, or the tenant. ### Granting the directory permission Workspaces that connected Defender XDR before this permission was introduced need to reconsent the module once. Until they do, the Microsoft Entra ID card shows a **Microsoft Defender consent required** notice in place of the counters. **1. Open the notice** Go to the workspace's **Environments** tab and open the **Microsoft** environment **2. Grant or share** In your own tenant, click **Grant consent** to be taken to the Microsoft consent screen. For a managed customer's tenant, click **Copy consent link** instead and send it to that tenant's administrator. A partner administrator cannot consent inside a customer's directory. **3. Approve in Microsoft** A Global Administrator or Privileged Role Administrator reviews and approves the permissions **4. Return to the tab** You are returned to the Environments tab and the counters populate > [!WARNING] > > Consent must be granted by a **Global Administrator** or **Privileged Role Administrator** in the tenant being consented. Other roles cannot approve application permissions. > [!NOTE] > > Because these are application permissions, Microsoft shows the Defender XDR app registration's full permission set on the consent screen rather than only the new entry. Approving does not add anything beyond what the app registration declares. The same list is shown on the module's configuration page under **Microsoft Graph**. ## Troubleshooting > **The Microsoft Entra ID card says to connect Microsoft Defender XDR** > > Directory inventory is read through the Defender XDR connection. Connect that module on the workspace's **Modules** tab, then return to Environments. > **A consent notice appears even though the module is connected** > > The module was consented before the directory permission was added. Follow the consent steps above to reconsent it once. > **The consent notice is still showing right after granting consent** > > Click **Refresh** on the Microsoft Entra ID card. If it persists, confirm the approval completed in Microsoft and that it was granted in the correct tenant. > **You do not have access to this environment** > > Your account has no role on this workspace. A workspace owner needs to grant you access. Refreshing the page will not change this. > **The endpoint table shows a sample rather than every device** > > Large tenants are capped for page performance and show a note saying so. Use the search field, which queries the provider's complete inventory. ## Related > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspaces, modules, and per-workspace settings > **[Defender capability matrix](/guides/technical/microsoft-defender-capability-matrix)** > > Which capabilities each Microsoft license tier unlocks > **[Enterprise applications](/guides/technical/enterprise-applications)** > > The app registrations ContraForce uses and what each one needs > **[Platform permissions and consent](/guides/getting-started/platform-permissions-and-consent)** > > How consent works across the platform # Workspace Center: Manage Customer Workspaces Source: https://docs.contraforce.com/guides/getting-started/workspace-manager Manage customer workspaces in the Workspace Center: pre-onboard customers, monitor health, configure modules, grant consent, and set Gamebook approvers. The **Workspace Center** is your administrative control panel for every customer workspace. Monitor active workspaces at a glance, pre-onboard new customers, and drill into per-workspace settings. > [!NOTE] > > Workspaces represent individual customer tenants in ContraForce. Each workspace has its own data, configurations, modules, and user permissions. ## What Can You Do Here? > **Pre-Onboard Customers** > > Create workspace placeholders before customer admins complete their setup > **Manage Configurations** > > Edit module settings, integrations, and access from the per-workspace settings page > **Monitor Health** > > See which workspaces are healthy, need attention, or are still onboarding > **Control Permissions** > > Manage module consents and workspace-level access *** ## Accessing the Workspace Center **1. Locate the Workspaces icon** Find the **Workspaces** icon in the left navigation bar **2. Open the page** Click the icon to open the Workspace Center ![Workspaces icon in the left navigation](https://mintcdn.com/contraforce/EJSv-50EV_kHzCm1/images/nav-sidebar-workspaces.png?fit=max\&auto=format\&n=EJSv-50EV_kHzCm1\&q=85\&s=72d2d01bdc89cd91b420ac81921386f7) ## Page Layout: Tabs and KPI Cards The Workspace Center has a set of tabs and a row of rollup KPI cards. ![Workspace Center Workspaces tab with Workspaces connected, Need attention, and Onboarding cards above workspace cards](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/images/onboarding/workspace-center/workspaces-01-workspace-overview.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=84c00da0e8de54fb82ab5484e3f62baa) Workspace Center overview ### Rollup KPI cards The cards at the top of the page show counts at a glance and are clickable shortcuts. | Card | What it shows | What clicking does | | - | - | - | | **Workspaces connected** | Active customer workspaces in a healthy state | Switches to the Workspaces tab with the **All** filter | | **Need attention** | Active workspaces that have a missing module or undeployed agent | Switches to the Workspaces tab with the **Needs attention** filter | | **Onboarding** | Pre-onboarded workspaces awaiting customer admin setup | Switches to the Onboarding tab | ### Workspace Center tabs | Tab | What it contains | | - | - | | **Workspaces** | Active customer workspaces. Search, filter by health, and click a card to open its settings page | | **Onboarding** | Pre-onboarded workspaces awaiting customer admin setup. Add a new workspace from here, or click an existing card to see its onboarding progress | | **Profiles** | Reusable [Workspace Profiles](/guides/fleet-management/workspace-profiles) that apply the same access, module, notification, Gamebook, and agent settings to every attached workspace. Available to Organizational Admins on service provider accounts | | **SLA** | SLA configurations that set response and resolution targets for the workspaces you assign. See [SLA Tracking](/guides/getting-started/sla-tracking) | *** ## Workspace Cards Each workspace renders as a card. Click any card to open its settings page (no gear or equalizer button needed). ![Workspace card with a Your workspace badge, Modules and Agent pills, a green status light, and the flask icon](https://mintcdn.com/contraforce/KGdPGoMZjf7nE2PL/images/onboarding/workspace-center/workspaces-02-workspace-card.png?fit=max\&auto=format\&n=KGdPGoMZjf7nE2PL\&q=85\&s=11892c01bd5d16e4485a57426862fe9d) Workspace card anatomy ### What's on a card | Element | Description | | - | - | | **Status light** (top-right corner) | Green: healthy. Amber: needs attention. Blue: pre-onboarded. Hidden on the service provider's own workspace | | **Workspace name** | The customer's friendly name | | **Tenant ID** | The customer's Microsoft Entra tenant ID, in muted text below the name | | **Inline chip** | "Your workspace" on the service provider's own card; "Service provider" if the row represents the MSP itself with no monitoring on it | | **Modules pill** | Visible on the Workspaces tab. Healthy when at least one detection module is configured | | **Agent pill** | Visible on the Workspaces tab. Healthy when an Agent Center is deployed | > [!TIP] > > Health pills only appear on the Workspaces tab. The Onboarding tab uses the blue **pre-onboarded** status light instead, since health checks are not meaningful until the customer admin completes their onboarding. *** ## Search and Filter Both tabs include a **Search by workspace name** field that filters cards as you type. The Workspaces tab also has filter chips: | Filter | Description | | - | - | | **All** | Every active workspace, regardless of health | | **Needs attention** | Active workspaces with a missing detection module or no deployed Agent Center | | **Healthy** | Active workspaces with both a detection module and an Agent Center deployed | The Onboarding tab does not have filter chips. Use search to narrow the list when you have many pre-onboarded workspaces. > [!TIP] > > Press **Ctrl + K** to open [Quick Actions](/guides/getting-started/quick-actions), then type part of a workspace name to jump straight to its settings, modules, or notifications. *** ## Opening Workspace Details Click any card to open the workspace's settings page. ![Contoso workspace settings page on the General tab, with Workspace, Primary contact, and Activity sections](https://mintcdn.com/contraforce/OXtE1nSnqbk3dWX9/images/onboarding/workspace-center/workspaces-03-workspace-details.png?fit=max\&auto=format\&n=OXtE1nSnqbk3dWX9\&q=85\&s=79832b4141c578ee09693e46f236371c) Workspace settings page after clicking a card The settings page includes these areas: * **General** 1. **Account Information and Service Provider Information**: account identifiers, points of contact, account ID, account type, and subscription information 2. **Allow Service Providers to Run Gamebooks**: manage the team members responsible for approving Gamebooks that require manual authorization. Only users with the Workspace Owner role can be assigned as Gamebook Approvers * **Modules**: configure and manage detection and response modules * **IAM**: manage users, groups, and permissions at the workspace level * **Notifications**: configure the notifications module for Microsoft Sentinel * **Environments**: review the workspace's endpoint and license inventory, and which response actions each connection supports. See [Workspace Environments](/guides/getting-started/workspace-environments) * **Gamebooks** and **Agents**: set [Workspace Policies](/guides/getting-started/workspace-policies) that allow, block, or require approval for Gamebook actions, and allow or block agent investigations *** ## Pre-Onboarding a Customer Workspace Pre-onboarding lets you prepare a customer's workspace before they complete onboarding themselves. The customer admin receives an invite email and finishes the rest. See [Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding) for the customer-side flow. ### Why pre-onboard? > **Faster Deployment** > > Configuration is ready when the customer is > **Reduced Errors** > > Verify settings before the customer is invited > **Better Planning** > > Schedule onboardings in advance ### Creating a pre-onboarded workspace **1. Open the Onboarding tab** Click the **Onboarding** tab at the top of the Workspace Center **2. Click Add workspace** The button is in the top-right of the toolbar. The right-hand rail panel opens with the **Add workspace** form ![Onboarding tab with the Add a workspace panel open, showing Workspace name, Tenant ID, and Customer admin email fields](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-07-add-customer-workspace.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=1a640c2801a814465dd484a71dec8985) Add workspace rail open on the Onboarding tab **3. Fill in customer details** | Field | Description | | - | - | | **Workspace name** | Friendly label you'll use to refer to this customer | | **Tenant ID** | The customer's Microsoft Entra tenant ID | | **Primary point-of-contact email** | The customer admin who will receive the invite | | **Detection modules** | Pre-select the security tools the customer is bringing | | **Response modules** | Pre-select the response capabilities the customer will use | **4. Click Send Invite** ContraForce sends an invite email to the POC. The new workspace appears as a card on the Onboarding tab with a **Pending customer setup** badge ![Onboarding tab with a pre-onboarded workspace card and its Setup progress panel showing module and agent setup status](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-10-customer-workspace-preonboarded.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=e12d2aed4abd9d2f8f5414483378f86a) New pre-onboarded workspace card > [!TIP] > > Click any pre-onboarded card to see its onboarding progress in the right-hand rail. Use this to confirm which modules the customer has connected so far. To pre-onboard many customers at once from a CSV file, and have each new workspace land already configured by a Workspace Profile, see [Onboarding Workspaces at Scale](/guides/fleet-management/onboarding-workspaces-at-scale). ### When the customer finishes onboarding You'll receive a real-time **Customer onboarding complete** notification in the portal. The card moves from the Onboarding tab to the Workspaces tab, and the status light flips from blue (pre-onboarded) to green (healthy) or amber (needs attention) based on what the customer connected. For the post-go-live verification runbook, see [Workspace Onboarding Verification](/guides/onboarding/workspace-onboarding-checklist). *** ## Module Management Each workspace can have different modules enabled based on customer needs. Open a workspace's settings page (click the card), then go to the **Modules** tab. ### Available modules | Module | Description | Key features | | - | - | - | | [Microsoft Defender for Endpoint](/guides/onboarding/defender-for-endpoint-module-deployment) | Defender for Endpoint integration | Endpoint detection, response actions, device management | | [Microsoft Sentinel](/guides/onboarding/microsoft-sentinel-module) | Microsoft Sentinel integration | Log analysis, custom alerts, threat hunting | | [SentinelOne XDR](/guides/onboarding/sentinelone-module) | SentinelOne XDR integration | Read SentinelOne alerts and respond to SentinelOne endpoints | | [CrowdStrike](/guides/onboarding/crowdstrike-detection-and-response-modules) | CrowdStrike Falcon integration | CrowdStrike detection and response | | [Sumo Logic](/guides/onboarding/sumo-logic-module) | Sumo Logic monitors integration | Monitor alerts as incidents, monitor management | | Notifications | Incident notification engine | Email notifications for Microsoft Sentinel incidents based on severity | ### Configuring modules **1. Open the workspace** Click the workspace card to open its settings page **2. Go to the Modules tab** Navigate to the module you want to configure **3. Adjust settings** Enable or disable features, set thresholds, configure options **4. Consent permissions** Click **Consent** to authorize required permissions for the module **5. Save changes** Apply the configuration ### Module-specific settings **General** Basic workspace settings: * Workspace name * Alias name * Domain * Points of contact * Email address * Subscription ID * Subscription type **Modules** Enable or disable ContraForce modules: * Microsoft Sentinel (Detection + Response) > [!WARNING] > > Prerequisites to manage this module: > > * Microsoft Entra Role: Global Administrator or Privileged Role Administrator (required to grant the module Consent) > * ContraForce Workspace Role: Owner > * Microsoft Subscription Permission: Owner > [!TIP] > > Open this workspace's [Content Management System (CMS)](/guides/getting-started/content-management-system), its Detection Rules page, by selecting the flask icon on the Microsoft Sentinel module. * Microsoft Defender for Endpoint (Detection + Response) > [!WARNING] > > Prerequisites to manage this module: > > * Microsoft Entra Role: Global Administrator or Privileged Role Administrator (required to grant the module Consent) > * ContraForce Workspace Role: Owner * SentinelOne XDR (Detection + Response) > [!WARNING] > > Prerequisites to manage this module: > > * ContraForce Workspace Role: Owner * Gamebooks for Defender XDR (Response for endpoints) * Gamebooks for Identity (Response for users) * Gamebooks for Microsoft 365 (Response for emails) * Gamebooks for Azure (Response for Azure NSG) * Gamebooks for SentinelOne (Response for endpoints) **IAM** Group Management. Workspace Roles: * Owner * Content Admin * Incident Responder * Incident Analyst * Workspace Reader Use Role Management. User Roles: * Owner * Content Admin * Incident Responder * Incident Analyst * Workspace Reader **Notifications** Notification Settings: > [!WARNING] > > Prerequisites to manage this module: > > * ContraForce Workspace Role: Owner > * Sentinel Module Configured Microsoft Sentinel Notifications Settings Based on Severity: * High * Medium * Low * Info *** ## Permission Consent Some features require explicit consent to Microsoft enterprise applications. ### Why consent is required ContraForce uses Microsoft Graph API and other APIs to: * Read security alerts and incidents * Execute response actions (isolate devices, disable users) * Access log data for analysis These permissions must be granted by a tenant administrator. ### Granting consent **1. Open the workspace settings** Click the workspace card to open its settings page **2. Go to the Modules tab** Find the module that needs consent **3. Click Consent** A Microsoft authentication window opens **4. Sign in as a Global Administrator** Sign in with a **Global Administrator** or **Privileged Role Administrator** account. ContraForce uses app-only Microsoft Graph permissions, so Cloud Application Administrator and Application Administrator cannot grant this consent **5. Review and accept** Review the requested permissions and click **Accept** > [!WARNING] > > Consent requires **Global Administrator** privileges in the customer's Microsoft tenant. Work with your customer's IT team if you don't have Global Administrator access. > **[Platform Permissions](/guides/getting-started/platform-permissions-and-consent)** > > Which Microsoft Entra ID apps ContraForce uses and which admin roles can grant consent *** ## Best Practices > **Use consistent naming conventions** > > Name workspaces consistently (for example, "CustomerName: Primary") so they're easy to identify in search and filters. > **Pre-onboard before customer meetings** > > Create pre-onboarded workspaces before onboarding calls so the customer admin can complete their onboarding immediately. > **Watch the Need attention rollup** > > Periodically click the **Need attention** rollup card to surface workspaces missing a detection module or Agent Center. > **Verify consent status regularly** > > Token expirations or policy changes can affect access. Open a workspace's Modules tab to confirm everything still shows **Connected**. > **Document module configurations** > > Keep records of which modules and settings are enabled for each customer for support and renewal conversations. *** ## Troubleshooting ### Common Issues | Issue | Possible cause | Solution | | - | - | - | | Workspace shows no data | Consent not completed | Re-run consent flow with admin credentials | | Module won't enable | Missing permissions | Verify required permissions are granted | | Pre-onboarded card never moves to Workspaces tab | Customer admin hasn't finished onboarding | Resend the invite or contact the POC | | Configuration won't save | Validation error | Check for required fields or invalid values | | Status light is amber | Detection module or Agent Center missing | Open the workspace card and complete the missing module or deploy an agent | > [!NOTE] > > If you encounter persistent issues with workspace configuration, contact [support@contraforce.com](mailto:support@contraforce.com) with the workspace name and error details. *** ## Related Guides > **[MSP Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Granting access, Agent Center, connecting your own sources > **[Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding)** > > What customer admins see after the invite email > **[Workspace Onboarding Verification](/guides/onboarding/workspace-onboarding-checklist)** > > Post-go-live verification runbook > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Managing multiple workspaces *** > [!NOTE] > > Questions about the Workspace Center? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Workspace Policies for Gamebooks and Agents Source: https://docs.contraforce.com/guides/getting-started/workspace-policies Set ordered allow, block, and approval policies per workspace to control which Gamebook response actions run and which incidents your agents investigate. Workspace Policies let you decide, per workspace, what is allowed to run before it runs. Build each policy as a plain sentence from your own actions, people, and devices, put the policies in the order you want them checked, and ContraForce enforces them on every Gamebook action and agent investigation. > [!NOTE] > > **Who is this for?** Workspace Owners manage policies. Other roles can read the policy lists, and everyone benefits from the results: blocked actions are stopped before they run, and approval-gated actions wait for a decision. Policies live in **Workspace Center**: open a workspace, then use the **Gamebooks** tab for run policies and the **Agents** tab for investigation policies. *** ## How policies are checked Every policy list works the same way: 1. Policies are checked **in order, top to bottom**. 2. The **first policy that fits** the action decides: allow it, block it, or send it for approval. 3. If **no policy fits, the action is allowed**. Policies are an exception mechanism; a workspace with none behaves exactly as before. The position number next to each policy is its place in that order. Use the arrows to move a policy up or down, and the toggle to turn one off without deleting it. > [!NOTE] > > Order is how you express exceptions. A narrow **Allow** placed above a broad **Block** means "block this category, except these cases". The builder warns you when a new policy sits below a catch-all that would decide every run before your policy gets a turn. *** ## Gamebook run policies Run policies govern Gamebook actions: what may execute, against what, and whether an approver must sign off first. ### What a policy can do | Effect | Result | | - | - | | **Allow the action** | The action runs. Useful as an exception above a broader block. | | **Block the action** | The action does not run. | | **Ask an approver first** | The action pauses until an approver decides. | ### Who it applies to A run policy can apply to anyone, only to people in the workspace, only to Security Delivery Agents, or only to service providers managing the workspace. This lets you, for example, require approval for agent-initiated response actions while leaving your analysts unrestricted. ### Conditions Conditions decide when a policy fits an action. Pick them from your own data rather than typing identifiers: * **The action**: one or more of the workspace's actions (isolate endpoint, reset user password, and so on). * **The action's target**: specific people or devices the action would act on. * **The incident involves**: specific people or devices anywhere in the incident, protecting your VIPs and critical servers no matter which action is attempted. * **The incident title**: contains, is exactly, starts with, or is any of the values you list. * **The incident severity** and **the incident source**. Everything inside one condition group must be true together. Add an "or" group to give the policy a second, independent way to apply. ### Creating a run policy **1. Open the run policies list** In **Workspace Center**, open the workspace and select the **Gamebooks** tab. The **Run policies** card lists the workspace's policies in evaluation order. **2. Add a policy** Click **Add policy**, then choose **Blank policy**. The builder opens as a drawer. **3. Describe the rule** Name the policy, choose what it does and who it applies to, then add conditions. The live preview reads the policy back as one sentence, exactly as the list will show it. **4. Save** New policies start at the bottom of the list. Move them up with the arrows if they need to win over broader rules below. ### Switching to an allow-list posture By default, anything no policy covers is allowed. To flip that, use **Add policy → Block anything not allowed**. This adds a catch-all block at the bottom of the list, so only actions an **Allow** policy above it lets through will keep running. Delete it at any time to return to allowing everything. ### Policies in the action menus Action menus show policy outcomes before anyone clicks: an action a policy would block is disabled with a tooltip naming the policy, and an action that needs sign-off carries an approval badge. Enforcement still happens at run time, so the menu is a preview, never the decision. *** ## Agent investigation policies Investigation policies govern whether an agent investigates an incident at all. They live on the **Agents** tab of workspace settings, and the same list appears on each agent's **Policies** tab, so an edit made on either surface is immediately true on the other. Investigation policies **allow or block**; there is no approval option. Conditions cover the incident (who it involves, its title, severity, and source) plus schedules, which are best created as [Agent Shifts](/guides/agent-center/agent-shifts). When a policy blocks an **automatic** investigation, the incident simply stays in your team's queue and the verdict is recorded in the workspace audit trail. When a policy blocks a **manually triggered** investigation, the person triggering it sees a message naming the policy. *** ## Managing the list * **Edit** reopens a policy in the builder. What a policy covers is fixed at creation; everything else can change. * **Turn off** a policy to take it out of evaluation without losing it. * **Delete** removes it permanently. Actions it covered follow the remaining policies, and if none fit, they are allowed. * **Reorder** with the arrows. The confirmation and numbering always reflect the list you are looking at. *** ## Roles and permissions | Role | Permissions | | - | - | | Workspace Owner | Create, edit, reorder, enable or disable, and delete policies | | Other workspace and organization roles | Read the policy lists; see policy outcomes in action menus | *** ## Frequently asked questions > **What happens when no policy matches?** > > The action or investigation is allowed. Policies only change behavior where you write rules; an empty list changes nothing. > **Do run policies and investigation policies share one list?** > > No. Gamebook run policies and agent investigation policies are separate lists with separate ordering. They never affect each other's decisions. > **Why does the builder warn me about a policy above mine?** > > A catch-all policy earlier in the order decides every run before yours is reached, so your policy would never do anything unless you move it above that one. The warning names the policy and its position. > **Can two policies overlap?** > > Yes, deliberately. Overlap plus ordering is how exceptions work: the first fit wins, so put the narrow exception above the broad rule. > **Where do I see what a policy decided?** > > The workspace audit trail records policy verdicts, including investigations that were blocked automatically. For Gamebook runs that need approval, the run appears in the approval flow as usual. *** ## Related guides > **[Agent Shifts](/guides/agent-center/agent-shifts)** > > Schedule when agents investigate on their own with a weekly working-hours grid. > **[What are Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Understand the guided response workflows that run policies govern. > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up and configure agents using the three-phase adoption model. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings, modules, and access. *** Questions about Workspace Policies? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Deploying Agent Center with Microsoft Foundry Source: https://docs.contraforce.com/guides/onboarding/agent-center-deployment Deploy Agent Center to set up Microsoft Foundry for Security Delivery Agents. You need Azure Subscription Owner plus Organizational Admin or Agent Admin. The AI Agent Center enables you to deploy Microsoft Foundry infrastructure directly through ContraForce, powering automated incident investigation and response capabilities with Security Delivery Agents (SDAs). > [!NOTE] > > Agent Center leverages Microsoft Foundry to provision the AI infrastructure required for automated security operations. Once deployed, you can configure Security Delivery Agents to handle incidents automatically. ## What Can You Do Here? > **Deploy AI Infrastructure** > > Provision Microsoft Foundry resources through ContraForce > **Create Security Agents** > > Deploy Security Delivery Agents for automated response > **Enable Automation** > > Configure agents to investigate and respond to incidents > **Run Gamebooks** > > Allow agents to execute response playbooks automatically *** ## Prerequisites Before deploying Agent Center, ensure you meet the following requirements. ### User Requirements | Requirement | Description | | - | - | | **Subscription Owner** | Owner-level access to the Azure subscription where Agent Center infrastructure will be deployed | | **ContraForce Role** | Organizational Admin or Agent Admin role in ContraForce | | **Provisioning** | Users do not need to be separately provisioned for ContraForce | ### Required Tooling | Tool | Purpose | | - | - | | **Microsoft Foundry** | Microsoft Foundry platform for AI infrastructure provisioning | > [!WARNING] > > You must have Owner permissions on the Azure subscription to successfully deploy Agent Center infrastructure. Work with your Azure administrator if you don't have the required access. *** ## Deploy Agent Center from the Portal **1. Access ContraForce Portal** Navigate to [portal.contraforce.com](https://portal.contraforce.com) and sign in with your credentials **2. Navigate to AI Agent Center** Select **Agents** in the left navigation to open the Agent Center **3. Deploy Microsoft Foundry Infrastructure** Follow the on-screen prompts to configure and provision the Microsoft Foundry infrastructure in your environment **4. Deploy Your First Security Delivery Agent** Once infrastructure provisioning completes, deploy your first Security Delivery Agent (SDA) to begin automated incident handling > [!TIP] > > The deployment process handles all Azure resource provisioning automatically. You don't need to manually configure Microsoft Foundry resources. *** ## Post-Deployment Configuration After successfully deploying Agent Center, configure your Security Delivery Agents to match your operational requirements. ### Configuration Options **Manual Execution** **Run agents on-demand:** * Select individual incidents for investigation * Choose between investigation-only or investigation with response * Review agent findings before taking action **Automatic Execution** **Configure severity-based automation:** * Set agents to run automatically on new incidents * Filter by incident status (New, Active, Closed) * Define which severity levels trigger automatic execution **Gamebook Automation** **Enable automatic response actions:** * Allow agents to execute gamebooks * Set confidence thresholds for automated actions * Control which response types are permitted To have agents follow your team's policies, link [standard operating procedures (SOPs)](/guides/agent-center/operating-procedures) to them. To limit when an agent investigates on its own, set [Agent Shifts](/guides/agent-center/agent-shifts) for its working hours. *** ## Best Practices > **Verify Azure permissions before deployment** > > Confirm you have Subscription Owner access before starting the deployment process to avoid interruptions. > **Start with manual agent execution** > > Begin with Phase 1 (manual execution) to understand how agents analyze your specific incident types before enabling automation. > **Review agent outputs regularly** > > Monitor agent investigation results to ensure accuracy and tune configurations as needed. > **Document your deployment configuration** > > Keep records of your Agent Center settings for troubleshooting and future reference. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | Deployment fails | Insufficient Azure permissions | Verify Subscription Owner access | | Agent Center not visible | Missing ContraForce role | Confirm Organizational Admin or Agent Admin role assignment | | Infrastructure provisioning stuck | Azure resource limits | Check Azure subscription quotas and limits | | SDA deployment fails | Prerequisites incomplete | Ensure Microsoft Foundry infrastructure deployed successfully first | > [!NOTE] > > If you encounter persistent issues with Agent Center deployment, contact [support@contraforce.com](mailto:support@contraforce.com) with your subscription details and error messages. *** ## Related Guides > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > Set up automated incident investigation and response > **[Understanding Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Learn about automated response playbooks > **[Incident Management](/guides/getting-started/incident-management)** > > Overview of incident handling in ContraForce > **[User Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Understanding ContraForce role requirements > **[Defender for Endpoint On Queue](/guides/agent-center/defender-for-endpoint-on-queue)** > > Run On Queue agents on Defender for Endpoint incidents without Sentinel forwarding > **[Cost Management Center](/guides/general-support/cost-management-center)** > > Track agent token usage and set usage budgets and spend controls *** > [!NOTE] > > Questions about Agent Center deployment? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # CrowdStrike Falcon Detection and Response Modules Source: https://docs.contraforce.com/guides/onboarding/crowdstrike-detection-and-response-modules Create Falcon API clients, connect the CrowdStrike Falcon Detection and Response modules, ingest detections as incidents, and contain hosts with Gamebooks. > [!NOTE] > > **Who is this for?** Workspace Owners or Security Engineers who manage a workspace that uses CrowdStrike Falcon. This guide walks you through creating the CrowdStrike API clients, configuring both modules in ContraForce, and verifying that alerts flow end-to-end. ## Before You Begin ### What These Modules Do CrowdStrike integrates with ContraForce through two separate modules: > **Detection Module** > > **Detection ingestion and investigation** > > * Pulls Falcon detections from the CrowdStrike Alerts API > * Surfaces every detection as its own ContraForce incident > * Round-trips status changes and comments back to Falcon > **Response Module** > > **Gamebook response actions** > > * Powers Contain and Lift Containment Gamebooks > * Powers On-Demand Scan Gamebooks > * Required for any Gamebook that acts on a CrowdStrike-managed device The two modules use separate CrowdStrike API clients so each client has only the scopes it needs. ### Prerequisites **1. CrowdStrike Falcon subscription** An active CrowdStrike Falcon subscription with at least one product line in scope (EPP, IDP, or any of the product lines listed in **Select Alert Types** below). **2. Falcon admin access** Access to **API Clients and Keys** under **Support and resources → Resources and tools** in the Falcon console. This typically requires the Falcon Administrator role. **3. ContraForce workspace** A ContraForce workspace created for the tenant, with your account assigned the workspace **Owner** role. **4. Your CrowdStrike cloud region** Identify which CrowdStrike cloud your tenant is deployed in. You need this for the **Base URL** field when configuring each module. ### CrowdStrike Cloud Base URLs CrowdStrike has multiple regional clouds. Use the Base URL that matches your tenant: | Cloud | Base URL | | - | - | | US-1 (Commercial) | `https://api.crowdstrike.com` | | US-2 | `https://api.us-2.crowdstrike.com` | | EU-1 | `https://api.eu-1.crowdstrike.com` | > [!NOTE] > > ContraForce does not currently support CrowdStrike's US-GOV-1 cloud. Contact [support@contraforce.com](mailto:support@contraforce.com) if you have a GovCloud tenant. > [!TIP] > > You can confirm which cloud your tenant is in by looking at the URL of your Falcon console. A console URL of `https://falcon.us-2.crowdstrike.com` means you're on US-2. *** ## Step 1 — Create the Detection API Client in Falcon The scopes you grant on the Detection API client depend on which **Falcon tier** the customer is licensed for. Pick the matching column below — the tier you choose here must match what you select on the ContraForce configuration page in Step 3. 1. Navigate to **Support and resources → Resources and tools → API Clients and Keys** in the Falcon console 2. Click **Create API client** 3. Set **Client name** to `ContraForce Detection` 4. Set **Description** to `ContraForce alert ingestion and status writeback` 5. Under **API scopes**, grant the scopes for the customer's tier, then click **Create**: **Falcon Insight (EDR)** For tenants on **Falcon Insight (EDR) only.** Cases workbench is not available on this tier. | Resource | Permission | Why | | - | - | - | | **Alerts** | Read + Write | Ingest detections and update their status | | **User Management** | Read | Resolve assignee names on detections | | **Hosts** | Read | Resolve device metadata on detections | | **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities | **Falcon Insight XDR** For tenants licensed for **Falcon Insight XDR.** Cases workbench is active. | Resource | Permission | Why | | - | - | - | | **Alerts** | Read + Write | Ingest detections and update their status | | **Cases** | Read + Write | Resolve case context for detections that reference a case (used by detail views and reserved for upcoming Cases features) | | **User Management** | Read | Resolve assignee names on detections | | **Hosts** | Read | Resolve device metadata on detections | | **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities | **Falcon NG-SIEM** For tenants licensed for **NG-SIEM.** Same detection-as-incident shape as the other tiers, plus the LogScale-backed Process Tree ancestor walk and Events Timeline are unlocked. | Resource | Permission | Why | | - | - | - | | **Alerts** | Read + Write | Ingest detections and update their status | | **Cases** | Read + Write | Resolve case context for detections that reference a case (used by detail views and reserved for upcoming Cases features) | | **User Management** | Read | Resolve assignee names on detections | | **Hosts** | Read | Resolve device metadata on detections | | **IOCs (Indicators of Compromise)** | Read | Resolve IOC context on alert entities | | **NGSIEM** | Read + Write | Run LogScale searches for Process Tree and Events Timeline. Write is needed to start search jobs | Copy the **Client ID** and **Client Secret** to a secure location — the secret is only shown once. > [!WARNING] > > The Client Secret is shown once at creation time and cannot be retrieved later. If you lose it, you must reset the secret from the same API client in Falcon. *** ## Step 2 — Create the Response API Client in Falcon Repeat the process for a second API client that ContraForce will use for Gamebook response actions. 1. In the same **API Clients and Keys** menu, click **Create API client** 2. Set **Client name** to `ContraForce Response` 3. Set **Description** to `ContraForce Gamebook response actions` 4. Under **API scopes**, grant the scopes listed below, then click **Create**: | Resource | Permission | | - | - | | **Hosts** | Read + Write | | **On-Demand Scans (ODS)** | Read + Write | Copy the **Client ID** and **Client Secret** for the Response client. > [!TIP] > > Creating two separate API clients — one for Detection, one for Response — follows the principle of least privilege. The Detection client never needs to contain a device or run a scan, and the Response client never needs to read an alert. *** ## Step 3 — Configure the CrowdStrike Falcon Module in ContraForce 1. In the ContraForce portal, navigate to **Workspaces** → your workspace → **Modules** 2. Locate the **CrowdStrike Falcon** card and click **Configure** 3. Pick the **Falcon licensing tier** that matches the customer's CrowdStrike SKU. The required-scopes list, the incidents-table preview copy, and the verification panel all update based on this selection: | Tier | When to pick it | Effect on the platform | | - | - | - | | **Falcon Insight (EDR)** | Customer is on Falcon Insight (EDR) only — no Cases workbench, no NG-SIEM SKU | Each Falcon detection becomes its own incident in the table | | **Falcon Insight XDR** | Customer is licensed for XDR with Cases workbench but no NG-SIEM SKU | Each Falcon detection becomes its own incident; case context is resolvable on detections that reference a case | | **Falcon NG-SIEM** | Customer is licensed for NG-SIEM | Same detection-as-incident shape, plus LogScale-backed Process Tree ancestor walk and Events Timeline are unlocked | > [!WARNING] > > The tier you pick must match the customer's actual Falcon SKU. The required scopes and which advanced features (Process Tree ancestor walk, Events Timeline) unlock depend on the tier — see [CrowdStrike Falcon Integration → Tier Selection](/guides/technical/crowdstrike-falcon-integration#tier-selection-—-what-you-pick-on-the-configuration-page) for the full breakdown. 1. Fill in the following fields: | Field | Value | | - | - | | **Base URL** | The Base URL for your CrowdStrike cloud (see table above) | | **Client ID** | The Client ID from the Detection API client you created in Step 1 | | **Client Secret** | The Client Secret from the Detection API client | 1. Click **Test Connection** to verify the credentials reach CrowdStrike and have the scopes the selected tier requires 2. Review the **Verification panel** that appears below the form: * ✓ on a row means the API client has that scope and the tenant exposes the corresponding capability * ✗ on a row means the scope or capability is missing for the tier you picked — fix it in the Falcon console before saving * ℹ︎ on a row means the API client has more capability than the tier you picked uses (e.g. NG-SIEM is reachable but you picked Falcon Insight XDR) — pick a higher tier to unlock the advanced features 3. Click **Save** If Test Connection fails with a scope-missing error, return to the Falcon console and verify the scopes listed in Step 1 for the tier you picked. ### What You'll See After Saving The configuration page surfaces a "What you'll see in the incidents table" preview directly under the tier dropdown, so you can confirm the choice before saving. After Save, the incidents table reflects that preview the next time the poller runs (typically within a few minutes). ### Tune Which Products Are Ingested (Optional) After the credentials are saved, an **Alert Types** card appears as a sibling to the Configuration Information card. Use it to narrow which CrowdStrike products ContraForce ingests into the analyst queue — useful when you're contracted to triage only a subset of the products the customer's Falcon tenant emits. | Product | Wire form | Surfaces | | - | - | - | | **Endpoint (EPP)** | `epp` | Falcon Insight endpoint-protection detections | | **Identity (IDP)** | `idp` | Falcon Identity Protection alerts | | **Mobile** | `mobile` | Falcon for Mobile alerts | | **Data Protection** | `dp` | Falcon Data Protection alerts | | **NG-SIEM** | `ngsiem` | NG-SIEM correlation alerts | | **XDR** | `xdr` | Cross-platform correlated detections | | **Cloud Workload (CWPP)** | `cwpp` | Falcon Cloud Security workload-protection alerts | | **OverWatch** | `overwatch` | Falcon OverWatch managed-threat-hunting alerts | | **Third-Party** | `thirdparty` | Alerts ingested from integrated third-party tools | The card is **tier-aware** by default to cut UI noise: | Tier | Default checkbox shortlist | | - | - | | **Falcon Insight (EDR)** | EPP | | **Falcon Insight XDR** | EPP, IDP, XDR | | **Falcon NG-SIEM** | All products | Click **Show all products** above the checkbox list (visible on EDR / XDR tiers) to reveal the full catalog when the customer has non-standard add-ons (e.g. EDR with the Mobile add-on). The toggle auto-defaults to "show all" when the persisted selection already includes products outside the tier shortlist. > [!TIP] > > Saving the Alert Types card is **independent of Test Connection**. Changing the product selection does not require re-validating credentials or re-saving the Detection module — the card has its own Save button. > [!NOTE] > > Leaving every product checked, or unchecking every product, both fall through to "ingest all products." This preserves backwards-compatibility for workspaces created before the per-product filter shipped, and acts as a friendly fallback if you accidentally clear every box. ### Choose a Vendor-Side Service Account (Optional) By default, when one of your analysts takes a CrowdStrike-sourced incident in ContraForce, the assignment is recorded in the ContraForce audit log only and the underlying Falcon alert stays unassigned. This is the right default for tenants where every analyst already has a Falcon login, but in MSSP topologies most ContraForce analysts have no matching principal in the customer's Falcon tenant. The **Assignment Writeback** card lets you bind one CrowdStrike user (typically a named service account in the customer's Falcon tenant, e.g. `Stratascale ContraForce`) so that ContraForce mirrors every analyst assignment onto the underlying Falcon alert as that user. The end customer sees someone is actively engaged in their own Falcon console, without you having to provision a per-analyst account in every customer's tenant. | State | Behavior | | :- | :- | | **None (default)** | Assignment is recorded in the ContraForce audit log only. No vendor write. | | **Bound** | The selected Falcon user is PATCHed onto the alert as the vendor-side assignee on every analyst assignment in ContraForce. Unassigning in ContraForce also clears the assignee on Falcon. | To bind a service account: **1. Click Change** On the Assignment Writeback card, click **Change**. ContraForce queries the customer's Falcon user-management API (this requires the **User Management: Read** scope on the Detection client, already part of every tier in Step 1). **2. Search and pick** Type a name or email into the search box; the picker filters the live Falcon user list as you type. Pick the user that should appear as the assignee on the customer's Falcon console. **3. Save** Click **Save Service Account**. Future analyst assignments in ContraForce immediately mirror onto the underlying Falcon alert as the chosen user. To stop writing back, click **Remove** on the bound state, then **Save Service Account**. The card returns to **None** and the audit-only behavior resumes. > [!TIP] > > The ContraForce audit log is always the source of truth for who actually picked up an incident, regardless of what shows on the Falcon side. The writeback only controls visibility in the customer's Falcon console. > [!NOTE] > > The writeback only affects detections (alerts that contain a colon-shaped composite ID). Legacy case-shaped IDs continue to behave as audit-only. If the Falcon PATCH fails (network blip, Falcon-side outage, the bound user was deleted), ContraForce records the failure in the trace logs and continues with the audit-only assignment so your queue stays responsive. *** ## Step 4 — Configure the CrowdStrike Falcon Response Module 1. On the same **Modules** page, locate the **CrowdStrike Falcon Response** card and click **Configure** 2. Fill in the following fields: | Field | Value | | - | - | | **Base URL** | Same Base URL as the Detection module | | **Client ID** | The Client ID from the **Response** API client you created in Step 2 | | **Client Secret** | The Client Secret from the **Response** API client | 1. Click **Test Connection** to verify the credentials reach CrowdStrike and have the required scopes 2. Click **Save** A successful test means Gamebook response actions are ready for CrowdStrike-managed devices. *** ## Step 5 — Verify End-to-End **1. Wait for the first poll cycle** The Detection module polls CrowdStrike on a short interval. New alerts appear in ContraForce within a few minutes of being generated in Falcon. **2. Check the Command Dashboard** Navigate to the **Command Dashboard**. CrowdStrike incidents should appear alongside incidents from other sources. **3. Open an incident** Click into a CrowdStrike incident and verify that the **Entities** and **Timeline** tabs are populated with alert data. **4. Try a Gamebook (optional)** If the Response module is configured, open a CrowdStrike incident where the affected entity is a device and confirm that **Contain**, **Lift Containment**, and **On-Demand Scan** Gamebook actions are available. *** ## What Each Module Unlocks | Capability | Requires Detection | Requires Response | | - | :-: | :-: | | Ingest CrowdStrike Falcon detections as incidents | ✓ | | | Round-trip status, assignment, and comments to Falcon | ✓ | | | Receive real-time incident updates in the portal | ✓ | | | Run Contain and Lift Containment Gamebooks | | ✓ | | Run On-Demand Scan Gamebooks | | ✓ | | Trigger Security Delivery Agents on new incidents | ✓ | | You can configure the Detection module without the Response module if you don't need Gamebook response actions for CrowdStrike devices. Configuring only the Response module without Detection is not a supported configuration — you'd have no incidents for the Gamebooks to run on. *** ## Troubleshooting | Issue | Likely cause | Fix | | - | - | - | | Test Connection fails with `missing the 'Alerts: Read' scope` | The Detection API client does not have Alerts: Read granted | Return to **API Clients and Keys** in Falcon, edit the Detection client, enable **Alerts: Read**, and save | | Test Connection fails with `missing the 'Hosts: Write' scope` | The Response API client does not have Hosts: Write granted | Edit the Response client and enable **Hosts: Write** | | Test Connection fails with a generic OAuth error | The **Base URL** does not match the tenant's actual CrowdStrike cloud | Verify the Base URL against the cloud table above; cross-check against the Falcon console URL | | Verification panel shows ✗ on **Cases workbench** for XDR / NG-SIEM tier | The Detection API client does not have **Cases: Read + Write** granted | Edit the Detection client and add Cases: Read + Write, then re-run Test Connection. Without it, ContraForce can ingest detections normally but won't be able to resolve case context on detections that reference a case | | Verification panel shows ✗ on **NG-SIEM** for the NG-SIEM tier | The Detection API client does not have **NGSIEM: Read + Write** granted, or the tenant does not have the NG-SIEM SKU | Edit the Detection client and add NGSIEM: Read + Write; if the scope still doesn't appear in the Falcon console it means the tenant isn't licensed for NG-SIEM and you should pick the XDR tier instead | | Process Tree shows only the triggering process (no ancestors) | Tenant tier was set to EDR or XDR, or the NG-SIEM scope is missing | Confirm the customer is licensed for NG-SIEM and the tier dropdown reflects that; verify the NGSIEM scope on the Detection client | | Detection Events Timeline is empty on the NG-SIEM tier | NG-SIEM scope missing, or the alert's process lifetime predates the `base_sensor` retention horizon | Check the verification panel for ✗ on NG-SIEM; if the scope is fine, the older detection's events have aged out — see the [retention disclosure](/guides/technical/crowdstrike-falcon-integration#crowdstrike-data-retention-—-how-it-affects-the-platform) | | Incidents table is empty even though detections are firing in Falcon | Time filter or product filter on the queue is excluding everything; or the API client lost its **Alerts: Read** scope | Widen the date filter to a known-detection window, confirm Alerts: Read is still granted, and re-test the connection | | Gamebook response actions are greyed out | The Response module is not configured | Complete Step 4 to configure the Response module | | Agent comments do not appear in Falcon | The Detection API client does not have Alerts: Write | Add **Alerts: Write** to the Detection client | | Incident owner you assigned in ContraForce isn't reflected in Falcon | The Assignment Writeback card is set to **None** (the default), so the assignment is audit-only on the ContraForce side | Bind a Falcon service account on the Assignment Writeback card (see [Choose a Vendor-Side Service Account](#choose-a-vendor-side-service-account-optional)) and re-assign the incident | | Assignment Writeback card shows "Failed to load Falcon users" | The Detection API client does not have the **User Management: Read** scope | Edit the Detection API client in Falcon, add **User Management: Read**, and re-run Test Connection | | Bound service account no longer appears as the Falcon-side assignee | The bound user was disabled or deleted in the customer's Falcon tenant | Open the Assignment Writeback card, click **Change**, pick a still-active user, and save | ### Rotating an API Secret CrowdStrike secrets do not expire automatically, but some organizations rotate them on a schedule. 1. In Falcon, open the affected API client and click **Reset secret** 2. Copy the new secret 3. In ContraForce, reopen the affected module (Detection or Response) 4. Paste the new secret into **Client Secret** and click **Save** 5. Click **Test Connection** to verify *** ## Related Documentation > **[CrowdStrike Falcon Integration](/guides/technical/crowdstrike-falcon-integration)** > > What the integration does, what each tier unlocks, and how Falcon's retention shapes the data shown in the platform > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Learn how Gamebook response actions work > **[Incident Management](/guides/getting-started/incident-management)** > > Triage and resolve incidents in ContraForce > **[Entity Insights](/entity-insights)** > > Explore investigation context for an incident's entities > **[Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Detailed role reference for ContraForce users *** > [!NOTE] > > Questions about connecting CrowdStrike Falcon to ContraForce? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Customer Workspace Onboarding Source: https://docs.contraforce.com/guides/onboarding/customer-workspace-onboarding Finish customer workspace onboarding: open your invite link, grant the ContraForce API and Portal consents, consent each module, and fix sign-in failures. This guide is for **customer admins** whose service provider has pre-onboarded their workspace in ContraForce. You'll receive an invite email from your service provider. Click the link to start. > [!NOTE] > > **Who is this for?** > > * Customer security or IT admins finishing the workspace their MSP/MSSP started for them > * Global Administrators in the customer's Microsoft Entra tenant who need to grant ContraForce access If your sign-in fails before you reach your workspace, jump to [Troubleshooting: Sign-in failed](#troubleshooting-sign-in-failed). *** ## Prerequisites | Requirement | Why | | - | - | | **Microsoft Entra admin role** | Required to grant the two core ContraForce consents. Global Administrator, Privileged Role Administrator, Application Administrator, or Cloud Application Administrator can all grant these | | **Invite email from your service provider** | The link in this email is your onboarding entry point | | **Pop-ups allowed for `portal.contraforce.com`** | The Microsoft consent prompts open in a popup window | | **Azure Subscription Owner** | Only if you'll deploy the **Microsoft Sentinel** module, which deploys supporting Azure infrastructure | > [!WARNING] > > The two core consents on this page can be granted by a **Global Administrator**, **Privileged Role Administrator**, **Application Administrator**, or **Cloud Application Administrator**. If you hold none of these, forward your invite link to someone in your organization who does and have them sign in instead. > > Connecting security **modules** later is stricter: those consents request Microsoft Graph application permissions and need a **Global Administrator** or **Privileged Role Administrator**. *** ## How onboarding works Your service provider has already created your workspace and pre-selected the **Detection** and **Response** modules you need. Your job is to sign in, grant ContraForce access to your tenant, and grant **Consent** for each module on the **Modules** tab. There's no completion screen to wait for. Your workspace is onboarded when its **status light turns green** on its card in the Workspace Center. Your service provider receives a real-time notification the moment your workspace goes live. *** ## Step 1: Grant ContraForce Access to Your Tenant When you click the link in your invite email, you'll be redirected to Microsoft to sign in. The first time anyone from your organization signs in, a Global Administrator must approve the core ContraForce app. ContraForce requests two core consents — **ContraForce API** and **ContraForce Portal** — as **two separate** Microsoft consent prompts. Accept both. **1. Click the invite link** Open the email from your service provider and click the onboarding link. You'll be taken to **portal.contraforce.com**. **2. Sign in as a Global Administrator** You'll be redirected to Microsoft. Sign in with your Global Admin credentials. **3. Review and accept the ContraForce API consent** Microsoft displays a consent screen listing the permissions ContraForce needs to read security data from your tenant. Check **Consent on behalf of your organization** and click **Accept**. ![Microsoft consent dialog showing ContraForce API permissions](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/customer-images/onboarding-01-customer-api-consent.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=6c795bef90f96c825b3d9be9c9fd3e99) Microsoft consent screen: ContraForce API permissions **4. Review and accept the ContraForce Portal consent** A second Microsoft consent prompt appears for the ContraForce Portal. Check **Consent on behalf of your organization** again and click **Accept**. ![Second Microsoft consent screen with the org-wide checkbox highlighted](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/customer-images/onboarding-02-customer-second-consent.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=4f388d348400602809c9394d9253d0c2) Second Microsoft consent screen: ContraForce Portal > [!TIP] > > This is a one-time approval. Once a Global Admin grants both core consents, the rest of your team can sign in normally. *** ## Step 2: Consent to Your Modules After the core consents are granted, open your workspace and go to the **Modules** tab. The modules your service provider pre-selected are already listed for you — you just grant **Consent** for each one. **1. Open your workspace** From the Workspace Center, open the workspace your service provider created for you. **2. Go to the Modules tab** Each pre-selected detection and response module appears here with a **Consent** action. **3. Click Consent on each module** A Microsoft consent window opens. Sign in if prompted, review the permissions, and click **Accept**. Consent is granted **per module** — repeat for each module on the tab. You can consent to modules in any order. > [!NOTE] > > **Microsoft Sentinel customers:** Consenting to the Sentinel module automatically deploys the supporting Azure infrastructure in your subscription, including the Azure Lighthouse delegation, the Apollo resource group, and the Sentinel-side automation. You don't need to run a separate Azure deployment step. To deploy Sentinel, you must be an **Azure Subscription Owner**. Allow a few minutes for resources to appear. > [!TIP] > > Response modules (such as Gamebooks for Defender XDR, Identity, Microsoft 365, Azure, and SentinelOne) enable Gamebook actions like isolating devices, disabling users, and quarantining files. Consent to them the same way — a single **Consent** per module. *** ## Step 3: Confirm Your Workspace Is Live There's no completion screen. Your workspace is onboarded when its **status light turns green** on its card in the Workspace Center. | Status light | What it means | | - | - | | **Blue** | Pre-onboarded — your service provider created the workspace and invited you | | **Amber** | A module or agent is still missing — finish consenting to your modules | | **Green** | Onboarded and live — incidents will begin to flow in | > [!TIP] > > Your service provider receives a real-time notification when your workspace goes live, so they'll know you're ready. *** ## Adding Users (After Onboarding) Adding users is **not** part of onboarding. Once your workspace is live, add teammates from **Settings → User Management** using the **Invite people to the organization** dialog. Manage groups from **Settings → Group Management**. *** ## Troubleshooting: Sign-in Failed If you click your invite link and see a **Sign In Failed** page, it's almost always because: * You aren't a Global Administrator and ContraForce hasn't been pre-approved for your tenant yet * A previous sign-in attempt got into a bad state ![Microsoft Need admin approval page for ContraForce API, with a Return to the application without granting consent link](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/customer-non-admin/onboarding-01-non-admin-customer-need-approval.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=e8cebe48a7f5584ec0576ee1e2ac1eb5) Consent required ### What to do **1. Click Sign out in the top right** This clears any stale session that might be blocking sign-in. **2. If you're a Global Admin, click Try Again** Sign in. Microsoft will show the consent screen. Accept both core consents, and you'll proceed into your workspace. **3. If you're not a Global Admin, click Email Your Admin** Or copy the **Admin Consent Link** from the page and send it to a Global Admin in your organization. Once they accept, return to your invite link and click **Try Again**. > [!WARNING] > > Don't keep retrying the same sign-in repeatedly without signing out. Repeated failures can compound the bad-session state and require a browser cache clear to recover. *** ## Next Steps > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy and consent to the Defender for Endpoint module > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Your home base for incident triage across your environment > **[Incident Management](/guides/getting-started/incident-management)** > > How to triage, investigate, and respond to incidents > **[What Are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Automated response workflows you can run from any incident *** > [!NOTE] > > **Need help?** Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Microsoft Defender for Endpoint Module Deployment Source: https://docs.contraforce.com/guides/onboarding/defender-for-endpoint-module-deployment Deploy the Microsoft Defender for Endpoint module: grant core consents, consent the module and Gamebook response modules, and confirm incidents sync. This guide walks you through deploying the ContraForce Defender module, enabling you to manage Microsoft Defender for Endpoint incidents, run Gamebook response actions, and monitor endpoints across your managed workspaces. > [!NOTE] > > The Defender module is designed for environments using Microsoft Defender for Endpoint (Defender for Endpoint, Defender for Identity, Defender for Office 365, and Defender for Cloud Apps). If you also use Microsoft Sentinel, consider the **XDR + SIEM** module instead. ## Before You Begin ### Prerequisites Ensure you have the following before starting deployment: **1. Microsoft Defender for Endpoint** An active Microsoft Defender for Endpoint deployment in the target tenant **2. Admin Credentials** **Global Administrator** or **Privileged Role Administrator** access to the Microsoft tenant being onboarded — required to grant admin consent for ContraForce enterprise applications. Cloud Application Administrator and Application Administrator cannot grant consent for Microsoft Graph application permissions. **3. Portal Access** Access to [portal.contraforce.com](https://portal.contraforce.com), plus your workspace **invite link** if you are a customer admin onboarding an invited workspace ### Supported Licenses The Defender module works with the following Microsoft 365 licenses: | License | Supported | Notes | | - | :-: | - | | **Microsoft 365 Business Premium** | ✓ | Full XDR capabilities | | **Microsoft 365 E3** | ✓ | Full XDR capabilities | | **Microsoft 365 E5** | ✓ | Full XDR capabilities + advanced features | | **Standalone Defender for Endpoint** | ✓ | Endpoint features only | > **[Capability Matrix](/guides/technical/microsoft-defender-capability-matrix)** > > View detailed feature availability by license tier *** ## Module Options ContraForce offers two deployment modules. Choose based on your security stack: > **Defender Module** > > **Microsoft Defender for Endpoint only** > > * Defender for Endpoint incidents > * Endpoint management > * Identity and email response > * Gamebook actions > > *Choose this if you don't use Microsoft Sentinel* > **XDR + SIEM Module** > > **Defender for Endpoint + Microsoft Sentinel** > > * Everything in Defender module > * Sentinel incidents > * Advanced threat hunting > * Data connectors > * Custom notifications by severity > > *Choose this if you use Sentinel alongside Defender* ### Feature Comparison | Feature | Defender Module | XDR + SIEM Module | | - | :-: | :-: | | Defender for Endpoint Incidents | ✓ | ✓ | | Endpoint Management | ✓ | ✓ | | Gamebook Response Actions | ✓ | ✓ | | Entity Insights | ✓ | ✓ | | Sentinel Incidents | — | ✓ | | Advanced Threat Hunting | — | ✓ | | Data Connectors | — | ✓ | | Custom Severity Notifications | — | ✓ | > [!TIP] > > Not sure which module to choose? Start with the Defender module if you only use Defender products. You can upgrade to XDR + SIEM later if you add Sentinel. When a workspace has both Defender XDR and Sentinel connected, ContraForce keeps duplicate incidents out of your queue; see [Incident Deduplication](/guides/technical/parallel-incident-deduplication). *** ## Deployment Process You deploy the Defender module directly in the ContraForce portal — there is no separate setup tool to launch. Sign in, grant the core ContraForce app consents, then enable and consent the Defender module from your workspace's **Modules** tab. > [!WARNING] > > Granting consent requires the **Global Administrator** or **Privileged Role Administrator** role to authorize the enterprise applications. Cloud Application Administrator and Application Administrator cannot grant consent for Microsoft Graph application permissions. The role is required for the one-time consent only and is not retained; activate it just-in-time with Privileged Identity Management (PIM) and deactivate afterward. ### Step 1: Sign In and Grant Core App Consents **1. Open the portal** Open [portal.contraforce.com](https://portal.contraforce.com). If you were invited to a workspace, open your **invite link** instead — it routes you to the portal sign-in. **2. Sign in with Microsoft** Authenticate with a **Global Administrator** account from the target tenant. **3. Consent ContraForce API** The first time anyone from your tenant signs in, a Microsoft consent prompt appears for **ContraForce API**. Review the requested permissions and click **Accept**. **4. Consent ContraForce Portal** A second, separate Microsoft consent prompt appears for **ContraForce Portal**. Review the requested permissions and click **Accept**. > [!NOTE] > > **ContraForce API** and **ContraForce Portal** are consented as two separate Microsoft prompts. Both are required for all ContraForce deployments, regardless of module selection. *** ### Step 2: Open the Modules Tab After the core app consents complete, open the workspace you are onboarding and go to its **Modules** tab. This is where you enable and consent each module for the workspace. > [!TIP] > > If a module was pre-selected for your workspace during invitation (for example, **Detection** and **Response**), you'll find it listed here ready to consent. *** ### Step 3: Consent the Microsoft Defender for Endpoint Module On the **Modules** tab, enable and consent the Microsoft Defender for Endpoint module. **1. Locate the module** Find **Microsoft Defender for Endpoint** in the module list on the **Modules** tab. **2. Click Consent** Click **Consent** for the module. A Microsoft consent window opens. **3. Sign in and Accept** Sign in with your **Global Administrator** account, review the requested permissions, and click **Accept**. > [!NOTE] > > Consent is granted **per module** on the **Modules** tab with a single **Consent** action. The single Consent authorizes ContraForce to operate the module for the workspace. For the permissions it grants and how to verify or revoke consent, see [Defender for Endpoint Permissions and Consent](/defender-for-endpoint-module). *** ### Step 4: Consent Response (Gamebook) Modules To enable Gamebook response actions, consent the response modules you need — each with a single **Consent** on the **Modules** tab. **1. Gamebooks for Microsoft Defender for Endpoint** Consent this module to enable endpoint response actions (isolate, scan, offboard). **2. Additional response modules** Consent the response modules that match your environment (see the table below). | Module | Purpose | When to Consent | | - | - | - | | **Gamebooks for Identity** | User response actions (disable, reset password) | If managing Microsoft Entra ID identities | | **Microsoft 365 Response** | Email response actions (delete email) | If using Defender for Office 365 | | **Azure Response** | Azure resource response actions | If responding to Azure-based threats | For each module, click **Consent**, complete the Microsoft authentication flow, and click **Accept** on the permissions prompt. *** ### Step 5: Confirm the Workspace Is Live There is no completion screen. Your workspace is onboarded when its **status light turns green** on its card in the **Workspace Center**. **1. Check the status light** Open the **Workspace Center** and find your workspace card. A **green** status light means the workspace is live. A **blue** light means it is pre-onboarded and still awaiting consent; **amber** means a module or agent is still missing. **2. Verify incidents** Defender for Endpoint incidents begin syncing to ContraForce (this may take 15-30 minutes). Open the **Command** page to confirm incidents are appearing. **3. Test Gamebooks** Open an incident and confirm Gamebook response actions are available. > [!TIP] > > If you don't see incidents immediately, verify that incidents exist in Microsoft Defender for Endpoint. ContraForce only displays incidents that exist in the source system. *** ## Adding Users Adding users is **not** part of module deployment. Once your workspace is live, invite your team from the organization settings. **1. Invite people** Go to **Settings → User Management** and open the **Invite people to the organization** dialog to add users and assign roles. **2. Manage groups** Manage groups in **Settings → Group Management**. | Role | Best For | | - | - | | **Owner** | Team leads, workspace owners | | **Incident Responder** | SOC analysts who need response capabilities | | **Incident Analyst** | Junior analysts who work incidents and request approval to run Gamebooks | | **Workspace Reader** | Stakeholders who need read-only access | > **[User Roles Reference](/guides/general-support/roles-and-permissions-reference)** > > View detailed permissions for each role *** ## Defender Module Limitations When using the Defender module (without SIEM), the following features are **not available**: | Feature | Status | Alternative | | - | - | - | | SIEM Incidents | Not available | Upgrade to XDR + SIEM | | Sentinel Advanced Threat Hunting | Not available | Upgrade to XDR + SIEM | | Data Connectors page | Empty | Upgrade to XDR + SIEM | | Custom severity notifications | Not available | Upgrade to XDR + SIEM | ### Notifications > [!NOTE] > > **Defender Module Notification Behavior:** > > * Email notifications are **not** generated by ContraForce for new Defender for Endpoint incidents > * Email notifications **are** sent for Gamebook runs > * ContraForce does not interrupt existing Defender notification configurations > **[Notifications Guide](/guides/technical/notifications-configuration)** > > Choose which Sentinel incident severities send email notifications and who receives them *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Consent fails** | Insufficient permissions | Verify you're using a **Global Administrator** or **Privileged Role Administrator** account. Cloud Application Administrator and Application Administrator cannot grant consent for Microsoft Graph application permissions | | **Consent window doesn't open** | Pop-up blocker | Disable the pop-up blocker for portal.contraforce.com and click **Consent** again | | **No incidents appearing** | Sync in progress | Wait 15-30 minutes for initial sync | | **No incidents appearing** | No incidents in Defender | Verify incidents exist in the Microsoft Defender for Endpoint portal | | **No MDE device data** | MDE consent incomplete | Re-consent the Microsoft Defender for Endpoint module on the **Modules** tab | | **Gamebooks unavailable** | Module not consented | Consent **Gamebooks for Microsoft Defender for Endpoint** on the **Modules** tab | | **Status light not green** | Module or agent still missing | Confirm every required module shows consented on the **Modules** tab | ### Getting Help If you encounter issues during deployment: 1. **Check consent status** on the workspace **Modules** tab 2. **Verify admin permissions** in the target tenant 3. **Review error messages** for specific guidance 4. **Contact support** at [support@contraforce.com](mailto:support@contraforce.com) *** ## Related Documentation ### Enterprise Applications > **[Enterprise Applications Overview](/guides/technical/enterprise-applications)** > > Overview of all ContraForce service principals > **[Microsoft Defender for Endpoint Application](/guides/technical/enterprise-applications#contraforce-for-mde-microsoft-defender-for-endpoint)** > > Detailed permissions reference > **[Gamebooks for Defender for Endpoint](/guides/technical/enterprise-applications#contraforce-gamebooks-for-mde)** > > Endpoint response permissions > **[Portal Application](/guides/technical/enterprise-applications#contraforce-portal)** > > Core portal permissions ### Next Steps > **[Incident Management Guide](/guides/getting-started/incident-management)** > > Learn the incident workflow > **[Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Start using response actions > **[User Management](/guides/general-support/user-group-management)** > > Add and manage users > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Navigate your dashboard > **[Defender for Endpoint On Queue](/guides/agent-center/defender-for-endpoint-on-queue)** > > Let On Queue agents pick up Defender for Endpoint incidents without Sentinel forwarding > **[Defender Native Automations](/guides/technical/microsoft-defender-native-automations)** > > How ContraForce shows Defender AIR, ZAP, and attack disruption and works alongside them *** > [!NOTE] > > Questions about Defender module deployment? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Microsoft Sentinel Module Deployment Source: https://docs.contraforce.com/guides/onboarding/microsoft-sentinel-module Deploy the Microsoft Sentinel module: one consent sets up Azure Lighthouse and incident streaming so you can manage analytics rules and hunt with KQL. The Microsoft Sentinel module connects ContraForce to your Microsoft Sentinel workspace, enabling centralized monitoring, real-time incident streaming, and the ability to act on Sentinel security data directly from the ContraForce platform. > [!NOTE] > > **What this module adds:** Sentinel incident ingestion, the workspace's Content Management System (CMS) for detection rules, email notifications, log search, and Azure Lighthouse cross-tenant management. > [!NOTE] > > **Who is this for?** Workspace Owners deploying the Sentinel module from the **Modules** tab of a workspace in the ContraForce portal. *** ## Prerequisites Before starting, ensure you have the following: > **Admin Role** > > **Global Administrator** or **Privileged Role Administrator** — either can grant admin consent for ContraForce enterprise applications (service principals). Cloud Application Administrator and Application Administrator cannot grant consent for Microsoft Graph application permissions. > **Workspace Role** > > ContraForce Workspace Role: **Owner** > **Subscription Owner** > > Microsoft Subscription Permission: **Owner** — required to deploy the supporting Azure infrastructure ### Additional Requirements | Requirement | Details | | - | - | | **Microsoft Sentinel** | Active Sentinel workspace in your Azure subscription | | **Log Analytics Workspace** | The workspace linked to your Sentinel deployment | | **Resource Group Access** | Ability to create resources in the subscription | | **No Conflicting Policies** | Azure Policy must allow Lighthouse delegations | > [!WARNING] > > If you don't have Subscription Owner permissions, the Azure deployment will fail. Contact your Azure administrator to obtain the necessary access or have them complete the deployment with you. > [!WARNING] > > **Consent model.** ContraForce enterprise applications are consented with **application (app-only)** Microsoft Graph permissions. Admin consent for Microsoft Graph application permissions must be granted by a **Global Administrator** or a **Privileged Role Administrator** — Cloud Application Administrator and Application Administrator cannot grant it. The role is required for the one-time consent only and is not retained; activate it just-in-time with Privileged Identity Management (PIM) and deactivate afterward. > > Because actions run as the application (no signed-in user required), operator control is enforced through **Gamebook approval gates** — only Workspace Owners can approve high-impact actions — and a complete **audit trail** in the Gamebooks History page. *** ## What Gets Deployed When you deploy the Sentinel module, ContraForce **automatically** provisions the Azure resources needed for integration. You do not deploy Lighthouse or the streaming infrastructure as separate manual steps — they are created as part of module deployment. | Component | Purpose | | - | - | | **Azure Lighthouse** | Cross-tenant delegation for multi-tenant management | | **Apollo Resource Group** | Infrastructure for incident streaming | | **Logic App** | Streams Sentinel incidents to ContraForce in real-time | | **Automation Rule** | Triggers the Logic App when incidents are created/updated | | **Role Assignments** | Grants ContraForce service principals access to Sentinel | > **[Azure Resources Reference](/guides/technical/azure-resources-deployed)** > > Complete list of all deployed resources with details *** ## Step 1: Open the Modules Tab **1. Open Your Workspace** Sign in at [portal.contraforce.com](https://portal.contraforce.com), open the **Workspace Center**, and select the workspace you want to configure. **2. Go to the Modules Tab** Open the workspace and select the **Modules** tab. This is where every module is enabled and consented. **3. Locate Microsoft Sentinel** Find the **Microsoft Sentinel** module in the list of available modules. *** ## Step 2: Verify Prerequisites Before deploying, confirm you hold the required roles. The deployment will not complete without them. | Prerequisite | Required Value | | - | - | | Azure Role for Microsoft Tenant | Global Administrator | | ContraForce Workspace Role | Owner | | Microsoft Subscription Permission | Owner | > [!NOTE] > > If you're missing any of these, obtain the required permissions before proceeding. The deployment will fail without proper access. *** ## Step 3: Consent the Microsoft Sentinel Module Consent is a **single action per module** on the **Modules** tab. Clicking **Consent** grants everything ContraForce needs for this module in one step. **1. Click Consent** On the **Microsoft Sentinel** module, click **Consent**. **2. Sign In as Global Administrator** A Microsoft consent window opens. Sign in with **Global Administrator** credentials. **3. Accept Permissions** Review the requested permissions and click **Accept** to consent on behalf of your organization. **4. Deploy the Supporting Azure Infrastructure** Consenting the module **automatically deploys** the supporting Azure resources — Azure Lighthouse delegation, the Apollo resource group, and the Sentinel-side Logic App and automation rule. You may be prompted to sign in with an account that has **Subscription Owner** permissions so the resources can be created. > [!NOTE] > > Apollo resources are created in the customer's Azure subscription. Standard Azure charges may apply for Logic App executions. ### What the Sentinel Module Grants | Capability | Description | | - | - | | **Cross-tenant visibility** | View and manage Sentinel from the ContraForce portal | | **Incident access** | Read and update incidents across tenants | | **Query execution** | Run Log Analytics queries for threat hunting | | **Rule deployment** | Manage analytics rules in the workspace's CMS | ### Resources Created in Your Subscription | Resource | Type | Purpose | | - | - | - | | **cf-apollo-\[workspace]** | Resource Group | Container for streaming resources | | **cf-incident-stream** | Logic App | Processes and forwards incidents | | **cf-sentinel-connection** | API Connection | Authenticates to Sentinel | | **cf-incident-trigger** | Automation Rule | Triggers on incident changes | ### Threat Hunting Permissions The Sentinel module grants the **ContraForce Sentinel Hunting** application read access to your Log Analytics data. | Application | Permissions | Purpose | | - | - | - | | **ContraForce Sentinel Hunting** | Log Analytics Reader | Execute KQL queries for threat hunting | > **[Sentinel Hunting Application](/guides/technical/enterprise-applications#contraforce-sentinel-hunting)** > > Enterprise application details and permissions *** ## Step 4: Verify Module Status A workspace module is live when its status indicator turns **green** on its card. Confirm the Sentinel module is fully deployed: * Microsoft Sentinel module status light shows **green** * Sentinel incidents begin streaming into the Command Dashboard ### Test Incident Sync **1. Open the Command Dashboard** Navigate to the **Command Dashboard** in ContraForce. **2. Check for Sentinel Incidents** Look for incidents with the Sentinel source indicator. **3. Verify Incident Details** Click an incident to confirm entity enrichment and details are loading. > [!TIP] > > Incidents may take 5-15 minutes to appear initially. If you have existing incidents in Sentinel, they should sync automatically. *** ## Post-Deployment Steps ### Configure Notifications With the Sentinel module active, you can now configure email notifications: **1. Go to Notifications Settings** Navigate to workspace **Settings → Notifications**. **2. Enable Severity Filters** Select which severity levels should trigger notifications. **3. Save Settings** Click **Save** to apply your notification preferences. > **[Notifications Configuration](/guides/technical/notifications-configuration)** > > Complete guide to notification setup ### Deploy Detection Rules Manage this workspace's analytics rules in its **Content Management System (CMS)**: **1. Open the CMS** Open **Workspaces → \[workspace] → Modules** and select the flask icon on **Microsoft Sentinel**. The flask icon on the workspace's card in the Workspace Center opens the same page. **2. Review the Rules** The **Detection Rules** page opens on the **Sentinel Analytical Rules** tab. Filter by severity and status, or search by name. **3. Add or Change Rules** Select **Add rule** to create an analytics rule, or select rules and use **Actions** to enable, disable, or delete them in bulk. To manage the same detection content across many workspaces as versioned repositories, use the [Content Management Center](/guides/content-management-center/overview) instead. > **[Content Management System](/guides/getting-started/content-management-system)** > > Manage a workspace's Sentinel analytics rules and Defender custom detections *** ## Troubleshooting ### Common Issues | Issue | Cause | Solution | | - | - | - | | Subscription not visible | Insufficient permissions | Sign in with a Subscription Owner account | | Deployment fails | Azure Policy restrictions | Check for policies blocking Lighthouse or resource creation | | Lighthouse delegation fails | Existing delegation | Remove the existing Lighthouse delegation and retry | | Consent fails | Insufficient role | Grant consent with Global Administrator credentials | | No incidents appearing | No incidents in Sentinel | Verify incidents exist in the Sentinel portal | | Apollo Logic App disabled | Deployment issue | Manually enable the Logic App in the Azure portal | | Consent popup blocked | Browser settings | Allow popups from portal.contraforce.com | ### Verifying Azure Resources To verify resources deployed correctly: **1. Open Azure Portal** Navigate to [portal.azure.com](https://portal.azure.com). **2. Check Resource Group** Search for the Apollo resource group (cf-apollo-\[workspace]). **3. Verify Logic App** Confirm the Logic App exists and is **Enabled**. **4. Check Automation Rule** In Sentinel, go to **Automation → Automation Rules** and verify the ContraForce rule exists. ### Lighthouse Troubleshooting If Lighthouse delegation fails: 1. **Check Azure Policy** — Some organizations restrict Lighthouse delegations 2. **Remove existing delegations** — Conflicting delegations can cause failures 3. **Verify permissions** — Subscription Owner is required 4. **Check tenant settings** — Ensure cross-tenant access isn't blocked > **How to remove existing Lighthouse delegation** > > 1. Go to Azure Portal → Service providers > 2. Find any existing ContraForce delegations > 3. Click on the delegation and select **Delete** > 4. Wait for deletion to complete > 5. Retry the deployment in ContraForce > **How to enable Logic App manually** > > 1. Go to Azure Portal → Resource Groups > 2. Open the cf-apollo-\[workspace] resource group > 3. Click on the Logic App resource > 4. Click **Enable** if the Logic App is disabled > 5. Verify the Logic App shows "Enabled" status *** ## Module Capabilities Unlocked With the Sentinel module deployed, you now have access to: > **Sentinel Incidents** > > Real-time incident ingestion from Microsoft Sentinel > **Email Notifications** > > Instant alerts when new incidents are created > **Content Management System** > > Manage the workspace's Sentinel analytics rules > **[Log Search](/guides/getting-started/log-search)** > > Query Log Analytics for threat hunting > **Cross-Tenant Management** > > Manage multiple Sentinel workspaces from one portal > **Advanced Threat Hunting** > > Execute KQL queries across customer environments *** ## Next Steps > **[Configure Notifications](/guides/technical/notifications-configuration)** > > Set up email alerts for incidents > **[Deploy Detection Rules](/guides/content-management-center/rules)** > > Deploy rules from a content repository > **[Add Users](/guides/onboarding/user-group-management-for-providers)** > > Grant team access in Settings → User Management > **[Incident Management](/guides/getting-started/incident-management)** > > Start triaging Sentinel incidents *** ## Related Guides > **[Defender Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Defender for Endpoint integration > **[Azure Resources](/guides/technical/azure-resources-deployed)** > > Complete resource reference > **[Content Management Center](/guides/content-management-center/overview)** > > Detection rule management > **[Incident Deduplication](/guides/technical/parallel-incident-deduplication)** > > How duplicate Sentinel and Defender XDR incidents are kept out of your queue *** > [!NOTE] > > Need help with Sentinel module deployment? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Email Notifications for Incidents and Gamebooks Source: https://docs.contraforce.com/guides/onboarding/notifications-module Set up email notifications for Microsoft Sentinel incidents and Gamebook runs, see what each module supports, and route them to a team inbox or ITSM tool. ContraForce keeps your team informed with configurable email notifications. Receive alerts when new incidents are detected, Gamebooks complete, or when issues require attention—all customizable by severity and workspace. > [!NOTE] > > Notification capabilities vary by module. The XDR + SIEM module offers full customization, while the XDR-only module has limited notification options. ## Notification Overview > **Incident Alerts** > > Get notified when new security incidents are detected > **Gamebook Activity** > > Receive updates when Gamebook actions complete > **Severity Filtering** > > Choose which severity levels trigger notifications *** ## Notification Capabilities by Module Notification features depend on which ContraForce module you've deployed: | Feature | Defender Module | XDR + SIEM Module | | - | :-: | :-: | | Sentinel incident notifications | — | ✓ | | Defender for Endpoint incident notifications | — | — | | Gamebook completion notifications | ✓ | ✓ | | Severity-based filtering | — | ✓ | | Per-workspace customization | — | ✓ | | Distribution group support | — | ✓ | > [!WARNING] > > **Defender Module Users:** ContraForce does not generate email notifications for new Defender for Endpoint incidents. Use Microsoft Defender's built-in notification settings for Defender alerts. ContraForce notifications are sent only for Gamebook activity. > [!TIP] > > Deploying ContraForce does not interrupt or override your existing Microsoft Defender notification configuration. *** ## Email Notification Details ### Sender Address All ContraForce notifications are sent from: ``` noreply@notifications.contraforce.com ``` > [!NOTE] > > Add this address to your email allowlist to ensure notifications aren't blocked by spam filters. ### Email Content Incident notification emails include: | Field | Description | | - | - | | **Title** | Incident name/description | | **Description** | Summary of the security event | | **Severity** | High, Medium, Low, or Informational | | **Incident ID** | Unique identifier for tracking | | **MITRE Tactics** | Associated attack techniques | | **Entities** | Affected users, devices, IPs, etc. | | **View Incident Button** | Direct link to open the incident in ContraForce | ## Configuring Notifications ### Accessing Notification Settings Notifications are configured per workspace: **1. Open the Workspace** Select **Workspaces** in the left navigation and open the workspace **2. Select Notifications** Select the **Notifications** tab. Its sub-tabs cover **Incidents**, **Gamebooks**, **Agent Runs**, and **SOPs** notifications **3. Configure Preferences** On **Incidents**, choose which severities trigger notifications and who receives them ### Severity-Based Filtering For Microsoft Sentinel deployments, you can customize which severity levels trigger notifications: **High** **High severity incidents** typically indicate active threats requiring immediate response. *Recommendation: Always enable* **Medium** **Medium severity incidents** indicate potential threats that need investigation. *Recommendation: Enable for most teams* **Low** **Low severity incidents** are often informational or low-risk events. *Recommendation: Enable based on team capacity* **Informational** **Informational incidents** are typically audit events or low-priority alerts. *Recommendation: Disable to reduce noise, unless required for compliance* ### Per-Workspace Configuration Configure different notification preferences for each customer workspace: 1. Open **Workspaces → \[workspace] → Notifications → Incidents** 2. Turn on the severities (High, Medium, Low, Info) that should notify 3. Under **Recipients**, add the people, groups, or email addresses that should receive them > [!TIP] > > Use per-workspace configuration to match notification settings to each customer's SLA. High-priority customers might need all severities enabled, while others might only need High alerts. *** ## Distribution Group Notifications Send notifications to a team distribution list instead of individual users. ### Use Cases > **SOC Team Inbox** > > Route all alerts to a shared SOC mailbox for team visibility > **On-Call Rotation** > > Send to a distribution group that routes to the current on-call analyst > **Ticketing Integration** > > Route to an email address that auto-creates tickets in your ITSM > **Customer Notifications** > > Keep customers informed by CCing their security team ### Setting Up Distribution Groups Add a distribution list or shared mailbox as a recipient yourself: **1. Open Notifications** Open **Workspaces → \[workspace] → Notifications** **2. Add the Recipient** Under **Recipients**, select **Add recipient** and enter the distribution group's email address. You can also add workspace members and groups **3. Verify** Test that notifications are reaching the distribution group *** ## Gamebook Notifications Gamebook notifications are available for **all modules** (XDR and XDR + SIEM). ### When You'll Receive Notifications | Event | Notification Sent | | - | :-: | | Gamebook execution started | — | | Gamebook completed successfully | ✓ | | Gamebook failed | ✓ | | Gamebook requires approval | ✓ | | Gamebook approved | ✓ | ### Gamebook Email Content Gamebook notifications include: * Gamebook name * Target incident * Actions executed * Execution status (Success/Failed) * Workspace name * Link to view details *** ## Notification Best Practices > **Start with High severity only** > > Begin with High severity notifications enabled for all workspaces. Add Medium and Low severities gradually based on team capacity to avoid alert fatigue. > **Use distribution groups for team visibility** > > Route notifications to a shared mailbox so the entire SOC team has visibility. This prevents missed alerts when individuals are unavailable. > **Create email rules for organization** > > Set up email folder rules to automatically categorize ContraForce notifications by workspace or severity for easier triage. > **Integrate with ticketing systems** > > Route notifications to an email address that creates tickets in your ITSM (ServiceNow, Jira, etc.) for automatic tracking and SLA management. > **Review and adjust periodically** > > Regularly review notification settings. If you're experiencing alert fatigue, consider disabling lower severity levels or refining detection rules. > **Allowlist the sender address** > > Add `noreply@notifications.contraforce.com` to your email allowlist to prevent notifications from being caught by spam filters. *** ## Integrating Notifications with Other Tools ### Email-to-Ticket Integration Many ITSM platforms support email-based ticket creation: | Platform | Method | | - | - | | **ServiceNow** | Configure inbound email actions | | **Jira Service Management** | Use email request channel | | **Autotask** | Set up email-to-ticket rules | | **ConnectWise** | Configure email connector | > [!TIP] > > For tighter integration, consider using the [ContraForce v2 API](/api-reference/endpoints). ### Microsoft Teams / Slack For real-time team notifications: 1. Create an email-enabled channel in Teams or Slack 2. Use that email address as a distribution group in ContraForce 3. Notifications appear directly in your chat platform *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Not receiving notifications** | Spam filter blocking | Add sender to allowlist | | **Not receiving notifications** | Wrong module deployed | Verify you have XDR + SIEM module | | **Not receiving notifications** | Severity disabled | Check notification settings | | **Missing workspaces in settings** | Permissions issue | Verify you have admin access | | **Distribution group not working** | Not a recipient | Add it under Notifications → Recipients | | **Too many notifications** | All severities enabled | Disable Informational and Low | ### Testing Notifications To verify notifications are working: 1. Ensure notification settings are enabled for the workspace 2. Wait for a new incident to be detected (or ask ContraForce to send a test) 3. Check your inbox (including spam/junk folders) 4. Verify the email contains expected content *** ## Frequently Asked Questions > **What email address sends ContraForce notifications?** > > All notifications are sent from `noreply@notifications.contraforce.com` > **Can I get notifications for Defender for Endpoint incidents?** > > ContraForce does not send email notifications for Defender for Endpoint incidents directly. Use Microsoft Defender's built-in notification settings for those alerts. ContraForce sends notifications for Sentinel incidents (XDR + SIEM module) and Gamebook activity (all modules). > **How do I add a distribution group?** > > Open **Workspaces → \[workspace] → Notifications**, select **Add recipient**, and enter the distribution group's email address. > **Can I customize the email template?** > > Email templates are standardized and cannot be customized. For custom notification formatting, consider routing emails to a ticketing system that can reformat them. > **Is there a notification delay?** > > Notifications are sent in near real-time when incidents are detected and processed by ContraForce. Typical delay is under 5 minutes. > **Can I get SMS or push notifications?** > > ContraForce currently supports email notifications only. For SMS or push, route email notifications to a service like PagerDuty or Opsgenie. *** ## Related Guides > **[Module Reference](/onboarding-customer-workspaces#module-reference)** > > Compare the detection and response modules *** > [!NOTE] > > Questions about notifications? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # MSP and MSSP Platform Onboarding Source: https://docs.contraforce.com/guides/onboarding/platform-onboarding Onboard your MSP or MSSP organization: grant Microsoft Entra admin consent, set up your Agent Center, connect detection sources, and pre-onboard customers. This guide walks you through getting your **service-provider organization** up and running on ContraForce. By the end, you'll be ready to pre-onboard your first customer. > [!NOTE] > > **Who is this for?** > > * **MSP/MSSP partners** setting up your parent tenant before onboarding customers > * **Internal security teams** deploying ContraForce for your own organization This is Part 1 of onboarding. To see how it connects to your customer's part, read the [Onboarding Workspaces overview](/onboarding-customer-workspaces). If a teammate gets stuck at sign-in, jump to [Troubleshooting: Sign-in failed](#troubleshooting-sign-in-failed). *** ## Prerequisites | Requirement | Why | | - | - | | **Microsoft Entra admin role** | Required the very first time anyone from your tenant signs in, to grant ContraForce permission to read security data. Global Administrator, Privileged Role Administrator, Application Administrator, or Cloud Application Administrator can all grant this | | **ContraForce sign-up link** | Provided by your account team | | **Pop-ups allowed for `portal.contraforce.com`** | Microsoft consent prompts open in popup windows | > [!WARNING] > > If your tenant has a "Do not allow user consent" policy, the consent must be completed by a Global Administrator. Non-admin users will see a Sign In Failed page. See [Troubleshooting: Sign-in failed](#troubleshooting-sign-in-failed) below. *** ## Step 1: Grant ContraForce Access to Your Tenant Before anyone in your organization can sign in, a Microsoft Entra admin has to grant ContraForce permission to read security data from your tenant — a **Global Administrator**, **Privileged Role Administrator**, **Application Administrator**, or **Cloud Application Administrator**. **This is a one-time approval.** **1. Open the ContraForce sign-up link** Use the link your account team shared with you. **2. Sign in with Microsoft** You'll be redirected to Microsoft. Sign in with your Global Admin credentials. **3. Review the requested permissions** Microsoft displays a consent screen listing the permissions ContraForce needs. Review the list and click **Next**. To see what each ContraForce app does and why it asks for these permissions, see [Platform Permissions and Consent](/guides/getting-started/platform-permissions-and-consent). ![Microsoft consent dialog showing ContraForce Portal permissions](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-01-msp-first-consent.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=f5c63fb007602ead49de620fbb28fe32) Initial Microsoft consent screen **4. Accept the second consent** Microsoft may ask you to consent a second time: the first prompt covers the ContraForce Portal, and this one covers the ContraForce API. Check **Consent on behalf of your organization** and click **Accept**. ![Microsoft Permissions requested (2 of 2 apps) screen for ContraForce API with Consent on behalf of your organization checked](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-02-msp-second-consent.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=e6c06422c27f23bbb3886428e3d6a311) Second Microsoft consent: ContraForce API, with Consent on behalf of your organization checked *** ## Step 2: Sign In for the First Time Once consent is granted, create a workspace for your organization. ![Create a Workspace for your organization card with a Start Your Trial Now button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-03-msp-create-workspace.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=c84ab100408a3a4153d45fc04970306b) Create a Workspace for your organization card The platform detects that this is a brand-new tenant and creates your account automatically. You'll land on the **Command** page. ![Command page with the Get started with ContraForce checklist: Create your account checked and three Start buttons](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-04-msp-getting-started.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=352ba9b5e3f2b053b282149cc3f2d8ae) Command Dashboard on Getting Started *** ## Step 3: The Get Started Checklist The **Get started with ContraForce** panel is your home base for setup. It lists the activities your organization still needs to complete. | Item | What it does | | - | - | | **Create your account** | Already done by signing in for the first time | | **Setup agent center** | Choose where ContraForce-hosted automation runs | | **Connect sources** | Connect your own security tools so your SOC team can use ContraForce internally | | **Add customer workspaces** | Pre-onboard the customers you'll be managing | Each unchecked item has a **Start** button on the right that takes you straight to the relevant page. You can dismiss the panel at any time using the ✕ in the top right; it will also self-hide once every item is complete. *** ## Step 4: Set Up Your Agent Center Click **Start** next to **Setup agent center**. This is where you choose how the ContraForce automation engine runs for your organization. ![Agent Center Overview tab with a Welcome to your Agent Center banner, Get Started highlighted, and a What gets deployed list](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-05-agent-center.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=2565bd8ebf1e608668e0d5a93b89ac1a) Agent Center setup page You can either deploy your agent here or skip it and continue with the other items. If you deploy an agent, the **Setup agent center** item shows a green checkmark when you return to the Command Dashboard. > **[Agent Center Deployment Reference](/guides/onboarding/agent-center-deployment)** > > Detailed Agent Center setup, requirements, and configuration options *** ## Step 5: Connect Detection Sources to Your Own Workspace Click **Start** next to **Connect sources**. This jumps you straight to the detection-source picker for your own workspace. ![Workspace Modules tab with the Detection Module Connection panel listing Sentinel, Defender XDR, CrowdStrike and SentinelOne](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-06-detection-sources.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=a57c6a43a528314ab59d3681aec4f0c8) Detection-source picker for your own workspace Select the security tools your team uses, then follow the prompts to authorize ContraForce to read from each one. Once at least one detection source is connected, the **Connect sources** item on the checklist will check off. > [!NOTE] > > Connecting Microsoft Sentinel triggers ContraForce to deploy the supporting Azure infrastructure in your subscription automatically. You don't need a separate Azure deployment step. Provisioning runs in the background after you grant consent. *** ## Step 6: Add a Customer Workspace Click **Start** next to **Add customer workspaces**. You'll land on the **Workspace Center** with the **Onboarding** tab active and the **Add workspace** rail panel already open on the right. ![Add a workspace panel, step 1 of 2, with Workspace name, a verified Tenant ID and Customer admin email filled in](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-08-add-customer-workspace-2.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=d40718ce62d5b29925c2daac1f9c7db1) Workspace Center with Add workspace rail open Fill in the customer details: | Field | Description | | - | - | | **Workspace name** | Friendly label you'll use to refer to this customer | | **Tenant ID** | The customer's Microsoft Entra tenant ID | | **Customer admin email** (optional) | The customer admin who will complete onboarding on their side. The invite link is sent here | | **Detection modules** | Pre-select the security tools the customer is bringing | | **Response modules** | Pre-select the response capabilities the customer will use | ![Choose modules panel, step 2 of 2, with detection and response module tiles to select and a Send Invite button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-09-add-customer-workspace-3.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=71cb1cdfc11e07615df1d06b477bde11) Detection and response module pre-selection in the rail Click **Send Invite**. ContraForce sends an invite email to the customer admin email you entered, and the new workspace appears as a card in the Onboarding tab with a **Pending customer setup** badge. ![Onboarding tab with a pre-onboarded workspace card and its Setup progress panel, module and agent status, and invite link](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-images/onboarding-10-customer-workspace-preonboarded.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=e12d2aed4abd9d2f8f5414483378f86a) New customer workspace card on the Onboarding tab Repeat this step for every customer you want to manage. To add many customers at once, use [Onboarding Workspaces at Scale](/guides/fleet-management/onboarding-workspaces-at-scale) to import them from a CSV file. > [!TIP] > > When the customer admin finishes onboarding their workspace, you'll receive a real-time notification in the portal so you know their workspace is live. > **[Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding)** > > What your customer sees on their side after they receive the invite email *** ## Troubleshooting: Sign-in Failed If a teammate sees the **Sign In Failed** page after trying to log in, it usually means one of three things: * The Microsoft admin consent step was skipped * A non-admin user tried to sign in before consent was granted * A previous sign-in session is stuck ![Microsoft Need admin approval page for ContraForce Portal, with a Return to the application without granting consent link](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-01-non-admin-msp-need-approval.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=2ecfbe795b745741d7ee1636f81f07e3) Microsoft Need admin approval page ### What to do, in order **1. Click Return to the application without granting consent** This bounces you back to a clean state without applying a half-completed consent. **2. Send the admin consent link to your admin** Copy the admin consent link from the page and forward it to your Global Admin. ![ContraForce Sign In Failed page with the Admin Consent Link copy button highlighted and an Email Your Admin button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-02-non-admin-msp-login-failed-copy-link.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=9abdf6a92bb4ac9aeee5759e5b7119bd) Admin consent link to forward **3. Have your admin complete the consent flow** Your admin clicks the link, signs in as a Global Administrator, and walks through the Microsoft consent prompts. ![Microsoft Permissions requested screen for ContraForce API, listing Azure Resource Manager, profile, RBAC and app reads](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-03-non-admin-msp-admin-consent-1.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=e332cb4d19a085cd4f8497120563bccf) Admin consent: first permissions screen ![Microsoft Permissions requested (1 of 2 apps) screen for the ContraForce Portal app with a Next button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-04-non-admin-msp-admin-consent-2.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=ddcfa5ab5294892a9140f813808758a5) Admin consent: second permissions screen ![Microsoft Permissions requested (2 of 2 apps) screen for the ContraForce API app with an Accept button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-05-non-admin-msp-admin-consent-3.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=976a1f52a08fe77290d2a00055951e27) Admin consent: third permissions screen ![ContraForce Permissions Approved confirmation telling the admin the team can continue setup and the tab can be closed](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-06-non-admin-msp-admin-approved.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=ad64ed960b5ab501836627880a08f14a) Admin consent: Permissions Approved card Wait until your admin reaches the **Permissions Approved** card before you try again. **4. Try sign-in again** Once consent is approved, you can sign in normally and proceed to create your workspace. ![ContraForce Sign In Failed page with the Try Again button highlighted](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-07-non-admin-msp-try-again.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=327b116512d37032aeebc763ac906627) Sign In Failed page with Try Again highlighted ![Create a Workspace for your organization card with a Start Your Trial Now button](https://mintcdn.com/contraforce/WrVM0ufvE8QAC_TC/images/onboarding/msp-non-admin/onboarding-08-non-admin-msp-create-workspace.png?fit=max\&auto=format\&n=WrVM0ufvE8QAC_TC\&q=85\&s=14433c7b487956a104d534284511012d) Workspace creation continues If sign-in still fails after your admin has approved consent, [submit a support ticket](/submit-ticket) so our team can help. *** ## Next Steps > **[User & Group Management](/guides/onboarding/user-group-management-for-providers)** > > Set up groups before onboarding customers > **[Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding)** > > What your customer sees on their side > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Manage multiple customers efficiently > **[Roles & Permissions Reference](/guides/general-support/roles-and-permissions-reference)** > > Plan role assignments for your team > **[Workspace Profiles](/guides/fleet-management/workspace-profiles)** > > Set access, modules, and notifications once, then apply them to many workspaces > **[Shared Teams Channel](/guides/general-support/contraforce-success-teams-channel)** > > Set up a shared Microsoft Teams channel with the ContraForce Success Team *** > [!NOTE] > > Questions about platform onboarding? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # SentinelOne Detection and Response Modules Source: https://docs.contraforce.com/guides/onboarding/sentinelone-module Set up the SentinelOne integration for your workspace: create two Service Users, ingest threats as incidents, and run Contain and On-Demand Scan Gamebooks. > [!NOTE] > > **Who is this for?** Workspace Owners or Security Engineers who manage a workspace that uses SentinelOne Singularity. This guide walks you through creating two SentinelOne Service Users, configuring both modules in ContraForce, and verifying that threats flow end-to-end. ## Before You Begin ### What These Modules Do SentinelOne integrates with ContraForce through two separate modules: > **Detection Module** > > **Threat ingestion and investigation** > > * Polls the SentinelOne Threats API for new threats > * Classifies them as ContraForce Incidents or Detections > * Round-trips status changes and analyst notes back to SentinelOne > * Records incident ownership in ContraForce (not written back to SentinelOne) > **Response Module** > > **Gamebook response actions** > > * Powers Contain and Lift Containment Gamebooks (Network Quarantine) > * Powers On-Demand Scan Gamebooks > * Required for any Gamebook that acts on a SentinelOne-managed endpoint The two modules use separate SentinelOne Service Users so each has only the role it needs. > [!NOTE] > > **Incident ownership is tracked in ContraForce, not in SentinelOne.** A SentinelOne threat has no owner or assignee property, and analysts working through a service provider rarely hold an account in the customer's SentinelOne tenant. Assigning an owner in ContraForce therefore records the assignment in ContraForce, where every user who can see the incident can see who owns it. The SentinelOne console will continue to show the threat with no assignee. > > Status changes and analyst notes are unaffected — those still round-trip to SentinelOne. Unlike the CrowdStrike module, there is no option to mirror ownership to the vendor, because SentinelOne has no field to write it to. ### Prerequisites **1. SentinelOne Singularity subscription** An active SentinelOne Singularity subscription with endpoint agents deployed and reporting to the management console. **2. SentinelOne admin access** Access to **Settings → Users → Service Users** in the SentinelOne console. Creating Service Users typically requires the SentinelOne **Admin** role at the scope you plan to integrate. **3. ContraForce workspace** A ContraForce workspace created for the tenant, with your account assigned the workspace **Owner** role. **4. Your SentinelOne Management Console URL** Identify the full URL of your SentinelOne management console (for example, `https://yourtenant.sentinelone.net`). You will enter this as the **Endpoint** when configuring the Detection module. > [!TIP] > > You can confirm the Management Console URL by logging in to SentinelOne — the base URL in your browser (without any path after the hostname) is the value you will use. Do not include a trailing slash. ### Scope of Access SentinelOne scopes roles by **Global → Account → Site → Group**. For most integrations, set the scope of each Service User to **Site** and pick the specific sites you want ContraForce to monitor. Use **Account** only if ContraForce should cover every site in the account. *** ## Step 1 — Create the Detection Service User in SentinelOne 1. In the SentinelOne console, navigate to **Settings → Users → Service Users** 2. Click **Actions → Create New Service User** 3. Set **Name** to `ContraForce Detection` 4. Set **Description** to `ContraForce threat ingestion and status writeback` 5. Set **Scope of access** to **Site** (pick the sites ContraForce will monitor) or **Account** if all sites are in scope 6. Assign the built-in role **SOC** 7. Set an expiration date for the API token — SentinelOne supports up to 1 year. Pick a date that fits your rotation policy 8. Click **Create** SentinelOne will display the **API Token** on the confirmation screen. > [!WARNING] > > The API Token is shown once at creation time and cannot be retrieved later. Copy it to a secure location immediately. If you lose it, you must regenerate the token from the same Service User. > [!NOTE] > > If your organization doesn't use the built-in **SOC** role, you can create a custom role with the following permissions instead: **Threats** (View, Modify), **Threat Notes** (View, Add, Edit, Delete), and **Activity** (View). *** ## Step 2 — Create the Response Service User in SentinelOne Repeat the process for a second Service User that ContraForce will use for Gamebook response actions. 1. In **Settings → Users → Service Users**, click **Actions → Create New Service User** 2. Set **Name** to `ContraForce Response` 3. Set **Description** to `ContraForce Gamebook response actions` 4. Set **Scope of access** to match the Detection Service User 5. Assign the built-in role **IR Team** 6. Set an expiration date and click **Create** Copy the **API Token** for the Response Service User. > [!NOTE] > > If your organization doesn't use the built-in **IR Team** role, you can create a custom role with the Detection permissions above plus **Endpoints / Agents** (View, Disconnect, Reconnect, Initiate Scan). > [!TIP] > > Creating two separate Service Users — one with SOC for Detection, one with IR Team for Response — follows the principle of least privilege. The Detection user can't disconnect an endpoint, and the Response user doesn't get more threat access than it needs. *** ## Step 3 — Configure the SentinelOne Detection Module in ContraForce 1. In the ContraForce portal, navigate to **Workspaces** → your workspace → **Modules** 2. Locate the **SentinelOne Detection** card and click **Configure** 3. Fill in the following fields: | Field | Value | | - | - | | **Endpoint** | The full URL of your SentinelOne console, for example `https://yourtenant.sentinelone.net` — no trailing slash and no `/web/api/...` path | | **API Token** | The token from the Detection Service User you created in Step 1 | 1. Click **Test Connection** to verify the credentials reach SentinelOne and have the required permissions 2. Click **Configure and Save** If **Test Connection** fails, see the [Troubleshooting](#troubleshooting) table before saving. *** ## Step 4 — Configure the SentinelOne Response Module in ContraForce 1. On the same **Modules** page, locate the **SentinelOne Response** card and click **Configure** 2. Fill in the following fields: | Field | Value | | - | - | | **Endpoint** | Inherited from the Detection module — read-only. Edit it on the Detection card if it needs to change. | | **API Token** | The token from the Response Service User you created in Step 2 | 1. Click **Test Connection** and then **Configure and Save** A successful test means Gamebook response actions are ready for SentinelOne-managed endpoints. *** ## Step 5 — Verify End-to-End **1. Wait for the first poll cycle** The Detection module polls SentinelOne on a short interval. New threats appear in ContraForce within a few minutes of being generated in SentinelOne. **2. Check the Command Dashboard** Navigate to the **Command Dashboard**. SentinelOne threats should appear alongside incidents from other sources. **3. Open an incident** Click into a SentinelOne-sourced incident and verify that the **Entities** and **Timeline** tabs are populated with threat data. **4. Try a Gamebook (optional)** If the Response module is configured, open a SentinelOne incident where the affected entity is an agent and confirm that **Contain**, **Lift Containment**, and **On-Demand Scan** Gamebook actions are available. *** ## What Each Module Unlocks | Capability | Requires Detection | Requires Response | | - | :-: | :-: | | Ingest SentinelOne threats as incidents or detections | ✓ | | | Round-trip status and analyst notes to SentinelOne | ✓ | | | Assign an incident owner (recorded in ContraForce only) | ✓ | | | Receive real-time incident updates in the portal | ✓ | | | Run Contain and Lift Containment Gamebooks | | ✓ | | Run On-Demand Scan Gamebooks | | ✓ | | Trigger Security Delivery Agents on new incidents | ✓ | | You can configure the Detection module without the Response module if you don't need Gamebook response actions for SentinelOne endpoints. Configuring only the Response module without Detection is not a supported configuration — you'd have no incidents for the Gamebooks to run on. *** ## Troubleshooting | Issue | Likely cause | Fix | | - | - | - | | Test Connection fails with a URL / format error | The **Endpoint** is blank, has a trailing slash, or includes a path like `/web/api/...` | Re-enter the bare console URL, e.g. `https://yourtenant.sentinelone.net` | | Test Connection fails with `401 Unauthorized` | The API token is wrong, expired, or was rotated in SentinelOne | Regenerate the token for the affected Service User and paste the new value into ContraForce | | Test Connection fails with `403 Forbidden` on threats | The Detection Service User's role is missing **Threats: View** (or the SOC role was customized) | Verify the **SOC** role is assigned, or check that your custom role has Threats (View, Modify) | | Gamebook response actions are greyed out on SentinelOne incidents | The Response Service User's role is missing Network Quarantine or Initiate Scan permissions | Verify the **IR Team** role is assigned to the Response Service User, or check that your custom role has Endpoints / Agents (View, Disconnect, Reconnect, Initiate Scan) | | No threats appear after 15 minutes | No unresolved threats exist in the scope assigned to the Detection Service User | Verify threats exist in the SentinelOne console within the Sites or Account you selected | | Status updates from ContraForce don't appear in SentinelOne | The Detection Service User's role is missing **Threats: Modify** | Re-assign the SOC role or grant Threats: Modify in the custom role | | An owner assigned in ContraForce doesn't appear in SentinelOne | Expected behavior — SentinelOne threats have no owner field | None needed. Ownership is tracked in ContraForce; status and analyst notes still round-trip | | Polling stopped working after a while | The Detection API token's expiration date has passed | Rotate the token — see the section below | ### Rotating an API Token SentinelOne API tokens expire (up to 1 year). Plan to rotate before expiration. 1. In SentinelOne, navigate to **Settings → Users → Service Users** 2. Open the affected Service User (Detection or Response) 3. Click **Actions → Regenerate API Token** 4. Copy the new token immediately — it is only shown once 5. In ContraForce, reopen the affected module (Detection or Response) 6. Paste the new token into **API Token** and click **Configure and Save** 7. Click **Test Connection** to verify *** ## Related Documentation > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Learn how Gamebook response actions work > **[Incident Management](/guides/getting-started/incident-management)** > > Triage and resolve incidents in ContraForce > **[Entity Insights](/entity-insights)** > > Explore investigation context for an incident's entities > **[Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Detailed role reference for ContraForce users *** > [!NOTE] > > Questions about connecting SentinelOne to ContraForce? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Sumo Logic Detection Module Source: https://docs.contraforce.com/guides/onboarding/sumo-logic-module Connect Sumo Logic to your workspace with an OAuth client, investigate monitor alerts as incidents, and manage monitors. Cloud SIEM isn't ingested. > [!NOTE] > > **Who is this for?** Workspace Owners or Security Engineers who manage a workspace that uses Sumo Logic. This guide walks you through creating a Sumo Logic service account and OAuth client, configuring the module in ContraForce, and verifying that alerts flow end to end. ## Before You Begin ### What This Module Does The Sumo Logic Detection module connects a ContraForce workspace to a Sumo Logic organization: > **Incidents** > > **Monitor alerts become incidents** > > * Checks Sumo Logic for new monitor alerts about every 2 minutes > * Creates a ContraForce incident for each alert > * Shows the monitor behind each alert and the log messages that triggered it > * Resolves the alert in Sumo Logic when you close the incident in ContraForce > **Monitors** > > **Manage the monitors that raise alerts** > > * Lists the organization's monitors on the workspace **Detection Rules** page > * Shows each monitor's queries, trigger conditions, notifications and playbook > * Enables, disables, edits and deletes monitors from ContraForce > [!NOTE] > > **This module works with Sumo Logic monitors, not Cloud SIEM.** A ContraForce incident is a Sumo Logic monitor alert. Cloud SIEM Insights and Signals are not ingested, so the module works on any Sumo Logic plan that has monitors. ### What Syncs and What Stays in ContraForce | Action | Where it applies | | - | - | | **Close** an incident in ContraForce | ContraForce, and the alert is resolved in Sumo Logic | | Sumo Logic **auto-resolves** an alert | The ContraForce incident closes | | Set an incident to **New** or **In Progress**, or **reopen** it | ContraForce only | | Assign an **owner** | ContraForce only | | Add a **comment** | ContraForce only | Sumo Logic monitor alerts have no assignee, comments or in-progress state, so those are recorded in ContraForce, where everyone who can see the incident sees them. Sumo Logic resolves an alert on its own when the monitor's recovery condition is met, and the ContraForce incident follows. > [!NOTE] > > **Closing is best effort in Sumo Logic.** If Sumo Logic cannot be reached, or the alert no longer exists there, the incident still closes in ContraForce. Reopening an incident in ContraForce does not reopen the alert in Sumo Logic. ### Alert Retention Sumo Logic deletes monitor alerts 30 days after they are created, and ContraForce does not keep a copy of the alert or its logs. The log messages behind an alert are fetched from Sumo Logic each time you open the incident. After 30 days, the incident shows a **No longer retained in Sumo Logic** notice, and the status, classification, owner, comments and audit trail recorded in ContraForce are still shown. ### Prerequisites **1. Sumo Logic monitors** A Sumo Logic organization with the monitors you want ContraForce to track. **2. Sumo Logic administrator access** The Sumo Logic **Administrator** role, which is required to create service accounts and OAuth clients. **3. ContraForce workspace** A ContraForce workspace for the organization, with your account assigned the workspace **Owner** role. **4. Your Sumo Logic deployment** The Sumo Logic region hosting the organization, for example **US1** or **EU**. It is part of the API endpoint shown on the OAuth client page. *** ## Step 1: Create a Service Account in Sumo Logic An OAuth client acts as a service account. What ContraForce can do is limited both by the service account's role and by the OAuth client's scopes, so the role must allow everything the scopes grant. 1. In Sumo Logic, go to **Administration > Account Security Settings > Service Accounts** 2. Create a service account, for example `ContraForce` 3. Assign a role that can view alerts, view and manage monitors, and search the log data your monitors query *** ## Step 2: Create the OAuth Client in Sumo Logic 1. Go to **Administration > Account Security Settings > OAuth Clients** (classic UI: **Administration > Security**) 2. Click **Add OAuth Client** 3. Set **Client Type** to **Client Credentials** 4. Set **Name** to `ContraForce` and add a description 5. Set **Service Account** to the service account from Step 1 6. Select these four **Scopes**: | Scope | Why ContraForce needs it | | - | - | | **View Alerts** (`viewAlerts`) | Ingest monitor alerts as incidents | | **View Monitors** (`viewMonitorsV2`) | Read the monitor behind each alert | | **Run Log Search** (`runLogSearch`) | Fetch the log messages that triggered each alert | | **Manage Monitors** (`manageMonitorsV2`) | Manage monitors from the Monitors tab, and resolve alerts when an incident is closed | 1. Click **Save** Sumo Logic shows the **Client ID** and **Client Secret**. > [!WARNING] > > The client secret is shown once and cannot be retrieved later. Copy it to a secure location immediately. If you lose it, create a new OAuth client. > [!NOTE] > > All four scopes are required. The connection test in ContraForce fails if any of them is missing. *** ## Step 3: Configure the Sumo Logic Module in ContraForce 1. In the ContraForce portal, go to **Workspaces** > your workspace > **Modules** 2. Find the **Sumo Logic** detection module card and click its settings (gear) icon, **Configure Sumo Logic** 3. Fill in these fields: | Field | Value | | - | - | | **Deployment** | The Sumo Logic region hosting your organization, for example **US1 (US East)** | | **Client ID** | The client ID from Step 2 | | **Client secret** | The client secret from Step 2 | 1. Click **Test connection**. The button changes to **Connection verified** when the credentials, deployment and scopes are all correct 2. Click **Configure and save** The client secret is stored securely and never shown again. To change the configuration later, enter the secret again. If the test fails, see [Troubleshooting](#troubleshooting). *** ## Step 4: Verify End to End **1. Wait for the first check** ContraForce checks Sumo Logic about every 2 minutes. A new monitor alert appears as an incident within a few minutes. **2. Open an incident** Open a Sumo Logic incident. The **Rule** tab shows the monitor that raised the alert, and the **Logs** tab shows the log messages that triggered it, fetched from Sumo Logic. **3. Check the Monitors tab** On the **Sumo Logic** module card, click **Monitors**, or open **Detection Rules** for the workspace and select the **Sumo Logic Monitors** tab. Your monitors should be listed. *** ## Manage Monitors from ContraForce The **Sumo Logic Monitors** tab lists the organization's monitors with their folder path, type, alert levels, status and last change. Open a monitor to see its queries, trigger conditions, notifications and playbook. From an incident, **View monitor details** on the **Rule** tab opens the monitor behind the alert. Users with the workspace **Owner** or **Content Admin** role can: * **Enable** or **disable** a monitor * **Edit** a monitor's name, description, queries and alert thresholds * **Delete** a monitor Changes are made directly in Sumo Logic. An edit changes only those fields; every other setting, such as notifications and schedules, is kept as it is in Sumo Logic. > [!NOTE] > > **Some settings stay in Sumo Logic.** Thresholds can be edited for static conditions only. Outlier, anomaly, missing data and SLO conditions are shown but are edited in Sumo Logic. System monitors, and monitors Sumo Logic marks as read-only, cannot be changed from ContraForce. If someone changes a monitor in Sumo Logic while you are editing it, ContraForce does not overwrite their change. It asks you to reload the monitor and make your edit again. *** ## Limitations * **Cloud SIEM** Insights and Signals are not ingested * **Response actions**: there are no Gamebook response actions for Sumo Logic * **Log search**: there is no ad hoc log search from ContraForce; log messages are shown for the alert that triggered the incident * **Metrics monitors**: incidents from metrics monitors show no log messages * **Retention**: alerts older than 30 days are deleted by Sumo Logic, as described in [Alert Retention](#alert-retention) *** ## Troubleshooting | Issue | Likely cause | Fix | | - | - | - | | Test connection: Sumo Logic rejected the client ID and secret | The client ID or secret is wrong, or the **Deployment** is not the one your organization is hosted in | Check both values, and confirm the deployment matches your organization's region | | Test connection: not hosted in the selected deployment | The wrong **Deployment** is selected | Select the region shown in the API endpoint on the OAuth client page | | Test connection: missing required scopes | The OAuth client lacks one of the four scopes | Create a new OAuth client with all four scopes and enter its client ID and secret | | Test connection: denied access to monitor alerts | The service account's role cannot view alerts | Give the service account's role permission to view alerts | | No incidents appear after 15 minutes | No monitor alerts have fired since the module was configured | Confirm in Sumo Logic that a monitor has triggered an alert recently | | An incident shows no log messages | The alert is from a metrics monitor, is older than 30 days, or the service account cannot search the monitor's data | Check the monitor type and alert age, and the service account's data access | | The Monitors tab says access was denied | Your workspace role cannot manage monitors, or Sumo Logic refused the request | Follow the message shown. For a Sumo Logic refusal, add the missing scopes to the OAuth client and test the connection again | | A closed incident's alert is still open in Sumo Logic | Resolving in Sumo Logic is best effort | Resolve the alert in Sumo Logic. The incident stays closed in ContraForce | *** ## Related Documentation > **[Incident Management](/guides/getting-started/incident-management)** > > Triage and resolve incidents in ContraForce > **[Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Detailed role reference for ContraForce users *** > [!NOTE] > > Questions about connecting Sumo Logic to ContraForce? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # User and Group Management for MSPs and MSSPs Source: https://docs.contraforce.com/guides/onboarding/user-group-management-for-providers Manage users and groups as an MSP or MSSP: create organization groups once, assign them roles in each customer workspace, and troubleshoot access. This guide addresses the most common challenges MSP/MSSP partners face when setting up user and group management in ContraForce. Understanding the relationship between parent (partner) and child (customer) workspaces is essential for a smooth onboarding experience. > ## For Azure Administrators > > For MSP/MSSP teams already fluent in Azure and Entra administration, ContraForce's user and group management model will feel intuitive once you establish these mental mappings: > > 1. Organization = Root Management Group: The top-level scope where you establish identities that can flow down > 2. Workspace = Subscription / Administrative Unit: The isolation boundary where customer-specific access lives > 3. Organization Groups = Inherited RBAC: Create once, assign many times, automatic access when group membership changes > 4. Workspace Users = AU-scoped delegation: Strictly bounded to one customer's data > 5. Two locations = Two scopes: Just like Azure has IAM blades at different levels, ContraForce has Organization Settings and Workspace Settings > > The key transferable skill is **thinking hierarchically about access scope**—a discipline your team has already developed managing Azure governance at scale. > [!NOTE] > > This guide is specifically designed for **MSP/MSSP partners** managing multiple customer workspaces. If you're a single-tenant customer, see the standard [User Management](/guides/general-support/user-group-management) guide. ## Understanding the Two-Tier Model ContraForce uses a two-tier user management model that separates partner-level access from customer-level access. This is the **most important concept** to understand before configuring users and groups. > **Parent (Partner) Level** > > Your organization's workspace where you manage your team and oversee all customer workspaces > **Child (Customer) Level** > > Individual customer workspaces where you manage customer-specific users and access ### How the Tiers Work Together ```mermaid theme={null} flowchart TD A[Partner Organization] --> B[Partner Workspace] B --> C[Partner Users & Groups] B --> D[Customer Workspace 1] B --> E[Customer Workspace 2] B --> F[Customer Workspace 3] D --> G[Customer 1 Users & Groups] E --> H[Customer 2 Users & Groups] F --> I[Customer 3 Users & Groups] C --> D C --> E C --> F ``` > [!WARNING] > > **Key Insight:** Users and groups created at the **child (customer) level** are only visible within that specific workspace. Users and groups created at the **parent (partner) level** can be assigned access across ALL workspaces. *** ## The Two Places for User & Group Management One of the most common points of confusion is that there are **two different locations** to manage users and groups, each serving a different purpose. ### Location 1: Organization Settings (Partner Level) **Path:** Settings → User Management This is where you manage users and groups for your **partner organization**: | What You Manage | Scope | | - | - | | Partner team members | Access to all workspaces | | Partner user groups | Cross-workspace permissions | | Organizational roles | Partner-level capabilities | ![Settings User Management tab with the Users table, Organizational Role column, and Sync Users and Add User buttons](https://mintcdn.com/contraforce/KGdPGoMZjf7nE2PL/Settings-User.png?fit=max\&auto=format\&n=KGdPGoMZjf7nE2PL\&q=85\&s=e37811d67ca74d716f63dd3ec15fc459) ### Location 2: Workspace Settings (Customer Level) **Path:** Workspaces → \[Select Customer] → IAM → Users & Groups This is where you manage users and groups for a **specific customer workspace**: | What You Manage | Scope | | - | - | | Customer users | This workspace only | | Customer groups | This workspace only | | Workspace-specific roles | This workspace only | ![Workspace IAM tab, Users sub-tab, listing three users with the Owner, Incident Analyst and Incident Responder workspace roles](https://mintcdn.com/contraforce/KGdPGoMZjf7nE2PL/Workspace-Equalizer-IAM.png?fit=max\&auto=format\&n=KGdPGoMZjf7nE2PL\&q=85\&s=def29a318afda80d18c2cc26f6d40c63) ### Quick Reference: Where to Go | I Want To... | Go To | | - | - | | Add a partner analyst who needs access to multiple customers | Organization Settings | | Create a group for your SOC team to access all workspaces | Organization Settings | | Add a customer's IT admin to view their own workspace | Workspace Settings | | Create a customer-specific group | Workspace Settings | | Manage your own organization's users | Organization Settings | | Grant a customer limited access to their incidents | Workspace Settings | *** ## Parent vs Child: When to Use Each ### Use Parent (Organization) Level When: > **Adding your own team members (SOC analysts, engineers)** > > Your internal team needs access to multiple or all customer workspaces. Adding them at the organization level lets you assign them to any workspace without recreating their account. > > **Example:** Adding a new SOC analyst who will handle incidents for 10 customers. > **Creating groups for your internal teams** > > Create groups like "Tier 1 Analysts," "Tier 2 Engineers," or "Account Managers" at the organization level, then assign these groups to relevant workspaces. > > **Example:** Create a "SOC Team" group, add your analysts, then assign this group to all customer workspaces. > **Setting up cross-workspace permissions** > > When you need consistent permissions across multiple customers, define them at the organization level. > > **Example:** All Tier 1 analysts should have "Incident Analyst" role across all customer workspaces. ### Use Child (Workspace) Level When: > **Adding customer users who only access their own data** > > Customers who need to view their own incidents, reports, or dashboards should be added at the workspace level. > > **Example:** Adding a customer's CISO who wants to review their security incidents. > **Creating customer-specific groups** > > Groups that only make sense for a specific customer should be created at the workspace level. > > **Example:** A customer's "Security Committee" group that reviews monthly reports. > **Granting limited access to customer stakeholders** > > When customers need read-only or limited access to their workspace. > > **Example:** A customer's compliance officer who needs incident audit access. *** ## Step-by-Step: Setting Up Partner Users ### Adding a Partner Team Member **1. Navigate to Organization Settings** Go to **Settings** → **User Management** **2. Click Add User** Click the **Add User** button **3. Enter User Details** Enter the user's email address (must match their Microsoft Entra ID account) **4. Assign Organizational Role** New users start as **Member**. Only an Org Admin can pick a higher organization role: * **Org Admin**: full control of the organization, including roles and API keys * **User Admin**: manages users and groups * **Workspace Admin**: adds and manages customer workspaces and who can access them * **Agent Admin**: deploys and configures agents * **Member**: standard access to the workspaces they are assigned to **5. Save User** Click **Save** to create the user **6. Assign to Workspaces** Assign the user to specific customer workspaces (see next section) > [!TIP] > > To sync the people and groups you assign in Microsoft Entra ID instead of adding them one at a time, see [Setting Up SCIM Provisioning](/guides/technical/scim-provisioning). ### Assigning Users to Customer Workspaces After creating a user at the organization level, grant them access to customer workspaces: **1. Go to Workspaces** Navigate to the **Workspaces** page **2. Select Customer Workspace** Click on the customer workspace you want to configure **3. Open Workspace Settings** Click the workspace card to open its settings page **4. Go to Users & Groups** Select the **Users & Groups** tab **5. Add User or Group** Add the organization user or group to this workspace **6. Assign Workspace Role** Select the role for this specific workspace: * **Owner**: full workspace control, including users, modules and settings * **Content Admin**: manages analytic rules and works incidents * **Incident Responder**: works incidents and runs Gamebooks * **Incident Analyst**: works incidents and requests approval to run Gamebooks * **Workspace Reader**: read-only access *** ## Step-by-Step: Setting Up Groups Groups simplify permission management by letting you assign roles to multiple users at once. ### Creating an Organization Group **1. Navigate to Organization Settings** Go to **Settings** → **User Management** → **Groups** tab **2. Click Create Group** Click **Create Group** **3. Name the Group** Enter a descriptive name (e.g., "SOC Tier 1 Analysts") **4. Add Members** Select users to add to this group **5. Save Group** Click **Save** to create the group ### Assigning a Group to Workspaces **1. Go to Workspace Settings** Navigate to the customer workspace → **IAM** → **Users & Groups** **2. Click Add Group** Click **Add Group** **3. Select Organization Group** Choose the group from your organization **4. Assign Role** Select the workspace role for all group members **5. Save** Click **Save** to apply > [!TIP] > > **Best Practice:** Create groups at the organization level and assign them to workspaces. This way, when you add a new team member to a group, they automatically get access to all workspaces that group is assigned to. *** ## Recommended Default Groups Setting up default groups during initial configuration saves time and ensures consistent access patterns. ### Suggested Partner Groups | Group Name | Description | Suggested Workspace Role | | - | - | - | | **SOC Tier 1** | Front-line analysts handling initial triage | Incident Analyst | | **SOC Tier 2** | Senior analysts with response capabilities | Incident Responder | | **SOC Managers** | Team leads overseeing operations | Owner | | **Detection Engineers** | Staff managing analytic rules and content | Content Admin | | **Account Managers** | Customer relationship managers | Workspace Reader | ### Setting Up Default Groups **1. Create Groups First** Before onboarding customers, create your standard groups at the organization level **2. Add Team Members** Add your team members to the appropriate groups **3. Document Group Purposes** Document what each group is for and what role it should receive **4. Apply to New Workspaces** When onboarding new customers, assign these groups with consistent roles > [!NOTE] > > **Pro Tip:** Create a simple spreadsheet mapping your groups to workspace roles. This becomes your "template" for onboarding new customers and ensures consistency. *** ## Common Permission Scenarios ### Scenario 1: New SOC Analyst Joining Your Team **Goal:** Add a new analyst who needs to handle incidents for all customers. **1. Create User at Organization Level** Settings → User Management → Add User → Enter email → Save **2. Add to SOC Group** Add user to your "SOC Tier 1" or appropriate group **3. Verify Workspace Access** The user automatically inherits access to all workspaces the group is assigned to ### Scenario 2: Customer Wants to View Their Incidents **Goal:** Give a customer's security team read-only access to their workspace. **1. Go to Customer Workspace** Workspaces → Select Customer → IAM **2. Add Customer User** Users & Groups → Add User → Enter customer email **3. Assign Reader Role** Select "Workspace Reader" role for read-only access ### Scenario 3: Partner User Can't Access a Workspace **Goal:** Troubleshoot why a partner user can't see a specific customer workspace. **1. Check Organization Membership** Verify the user exists in Settings → User Management **2. Check Group Membership** Verify the user is in a group that has workspace access **3. Check Workspace Assignment** Go to the workspace settings and verify the user or their group is listed **4. Check Role Assignment** Ensure a workspace role is assigned (not just added to the workspace) > [!NOTE] > > Opening a workspace needs a workspace role there, unless the user is an Org Admin or Workspace Admin. Other users see a workspace in the Workspaces list only once they hold a role on it. Group roles can take a few minutes to apply. ### Scenario 4: User Has Wrong Permissions **Goal:** User can work incidents but can't run Gamebooks or response actions. **Cause:** User has "Incident Analyst" role (which can only request approval to run Gamebooks) instead of "Incident Responder." **1. Go to Workspace Settings** Navigate to the affected workspace **2. Find the User or Group** Locate in Users & Groups **3. Update Role** Change role from Incident Analyst to Incident Responder **4. Save Changes** Click Save to apply *** ## Workspace Roles Reference | Role | View Incidents | Work Incidents | Run Gamebooks | Configure Modules | Manage Users | | - | :-: | :-: | :-: | :-: | :-: | | **Owner** | ✓ | ✓ | ✓ | ✓ | ✓ | | **Content Admin** | ✓ | ✓ | Request approval | Add modules only | — | | **Incident Responder** | ✓ | ✓ | ✓ | — | — | | **Incident Analyst** | ✓ | ✓ | Request approval | — | — | | **Workspace Reader** | ✓ | — | — | — | — | > **[Full Roles Reference](/guides/general-support/roles-and-permissions-reference)** > > View complete permissions for all roles *** ## Troubleshooting ### Common Issues | Issue | Cause | Solution | | - | - | - | | **User can't see any workspaces** | Not assigned to any workspace | Add user/group to workspaces in workspace settings | | **User can see workspace but can't do anything** | No role assigned | Assign a workspace role to the user or their group | | **"You do not have access to this workspace"** | No workspace role there | Assign a workspace role to the user or their group, or make them an Org Admin or Workspace Admin | | **User can't add modules** | Insufficient role | User needs the Owner role | | **Can't add users to workspace** | Not a workspace Owner | Need the Owner role on that workspace, or an Org Admin or Workspace Admin | | **Group changes not reflected** | Caching | Refresh browser; changes may take a few minutes | | **Customer user sees other customers' data** | Added at wrong level | Remove from org level, add only at workspace level | ### Permission Troubleshooting Flow ```mermaid theme={null} flowchart TD A[User Can't Access Something] --> B{Is user in Organization?} B -->|No| C[Add user to Organization] B -->|Yes| D{Is user assigned to Workspace?} D -->|No| E[Add user/group to Workspace] D -->|Yes| F{Does user have correct Role?} F -->|No| G[Update workspace role] F -->|Yes| H[Check module-specific permissions] C --> D E --> F G --> I[Issue Resolved] H --> I ``` *** ## Best Practices > **Create groups before onboarding customers** > > Set up your standard groups (SOC Tier 1, Tier 2, Managers, etc.) before onboarding any customers. This creates a consistent template to follow. > **Use groups instead of individual user assignments** > > Assigning groups to workspaces instead of individual users makes it much easier to onboard new team members—just add them to the appropriate group. > **Document your group-to-role mappings** > > Create a simple reference document showing which groups get which roles. This ensures consistency across all customer onboardings. > **Keep customer users at the workspace level only** > > Never add customer users at the organization level unless they need cross-workspace access. This prevents accidental data exposure. > **Use consistent naming conventions** > > Name groups clearly (e.g., "SOC-Tier1-Analysts" not "Group1") so anyone can understand their purpose. > **Audit permissions periodically** > > Review user and group assignments quarterly to remove departed employees and ensure permissions are still appropriate. > **Test with a non-admin account** > > After setting up permissions, test access with a non-admin account to verify users see what they should see. *** ## Onboarding Checklist Use this checklist when onboarding a new customer workspace: ### Pre-Onboarding (One-Time Setup) * Create standard organization groups (SOC Tier 1, Tier 2, etc.) * Add your team members to appropriate groups * Document group-to-role mappings ### Per-Customer Onboarding * Create/configure customer workspace * Assign organization groups to workspace with appropriate roles * Verify partner team can access the workspace * Add customer users at workspace level (if needed) * Create customer-specific groups (if needed) * Test access with a non-admin account * Document any customer-specific permission requirements *** ## Frequently Asked Questions > **Why are there two places to manage users?** > > The two locations serve different purposes: Organization Settings manages your partner team (who may need access to multiple customers), while Workspace Settings manages access to a specific customer (including customer users who should only see their own data). > **Can a customer user see other customers' data?** > > Not if set up correctly. Customer users should only be added at the workspace level, not at the organization level. This ensures they can only see their own workspace. > **What's the fastest way to give a new analyst access to all customers?** > > Add them to an organization group that's already assigned to all customer workspaces. They'll inherit access automatically. > **Can I have different roles for the same user in different workspaces?** > > Yes. A user might be an Owner in one workspace and an Incident Responder in another. Roles are assigned per-workspace. > **What happens if I remove a user from a group?** > > They lose access to all workspaces that group was assigned to (unless they have individual access or belong to another group with access). > **Can customers manage their own users?** > > Yes, if you give them the Owner role on their workspace. They can then add/remove users within their workspace only. *** ## Related Guides > **[Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > Complete permissions for each role > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Managing customer workspaces > **[Onboarding Overview](/guides/onboarding/platform-onboarding)** > > Full onboarding process > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Cross-workspace management *** > [!NOTE] > > Questions about user and group management? Contact us at [support@contraforce.com](mailto:support@contraforce.com) or request hands-on onboarding support for your first few customer deployments. # Onboarding Admin Roles and App Permissions Source: https://docs.contraforce.com/guides/onboarding/workspace-onboarding See which Microsoft Entra roles can grant ContraForce admin consent, when you need Subscription Owner, and the permissions each enterprise app requests. Before ContraForce can protect your organization, specific Microsoft Entra ID permissions must be granted to enable secure communication between ContraForce services and your Microsoft environment. This article explains the enterprise applications deployed during onboarding and the permissions each requires. ## Getting Started > [!NOTE] > > **ContraForce Portal:** [portal.contraforce.com](https://portal.contraforce.com) ### Required Roles for Onboarding To complete the ContraForce onboarding process and consent to the required enterprise applications, the following roles must be assigned to the user performing the onboarding: | Role | Purpose | | - | - | | **Microsoft Entra admin role** | The two core consents (ContraForce API and Portal) accept Global Administrator, Privileged Role Administrator, Application Administrator, or Cloud Application Administrator. Connecting a security **module** is stricter and needs Global Administrator or Privileged Role Administrator — see the consent model note below. | | **Subscription Owner** | Required only for Microsoft Sentinel onboarding and Agent Center/agent deployment. Not needed for XDR-only module. | > [!WARNING] > > If your organization separates these roles across different users, coordinate with both administrators to complete the onboarding process. > [!WARNING] > > **Consent model.** Security **modules** (Microsoft Defender XDR, the Microsoft response modules, and the Sentinel Hunting add-on) are consented with **application (app-only)** Microsoft Graph permissions. Entra grants those only to a **Global Administrator** or a **Privileged Role Administrator** — Application Administrator and Cloud Application Administrator can complete delegated consent but reach "approval required" on application permissions. The role is required for the one-time consent only and is not retained; activate it just-in-time with Privileged Identity Management (PIM) and deactivate afterward. > > The two core consents (ContraForce API and Portal) are less restrictive and additionally accept Application Administrator and Cloud Application Administrator. > > Because actions run as the application (no signed-in user required), operator control is enforced through **Gamebook approval gates** — only Workspace Owners can approve high-impact actions — and a complete **audit trail** in the Gamebooks History page. ## Overview of ContraForce Enterprise Applications ContraForce uses a modular application architecture designed around the principle of least privilege. Rather than requesting all permissions through a single application, ContraForce distributes responsibilities across purpose-built enterprise applications. This approach ensures that each application only receives the permissions necessary for its specific function. When you onboard with ContraForce, the following enterprise applications are registered in your Microsoft Entra tenant: | Application | Primary Function | | - | - | | ContraForce API | Core API services and Azure resource management | | ContraForce Portal | User authentication and profile management | | ContraForce Sentinel Hunting | Log Analytics queries and incident evidence retrieval | | ContraForce for MDE | Microsoft Defender for Endpoint visibility and management | | ContraForce Gamebooks for Identity | Identity-based automated response actions | | ContraForce Gamebooks for MDE | Endpoint-based automated response actions | ## Onboarding Consent Flow ### Initial Registration 1. Navigate to [portal.contraforce.com](https://portal.contraforce.com) 2. Click **Register with Microsoft** 3. Sign in with your Microsoft Work account (needs Global Administrator, Privileged Role Administrator, Application Administrator, or Cloud Application Administrator to grant the two core consents; Subscription Owner also needed for Sentinel and Agent Center) 4. Consent to the **ContraForce API** permissions 5. Consent to the **ContraForce Portal** permissions The **ContraForce API** and **ContraForce Portal** consents appear as two separate Microsoft consent prompts. After these core app consents are granted, you configure module-specific permissions per workspace from the **Modules** tab. ### Additional Permissions After initial onboarding, additional enterprise application permissions can be configured from each module's page under **Workspaces → \[workspace] → Modules** in the ContraForce portal based on the features your organization requires. ## Enterprise Application Details ### ContraForce API The ContraForce API is the core service principal that enables communication between ContraForce services and Microsoft APIs including Microsoft Graph and Azure Resource Manager. > **View ContraForce API Permissions** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `offline_access` | Delegated | No | Enables refresh token acquisition for persistent sessions | > | `openid` | Delegated | No | Allows sign-in using OpenID Connect | > | `profile` | Delegated | No | Retrieves signed-in user's name and object ID | > | `Application.Read.All` | Delegated | Yes | Evaluates which ContraForce service principals have been consented | > | `RoleManagement.Read.Directory` | Delegated | Yes | Evaluates user roles for Portal access control | > | `User.Read.All` | Delegated | Yes | Reads user profile data for user management operations | > | `user_impersonation` (Azure Service Management) | Delegated | No | Used throughout platform operation, not only at onboarding: backs Microsoft Sentinel access; enumeration of subscriptions, resource groups, and identity role assignments; and, with AI Agents, reading model capacities and quotas and pushing agent model and harness updates | ### ContraForce Portal The ContraForce Portal service principal handles user authentication through Microsoft's OpenID Connect implementation and retrieves basic profile information for signed-in users. > **View ContraForce Portal Permissions** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `offline_access` | Delegated | No | Enables refresh token acquisition | > | `openid` | Delegated | No | Allows sign-in using OpenID Connect | > | `profile` | Delegated | No | Retrieves signed-in user's name and object ID | ### ContraForce Sentinel Hunting This service principal enables direct queries to your Microsoft Sentinel workspace for incident investigation and advanced hunting capabilities. > **View ContraForce Sentinel Hunting Permissions** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `Data.Read` (Log Analytics) | Delegated | No | Queries Log Analytics workspace data for incident evidence and advanced hunting | ### ContraForce for MDE This service principal provides visibility into Microsoft Defender for Endpoint data, enabling endpoint monitoring and threat intelligence display in the ContraForce portal. > **View ContraForce for MDE Permissions** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `ThreatHunting.Read.All` | Delegated | Yes | Enables threat hunting queries | > | `SecurityAlert.Read.All` | Delegated | Yes | Displays Microsoft Graph Security alerts | > | `SecurityIncident.Read.All` | Delegated | Yes | Displays Microsoft Graph Security incidents | > | `SecurityIncident.ReadWrite.All` | Delegated | Yes | Manages Microsoft Graph Security incidents | > | `Incident.Read` (Microsoft Threat Protection) | Delegated | Yes | Reads threat protection incidents | > | `Incident.ReadWrite` (Microsoft Threat Protection) | Delegated | Yes | Manages threat protection incidents | > | `AdvancedQuery.Read` (WindowsDefenderATP) | Delegated | Yes | Queries raw event and incident data | > | `Alert.Read` (WindowsDefenderATP) | Delegated | Yes | Displays Defender alerts | > | `Machine.Read` (WindowsDefenderATP) | Delegated | Yes | Retrieves endpoint profile details | > | `Score.Read` (WindowsDefenderATP) | Delegated | Yes | Displays Threat and Vulnerability Management scores | > | `Vulnerability.Read` (WindowsDefenderATP) | Delegated | Yes | Displays vulnerability information | ### ContraForce Gamebooks for Identity This service principal enables automated response actions targeting user entities, including session invalidation, account lockout, and password reset capabilities. > **View ContraForce Gamebooks for Identity Permissions** > > **Delegated Permissions (on-behalf-of flows)** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `User.ReadWrite.All` | Delegated | Yes | Invalidates user sessions and locks accounts | > | `User.AuthenticationMethod.ReadWrite.All` | Delegated | Yes | Resets user passwords | > | `User.ManagedIdentities.All` | Delegated | Yes | Manages user identities | > | `UserAuthenticationMethod.ReadWrite` | Delegated | Yes | Resets user passwords | > > **Application Permissions (Default)** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `User.ReadWrite.All` | Application | Yes | Enables automated session invalidation and account lockout without user presence | > > > [!NOTE] > > > > Application permissions allow ContraForce to execute Gamebook actions without requiring a service provider user to be signed in. Password reset runs on-behalf-of (delegated) by default; enabling the optional **service-provider password reset** add-on lets it run app-only via a customer-consented permission and an Authentication Administrator directory role. See the [Enterprise Applications Reference](/guides/technical/enterprise-applications#contraforce-gamebooks-for-identity). ### ContraForce Gamebooks for MDE This service principal enables automated response actions targeting endpoint entities, including device isolation, antivirus scans, and file quarantine operations. > **View ContraForce Gamebooks for MDE Permissions** > > **Delegated Permissions (on-behalf-of flows)** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `Machine.Isolate` | Delegated | Yes | Isolates endpoints from the network | > | `Machine.Offboard` | Delegated | Yes | Offboards endpoints from Defender | > | `Machine.Scan` | Delegated | Yes | Initiates Microsoft Defender Antivirus scans | > | `Machine.StopAndQuarantine` | Delegated | Yes | Stops file execution and quarantines malicious files | > | `Alert.ReadWrite` | Delegated | Yes | Reads and writes Defender alerts | > > **Application Permissions (Default)** > > | Permission | Type | Admin Consent | Purpose | > | - | - | - | - | > | `Machine.Isolate` | Application | Yes | Isolates endpoints without user presence | > | `Machine.Scan` | Application | Yes | Initiates scans without user presence | > | `Machine.StopAndQuarantine` | Application | Yes | Quarantines files without user presence | > > > [!NOTE] > > > > Application permissions enable service providers to execute endpoint response actions in customer tenants without requiring a user to be actively signed in. ## Why This Architecture? ContraForce's modular application architecture provides several benefits: * **Principle of Least Privilege** — Each application only requests the permissions necessary for its specific function * **Granular Control** — Organizations can enable only the features they need without granting unnecessary permissions * **Reduced Friction** — Service providers can onboard customers incrementally based on their security maturity * **Improved Security Posture** — Limiting permissions reduces potential attack surface ## Managing Permissions After onboarding, you can review and manage ContraForce enterprise application permissions in two locations: 1. **ContraForce Portal:** Review core app consent under **Settings → Enterprise Apps**, and consent module apps from **Workspaces → \[workspace] → Modules** 2. **Microsoft Entra Admin Center:** Review enterprise applications and their granted permissions under **Enterprise Applications** To verify the granted permissions with read-only PowerShell or Python scripts, see [Auditing Enterprise App Permissions](/guides/technical/auditing-enterprise-app-permissions). > [!TIP] > > For questions about specific permissions or to request changes to your ContraForce configuration, contact your ContraForce support: [support@contraforce.com](mailto:support@contraforce.com). *** ## Related Guides > **[Platform Permissions & Consent](/guides/getting-started/platform-permissions-and-consent)** > > Which Microsoft Entra ID apps ContraForce uses and which admin roles can grant consent > **[Enterprise Applications](/guides/technical/enterprise-applications)** > > App IDs, permissions, and admin consent needs for every ContraForce enterprise app > **[Audit Permissions](/guides/technical/auditing-enterprise-app-permissions)** > > Check granted permissions with read-only PowerShell or Python scripts > **[Offboarding Procedure](/guides/general-support/offboarding-contra-force)** > > Remove ContraForce enterprise apps, Azure resources, and role assignments *** > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Workspace Onboarding Verification Checklist Source: https://docs.contraforce.com/guides/onboarding/workspace-onboarding-checklist Verify a newly onboarded customer workspace before go-live: check module connections, incident sync, Gamebook actions, and Microsoft Sentinel setup. A focused verification runbook to run **after a customer admin finishes onboarding their workspace**. Use it to confirm every part of the deployment is healthy before declaring the workspace go-live. > [!NOTE] > > **Who is this for?** > > Service-provider operations and onboarding leads verifying a freshly onboarded customer workspace. For the steps that come before this point (pre-onboarding the customer, the customer's own onboarding journey), see: > **[Part 1: MSP Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Pre-onboard the customer workspace > **[Part 2: Customer Workspace Onboarding](/guides/onboarding/customer-workspace-onboarding)** > > What the customer admin sees on their side *** ## Core Verification Run these checks first. Any failure here blocks go-live. * The customer workspace shows **Active** status (not **Pending customer setup**) in your Workspace Center * You received the **Customer onboarding complete** real-time notification in the portal * Open the customer's workspace and confirm every pre-selected module shows **Connected** * Navigate to the **Command Dashboard** filtered to the customer workspace and verify incidents appear (allow 5 to 15 minutes for initial sync) * On the workspace's **Environments** tab, confirm endpoints are onboarded and licenses are in place ([Workspace Environments](/guides/getting-started/workspace-environments)) * Open an incident and confirm the **Workbench** loads with entity context and timeline * Verify Gamebook response actions appear on incident entities (do not execute on production entities) > [!WARNING] > > **Don't test response actions on production entities.** Gamebook actions like "Isolate Device" or "Disable User" execute immediately. Use a test account or device if you want to verify functionality. *** ## Sentinel-Specific Verification Skip this section if the customer is on Defender-only. * Sentinel incidents are syncing alongside Defender for Endpoint incidents * Azure Lighthouse delegation completed successfully in the customer's subscription * Supporting Azure infrastructure deployed by Sentinel consent shows **Active** * Open the workspace's **Content Management System** (flask icon on the Microsoft Sentinel module) and confirm its analytics rules load * Log search is functional > [!NOTE] > > Sentinel Azure infrastructure is provisioned in the background after the customer grants Sentinel consent. If verification fails, allow 5 to 10 extra minutes for the deployment to complete before retrying. *** ## If Something Fails | Symptom | Likely cause | Where to look | | - | - | - | | Workspace stuck in **Pending customer setup** | Customer hasn't finished consenting their modules | Resend the invite or contact the POC | | Module shows **Not Connected** in the customer's view | Consent skipped or denied | Customer clicks **Consent** on the module from their workspace's **Modules** tab ([Step 2: Consent to Your Modules](/guides/onboarding/customer-workspace-onboarding#step-2-consent-to-your-modules)) | | No incidents appearing after 30 minutes | No active incidents in source system | Check Defender, Sentinel, or CrowdStrike console for existing incidents | | Sentinel infrastructure didn't deploy | Insufficient Azure permissions | Verify customer admin has Subscription Owner | | Gamebook actions unavailable on entities | Response module not connected | Customer reconnects the response module from their Modules tab | For sign-in failures encountered by the customer admin, point them to the [Customer onboarding sign-in failed troubleshooting](/guides/onboarding/customer-workspace-onboarding#troubleshooting-sign-in-failed). *** ## After Verification Passes Two follow-ups close out the onboarding. ### Assign your team to the workspace Use organization-level groups rather than individual users so future onboardings are consistent. | Role | Best for | | - | - | | Owner | Team leads, workspace owners | | Incident Responder | SOC analysts who need response capabilities | | Incident Analyst | Junior analysts who work incidents and request approval to run Gamebooks | | Workspace Reader | Stakeholders who need read-only access | | Content Admin | Detection engineers (Sentinel only) | > **[User & Group Management](/guides/general-support/user-group-management)** > > Detailed user and group setup, including organization-level groups ### Configure notifications (Sentinel only) > **[Notifications Configuration](/guides/technical/notifications-configuration)** > > Severity filters, distribution group setup, and test notification verification *** ## Go-Live Communication * Notify the customer that ContraForce is live on their environment * Share relevant documentation links with the customer team * Confirm the customer knows how to reach your delivery team * Document any customer-specific configuration notes or permission exceptions * Schedule a follow-up check-in within 7 days to review initial incident volume and rule tuning *** ## Related Guides > **[Workspace Environments](/guides/getting-started/workspace-environments)** > > Review a workspace's endpoints and licenses and which response actions each connection supports > **[Onboarding Workspaces](/onboarding-customer-workspaces)** > > What service providers and customer admins each need, and how to confirm go-live > **[SLA Tracking](/guides/getting-started/sla-tracking)** > > Set incident SLA targets per workspace and track first response and time to resolution > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Manage workspace settings, modules, and access *** > [!NOTE] > > **Need help?** Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Auditing Enterprise App Permissions Source: https://docs.contraforce.com/guides/technical/auditing-enterprise-app-permissions Audit the permissions granted to ContraForce enterprise apps in Microsoft Entra ID with read-only PowerShell or Python scripts, including GCC High and DoD. > [!NOTE] > > **Who is this for?** IT administrators, security teams, and change advisory board (CAB) reviewers who need to independently verify the permissions granted to ContraForce enterprise applications before or after onboarding. ## Choose a Script ContraForce provides two audit scripts that enumerate the permissions granted to ContraForce enterprise applications in your Microsoft Entra ID tenant. Both scripts produce an identical JSON output that you can compare against the [Enterprise Applications Reference](/guides/technical/enterprise-applications) to verify that only the documented permissions are in place. Choose the script that fits your environment: | | PowerShell | Python | | - | - | - | | **Best for** | Microsoft-native environments | Cross-platform / CLI-first teams | | **Runtime** | PowerShell 7.0+ (`pwsh`) | Python 3.10+ | | **Auth method** | Microsoft Graph PowerShell SDK | Azure CLI (`az login`) | | **Dependencies** | `Microsoft.Graph` modules (Microsoft-published) | `azure-identity` (Microsoft-published) + `httpx` | | **Government cloud** | `-Cloud AzureUSGovernment` | `-c AzureUSGovernment` | > [!WARNING] > > These scripts are **read-only**. They do not create, modify, or delete any objects in your tenant. All API calls are HTTP `GET` requests to Microsoft Graph. ## What the Scripts Access Both scripts make read-only queries to the Microsoft Graph REST API. The specific endpoint depends on your cloud environment: | Environment | Graph API Base | Identity Platform | | - | - | - | | Commercial / GCC | `https://graph.microsoft.com/v1.0` | `https://login.microsoftonline.com` | | GCC High / DoD | `https://graph.microsoft.us/v1.0` | `https://login.microsoftonline.us` | No other endpoints are contacted beyond the Microsoft identity platform for token acquisition. | Graph API Endpoint | Purpose | | - | - | | `GET /me` | Resolve the authenticated operator's identity (UPN and object ID) | | `GET /organization` | Resolve the tenant ID | | `GET /servicePrincipals` | Look up ContraForce and Microsoft resource API service principals by name or app ID | | `GET /servicePrincipals/{id}/oauth2PermissionGrants` | Read delegated permission grants for each application | | `GET /servicePrincipals/{id}/appRoleAssignments` | Read application permission assignments for each application | ### Data in the Output File The output JSON contains: * **Application names and app IDs** for each ContraForce enterprise application * **Permission names and descriptions** resolved to human-readable values * **The resource API** each permission targets (Microsoft Graph, WindowsDefenderATP, etc.) * **Metadata**: timestamp, tenant ID, cloud environment, authenticated operator, and tool version The output does not contain secrets, tokens, or user data beyond the operator identifier. In government cloud environments, the operator's UPN is automatically redacted and replaced with their Entra object ID (an opaque GUID). See [Output File Access Control](#output-file-access-control) for handling guidance. ## Directory Role Assignments The scripts on this page report **Microsoft Graph permission grants** — delegated (`oauth2PermissionGrants`) and application (`appRoleAssignments`). They do **not** enumerate **Entra directory role** memberships, which are a separate authorization mechanism that Graph permission audits do not surface. One ContraForce capability uses a directory role. If you enable the optional **service-provider password reset** add-on on the Identity module, the **ContraForce Gamebooks for Identity** service principal is assigned the **Authentication Administrator** role so the Reset Password Gamebook can run app-only (see the [Enterprise Applications Reference](/guides/technical/enterprise-applications#contraforce-gamebooks-for-identity)). Review that assignment directly with the same read-only access the audit scripts already use (`Directory.Read.All`): ```powershell PowerShell theme={null} # Connect-MgGraph -Scopes "Directory.Read.All" # Commercial app ID shown; government environments use a different ID (contact support). $sp = Get-MgServicePrincipal -Filter "appId eq '36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a'" Get-MgRoleManagementDirectoryRoleAssignment -Filter "principalId eq '$($sp.Id)'" | ForEach-Object { $def = Get-MgRoleManagementDirectoryRoleDefinition -UnifiedRoleDefinitionId $_.RoleDefinitionId [pscustomobject]@{ ServicePrincipal = $sp.DisplayName; Role = $def.DisplayName } } ``` ```bash Graph API theme={null} # Requires Directory.Read.All. Resolve the service principal object id, then its role assignments. GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a')?$select=id GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId eq ''&$expand=roleDefinition ``` An empty result means the add-on is not enabled (or has been turned off). When it is enabled, the expected assignment is **Authentication Administrator** — a role scoped to non-administrator users that cannot reset passwords for Global Administrators or other higher-privileged roles. ## Applications Audited In **commercial (AzureCloud)** environments, both scripts use built-in app IDs that match the [Quick Reference](/guides/technical/enterprise-applications#quick-reference) table: | Application | App ID | | - | - | | ContraForce API | `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` | | ContraForce Portal | `8b7cb435-9526-47ee-b79a-34433f0daad2` | | ContraForce for MDE | `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` | | ContraForce Gamebooks for MDE | `ad7b0e79-3c37-4408-bf8f-eb89522cc920` | | ContraForce Gamebooks for Identity | `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` | | ContraForce Gamebooks for Email | `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` | | ContraForce Sentinel Hunting | `6bf1c74d-7ade-4671-a507-166936f89a1f` | You can verify these app IDs in the **Microsoft Entra Admin Center** under **Enterprise Applications** before running the scripts. > [!WARNING] > > **Government cloud environments** use different app IDs. Contact [support@contraforce.com](mailto:support@contraforce.com) to obtain the app IDs for your environment. Pass them to the script via `-AppsFile` (PowerShell) or `--apps-file` (Python) — a JSON file containing an array of objects with `Name`/`AppId` (PowerShell) or `name`/`app_id` (Python) fields. ## Prerequisites **PowerShell** **Runtime:** [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) (`pwsh`, not Windows PowerShell 5.1) **Microsoft Graph modules:** ```powershell theme={null} Install-Module Microsoft.Graph.Authentication, Microsoft.Graph.Applications -Scope CurrentUser ``` **Required Graph scopes:** `Application.Read.All` and `Directory.Read.All` **Authenticate before running:** ```powershell theme={null} # Commercial / GCC (-Cloud AzureCloud, the default) Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" # GCC High (-Cloud AzureUSGovernment) Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" -Environment USGov # DoD (-Cloud AzureUSGovernment) Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" -Environment USGovDoD ``` For environments without a browser, use device code flow: ```powershell theme={null} Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" -UseDeviceCode ``` **Python** **Runtime:** [Python 3.10+](https://devguide.python.org/versions/) (older versions will produce a clear error message) **Azure CLI:** [Install the Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) and sign in: ```bash theme={null} # Commercial / GCC az login # GCC High / DoD az cloud set --name AzureUSGovernment az login ``` **Python packages:** ```bash theme={null} pip install azure-identity httpx ``` The script uses `AzureCliCredential` from the Microsoft-published `azure-identity` library, which reuses your existing `az login` session. The `httpx` library handles HTTP communication with the Graph API. > [!TIP] > > For stricter environments, pin exact versions: `pip install azure-identity==1.19.0 httpx==0.28.1`. If your organization uses an internal package mirror, install from that source instead of public PyPI. ### Minimum Permissions The account running the script needs read access to service principals and their permission grants. The minimum Microsoft Entra ID role is **Directory Reader**, or you can grant the following Microsoft Graph API permissions directly: | Graph Permission | Type | Purpose | | - | - | - | | `Application.Read.All` | Delegated | Read service principal properties and app roles | | `Directory.Read.All` | Delegated | Read delegated permission grants and role assignments | These are **read-only** permissions. They do not grant the ability to modify applications, permissions, or any other tenant objects. ## Running the Scripts **PowerShell** ```powershell theme={null} # Commercial (default) pwsh -File Audit-EnterpriseApps.ps1 # Custom output path pwsh -File Audit-EnterpriseApps.ps1 -OutputPath ./audit-2026-02-12.json # Government (GCC High / DoD) — requires -AppsFile pwsh -File Audit-EnterpriseApps.ps1 -Cloud AzureUSGovernment -AppsFile ./gov-apps.json ``` The `-Cloud` parameter value must match the cloud you authenticated to with `Connect-MgGraph -Environment`. The script validates this and exits with an error if there is a mismatch. Government environments require `-AppsFile` because app IDs differ from commercial. **Python** ```bash theme={null} # Commercial (default) python audit_enterprise_apps.py # Custom output path python audit_enterprise_apps.py -o audit-2026-02-12.json # Government (GCC High / DoD) — requires --apps-file python audit_enterprise_apps.py -c AzureUSGovernment -a gov-apps.json ``` The `-c` flag must match the Azure CLI cloud set via `az cloud set --name`. Government environments require `az cloud set --name AzureUSGovernment` before `az login` and `--apps-file` (`-a`) because app IDs differ from commercial. Both scripts display progress as they resolve permissions and will report a summary when complete. A **non-zero exit code** means one or more applications were not found in the tenant — this is expected if you haven't consented all ContraForce applications (for example, Sentinel Hunting is only required for XDR + SIEM deployments). ## Government Cloud Environments (GCC High / DoD) Both scripts support Microsoft Azure Government cloud environments used by public sector organizations subject to CMMC, FedRAMP, or ITAR requirements. Both scripts use the same `-Cloud` / `-c` parameter values, which match the `az cloud set --name` values: | Cloud | Value | PowerShell | Python | | - | - | - | - | | Commercial (default) | `AzureCloud` | `-Cloud AzureCloud` | `-c AzureCloud` | | Government (GCC High / DoD) | `AzureUSGovernment` | `-Cloud AzureUSGovernment` | `-c AzureUSGovernment` | When running in a government cloud environment, the scripts automatically: 1. **Use the correct Graph endpoint** — `graph.microsoft.us` instead of `graph.microsoft.com` 2. **Redact the operator's UPN** — Records the Entra object ID (an opaque GUID) instead of the User Principal Name in the `generatedBy` metadata field 3. **Restrict output file permissions** — Limits file access to the current user only (PowerShell: Windows ACL; Python: POSIX `chmod 600`) You can also redact the UPN in commercial environments using the `-RedactUPN` switch (PowerShell) or `--redact-upn` flag (Python). > [!WARNING] > > The script validates that the connected session matches the requested cloud environment. If you specify `-Cloud AzureUSGovernment` but are connected to a commercial Graph session, the script will exit with an error and instructions to reconnect. ## Audit Scripts ```powershell Audit-EnterpriseApps.ps1 icon="terminal" expandable theme={null} #Requires -Version 7.0 #Requires -Modules Microsoft.Graph.Authentication, Microsoft.Graph.Applications <# .SYNOPSIS Audits ContraForce enterprise application permissions in the current Microsoft Entra ID tenant. .DESCRIPTION Queries Microsoft Graph for all documented ContraForce enterprise applications, resolves their delegated and application permissions to human-readable names, and outputs a structured JSON file suitable for diffing against documentation. Supports Commercial, GCC High, and DoD cloud environments. Requires: - Microsoft.Graph PowerShell modules: Install-Module Microsoft.Graph.Applications -Scope CurrentUser - An authenticated Microsoft Graph session with Directory.Read.All: Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All" -Environment USGov - The target tenant must have the ContraForce enterprise applications consented .PARAMETER OutputPath Path for the output JSON file. Defaults to enterprise-apps-audit.json in the current directory. .PARAMETER Cloud The Microsoft cloud environment to audit. Uses the same values as 'az cloud set --name': AzureCloud (Commercial) or AzureUSGovernment (GCC High / DoD). Defaults to AzureCloud. .PARAMETER AppsFile Path to a JSON file listing the applications to audit. Each entry must have 'Name' and 'AppId' fields. Required for government cloud environments where app IDs differ from commercial. Contact support@contraforce.com for your environment's app IDs. .PARAMETER RedactUPN When set, records the operator's Entra object ID instead of the User Principal Name in the generatedBy metadata field. Automatically enabled for AzureUSGovernment to avoid recording PII in audit artifacts. .EXAMPLE pwsh -File Audit-EnterpriseApps.ps1 pwsh -File Audit-EnterpriseApps.ps1 -OutputPath ./audit-2026-02-12.json pwsh -File Audit-EnterpriseApps.ps1 -Cloud AzureUSGovernment -AppsFile ./gov-apps.json -OutputPath ./audit-gov.json #> param( [string]$OutputPath = "enterprise-apps-audit.json", [ValidateSet("AzureCloud", "AzureUSGovernment")] [string]$Cloud = "AzureCloud", [string]$AppsFile, [switch]$RedactUPN ) $ErrorActionPreference = "Stop" # ── Cloud environment metadata ─────────────────────────────────────────────── $EnvironmentNames = @{ "AzureCloud" = "Commercial" "AzureUSGovernment" = "US Government (GCC High / DoD)" } # Maps our -Cloud parameter values to the Connect-MgGraph -Environment values # that Microsoft Graph PowerShell SDK uses internally. GCC High uses "USGov" # and DoD uses "USGovDoD" — both map to our single "AzureUSGovernment" value. $ValidMgEnvironments = @{ "AzureCloud" = @("Global") "AzureUSGovernment" = @("USGov", "USGovDoD") } # ── Pre-flight: verify Microsoft Graph authentication ───────────────────────── $context = Get-MgContext if (-not $context) { $suggestedEnv = $ValidMgEnvironments[$Cloud][0] $envFlag = if ($Cloud -ne "AzureCloud") { " -Environment $suggestedEnv" } else { "" } Write-Error ("No active Microsoft Graph session. Connect first:`n" + " Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All'$envFlag`n" + " Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All'$envFlag -UseDeviceCode") exit 1 } # Validate the connected environment matches the requested one. # Connect-MgGraph -Environment uses "Global", "USGov", "USGovDoD" internally, # so we check against the valid set for the -Cloud value the operator chose. if ($context.Environment -notin $ValidMgEnvironments[$Cloud]) { $validList = $ValidMgEnvironments[$Cloud] -join "' or '" Write-Error ("Environment mismatch: connected to '$($context.Environment)' " + "but -Cloud '$Cloud' expects '$validList'.`n" + "Disconnect and reconnect to the correct environment:`n" + " Disconnect-MgGraph`n" + " Connect-MgGraph -Scopes 'Application.Read.All','Directory.Read.All' -Environment $($ValidMgEnvironments[$Cloud][0])") exit 1 } # Resolve operator identity via Graph API (avoids parsing access tokens) $meResponse = Invoke-MgGraphRequest -Uri '/me?$select=id,userPrincipalName' -Method GET $operatorOid = $meResponse.id $operatorUpn = $meResponse.userPrincipalName # Auto-enable UPN redaction for government environments $effectiveRedact = $RedactUPN.IsPresent -or ($Cloud -ne "AzureCloud") $generatedBy = if ($effectiveRedact) { $operatorOid } else { $operatorUpn } $envDisplayName = $EnvironmentNames[$Cloud] Write-Host "Environment: $envDisplayName ($Cloud)" -ForegroundColor Green Write-Host "Authenticated as: $generatedBy (Tenant: $($context.TenantId))" -ForegroundColor Green # ── ContraForce enterprise applications to audit ────────────────────────────── # App IDs differ by cloud environment. The commercial IDs are built-in; # government cloud app IDs are provided by ContraForce upon request and # passed via -AppsFile. if ($AppsFile) { $AppsToAudit = Get-Content $AppsFile -Raw | ConvertFrom-Json } elseif ($Cloud -eq "AzureCloud") { $AppsToAudit = @( @{ Name = "ContraForce API"; AppId = "24d97bc0-8f2b-45d5-8e0b-7fe286732ef2" } @{ Name = "ContraForce Portal"; AppId = "8b7cb435-9526-47ee-b79a-34433f0daad2" } @{ Name = "ContraForce for MDE"; AppId = "6efccc6a-f0d3-49e5-92d0-17d4afa9ba52" } @{ Name = "ContraForce Gamebooks for MDE"; AppId = "ad7b0e79-3c37-4408-bf8f-eb89522cc920" } @{ Name = "ContraForce Gamebooks for Identity"; AppId = "36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a" } @{ Name = "ContraForce Gamebooks for Email"; AppId = "44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d" } @{ Name = "ContraForce Sentinel Hunting"; AppId = "6bf1c74d-7ade-4671-a507-166936f89a1f" } ) } else { Write-Error ("Government cloud environments require -AppsFile.`n" + "App IDs differ by cloud environment. Contact support@contraforce.com`n" + "to obtain the app IDs for your environment.") exit 1 } # ── Well-known first-party resource APIs ────────────────────────────────────── # Maps Entra object IDs → friendly names for the Microsoft APIs that ContraForce # integrates with. Object IDs are tenant-local so we resolve them at runtime. $ResourceAPIs = @( "Microsoft Graph" "Windows Azure Service Management API" "WindowsDefenderATP" "Microsoft Threat Protection" "Log Analytics API" ) # ── Friendly display names for resource APIs ────────────────────────────────── $FriendlyNames = @{ "Windows Azure Service Management API" = "Azure Service Management" } # ── Permission lookup tables ───────────────────────────────────────────────── $AppRoleLookup = @{} # resourceSPId -> { roleId -> { name, description } } $DescByNameLookup = @{} # resourceSPId -> { scopeName -> description } $ResourceNameById = @{} # resourceSPId -> friendly name function Register-ServicePrincipal { param( [Parameter(Mandatory)]$Sp, [string]$FriendlyName ) $id = $Sp.Id $ResourceNameById[$id] = if ($FriendlyName) { $FriendlyName } else { $Sp.DisplayName } $roles = @{} foreach ($role in $Sp.AppRoles) { $roles[$role.Id] = @{ name = $role.Value; description = $role.Description } } $AppRoleLookup[$id] = $roles $descByName = @{} foreach ($scope in $Sp.Oauth2PermissionScopes) { $descByName[$scope.Value] = $scope.AdminConsentDescription } $DescByNameLookup[$id] = $descByName } # ── Resolve resource API service principals ─────────────────────────────────── Write-Host "Resolving resource API service principals..." -ForegroundColor Cyan foreach ($apiName in $ResourceAPIs) { $sp = Get-MgServicePrincipal -Filter "displayName eq '$apiName'" ` -Property Id, DisplayName, AppRoles, Oauth2PermissionScopes -Top 1 if (-not $sp) { Write-Warning "Resource API not found in tenant: $apiName" continue } $friendly = if ($FriendlyNames.ContainsKey($sp.DisplayName)) { $FriendlyNames[$sp.DisplayName] } else { $sp.DisplayName } Register-ServicePrincipal -Sp $sp -FriendlyName $friendly Write-Host " Resolved: $friendly ($($sp.Id)) — $($AppRoleLookup[$sp.Id].Count) app roles, $($DescByNameLookup[$sp.Id].Count) delegated scopes" } # ── Also index ContraForce apps themselves (they expose internal scopes) ────── # Why startswith('ContraForce')? # Some ContraForce apps delegate to each other via custom oauth2 scopes (e.g. the # Portal app exposes scopes consumed by the API app). To resolve these internal # cross-app scopes to human-readable names instead of raw GUIDs, we index ALL # service principals whose display name starts with "ContraForce" — not just the # 8 customer-facing apps listed in $AppsToAudit. Permissions that originate from # these internal apps are tagged with "internal": true in the output so auditors # can distinguish them from Microsoft first-party API permissions. $AllCFServicePrincipals = Get-MgServicePrincipal ` -Filter "startswith(displayName, 'ContraForce')" ` -Property Id, DisplayName, AppRoles, Oauth2PermissionScopes -All foreach ($cfSp in $AllCFServicePrincipals) { if (-not $ResourceNameById.ContainsKey($cfSp.Id)) { Register-ServicePrincipal -Sp $cfSp } } # ── Audit each application ─────────────────────────────────────────────────── $results = [System.Collections.Generic.List[object]]::new() foreach ($app in $AppsToAudit) { Write-Host "`nAuditing: $($app.Name) ($($app.AppId))..." -ForegroundColor Cyan # Find the service principal in this tenant $sp = Get-MgServicePrincipal -Filter "appId eq '$($app.AppId)'" ` -Property Id, DisplayName, AppId -Top 1 if (-not $sp) { Write-Warning " NOT FOUND in tenant — skipping" $results.Add([ordered]@{ applicationName = $app.Name appId = $app.AppId status = "NOT_FOUND" delegatedPermissions = @() applicationPermissions = @() }) continue } $spId = $sp.Id # ── Delegated permissions (oauth2PermissionGrants) ──────────────────────── $grants = Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId $spId -All $delegated = [System.Collections.Generic.List[object]]::new() foreach ($grant in $grants) { $resourceId = $grant.ResourceId $resourceName = if ($ResourceNameById.ContainsKey($resourceId)) { $ResourceNameById[$resourceId] } else { $resourceId } $isInternal = $resourceName -like "ContraForce *" $scopeNames = ($grant.Scope -split ' ') | Where-Object { $_ -ne '' } | Sort-Object foreach ($scope in $scopeNames) { $desc = if ($DescByNameLookup.ContainsKey($resourceId) -and $DescByNameLookup[$resourceId].ContainsKey($scope)) { $DescByNameLookup[$resourceId][$scope] } else { $null } $delegated.Add([ordered]@{ permission = $scope api = $resourceName type = "Delegated" description = $desc internal = $isInternal }) } } # ── Application permissions (appRoleAssignments) ────────────────────────── $assignments = Get-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $spId -All $appPerms = [System.Collections.Generic.List[object]]::new() foreach ($assignment in $assignments) { $resourceName = $assignment.ResourceDisplayName $resourceId = $assignment.ResourceId $roleId = $assignment.AppRoleId # Resolve the role ID to a permission name and description $permName = $roleId $desc = $null if ($AppRoleLookup.ContainsKey($resourceId)) { $lookup = $AppRoleLookup[$resourceId] if ($lookup.ContainsKey($roleId)) { $permName = $lookup[$roleId].name $desc = $lookup[$roleId].description } } # Use friendly resource name if available $friendlyResource = if ($ResourceNameById.ContainsKey($resourceId)) { $ResourceNameById[$resourceId] } else { $resourceName } $appPerms.Add([ordered]@{ permission = $permName api = $friendlyResource type = "Application" description = $desc }) } # Sort for stable output $sortedDelegated = $delegated | Sort-Object { $_.api }, { $_.permission } $sortedAppPerms = $appPerms | Sort-Object { $_.api }, { $_.permission } $results.Add([ordered]@{ applicationName = $sp.DisplayName appId = $sp.AppId status = "OK" delegatedPermissions = @($sortedDelegated) applicationPermissions = @($sortedAppPerms) }) Write-Host " Delegated: $($delegated.Count) | Application: $($appPerms.Count)" } # ── Build output document ──────────────────────────────────────────────────── $output = [ordered]@{ metadata = [ordered]@{ generatedAt = (Get-Date -Format "o") tenantId = $context.TenantId environment = $Cloud generatedBy = $generatedBy toolVersion = "2.1.0" description = "ContraForce enterprise application permissions snapshot for documentation auditing." } applications = @($results) } $fullPath = [System.IO.Path]::GetFullPath($OutputPath) $json = $output | ConvertTo-Json -Depth 10 # Normalize to LF line endings $json = $json -replace "`r`n", "`n" [System.IO.File]::WriteAllText( $fullPath, "$json`n", [System.Text.UTF8Encoding]::new($false) ) # ── Restrict file permissions for government environments ───────────────────── # In GCC High and DoD environments, restrict the output file so only the current # user can read/write it. This prevents other accounts on shared jump boxes from # accessing tenant permission data. if ($Cloud -ne "AzureCloud") { try { $acl = Get-Acl -Path $fullPath $acl.SetAccessRuleProtection($true, $false) # disable inheritance, remove inherited rules $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name $rule = [System.Security.AccessControl.FileSystemAccessRule]::new( $currentUser, [System.Security.AccessControl.FileSystemRights]::FullControl, [System.Security.AccessControl.AccessControlType]::Allow ) $acl.SetAccessRule($rule) Set-Acl -Path $fullPath -AclObject $acl Write-Host " File permissions restricted to current user." -ForegroundColor Yellow } catch { Write-Warning "Could not restrict file permissions on '$fullPath': $_" } } Write-Host "`nAudit complete. Output written to: $OutputPath" -ForegroundColor Green Write-Host "Environment: $envDisplayName" Write-Host "Applications audited: $($results.Count)" Write-Host "Tenant: $($context.TenantId)" # ── Exit with non-zero code if any apps were not found ──────────────────────── $failures = @($results | Where-Object { $_.status -eq "NOT_FOUND" }) if ($failures.Count -gt 0) { Write-Warning "$($failures.Count) application(s) were not found in the tenant." exit 1 } ``` ```python audit_enterprise_apps.py icon="python" expandable theme={null} #!/usr/bin/env python3 """Audit ContraForce enterprise application permissions in Microsoft Entra ID. Queries Microsoft Graph for all documented ContraForce enterprise applications, resolves their delegated and application permissions to human-readable names, and outputs a structured JSON file suitable for diffing against documentation. Requires: - Python 3.10+ (older versions will produce a clear version error). See https://devguide.python.org/versions/ for supported Python versions. - ``azure-identity>=1.19`` and ``httpx>=0.28``:: pip install azure-identity httpx - Azure CLI (``az login``) session — used by ``AzureCliCredential`` for token acquisition - The target tenant must have the ContraForce enterprise applications consented Usage: python audit_enterprise_apps.py python audit_enterprise_apps.py -o audit-2026-02-12.json python audit_enterprise_apps.py -c AzureUSGovernment python audit_enterprise_apps.py -c AzureUSGovernment -o gov-audit.json """ import argparse import dataclasses import importlib.util import json import os import stat import sys import time from datetime import datetime, timezone from typing import Any # ── Requires: Python 3.10+, azure-identity>=1.19, httpx>=0.28 ──────────────── # Mirrors PowerShell's #Requires — validate before any third-party import. if sys.version_info < (3, 10): # noqa: UP036 print( f"Python 3.10+ is required (running {sys.version.split()[0]})", file=sys.stderr, ) raise SystemExit(1) _REQUIRED_PACKAGES = [ ("httpx", "httpx>=0.28"), ("azure.identity", "azure-identity>=1.19"), ] _missing = [spec for mod, spec in _REQUIRED_PACKAGES if importlib.util.find_spec(mod) is None] if _missing: print( f"Missing required packages: {', '.join(_missing)}\n" "Install via: pip install azure-identity httpx", file=sys.stderr, ) raise SystemExit(1) del _REQUIRED_PACKAGES, _missing import httpx # noqa: E402 from azure.core.exceptions import ClientAuthenticationError # noqa: E402 from azure.identity import AzureCliCredential, CredentialUnavailableError # noqa: E402 TOOL_VERSION = "2.1.0" # ── Cloud environment endpoints ─────────────────────────────────────────────── # Microsoft Graph endpoints differ by cloud environment. Commercial (including # GCC) uses graph.microsoft.com; GCC High and DoD use graph.microsoft.us. # See: https://learn.microsoft.com/en-us/graph/deployments CLOUD_ENVIRONMENTS: dict[str, dict[str, str]] = { "AzureCloud": { "graph_base": "https://graph.microsoft.com/v1.0", "graph_scope": "https://graph.microsoft.com/.default", "name": "Commercial", }, "AzureUSGovernment": { "graph_base": "https://graph.microsoft.us/v1.0", "graph_scope": "https://graph.microsoft.us/.default", "name": "US Government (GCC High / DoD)", }, } # ContraForce enterprise applications to audit (Commercial / AzureCloud only). # App IDs differ by cloud environment. Government cloud app IDs are provided # by ContraForce upon request and passed via --apps-file. COMMERCIAL_APPS = [ {"name": "ContraForce API", "app_id": "24d97bc0-8f2b-45d5-8e0b-7fe286732ef2"}, {"name": "ContraForce Portal", "app_id": "8b7cb435-9526-47ee-b79a-34433f0daad2"}, {"name": "ContraForce for MDE", "app_id": "6efccc6a-f0d3-49e5-92d0-17d4afa9ba52"}, {"name": "ContraForce Gamebooks for MDE", "app_id": "ad7b0e79-3c37-4408-bf8f-eb89522cc920"}, { "name": "ContraForce Gamebooks for Identity", "app_id": "36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a", }, { "name": "ContraForce Gamebooks for Email", "app_id": "44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d", }, { "name": "ContraForce Sentinel Hunting", "app_id": "6bf1c74d-7ade-4671-a507-166936f89a1f", }, ] # Well-known first-party resource APIs that ContraForce integrates with. RESOURCE_APIS = [ "Microsoft Graph", "Windows Azure Service Management API", "WindowsDefenderATP", "Microsoft Threat Protection", "Log Analytics API", ] # Friendly display names for resource APIs. FRIENDLY_NAMES: dict[str, str] = { "Windows Azure Service Management API": "Azure Service Management", } @dataclasses.dataclass class PermissionRegistry: """Lookup tables for resolving permission IDs to human-readable names.""" app_roles: dict[str, dict[str, dict[str, str | None]]] = dataclasses.field( default_factory=dict, ) delegated_scopes: dict[str, dict[str, dict[str, str | None]]] = dataclasses.field( default_factory=dict, ) resource_names: dict[str, str] = dataclasses.field(default_factory=dict) _scope_desc_by_name: dict[str, dict[str, str | None]] = dataclasses.field( default_factory=dict, repr=False, ) def index_service_principal(self, sp: dict, *, friendly_name: str | None = None) -> None: """Index a service principal's roles and scopes for later resolution.""" sp_id = sp["id"] self.resource_names[sp_id] = friendly_name or sp["displayName"] self.app_roles[sp_id] = { role["id"]: {"name": role["value"], "description": role.get("description")} for role in sp.get("appRoles") or [] } scopes_by_id: dict[str, dict[str, str | None]] = {} desc_by_name: dict[str, str | None] = {} for scope in sp.get("oauth2PermissionScopes") or []: desc = scope.get("adminConsentDescription") scopes_by_id[scope["id"]] = {"name": scope["value"], "description": desc} desc_by_name[scope["value"]] = desc self.delegated_scopes[sp_id] = scopes_by_id self._scope_desc_by_name[sp_id] = desc_by_name def resolve_scope_description(self, resource_id: str, scope_name: str) -> str | None: """Look up a delegated scope description by name.""" return self._scope_desc_by_name.get(resource_id, {}).get(scope_name) class AuditAuthError(Exception): """Raised when Azure CLI authentication fails.""" class GraphClient: """Lightweight Microsoft Graph client backed by httpx and AzureCliCredential.""" def __init__(self, *, cloud: str = "AzureCloud") -> None: env = CLOUD_ENVIRONMENTS[cloud] self._graph_base = env["graph_base"] self._graph_scope = env["graph_scope"] try: self._credential = AzureCliCredential() self._token = self._credential.get_token(self._graph_scope) except (CredentialUnavailableError, ClientAuthenticationError) as e: raise AuditAuthError( "Azure CLI is not authenticated. Run 'az login' first.\n" "For government cloud: az cloud set --name AzureUSGovernment && az login" ) from e self._http = httpx.Client( timeout=httpx.Timeout(30.0, connect=10.0), ) self._refresh_auth() # Resolve identity from Microsoft Graph API rather than decoding the # access token JWT on the client side. Access tokens are intended for # the resource server, not the client — decoding them without signature # verification is architecturally incorrect and raises red flags in # security reviews. Using /me and /organization is both correct and # eliminates the need for a JWT verification library. self._resolve_identity() def _resolve_identity(self) -> None: """Resolve authenticated user and tenant identity from Microsoft Graph.""" me_resp = self._request_with_retry( f"{self._graph_base}/me", params={"$select": "id,userPrincipalName"}, ) if me_resp is not None: me = me_resp.json() self.user_upn: str = me.get("userPrincipalName", "") self.user_oid: str = me.get("id", "") else: self.user_upn = "" self.user_oid = "" print( " WARNING: Could not resolve user identity from /me.", file=sys.stderr, ) org_resp = self._request_with_retry( f"{self._graph_base}/organization", params={"$select": "id"}, ) if org_resp is not None: orgs = org_resp.json().get("value", []) self.tenant_id: str = orgs[0]["id"] if orgs else "" else: self.tenant_id = "" print( " WARNING: Could not resolve tenant from /organization.", file=sys.stderr, ) # NOTE: Remove quotes when minimum version is Python 3.14+ (PEP 649). def __enter__(self) -> "GraphClient": # quoted: class name isn't bound yet return self def __exit__(self, *exc: object) -> None: self._http.close() def _refresh_auth(self) -> None: """Refresh the bearer token if it is within 5 minutes of expiry.""" if self._token.expires_on - time.time() < 300: self._token = self._credential.get_token(self._graph_scope) self._http.headers["Authorization"] = f"Bearer {self._token.token}" def _request_with_retry( self, url: str, params: dict[str, str] | None = None, *, max_retries: int = 3, ) -> httpx.Response | None: """GET with retry and 429/Retry-After handling.""" for attempt in range(max_retries + 1): self._refresh_auth() try: resp = self._http.get(url, params=params) if resp.status_code == 429: try: retry_after = int(resp.headers.get("Retry-After", 2**attempt)) except ValueError: retry_after = 2**attempt print(f" Throttled, retrying in {retry_after}s...", file=sys.stderr) time.sleep(retry_after) continue resp.raise_for_status() return resp except httpx.HTTPError as e: if attempt < max_retries: time.sleep(2**attempt) continue print( f" WARNING: Graph call failed after {max_retries + 1} attempts: {url}\n" f" {e}", file=sys.stderr, ) return None return None def paginated_get(self, url: str, params: dict[str, str] | None = None) -> list[dict]: """GET with automatic @odata.nextLink pagination.""" all_values: list[dict] = [] current_url: str | None = url current_params = params while current_url: resp = self._request_with_retry(current_url, current_params) if resp is None: print( f" WARNING: Pagination interrupted — returning {len(all_values)} " f"partial result(s) for {url}", file=sys.stderr, ) break data = resp.json() all_values.extend(data.get("value", [])) current_url = data.get("@odata.nextLink") current_params = None # nextLink includes query params return all_values def list_service_principals( self, *, odata_filter: str, select: list[str], ) -> list[dict]: """Query /servicePrincipals with an OData filter.""" return self.paginated_get( f"{self._graph_base}/servicePrincipals", params={"$filter": odata_filter, "$select": ",".join(select)}, ) def get_oauth2_permission_grants(self, sp_id: str) -> list[dict]: """Get delegated permission grants for a service principal.""" return self.paginated_get( f"{self._graph_base}/servicePrincipals/{sp_id}/oauth2PermissionGrants", ) def get_app_role_assignments(self, sp_id: str) -> list[dict]: """Get application permission assignments for a service principal.""" return self.paginated_get( f"{self._graph_base}/servicePrincipals/{sp_id}/appRoleAssignments", ) def resolve_resource_apis(graph: GraphClient, registry: PermissionRegistry) -> None: """Resolve resource API service principals and populate the registry.""" print("\033[36mResolving resource API service principals...\033[0m") select = ["id", "displayName", "appRoles", "oauth2PermissionScopes"] for api_name in RESOURCE_APIS: results = graph.list_service_principals( odata_filter=f"displayName eq '{api_name}'", select=select, ) if not results: print(f" WARNING: Resource API not found in tenant: {api_name}", file=sys.stderr) continue sp = results[0] sp_id = sp["id"] friendly_name = FRIENDLY_NAMES.get(sp["displayName"], sp["displayName"]) registry.index_service_principal(sp, friendly_name=friendly_name) print( f" Resolved: {friendly_name} ({sp_id})" f" — {len(registry.app_roles[sp_id])} app roles," f" {len(registry.delegated_scopes[sp_id])} delegated scopes" ) def index_contraforce_apps(graph: GraphClient, registry: PermissionRegistry) -> None: """Index ContraForce apps for internal cross-app scope resolution. Some ContraForce applications delegate to each other via custom OAuth2 scopes (e.g., the Portal delegates to the API). This queries for ALL service principals whose displayName starts with ``ContraForce`` — not just the seven audited apps — so that cross-app scopes resolve to human-readable names instead of raw GUIDs in the output. This broader query does NOT grant any additional access; it only reads public service principal metadata visible to any authenticated directory reader. Permissions returned from this query are tagged with ``"internal": true`` in the output to distinguish them from permissions that grant access to tenant data. """ cf_sps = graph.list_service_principals( odata_filter="startswith(displayName, 'ContraForce')", select=["id", "displayName", "oauth2PermissionScopes"], ) for cf_sp in cf_sps: if cf_sp["id"] not in registry.resource_names: registry.index_service_principal(cf_sp) def audit_delegated_permissions( graph: GraphClient, sp_id: str, registry: PermissionRegistry, ) -> list[dict[str, Any]]: """Query and resolve delegated permissions (oauth2PermissionGrants).""" grants = graph.get_oauth2_permission_grants(sp_id) delegated: list[dict[str, Any]] = [] for grant in grants: resource_id = grant["resourceId"] resource_name = registry.resource_names.get(resource_id, resource_id) is_internal = resource_name.startswith("ContraForce ") scope_names = sorted(s for s in grant.get("scope", "").split() if s) for scope in scope_names: delegated.append({ "permission": scope, "api": resource_name, "type": "Delegated", "description": registry.resolve_scope_description(resource_id, scope), "internal": is_internal, }) return sorted(delegated, key=lambda p: (p["api"], p["permission"])) def audit_application_permissions( graph: GraphClient, sp_id: str, registry: PermissionRegistry, ) -> list[dict[str, Any]]: """Query and resolve application permissions (appRoleAssignments).""" assignments = graph.get_app_role_assignments(sp_id) app_perms: list[dict[str, Any]] = [] for assignment in assignments: resource_name = assignment.get("resourceDisplayName", "") resource_id = assignment["resourceId"] role_id = assignment["appRoleId"] # Resolve the role ID to a permission name and description role = registry.app_roles.get(resource_id, {}).get(role_id) perm_name = role["name"] if role else role_id desc = role["description"] if role else None app_perms.append({ "permission": perm_name, "api": registry.resource_names.get(resource_id, resource_name), "type": "Application", "description": desc, }) return sorted(app_perms, key=lambda p: (p["api"], p["permission"])) def audit_app( graph: GraphClient, app: dict[str, str], registry: PermissionRegistry, ) -> dict[str, Any]: """Audit a single enterprise application.""" print(f"\n\033[36mAuditing: {app['name']} ({app['app_id']})...\033[0m") results = graph.list_service_principals( odata_filter=f"appId eq '{app['app_id']}'", select=["id", "displayName", "appId"], ) if not results: print(" WARNING: NOT FOUND in tenant — skipping", file=sys.stderr) return { "applicationName": app["name"], "appId": app["app_id"], "status": "NOT_FOUND", "delegatedPermissions": [], "applicationPermissions": [], } sp = results[0] sp_id = sp["id"] delegated = audit_delegated_permissions(graph, sp_id, registry) app_perms = audit_application_permissions(graph, sp_id, registry) print(f" Delegated: {len(delegated)} | Application: {len(app_perms)}") return { "applicationName": sp["displayName"], "appId": sp["appId"], "status": "OK", "delegatedPermissions": delegated, "applicationPermissions": app_perms, } def parse_args() -> argparse.Namespace: """Parse command-line arguments.""" parser = argparse.ArgumentParser( description="Audit ContraForce enterprise application permissions in Microsoft Entra ID.", ) parser.add_argument( "-o", "--output", default="enterprise-apps-audit.json", help="Path for the output JSON file (default: enterprise-apps-audit.json)", ) parser.add_argument( "-c", "--cloud", choices=list(CLOUD_ENVIRONMENTS), default="AzureCloud", help=( "Cloud environment to audit: AzureCloud (default) or" " AzureUSGovernment (GCC High / DoD). Must match the environment" " set with 'az cloud set --name '." ), ) parser.add_argument( "-a", "--apps-file", help=( "Path to a JSON file listing the applications to audit. Each entry" " must have 'name' and 'app_id' fields. Required for government" " cloud environments where app IDs differ from commercial." " Contact support@contraforce.com for your environment's app IDs." ), ) parser.add_argument( "--redact-upn", action="store_true", help=( "Record the operator's Entra object ID instead of UPN in output" " metadata. Automatically enabled for government environments." ), ) return parser.parse_args() def main() -> int: """Run the enterprise application audit and return exit code.""" args = parse_args() cloud = args.cloud # Resolve the application list: built-in for commercial, file-based for gov if args.apps_file: with open(args.apps_file, encoding="utf-8") as f: apps_to_audit = json.load(f) elif cloud == "AzureCloud": apps_to_audit = COMMERCIAL_APPS else: print( "ERROR: Government cloud environments require --apps-file.\n" "App IDs differ by cloud environment. Contact support@contraforce.com\n" "to obtain the app IDs for your environment.", file=sys.stderr, ) return 1 try: graph = GraphClient(cloud=cloud) except AuditAuthError as e: print(f"ERROR: {e}", file=sys.stderr) return 1 with graph: # Auto-enable UPN redaction for government cloud environments redact_upn = args.redact_upn or cloud != "AzureCloud" generated_by = graph.user_oid if redact_upn else graph.user_upn tenant_id = graph.tenant_id env_name = CLOUD_ENVIRONMENTS[cloud]["name"] print( f"\033[32mAuthenticated as: {generated_by}" f" (Tenant: {tenant_id}, Environment: {env_name})\033[0m" ) registry = PermissionRegistry() resolve_resource_apis(graph, registry) index_contraforce_apps(graph, registry) results = [audit_app(graph, app, registry) for app in apps_to_audit] # Build output document output = { "metadata": { "generatedAt": datetime.now(timezone.utc).isoformat(), # noqa: UP017 "tenantId": tenant_id, "generatedBy": generated_by, "toolVersion": TOOL_VERSION, "environment": cloud, "description": ( "ContraForce enterprise application permissions snapshot" " for documentation auditing." ), }, "applications": results, } output_json = json.dumps(output, indent=2, ensure_ascii=False) + "\n" with open(args.output, "w", encoding="utf-8", newline="\n") as f: f.write(output_json) # Restrict file permissions for government cloud environments if cloud != "AzureCloud": try: os.chmod(args.output, stat.S_IRUSR | stat.S_IWUSR) except OSError: print( f" WARNING: Could not restrict file permissions on {args.output}.\n" ' On Windows, run: icacls /inheritance:r /grant:r "%USERNAME%":F', file=sys.stderr, ) print(f"\n\033[32mAudit complete. Output written to: {args.output}\033[0m") print(f"Applications audited: {len(results)}") print(f"Tenant: {tenant_id}") print(f"Environment: {env_name}") if redact_upn: print("Operator identity: redacted (object ID used)") # Exit with non-zero code if any apps were not found failures = [r for r in results if r["status"] == "NOT_FOUND"] if failures: print( f"\nWARNING: {len(failures)} application(s) were not found in the tenant.", file=sys.stderr, ) return 1 return 0 if __name__ == "__main__": sys.exit(main()) ``` ## Understanding the Output Both scripts produce a JSON file with the same structure. Here's an abbreviated example: ```json Output Schema theme={null} { "metadata": { "generatedAt": "2026-02-12T18:30:00.000000+00:00", "tenantId": "your-tenant-id", "generatedBy": "admin@company.example", "toolVersion": "2.1.0", "environment": "AzureCloud", "description": "ContraForce enterprise application permissions snapshot for documentation auditing." }, "applications": [ { "applicationName": "ContraForce API", "appId": "24d97bc0-8f2b-45d5-8e0b-7fe286732ef2", "status": "OK", "delegatedPermissions": [ { "permission": "Application.Read.All", "api": "Microsoft Graph", "type": "Delegated", "description": "Allows the app to read applications and service principals on behalf of the signed-in user.", "internal": false } ], "applicationPermissions": [] } ] } ``` ### Key Fields | Field | Description | | - | - | | `status` | `OK` if the application was found and audited. `NOT_FOUND` if the application is not consented in the tenant. | | `type` | `Delegated` (on-behalf-of user) or `Application` (app-only, no user context). See [Permission Types Explained](/guides/technical/enterprise-applications#permission-types-explained). | | `internal` | `true` for permissions between ContraForce applications (e.g., Portal delegating to API). These are internal platform scopes and do not grant access to your tenant data. Only present on delegated permissions. | | `environment` | The cloud environment the audit was run against (`AzureCloud` or `AzureUSGovernment`). Matches the `az cloud set --name` value. | | `generatedBy` | The authenticated operator. In government environments, this is an Entra object ID (GUID) rather than a UPN. | | `toolVersion` | Include this when sharing audit results with ContraForce support for traceability. | ### Internal Scope Resolution You may notice the output includes delegated permissions where the `api` field shows a ContraForce application name (e.g., `"ContraForce Portal"`) and `"internal": true`. These are cross-application delegations where one ContraForce app delegates to another via custom OAuth2 scopes. To resolve these internal scopes to human-readable names instead of raw GUIDs, the scripts query for all service principals whose display name starts with `ContraForce` — not just the seven applications listed in the audit table. This broader query: * **Does not grant additional access** — it reads public service principal metadata that any authenticated directory reader can see * **Is clearly tagged** — all permissions from internal apps are marked `"internal": true` in the output * **Improves readability** — without this, internal scopes would appear as opaque GUIDs that are difficult to review ### Comparing Against Documentation To verify your tenant's permissions match the documented permissions: 1. Run the audit script to produce `enterprise-apps-audit.json` 2. Open the [Enterprise Applications Reference](/guides/technical/enterprise-applications) 3. For each application in the JSON output, compare its `delegatedPermissions` and `applicationPermissions` against the corresponding tables in the reference 4. Permissions marked `"internal": true` are ContraForce-to-ContraForce delegations and are not listed in the reference tables ### Comparing Across Audit Runs To track permission changes over time, save each audit output with a date-stamped filename: ```bash theme={null} # Date-stamped output python audit_enterprise_apps.py -o audit-2026-02-12.json # Later, compare against a previous audit diff audit-2026-01-15.json audit-2026-02-12.json ``` Because the scripts sort all permissions alphabetically and produce deterministic JSON output, standard text diff tools (`diff`, VS Code's built-in compare, or `Compare-Object` in PowerShell) will surface only actual permission changes — not ordering noise. Store audit outputs alongside your change management records. The `metadata.generatedAt` and `metadata.toolVersion` fields provide traceability for each snapshot. ## Output File Access Control The audit output reveals your tenant's permission surface for ContraForce applications. While it does not contain secrets or tokens, it should be treated as internal documentation. **Government cloud environments:** Both scripts automatically restrict the output file so only the current user can read or write it: * **PowerShell (Windows):** Removes inherited ACL entries and grants `FullControl` only to the current user via `Set-Acl` * **Python (POSIX):** Sets file mode to `600` (`chmod u=rw,go=`) via `os.chmod` **Commercial environments:** File permissions are not restricted automatically. If you are running the audit on a shared workstation or jump box, consider restricting access manually: **Windows** ```powershell theme={null} icacls enterprise-apps-audit.json /inheritance:r /grant:r "%USERNAME%":F ``` **Linux / macOS** ```bash theme={null} chmod 600 enterprise-apps-audit.json ``` ## Using This Output as Audit Evidence The audit output is designed to serve as evidence in change advisory board (CAB) reviews, compliance audits, and periodic access reviews. **For CAB / Change Management:** * Run the audit before and after onboarding a new ContraForce module * Include both snapshots in your change record to show exactly which permissions were added * The `toolVersion` field ensures reviewers know which version of the script produced the output **For Periodic Access Reviews (CMMC, SOC 2, FedRAMP):** * Schedule monthly or quarterly audit runs and archive the output alongside your review documentation * Use date-stamped filenames (e.g., `audit-2026-Q1.json`) for easy retrieval * Compare successive outputs using `diff` to identify any permission drift **For Incident Response:** * If you suspect unauthorized permission changes, run an immediate audit and compare against your most recent baseline * The `generatedAt` timestamp provides a verifiable point-in-time snapshot > [!TIP] > > Store audit outputs in a version-controlled repository or a tamper-evident storage location (such as an Azure Storage account with immutable blob policies) to maintain an auditable chain of custody. ## Troubleshooting | Issue | Cause | Resolution | | - | - | - | | `NOT_FOUND` for some applications | Application not consented in tenant | Expected if you haven't deployed all modules. See [Applications by Module](/guides/technical/enterprise-applications#applications-by-module). | | PowerShell: "No active Microsoft Graph session" | `Connect-MgGraph` not run | Run `Connect-MgGraph -Scopes "Application.Read.All","Directory.Read.All"` first. For government cloud, add `-Environment USGov` (GCC High) or `-Environment USGovDoD` (DoD). | | PowerShell: "Environment mismatch" | `-Cloud` value does not match the `Connect-MgGraph -Environment` session | Disconnect with `Disconnect-MgGraph` and reconnect with the correct `-Environment` flag matching your `-Cloud` value. | | "Government cloud environments require -AppsFile / --apps-file" | No apps file provided for government cloud | App IDs differ by cloud environment. Contact [support@contraforce.com](mailto:support@contraforce.com) for your environment's app IDs and provide them via `-AppsFile` (PowerShell) or `--apps-file` (Python). | | Python: "Azure CLI is not authenticated" | `az login` not run or session expired | Run `az login` to authenticate. For government cloud, run `az cloud set --name AzureUSGovernment` first. | | Python: "Missing required packages" | `azure-identity` or `httpx` not installed | Run `pip install azure-identity httpx` | | Python: "Python 3.10+ is required" | Running on an older Python version | Install [Python 3.10 or newer](https://devguide.python.org/versions/) | | Script takes a long time | Microsoft Graph API throttling | Normal in large tenants. The scripts handle `429 Retry-After` responses automatically. | | Permissions don't match documentation | Permissions changed since last documentation update | Contact [support@contraforce.com](mailto:support@contraforce.com) with the audit JSON and `toolVersion` | *** ## Related Resources > **[Enterprise Applications Reference](/guides/technical/enterprise-applications)** > > Complete reference for all ContraForce enterprise applications and their permissions > **[Azure Resources Deployed](/guides/technical/azure-resources-deployed)** > > All Azure resources provisioned during ContraForce onboarding > **[Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > ContraForce platform roles and what each can do > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Step-by-step guide to onboarding your parent workspace > **[Offboarding Procedure](/guides/general-support/offboarding-contra-force)** > > Remove ContraForce enterprise apps, Azure resources, role assignments, and Lighthouse delegation > [!NOTE] > > Questions about the audit scripts or enterprise application permissions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Azure Resources Deployed for Sentinel and Agents Source: https://docs.contraforce.com/guides/technical/azure-resources-deployed See which Azure resources ContraForce deploys for your module, from Azure Lighthouse and rg-contraforce-apollo to Agent Center, and how to verify them. This article documents all Azure resources that ContraForce provisions during the onboarding process. Use this reference to understand what's deployed in your environment, verify deployments, and plan for [offboarding](/guides/general-support/offboarding-contra-force) if needed. > [!NOTE] > > The resources deployed depend on your module selection (XDR vs XDR + SIEM) and whether you enable AI Agents. Not all resources apply to every deployment. ## Deployment Overview ContraForce deploys resources across several Azure components: > **Enterprise Applications** > > Service principals in Microsoft Entra ID for API access and authentication > **Azure Lighthouse** > > Cross-tenant delegation for MSSP management scenarios > **Apollo Infrastructure** > > Real-time incident notification system for Sentinel > **Agent Infrastructure** > > AI agent hosting environment (optional) ### Resources by Module | Resource Category | Defender Module | XDR + SIEM Module | With AI Agents | | - | :-: | :-: | :-: | | Core Enterprise Applications | ✓ | ✓ | ✓ | | Defender Enterprise Applications | ✓ | ✓ | ✓ | | Azure Lighthouse | — | ✓ | ✓ | | Apollo Resource Group | — | ✓ | ✓ | | Sentinel Resource Deployments | — | ✓ | ✓ | | Agent Center Resource Group | — | — | ✓ | | Per-Agent Resource Groups | — | — | ✓ | *** ## Phase 1: Initial Onboarding The first phase provisions core enterprise applications required for all ContraForce deployments. ### Enterprise Applications These applications are provisioned and consented during initial setup: | Application | Application ID | Purpose | | - | - | - | | **ContraForce API** | `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` | Core platform API access | | **ContraForce Portal** | `8b7cb435-9526-47ee-b79a-34433f0daad2` | User authentication and portal access | > [!NOTE] > > These two applications are required for all ContraForce deployments, regardless of module selection. They are consented when you first sign in at [portal.contraforce.com](https://portal.contraforce.com), as separate **ContraForce API** and **ContraForce Portal** Microsoft consent prompts granted by a **Global Administrator**. ### Permissions Granted | Application | Permission Type | Permissions | | - | - | - | | **ContraForce API** | Application | User.Read.All | | **ContraForce Portal** | Delegated | User.Read, openid, profile | > [!WARNING] > > **Consent model.** ContraForce enterprise applications are consented with **application (app-only)** Microsoft Graph permissions. Admin consent for Microsoft Graph application permissions must be granted by a **Global Administrator** or a **Privileged Role Administrator** — Cloud Application Administrator and Application Administrator cannot grant it. The role is required for the one-time consent only and is not retained; activate it just-in-time with Privileged Identity Management (PIM) and deactivate afterward. > > Because actions run as the application (no signed-in user required), operator control is enforced through **Gamebook approval gates** — only Workspace Owners can approve high-impact actions — and a complete **audit trail** in the Gamebooks History page. *** ## Phase 2: Module-Specific Applications Additional enterprise applications are consented based on your module selection and enabled features. ### Microsoft Defender for Endpoint Applications | Application | Application ID | Purpose | | - | - | - | | **ContraForce for MDE** | `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` | Defender for Endpoint data access | | **ContraForce Gamebooks for MDE** | `ad7b0e79-3c37-4408-bf8f-eb89522cc920` | Endpoint response actions | ### Identity Applications | Application | Application ID | Purpose | | - | - | - | | **ContraForce Gamebooks for Identity** | `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` | User response actions (disable, reset password) | ### Microsoft Sentinel Applications | Application | Application ID | Purpose | | - | - | - | | **ContraForce Sentinel Hunting** | `6bf1c74d-7ade-4671-a507-166936f89a1f` | Log Analytics queries for threat hunting | ### Email Applications | Application | Application ID | Purpose | | - | - | - | | **ContraForce Gamebooks for Email** | `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` | Email response actions (soft delete) | *** ## Phase 3: Microsoft Sentinel Core Components For XDR + SIEM deployments, additional Azure resources establish the connection between your Sentinel environment and ContraForce. > [!WARNING] > > This phase only applies to **XDR + SIEM module** deployments. XDR-only deployments skip this phase. ### Azure Lighthouse Delegation Azure Lighthouse enables cross-tenant management without credential sharing. | Resource | Type | Description | | - | - | - | | **ContraForceLighthouseDeployment** | ARM Template | Assigns Sentinel resource group to ContraForce tenant | #### What Lighthouse Enables * Cross-tenant visibility into your Sentinel workspace * Incident management without logging into your tenant * Centralized management for MSSPs > [!NOTE] > > Azure Lighthouse delegates **Azure resource access only** (Sentinel Contributor + Reader on the Sentinel resource group). It does **not** delegate identity, mailbox, or endpoint response. Those capabilities are provided by the consented ContraForce enterprise applications in each tenant — through per-tenant application consent, or GDAP for CSP relationships. Azure Lighthouse is distinct from Microsoft 365 Lighthouse and from GDAP. > [!TIP] > > Azure Lighthouse is the Microsoft-recommended approach for MSSP scenarios. It provides secure delegated access without sharing credentials or creating guest accounts. ### Role Assignments | Principal | Role | Scope | | - | - | - | | **ContraForce API** | Sentinel Contributor | Sentinel Resource Group | | **ContraForce API** | Reader | Sentinel Resource Group | ### Resource Provider Registrations The following resource providers are registered in your subscription: | Resource Provider | Purpose | | - | - | | **Microsoft.Network** | Network resources for Apollo deployment | | **Microsoft.Storage** | Storage accounts for Apollo deployment | *** ## Phase 4: Apollo Resource Group Apollo enables real-time Sentinel incident notifications. A dedicated resource group is created with supporting infrastructure. ### Apollo Resource Group Details | Property | Value | | - | - | | **Name** | `rg-contraforce-apollo` | | **Purpose** | Real-time incident notification infrastructure | | **Location** | Same region as your Sentinel workspace | ### Apollo Resources > **Compute Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Function App** | Microsoft.Web/sites | Processes incident events | > | **App Service Plan** | Microsoft.Web/serverfarms | Hosts the Function App | > **Monitoring Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Log Analytics Workspace** | Microsoft.OperationalInsights/workspaces | Apollo diagnostics and logging | > | **Application Insights** | Microsoft.Insights/components | Function App monitoring | > **Storage Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Storage Account** | Microsoft.Storage/storageAccounts | Function App storage | > **Security Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Apollo Role Definition** | Microsoft.Authorization/roleDefinitions | Custom role for Apollo access | > | **Role Assignment** | Microsoft.Authorization/roleAssignments | Apollo RG to Lighthouse delegation | ### Apollo Architecture ```mermaid theme={null} flowchart LR A[Sentinel Incident] --> B[Automation Rule] B --> C[Logic App] C --> D[Function App] D --> E[ContraForce Platform] ``` *** ## Phase 5: Sentinel Resource Group Deployments Resources are also deployed directly into your existing Sentinel resource group to enable incident streaming. ### Resources in Sentinel Resource Group | Resource | Type | Name | | - | - | - | | **API Connection** | Microsoft.Web/connections | `microsoftsentinel-Publish-Incident-To-Apollo` | | **Logic App** | Microsoft.Logic/workflows | `Publish-Incident-To-Apollo` | | **Automation Rule** | Microsoft.SecurityInsights/automationRules | `Run-Playbook-Publish-Incident-To-Apollo` | ### How Incident Streaming Works **1. Incident Created** A new incident is created in Microsoft Sentinel **2. Automation Rule Triggers** The `Run-Playbook-Publish-Incident-To-Apollo` automation rule detects the new incident **3. Logic App Executes** The `Publish-Incident-To-Apollo` Logic App is triggered **4. Incident Sent** The Logic App sends incident data to the Apollo Function App **5. ContraForce Updated** The incident appears in the ContraForce Command Dashboard in near real-time *** ## Phase 6: Agent Center Resource Group (Optional) If you deploy ContraForce AI Agents, a dedicated resource group hosts the core agent infrastructure. > [!NOTE] > > AI Agents are an optional feature. Most deployments do not include agent infrastructure. Skip this section if you haven't enabled AI Agents. ### Agent Center Resource Group Details | Property | Value | | - | - | | **Name** | `rg-cf-agent-center` | | **Purpose** | Core infrastructure for ContraForce AI agents | | **Location** | Configured during agent deployment | ### Agent Center Resources > **AI Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Microsoft Foundry** | Microsoft.MachineLearningServices/workspaces | AI model management | > | **CosmosDB** | Microsoft.DocumentDB/databaseAccounts | Agent data storage | > **Compute Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Container Apps Environment** | Microsoft.App/managedEnvironments | Agent runtime environment | > | **Container App (Infrastructure)** | Microsoft.App/containerApps | Infrastructure management | > | **Log Analytics Workspace** | Microsoft.OperationalInsights/workspaces | Container Apps logging | > **Network Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Virtual Network (VNET)** | Microsoft.Network/virtualNetworks | Network isolation | > | **Azure Subnet** | Subnet | Container Apps subnet | > | **Private Endpoint Subnet** | Subnet | Private endpoints | > | **Cosmos DNS Zone** | Microsoft.Network/privateDnsZones | CosmosDB DNS resolution | > | **Key Vault DNS Zone** | Microsoft.Network/privateDnsZones | Key Vault DNS resolution | > | **CosmosDB Private Endpoint** | Microsoft.Network/privateEndpoints | Secure CosmosDB access | > | **Key Vault Private Endpoint** | Microsoft.Network/privateEndpoints | Secure Key Vault access | > **Security Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Key Vaults** | Microsoft.KeyVault/vaults | Secret management | > | **Managed Identity** | Microsoft.ManagedIdentity/userAssignedIdentities | Container App authentication | > **Storage Resources** > > | Resource | Type | Purpose | > | - | - | - | > | **Storage Account** | Microsoft.Storage/storageAccounts | Infrastructure management storage | *** ## Phase 7: Per-Agent Resource Groups (Optional) A dedicated resource group is created for each AI agent deployed per workspace. ### Resource Group Naming | Property | Pattern | | - | - | | **Name Format** | `rg-cf-agent-{agent-id}` | | **Example** | `rg-cf-agent-abc123` | ### Resources Per Agent | Resource | Type | Purpose | | - | - | - | | **Microsoft Foundry project** | Microsoft.MachineLearningServices/workspaces/projects | Agent-specific AI project | | **OpenAI Model Deployment** | Microsoft.CognitiveServices/accounts/deployments | LLM for agent reasoning | | **Container App** | Microsoft.App/containerApps | Agent application runtime | > [!TIP] > > Each workspace can have multiple agents, each with its own resource group. Monitor your Azure costs if you deploy many agents across many workspaces. *** ## Complete Resource Summary ### By Deployment Type **XDR Only** **Enterprise Applications:** * ContraForce API * ContraForce Portal * ContraForce for MDE * ContraForce Gamebooks for MDE * ContraForce Gamebooks for Identity * ContraForce Gamebooks for Email **Azure Resources:** None **XDR + SIEM** **Enterprise Applications:** * All XDR applications * ContraForce Sentinel Hunting **Azure Resources:** * Azure Lighthouse delegation * Role assignments (Sentinel Contributor, Reader) * Apollo Resource Group (`rg-contraforce-apollo`) * Sentinel Logic App and API Connection * Sentinel Automation Rule **With AI Agents** **Enterprise Applications:** * All XDR + SIEM applications **Azure Resources:** * All XDR + SIEM resources * Agent Center Resource Group (`rg-cf-agent-center`) * Per-Agent Resource Groups (`rg-cf-agent-*`) ### Enterprise Application Quick Reference | Application | App ID | Required For | | - | - | - | | ContraForce API | `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` | All deployments | | ContraForce Portal | `8b7cb435-9526-47ee-b79a-34433f0daad2` | All deployments | | ContraForce for MDE | `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` | Endpoint visibility | | ContraForce Gamebooks for MDE | `ad7b0e79-3c37-4408-bf8f-eb89522cc920` | Endpoint response | | ContraForce Gamebooks for Identity | `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` | User response | | ContraForce Sentinel Hunting | `6bf1c74d-7ade-4671-a507-166936f89a1f` | Threat hunting | | ContraForce Gamebooks for Email | `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` | Email response | *** ## Verifying Deployed Resources ### Check Enterprise Applications **1. Open Microsoft Entra ID** Navigate to [entra.microsoft.com](https://entra.microsoft.com) **2. Go to Enterprise Applications** Click **Identity** > **Applications** > **Enterprise applications** **3. Search for ContraForce** Search for "ContraForce" to see all provisioned applications **4. Verify Status** Each application should show "Enabled" status ### Check Azure Resources **1. Open Azure Portal** Navigate to [portal.azure.com](https://portal.azure.com) **2. Search Resource Groups** Search for "contraforce" or "cf-agent" in resource groups **3. Verify Resources** Open each resource group and confirm expected resources exist ### Check Role Assignments **1. Navigate to Sentinel Resource Group** Find your Sentinel resource group in Azure Portal **2. Open Access Control** Click **Access control (IAM)** **3. View Role Assignments** Click **Role assignments** tab **4. Find ContraForce** Search for "ContraForce" to verify assignments *** ## Cost Considerations ### Included Resources Most ContraForce resources have minimal Azure cost impact: | Resource Type | Typical Cost | | - | - | | Enterprise Applications | Free | | Azure Lighthouse | Free | | Role Assignments | Free | | Logic App (Consumption) | \~\$0.01-1/month | | Function App (Consumption) | \~\$1-5/month | ### Potentially Significant Costs > [!WARNING] > > AI Agent deployments can incur significant Azure costs depending on usage: > > * **Microsoft Foundry / OpenAI**: Pay-per-token pricing > * **Container Apps**: Compute costs based on usage > * **CosmosDB**: Storage and throughput costs > > Monitor your Azure spending if you enable AI Agents. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Missing enterprise apps** | Consent incomplete | Re-run consent flow in workspace settings | | **Apollo resource group missing** | Deployment failed | Check deployment history in Azure; contact support | | **Logic App not running** | Disabled or failed | Enable the Logic App in Azure Portal | | **No incidents syncing** | Automation rule disabled | Enable the automation rule in Sentinel | | **Role assignment missing** | Manual removal | Re-run onboarding or manually add assignments | ### Viewing Deployment History **1. Open Subscription** Navigate to your Azure subscription **2. Go to Deployments** Click **Deployments** in the left navigation **3. Find ContraForce Deployments** Search for "ContraForce" or "Apollo" **4. Review Status** Check deployment status and error messages *** ## Related Guides > **[Sentinel Onboarding](/guides/onboarding/microsoft-sentinel-module)** > > Complete SIEM module deployment guide > **[XDR Onboarding](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Defender module deployment guide > **[Enterprise Applications](/guides/technical/enterprise-applications)** > > Service principal details and permissions > **[Audit Permissions](/guides/technical/auditing-enterprise-app-permissions)** > > Verify the permissions granted to ContraForce enterprise apps with read-only scripts *** > [!NOTE] > > Questions about deployed resources? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Configure Incident Webhooks Source: https://docs.contraforce.com/guides/technical/configure-webhooks Send signed incident webhooks from ContraForce to your ticketing system, SIEM, or chat tools. Pick events and workspaces, then test and manage deliveries. A webhook sends a signed HTTPS request to an endpoint you control every time a selected event happens in ContraForce, such as an incident being created, closed, or commented on. Use webhooks to push incidents into your ticketing system, SIEM, chat tools, or automation platform without polling the API. > [!NOTE] > > **Who is this for?** Organization Admins and security engineers connecting ContraForce to an external system. For the payload of each event, see the [Webhook Event Reference](/api-reference/webhook-events). ## Before you start * You are signed in as an **Organization Admin**. * You have an HTTPS endpoint that accepts `POST` requests and answers with a `2xx` status within 30 seconds. Plain HTTP, `localhost`, and private network addresses are rejected. * You know how your endpoint expects to authenticate callers: no authentication, basic authentication, or a bearer token. ## Choose an authentication type Every delivery is signed with an HMAC-SHA256 signature in the `X-CF-Signature` header, whichever option you pick. The authentication type adds an `Authorization` header on top of that signature for endpoints that require one. | Authentication | What ContraForce sends | Use it when | | - | - | - | | **No authentication** | No `Authorization` header. The request is verified by its `X-CF-Signature` only. | Your endpoint verifies the signature itself, or it is a URL with a secret token built in. | | **Basic authentication** | `Authorization: Basic ` | Your endpoint or gateway expects a username and password. | | **Bearer token** | `Authorization: Bearer ` | Your endpoint or API gateway expects an API key or token. | ## Create a webhook **1. Open the Developers tab** In the left navigation, click **Settings**, then select the **Developers** tab. The **Integrations** list shows your existing webhooks and service accounts. ![Settings page with the Developers tab selected, showing the Integrations list and the Add integration button](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/01-developers-tab.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=ee3d27542e6c273e874356902f593b85) **2. Start a new webhook integration** Click **Add integration**. In the panel that opens, open the **Integration type** list and select **Webhook**. ![Add integration panel with the Integration type list open, showing Webhook and Service account](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/02-integration-type.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=e0a1ada5860e1d5ea2df7b7a3526f6e7) **3. Name the webhook and enter the endpoint URL** Under **Webhook details**, enter a **Name** that tells your team where the events go (for example, `SOC ticketing webhook`) and the **URL** of your endpoint, such as `https://hooks.company.example/contraforce`. Then open the **Authentication** list and choose the type your endpoint expects. ![Webhook details with Name and URL filled in and the Authentication list open, showing No authentication, Basic authentication, and Bearer token](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/03-details-and-auth.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=5bbbe60f8a12b349364df2a60e828a1a) **4. Enter the credentials for your authentication type** What you fill in depends on the type you picked. **No authentication** Nothing else to enter. Verify the `X-CF-Signature` header on your endpoint so it only accepts requests from ContraForce. **Basic authentication** Enter the **Username** and **Password** your endpoint expects. Both are required. ![Basic authentication selected, with Username and Password fields](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/04-basic-auth.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=4c8480785c78a9b9e236bfa08777009f) **Bearer token** Enter the **Token** your endpoint expects. It is sent as `Authorization: Bearer `. **Signing token** is optional. Leave it empty and ContraForce generates a signing secret for you when you save. Enter a value only if you want to supply the key used to sign `X-CF-Signature` yourself. ![Bearer token selected, with a required Token field and an optional Signing token field](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/05-bearer-token.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=7bfc1010c9b371e4563577bcd87c1d86) **5. Select the events to send** Under **Events**, turn on each event this webhook should receive. At least one is required. * Turn on **Webhook Test** if you want to use **Send test** later to check connectivity. * For close handling, pick **Incident Closed** *or* **Incident Status Changed**. A close fires both, so subscribing to both gives you two deliveries per close. ![Events list with Incident Created, Incident Closed, and Incident Comment Added turned on](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/06-events.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=a646548c1c05a1ec976bab7c27f8653c) > [!TIP] > > Click the info icon next to any event to see a sample payload exactly as your endpoint will receive it. Use **Copy JSON** to build and test your parser before any real event arrives. ![Incident Created sample payload dialog showing the JSON envelope, with Copy JSON and Close buttons](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/07-sample-payload.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=e2ed3d8e312ecab1409f345267ba2d9b) **6. Choose which workspaces the webhook covers** Under **Workspaces**, search for and add the customer workspaces this webhook should send events for. Leave the list empty to send events from **all** workspaces you manage, including ones you add later. The **Agent investigation completed** event is listed separately as **Owned by another flow**. You don't subscribe to it here: it is wired from an agent's classification card. See [Send agent verdicts to a webhook](#send-agent-verdicts-to-a-webhook). ![Owned by another flow callout for Agent investigation completed, and the Workspaces section with an empty workspace search](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/08-agent-event-and-workspaces.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=520466f02ccd40f3fbc59ecdf825384c) **7. Save and copy the signing secret** Click **Save**. ContraForce shows the webhook's **signing secret** once. Copy it with the copy button and store it in your endpoint's secret store, then click **Done**. > [!WARNING] > > The signing secret is not shown again after you close this dialog. If you lose it, open the webhook and click **Regenerate**, then update your endpoint with the new secret. ![Webhook signing secret dialog with the secret value hidden, a copy button, and a Done button](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/09-signing-secret.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=ceb99b1d16070ef3c7121dbc25702b8a) If you entered your own **Signing token** for a bearer-token webhook, the dialog tells you that token is used for signing instead. **8. Confirm the webhook is active** The new webhook appears in the **Integrations** list with the **Webhook** type and an **Active** status. ![Integrations list showing the new SOC ticketing webhook with Webhook type and Active status](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/10-integration-list.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=7a84a7b2a7f6437404e1bacc1a4f9832) ## Send a test and check the delivery Test before you rely on the webhook, and again any time you change the endpoint or its credentials. **1. Open the webhook** In **Settings → Developers**, click the gear icon on the webhook's row. The **General** tab shows the endpoint, authentication, signing secret, event subscriptions, and workspaces. ![Webhook details General tab with Pause and Delete buttons, the Endpoint section, the Authentication section with Update credentials, and the Signing secret section with Regenerate](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/11-details-general.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=cc13dbe123bb68321875a089c613c1d7) **2. Send a test event** Under **Event subscriptions**, click **Send test** on the **Webhook Test** row. A **Test webhook queued for delivery** message confirms the request was queued. ![Event subscriptions section with Webhook Test turned on and a Send test button](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/12-event-subscriptions.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=2c755d2d9d9e5944f69b7f4d3435798a) Test deliveries carry an `X-CF-Test: true` header and `"isTest": true` in the body, so your endpoint can tell them apart from real events. **3. Check the delivery log** Select the **Events** tab. Each delivery attempt is listed with its date, workspace, event type, and status. A test that reached your endpoint shows **Success**. ![Delivery events list showing a webhook.test.v1 delivery with Success status](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/13-delivery-log.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=b26bd555a99aeb80542ae811327435f4) **4. Inspect a delivery** Click the eye icon on a row to see the HTTP status code your endpoint returned, the latency, the attempt number, and any error message. ![Event run details dialog showing webhook.test.v1, Success status, API response 200, latency 449 ms, and attempt 1](https://mintcdn.com/contraforce/-JmjqFAD1dEqopSD/images/webhooks/14-delivery-details.png?fit=max\&auto=format\&n=-JmjqFAD1dEqopSD\&q=85\&s=ec36d510f2d9a741e6cf4c748cad4f4d) The delivery log stores delivery metadata only, not the body that was sent. For incident events, the details show the incident as it is now, fetched from the source. See [Delivery logs](/api-reference/webhook-events#delivery-logs). ## Manage an existing webhook Everything below is on the webhook's **General** tab unless noted. | To do this | Do this | | - | - | | Stop deliveries temporarily | Click **Pause**. Click **Resume** to start again. | | Change the name, URL, events, or workspaces | Edit the field, then click **Save changes**. | | Rotate credentials | Click **Update credentials** in the **Authentication** section. Existing credentials are never shown. | | Rotate the signing secret | Click **Regenerate** in the **Signing secret** section, then update your endpoint with the new secret. | | Re-enable an auto-disabled webhook | Fix the endpoint, then click **Enable**. A webhook is disabled automatically after 5 or more distinct incidents fail final delivery within 24 hours. | | Resend a failed incident delivery | On the **Events** tab, open the failed entry and redeliver it. See [Redelivery](/api-reference/webhook-events#redelivery). | | Remove the webhook | Click **Delete**. | ## Send agent verdicts to a webhook The **Agent investigation completed** event (`agent.investigation.completed.v1`) is not a subscription. It fires only when an agent's classification card names this webhook as its custom action. You can create the webhook from the card itself, and it is subscribed to the event automatically when you save. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) to set it up, and [Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook) for the payload. ## Troubleshooting | Symptom | Likely cause | Fix | | - | - | - | | **Save** reports the URL is invalid | The URL is plain HTTP, `localhost`, or a private address | Use a public HTTPS endpoint. | | Test delivery shows **Failed** with `401` or `403` | Your endpoint rejected the credentials | Click **Update credentials** and re-enter them, then send another test. | | Delivery shows **Failed** with a timeout | Your endpoint took longer than 30 seconds | Return a `2xx` immediately and process the event asynchronously. | | Your endpoint rejects the signature | The wrong secret, or the body was parsed before verifying | Verify against the raw request body with the current secret. See [Verifying the Signature](/api-reference/webhook-events#verifying-the-signature). | | No events arrive, but tests succeed | The event is not turned on, or the workspace is not in the webhook's list | Check **Event subscriptions** and **Workspaces** on the **General** tab. | | The webhook status is **Disabled** | Repeated final delivery failures triggered auto-disable | Fix the endpoint, send a test, then click **Enable**. | ## Related guides > **[Webhook Event Reference](/api-reference/webhook-events)** > > Every event type, the delivery envelope, headers, retries, and signature verification. > **[Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook)** > > Receive and verify agent verdicts from a classification card. > **[Service Accounts](/guides/general-support/service-accounts)** > > Call the ContraForce API from your automation. > **[Incident Classification](/concepts/incident-classification)** > > The classifications and reasons carried on closed incidents. > [!NOTE] > > Need help? Contact [support@contraforce.com](mailto:support@contraforce.com). # How the CrowdStrike Falcon Integration Works Source: https://docs.contraforce.com/guides/technical/crowdstrike-falcon-integration See how CrowdStrike Falcon detections become ContraForce incidents, what the EDR, XDR, and NG-SIEM tiers unlock, and how Falcon retention limits your data. ContraForce integrates with CrowdStrike Falcon to bring every Falcon detection into the unified Command Dashboard as a ContraForce incident, and to power Gamebook response actions on Falcon-managed devices. The integration is split across two CrowdStrike API clients — one for ingestion, one for response — so each client carries only the scopes it needs. > [!NOTE] > > **Detection-first ingestion.** Each Falcon detection becomes its own ContraForce incident across every tier (EDR, XDR, NG-SIEM). Cases and automated leads are not surfaced as incidents — they are CrowdStrike's analyst- and AI-curated groupings over the underlying detections, and ingesting them too would either double-count the signal or leave detections that never roll into a case or lead as silent blind spots. A first-class **ContraForce Cases** primitive that sits above incidents (cross-source) is on the roadmap as separate work. > [!NOTE] > > This page describes **what the integration does** and **what the tier you pick on the configuration page unlocks**. For the step-by-step setup, see [CrowdStrike Falcon Detection and Response Modules](/guides/onboarding/crowdstrike-detection-and-response-modules). ## What the Integration Does > **Ingestion** > > Polls CrowdStrike's unified Alerts API on a continuous loop and surfaces every new Falcon detection in the Command Dashboard as a ContraForce incident. > **Investigation** > > Hydrates the detection with process tree, events timeline, device, and identity context drawn from CrowdStrike NG-SIEM and the alert payload itself. > **Status round-trip** > > Status changes you make in ContraForce (New → In Progress → Closed) PATCH back to CrowdStrike via the Alerts API. > **Owner assignment (with optional writeback)** > > Assigning a CrowdStrike incident in ContraForce always records the owner in the ContraForce audit log. If the workspace has a CrowdStrike service account bound on the Assignment Writeback card, the assignment is also PATCHed onto the underlying Falcon alert as that service account. See the callout below. > **Response actions** > > Powers the Contain, Lift Containment, and On-Demand Scan Gamebooks on Falcon-managed devices via the Response API client. > **Agents on queue** > > Triggers Security Delivery Agents on every CrowdStrike incident that lands in the unified pipeline. > [!NOTE] > > **Why owner assignment defaults to audit-only.** In MSSP topologies the ContraForce user (Entra UPN) frequently has no matching principal in the customer's CrowdStrike tenant, so pushing the assignment directly to Falcon either fails or lands on the wrong account. Recording the assignment locally lets every ContraForce user who can see the incident see the assigned owner without requiring a vendor-side identity match. The list view and the incident detail both hydrate the owner from the audit log on read. > > **The optional service-account writeback** lets you opt back into vendor-side visibility without giving up the MSSP-friendly default. You bind one Falcon user (typically a named service account in the customer's tenant) on the workspace's Assignment Writeback card; from then on every analyst assignment in ContraForce is mirrored onto the underlying alert as that bound user, and unassigning in ContraForce clears the Falcon-side assignee. The ContraForce audit log is still the source of truth for which analyst actually picked up the incident; the writeback only controls what the customer sees on the Falcon side. Writeback failures (Falcon outage, deleted user, missing scope) are logged but do not fail the ContraForce-side assignment, so the analyst queue stays responsive even when the vendor is degraded. *** ## Tier Selection — What You Pick on the Configuration Page When you configure the Detection module in ContraForce, you pick which Falcon **tier** the customer is licensed for. The tier you declare drives which scopes the API client needs and which advanced investigation surfaces (Process Tree ancestor walk, Events Timeline) unlock. **It does not change the ingestion shape** — every Falcon detection becomes its own ContraForce incident on every tier. There are three options: **Falcon Insight (EDR)** **For tenants on Falcon Insight (EDR) only.** Cases workbench is not available on this tier. | Behaviour | What you get | | - | - | | **Incidents table shape** | Each Falcon detection becomes its own incident | | **Case context** | Not available — Cases workbench doesn't exist on this tier | | **Process Tree** | Falls back to the alert payload's 3-level lineage (no NG-SIEM ancestor walk) | | **Events Timeline** | Falls back to the detection alerts on the device itself (no LogScale events) | | **Agents on queue / Gamebook auto-run** | Trigger on every detection | | **"Incidents Detected" metric** | Counts every detection ingested | **Falcon Insight XDR** **For tenants licensed for Falcon Insight XDR.** Cases workbench is active and used to resolve case context on detections that reference a case (and reserved for upcoming Cases features). | Behaviour | What you get | | - | - | | **Incidents table shape** | Each Falcon detection becomes its own incident (same as EDR) | | **Case context** | Available — case metadata can be resolved on detections that reference a case. Cases themselves are not surfaced as incidents (see the Detection-first ingestion note above) | | **Process Tree** | Falls back to the alert payload's 3-level lineage (NG-SIEM SKU is required for the ancestor walk) | | **Events Timeline** | Falls back to the detection alerts on the device itself | | **Agents on queue / Gamebook auto-run** | Trigger on every detection | | **"Incidents Detected" metric** | Counts every detection ingested | **Falcon NG-SIEM** **For tenants licensed for NG-SIEM.** Same detection-as-incident shape as the other tiers, plus the LogScale-backed Process Tree ancestor walk and the Events Timeline are unlocked. | Behaviour | What you get | | - | - | | **Incidents table shape** | Each Falcon detection becomes its own incident (same as EDR / XDR) | | **Case context** | Available — case metadata can be resolved on detections that reference a case. Cases themselves are not surfaced as incidents | | **Process Tree** | Full NG-SIEM ancestor walk via `ProcessRollup2` events on the `base_sensor` repository — surfaces System / smss.exe / winlogon.exe / userinit.exe / explorer.exe / etc. ancestors of the alerted process | | **Events Timeline** | Real Falcon EDR telemetry from `base_sensor` (process starts, DLL / library loads, registry / ASEP, file create / new executable / new script, DNS, network in/out, logon) scoped to the alert's process lineage | | **Agents on queue / Gamebook auto-run** | Trigger on every detection | | **"Incidents Detected" metric** | Counts every detection ingested | > [!TIP] > > The tier you declare must match the customer's actual Falcon SKU. The ingestion shape is the same on every tier — it's the **scopes** the API client needs and the **advanced investigation surfaces** that change. Picking NG-SIEM on a tenant that doesn't have the NG-SIEM SKU will produce missing-scope errors during Test Connection; picking EDR on an XDR / NG-SIEM tenant will leave the Process Tree ancestor walk and Events Timeline locked. ### How the Pipeline Works The ingestion shape is uniform across tiers — every Falcon detection becomes a ContraForce incident — and every downstream consumer reads from the same unified incident pipeline: | Stage | Behaviour | | - | - | | **Poller** (continuous) | Pulls alerts from CrowdStrike's Alerts API and filters out container types (cases, automated leads, legacy CrowdScore incidents) so only Falcon detections enter the pipeline | | **Interactive incidents-table query** | Same deny-list filter so what you see on a refresh matches what was queued | | **`IncidentDetected` audit / metric** | Written once per detection that enters the pipeline | | **Gamebook auto-run subscriber** | Triggers on every detection that lands in the pipeline | | **Agents on queue** | Same — agents trigger on every detection in the pipeline | The tier you declare on the configuration page only changes which scopes the API client needs and which advanced investigation surfaces unlock. It does not change the ingestion shape. *** ## Per-Product Allow-List Independent of the tier, each workspace can narrow ingestion to a subset of CrowdStrike's `product` values via the **Alert Types** card on the Detection module configuration page. Useful for MSSPs whose contract scope is narrower than the customer's full Falcon SKU. ### How the filter is applied The allow-list is enforced at every ingestion site so the queue, stats, agents, and Gamebook auto-run all see the same shape: | Site | Filter behaviour | | - | - | | **Poller** (continuous) | Drops alerts whose `product` is outside the allow-list before queueing to the unified pipeline | | **Interactive incidents-table query** | Same allow-list applied post-hydration so refresh matches the queue | | **Stats / "Incidents detected" metric** | Counts only alerts that pass the allow-list | | **Related-incidents-by-entity** | Same allow-list applied to related-incident search results | Detections from products outside the allow-list never reach the pipeline — they are dropped at the retriever / poller layer, not hidden in the UI. Re-enabling a product surfaces its detections from the next poll cycle onward; previously dropped detections are not back-filled. ### Persistence model | Stored value | Meaning | | - | - | | `null` (default for pre-existing workspaces) | "Ingest all products" — no narrowing applied | | Empty list | Same as `null` — friendly fallback when every box is unchecked | | Explicit list (e.g. `["epp", "idp"]`) | Ingest only the listed products; everything else is dropped | Changing the allow-list is **independent of credential save**. The Alert Types card has its own Save button and does not require Test Connection or Client Secret re-entry. ### Tier-driven shortlist The Alert Types card only shows the products typical for the declared tier by default to keep the UI compact: | Tier | Default checkbox shortlist | | - | - | | **Falcon Insight (EDR)** | `epp` | | **Falcon Insight XDR** | `epp`, `idp`, `xdr` | | **Falcon NG-SIEM** | All products (toggle hidden — no narrowing to do) | A "Show all products" toggle reveals the full catalog for non-standard SKU combos (e.g. EDR + Mobile add-on). The toggle auto-defaults to "show all" when the persisted selection already includes products outside the tier shortlist, so saved selections are never hidden. The shortlist is a UX hint rather than a hard licensing gate — the source of truth for tier-to-product availability still lives on the CrowdStrike side. ### Why a ContraForce-side filter CrowdStrike's OAuth scopes don't expose per-product granularity — the only available scope is `alerts.read` across all products. So the filter has to live in ContraForce code; we cannot narrow at the API-client level. *** ## Verification Panel After you click **Test Connection** on the configuration page, ContraForce runs a live probe of the API client and renders a verification panel below the form. The panel **doesn't override your tier choice** — it confirms the claim against what's actually present on the API client: | Indicator | Meaning | | - | - | | ✓ on **Cases workbench** | The Cases endpoint returned data — case context resolution will work on detections that reference a case | | ✗ on **Cases workbench** | Cases endpoint returned no data — add `Cases: Read + Write` to the API client and confirm the tenant has the workbench enabled. Detections still ingest normally without it; only case-context resolution is degraded | | ✓ on **NG-SIEM** | NG-SIEM is reachable; if the tenant has retention metadata, the panel shows the approximate `base_sensor` retention horizon | | ✗ on **NG-SIEM** (NG-SIEM tier picked) | Add `NGSIEM: Read + Write` to the API client and confirm the tenant has the NG-SIEM SKU before saving | | ℹ︎ on **NG-SIEM** (EDR / XDR tier picked) | NG-SIEM is reachable on this client but the declared tier doesn't use it; pick the NG-SIEM tier to unlock the Process Tree ancestor walk and Events Timeline | The verification panel is informational — you can save with a missing-required indicator, but the corresponding feature won't work until you add the scope and re-test. *** ## CrowdStrike Data Retention — How It Affects the Platform The data ContraForce surfaces from CrowdStrike is bounded by Falcon's own retention policy. The Falcon console may have access to additional historical data that ContraForce doesn't query. ### Where retention shows up in the platform | Surface | What's bounded | By what | | - | - | - | | **Detection Events Timeline** (NG-SIEM tier) | The events shown for a detection | The `base_sensor` repository's retention horizon on your Falcon NG-SIEM SKU. ContraForce reads this from the NG-SIEM `repos-metadata` endpoint at Test Connection / Save and persists it on the workspace; the Detection Events Timeline only queries within that window. | | **Process Tree ancestors** (NG-SIEM tier) | How far back the ancestor walk reaches | Same `base_sensor` retention. Ancestor processes that started before the retention window are missing from the tree. The Falcon console can sometimes show ancestors beyond this because it has access to repositories ContraForce doesn't query. | | **Detection visibility** | The earliest incident you can investigate in ContraForce | CrowdStrike's standard alert retention. Detections older than that no longer come back from the Alerts API at all. | | **Module configuration page** | How fresh the verification panel's NG-SIEM retention number is | The probe runs on Test Connection / Save. If retention has changed since you last saved, the displayed number may be stale until the next save. | ### What this means in practice > [!WARNING] > > **The Detection Events Timeline and Process Tree are subsets, not the full Falcon view.** ContraForce surfaces a banner above both surfaces on CrowdStrike incidents to remind you that the data shown is bounded by your tenant's NG-SIEM retention policy. If you need data beyond the retention window — older ancestors in the process tree, older events in the timeline — you must query the Falcon console directly. | Symptom you might see | Likely cause | | - | - | | Process tree stops at a process you'd expect to have a parent | Parent process started before the `base_sensor` retention horizon | | Events Timeline shows fewer events than the Falcon console for the same detection | Detection's process lifetime spans events older than the NG-SIEM retention window | | Detection Events Timeline is empty on the NG-SIEM tier | Either NG-SIEM scope is missing on the API client, or the tenant's retention is shorter than the alert's process lifetime — the verification panel and the saved retention horizon will tell you which | | Older incidents from a few months ago aren't accessible | The CrowdStrike Alerts / Cases retention has expired for those records on the tenant side | ### Tuning the retention horizon ContraForce does not control your CrowdStrike retention — it's set by the customer's NG-SIEM SKU. To change it: 1. Open the Falcon console 2. Navigate to **Next-Gen SIEM → Configuration → Settings → Data ingest** (path may vary by tenant) 3. Adjust the retention policy on the `base_sensor` repository according to your subscription terms 4. After the change takes effect, run **Test Connection** on the ContraForce configuration page so the new horizon persists on the workspace *** ## How the Pieces Fit Together ```mermaid theme={null} flowchart LR subgraph Falcon["CrowdStrike Falcon"] AlertsAPI[Alerts API] CasesAPI[Cases API] NGSIEM[NG-SIEM
base_sensor] Hosts[Hosts API] ODS[On-Demand Scans] end subgraph Iris["ContraForce"] Poller[Detection Poller] Pipeline[Unified Incident Pipeline] Dashboard[Command Dashboard] Insights[Entity Insights] Gamebooks[Gamebook Engine] Agents[Agents on Queue] Audit[Audit Log] end AlertsAPI -->|polls detections| Poller Poller -->|every detection| Pipeline Pipeline --> Dashboard Pipeline --> Agents Pipeline -->|IncidentDetected| Audit Pipeline -->|on new incident| Gamebooks Insights -->|process tree, events| NGSIEM Insights -->|case context| CasesAPI Gamebooks -->|Contain / Lift / Scan| Hosts Gamebooks -->|Scan| ODS Dashboard -->|owner read| Audit Dashboard -->|status / comments| AlertsAPI ``` The Detection API client carries the scopes for everything in the top-half (detection ingestion + investigation + case-context resolution + status writeback); the Response API client carries the scopes for the Hosts / ODS Gamebook actions in the bottom half. *** ## Related Documentation > **[CrowdStrike Falcon Detection and Response Modules](/guides/onboarding/crowdstrike-detection-and-response-modules)** > > Step-by-step setup with per-tier scope requirements > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > How Gamebook response actions work > **[Entity Insights](/entity-insights)** > > Investigation context for an incident's entities > **[Roles and Permissions](/guides/general-support/roles-and-permissions-reference)** > > Detailed role reference for ContraForce users *** > [!NOTE] > > Questions about the CrowdStrike Falcon integration? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Enterprise Application Permissions and App IDs Source: https://docs.contraforce.com/guides/technical/enterprise-applications Find each ContraForce enterprise application's app ID, Entra ID permissions, and admin consent needs, plus the Gamebook actions the response apps enable. ## Least-Privilege Application Model ContraForce uses a modular application architecture designed around the **principle of least privilege**. Rather than requesting all permissions through a single application, ContraForce distributes responsibilities across purpose-built enterprise applications registered in your Microsoft Entra ID tenant. Each application only receives the permissions necessary for its specific function. This means you only grant permissions for the capabilities you actually use. For example, if you don't use Gamebooks to respond to endpoint threats, you never need to consent the ContraForce Gamebooks for MDE application. > [!WARNING] > > **Consent model.** ContraForce enterprise applications are consented with **application (app-only)** Microsoft Graph permissions. Admin consent for Microsoft Graph application permissions must be granted by a **Global Administrator** or a **Privileged Role Administrator** — Cloud Application Administrator and Application Administrator cannot grant it. The role is required for the one-time consent only and is not retained; activate it just-in-time with Privileged Identity Management (PIM) and deactivate afterward. > > Because actions run as the application (no signed-in user required), operator control is enforced through **Gamebook approval gates** — only Workspace Owners can approve high-impact actions — and a complete **audit trail** in the Gamebooks History page. ## Quick Reference | Application | App ID | Required For | Consent Timing | | - | - | - | - | | ContraForce API | `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` | All deployments | First sign-in (core app consent) | | ContraForce Portal | `8b7cb435-9526-47ee-b79a-34433f0daad2` | All deployments | First sign-in (core app consent) | | ContraForce for MDE | `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` | Endpoint visibility | Module consent | | ContraForce Gamebooks for MDE | `ad7b0e79-3c37-4408-bf8f-eb89522cc920` | Endpoint response actions | Module consent | | ContraForce Gamebooks for Identity | `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` | User response actions | Module consent | | ContraForce Gamebooks for Email | `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` | Email response actions | Module consent | | ContraForce Sentinel Hunting | `6bf1c74d-7ade-4671-a507-166936f89a1f` | Log search & threat hunting | Module consent (XDR + SIEM only) | ## Applications by Module **All Deployments** Every ContraForce deployment requires these two core applications: * **ContraForce API** — Core platform connectivity * **ContraForce Portal** — User authentication and portal access **Defender Module** Core applications plus: * **ContraForce for MDE** — Endpoint visibility and incident data * **ContraForce Gamebooks for MDE** — Endpoint response actions * **ContraForce Gamebooks for Identity** — User response actions * **ContraForce Gamebooks for Email** — Email response actions **XDR + SIEM Module** Everything in XDR, plus: * **ContraForce Sentinel Hunting** — Log Analytics queries and threat hunting *** ## Core Applications ### ContraForce API The core service principal that enables communication between ContraForce services and Microsoft APIs including Microsoft Graph and Azure Resource Manager. This application coordinates all platform operations — from onboarding your workspace to managing Azure resources. **App ID:** `24d97bc0-8f2b-45d5-8e0b-7fe286732ef2` #### Delegated Permissions | Permission | Admin Consent | Purpose | | - | - | - | | `offline_access` | No | Enables refresh token acquisition for persistent sessions | | `profile` | No | Retrieves signed-in user's name and object ID | | `Application.Read.All` | Yes | Evaluates which ContraForce service principals have been consented | | `RoleManagement.Read.All` | Yes | Evaluates user roles for Portal access control | | `RoleManagement.ReadWrite.Directory` | Yes | Assigns the password-reset directory role to the *Gamebooks for Identity* app when a customer enables the service-provider password reset add-on | | `User.Read.All` | Yes | Reads user profile data for user management operations | | `user_impersonation` (Azure Service Management) | No | Used throughout platform operation, not only at onboarding: backs Microsoft Sentinel access; enumeration of subscriptions, resource groups, and identity role assignments; and, with AI Agents, reading model capacities and quotas and pushing agent model and harness updates | *** ### ContraForce Portal Handles user authentication through Microsoft's OpenID Connect implementation and retrieves basic profile information for signed-in users. This application enables secure sign-in to ContraForce using your Microsoft work account. **App ID:** `8b7cb435-9526-47ee-b79a-34433f0daad2` #### Delegated Permissions | Permission | Admin Consent | Purpose | | - | - | - | | `offline_access` | No | Enables refresh token acquisition | | `openid` | No | Allows sign-in using OpenID Connect | | `profile` | No | Retrieves signed-in user's name and object ID | *** ## Detection & Visibility Applications ### ContraForce for MDE (Microsoft Defender for Endpoint) Provides visibility into Microsoft Defender for Endpoint data, enabling endpoint monitoring, incident ingestion, and threat intelligence display in the ContraForce portal. This application provides device health, alert, and security posture data from Defender for Endpoint. To grant, verify, or revoke its consent, see [Defender for Endpoint Permissions and Consent](/defender-for-endpoint-module). **App ID:** `6efccc6a-f0d3-49e5-92d0-17d4afa9ba52` > [!NOTE] > > Requires Microsoft Defender for Endpoint to be deployed and active in the target tenant. Compatible with Microsoft 365 Business Premium, E3, E5, or standalone MDE licenses. #### Delegated Permissions | Permission | API | Admin Consent | Purpose | | - | - | - | - | | `ThreatHunting.Read.All` | Microsoft Graph | Yes | Enables threat hunting queries | | `SecurityAlert.Read.All` | Microsoft Graph | Yes | Displays security alerts | | `SecurityIncident.Read.All` | Microsoft Graph | Yes | Displays security incidents | | `SecurityIncident.ReadWrite.All` | Microsoft Graph | Yes | Manages security incidents | | `Incident.Read` | Microsoft Threat Protection | Yes | Reads threat protection incidents | | `Incident.ReadWrite` | Microsoft Threat Protection | Yes | Manages threat protection incidents | | `AdvancedHunting.Read` | Microsoft Threat Protection | Yes | Queries raw event and incident data | | `Alert.Read` | WindowsDefenderATP | Yes | Displays Defender alerts | | `Machine.Read` | WindowsDefenderATP | Yes | Retrieves endpoint profile details | | `Score.Read` | WindowsDefenderATP | Yes | Displays Threat and Vulnerability Management scores | | `Vulnerability.Read` | WindowsDefenderATP | Yes | Displays vulnerability information | | `File.Read.All` | WindowsDefenderATP | Yes | Read file profiles | #### Application Permissions | Permission | API | Admin Consent | Purpose | | - | - | - | - | | `SecurityAlert.Read.All` | Microsoft Graph | Yes | Displays security alerts | | `SecurityIncident.Read.All` | Microsoft Graph | Yes | Displays security incidents | | `SecurityIncident.ReadWrite.All` | Microsoft Graph | Yes | Manages security incidents | | `ThreatHunting.Read.All` | Microsoft Graph | Yes | Enables threat hunting queries | | `Incident.ReadWrite.All` | Microsoft Threat Protection | Yes | Manages threat protection incidents | | `Incident.Read.All` | Microsoft Threat Protection | Yes | Reads threat protection incidents | | `AdvancedHunting.Read.All` | Microsoft Threat Protection | Yes | Queries raw event and incident data | | `Alert.Read.All` | WindowsDefenderATP | Yes | Displays Defender alerts | | `Machine.Read.All` | WindowsDefenderATP | Yes | Retrieves endpoint profile details | | `Vulnerability.Read.All` | WindowsDefenderATP | Yes | Displays vulnerability information | | `Score.Read.All` | WindowsDefenderATP | Yes | Displays Threat and Vulnerability Management scores | | `File.Read.All` | WindowsDefenderATP | Yes | Read file profiles | *** ### ContraForce Sentinel Hunting Calls the Log Analytics API to send direct queries to a Microsoft Sentinel workspace on behalf of the signed-in user. This enables deeper incident context via raw event and evidence logs, and powers the Advanced Hunting page in ContraForce. **App ID:** `6bf1c74d-7ade-4671-a507-166936f89a1f` > [!NOTE] > > Only required for the **XDR + SIEM module**. Not needed for XDR-only deployments. #### Delegated Permissions | Permission | API | Admin Consent | Purpose | | - | - | - | - | | `Data.Read` | Log Analytics API | Yes | Queries Log Analytics workspace data for incident evidence and threat hunting | *** ## Response Applications (Gamebooks) These enterprise applications enable Gamebook response actions. Each application is scoped to a specific entity type, ensuring least-privilege access for automated incident response. ### ContraForce Gamebooks for MDE Enables automated response actions targeting **endpoint entities**, including device isolation, antivirus scans, and file quarantine operations. **App ID:** `ad7b0e79-3c37-4408-bf8f-eb89522cc920` #### Delegated Permissions (on-behalf-of flows) | Permission | Admin Consent | Purpose | | - | - | - | | `Machine.Isolate` | Yes | Isolates endpoints from the network | | `Machine.Offboard` | Yes | Offboards endpoints from Defender | | `Machine.Scan` | Yes | Initiates Microsoft Defender Antivirus scans | | `Machine.StopAndQuarantine` | Yes | Stops file execution and quarantines malicious files | | `Machine.ReadWrite` | Yes | Read and write machine information | | `User.Read` | Yes | Sign in and read user profile | #### Application Permissions (Default) | Permission | Admin Consent | Purpose | | - | - | - | | `Machine.Isolate` | Yes | Isolates endpoints without user presence | | `Machine.Scan` | Yes | Initiates scans without user presence | | `Machine.StopAndQuarantine` | Yes | Quarantines files without user presence | | `Machine.ReadWrite.All` | Yes | Read and write all machine information | | `Machine.Offboard` | Yes | Offboards endpoints from Defender | > [!TIP] > > **Service Provider Mode:** Application permissions enable MSPs/MSSPs to execute endpoint response actions in customer tenants without requiring a user to be actively signed in. For each module, click **Consent** on the workspace **Modules** tab to grant these permissions. #### Enabled Gamebook Actions | Action | Description | | - | - | | Isolate Device | Disconnects the endpoint from the network while maintaining Defender connectivity | | Unisolate Device | Restores full network connectivity to a previously isolated endpoint | | Quick Scan | Initiates a quick antivirus scan on the endpoint | | Full Scan | Initiates a comprehensive antivirus scan on the endpoint | | Quarantine File | Stops a file from executing and quarantines it | | Offboard Device | Removes the endpoint from Defender for Endpoint management | *** ### ContraForce Gamebooks for Identity Enables automated response actions targeting **user entities**, including session invalidation, account lockout, password reset, and MFA reset capabilities. **App ID:** `36b0d51c-4c0f-4810-9cc4-bfbd40c7dd4a` #### Delegated Permissions (on-behalf-of flows) | Permission | Admin Consent | Purpose | | - | - | - | | `User.ReadWrite.All` | Yes | Invalidates user sessions and locks accounts | | `UserAuthenticationMethod.ReadWrite.All` | Yes | Resets user passwords and removes a user's registered MFA methods (Reset MFA) | | `User.ReadWrite` | Yes | Read and write access to user profile | | `User.Read` | Yes | Sign in and read user profile | | `User.EnableDisableAccount.All` | Yes | Enable and disable user accounts | | `Directory.Read.All` | Yes | Read directory data | | `AuditLog.Read.All` | Yes | Read audit log data | #### Application Permissions (Default) | Permission | Admin Consent | Purpose | | - | - | - | | `User.ReadWrite.All` | Yes | Enables automated session invalidation and account lockout without user presence | | `User.EnableDisableAccount.All` | Yes | Enable and disable user accounts | | `Directory.Read.All` | Yes | Read directory data | | `AuditLog.Read.All` | Yes | Read all audit log data | | `RoleManagement.Read.Directory` | Yes | Read all directory RBAC settings | #### Application Permissions (Service Provider Password Reset add-on) These are consented **only if** a customer enables the optional **service-provider password reset** add-on (Identity module → **Allow service provider to reset passwords**). The add-on lets the **Reset Password** Gamebook run app-only, without an on-behalf-of signed-in user. Enabling it is a customer decision and must be authorized by a **Global Administrator** or **Privileged Role Administrator** in the customer tenant. | Permission | Admin Consent | Purpose | | - | - | - | | `User-PasswordProfile.ReadWrite.All` | Yes | Sets a new password on a user's `passwordProfile` so Reset Password can run app-only | > [!WARNING] > > **Directory role grant.** Enabling the add-on also assigns the **Authentication Administrator** Entra directory role to the *ContraForce Gamebooks for Identity* service principal in your tenant. This is a privileged role: it allows password and authentication-method management for **non-administrator** users only — it **cannot** reset passwords for Global Administrators or other higher-privileged roles, and a pre-flight check blocks those targets. The assignment is made only with explicit customer consent, and turning the add-on off removes it. > > Because this grant is a **directory role** rather than a Microsoft Graph application permission, it does **not** appear in the enterprise-app permission audit scripts. See [Auditing Enterprise App Permissions](/guides/technical/auditing-enterprise-app-permissions#directory-role-assignments) for how to review it. > [!NOTE] > > When the add-on is **not** enabled, **Reset Password** runs through the **delegated** (on-behalf-of) flow and requires a signed-in user with sufficient privileges. The modern Graph `resetPassword` endpoint does not support application-only calls, so app-only resets use the `passwordProfile` path enabled by the add-on above. #### Enabled Gamebook Actions | Action | Description | | - | - | | Disable Account | Blocks the user from signing in to any Microsoft service | | Enable Account | Restores sign-in access for a previously disabled account | | Reset Password | Generates a new temporary password for the user | | Reset MFA | Deletes the user's registered multi-factor authentication methods, forcing re-registration at next sign in | | Revoke Sessions | Invalidates all active refresh tokens and session cookies | *** ### ContraForce Gamebooks for Email (Microsoft 365 Response) Facilitates email response actions through the delete email Gamebook. This application can delete malicious emails from user mailboxes and purge phishing messages across the organization. **App ID:** `44dbf6fe-45e3-48a3-bac3-f8d4cf1dba6d` #### Delegated Permissions | Permission | Admin Consent | Purpose | | - | - | - | | `Mail.ReadWrite` | No | Allows the app to create, read, update, and delete mail in all mailboxes without a signed-in user. Does not include permission to send mail. | #### Application Permissions | Permission | Admin Consent | Purpose | | - | - | - | | `Mail.ReadWrite` | Yes | Allows the app to create, read, update, and delete mail in all mailboxes without a signed-in user. Does not include permission to send mail. | > [!NOTE] > > This application does **not** have the ability to send email. It requires Microsoft 365 Exchange licenses to be active in the target tenant. #### Enabled Gamebook Actions | Action | Description | | - | - | | Soft Delete Email | Removes a malicious or suspicious email from the user's mailbox | *** ## Managing Users and Groups Group-to-workspace mapping is managed directly in the ContraForce portal under **Settings → User Management**. ContraForce no longer provisions a separate User Management enterprise application for group management. To sync the people and groups you assign in Microsoft Entra ID to ContraForce automatically, see [Setting Up SCIM Provisioning](/guides/technical/scim-provisioning). *** ## Permission Types Explained ContraForce uses two types of Microsoft Entra ID permissions: | Type | Description | Use Case | | - | - | - | | **Application (app-only)** | Runs without a user context. The application acts with its own identity. | The default for ContraForce enterprise applications — automated investigation and response actions that execute without a signed-in user | | **Delegated** | Runs on behalf of a signed-in user. The application can only do what the signed-in user has permission to do. | Portal sign-in (OIDC) and the specific on-behalf-of flows that require a user, such as password reset | ContraForce enterprise applications are consented with **application (app-only)** permissions, so response actions can execute in a customer tenant without requiring an operator to be signed in. Because these actions run unattended, operator control is enforced through **Gamebook approval gates** and a complete **audit trail** in the Gamebooks History page. A small number of flows use delegated permissions with a signed-in user — for example, **password reset** runs on-behalf-of by default, unless a customer enables the **service-provider password reset** add-on, which lets it run app-only via a customer-consented `passwordProfile` permission and directory role (see [ContraForce Gamebooks for Identity](#contraforce-gamebooks-for-identity)). *** ## Managing Permissions After onboarding, you can review and manage enterprise application permissions in two locations: **From the ContraForce Portal:** Navigate to **Settings → Enterprise Apps** to review consent status for the core ContraForce apps and reconsent them. Module apps are consented from each module's page under **Workspaces → \[workspace] → Modules**. **From Microsoft Entra Admin Center:** Go to **Enterprise Applications** to review all ContraForce applications registered in your tenant and their granted permissions. *** ## Revoking Consent If you need to revoke consent for any ContraForce enterprise application: 1. Go to **Azure Portal → Microsoft Entra ID → Enterprise Applications** 2. Find the ContraForce application you want to revoke 3. Click **Properties** 4. Set **Enabled for users to sign-in** to **No** (to disable) or **Delete** the application entirely > [!WARNING] > > Revoking consent will disable the associated ContraForce capabilities for that workspace. For example, revoking the ContraForce for MDE application will stop Defender for Endpoint device and incident data from appearing in ContraForce. To remove ContraForce from your tenant entirely, including its Azure resources and role assignments, follow the [Offboarding Procedure](/guides/general-support/offboarding-contra-force). *** ## Troubleshooting | Issue | Likely Cause | Resolution | | - | - | - | | Consent popup doesn't appear | Pop-up blocker active | Disable pop-up blocker for `portal.contraforce.com` | | Consent fails with permissions error | Insufficient privileges | Verify the account has the **Global Administrator** or **Privileged Role Administrator** role. Admin consent for Microsoft Graph application permissions cannot be granted by Cloud Application Administrator or Application Administrator | | Application shows "Not Configured" | Consent flow incomplete | Re-run consent from workspace settings (gear icon) | | Gamebook actions unavailable | Service principal not consented | Consent the relevant Gamebooks application for the entity type | | Defender for Endpoint data missing | MDE application not consented | Consent the ContraForce for MDE application | *** ## Related Resources > **[Audit Permissions](/guides/technical/auditing-enterprise-app-permissions)** > > Independently verify enterprise application permissions in your tenant > **[Platform Permissions & Consent](/guides/getting-started/platform-permissions-and-consent)** > > Which admin roles can grant core consent at sign-in and module consent later > **[Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Step-by-step guide to onboarding your parent workspace > **[Customer Workspace Onboarding](/onboarding-customer-workspaces)** > > Onboard customer workspaces with the right modules > **[Azure Resources Deployed](/guides/technical/azure-resources-deployed)** > > Complete reference of all Azure resources ContraForce deploys > **[Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > ContraForce platform roles and what each can do Questions about enterprise applications or permissions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Defender for Endpoint Capability Matrix by License Source: https://docs.contraforce.com/guides/technical/microsoft-defender-capability-matrix Check which ContraForce features you get with Defender for Endpoint on Business Premium, E3, or E5, and which need Plan 2, Entra ID, Sentinel, or Exchange. This capability matrix details which ContraForce features are available for Microsoft Defender for Endpoint based on your Microsoft 365 license tier. Use this reference to understand what capabilities you can leverage and what dependencies may apply. > [!NOTE] > > This matrix only covers the **Microsoft Defender for Endpoint module** capabilities. ## Understanding the Matrix ### Legend | Symbol | Meaning | | :-: | - | | ✓ | Capability fully available | | ✓(1) | Requires Microsoft Entra ID connection | | ✓(2) | Requires Microsoft Sentinel connection | | ✓(3) | Requires Defender for Endpoint Plan 2 | | ✓(4) | Requires Microsoft 365 Exchange license | | — | Not available | ### License Tiers > **Business Premium** > > Small/medium business license with Defender for Business > **Enterprise E3** > > Enterprise license with Defender for Endpoint P1 > **Enterprise E5** > > Full enterprise license with Defender for Endpoint P2 To see which licenses and endpoints a specific workspace has, open the **Environments** tab on its settings page. See [Workspace Environments](/guides/getting-started/workspace-environments). *** ## Incident Investigation Core capabilities for investigating security incidents detected by Microsoft Defender for Endpoint. ### Incident Management | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Bi-directional streaming of incidents | ✓ | ✓ | ✓ | | Fetching incident entities | ✓ | ✓ | ✓ | | Fetching incident evidence (logs) | ✓ | ✓ | ✓ | | Incident alert timelines | ✓ | ✓ | ✓ | | Incident investigation audit | ✓ | ✓ | ✓ | > [!TIP] > > All core incident management features are available across all license tiers. ContraForce provides full incident visibility regardless of your Microsoft 365 license. *** ## Entity Enrichment & Triage Capabilities for enriching entity data and correlating related incidents during investigation. ### User Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Related incident search | ✓ | ✓ | ✓ | | Sign-in logs | ✓(1) | ✓(1) | ✓(1) | | Audit logs | ✓(1) | ✓(1) | ✓(1) | | Entra ID profile | ✓(1) | ✓(1) | ✓(1) | > [!NOTE] > > **(1)** User insights require Microsoft Entra ID to be connected to ContraForce. Consent the appropriate enterprise applications during onboarding. ### IP Address Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Sign-in log activity | ✓(2) | ✓(2) | ✓(2) | | Related incidents | ✓(3) | ✓(3) | ✓ | > [!NOTE] > > **(2)** IP sign-in activity requires Microsoft Sentinel connection (XDR + SIEM module). > > **(3)** Some IP insights require Defender for Endpoint Plan 2 on Business Premium and E3. ### Device Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Device info | ✓ | ✓ | ✓ | | Device timeline | ✓(3) | ✓(3) | ✓ | | Related incidents | ✓(3) | ✓(3) | ✓ | > [!NOTE] > > **(3)** Device timeline and related incidents require Defender for Endpoint Plan 2 add-on for Business Premium and E3 licenses. ### Email Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Related incidents | ✓ | ✓ | ✓ | | Email info | ✓(3) | ✓(3) | ✓ | ### File Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Related incidents | ✓ | ✓ | ✓ | | File info | ✓ | ✓ | ✓ | ### URL Insights | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Related incidents | ✓ | ✓ | ✓ | | URL info | ✓(3) | ✓(3) | ✓ | *** ## Log Search Advanced hunting and log query capabilities. | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Log search (Advanced Hunting) | ✓(3) | ✓(3) | ✓ | > [!WARNING] > > [Log search](/guides/getting-started/log-search) requires Defender for Endpoint Plan 2 for Business Premium and E3 licenses. E5 includes this capability natively. *** ## Endpoint Management Capabilities for managing and monitoring endpoints through ContraForce. | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | View device list | ✓ | ✓ | ✓ | | View device info | ✓ | ✓ | ✓ | > [!TIP] > > All endpoint visibility features are available across all license tiers. ContraForce surfaces all devices managed by Defender for Endpoint. *** ## Gamebook Response Actions Automated response capabilities organized by entity type. ### Endpoint Actions | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Isolate endpoint | ✓ | ✓ | ✓ | | Anti-virus scan of endpoint | ✓ | ✓ | ✓ | | Remove from isolation | ✓ | ✓ | ✓ | > [!NOTE] > > Endpoint Gamebook actions require the **Gamebooks for Microsoft Defender for Endpoint** enterprise application to be consented. ### File Actions | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Quarantine file | ✓ | ✓ | ✓ | ### User Actions | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Invalidate existing sessions | ✓(1) | ✓(1) | ✓(1) | | Reset user password | ✓(1) | ✓(1) | ✓(1) | | Lock out user | ✓(1) | ✓(1) | ✓(1) | | Unlock user | ✓(1) | ✓(1) | ✓(1) | > [!NOTE] > > **(1)** User Gamebook actions require Microsoft Entra ID connection and the **Gamebooks for Identity** enterprise application. ### IP Address Actions | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Block IP (Azure NSG) | — | — | — | > [!NOTE] > > IP blocking via Azure Network Security Groups is planned for future release. ### Email Actions | Capability | Business Premium | E3 | E5 | | - | :-: | :-: | :-: | | Soft delete email | ✓(4) | ✓(4) | ✓(4) | > [!NOTE] > > **(4)** Email actions require a Microsoft 365 Exchange license and the **Microsoft 365 Response** enterprise application. *** ## Dependencies Reference ### Dependency (1): Microsoft Entra ID **Required for:** User insights, User Gamebook actions **How to enable:** 1. During onboarding, consent the ContraForce enterprise applications 2. The Gamebooks for Identity service principal must be consented for user response actions **Enterprise Applications:** * ContraForce API * ContraForce Portal * Gamebooks for Identity ### Dependency (2): Microsoft Sentinel **Required for:** IP sign-in activity **How to enable:** 1. Deploy the XDR + SIEM module instead of XDR-only 2. Connect your Sentinel workspace during onboarding > **[Sentinel Onboarding](/guides/onboarding/microsoft-sentinel-module)** > > Complete Sentinel onboarding guide ### Dependency (3): Defender for Endpoint Plan 2 **Required for:** Device timeline, IP/Email/URL detailed insights, Log search **How to enable:** * E5 licenses include Plan 2 natively * Business Premium and E3 require the Defender for Endpoint Plan 2 add-on **License options:** | Base License | Add-on Required | | - | - | | Business Premium | Defender for Endpoint Plan 2 | | Enterprise E3 | Defender for Endpoint Plan 2 | | Enterprise E5 | Included | ### Dependency (4): Microsoft 365 Exchange **Required for:** Email Gamebook actions (soft delete) **How to enable:** 1. Ensure users have Exchange Online licenses 2. Consent the Microsoft 365 Response enterprise application > **[M365 Response Application](/guides/technical/enterprise-applications#contraforce-gamebooks-for-email-microsoft-365-response)** > > Microsoft 365 Response enterprise application details *** ## Complete Capability Summary ### By License Tier **Business Premium** **Full capabilities:** * All incident management features * Endpoint management (view devices) * All endpoint Gamebook actions * File quarantine * Basic entity insights **With Entra ID:** * User insights (sign-in, audit, profile) * User Gamebook actions **With Exchange:** * Email soft delete **Requires Plan 2 add-on:** * Device timeline * Advanced log search * Detailed IP/Email/URL insights **Enterprise E3** **Full capabilities:** * All incident management features * Endpoint management (view devices) * All endpoint Gamebook actions * File quarantine * Basic entity insights **With Entra ID:** * User insights (sign-in, audit, profile) * User Gamebook actions **With Exchange:** * Email soft delete **Requires Plan 2 add-on:** * Device timeline * Advanced log search * Detailed IP/Email/URL insights **Enterprise E5** **Full capabilities:** * All incident management features * Endpoint management (view devices) * All endpoint Gamebook actions * File quarantine * Device timeline * Advanced log search * All entity insights (IP, Email, URL, File) **With Entra ID:** * User insights (sign-in, audit, profile) * User Gamebook actions **With Exchange:** * Email soft delete ### Quick Reference by Feature Area | Feature Area | Dependencies | Notes | | - | - | - | | Incident Management | None | Full capability on all licenses | | Endpoint Management | None | Full capability on all licenses | | Endpoint Gamebooks | Gamebooks for Defender for Endpoint | Full capability on all licenses | | User Insights | Entra ID (1) | Same across all licenses | | User Gamebooks | Entra ID (1) + Gamebooks for Identity | Same across all licenses | | Device Timeline | Plan 2 (3) | Native on E5 | | Log Search | Plan 2 (3) | Native on E5 | | Email Actions | Exchange (4) + M365 Response | Same across all licenses | | IP Sign-in Activity | Sentinel (2) | Requires XDR + SIEM module | *** ## Maximizing Your Capabilities > **Connect Entra ID for user capabilities** > > User insights and user Gamebook actions are essential for identity-based investigations. Ensure you consent all identity-related enterprise applications during onboarding. > **Consider E5 or Plan 2 add-on for full visibility** > > If you frequently need device timelines, advanced hunting, or detailed entity insights, the Defender for Endpoint Plan 2 capabilities are worth the investment. > **Add Sentinel for comprehensive coverage** > > The XDR + SIEM module adds Sentinel incidents, advanced threat hunting, the in-workspace CMS for Sentinel analytics rules, and IP sign-in insights. Consider upgrading if you use Sentinel. > **Consent all relevant enterprise applications** > > Many capabilities require specific enterprise applications. Review the [Enterprise Applications Overview](/guides/technical/enterprise-applications) and consent all applications relevant to your needs. *** ## Related Guides > **[XDR Onboarding](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Deploy the Defender module > **[Enterprise Applications](/guides/technical/enterprise-applications)** > > All service principals and permissions > **[Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Response action capabilities > **[Defender for Endpoint Permissions and Consent](/defender-for-endpoint-module)** > > Permissions the Defender for Endpoint app needs, and how to grant or revoke consent > **[Defender Native Automations](/guides/technical/microsoft-defender-native-automations)** > > How AIR, ZAP, and attack disruption work alongside ContraForce *** > [!NOTE] > > Questions about capabilities or licensing? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Defender AIR, ZAP, and Attack Disruption Source: https://docs.contraforce.com/guides/technical/microsoft-defender-native-automations See what Defender AIR, ZAP, and attack disruption handle, how ContraForce shows their status per workspace, and how Security Delivery Agents defer to them. Many of your customers run Microsoft Defender with its native automations turned on. Those automations investigate, remediate, and even contain threats on their own, often before a ContraForce analyst or the Security Delivery Agent ever looks at the incident. This page explains what Defender's automations do by themselves, how ContraForce makes their status visible per Workspace, and where the Security Delivery Agent defers to them so no agent compute is spent on incidents Defender already resolved. > [!WARNING] > > Coordination today covers **incident dispatch**, not individual response actions. The agent stands down when Defender already handled an incident, but ContraForce does not yet re-check ZAP or containment state at the moment a Gamebook action runs. Part 2 marks exactly which behaviors are live and which are not. > [!NOTE] > > This is a reference page for service providers managing customer Workspaces. For setting up the Defender integration itself, see [Microsoft Defender for Endpoint Module](/defender-for-endpoint-module) and the [Microsoft Defender Capability Matrix](/guides/technical/microsoft-defender-capability-matrix). ## Part 1: Defender's Native Automations Microsoft Defender ships three distinct automation mechanisms. They trigger on different signals, act at different layers, and sit at opposite ends of the severity spectrum. Understanding which is which is the key to understanding how ContraForce coordinates with each. > **AIR** > > **Automated Investigation and Response.** Investigates alerts of specific types and applies or queues remediation. Frequently auto-resolves benign incidents. > **ZAP** > > **Zero-hour Auto Purge.** Retroactively quarantines or junks malicious mail already sitting in the mailbox, up to 48 hours after delivery. > **Attack Disruption** > > **Automatic Attack Disruption.** Contains active, high-confidence attacks at machine speed, without waiting for approval. ### Automated Investigation and Response (AIR) [AIR](https://learn.microsoft.com/defender-xdr/m365d-autoir) is triggered by **alert type, not by incident severity**. Defender launches an automated investigation when it sees alerts such as suspicious email, attachment, or URL activity; compromised-account signals; [Zero-hour Auto Purge](https://learn.microsoft.com/defender-office-365/zero-hour-auto-purge) actions; user submissions (user-reported phishing); user-click alerts; and suspicious mailbox behavior. An analyst can also start an investigation manually. Which alerts launch an investigation is driven by Defender's Threat-management alert policies, specifically those with **Automated investigation = Yes**. Once running, an investigation produces findings and recommended actions. Whether Defender applies remediation automatically or holds it for analyst approval depends on the tenant's [automation level](https://learn.microsoft.com/defender-endpoint/automation-levels): full automation remediates automatically, while semi-automation queues actions in the Action Center for approval. > [!NOTE] > > **AIR frequently auto-resolves benign incidents.** When an investigation finds no threat, Defender resolves the incident on its own. Microsoft notes this is a common outcome in user-submission scenarios, where a user reports a message as phishing and the investigation clears it. This is exactly the pattern ContraForce's settling window is designed for (see Part 2). > [!NOTE] > > **A Defender product change that does not affect the integration.** As of 2026-09-01, Microsoft is folding the standalone Defender for Endpoint AIR investigation experience into the default protection stack; it will no longer run as a separate investigation experience or be available for manual triggering in Defender for Endpoint. ContraForce reads incident and alert **state**, not AIR investigation objects, so this transition does not change how the integration behaves. AIR capabilities for Defender for Office 365 remain available. ### Zero-hour Auto Purge (ZAP), Defender for Office 365 [ZAP](https://learn.microsoft.com/defender-office-365/zero-hour-auto-purge) retroactively neutralizes phishing, spam, and malware email, and Microsoft Teams messages, that were already delivered to cloud mailboxes. Because spam and malware signatures update continuously, a message that was clean at delivery can be re-judged as malicious afterward. ZAP acts on that message **up to 48 hours after delivery**, across all cloud mailboxes. It is on by default for high-confidence phishing and malware. The action ZAP takes depends on the verdict and on the tenant's anti-spam, anti-malware, and anti-phishing policies: it may quarantine the message or move it to Junk Email. Like AIR, ZAP is driven by verdict and policy, **not by incident severity**. > [!WARNING] > > **ZAP has a long tail and a visibility gap.** Two facts shape how ContraForce coordinates with it: > > * **The 48-hour window is far longer than any dispatch delay.** A message can be purged well after an incident lands in ContraForce, so ZAP cannot be accounted for with a short settling delay alone. Accounting for it fully requires a re-check at the moment a remediation is about to run, which ContraForce does not perform today (see Part 2). > * **ZAP is not recorded in Exchange mailbox audit logs.** It is a system action visible through [Threat Explorer](https://learn.microsoft.com/defender-office-365/zero-hour-auto-purge#how-to-see-if-zap-moved-your-message) by filtering the **Additional action** column for the value **ZAP**. Allowlists and Exchange mail-flow (transport) rules can also override ZAP, so coverage is not uniform across a tenant. ### Automatic Attack Disruption (Defender XDR) [Automatic Attack Disruption](https://learn.microsoft.com/defender-xdr/automatic-attack-disruption) correlates signals across Defender XDR into a single high-confidence incident for active, sophisticated attacks: ransomware campaigns, business email compromise, and adversary-in-the-middle. It operates at the incident level and is inherently high severity. This is the opposite end of the spectrum from AIR's benign auto-resolutions. When Attack Disruption fires, it **contains the attack automatically, without approval, regardless of the tenant's automation-level settings**. Its [response actions](https://learn.microsoft.com/defender-xdr/automatic-attack-disruption#automated-response-actions) include: contain device, contain IP, isolate device, disable user (including Entra-only cloud-native accounts), revoke user sessions, and OAuth app containment. > [!WARNING] > > **Attack Disruption acts without approval and cannot be gated by automation level.** Because it contains live attacks at machine speed, there is no approval step to wait on and no automation setting that holds it back. Any coordinating system must assume the containment is already in effect. ContraForce never delays an attack-disruption incident: it is excluded from the settling window and the agent engages immediately. > > Note that ContraForce does not currently block a Gamebook action against an entity Defender has already contained. Containment state is surfaced for awareness, not enforced at action time, so analysts should check the Action Center before running a containment action on an attack-disruption incident. You can recognize an attack-disruption incident by several signals: the **Attack Disruption** incident tag in the queue and on the incident page, a **(attack disruption)** suffix appended to the incident title, the actions listed in the Action Center, and the [DisruptionAndResponseEvents](https://learn.microsoft.com/defender-xdr/advanced-hunting-disruptionandresponseevents-table) advanced-hunting table. ### Comparison at a Glance | Mechanism | What triggers it | What it does | Severity / scope | How ContraForce accounts for it | | - | - | - | - | - | | **AIR** | Specific alert types (suspicious email / URL / attachment, compromised account, ZAP, user submissions, user-click, suspicious mailbox behavior) or a manual analyst action | Runs an automated investigation, produces findings and recommended actions, applies or queues remediation, and auto-resolves incidents where no threat is found | Any severity; commonly low or benign (user-reported phishing) | Adaptive settling window on low-severity incidents, plus a pre-dispatch skip when AIR has already resolved or merged the incident | | **ZAP** | Updated spam / malware / phishing signals matching already-delivered mail or Teams messages, up to 48 hours after delivery | Retroactively quarantines or junks the message per the anti-spam, anti-malware, and anti-phishing policies | Not tied to incident severity; acts at the message level | Visibility only today. The Native Automations card reports whether ZAP is active in the tenant; ContraForce does not yet check ZAP before proposing an email remediation | | **Attack Disruption** | High-confidence correlation of XDR signals for an active, sophisticated attack (ransomware, BEC, adversary-in-the-middle) | Contains the attack without approval: contain device / IP, isolate device, disable user, revoke sessions, OAuth app containment | Inherently high severity; acts at the incident level | Never delayed. Attack-disruption incidents are excluded from the settling window, so the agent engages immediately | ## Part 2: How ContraForce Complements Defender's Automations ContraForce assumes Defender's automations are running and coordinates around them in two ways: it makes their status visible to you per Workspace, and it makes the Security Delivery Agent automation-aware at dispatch time so the agent does not investigate an incident Defender already closed. ### Visibility: The Defender XDR Module Configuration Tab The Defender XDR module's **Configuration** tab gives you a per-Workspace read on what Defender is actually doing, so you are not guessing whether a customer's automations are on. > **Native Automations card** > > A per-mechanism status for AIR, ZAP, and Attack Disruption: > > * **Active**, with an observed count and recency > * **Not observed**, meaning licensed (or licensing unknown) but no events in the probe window > * **Not licensed**, asserted only when the license read succeeded and the SKU is absent > * Before any probe has run, the card is empty and prompts you to click **Run detection** > > The status is derived by behavioral probing: Defender advanced hunting plus Microsoft Graph, using the consent already collected when the module was onboarded. The hunting and alert reads need no additional scope. > **Detected Products card** > > Two views of the customer's Defender footprint side by side: > > * **License truth:** which Defender products the Workspace is licensed for > * **Signal truth:** which products are actually emitting alerts > > Comparing the two surfaces "licensed but no signal" gaps, where a product is paid for but silent. > [!WARNING] > > **License truth requires one extra permission.** The license half of the Detected Products card reads Microsoft Graph `subscribedSkus`, which needs `Organization.Read.All` admin consent on the Defender app registration. Without it the probe degrades gracefully: the automation states still populate from hunting data, but license truth is unavailable and the "licensed but no signal" gap list is suppressed rather than guessed. An empty gap list therefore means either no gaps or no license read, so confirm consent before reading it as a clean bill of health. The probe runs automatically when the Defender module is consented at onboarding, and on demand whenever you click the **Run detection** button on the card. There is no scheduled background refresh today, so for a long-lived Workspace the card reflects the last time the probe actually ran. The **Last detected** timestamp under the card tells you how stale the reading is. ### An Automation-Aware Security Delivery Agent The Security Delivery Agent is built to defer to Defender's own automation at dispatch time. Two behaviors keep it from spending an investigation on work Defender already did. > [!NOTE] > > **"Not observed" does not disable the settling window.** Absence of evidence is not evidence of absence, so a mechanism the probe did not observe is still treated as possibly active. The gate stays conservative rather than assuming an automation is off. **1. Pre-dispatch skip: never act on an incident Defender already handled** Immediately before dispatching the agent, ContraForce re-checks the **live** Defender incident state. If the incident was resolved by AIR, or was merged or redirected into another incident, the agent is skipped entirely: no investigation runs, no agent compute is spent, and a **skipped: handled by Defender automation** entry is written to the Workspace activity log for auditability. You keep a clear record of why the agent stood down. **2. Adaptive settling window: give AIR time to auto-resolve quiet incidents** For **low and informational severity** Defender XDR incidents, ContraForce briefly holds the incident before running the agent, giving Defender's AIR a chance to auto-resolve it first (the common outcome for user-reported phishing). The length of the hold is derived per Workspace from how quickly that Workspace's incidents actually auto-resolve, bounded to between 5 and 30 minutes. **Medium and high severity incidents, and attack-disruption incidents, are never delayed**: the agent engages immediately. The window is set automatically from the probe. There is no manual override: the Native Automations card displays the current value as a read-only chip so you can see what the agent is waiting for. The net effect for you is that the agent does not investigate incidents Defender already resolved, and no agent compute is spent on them. > [!NOTE] > > **Not yet covered: ZAP dedup and containment guards at action time.** Both coordination points below are on the roadmap but are not implemented today. Neither the agent nor a Gamebook currently re-checks ZAP or Defender containment state before proposing a response action: > > * **ZAP.** Because ZAP acts up to 48 hours after delivery, an email remediation can be proposed for a message Defender already purged. ContraForce detects whether ZAP is active in the tenant, but does not check individual messages at action time. > * **Attack-disruption containment.** ContraForce does not block an action against an entity Defender has already contained. > > Until these ship, treat the Action Center as the source of truth before running an email or containment action on a Defender incident. ### Guidance for Service Providers > **Confirm what is licensed before you rely on it** > > Use the **Detected Products** card to confirm which Defender automations a customer is actually licensed for before you count on them to handle a class of incidents. A "licensed but no signal" gap means an automation you expect to fire may not be. > > Check that `Organization.Read.All` is consented first. Without it there is no license truth, and the gap list is suppressed rather than populated, so it will look clean whether or not gaps exist. > **Re-run detection after a customer changes their Defender configuration** > > The probe does not refresh on a schedule. If a customer enables an automation, changes licensing, or onboards a new Defender product, the card keeps showing the previous reading until someone clicks **Run detection**. Check the **Last detected** timestamp before treating the card as current. > **Know the division of labor across the three automations** > > Each Defender automation is covered differently today: > > * **AIR auto-resolution** is handled by the settling window plus the pre-dispatch skip. > * **ZAP** is detected for visibility only. There is no pre-action dedup at Gamebook time yet, so an email action can be proposed for a message ZAP already purged. > * **Attack Disruption** is never delayed and the agent engages immediately, but ContraForce does not block an action against an already-contained entity. ## What This Means for You * **Defender's automations run on their own terms.** AIR triggers on alert type and often auto-resolves benign incidents; ZAP purges bad mail up to 48 hours after delivery; Attack Disruption contains live attacks without approval. None of the three keys off ContraForce incident severity except in the sense that Attack Disruption is inherently high severity. * **ContraForce coordinates at the incident level.** The Configuration tab shows you what each automation is doing per Workspace, and the Security Delivery Agent defers to Defender through a pre-dispatch skip and an adaptive settling window. * **You save agent effort without losing coverage.** Low and informational severity incidents get a chance to auto-resolve before the agent spends compute on them, while medium, high, and attack-disruption incidents are engaged immediately. * **Action-level coordination is not there yet.** ZAP dedup and containment guards at Gamebook-action time are not implemented, so the Action Center remains the source of truth before running an email or containment action. ## Related Documentation > **[Microsoft Defender for Endpoint Module](/defender-for-endpoint-module)** > > Consent the module and enable Defender data and response in ContraForce > **[Microsoft Defender Capability Matrix](/guides/technical/microsoft-defender-capability-matrix)** > > Which ContraForce capabilities are available by Defender license tier > **[Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents)** > > How the Security Delivery Agent runs on the incident queue > **[What are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > How Gamebook response actions work *** > [!NOTE] > > Questions about how ContraForce coordinates with Microsoft Defender's native automations? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Microsoft Sentinel Incident Email Notifications Source: https://docs.contraforce.com/guides/technical/notifications-configuration Choose which Microsoft Sentinel incident severities send email notifications in each workspace, route them to distribution groups, and track Gamebook runs. ContraForce provides customizable email notifications for Microsoft Sentinel incidents, allowing you to configure alerts by severity level for each workspace. Keep your team informed about critical security events while filtering out noise. > [!NOTE] > > **Module Requirement:** Full notification customization is available with the **XDR + SIEM module**. The XDR-only module has limited notification capabilities (Gamebook notifications only). ## Notification Capabilities by Module | Feature | Defender Module | XDR + SIEM Module | | - | :-: | :-: | | Sentinel incident notifications | — | ✓ | | Severity-based filtering | — | ✓ | | Per-workspace customization | — | ✓ | | Gamebook completion notifications | ✓ | ✓ | | Distribution group support | — | ✓ | > [!WARNING] > > **Defender Module Users:** ContraForce does not generate email notifications for Defender for Endpoint incidents. Use Microsoft Defender's built-in notification settings for Defender alerts. Deploying ContraForce will not interrupt your existing Defender notification configuration. *** ## SIEM Notification Overview With the XDR + SIEM module, you can: > **Filter by Severity** > > Choose which incident severities trigger notifications—High, Medium, Low, or Informational > **Configure Per Workspace** > > Set different notification preferences for each customer workspace > **Use Distribution Groups** > > Route notifications to shared mailboxes or team distribution lists > **Direct Portal Access** > > One-click access to incidents directly from notification emails *** ## Configuring Notification Settings ### Accessing Settings **1. Open the Workspace** Select **Workspaces** in the left navigation and open the workspace you want to configure **2. Select Notifications** Select the **Notifications** tab, then the **Incidents**, **Gamebooks**, **Agent Runs**, or **SOPs** sub-tab ### Notification Settings Interface ![Workspace Notifications tab, Incidents sub-tab, with severity toggles and a Recipients list with an Add Recipient button](https://mintcdn.com/contraforce/KGdPGoMZjf7nE2PL/images/notifications-settings-interface.png?fit=max\&auto=format\&n=KGdPGoMZjf7nE2PL\&q=85\&s=bb3ad4f1029f43365ad4af96ef991407) The notification settings interface displays: | Element | Description | | - | - | | **Workspace Selector** | Choose which workspace to configure | | **Severity Toggles** | Enable/disable notifications per severity level | | **Recipient Display** | Shows current notification recipients | | **Save Button** | Apply changes to the selected workspace | *** ## Severity-Based Filtering Customize which severity levels generate email notifications for each workspace. ### Default Behavior By default, notifications are **enabled for all severity levels** when a workspace is onboarded: * ✅ High severity — Enabled * ✅ Medium severity — Enabled * ✅ Low severity — Enabled * ✅ Informational — Enabled ### Configuring Severities **1. Select Workspace** Choose the workspace from the dropdown **2. Toggle Severities** Click the toggle for each severity level to enable or disable **3. Save Changes** Click **Save** to apply your changes ![Incident created preferences with on/off toggles for High, Medium, Low and Info severities](https://mintcdn.com/contraforce/KGdPGoMZjf7nE2PL/images/notifications-severity-toggles.png?fit=max\&auto=format\&n=KGdPGoMZjf7nE2PL\&q=85\&s=c067d78db6733060a3489d53e2bd8125) ### Severity Level Guidance **High** **High severity incidents** indicate active threats requiring immediate response. **Examples:** * Active malware execution * Credential theft detected * Ransomware activity * Privilege escalation attacks **Recommendation:** Always keep enabled for all workspaces **Medium** **Medium severity incidents** indicate potential threats needing investigation. **Examples:** * Suspicious sign-in activity * Unusual data access patterns * Policy violations * Reconnaissance activity **Recommendation:** Enable for most workspaces; disable only if generating excessive noise **Low** **Low severity incidents** are often informational or low-risk events. **Examples:** * Minor policy alerts * Informational detections * Low-confidence alerts **Recommendation:** Enable based on team capacity and customer SLA **Informational** **Informational incidents** are typically audit events or very low-priority alerts. **Examples:** * Audit log events * Configuration changes * Informational notices **Recommendation:** Disable for most workspaces to reduce noise; enable only for compliance requirements *** ## Per-Workspace Configuration MSSPs managing multiple customers can configure different notification settings for each workspace. ### Use Cases | Scenario | Configuration | | - | - | | **Premium SLA customer** | All severities enabled | | **Standard SLA customer** | High and Medium only | | **Development/test workspace** | High only or disabled | | **Compliance-focused customer** | All severities including Informational | ### Configuring Multiple Workspaces **1. Configure First Workspace** Select workspace, set severity preferences, save **2. Switch Workspace** Use the dropdown to select the next workspace **3. Configure Settings** Adjust severity settings for this workspace **4. Repeat** Continue for all workspaces requiring custom settings > [!TIP] > > Document your notification configuration for each customer. This helps maintain consistency and simplifies troubleshooting when customers report notification issues. *** ## Email Notification Details ### Sender Address All ContraForce notifications are sent from: ``` noreply@notifications.contraforce.com ``` > [!NOTE] > > Add this address to your email allowlist and your customers' allowlists to ensure notifications aren't blocked by spam filters. ### Email Content Each incident notification email includes: | Field | Description | | - | - | | **Subject Line** | Incident title with severity indicator | | **Incident ID** | Unique identifier for tracking | | **Severity** | High, Medium, Low, or Informational | | **Description** | Summary of the security event | | **MITRE Tactics** | Associated ATT\&CK techniques | | **Entities** | Affected users, devices, IPs, etc. | | **View Incident Button** | Direct link to the incident in ContraForce | The **View Incident** button opens the incident directly in the ContraForce Portal, allowing immediate investigation and response. *** ## Distribution Group Notifications Route notifications to a team distribution list instead of individual users for better team visibility. ### Benefits > **Team Visibility** > > Entire SOC team sees all alerts in a shared inbox > **No Missed Alerts** > > Alerts aren't missed when individuals are unavailable > **On-Call Routing** > > Route to on-call rotation distribution groups > **Ticketing Integration** > > Use email-to-ticket systems for automatic tracking ### Setting Up Distribution Groups Distribution group notifications require setup assistance from ContraForce: **1. Identify Email Address** Determine the distribution group email address (e.g., `soc-alerts@yourcompany.example`) **2. Provide During Onboarding** Share the email address during initial workspace onboarding **3. Or Contact Support** For existing workspaces, email [support@contraforce.com](mailto:support@contraforce.com) **4. Engineering Configuration** ContraForce Engineering team configures the distribution group **5. Verification** Test that notifications are reaching the distribution group > [!NOTE] > > Distribution group changes require ContraForce support assistance. Self-service distribution group configuration is planned for a future release. ### Common Distribution Group Patterns | Pattern | Email Example | Use Case | | - | - | - | | **SOC Team Inbox** | [soc-team@company.example](mailto:soc-team@company.example) | Shared visibility for all analysts | | **Customer-Specific** | [customer-alerts@msp.example](mailto:customer-alerts@msp.example) | Dedicated inbox per customer | | **On-Call Rotation** | [oncall@company.example](mailto:oncall@company.example) | Routes to current on-call analyst | | **Ticketing System** | [tickets@company.example](mailto:tickets@company.example) | Auto-creates tickets in ITSM | *** ## Gamebook Notifications Gamebook notifications are available for **all modules** (XDR and XDR + SIEM). ### Gamebook Notification Events | Event | Notification Sent | | - | :-: | | Gamebook completed successfully | ✓ | | Gamebook execution failed | ✓ | | Gamebook requires approval | ✓ | | Gamebook approved/rejected | ✓ | ### Gamebook Email Content * Gamebook name and type * Target incident details * Actions executed * Execution status (Success/Failed/Pending) * Workspace name * Link to view details > [!TIP] > > Gamebook notifications help track automated response actions across your customer base, providing audit trails for compliance and visibility into response activity. *** ## Integration with External Tools ### Email-to-Ticket Integration Route notifications to ITSM platforms that support email-based ticket creation: | Platform | Setup Method | | - | - | | **ServiceNow** | Configure inbound email actions | | **Jira Service Management** | Use email request channel | | **Autotask** | Set up email-to-ticket rules | | **ConnectWise** | Configure email connector | | **Zendesk** | Use support email address | ### Microsoft Teams / Slack For real-time chat notifications: **1. Create Email-Enabled Channel** Set up an email address for your Teams channel or Slack workspace **2. Use as Distribution Group** Provide this email to ContraForce as your notification recipient **3. Receive in Chat** Notifications appear directly in your team chat *** ## Best Practices > **Start conservative, then expand** > > Begin with High severity only, monitor for a week, then gradually enable Medium and Low based on team capacity and incident quality. > **Match notifications to SLAs** > > Configure severity settings to match your SLA with each customer. Premium customers might get all severities; standard customers might only get High and Medium. > **Use distribution groups for team visibility** > > Individual email notifications risk being missed. Distribution groups ensure the entire team has visibility into alerts. > **Integrate with ticketing for tracking** > > Route notifications to your ITSM for automatic ticket creation, SLA tracking, and audit trails. > **Allowlist the sender address** > > Add `noreply@notifications.contraforce.com` to email allowlists for your organization and your customers. > **Review and tune periodically** > > Monthly review notification settings. If a severity level generates too much noise, consider disabling it while you tune detection rules. *** ## Troubleshooting ### Common Issues | Issue | Possible Cause | Solution | | - | - | - | | **Not receiving notifications** | Spam filter blocking | Add sender to allowlist | | **Not receiving notifications** | Wrong module deployed | Verify XDR + SIEM module is active | | **Not receiving notifications** | Severity disabled | Check notification settings | | **Not receiving notifications** | Distribution group issue | Contact support to verify configuration | | **Too many notifications** | All severities enabled | Disable Informational and Low | | **Delayed notifications** | Email server delays | Check your mail server; ContraForce sends in near real-time | | **Missing workspaces** | Permissions issue | Verify you have admin access to the workspace | ### Testing Notifications To verify notifications are working: **1. Check Settings** Confirm notification settings are enabled for the workspace **2. Verify Email Allowlist** Ensure the sender address isn't blocked **3. Wait for Incident** Wait for a new Sentinel incident (or ask ContraForce to send a test) **4. Check All Folders** Check inbox, spam, and junk folders **5. Verify Content** Confirm the email contains expected incident details *** ## Frequently Asked Questions > **What email address sends notifications?** > > All notifications are sent from `noreply@notifications.contraforce.com` > **Can I get notifications for Defender for Endpoint incidents?** > > No, ContraForce does not send notifications for Defender for Endpoint incidents. Use Microsoft Defender's built-in notification settings. ContraForce notifications are for Sentinel incidents (XDR + SIEM module) and Gamebook activity. > **How do I add a distribution group?** > > Contact [support@contraforce.com](mailto:support@contraforce.com) with the email address. The ContraForce Engineering team will configure it for your account. > **Can I customize the email template?** > > Email templates are standardized and cannot be customized. For custom formatting, route emails to a ticketing system that can transform them. > **Is there a notification delay?** > > Notifications are sent in near real-time when Sentinel incidents are processed. Typical delay is under 5 minutes from incident creation. > **Can different users get different notifications?** > > Currently, notifications are configured at the workspace level, not per-user. All recipients for a workspace receive the same notifications based on severity settings. > **Can I get SMS or push notifications?** > > ContraForce currently supports email only. For SMS or push, route email notifications to PagerDuty, Opsgenie, or similar services. *** ## Related Guides > **[Module Reference](/onboarding-customer-workspaces#module-reference)** > > Compare the detection and response modules > **[Sentinel Onboarding](/guides/onboarding/microsoft-sentinel-module)** > > Deploy the XDR + SIEM module > **[Incident Management](/guides/getting-started/incident-management)** > > Handling incidents from notifications > **[Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Automated response actions > **[Incident Deduplication](/guides/technical/parallel-incident-deduplication)** > > How duplicate Sentinel and Defender XDR incidents are kept out of your queue and notifications *** > [!NOTE] > > Questions about notifications? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Sentinel and Defender XDR Incident Deduplication Source: https://docs.contraforce.com/guides/technical/parallel-incident-deduplication See how ContraForce keeps duplicate Microsoft Sentinel and Defender XDR incidents out of your queue, notifications, agent runs, webhooks, and metrics. Microsoft keeps a Defender XDR incident and its Microsoft Sentinel counterpart synchronised, and presents them to you as one "parallel incident". ContraForce reads both APIs, so without a rule that same real-world incident arrives twice under two different vendor IDs. ContraForce resolves this **per incident**: it keeps the incident on the side it originated and discards the mirror. No configuration is required, and there is no toggle to set. > [!NOTE] > > Deduplication only applies to a workspace with **both** the Microsoft Defender XDR and Microsoft Sentinel detection modules connected. See [Detection module state](#detection-module-state). ## How ContraForce decides Both systems label the origin of an incident, and ContraForce reads those labels directly. There is no cross-API lookup, no correlation database, and no dependence on which copy arrives first. | Side | The incident is discarded when | | :- | :- | | Microsoft Sentinel | `providerName` is `Microsoft 365 Defender`, or is `Microsoft XDR` and the alert products are Defender-produced | | Microsoft Defender XDR | every alert on the incident has `serviceSource` of `microsoftSentinel` | | Either | Nothing else. Anything not positively identified as a mirror is kept. | That last row is deliberate. An unreadable label, an unfamiliar provider, or a provider call that fails all mean "show the incident". A duplicate is a visible annoyance; a discarded incident is silent data loss. ### The providerName values you will see | Value | Meaning | | :- | :- | | `Azure Sentinel` | Created in Sentinel. Never treated as a mirror. | | `Microsoft 365 Defender` | Forwarded into Sentinel by the Defender XDR connector. The Defender incident is the original. | | `Microsoft XDR` | The workspace is onboarded to the Defender portal, so both representations exist. The alert products decide the origin. | ## The three forwarding scenarios **Defender to Sentinel** The Defender XDR data connector in Microsoft Sentinel has **Connect incidents & alerts** enabled, so Defender incidents are pushed into Sentinel. Those forwarded copies carry `providerName` of `Microsoft 365 Defender`. * **Kept:** the Defender XDR incident, attributed to Defender. * **Discarded:** the Sentinel copy. * **Unaffected:** incidents created natively in Sentinel, which carry `Azure Sentinel` and are never mirrors. In the portal, an incident that originated in Defender shows **Microsoft Defender XDR** as its source, even though a copy also exists in your Sentinel workspace. **Sentinel to Defender** The Sentinel workspace is onboarded to the Microsoft Defender portal, so Sentinel analytic rules surface as Defender incidents. Those incidents carry `providerName` of `Microsoft XDR`, and their alerts have a `serviceSource` of `microsoftSentinel`. * **Kept:** the Sentinel incident, attributed to Sentinel. * **Discarded:** the Defender mirror. * **Unaffected:** genuinely Defender-produced incidents in the same workspace, which are kept and attributed to Defender. > [!NOTE] > > Incidents created manually, through the API, or by a playbook exist **only** in Sentinel even in a fully onboarded workspace. They carry `Azure Sentinel` and are always kept. This is why ContraForce deduplicates per incident rather than suppressing a whole source. **No forwarding** Neither connector is forwarding. Each system holds its own incidents and there are no mirrors. * **Kept:** everything, from both sources. * Nothing is discarded, and behaviour is identical to a workspace with a single detection module. A workspace can move into this state and back out of it without any configuration change in ContraForce, because the decision is made per incident at the time it arrives. > [!WARNING] > > Forwarding in **both** directions at once is common, not exceptional. A workspace onboarded to the Defender portal will typically show Sentinel-origin incidents in Defender **and** Defender-origin incidents in Sentinel. Because the rule is applied per incident, each one is resolved on its own evidence and the correct copy survives in both directions simultaneously. ## Detection module state Deduplication is only safe when ContraForce actually reads both systems. Before discarding a mirror, ContraForce checks that the **counterpart detection module is connected and enabled** on the workspace. | Workspace modules | Behaviour | | :- | :- | | Defender XDR **and** Sentinel | Deduplication applies in both directions. | | Defender XDR only | Nothing is discarded. A Sentinel-origin incident is the only copy ContraForce will ever fetch, so it is kept and attributed to Defender. | | Sentinel only | Nothing is discarded. A forwarded Defender incident is the only copy ContraForce will ever fetch, so it is kept and attributed to Sentinel. | | Neither | Not applicable. | > [!WARNING] > > Disabling one of the two detection modules changes deduplication behaviour immediately. A workspace that was discarding mirrors will start keeping them, because the counterpart is no longer being read. Incident volume in the queue will rise accordingly. This is correct: it is better to show a duplicate than to hide the only copy. ## Downstream effects The decision is made **once, at ingestion**, before any other processing occurs. A discarded mirror never becomes an incident in ContraForce, so it creates no state anywhere downstream. | Area | Effect on a discarded mirror | | :- | :- | | Incident queue | Never appears. Only the surviving copy is listed. | | Email notifications | None sent. Recipients receive one notification per real-world incident. | | Agent runs | Not triggered. An agent runs once, against the surviving incident. | | Gamebook auto-run | Not triggered. | | Webhooks | No event is delivered. Subscribers receive one event per real-world incident. | | Real-time portal updates | Not pushed. | | Audit trail | No **Incident Detected** entry is written. | | SLA tracking | No timer is started and no SLA state is created. | | Metrics and dashboards | Not counted. Incident counts, classification breakdowns, and closure statistics reflect real-world incidents rather than vendor records. | > [!NOTE] > > If your incident counts fell when this behaviour was introduced, that is the duplication being removed. The count now reflects distinct real-world incidents. Historical aggregates computed before the change still include the duplicates and are not retroactively corrected. ### Direct links still work Deduplication is applied when **listing** incidents, not when fetching one. A direct link to a mirrored incident still opens and displays it. This is intentional: a link shared in a ticket, an email, or a chat message continues to resolve rather than returning "not found". ## What this replaced Earlier versions of ContraForce offered a per-workspace toggle to suppress an entire source. That approach was withdrawn because it cannot be made correct: * A workspace commonly forwards in both directions, so there is no single source that is safely redundant. * Suppressing Microsoft Sentinel discards incidents that never reach Defender at all, including any created manually, through the API, by a playbook, or in a secondary workspace. The toggle no longer exists and no action is required. Any previously configured value is ignored. ## Troubleshooting > **I see the same incident twice** > > Confirm both detection modules are connected and enabled on the workspace. With only one connected, ContraForce keeps every incident by design. > > If both are connected, check the `providerName` on the Sentinel incident. A value other than the three listed above is not recognised as a mirror and the incident is kept deliberately, so that an unfamiliar label never causes data loss. > **An incident is attributed to the source I did not expect** > > Attribution follows origin, not arrival. An incident created by a Sentinel analytic rule is attributed to Sentinel even when it also appears in the Defender portal, and an incident created by Defender is attributed to Defender even when it also appears in your Sentinel workspace. > **An incident is missing from the queue** > > Deduplication never removes the last copy, so a missing incident is unlikely to be caused by it. Check the time filter first: the incident list filters on incident **creation** time, while the Microsoft Defender portal displays last activity time. An older incident with recent activity appears recent in Defender and falls outside a short creation-time window in ContraForce. *** ## Related Guides > **[Incident Management](/guides/getting-started/incident-management)** > > Triage, assign, investigate, and close incidents across your workspaces > **[Microsoft Sentinel Integration](/guides/onboarding/microsoft-sentinel-module)** > > Connect Microsoft Sentinel to a workspace and stream its incidents into ContraForce > **[SLA Tracking](/guides/getting-started/sla-tracking)** > > Set SLA targets per workspace and severity, then track response and resolution times > **[Setting Up Webhooks](/guides/technical/configure-webhooks)** > > Send signed incident webhooks to your ticketing system, SIEM, or chat tools > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Setting Up SCIM Provisioning Source: https://docs.contraforce.com/guides/technical/scim-provisioning Set up SCIM provisioning from Microsoft Entra ID so the people and groups you assign sync to ContraForce, then grant roles and workspace access by group. Directory sync connects your Microsoft Entra ID tenant to ContraForce over SCIM 2.0. Once it is set up, the people and groups you assign to the ContraForce application in Entra appear in ContraForce on their own, changes to their names and emails follow, and removing someone in Entra removes their access on the next sync. Entra decides **who** is in your organization and which groups they belong to. ContraForce decides **what** each group may do. New people start with the least privilege, and you grant more access to groups. > [!NOTE] > > **Who is this for?** Organization Admins and User Admins who manage access to ContraForce, together with whoever administers your Microsoft Entra tenant. Setting up the connection takes about 15 minutes. The first sync starts shortly after you turn provisioning on, and then repeats about every 40 minutes. ## Before you start * You are signed in to ContraForce as an **Org Admin** or a **User Admin**. Only an Org Admin can change the default role for provisioned people. * Your ContraForce plan includes **SCIM provisioning**. It is included with the Growth, Scale, and Enterprise plans, and is available as an add-on. Without it, the **Directory sync** tab shows what the feature includes and a way to contact sales. * In Microsoft Entra ID you can create enterprise applications and configure provisioning, for example as an **Application Administrator** or **Cloud Application Administrator**. * To assign **groups** to the application, your tenant needs Microsoft Entra ID P1 or P2. With Microsoft Entra ID Free you can assign people individually. ## Who decides what | | Set by Microsoft Entra ID | Set in ContraForce | | - | - | - | | Name, email and user name | Yes | No, locked for provisioned people | | Whether someone can sign in | Yes, through assignment to the application | Emergency removal only (see [Remove someone right away](#remove-someone-right-away)) | | Which groups someone is in | Yes | No, locked for provisioned groups | | Group names | Yes | No, locked for provisioned groups | | Organizational role | No | Yes: the default role, plus roles you grant to groups | | Workspace access | No | Yes: assign groups to workspaces | ## Step 1: Connect directory sync in ContraForce **1. Open the Directory sync tab** In the left navigation, click **Settings**, then select the **Directory sync** tab. Before you connect, it shows **Not connected**, what directory sync does, and the **Connect with SCIM** button. **2. Connect with SCIM** Click **Connect with SCIM**. ContraForce creates the connection and opens the **Copy your secret token** window with the **Tenant URL** and the **Secret token**. The window shows the token only once. ContraForce stores only a hash of it, so it cannot show it again. Copy both values with the copy buttons and keep them somewhere safe until you paste them into Entra in Step 2, then click **I've copied both**. > [!WARNING] > > Treat the secret token like a password. Anyone who holds it can add and remove people in your ContraForce organization. If it is lost or exposed, rotate it (see [Rotate the secret token](#rotate-the-secret-token)). **3. Check that directory sync is connected** The tab now shows **Connected**. **Provisioning activity** shows **No requests yet** until Entra makes its first request. ![Settings page with the Directory sync tab selected, showing the Connected status and the Provisioning activity card with No requests yet](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/01-directory-sync-tab.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=c4bf8587e3b962e50ed7eac444e6cb59) Below it, **Connection details** shows what you need in Entra: * **Tenant URL**: the SCIM address of your ContraForce region, ending in `/scim/v2`. Use the copy button next to it. * **Secret token**: shown masked, with its last four characters and the date it was issued, so you can tell which token Entra holds. * **Attribute mapping**: the one mapping you must set in Entra, `objectId` to `externalId`. ![Connection details card with the Tenant URL, the masked Secret token with its issue date and the Rotate token button, and the required objectId to externalId mapping, next to the Default role and Setup guide cards](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/02-directory-sync-connected.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=20a50a6bb315f9412bd3e388ecb37b41) ## Step 2: Create the ContraForce application in Microsoft Entra ID **1. Create a non-gallery enterprise application** In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Entra ID** > **Enterprise apps** and click **New application**. Click **Create your own application**, enter a name such as `ContraForce`, keep **Integrate any other application you don't find in the gallery (Non-gallery)** selected, and click **Create**. ![Create your own application panel in the Microsoft Entra admin center with the name ContraForce and the Non-gallery option selected](https://mintcdn.com/contraforce/Y5unOVlkOy69Ll37/images/scim-provisioning/03-entra-create-application.png?fit=max\&auto=format\&n=Y5unOVlkOy69Ll37\&q=85\&s=0f6751a1517ac89f9986316133a41260) > [!NOTE] > > When you type the name, Entra suggests applications from its gallery, including one named ContraForce. Ignore the suggestions and keep the **Non-gallery** option: directory sync needs your own application. **2. Enter the Tenant URL and Secret token, then test** In the new application, open **Provisioning**, then **Connectivity**. Under **Select authentication method**, choose **Bearer authentication**. Paste the ContraForce **Tenant URL** into **Tenant URL** and the secret token into **Secret token**. Click **Test connection**. Entra confirms that it can reach ContraForce and that the token is accepted. Then click **Save**. ![Connectivity page of the application's provisioning in Entra, with Bearer authentication selected, the ContraForce Tenant URL filled in, the hidden Secret token and the Test connection button](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/04-entra-connectivity.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=e3c962d355dbbeec75b599b5800bb884) If the test fails, check that you copied the whole token and the full Tenant URL, and that directory sync shows **Connected** in ContraForce. > [!TIP] > > These steps follow the current provisioning experience in the Entra admin center. In the legacy experience, the same fields are under **Provisioning** > **Admin Credentials** and **Mappings**. ## Step 3: Map externalId to objectId ContraForce identifies every person and group by their Microsoft Entra **object ID**. Entra's default mapping for users sends `mailNickname` as `externalId` instead, so change it before you start provisioning. **1. Open the user mappings** In the application's provisioning menu, open **Attribute mapping** and select the **Users** tab. **2. Map objectId to externalId** Find the row whose target attribute is **externalId** and click its edit button. Set **Source attribute (Microsoft Entra ID)** to **objectId**, leave **Mapping type** as **Direct**, and click **Apply**. Back on **Attribute mapping**, click **Save**. ![Edit Attribute Mapping page in Entra with Mapping type Direct, Source attribute objectId and Target attribute externalId](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/05-entra-user-mapping-externalid.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=d052513213520557bcf8ed85223912ee) Keep **userPrincipalName** mapped to **userName**. ContraForce uses these attributes and ignores the others in the default list, so you can leave them in place: | Microsoft Entra ID attribute | ContraForce attribute | | - | - | | `objectId` | `externalId` (required) | | `userPrincipalName` | `userName` | | `givenName` | `name.givenName` | | `surname` | `name.familyName` | | `displayName` | `displayName` | | `mail` | `emails[type eq "work"].value` | | `Switch([IsSoftDeleted], ...)` | `active` | **3. Check the group mappings** Select the **Groups** tab. Confirm that **objectId** is mapped to **externalId**, along with **displayName** and **members**. These are Entra's defaults for groups, so there is usually nothing to change. ![Attribute mapping Groups tab in Entra showing displayName, members, and objectId mapped to externalId](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/06-entra-group-mapping.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=a0458581289c7a345630d48d852c7ce8) > [!WARNING] > > Without the `objectId` mapping, ContraForce refuses every user and group Entra sends, with the error `externalId must be the user's Microsoft Entra object ID` in the Entra provisioning logs. ## Step 4: Choose scope and safety settings In the application's provisioning menu, open **Provisioning** and expand **Settings**: * Set **Scope** to **Sync only assigned users and groups**, so only the people and groups you assign to the application get access to ContraForce. * Select **Prevent accidental deletion** and set a threshold. Entra then pauses provisioning instead of removing many people at once, for example after a mistaken change to a group. * Select **Send an email notification when a failure occurs** and enter a mailbox your team watches. Leave **Provisioning Status** set to **Off** for now, and click **Save**. ![Provisioning page in Entra with Provisioning Mode Automatic and the Settings section expanded, showing the failure email and accidental deletion options, Scope set to Sync only assigned users and groups, and Provisioning Status](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/07-entra-provisioning-settings.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=cc2b3709f548e4dd1acae26f713acc75) ## Step 5: Assign people and start provisioning **1. Assign users and groups** In the provisioning menu, open **Users and groups**, click **Add user/group**, and select the people and groups who should use ContraForce. Assign the groups you plan to grant access to in ContraForce, such as your SOC analysts or your admins. Everyone in an assigned group is provisioned. ![Users and groups page of the application in Entra with the Add user/group button and an assigned group](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/08-entra-users-and-groups.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=a6a4313e5768f261464ecab70730e8fc) **2. Test with Provision on demand** Before turning on provisioning for everyone, open **Provision on demand**, search for one assigned user, and click **Provision**. Entra shows each step and the result. The person then appears in ContraForce under **Settings** > **User Management**. ![Provision on demand page in Entra with the search box for selecting a user or group and the Provision button](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/09-entra-provision-on-demand.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=23ffe782b4b365c96643b6a6f06f28c7) **3. Start provisioning** Open the provisioning **Overview** and click **Start provisioning**, or set **Provisioning Status** to **On** on the **Provisioning** page and click **Save**. The first cycle provisions everyone in scope. Later cycles run about every 40 minutes and send only changes. ![Provisioning Overview in Entra with the Start provisioning button in the toolbar](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/10-entra-start-provisioning.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=3c1699aa56031de1bdfdfaed806e9b32) ## Step 6: Confirm in ContraForce Back on the **Directory sync** tab, **Provisioning activity** shows when Entra last contacted ContraForce and the last error it was sent, if any. Click the refresh button to update it. In **Settings** > **User Management** and **Group Management**, everyone and every group Entra provisioned is marked **Managed by Entra**. See [Tell Entra-managed and manual users apart](#tell-entra-managed-and-manual-users-apart) for what that changes. ## Tell Entra-managed and manual users apart Once directory sync is on, your organization can have two kinds of people and groups side by side: those Microsoft Entra ID provisions, and those added by hand in ContraForce. ContraForce marks the ones Entra manages wherever you might try to change them. ### In User Management * **Managed by Entra chip:** people Entra provisioned show a **Managed by Entra** chip next to their name. People added by hand have no chip. * **Organizational role:** for people Entra manages, the role list is locked and a line under it explains where the role comes from: * **Managed by Microsoft Entra ID. The role follows the default for provisioned users and the groups Entra puts them in.** when the role is the default role. * **Managed by Microsoft Entra ID. Role granted by group** followed by the group's name, when a group grants it. * **User details:** opening an Entra-managed person shows **Managed by Microsoft Entra ID**: Entra sets their name and email, and their organizational role follows the default role and their groups. * **Removing someone:** the confirmation for an Entra-managed person reminds you to also unassign them in Entra, or Entra adds them back on its next sync. See [Remove someone right away](#remove-someone-right-away). * **Directory sync is on:** this button replaces **Sync users** in the header and opens the **Directory sync** tab. The older user sync no longer applies once Entra provisions your people. **Add user** still works for people you add by hand. ### In Group Management * **Managed by Entra chip:** groups Entra provisioned show the same chip next to their name. * **Group details:** opening an Entra-managed group shows **Managed by Microsoft Entra ID**: Entra sets the group's name and members, while its workspace roles and organizational role are set in ContraForce. The details also show the group's **Organizational role**, or **None**. * **Edit group:** the name is locked (**The name is managed in Microsoft Entra ID and cannot be edited here.**) and so are the members (**Members are provisioned by Microsoft Entra ID. They cannot be edited here.**). The description stays editable, and an **Organizational role** field appears that groups added by hand do not have. ### What you can change for each | | Added by hand in ContraForce | Managed by Entra | | - | - | - | | Marked in the list | No chip | **Managed by Entra** chip | | Name and email (people) | Set in ContraForce | Set by Entra, locked | | Organizational role (people) | Set by an admin in **User Management** | Follows the default role and the person's groups, locked | | Name and members (groups) | Edited in ContraForce | Set by Entra, locked | | Organizational role (groups) | Not available | Set in **Edit group** | | Workspace access (groups) | Assign the group to workspaces | Assign the group to workspaces | | Removing access | Remove in ContraForce | Unassign in Entra; for immediate effect, also remove in ContraForce | ## How access works ### Everyone starts with the default role Every person Entra provisions gets the **default role** set on the **Directory sync** tab. It starts as **Member**, the least privileged organizational role, and it can never be Org Admin. Only an Org Admin can change it. Changing it moves every provisioned person whose role comes from the default; people a group grants a higher role keep it. New people have no workspace access until a group gives it to them. ### Groups grant more access Groups you provision from Entra work like any ContraForce group, with Entra deciding who is in them: * **Workspace access:** assign the group to workspaces with a workspace role, as you would any group. Its members get that access, and lose it when Entra removes them from the group. * **Organizational role:** in **Settings** > **Group Management**, click **Edit group** on a provisioned group and choose an **Organizational role**, then click **Save changes**. Members hold that role for as long as Microsoft Entra ID keeps them in the group. When someone is in several groups, they get the **most privileged** role any of them grants, or the default role if that is higher. An Org Admin can make a group grant any organizational role. A User Admin can make a group grant **Member** only. Only groups provisioned from Entra can grant an organizational role. The name and members of a provisioned group are locked in ContraForce; its description, workspace roles and organizational role are not. ### People who already use ContraForce When you assign someone who already has a ContraForce account, Entra takes them over instead of creating a duplicate. ContraForce matches them by their Entra object ID, which is the identity they already sign in with. From then on, Entra manages their name and email. Their organizational role stays as it is until Entra first changes their group memberships. After that it follows the default role and their groups, like everyone else Entra provisions. Make sure the groups that should grant Org Admin are assigned and set up before you rely on this, so no admin loses access. Groups created by hand in ContraForce are never taken over. If an Entra group has the same name as one of them, see [Troubleshooting](#troubleshooting). ### When someone leaves or changes teams * **Removed from a group in Entra:** on the next cycle, they lose the workspace access and organizational role that group granted. * **Unassigned from the application, or disabled in Entra:** on the next cycle, their ContraForce account is deactivated and they can no longer sign in. Their role and workspace access are kept, so assigning them again restores them. * **Deleted in Entra:** once Entra deletes them for good, ContraForce removes them from the organization. Changes reach ContraForce on the next cycle, about every 40 minutes. To make one take effect immediately, use **Provision on demand** for that person in Entra. ### Remove someone right away To cut off access immediately, remove the person in ContraForce under **Settings** > **User Management**. Their access ends at once. Also unassign them from the ContraForce application in Entra; otherwise Entra adds them back on its next sync. ### People you add by hand You can still invite people from **User Management**. They are not managed by Entra, and you set their role in ContraForce as before. People Entra provisions cannot be added by hand or have their role changed in ContraForce. ### Your last Org Admin is protected ContraForce never lets Entra deactivate, delete or demote the organization's last active Org Admin. Entra reports an error for that person instead. Make another person an Org Admin in ContraForce first. ## Manage the connection ### Check provisioning activity The **Provisioning activity** card on the **Directory sync** tab shows: * **Last activity from Entra:** when Entra last contacted ContraForce. * **Last error:** the status and detail of the last request ContraForce refused, the same text Entra shows in its provisioning logs. If Entra has not contacted ContraForce for more than two hours, the card warns: **Entra hasn't contacted ContraForce recently. Check that provisioning is started in Entra.** The two hours count from the later of Entra's last request and the moment the current token was issued, so a connection you just set up is not flagged before Entra has had time to call. ![Provisioning activity card warning that Entra hasn't contacted ContraForce recently, with No requests yet as the last activity and None recorded as the last error](https://mintcdn.com/contraforce/vrbte4FCInq9h6O6/images/scim-provisioning/11-provisioning-activity.png?fit=max\&auto=format\&n=vrbte4FCInq9h6O6\&q=85\&s=ec651699afbdf498803b629733c63472) ### Rotate the secret token Click **Rotate token** on the **Directory sync** tab and confirm. The current token stops working right away, and provisioning pauses until you paste the new token into the application's **Admin Credentials** in Entra and save. ### Change the default role Choose a role under **Default role** and confirm. Only an Org Admin can do this, and Org Admin itself is never available as the default. Grant admin rights through a group instead. ### Disconnect Click **Disconnect** under **Disconnect directory sync** and confirm. ContraForce stops accepting provisioning requests from Entra. People and groups already provisioned stay, with the access they have now. Connecting again issues a new secret token. Also stop provisioning in Entra, so it does not keep retrying. ## Troubleshooting Entra shows the error ContraForce sent for each failed change in the application's **Provisioning logs**. The **Provisioning activity** card shows the most recent one. | Error | Cause | Fix | | - | - | - | | `The SCIM token is missing, invalid, or no longer active.` | The token was rotated, directory sync was disconnected, or the token was copied incompletely. | Rotate the token in ContraForce, paste the new one into **Admin Credentials** in Entra, then **Test Connection** and **Save**. | | `SCIM provisioning is not included in this organization's ContraForce plan.` | The organization's plan does not include SCIM provisioning. | Move to the Growth plan or above, or add SCIM provisioning to your plan. Then restart provisioning in Entra. | | `externalId must be the user's Microsoft Entra object ID.` (or `the group's`) | `externalId` is not mapped to `objectId`. | Map `objectId` to `externalId` (see [Step 3](#step-3-map-externalid-to-objectid)), then restart provisioning. | | `This Microsoft Entra user already belongs to another ContraForce organization.` | A person can belong to only one ContraForce organization. | Remove them from the other organization first, or unassign them from this application. | | `A group named '' already exists in ContraForce. Rename the group in ContraForce or in Entra, then retry.` | A group created by hand in ContraForce has the same name. ContraForce never takes over hand-made groups. | Rename one of the two groups. The next cycle creates the Entra group. | | `This user is the organization's last active ContraForce admin and cannot be deactivated.` (also `deleted` or `demote`) | The change would leave the organization without an active Org Admin. | Make another person an Org Admin in ContraForce, then retry provisioning. | | `This ContraForce user is linked to a different Entra identity.` | The person in ContraForce signs in with a different Entra account than the one Entra is sending. | Check that you assigned the right person. If the ContraForce account is wrong, remove it in ContraForce and let Entra provision the person. | | `This ContraForce user is not linked to an Entra identity yet.` | The account was created in ContraForce without an Entra identity, so ContraForce cannot confirm it is the same person. | Remove the person in ContraForce and let Entra provision them. | | **Entra hasn't contacted ContraForce recently.** | Provisioning is stopped or in quarantine in Entra, or the token stopped working. | Open provisioning in Entra, check its status and logs, and start it again. | ## Microsoft Entra documentation * [Microsoft: Configure an app for automatic user provisioning](https://learn.microsoft.com/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal) * [Microsoft: Provision on demand](https://learn.microsoft.com/entra/identity/app-provisioning/provision-on-demand) * [Microsoft: Enable accidental deletion prevention](https://learn.microsoft.com/entra/identity/app-provisioning/accidental-deletions) *** ## Related Guides > **[User Management](/guides/general-support/user-group-management)** > > Add users and groups, assign workspace roles in each workspace's IAM tab, and remove access > **[User Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > What every organization role and workspace role can do > [!NOTE] > > Questions? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Onboarding Overview for MSPs and Customers Source: https://docs.contraforce.com/onboarding-customer-workspaces See how ContraForce onboarding works for MSPs and customer admins: what each side needs, which modules to pre-select, and how to confirm go-live. ContraForce onboarding is split into two parts. Pick the guide that matches your role. > **[Part 1: MSP / Service Provider](/guides/onboarding/platform-onboarding)** > > Grant Microsoft access, set up your Agent Center, connect your own security tools, and pre-onboard customer workspaces. > **[Part 2: Customer Admin](/guides/onboarding/customer-workspace-onboarding)** > > Your service provider has pre-onboarded your workspace. Click the invite link, grant consent, and consent each module on the **Modules** tab. ## Before You Begin ### What both sides need | Requirement | Who needs it | | - | - | | **Microsoft Entra Global Administrator** | First sign-in from each tenant requires an admin to grant ContraForce consent (one-time) | | **Pop-ups allowed for `portal.contraforce.com`** | Microsoft consent prompts open in popup windows | | **Active Microsoft 365 license** with Defender capabilities (Business Premium, E3, or E5) | Customer side, for Defender-based detection and response | ### What service providers also need | Requirement | Why | | - | - | | **ContraForce sign-up link** | Provided by your account team to start your own onboarding | | **Customer's Microsoft Entra tenant ID** | Required to pre-onboard a workspace for them | | **Customer's primary point-of-contact email** | Receives the invite that starts the customer's onboarding | ### What customers also need | Requirement | Why | | - | - | | **Invite email from your service provider** | The link in this email is your onboarding entry point | | **Azure Subscription Owner** | Only required if Microsoft Sentinel is among the pre-selected detection modules | *** ## How the Two Parts Connect ```mermaid theme={null} sequenceDiagram participant MSP as Service Provider participant CF as ContraForce participant Customer as Customer Admin MSP->>CF: Sign up via portal.contraforce.com link MSP->>CF: Grant Microsoft consent (Global Admin) MSP->>CF: Set up Agent Center, connect own sources MSP->>CF: Add customer workspace with pre-selected modules CF->>Customer: Invite email Customer->>CF: Click invite link, grant Microsoft consent Customer->>CF: Consent each module on the Modules tab CF->>MSP: Real-time notification: customer workspace is live ``` *** ## Module Reference The detection and response modules your customer ends up using depend on what your service provider pre-selects when adding the workspace from the **Workspace Center → Onboarding** tab. Use this matrix to decide what to pre-select. | Capability | Defender for Endpoint | Sentinel | | - | :-: | :-: | | Defender for Endpoint incidents | ✓ | ✓ | | Entity enrichment | ✓ | ✓ | | Gamebook response actions | ✓ | ✓ | | Multi-tenant management | ✓ | ✓ | | Sentinel incidents | – | ✓ | | Sentinel detection rules (CMS) | – | ✓ | | Email notifications | – | ✓ | | Log search | – | ✓ | | Azure Lighthouse | – | ✓ | > [!NOTE] > > Selecting Sentinel as a detection module triggers ContraForce to deploy the supporting Azure infrastructure in the customer's subscription automatically. The customer doesn't run a separate Azure deployment step. ### Per-module deep-dives > **[Microsoft Sentinel Module](/guides/onboarding/microsoft-sentinel-module)** > > What Sentinel adds and what gets deployed in the customer's Azure subscription > **[Defender for Endpoint Module](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Defender for Endpoint detection and response details > **[CrowdStrike Modules](/guides/onboarding/crowdstrike-detection-and-response-modules)** > > CrowdStrike detection and response options > **[CrowdStrike Falcon Integration](/guides/technical/crowdstrike-falcon-integration)** > > How Falcon detections become incidents, what each tier unlocks, and how retention applies > **[SentinelOne Module](/guides/onboarding/sentinelone-module)** > > SentinelOne detection and response > **[Sumo Logic Detection Module](/guides/onboarding/sumo-logic-module)** > > Sumo Logic monitor alerts as incidents, plus monitor management > **[Content Management Center](/guides/content-management-center/overview)** > > Detection content for Microsoft Sentinel and Microsoft Defender XDR > **[Notifications Module](/guides/onboarding/notifications-module)** > > Email notifications for incidents (Sentinel only) *** ## Verifying a Successful Deployment There is no completion screen. A workspace is onboarded when its **status light turns green** on its card in the Workspace Center. Run these checks once the customer has consented their modules. ### Immediate verification * The customer's card moves from the **Onboarding** tab to the **Workspaces** tab in your Workspace Center * The card's status light goes **blue** (pre-onboarded) to **green** (live). An **amber** light means a module or agent is still missing * You received the real-time notification that the customer's workspace is live * Incidents start appearing on the Command Dashboard within 5 to 15 minutes ### If incidents don't appear * Check the source system (Defender, Sentinel, CrowdStrike) for active incidents. ContraForce syncs existing incidents, so if there are none in the source, none will appear in ContraForce * Verify each pre-selected module shows as consented on the customer's **Modules** tab * For Sentinel customers, allow a few extra minutes after module consent for the Azure infrastructure to finish deploying *** ## Common Issues | Issue | Likely cause | Solution | | - | - | - | | Consent popup doesn't appear | Pop-up blocker | Allow pop-ups for `portal.contraforce.com` | | Consent fails with permissions error | Non-admin user | Forward the admin consent link to a Global Admin | | **Sign In Failed** page | Consent skipped or stuck session | See troubleshooting in [Part 1](/guides/onboarding/platform-onboarding#troubleshooting-sign-in-failed) or [Part 2](/guides/onboarding/customer-workspace-onboarding#troubleshooting-sign-in-failed) | | No incidents appearing | No active incidents in source | Check Defender/Sentinel/CrowdStrike console | | Customer card stays **blue** on the **Onboarding** tab | Customer hasn't consented their modules yet | Resend the invite or contact the POC | *** ## Next Steps After Onboarding > **[Incident Management](/guides/getting-started/incident-management)** > > Learn how to triage and respond to incidents > **[What Are Gamebooks?](/guides/getting-started/what-are-gamebooks)** > > Automated response workflows > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Monitor security posture across workspaces > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > Manage multiple customers efficiently > **[Onboarding Workspaces at Scale](/guides/fleet-management/onboarding-workspaces-at-scale)** > > Import up to 200 customer workspaces at once from a CSV file > **[Onboarding Verification](/guides/onboarding/workspace-onboarding-checklist)** > > Confirm a newly onboarded workspace is healthy before go-live *** > [!NOTE] > > Questions about onboarding? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Agentic Security Delivery Platform Documentation Source: https://docs.contraforce.com/overview Use the ContraForce documentation to onboard workspaces, triage incidents, run Gamebooks, and connect Microsoft Security and more. ## Getting Started with ContraForce Get your security delivery platform up and running in minutes. > **[Launch Here - Platform Onboarding](/guides/onboarding/platform-onboarding)** > > Follow our onboarding guide to connect your first workspace. Onboarding a customer? The [Onboarding Workspaces overview](/onboarding-customer-workspaces) explains what service providers and customer admins each need, and how the two parts connect. ## Core Platform Features Master the tools that power your security delivery. > **[Command Dashboard](/guides/getting-started/command-dashboard)** > > Your central hub for monitoring incidents across all workspaces in a single dashboard. > **[Incident Management](/guides/getting-started/incident-management)** > > Learn the workflow for triaging, investigating, and responding. > **[Workbench Overview](/guides/getting-started/workbench-overview)** > > Create custom response workflows with AI-mapped responses and standard operating procedures (SOPs). > **[Gamebooks](/guides/getting-started/what-are-gamebooks)** > > Automate incident response with pre-built and custom response actions. ## Multi-Tenant Management Designed for MSSPs and service providers managing multiple customers. > **[Multi-Tenant Features](/guides/getting-started/multi-tenant-features)** > > View and manage incidents across all customer workspaces from one interface. > **[Users and Groups](/guides/onboarding/user-group-management-for-providers)** > > Pre-onboard customers and manage workspace configurations. > **[Content Management Center](/guides/content-management-center/overview)** > > Manage detection content as a versioned library and deploy it across every workspace. > **[Workspace Center](/guides/getting-started/workspace-manager)** > > Pre-onboard customers and manage workspace configurations. ## Connect Your Modules Connect Microsoft security products and other security tools with ContraForce modules. > **[Microsoft Sentinel](/guides/onboarding/microsoft-sentinel-module)** > > Connect your Microsoft Sentinel for incident management and more. > **[Microsoft Defender for Endpoint](/guides/onboarding/defender-for-endpoint-module-deployment)** > > Connect Defender for Endpoint, Defender XDR, and Microsoft Entra ID. > **[Content Management Center](/guides/content-management-center/overview)** > > Set up repositories, deploy rules, and review changes. > **[Notifications Module](/guides/onboarding/notifications-module)** > > Connect your notifications module for Microsoft Sentinel > **[SentinelOne Modules](/guides/onboarding/sentinelone-module)** > > Ingest SentinelOne threats as incidents and run Contain and On-Demand Scan Gamebooks. > **[Sumo Logic Detection Module](/guides/onboarding/sumo-logic-module)** > > Investigate Sumo Logic monitor alerts as incidents and manage monitors from ContraForce. ## Understanding the Basics Key concepts for getting the most out of ContraForce. > **[Roles & Permissions](/guides/general-support/roles-and-permissions-reference)** > > Understand roles including organization-level and workspace-level permissions. > **[User Management](/guides/general-support/user-group-management)** > > Understand roles, and permissions across your workspaces. ## Need help? > **[Submit a Support Ticket](/submit-ticket)** > > Open a ticket, choose a category and priority, and track your organization's requests. > **[Contact Support](mailto:support@contraforce.com)** > > Reach our support team at [support@contraforce.com](mailto:support@contraforce.com) for assistance. > **[Release Notes](/release-notes)** > > Stay updated with the latest features, fixes, and improvements. # Release Notes Source: https://docs.contraforce.com/release-notes Read the ContraForce release notes: new features, improvements, and fixes for incidents, Gamebooks, agents, workspaces, and the API, newest first. **2026-10-23-03** SLA clocks measured from detection, an SLA timeline, and a security fix ### New Features * The incident **SLA** tab's timeline now shows each status switch that moved a clock: the first response, each pause and resume with the status that caused it (for example **Paused (On Hold)** and **Resumed (Active)**, with how long it was paused), any at-risk or breached crossing, and the resolution. ### Improvements * **Time to resolution** is now measured from when the incident is detected, the same as **Time to first response** and the way SLA tools measure it, instead of from the first response. Until the first response, the incident header shows both countdowns, and the **Time to Resolution** column counts down from the moment an incident arrives. Existing incidents show the new value the next time they load. * SLA configurations and ticketing accounts now open when you select anywhere on their row, like Content Management Center repositories, instead of through a settings icon. ### Bug Fixes * The incident queue's **MTTR** column is now **Time to Resolution**, and the SLA chips name the clock they count: **First response** and **Time to resolution**. MTTR is an average across many incidents, not one incident's clock. * Putting an incident **On Hold** or **Waiting on Customer** after its first response no longer reduces its time to first response. Each clock now leaves out only the paused time while it was running, so a breached first response no longer turns **On track** after a later pause. ### Security * Incident paging with Microsoft Sentinel and Microsoft Defender XDR now only follows page links to Microsoft's own services, and an unused incident endpoint was removed. **2026-10-23-02** Safer rule descriptions and a Get started checklist fix ### Security * Analytic rule descriptions from Microsoft Sentinel, Content Management Center rules and Microsoft Defender XDR custom detections are now cleaned before they are shown. Reference links (http, https and mailto) stay clickable, and any content that could run code in your browser is removed. ### Bug Fixes * The **Get started with ContraForce** card on the **Command** page now completes the **Setup agent center** step for service providers using ContraForce-hosted agents once they have an agent, so the card closes on its own when the rest of the checklist is done. **2026-10-23** Saved Log Search queries and ServiceNow custom states ### New Features * **Log Search** can now save queries. Once a query has run successfully, select **Save** to name it, file it in a folder, and choose who sees it: only you, or everyone on your team. The **Saved queries** panel lets you search, reopen, rename, move, share and delete saved queries, and organize them into folders. ### Bug Fixes * ServiceNow tickets in a custom state your instance added now appear in the **Link ServiceNow ticket** search and can be linked, instead of the search failing with an error. Their state shows as **Other**, and saving one of these tickets from ContraForce leaves its state in ServiceNow unchanged. **2026-10-22-03** Sentinel and Defender incident IDs side by side ### New Features * For Microsoft incidents that exist in both Microsoft Sentinel and Microsoft Defender XDR, the incident queue now shows **Sentinel ID** and **Defender ID** columns, and the incident header shows both IDs. Each ID links to its portal, so you can match a ContraForce incident to the one your team discusses in Sentinel or Defender without opening it. Incidents ContraForce reads from Defender in a workspace that also reads Sentinel now carry their Sentinel number too. The columns appear when the queue holds such incidents, and you can show or hide them from the column picker. **2026-10-22-02** Agent verdict in the incident header and accurate closure counts ### New Features * The incident header, on the incident detail page and in the incident modal, now shows the **Agent classification** and **Agent reason** next to the **Classification** and **Reason** the incident was closed with. You can compare the agent's verdict with how the incident was closed without opening the comments, and it shows on open incidents as soon as the agent has recorded a verdict. ### Bug Fixes * The **Incident Report**, its exports and the Command Center no longer count an incident more than once when it was forwarded between Microsoft Defender XDR and Microsoft Sentinel, or edited after it was closed. This applies to incidents closed from this release on, and the **Incident Report** also combines repeated closures recorded earlier. **2026-10-22** Content Management Center: deleted rules, duplicate imports and managed rules ### Bug Fixes * Deleting a rule from a Content Management Center repository no longer leaves it stuck as **Outdated** in workspace coverage. The rule keeps running in every workspace exactly as deployed, it and any workspace fork of it stop counting toward the repository's coverage, and its page shows **No longer managed**. * Importing a rule the repository already holds no longer creates a second copy. The import picker marks it **Already in this repository**, or **Pending in this repository** while an earlier import waits for review in a protected repository. * The **All** tab in workspace coverage now includes rules that are not deployed, so its count matches the other tabs. ### New Features * A workspace's **Detection Rules** page shows a **Managed** chip on each rule a Content Management Center repository manages. Hover or select the chip to see which repository. **2026-10-20** Content Management Center fixes and coverage views ### Bug Fixes * Adding a rule from an exported Sentinel or Defender `.json` file works again. Uploads previously failed with "Could not read the file". * Near-real-time (NRT) Sentinel analytics rules now appear when importing rules into a repository, and can be deployed and scanned for drift. * Sentinel rules with up to 10 entity mappings can now be deployed. Deployment previously stopped any rule with more than 5. * Editing or turning a Sentinel rule on or off no longer removes its MITRE sub-techniques. ### Improvements * A repository's **Workspaces** tab has a new **Accepted** column, so you can see which drift has been reviewed across every workspace. **Drifted** now counts only drift that still needs a decision. * Each workspace has a new **Repository** tab showing which content repositories manage its analytic rules. * The **Rules** list has an **Added** column, so two imports of the same rule can be told apart. * Click anywhere on a repository in the Content Management Center to open it. The settings icon now opens the repository's **Settings** tab. **2026-10-19** Workspace access checks ### Security * Requests that name a workspace now act only on workspaces your organization manages, across SLA configurations, the Command Center dashboard, data connectors, notification settings and AI agent checks. * An AI agent's credentials can no longer change who has access to a workspace. **2026-10-16-02** Safer user removal ### Security * Removing a user with a role above Member now needs an Org Admin, and an organization's last Org Admin can no longer be removed or deactivated. * Two unused API endpoints were removed: `GET /users/{userId}` and `PUT /users/profile`. **2026-10-16** Full-month Incident Report history ### Bug Fixes * The Incident Report's closed incident history now loads, pages and exports a full month across all of your workspaces, where large selections used to stop with "History unavailable". If a selection is still too large, the page now says why. **2026-10-15** Entity response actions, rule reviews, and fixes ### New Features * Run or queue a response action straight from an entity on the incident's **Entities** tab. * Start a rule review for a workspace directly, or from an agent tuning recommendation, so the Security Engineering agent can investigate and propose an improvement. ### Improvements * The agent's **Confidence to respond** threshold can be set to any whole number from 0 to 100. * The Agent Center **Models & Quotas** tab is clearer, and upgrades wait until models and quota have loaded. ### Bug Fixes * An agent no longer runs a Gamebook on its own when Gamebooks are turned off for the incident's severity; the Gamebook waits for analyst approval. * Onboarding a single workspace beyond your plan's included allowance now lets you accept the extra-workspace charge instead of stopping with an error. * Investigation Activity labels on the incident page no longer overflow their column. ### Security * Changes made in the portal and API now record which workspace acted and which workspace was changed, for audit. **2026-10-13** Incident Report export, API key scopes, and fixes ### New Features * The Incident Report has an **Export** menu: download it as PDF, as an Excel workbook (summary, workspaces and, optionally, the incident list, with frozen headers and filters), or as CSV (the incident list or the workspace breakdown). ### Security * API keys are now held to their scopes on the API endpoints that work across several workspaces, as on every other endpoint. A key without the scope an endpoint needs gets a 403 `INSUFFICIENT_SCOPE` response; for example, a read-only key can no longer update incidents in bulk. Keys already in use with these endpoints keep working. ### Bug Fixes * Command Center now records closed incidents for workspaces hosted in the UK, Sweden and Australia regions, so its closure totals update as incidents are closed. * Microsoft Defender machine actions run from a Gamebook, such as isolating a device, now reach the right device when it is known only by its Microsoft Entra device ID. If Defender has no matching device, the run is stopped with an error instead of reporting success. **2026-10-12** Security: ticketing integrations and ticket actions ### Security * A ticketing integration (Autotask, ServiceNow or Jira) can now be viewed only for the workspace you are working in, and saving one always applies to that workspace. Configuring or testing an integration needs a workspace Owner. * Creating, updating, linking or unlinking tickets, changing a ticket's status or priority, and syncing the ticketing setup now need a workspace Owner, Incident Responder or Incident Analyst, as in the API. Other roles still see linked tickets; the actions are shown disabled with the reason. **2026-10-09-b** Security: Agent Center changes need an Org Admin or Agent Admin ### Security * Changing your Agent Center and its agents (creating, upgrading or retrying the Agent Center, enabling features on it, updating agents, and creating, configuring or retrying an agent) now needs an Org Admin or Agent Admin, and removing the Agent Center deployment needs an Org Admin. Other members still see the Agent Center; its action buttons are shown disabled with the reason. **2026-10-09** Security: service accounts, and clearer identity investigations ### Security * Service accounts can now be viewed, changed, given keys or deleted only by their own organization. * Removing a service account from Settings > Users now deletes it with its keys, so the keys stop working right away. ### Improvements * Investigations now recognize Azure callers that are applications, service principals, managed identities or groups, not only users, and check that identity's own activity. When an identity cannot be resolved, the investigation reports it as a gap rather than as no activity. * Device compliance and management states that Microsoft does not report now show as Unknown instead of as non-compliant or unmanaged. * MCP: the identity tool is now `get-identity-details` with an `identityId` argument (previously `get-user-details` with `userId`). Refresh your MCP tool list and update any saved references. **2026-10-08** Security: Gamebook approvers and notification settings ### Security * A workspace's Gamebook approvers and notification settings can now be viewed only by people working in that workspace, and changed only by its Owners. * Gamebook approvers must be people from the workspace or from your own organization. Agents and service accounts cannot be approvers. Each approver is saved with their current email address, so an old address no longer counts toward approvals. **2026-10-06-b** Run Gamebooks with a service account, and more reliable ticket linking ### Feature * **Run Gamebooks with a service account** - start an incident-response Gamebook from your own tools through the ContraForce API. Add the new **Execute** scope under **Gamebooks** to the service account's credential. Running a Gamebook right away needs the Owner or Incident Responder role on the workspace; with any other workspace role, the service account can submit a run for approval. Workspace Gamebook policies and approvals still apply, and the credential cannot approve, retry, deny or cancel a run. Block IP is not available to service accounts yet. ### Bug Fix * Ticket API calls made with a service account now work on workspaces that use ServiceNow or Jira, instead of failing with an internal error. * Linking a ticket in the portal no longer adds a second link to an incident that already has one, and a link that fails partway no longer leaves a hidden link behind. * When a linked ticket can no longer be found in your ticketing system, for example because it was deleted, the incident now shows **Linked ticket unavailable** with an **Unlink** button instead of saying no ticket is linked. Unlinking removes every link on the incident, so you can link a new ticket right away. * ServiceNow tickets with a custom urgency level now link and display, with the urgency shown as Low. Saving one of these tickets from ContraForce sets its urgency to Low in ServiceNow. * When ServiceNow or Jira rejects a request, for example because the integration account's credentials expired or it lacks permission, you now see a clear message instead of an internal error. **2026-10-06** Security: workspace permissions ### Security * Actions inside a workspace now always require the matching role on that workspace. Changing workspace settings needs the Owner role, managing analytic rules needs Owner or Content Admin, and running, approving or retrying a Gamebook needs Owner or Incident Responder. Content Admins and Incident Analysts can still request approval for a Gamebook. * Organization Admins and Workspace Admins can still open every workspace your organization manages, but need a workspace role there to change it. * Only an Owner from the managing service provider can change a managed workspace's customer access mode. * The Workspaces list shows each user only the workspaces they can open. Organization Admins and Workspace Admins still see every managed workspace. **2026-10-02-b** A new panel for adding workspaces, and workspace access that follows workspace roles ### Improvement * Adding a workspace now opens a side panel that keeps everything in view: enter the Tenant ID and name, choose whether the customer gets the full portal or the setup page only, pick the modules, and add the workspace with or without an email invitation. ### Security * Opening a customer workspace now needs a workspace role there, unless you are an Org Admin or Workspace Admin. Agents work only in the workspace they are assigned to. If someone sees "You do not have access to this workspace", assign them a workspace role in that workspace's **IAM** tab. See [User Roles & Permissions](/guides/general-support/roles-and-permissions-reference). * Disabling or deleting a service account, or revoking its API keys, now needs the Org Admin or User Admin role. * Creating, changing or deleting organization webhooks, and reading their delivery logs, now needs the Org Admin or Agent Admin role. Everyone can still see the list of webhooks. **2026-10-02** Agent deployments complete again ### Bug Fix * Deploying or retrying an agent no longer shows as failed when Azure accepted the deployment. If an agent failed to deploy since October 1, retry it from the Agent Center. **2026-10-01-b** Copy buttons report failures, and a tighter API cross-origin policy ### Security * The portal API no longer tells browsers that any website may call it. Nothing changes in how you use the portal. ### Bug Fix * Copy buttons across the portal, such as workspace account ID, webhook URL and service account ID, now say "copied" only when the value actually reached your clipboard. If the browser blocks the copy, you see "Couldn't copy to the clipboard." instead. ### Improvement * The API reference for updating an incident's status now lists which classification reasons each classification accepts, so integrations closing incidents can avoid validation errors. **2026-10-01** Only organization admins assign roles, and smoother onboarding of former customers ### Security * Only organization admins can change organizational roles or give someone access. User admins can still add new users as members, remove users, sync from Microsoft Entra and manage groups, but they can no longer change anyone's role, add users with a higher role or with workspace access, add people to groups that give workspace access, or create, change or re-enable API service accounts. * The **Add Users** dialog now starts new users as **Member**, and a change that isn't allowed shows the reason instead of appearing to save. ### Bug Fix * When an MSP adds a workspace for a Microsoft tenant that already has a ContraForce account, the portal now explains that support needs to help, instead of creating a second account that could leave the customer's admin on an "inactive subscription" screen. **2026-09-28** Track agent updates in the Agent Center, and tighter user group permissions ### Feature * Agent updates are now tracked from start to finish. The Agent Center **Activity** tab shows the latest update with each agent's status and a plain-language reason when an agent fails or is skipped. **Retry failed agents** re-runs only the agents that failed, and a new update can't be started while one is still running. ### Security * Only an organization can change or delete its own user groups, and only its own users can be added to them. An organization's group list is visible only to that organization and the MSP that manages it. **2026-09-25** Tighter rule deployment and workspace member permissions, and consistent feature rollouts ### Security * Only users of a workspace, or of the MSP that manages it, can deploy, remove or list that workspace's Sentinel analytic rule deployments. * Only users of a workspace, or of the MSP that manages it, can view or change that workspace's members, and only workspace Owners and organization admins can change them. * The portal no longer serves its API reference document publicly. * Sign-in and consent redirects only ever return you to the portal or to Microsoft sign-in, and request details are cleaned before they are recorded in logs. ### Bug Fix * Features rolled out to specific workspaces now apply consistently everywhere, including background work such as incident ingestion, incident polling and agent auto-triggers. Before, these could fall back to the default setting. **2026-09-23-b** Deactivated users are locked out, webhook signing secrets, and notification recipient fixes ### Security * A portal user who has been deactivated can no longer sign in or use the API. They see a "Your access has been disabled" page, and re-inviting them from User Management restores access. Deactivating a user through **Sync** now revokes access as well. ### Bug Fix * The signing secret for a webhook is now shown once, right after you create it in the portal, with a copy button. The webhook details page has a new **Regenerate** action that replaces the secret and shows the new value once. Use it to verify the `X-CF-Signature` header on your receiver, or to rotate a secret that was lost or exposed. A bearer signing token, when set, still takes precedence. * Workspace groups added as notification recipients now receive email. A group on any notification list (incidents, gamebooks, agent runs, operating procedures, high malicious score, cost alerts) was stored with the wrong identifier and nobody in it was emailed. Group recipients added before this release still deliver to nobody: remove and re-add them. * Recipients pushed by a workspace profile are stored one by one, so removing one no longer removes the rest, and later members are no longer rejected as duplicates. A profile can no longer place one customer's group on another customer's workspace. * Removing a user or deleting a group now takes them off every notification list, not only the incident list. * Links in notification emails open the incident or gamebook directly instead of landing on the wrong page. * An agent that loses its connection while submitting an investigation no longer leaves the incident closed without its comment, webhook, audit entry and high malicious score email. **2026-09-23** Incident Report filters fixed ### Bug Fix * Filters on the **Incident Report** apply again. Choosing a custom date range now shows incidents for that range and keeps it selected, instead of returning to the previous window. Severity, source, reason, classification and page changes also reload the report, and a confirmation appears once the updated report loads. Refreshing the page, sharing its link and the browser Back button all keep your filters. **2026-09-22** Choose your region at sign-in, and high malicious score email alerts ### Feature * Choose your region when you sign in. The sign-in page now lists every ContraForce region (United States, United Kingdom, Europe and Australia) and marks the one you're on. Pick another and you're signed in there in one click. The same list is available at `portal.contraforce.com/regions`, so it's easy to share. * Get an email when an agent investigation rates an incident as likely malicious. Under **Notifications > Agent Runs**, the new **High malicious score** card emails its recipients when an investigation scores an incident at or above the threshold you choose (80 by default), optionally only for the severities you select. Each incident sends at most one of these emails, even if it is investigated again. ### Improvement * If you sign in to a region where your organization doesn't have an account, the page now tells you which region you're in and links to the others. Creating a new account there also asks you to confirm the region first, so creating an account in a region is always a deliberate choice. * Every notification card now holds its own recipients, shown inline with search, on the Incidents, Gamebooks, Agent Runs and Operating Procedures tabs and on workspace profiles. Existing recipients carry over unchanged. ### Security * Capabilities included in your plan are now enforced by the platform on every request, not only in the portal. Accounts see no change for the features they are licensed for. **2026-09-18-b** Incident Report improvements ### Improvement * Open the **Incident Report** from the Closed Incident Tracker total or a severity card, keeping your selected workspaces and time range. Severity cards show all classifications for the selected severity. * The portal and generated reports now use the same **Incident Report** title. Aligned filters, a larger and thinner donut, and taller severity cards make the report easier to explore. * IBM QRadar and Splunk are no longer offered for new source selections. Existing report links continue to show their legacy source filters clearly. ### Bug Fix * Severity percentages now total 100%, including when rounding is needed. **2026-09-18** Incident lifecycle webhook events and sample payloads ### Feature * Webhooks can now follow an incident after it is created. Subscribe to `incident.status.changed.v1` for every status transition, with the previous and new status; to `incident.assignee.changed.v1` for assignments, reassignments and unassignments, including the AI agent taking an incident; and to `incident.comment.added.v1` for analyst, agent and Gamebook comments, with the full text and any linked ticket note. See the [Webhook Event Reference](/api-reference/webhook-events). * View and copy a sample delivery for any event from the webhook form or the webhook detail page, so a receiver can be built against the exact shape before the first real delivery arrives. ### Improvement * `incident.closed.v1` now includes who was working the incident when it closed, separate from who performed the close. * Bulk reassignments now record an incident activity and count toward SLA first-response tracking, the same as single assignments. ### Bug Fix * Unassigning an incident no longer counts as a first-assignment response for SLA tracking. **2026-09-17** Classification reports, detection history, plan visibility, and regional email links ### Feature * Explore closed incident classifications from the Command Center, filter by time, selected workspaces, classifications, severity, source, and reason, and review summary statistics and workspace breakdowns. Print a report or save it as a PDF, with the option to include the incident list. * Browse Microsoft Sentinel analytical rules and Microsoft Defender custom detections in workspace tabs. Follow linked rules from incident history, inspect their configuration, and review associated incident history. ### Improvement * Accounts on a ContraForce Cloud plan can see which capabilities their plan includes and which require an upgrade or add-on. Accounts without a plan retain their existing access. ### Security * Strengthened registration navigation checks while preserving valid invitation and setup destinations within the portal. ### Bug Fix * Incident notification and gamebook emails now link to the portal for your workspace's own region. Links sent from regions outside the United States could previously point at the US portal. **2026-09-15** Delegated module consent, customer setup page, and incident update sync for API integrations ### Feature * Hand the Microsoft consent step to your customer's administrator in one action: send them a branded email or copy a single link from the workspace's security modules. They sign in with Microsoft, approve every module from one guided setup page, and can connect Microsoft Sentinel, CrowdStrike and SentinelOne there too. Tenants that have never consented ContraForce are walked through that first. * A new customer access mode, per workspace and per workspace profile, lets you limit a customer to the setup page until you are ready to give them the full portal. * Before the request goes out, ContraForce checks that the administrator's address belongs to the customer's organization and tells you when that person will be made an owner of the workspace, since only an owner can complete the setup. The setup page explains what approving does and what each group of permissions allows, and an administrator who arrives through your invite is guided through the onboarding wizard first and ends on that page. * Keep an external case management system in sync with incident updates through the v2 API. Set `filterByLastModified: true` on `POST /api/v2/incidents/across-workspaces` and the time window applies to when the incident last changed in Microsoft Sentinel or Microsoft Defender XDR, instead of when it was created. A short polling window now returns every incident that gained an alert or changed severity, status, owner, labels, or comments, including incidents created long before the window. See [Syncing incident updates](https://docs.contraforce.com/api-reference/endpoints#syncing-incident-updates-with-filterbylastmodified). ### Bug Fix * Regional background queues in the UK, EU and Australia no longer disappear after two idle weeks, which could make a feature fail the first time it was used in a region. * Table rows stay in line with their headers when a value is longer than its column, and dialogs no longer paint a darker band behind their body. ### Improvement * Production health alerting now covers UK South, Sweden Central and Australia East with the same rules as the US. **2026-09-14** Agent query visibility ### Feature * See the exact query the AI agent ran during an investigation, right on its incident comment, with the number of rows it returned and how long it took. * Hover a query to preview it, click to read it in full, and reopen it in log search to check the agent's evidence or refine the search yourself. ### Improvement * Clearer names across the product: SOPs now read as Operating Procedures, and AI Foundry is now Microsoft Foundry, in portal screens, messages, and notifications. Nothing about how they work has changed. **2026-09-10** Workspace Policies and Agent Shifts generally available, and operating-procedure change notifications ### New Features * **Workspace Policies, generally available** — govern what runs in each workspace with ordered allow-or-deny rules, checked top to bottom, first match wins. Policies cover gamebook runs and agent investigations, are built as plain sentences from your own playbooks, people, and devices, and can be previewed before they apply. Manage them from workspace settings or straight from an agent's Policies tab. * **Agent Shifts, generally available** — draw an agent's working hours on a weekly schedule and it investigates on its own only inside them. Outside those hours new incidents wait for people, and anyone can still start an investigation manually at any time. Agent Center shows each agent's on-shift or off-shift state at a glance, with when that next changes. * **Operating-procedure change notifications** — choose who should hear when operating procedures change, per workspace or across a workspace profile, and ContraForce sends a batched email digest instead of one email per edit. **2026-09-09** Content Security Policy enforcement, and ingestion health signals ### Security * The portal can now enforce its Content Security Policy rather than only report on it, and collects policy violations at a rate-limited, noise-filtered endpoint. Browsers are asked to stay on HTTPS for a full year, and the server no longer advertises its framework in response headers. ### Improvements * Incident and alert pollers now emit a heartbeat that telemetry sampling cannot drop, and the portals expose a health check Azure acts on, so a stalled poller or a dead portal instance is detectable within minutes instead of hours. **2026-09-04** Faster incident detail, and browser security headers ### Performance * Opening an incident, in the portal or through the incident API, is faster and no longer hangs. A secondary entity lookup that ran whenever Microsoft Sentinel reported no entities now runs only for incidents created in the last 30 minutes and for Microsoft Defender for Cloud Apps incidents, and is capped at ten seconds when it does. Detail requests for established incidents take roughly half the time they did. ### Security * Every portal and API response now carries the standard set of browser security headers, including a Content Security Policy in report-only mode ahead of enforcement. No change to how the portal behaves. **2026-09-03** Rate agent investigations, and data-zone AI for Australia ### New Features * **Agent investigation feedback** — rate any agent investigation from the incident or the runs table: agree, or correct it with a reason, and revise the rating any time as new information arrives. Closing an agent-investigated incident now counts toward the agent's accuracy on its own, and a new report per agent shows agreement, adjusted accuracy and review coverage — with confidence margins shown honestly, so a number backed by twelve assessments never masquerades as certainty. Ratings are visible to your team, never to your customers. * **Data-zone AI inference for Australia** — Ask Iris in the Australian region now keeps AI inference inside Microsoft's Asia-Pacific data zone instead of routing globally, strengthening the region's data-handling posture. **2026-09-01** Reliable return from Microsoft Entra admin consent ### Bug Fixes * Returning from Microsoft Entra admin consent now lands on a working module configuration page. Previously the portal could go blank after consent and needed a page reload before you could continue setting up the module. ### Improvements * The embedded third-party support widget has been removed from the portal. No support bubble sits over the app any more, and portal pages no longer load an external script on every visit. **2026-08-28-c** Clearer setup prerequisites and policy-aware playbook menus ### New Features * Playbook menus now show policy outcomes up front: denied playbooks are disabled with a tooltip naming the policy, and playbooks needing sign-off carry an approval badge. ### Bug Fixes * Connecting Microsoft Defender XDR or a Microsoft response module now names the Azure roles Microsoft actually accepts, instead of clearing roles that end at "approval required". * Microsoft Sentinel setup no longer asks for an Entra directory role that connecting never required. The Sentinel Hunting add-on now carries its own, correctly named prerequisite. **2026-08-28-b** Incident detail stays usable during data-source outages ### Improvements * The incident detail page and modal now stay usable when alerts and entities can't be retrieved from the source system: the incident's summary, comments, audit trail, and gamebook keep loading and remain interactive, while the affected investigation section shows a clear warning with a one-click retry. Opening an incident from the list also paints instantly with the row's details instead of waiting on the full fetch. **2026-08-28** Save a workspace as a profile, and reliable incident opening ### New Features * **Save as Profile** — turn a workspace you have already configured into a reusable profile from the workspace card, instead of rebuilding every section by hand. A preview shows what carries over and what stays behind, such as settings that only make sense in a single workspace. * **Policy builder** — build a workspace policy as a sentence: pick playbooks, people, and devices from your own data rather than typing identifiers, and get a warning when a new policy sits behind a broader one that would stop it ever matching. ### Bug Fixes * Opening a workspace profile's Notifications, Gamebooks, Agent, or OPs tab no longer reports unsaved changes before you touch anything. Previously, saving from that state could replace the profile's own settings with defaults and push them to every attached workspace. * Opening an incident no longer intermittently fails with an error or hangs on a spinner. This affected Microsoft Sentinel workspaces during busy periods. **2026-08-27** Webhook delivery logs no longer store incident content ### Security * Webhook delivery logs now record delivery metadata only: the event ID and type, outcome, HTTP status, latency, attempt number, and the incident's number, severity, status, and source. The event body, your endpoint's response body, and the incident title are no longer stored, and log entries now expire automatically instead of being kept indefinitely. Opening a log entry in the portal shows the incident's current state, fetched live from the source system. * Redelivering a failed `incident.created.v1` delivery now rebuilds the event from the incident's current state while keeping the original event ID and `occurredAt`, so your deduplication still recognizes it. Failed deliveries of other event types can no longer be redelivered. See [Delivery logs](https://docs.contraforce.com/api-reference/webhook-events#delivery-logs) for what is retained. **2026-08-26** Workspace Policies and onboarding reliability ### New Features * **Workspace Policies** — define ordered allow/deny rules that govern how gamebooks run and how agents behave, with a policies list, a guided policy builder, and a batch preview to check the effect before applying. ### Bug Fixes * Onboarding no longer adds a workspace administrator twice to the workspace and organization member lists. * Fixed the workspace profile Agent tab so its settings match the agent configuration. * The cookie consent banner now loads reliably on the European platform, including under ad and tracker blockers. **2026-08-25** Gamebook approver fix for managed workspaces ### Bug Fixes * Provider staff can now be selected as gamebook approvers on workspaces they manage. Previously the approver picker only offered users whose home account matched the workspace, so service-provider team members never appeared as candidates. **2026-08-21** Reliability fixes for Sentinel connections and metrics ### Bug Fixes * Incident ingestion now starts immediately after connecting a Microsoft Sentinel workspace, without waiting on a background infrastructure deployment. Deploying Apollo is a separate, explicit action with clear feedback. * Incident closure statistics and Classification Trends now record reliably for every workspace. Previously they could fail to record in some environments. ### Improvements * Importing a list of customers during onboarding now opens a file picker directly from the onboarding flow for a quicker, more consistent import experience. **2026-08-20** Reliable incident access for your own workspace ### Bug Fixes * Incidents from a service provider's own workspace now appear reliably in ContraForce. Previously that workspace was read using the signed-in user's personal Azure access, so a user without an Azure role on the workspace saw no incidents from it, and the incident list gave no indication anything was missing. * Connecting a Microsoft Sentinel workspace no longer leaves an account without an incident feed. Previously, if one optional step of the connection failed, the workspace could appear connected while producing no incidents, notifications, Gamebook runs or webhooks. **2026-08-19** Audit coverage for OPs and security rules ### New Features * **Operating procedure and security rule changes are now audited** - creating, updating, deleting and linking OPs, and enabling or disabling security rules, are recorded with who made the change and when. The Operating Procedures page has its own Audit tab showing that history, including the before and after state for each toggle, with date range filtering. * **Content repository lifecycle events appear in the CMS audit feed** - repository creation, updates and removal are recorded alongside the rest of the trail. **2026-08-18** Audit coverage for workspace and agent changes ### New Features * **The audit trail now covers workspace configuration, access and modules** - changes to a workspace's settings, its user access and its enabled modules are recorded with who made them and when, alongside the organization-wide trail. * **Agent Center activity is audited** - agent deployment and management changes are recorded, and each agent has its own Audit tab showing that agent's history in one place. **2026-08-14** Parallel incident deduplication and Ticketing in Workspace Center ### Improvements * Incidents that Microsoft syncs between Defender XDR and Sentinel now appear once instead of twice. Deduplication applies to workspaces with both detection modules connected, and produces one inbox entry, one notification, one webhook, one agent run and one SLA timer per real incident. The Defender and Sentinel forwarding toggles have been removed, and any previously configured value is ignored. See [Parallel incident deduplication](https://docs.contraforce.com/guides/technical/parallel-incident-deduplication#the-three-forwarding-scenarios) for how each forwarding scenario is resolved. * Ticketing configuration has moved from Settings to Workspace Center, alongside Workspaces, Onboarding and SLA. Existing Settings links redirect automatically. ### Bug Fixes * A failed content rule deploy now records why it failed, so the reason can be reviewed in the audit trail instead of disappearing with the on-screen message. * Importing rules from a Sentinel workspace in your own tenant now reports a clear permission error naming the Azure access required, instead of a generic "contact support" failure. * ContraForce administrators can now view and edit a workspace's module configuration through OmniView. **2026-08-12-c** Sentinel connection fixes for least-privilege roles ### Bug Fixes * **Connecting Microsoft Sentinel now works with least-privilege roles** - Contributor combined with either User Access Administrator or Role Based Access Control Administrator is accepted, alongside Owner and any custom role carrying the same permissions. Previously some correctly configured accounts were refused. * **Permission messages name the exact permission you are missing** - when a connection cannot proceed, the message lists the specific Azure permissions required and where to grant them, instead of naming only a role. That means you can grant precisely what is needed rather than over-granting. * **A failed check is no longer reported as a missing permission** - if the permission check itself cannot complete, because of a network problem or a temporary Azure issue, ContraForce now says so plainly instead of suggesting your access is misconfigured. **2026-08-12-b** An organization-wide audit trail in Settings ### New Features * **Organization Settings now has an Audit tab** - see who changed what across your organization in one place. It covers users added, removed, updated, and synced, group changes, organizational role and gamebook permission changes, organization and notification settings, and ticketing integration setup. Your existing webhook and API client activity now appears here too, so the whole organization reads as one trail. * **Every entry names the time, the person, and the target** - each record shows when it happened, who did it and their email, a plain-language description of the activity, and the resource that changed. Narrow the view to a date range when you are looking into a specific window. **2026-08-12** Upstream incident closures and a clearer Sentinel connection ### Bug Fixes * **Incidents closed in your security tools are now reflected in ContraForce** - when an analyst closes an incident directly in Defender, Sentinel, CrowdStrike or SentinelOne, ContraForce now detects the closure, including when an incident is later reopened upstream or its classification is corrected. * **Connecting Microsoft Sentinel tells you immediately when access cannot be granted** - the connection previously reported success and left a workspace that was never wired up in Azure. It now stops at the point of failure and names the resource group and the role that are missing, so you know exactly what to ask for. * **Gamebook history offers a retry instead of failing quietly** - a brief interruption while loading gamebook history now shows a clear error with a retry, rather than an empty view. ### New Features * **ContraForce is available as a Microsoft Sentinel solution** - the platform is now packaged for distribution through Microsoft Sentinel Content Hub. ### Improvements * **Temporary storage interruptions are reported clearly** - transient faults now surface as a retryable error rather than a generic failure. **2026-08-11** Onboarding fixes for customer administrators ### Bug Fixes * **Administrators can finish setup with any role that can approve ContraForce** - completing an invitation previously required a Global Administrator or Privileged Role Administrator. Every role Microsoft Entra allows to grant that approval can now complete setup. * **A missing organization approval is no longer reported as the wrong problem** - when an organization had not yet approved ContraForce, the setup page said the signed-in user's role was insufficient. It now explains that approval is needed and offers to grant it in one click. * **Module permissions are checked before you are sent to Microsoft** - the setup wizard now tells you up front when your role cannot approve a module's permissions, instead of sending you to Microsoft only to be refused and returned with an error. * **Connecting Microsoft Sentinel checks the right level of ownership** - owning a single resource group appeared to satisfy the subscription ownership requirement, allowing a connection that then failed without explanation. The check now looks at the subscription itself. * **Setup no longer reports success when nothing is connected** - the final step said ContraForce would start delivering security even when no detection source was ready to send data. It now says what is still outstanding. **2026-08-10** Manual investigation limits for busy agents ### Improvements * **Manual investigations no longer pile up on a busy agent** - an agent now takes at most three analyst-triggered investigations at a time. Trigger another while three are running and ContraForce tells you the agent is busy investigating other incidents so you can retry in a moment, instead of accepting work that slows down the investigations already under way. **2026-08-08** Reliable agent run reporting, defanged indicators in incident emails, and notification settings fixes ### Bug Fixes * **Long-running agent investigations are no longer shown as failed** - when an agent's investigation ran longer than the connection timeout, the run could be marked failed with a raw network error even though the agent was still working, and its result was then discarded. Run status now reflects what the agent actually did, and a result that arrives late corrects the record. * **Changing one incident severity no longer resets your other notification settings** - toggling a severity switch on a workspace's Notifications tab discarded that account's agent run preferences and recipients, cost alert budget and thresholds, and spend approval settings. Every other setting is now preserved. * **Content Management Center loads reliably in all regions** - the UK South portal returned "Operation failed" on every Content Management Center load. It now opens normally. ### Security * **Indicators in incident notification emails are no longer clickable** - URLs, domains, and IP addresses in incident emails are now shown in a defanged form, so your email client cannot turn a potentially malicious indicator into a live link. The View Incident button and recommended playbook links still work, and indicators inside the portal are unchanged. ### Improvements * **Agents pick up the next queued incident sooner** - an agent now frees up for the next queued incident after a 10-minute window, separate from the longer window used to decide a run never reported back. Queued incidents move through faster during busy periods. * **A more consistent interface** - the command palette, What's New panel, cookie consent notice, and page layouts have been rebuilt on the current design system. **2026-08-07** Sentinel detection rules for ContraForce activity, one-run-per-agent limits, and workspace drift visibility ### New Features * **Ready-made detections for ContraForce activity in Sentinel** - the ContraForce data connector now ships with analytic rules covering privileged access changes, destructive workspace actions, and machine credential activity, so suspicious ContraForce administration surfaces as Sentinel incidents without you writing the queries. ### Improvements * **Agents no longer run twice on the same work** - an agent is now limited to one run at a time, with further triggers queued behind it rather than starting alongside. Runs are more predictable and no longer duplicate effort during busy periods. * **SLA settings now live in Workspace Center** - service level configuration has moved alongside the rest of your workspace settings. * **A quicker agent creation wizard** - new agents default to On Queue mode, workspace aliases are shown so you can tell similar workspaces apart, and the agent name is prefilled. * **Standard operating procedures are now called Operating Procedures** - page titles and breadcrumbs updated to match how teams refer to them. * **Detection content stays in step with your workspaces** - reconciliation now detects and reports drift between the content ContraForce manages and what is actually deployed in your Sentinel workspaces, with clearer authoring and sync visibility. ### Bug Fixes * **Agents pick up every incident during a burst** - when several incidents arrived at once, an automatically triggered agent could miss some. All incidents in a burst are now processed. * **Completed agent runs are no longer left marked as failed** - if the connection dropped at the moment a run reported completion, it could stay marked failed and go unbilled despite finishing its work. Completion is now recorded reliably. **2026-08-05** ContraForce activity in Microsoft Sentinel, and Environments tab fixes ### New Features * **Stream ContraForce activity into Microsoft Sentinel** - a ContraForce data connector is now available for Microsoft Sentinel. Once connected, workspace audit activity flows into a dedicated table in your Sentinel workspace, so ContraForce actions sit alongside the rest of your security telemetry for hunting, correlation, and retention. Each connection is scoped to a single workspace. ### Improvements * **Consistent dialogs across the interface** - opening an incident from a link in an email, a Teams card, or a webhook now shows the same incident view as clicking the row in the incidents table. Gamebook and module setup dialogs have been rebuilt to match the rest of the interface. * **Redesigned sign-in landing screens** - the sign-in failure and admin consent screens now match the rest of the product. ### Bug Fixes * **The Environments tab no longer flashes an error before it loads** - opening the tab briefly showed a red "Environment unavailable" message before the content appeared. It now shows a loading indicator, and recovers on its own from momentary connection problems instead of reporting a failure. * **Administrators can open the Environments tab** - administrators who could open every other tab on a workspace were refused access to Environments. They can now read it, in line with every other tab on that page. * **Granting directory access no longer re-approves every ContraForce permission** - the consent prompt for user and license visibility asked an administrator to re-approve ContraForce's entire permission set. It now runs through the Microsoft Defender XDR connection, so only that module's permissions are involved. **2026-08-03** Workspace environment visibility, redesigned investigation panels, and more reliable agent runs ### New Features * **See your workspace's licensing and endpoint coverage** - a new Environment tab in workspace settings shows the security licenses in your tenant and how many seats are assigned, which users hold them, and which endpoints are onboarded to Defender versus still available to onboard. A capability matrix shows which response actions your current licensing supports, and anything that cannot be read is shown as unknown rather than reported as unavailable. Each card refreshes on demand and shows when it was last checked. ### Improvements * **Investigation panels rebuilt on the new interface** - entity insight and investigation panels have been rebuilt, with a redesigned process tree, an actionable related incidents view, and reworked sign-in and audit log inspectors. * **Agent model upgrades keep your throughput capacity** - upgrading an agent's model now carries over the throughput capacity your current deployment is tuned to, instead of resetting it to a default. ### Bug Fixes * **Long-running investigations are no longer reported as failed** - an agent investigation that ran past the gateway timeout could be marked failed and send a failure notification even though it had finished successfully. Runs are now given time to report their real outcome first. * **Agent run history shows every run in the selected range** - the account view showed only a fraction of the runs performed, and did not change when the time range was widened. Counts and breakdowns now cover the entire selected range. **2026-07-30** SentinelOne incident ownership ### Bug Fixes * **Assign an owner to SentinelOne incidents** - the owner control is no longer greyed out on SentinelOne incidents, so you can take ownership, hand work off, and see who is handling what. Ownership is tracked inside ContraForce and is not written back to SentinelOne, which has no owner field of its own. * **Incident owners now show in the all-workspaces view** - for service providers, an owner assigned from inside a customer workspace previously appeared on the incident itself but left the owner column blank in the all-workspaces incident list. SentinelOne and CrowdStrike incidents now show the assigned owner in both places. **2026-07-29-d** V2 is now the default experience ### New Features * **V2 is now the default experience** - every user now gets the modern ContraForce interface automatically. The classic view and the option to switch back to it have been removed. ### Bug Fixes * **Improved incident detail layout on smaller screens** - the Audit and Entities tables on the incident detail page no longer overflow or clip columns on narrower or laptop-width screens, and the layout gives the investigation panel more room instead of squeezing it against a fixed-width response panel. **2026-07-29-c** Agent status policy controls ### New Features * **Agent status policy controls** - choose No Change in the Status after run dropdown so an agent preserves the incident status unless a transition is deliberately configured. ### Bug Fixes * **SLA-aware status options** - SLA pause states are available only when SLA Management is enabled and the assigned workspace has an SLA configuration, preventing invalid or misleading agent policies. **2026-07-29-b** Bulk actions for the incidents table ### New Features * **Multi-select and bulk actions in the incidents table** - select multiple incidents at once and close or reassign them in a single step. Bulk close applies the classification and reason you choose to every incident, correctly mapped for each detection source, even when your selection spans multiple workspaces and sources. Any incidents you do not have permission to change are listed by workspace so nothing fails silently. **2026-07-29** ServiceNow self-hosted URL support and Detected Products license fixes ### Bug Fixes * Self-hosted ServiceNow customers can now enter their actual instance URL when configuring ticketing, instead of being limited to the standard hosted-instance name format. This restores incident sync and ticket creation for self-hosted ServiceNow deployments. * Fixed the Detected Products card so Business Premium, Defender for Business, and other SMB-tier license SKUs are correctly recognized and displayed, instead of being hidden or shown as raw IDs and causing automation coverage to be misreported as "Not licensed." **2026-07-28** Scoped Sentinel ingestion credential, Gamebooks settings tab, and Operating Procedures improvements ### New Features * **Bring-your-own credential for Sentinel incident ingestion** - connect Microsoft Sentinel to ContraForce using a credential you provision and control, scoped to incident ingestion only. The portal shows a one-time deployment card with the ingestion URL, client ID, and secret, and you can rotate or revoke the credential from the portal at any time. A leaked credential cannot be used to inject incidents into any other workspace. ### Improvements * **Dedicated Gamebooks settings tab** - gamebook configuration now has its own tab in workspace settings, with approver management and run-permission controls as a first-class area instead of being at the bottom of the General tab. The tab is deep-linkable and available to workspace owners. * **Operating Procedures workflow overhaul** - linking agents to an OP is now a single search, select, and confirm pass with a full checkbox list, and already-linked agents are shown so they cannot be double-linked. Markdown OPs can be edited and saved in place with a reviewable diff and a revert option before saving, and the preview dialog was redesigned with a comfortable reading width, document identity (name, version, and size), and an always-visible Close button. **2026-07-23** Content deployment to workspaces and incident list reliability ### New Features * **Content deployment to workspaces** - deploy analytic rules from a content repository to one, several, or all of your Microsoft Sentinel workspaces. Each target is checked before you deploy, results are reported per workspace, and a single rule can be rolled back in one workspace without affecting the others. ### Bug Fixes * Fixed an issue where the incidents list could appear empty. If one incident carried a field value the portal did not recognize, the remaining incidents on that page stopped loading. Widening the date range or including closed incidents made it more likely to happen. **2026-07-22-b** Cost Management Center ### New Features * **Cost Management Center** - a single place in the portal to track and manage agent spend, workspace licenses, and billing across all your workspaces. **2026-07-22** Model choice at agent creation and safer model upgrades ### New Features * When creating a Security Delivery Agent in your own cloud, you can now choose the AI model and deployment type (Global Standard or Data Zone Standard) right in the creation wizard, with plain-language guidance on where data is processed. Only models available in your Agent Center's region are offered, and Azure quota is verified before you continue — so a deployment can no longer fail at the last step because of missing capacity. ### Improvements * Upgrading an agent to the newest GPT-5.5 / GPT-5.6 models is now allowed only once the agent runtime supports them, preventing failed incident investigations from premature upgrades. * New Agent Centers use serverless infrastructure for their database, billing only for actual usage. **2026-07-20** Defender automation-aware agent, failed gamebook alerts, and reliable response actions ### Defender Automation Awareness * The Security Delivery Agent now recognizes what Microsoft Defender's own automation (automated investigation, attack disruption, and incident merging) has already handled. Incidents Defender resolved or merged are skipped before the agent spends any compute, and every skip is recorded in the activity log - eliminating duplicate work and reopened tickets. New Native Automations and Detected Products sections on the Defender XDR configuration tab show which automations are actually firing and which Defender products are licensed and emitting signal, with an on-demand Run detection action. ### Agent Notifications * Workspace teams can now opt in to email alerts when an autonomous agent run fails to submit a gamebook, so failed response actions no longer go unnoticed in an incident comment. The new toggle lives under workspace Notifications -> Agent Runs, reuses the existing agent-run recipient list, and is off by default. ### Defender Response Actions * Response actions on Microsoft Defender incidents (such as invalidating a user's sessions) now run reliably on the first attempt. Previously they could fail intermittently and only succeed after several retries, depending on which server handled the request. **2026-07-17** Operating Procedure Template Library and workspace admin management fix ### Operating Procedure Template Library * Service providers can now browse a curated library of pre-built Classification and Response playbook templates covering common incident scenarios, and promote the ones that match their environment straight into their active OP library instead of authoring from scratch. Every template is validated so the agent's classification verdicts are reproducible and its response steps are complete and technically correct, giving new and existing service providers reliable, agent-ready triage and response coverage from day one. ### Workspace Management * Organization admins and workspace admins can once again manage who has access to a workspace (adding, editing, and removing users and groups), regardless of whether they personally hold the workspace Owner role. This restores access that was inadvertently narrowed to Owner-only in the redesigned workspace management screen. **2026-07-15** Incident notification settings without full Sentinel setup ### Bug Fixes * Workspace Owners can now manage incident notification settings even when the Sentinel module is not fully configured. Previously the Notifications page showed a "Configuration unavailable" warning and blocked incident severity preferences and recipients until Sentinel setup was finished, even though incident notifications are not exclusive to Sentinel. **2026-07-13** Defender 'Not Malicious' incident close fix ### Bug Fixes * Closing a Microsoft Defender XDR incident as False Positive with the reason "Not Malicious" now saves correctly. Previously this specific reason could fail with "Request body is incorrect" and the incident stayed open. **2026-07-11** Live agent activity for manually triggered investigations ### Bug Fixes * Manually triggered agent investigations now show the agent's tool-by-tool activity live in the portal, the same as automatic on-queue runs. Previously a manual run showed no real-time progress, leaving analysts unsure whether the agent was working. **2026-07-10-b** Agent user protection in IAM ### Bug Fixes * Agent users are now protected in Workspace IAM and User Management. Previously an admin could change an agent's role or remove it, which silently stopped the workspace's AI agent from responding. Agent accounts are now clearly marked and locked from edits. **2026-07-10** Defender incident close fix and cleaner agent comments ### Bug Fixes * Closing a Microsoft Defender XDR incident with a benign or true-positive classification reason (such as "Confirmed User Activity", "Compromised User", or "Not Malicious") now succeeds. Previously these closes failed with "Request body is incorrect" and the incident stayed open. ### Improvements * Service providers can now turn off the agent metadata header on incident comments the Security Delivery Agent posts to Microsoft Sentinel and Defender. With it off, the comment shows only the agent's written summary, for a cleaner read in the native security console. **2026-07-09** Module names display in full when adding a workspace ### Bug Fixes * When adding a customer workspace, the detection and response module names now display in full instead of being cut off mid-name. **2026-07-08-b** Analytic rule delivery reliability ### Improvements * Analytic rule updates now deploy more reliably to Workspaces with auto-update enabled, and the rule version shown in the portal always matches what is running in Microsoft Sentinel. **2026-07-08** Bug Fixes ### Bug Fixes * Mailbox entities in the incident investigation graph no longer offer user account containment actions (lockout, password reset, MFA reset, session invalidation). User containment remains available on the related user account entities, and mailbox entities without an applicable response action now show "No options available" instead of a misleading error message. **2026-07-07-b** Agent assignment and manual run permission fixes ### Bug Fixes * The Security Delivery Agent no longer assigns itself to Microsoft Defender XDR incidents when its assign-self setting is turned off. Incidents the agent investigates keep their existing owner — or stay unassigned — unless the agent is explicitly configured to take ownership. Analysts updating an unassigned incident's status still become its owner, as before. * Manually triggering an agent investigation is now offered only to users whose role can complete it (Owner and Incident Responder), so runs no longer start and then fail partway with "Failed to submit the investigation result." **2026-07-07** SentinelOne GovCloud console support and platform hardening ### New Features * Connect SentinelOne FedRAMP GovCloud (`s1gov.net`) consoles, with a dedicated static egress IP you can add to your allowlist. ### Security * Ongoing security and reliability hardening across the platform, resolving findings from continuous code analysis. No change to day-to-day behavior. **2026-07-03** Agent run status accuracy fix ### Bug Fixes * Automatic agent investigations that finished after a brief connection timeout are no longer shown as failed. When the agent completes the investigation and reports back, the run is now correctly recorded as completed with its usage. **2026-07-02** Failed agent run notifications ### Features * **Failed agent run notifications** — Configure recipients per workspace to be emailed whenever an agent run fails, with the agent, run, and workspace context needed to act. Recipients are independent from Incident and Gamebook notifications. **2026-07-01** Reliable agent runs during incident bursts, Defender incident coverage, and portal UX polish ### Improvements * Incident detail now fills the full height of large screens, removing the empty space that used to sit below the cards. * The Add Users picker shows each person's name and email, so people with the same name are easy to tell apart. * Dropdown pickers now reveal their options as soon as you focus them, instead of appearing empty until you start typing. * Corrected the "API Token" label casing on the ticketing details view. ### Bug Fixes * Automatic agents now process every incident during a burst. When many incidents arrive for the same customer at once, runs are queued and worked through one at a time per customer, so none are silently skipped. * Microsoft Defender XDR incidents are no longer skipped when a newly created incident has a lower internal id than one already processed. Incidents are now tracked by when they were created, so anything visible in the Defender portal is reliably ingested. **2026-06-30** Portal sign-in and Defender incident reliability fixes ### Bug Fixes * Fixed a sign-in issue that could trap the portal in a loop on Firefox; signing in now works reliably across Firefox, Chrome, and Edge. * Fixed an issue where Microsoft Defender XDR incidents created during a brief polling interruption could be missed; incidents are now reliably re-scanned and ingested once polling recovers. **2026-06-29** Faster incident loading and access fixes ### Performance * Opening an incident is now dramatically faster. Incidents with many alerts that previously took 30 or more seconds to load now return in a few seconds, in the portal and through the API. Evidence loads on demand when you open the Evidence tab. ### Bug Fixes * Resolved an issue where some administrator accounts could be incorrectly denied access. * The incident comments API now correctly identifies an incident's closing comment. **2026-06-25-b** Reliability fixes for automated password resets ### Bug Fixes * Turning on automated password resets for end-customer users is now reliable: after granting Microsoft consent the setting enables itself instead of needing a second click, and tenants that need an additional consent are guided through it instead of getting stuck. **2026-06-25** Bulk email-remediation fix ### Bug Fix * Bulk **Delete Email** remediation now handles messages that share a reference correctly. Plan rows without a specific entity no longer collide, so every targeted email is actioned. **2026-06-24-b** Regional detection rule updates and Web Application Firewall fix ### Feature * Deployed security detection rules now stay up to date automatically as new versions are published, across all ContraForce regions. ### Bug Fix * Web Application Firewall analytic rules now deploy correctly; a rule name-matching issue had previously prevented them from being applied. **2026-06-24** Reset MFA response action and queued Gamebook approval fix ### Feature * New **Reset MFA** response action: responders can clear a user's registered multi-factor authentication methods from a Gamebook so the user must re-enroll MFA at next sign-in — available in the portal and to the Security Delivery Agent, with no extra admin consent. ### Bug Fix * Approving a queued Gamebook now runs it. Previously the approval appeared to do nothing and the Approve button kept returning; approved response plans now dispatch and show a running state. **2026-06-23-b** Log Search reliability fix ### Bug Fix * Log Search now runs KQL queries reliably again across Microsoft Sentinel and Microsoft Defender XDR workspaces; queries had begun returning an error instead of results. **2026-06-23** New plans & billing, password resets, classification trends, and UK availability ### Feature * New plans, pricing, and a Billing & Plan management screen: plan tiers now carry entitlements, XDR Only vs. XDR + SIEM is gated by tier, extra workspaces are billed automatically, and investigations are metered with trial limits enforced. * Service providers can now run automated password resets for end-customer users directly when the capability is enabled. * Incident classifications are now consistent across detection modules, with a new Classification Trends widget showing how classifications break down over time. * Admins can view and edit an account's Trial End Date when changing its subscription status from the modernized Admin Center. * ContraForce is now available on a UK-resident platform stack, with tooling to migrate existing customers from US to UK. ### Bug Fix * The Quarantine File gamebook now runs successfully (it previously failed with an invalid-hash error). * Customers onboarded to Sentinel without the ContraForce Apollo deployment now reliably receive their incidents. **2026-06-16** Manual incident email & webhook actions, and read-only workspace agent visibility ### New Features * You can now send an incident notification email to the end customer on demand from the incident's Actions menu — pick recipients (with quick-select from saved workspace contacts), then either send the "View Incident" email or send and escalate the incident to Waiting on Customer. Every manual send is recorded in the incident's audit trail. * A new "Trigger webhook" action on the incident detail page lets you push the current incident to any of the workspace's enabled webhooks on demand. The delivery is signed, audited, and appears in the webhook's events log just like an automatic delivery, marked as manually triggered. * End-customer workspaces now have a read-only Agents tab showing which AI agent is assigned and its configuration, plus a Run History view with a time filter and links to related incidents. ### Bug Fixes * Incident and gamebook links in notification emails now open regardless of how old the incident is or which time filter you have selected — deep links from emails, webhooks, and ITSM tools no longer fail with "couldn't load incident." Gamebook notification email subjects now also show the workspace, source, severity, and incident title at a glance. **2026-06-12** Command Center closure-metrics fix, clickable agent OP references, and a refreshed Ticketing page ### Bug Fixes * Incident closure metrics now keep the classification reason, so the "By reason" breakdown in Command Center is accurate. You can also now see incidents your service provider closed on your behalf in your own workspace's Command Center. ### Improvements * You can now click a matched OP chip in an AI agent's investigation activity to open and read the full operating procedure that guided the agent's classification. * The Ticketing integration details page has a refreshed look and feel consistent with the latest ContraForce experience. **2026-06-10-b** Onboarding completion and User Management consent fixes ### Bug Fixes * Pre-onboarded workspaces now activate automatically once the customer connects their selected security modules and grants admin consent. * Service providers can mark a pre-onboarded workspace as onboarded directly from the Onboarding tab. * The User Management settings tab now prompts to connect tenant directory access when it's missing. **2026-06-10** Sentinel incident ingestion resilience and Incidents filter fix ### Improvement * Improved the reliability of Microsoft Sentinel incident detection — incidents keep flowing into ContraForce even when the underlying infrastructure isn't reliably deployed or available, thanks to an automatic fallback ingestion path. ### Bug Fix * Fixed the Incidents page filter chips overflowing past the right edge of the table card on wider desktop screens; they now wrap and stay contained within the panel. **2026-06-09** Log Search revamp and Security Analytics fixes ### Improvement * Redesigned the Log Search results experience: a readable, resizable, searchable grid where you can expand any record to see full detail, with reliable workspace switching and a Stop button that truly cancels a running query. ### Bug Fix * Fixed a Security Analytics issue where a rule could appear multiple times and Deploy/Undeploy didn't always reflect the correct state. **2026-06-06** Gamebook notifications ### New Features * Get notified the moment a gamebook runs in a workspace, whether an analyst or the AI Agent started it. A new Gamebooks tab in workspace notification settings lets you toggle "Gamebook ran" and "Gamebook queued" events and maintain a dedicated recipient list, separate from incident notification recipients and gamebook approvers. * New `gamebook.run.v1` webhook event: subscribe a webhook to receive a signed delivery whenever a gamebook runs, ideal for automatically opening tickets in your ITSM. * The workspace Notifications page is now organized into Incidents and Gamebooks tabs. **2026-06-05-b** Log Search workspace-scoping fix ### Bug Fix * Log Search and Advanced Hunting now always run against the workspace you've selected — partner users querying a managed customer's Microsoft Defender no longer see intermittent consent errors, and results stay scoped to the chosen workspace. **2026-06-05** Unified incident classification, Classification Trends, and Agent Center fixes ### New Features * **One classification language across every detection module.** Closing an incident now uses four clear verdicts (True Positive, False Positive, Benign Positive, Undetermined) with a curated reason list per verdict, consistent across Microsoft Sentinel, Microsoft Defender, SentinelOne, and CrowdStrike. The verdict you pick is preserved exactly in ContraForce, even when the connected security tool cannot store it. * **Classification Trends in Command Center.** A new widget breaks down closed incidents by verdict, reason, and detection module. Click any verdict to jump straight to the matching incidents in the inbox. * **Filter the inbox by classification and reason.** New filters, columns, and shareable links let you slice closed incidents by how they were classified. * **Closures made in your security tools now flow into ContraForce.** When an incident is closed directly in the vendor console, ContraForce records the closure with its classification, adds an audit entry, and counts it in your closure metrics. * **New `incident.closed.v1` webhook.** Subscribed integrations are notified whenever an incident closes, including the classification, reason, and whether an analyst or an upstream tool closed it. ### Bug Fixes * **Agent Center: Models & Quotas now shows only self-hosted agents.** ContraForce-hosted (Our Cloud) agents no longer appear in configuration that only applies to your own cloud. * **Agent Center: usage chart is readable in light theme.** Axis labels no longer render invisible against a light background. * **Agent Center: run cost is no longer shown for ContraForce-hosted agents.** Cost figures appear only for agents running in your own cloud, where they reflect your actual spend. * **Agent model upgrades reliably switch the running agent to the new model.** Updating an agent's model from Models & Quotas now re-points the agent's runtime at the newly provisioned model deployment and notifies you when the upgrade completes, with success and failure counts per agent. **2026-06-04** Agent Center recovery, clearer update feedback, and incident comment fixes ### New Features * **Restart a failed Agent Center deployment.** When an Agent Center deployment fails, you can now delete it and start fresh with different settings (region, resource group, or subscription) instead of only retrying the same configuration. We also remind you to remove the old Azure resource group so it doesn't sit idle. ### Bug Fixes * **Agent updates now tell you whether they actually finished.** You get a clear success or failure notification when a background agent update completes — with actionable detail (like a permissions issue) on failure — instead of only a "started" message. * **Cleaner agent investigation comments on forwarded incidents.** Agent investigation comments on Microsoft Defender incidents forwarded to Sentinel now appear as a single, clean activity card instead of broken fragments. * **More reliable Sentinel onboarding.** Onboarding now verifies subscription-owner access before deploying, preventing customers from being onboarded without the required ContraForce infrastructure. **2026-06-03** SLA chip and audit-trail refinements, plus a workspace re-onboarding fix ### Bug Fixes * **SLA chip no longer sticks on "At Risk" once the target is met.** When an incident's time-to-first-response (or resolution) crossed into At Risk but was then handled in time, the SLA chip kept showing "At Risk"; it now flips to On Track once met. Only a genuine breach stays red. * **Re-onboarding a previously-removed workspace now works cleanly.** Removing a pre-onboarded customer workspace could leave the customer's account record pointing at the deleted workspace, stranding them with no access on the next sign-in. Removing a workspace now cleans up those records, so re-onboarding the same customer provisions them correctly. ### Improvements * **SLA state changes are now recorded in the incident audit trail.** Every SLA tier change (At Risk, Breached, or Met) for both the response and resolution clocks, plus SLA clock pause and resume, now appears as an entry in the incident's audit tab, so you can see exactly when and how an incident tracked against its SLA. **2026-06-02-b** SentinelOne setup reliability fix ### Bug Fixes * Fixed an issue where a SentinelOne detection module could appear connected while silently failing to pull threats. Configuration problems are now surfaced immediately, and a module cannot be enabled until it is fully configured, closing a hidden detection-coverage gap. **2026-06-02** Workspace SLA visibility, Delete Email gamebook fix, and V2 portal fixes ### New Features * **See the SLA applied to a workspace.** Workspace settings now has a read-only SLA tab showing the response and resolution targets configured for that workspace, so customers and service providers can confirm what's in effect at a glance. The configuration name on an incident's SLA timeline links straight to it. ### Bug Fixes * **SLA now tracks on service-provider-managed workspaces.** When a service provider assigned an SLA configuration to a customer workspace, that workspace's incidents weren't picking it up. Assigned configurations now track correctly, and SLA chips no longer freeze in cross-workspace views. * **Delete Email gamebook runs again.** The delete-email response action was failing with "Unable to run the delete email gamebook" because the mail entity wasn't resolved to the identifier the mailbox provider expected. It now resolves the message and completes the action. * **Command palette shortcut works in the new UI.** Ctrl+K (Windows/Linux) and ⌘K (macOS) now open Quick actions in the V2 portal, and the shortcut hint shows the correct key for your OS. * **Consistent incident view from agent history.** Clicking an incident in an agent's Execution History now opens the V2 incident view, matching the rest of the portal. ### Security * **Hardened email lookups.** The delete-email path now guards its mailbox lookup against message-identifier injection. **2026-05-29** Incident SLA tracking with live response and resolution timers ### New Features * **Incident SLA tracking.** Configure per-workspace response and resolution targets for each severity. The incident inbox gains "Time to First Response" and "MTTR" columns showing a live countdown chip on every row — "SLA 12m left", "At Risk 5m left", "Breached 3m over", or "On Track" once settled. Chips tick down without re-loading and update in real time when any analyst changes status or assignment from any session. The incident detail header carries the same chip alongside a dedicated SLA tab with the configured targets and the running clock. Entering an On Hold or Waiting on Customer status (introduced 2026-05-27) freezes both the response and resolution clocks; resuming continues from where they left off. Available as an opt-in feature — contact your ContraForce contact to enable it on your tenant. **2026-05-27** Phishing-email investigations, paused incident states, and per-run agent cost tracking ### New Features * **Security Delivery Agents now read the actual content of phishing emails.** Body, headers, embedded URLs, and attachment metadata are fetched automatically using your existing Microsoft 365 Response connection, so the agent can flag social-engineering patterns, sender spoofing, and suspicious links without an analyst opening the message. * **New "On Hold" and "Waiting on Customer" incident statuses.** Analysts can pause incidents that are blocked on a vendor RFI, a scheduled change window, or a pending customer reply, instead of leaving them as `Active`. The new statuses are ContraForce-native and don't write back to the upstream source. * **Vendor-side status changes now appear in the audit timeline.** When an incident is closed or reopened from the Azure portal (or another upstream tool), an attributed audit row is now recorded in ContraForce, so the CF view and the upstream view never silently disagree. * **Per-run agent token breakdown and dollar cost.** Every Security Delivery Agent run records its prompt / cached / completion token counts and the USD cost, visible on the per-agent execution history and the agent-center "Recent runs" strip. A row-level "Breakdown" link opens the detailed dialog. ### Improvements * **Agent token-usage telemetry.** Per-run baseline, per-tool-call sizes, and per-turn API usage are now captured so upcoming agent cost optimizations are measurable. **2026-05-20-b** Stale-session recovery and MSP agent webhook fix ### Bug Fixes * **Stale Microsoft sessions now silently recover.** When a signed-in user's Microsoft session quietly went stale — token expiry, signing in elsewhere, or a Conditional Access change — the portal was dropping them on a "We couldn't load your session" error screen and forcing a manual retry. The portal now routes them through interactive re-authentication silently and returns them to where they were, keeping analysts in flow. * **MSP-managed agent configurations now save webhooks correctly.** When an MSP managing a customer workspace tried to save an Agent configuration that referenced a webhook on a classification card, the save was failing with "Failed to save agent configuration" and leaving the webhook orphaned. The save now succeeds and the webhook binding is persisted as expected. ### Improvements * **Dependency refresh for security and reliability.** Updated the third-party libraries the platform depends on to pick up the latest bug fixes, security patches, and performance improvements. No visible behavior changes — customers benefit from a more reliable platform with fewer known vulnerabilities. **2026-05-20** Onboarding affordances on the new portal and Connect tenant recovery on the Agent Center ### New Features **Onboarding affordances restored on the new portal.** The Command page now shows the setup prompt for admins who haven't completed onboarding, the invite-admin flow for non-admin teammates, and the dismissible getting-started checklist after setup. These existed on the classic experience and are now consistent across both. **"Connect tenant" recovery on the Agent Center.** Self-service customers who open the Agent Center before completing the broader ContraForce API consent now see the same recoverable "Connect tenant" banner that already appears on detection module configuration pages. After granting consent, the admin lands back on the originating page and continues — no support ticket required. ### Bug Fixes **Module configuration consent prompt fixes.** Two small timing bugs in the "Connect tenant" recovery flow on module configuration pages were addressed: the prompt now appears reliably on the very first visit (previously hidden in cases where the consent gap surfaced on the module fetch itself), and it no longer briefly re-appears immediately after a successful consent grant (the post-consent propagation wait was missing a second probe). **2026-05-19** Fixed AI Query Assistant and module configuration crash for un-consented tenants ### Bug Fixes * **AI Query Assistant restored.** The natural-language KQL generator is working again. Analysts can ask for a query in plain English and get a usable KQL statement back, instead of the silent error the endpoint had been returning. * **Module configuration no longer crashes for un-consented tenants.** Self-service onboarded users who hadn't yet completed Entra admin consent for the ContraForce API were hitting a JSON-parse cascade on the Sentinel, Defender XDR, and Agent Center module configuration pages. The pages now detect the missing consent and surface an actionable "Connect tenant" prompt that walks the admin through the grant flow, so customers can self-unblock without contacting support. **2026-05-18-b** Advanced classification actions for Security Delivery Agents, and opaque pagination tokens on the v2 API ### New Features **Advanced classification actions for Security Delivery Agents.** Agent Configuration cards now support an **Advanced** mode where each classification verdict (true positive, benign positive, false positive, etc.) can be assigned a custom action. Pair a classification with a webhook to receive a signed `agent.investigation.completed.v1` event at the moment the agent reaches that verdict — useful for escalating true-positive incidents into your SIEM, ticketing, or on-call tooling. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) and [Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook). ### Improvements * Pagination tokens returned from `POST /api/v2/incidents/across-workspaces` are now opaque to API consumers. Partners continue to round-trip tokens unchanged from response to next request; only the internal token format has changed. A token that has been hand-modified or hand-built is rejected with `400 VALIDATION_ERROR` rather than failing further down the stack. See the worked example under [Cross-Workspace Endpoints](/api-reference/endpoints#paginating-/incidents/across-workspaces). **2026-05-18** The redesigned ContraForce Portal (v2) is now generally available ### New Features **The redesigned ContraForce Portal is now generally available.** Starting today, the new portal is the default experience for everyone. You will land on v2 the next time you sign in. v2 brings: * A refreshed visual language built around higher-density, more scannable information. * Reorganized navigation that surfaces the actions analysts actually reach for. * Reworked incident, gamebook, agent, operating procedure, log search, and command pages with consistent layouts and a unified design system. Prefer the classic experience? Open the user menu (top right) and pick **Switch to classic experience.** Your choice is remembered per browser, so you can move between the two while you get used to v2. **2026-05-16** Fixed an intermittent issue that blocked v2 agent investigations ### Bug Fixes * Resolved an intermittent issue that could prevent the v2 incident agent from starting an investigation. **2026-05-15-b** External API incidents endpoint now returns the full payload by default, and pagination is documented ### Bug Fixes * `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}` now returns the full incident detail (alerts, entities, investigation details, evidence, and the gamebook catalog) by default. Previously the endpoint returned the same lightweight payload as the cross-workspace list, with the richer fields hidden behind an undocumented `?withDetails=true` query parameter. Partners integrating from Logic Apps, Power Automate, or any OpenAPI-driven client now get the documented response without needing to know the flag exists. * Cross-workspace incident requests that target a workspace where the requested incident source is not enabled (for example, asking for a Defender XDR incident on a workspace where only Sentinel is onboarded) now return a clear `404 NOT_FOUND` with a message naming the source, instead of an opaque `500` or `502`. The same applies when an incident does not exist in the workspace's underlying tenant — partners receive a `404` they can handle, not an upstream-error response. * The portal's incident detail page and gamebook workbench now display a friendly "Incident unavailable" banner with a working breadcrumb when a stale or deleted incident is opened from a saved link, instead of hanging on a loading skeleton. ### Improvements * The cross-workspace incidents list (`POST /incidents/across-workspaces`) now publishes its pagination protocol in the OpenAPI spec. The continuation-token mechanism (`isFirstCall`, `workspacePageTokens` on the request, `sourcePageTokens` and `moreIncidentsAvailable` on the response) is fully described so partners can build paging loops against a documented contract. **2026-05-15** Workspace picker now filters the Workspaces, Log Search, and Agent Center pages ### Bug Fixes * The workspace selector in the top navigation now filters the Workspaces page, the Log Search page's workspace and module selector, and the Agent Center (including the Overview tab and the Recent Runs strip). Previously these pages ignored the selector and continued to show data from every workspace you have access to, which made it hard to focus on a subset of customers. **2026-05-14** Sentinel and Defender setup accepts inherited and group-based Azure permissions ### Bug Fixes * Microsoft Sentinel and Microsoft Defender XDR module setup now accepts administrators whose subscription permissions come from inheritance (management group or tenant root), Entra group membership, or the Contributor and User Access Administrator combination. The form previously rejected these valid permission patterns with a "you must have Owner" message even when the user could fully administer the subscription. * Fixed a stuck-loading state on the module configuration screens when viewing a workspace owned by a tenant other than your active tenant. The Azure role prerequisite would spin indefinitely; it now resolves immediately so you can see why the module cannot be configured. **2026-05-13** In-Portal Release Notes & Defender Agent Comment Fix ### Portal * Introduced an in-portal release notes side panel. When new releases ship, a release-notes indicator appears in the top navigation with an unread badge showing how many you have not yet seen. The panel is also reachable from the user-avatar dropdown so you can revisit the release history at any time. ### Bug Fixes * Resolved a character-encoding issue that prevented certain punctuation marks from displaying correctly in incident classifications. * Fixed an issue where Microsoft Defender XDR agent investigation comments could render as broken JSON when the comment payload was larger than Defender's per-comment character limit. Long agent investigation comments now stitch back together correctly in both the Microsoft Defender XDR portal and the ContraForce incident view. **2026-05-12** Incident Management in the v2 API ### v2 API * Incident management is now available in the v2 API. Customers integrating ContraForce through the v2 OpenAPI specification can read and update incidents programmatically, alongside the existing v1 endpoints. **2026-05-01** Word OP Uploads ### Operating Procedures * The OP upload experience now accepts Microsoft Word (`.docx`) files. Uploaded Word documents are stored, indexed, and searchable alongside your existing PDF and Markdown OPs, so you can publish OPs straight from your Word library without converting them first. **2026-04-27** Agent Center Visibility & Control ### Agent Center * Added a new **Models & Quotas** panel that shows the AI models powering your Security Delivery Agents, including version, capacity, and live per-region usage with a progress bar — so you can see capacity headroom at a glance. * Restricted models now display a badge and a direct link to the access-request flow, making it clear which models require additional access and where to ask for it. * You can now upgrade a deployed agent to a newer model directly from the Agent Center without filing a ticket. The upgrade flow lists the models actually available in your environment, and upgraded agents start using the new model immediately. * Redesigned the **Resources** tab with grouped cards organized by resource role, plus a live health chip on each resource (Available, Degraded, Unavailable, or Unknown). When something goes wrong, you can identify the unhealthy resource without leaving the portal. **2026-04-23** Bug Fixes ### Bug Fixes * Fixed an issue where Organization Admins could not create workspaces or Security Delivery Agents despite having the correct role assignment. * Fixed an issue where Microsoft Defender XDR incident comments displayed as fragmented "(N of M)" pieces instead of complete messages. **2026-04-22** Comment Attribution & Bulk Incident Reliability ### Incident Management * Comments posted on Microsoft Defender and SentinelOne incidents now show the original author from the source platform, matching the experience already in place for Microsoft Sentinel incidents. ### Bug Fixes * Fixed an issue where bulk-closing incidents did not refresh the aggregate counts on the Command Dashboard. * Fixed an issue where bulk incident updates could silently fail mid-operation, leaving some incidents unchanged. **2026-04-21** Bug Fixes ### Bug Fixes * Fixed a security issue where deleted user accounts could retain portal access until the next sign-in cycle. **2026-04-20** UI Experience Opt-in ### Portal * Users can now opt into the new UI experience individually from their profile, allowing teams to evaluate the new design at their own pace before broader rollout. * Let us know if you'd like to enable the new UI for your team or have any feedback on the design! ### Bug Fixes * Improved SentinelOne incident polling reliability and refined threat-handling behavior. **2026-04-17** Bug Fixes ### Bug Fixes * Fixed an issue where analysts could lose visibility into an incident after Microsoft Defender merged it with another incident. **2026-04-14** OmniView Metrics Dashboard & Sync Fixes ### OmniView * Introduced the **OmniView Metrics Dashboard**, surfacing customer health scores, operational and business metrics, and a flagged-accounts view in a single analytics dashboard. * The Account Overview page has been redesigned with a health-score summary, configured modules, and Security Delivery Agent activity metrics so service providers can assess each account at a glance. ### Bug Fixes * Fixed an issue where a user's organization role could revert to its original value after a User Management sync. * Fixed an issue where Microsoft Sentinel marketplace scanned sources failed to display when duplicate data source records existed with different casing. * Fixed an issue where analytic rule queries returned no results when data source ID casing did not match exactly. * Fixed an issue where Sync Users deactivated service accounts not matching identities in their directory. **2026-04-13** Cross-Workspace Incident Search & API Documentation ### Incident Management * The Command Palette now supports searching incidents across all of your workspaces, so you can jump directly to an incident regardless of which workspace it belongs to. ### API Reference * Published an actively maintained OpenAPI specification for the v2 ContraForce API, making it easier to generate clients and integrate ContraForce with your own tooling. ### Agent Center * Agent creation now validates available GPT quota during setup, surfacing capacity issues before you finish configuring the agent. ### Bug Fixes * Fixed an "Agent not found" toast that appeared when OmniView admins loaded executions for a managed account's agent. **2026-04-10** Bug Fixes ### Bug Fixes * Fixed an issue where EventCast webhook configurations were not delivered correctly for MSP tenants. **2026-04-09** Operating Procedures in Agent Deployment ### Agent Center * The Operating Procedures library is now integrated directly into agent deployment - agents pick up relevant OPs as part of the configuration flow, removing the need to attach them as a separate step. **2026-04-08** Starter OPs ### Agent Center * Starter OP templates are available for new customers, providing ready-made examples that accelerate Security Delivery Agent onboarding. * Reach out to your ContraForce contact to get these OPs for your organization and start customizing them for your team. * OPs now persist with full backend support, ensuring uploaded procedures are durably stored and accessible to agents at runtime. **2026-04-07** Customer API Clients ### REST API * Customer API Clients are now available. Create and manage API clients with scoped permissions and workspace-level access from a new portal experience that includes a creation wizard, a details page with scope and audit tabs, and a request-log viewer for monitoring usage. ### Workspace Management * The subscription picker for the Microsoft Sentinel module and Agent Center configuration now supports searching by subscription ID, making it easier to locate the right subscription in tenants with many subscriptions. ### Performance Improvements * Added additional health monitoring across all platform services for improved reliability and faster detection of service disruptions. **2026-04-06** Bug Fixes ### Bug Fixes * Fixed an issue where Gamebook orchestration could stall on timer cancellation, leaving Gamebooks stuck in a Running state. **2026-04-03** Time Zone Preferences ### User Profile * You can now set your preferred time zone in your user profile, and the platform will display all dates and times in your local zone. * Hovering over any date or time displays a tooltip showing the original UTC value, removing ambiguity when collaborating across time zones. **2026-03-31** Audit Log Stability ### Bug Fixes * Fixed an issue where the incident audit log could fail to render certain entries from the unified incident pipeline. **2026-03-28** Closing Comments in Comments Tab ### Incident Management * When you close an incident with a comment, that comment now appears in the **Comments** tab in addition to the **Summary**, keeping the full conversation history in one place. **2026-03-27** AI Comment Attribution & Workspace Reader Role ### Incident Management * Comments posted by Security Delivery Agents now display with a distinct visual treatment so analysts can quickly distinguish AI-generated comments from human analyst input. * Incident notification emails now include the source platform in the subject line, making it easier to filter and route alerts. ### Workspace Management * Added a read-only **Workspace Reader** workspace role that gives end customers and auditors view-only access to incidents and reports without permission to make changes. ### Agent Center * Security Delivery Agents now support a configurable **Should Assign Self** option that controls whether an agent automatically assigns itself as the incident owner during processing. **2026-03-26** Workspace Role Assignment Fixes ### Bug Fixes * Fixed an issue where the workspace name was missing from the **Role Assignment** view in User Management. * Improved reliability when removing role assignments so changes apply consistently on the first attempt. **2026-03-25** AI Query Assistant & Auto-Refresh ### Log Search * Introduced an **AI Query Assistant** for Advanced Hunting Log Search. Describe what you're looking for in plain language and the assistant generates the corresponding query for you. ### Incident Management * Incident tables and dashboards now auto-refresh, so the data you see stays current without manually refreshing the page. **2026-03-24** SentinelOne Gamebook Reliability ### Bug Fixes * Improved error handling for SentinelOne Gamebook actions so failures surface clearly instead of leaving Gamebooks in an ambiguous state. **2026-03-20** Operating Procedures ### Agent Center * Introduced **Operating Procedures** - a centralized library of security operating procedures for your Security Delivery Agents. Upload OPs via drag-and-drop with type selection and metadata, browse and filter them in a dedicated list view, and preview content in a slide-over detail panel. * Link OPs to specific agents and update procedures over time with edit, re-upload, and cascade-delete actions. Each agent's details page now includes an OP section showing its associated procedures. ### Workspace Management * Onboarding role validation now accepts Cloud Application Administrator and Application Administrator in addition to Global Administrator, supporting least-privilege Microsoft Entra ID deployments. ### Performance Improvements * Removed the cookie consent banner by switching analytics to session-only storage, simplifying first-load behavior for portal users. **2026-03-03** Agent Execution History & Account Management ### Agent Center * You can now review a complete history of every Security Delivery Agent execution from the **Execution History** tab on the Agent Details page. Each entry captures the timestamp, trigger source, incident, data source, severity, AI token usage, and outcome — providing full visibility for compliance and troubleshooting. * The portal now displays a notification when a Security Delivery Agent update is available, so you can update without checking manually. ### Workspace Management * Organization Admins can now permanently delete inactive accounts and all associated data, preventing stale accounts from consuming resources or cluttering the platform. ### Bug Fixes * Fixed an issue where the **Configure and Save** button on the agent configuration page was always enabled, even when no changes had been made or the user lacked the required permissions. **2026-03-02** Webhook Integrations ### Bug Fixes * Fixed an error that prevented non-partner users from loading the multi-workspace incident list. **2026-02-26** Defender for Endpoint Agent Automation ### Agent Center * Security Delivery Agents can now automatically detect and respond to Microsoft Defender for Endpoint incidents without requiring Microsoft Sentinel forwarding. Once configured, ContraForce polls Defender for Endpoint for new incidents and triggers your agent automatically — enabling a fully autonomous response workflow for environments using Defender for Endpoint directly. ### Bug Fixes * Fixed an issue where users in tenants with 50 or more Microsoft Entra ID group memberships silently lost real-time incident updates and portal connectivity. **2026-02-25** Gamebook Approval Controls ### Gamebook Improvements * Reviewers can now **Deny** a Gamebook queued for approval, removing it from the queue rather than leaving it pending indefinitely. ### Bug Fixes * Fixed a permissions issue where users with the Incident Analyst role could submit a Gamebook for approval, but it could execute instead of waiting for review. **2026-02-23** Bug Fixes ### Bug Fixes * Fixed a layout issue where incident table filters appeared misaligned on screens under 1800px wide. * Fixed an issue where the **Link Ticket** dialog only showed Jira projects A–F (approximately 10 results) and search had no effect, preventing analysts from linking incidents to projects not in the initial list. * Fixed an issue where Security Delivery Agents failed to update incident status due to a validation error, causing automation rules to not apply correctly. * Fixed an issue where audit log entries for agent-triggered status changes and owner assignments recorded the incorrect account ID. **2026-02-18** CMS Improvements & Workspace Management ### CMS Updates * Improved detection rule reliability by fixing issues with multi-table rule deployment. * Improved several detection rules for better accuracy and fewer false positives. ### Workspace Management * You can now delete a pre-onboarded tenant that hasn't completed setup, simplifying workspace cleanup. * Workspace tags now display more relevant contextual information, replacing the outdated "Configuration (XDR + SIEM)" label. ### Gamebook Improvements * Added a **Workspace** column to the Gamebook Activity view, making it easier to identify which workspace each Gamebook execution belongs to. ### Bug Fixes * Fixed a crash on the incidents list when viewing multiple workspaces caused by a module configuration change. * Fixed "Last Modification" in Group Management displaying "0 days ago" instead of the actual date. **2026-02-12** Gamebook Reliability ### Agent Center * Improved Security Delivery Agent reliability when investigating workspaces where certain Gamebook extensions are not enabled. ### Bug Fixes * Fixed an issue where Gamebooks could get stuck in a pending or running status. * Fixed visual rendering issues in several portal components. **2026-02-10** Incident Management Improvements ### Incident Management * Added an **Assign to me** quick-action button to incident details and the incident modal, enabling analysts to claim incidents faster. * Incident IDs now appear consistently in the breadcrumb, URL, and page header for easier reference and sharing. * Consolidated workspace filtering — individual table workspace filters have been replaced by the global workspace filter at the top of the page for a cleaner, more consistent experience. ### Gamebook Improvements * The Gamebook approval button now displays an informative tooltip explaining why approval is unavailable when prerequisites haven't been met. ### Bug Fixes * Fixed an issue in the Agent Center where pressing Enter during agent creation would prematurely submit the form. * Fixed a data source usage query failure affecting Google Workspace Reports. **2026-02-07** Dock Panel Improvements ### Dock Panel Navigation * The dock panel now opens to the **Browse** tab by default when expanded, providing faster access to workspaces and navigation. * The **Recent** tab now correctly displays workspaces you've recently accessed, improving workspace discovery. * Added a visual indicator to the active dock panel tab, making it easier to see which tab is currently selected. ### Bug Fixes * Fixed an issue where the dock panel collapsed when navigating between workspaces. * Reduced unnecessary re-renders when interacting with dock panel tabs. **2026-02-06** Incident Experience & Data Source Monitoring ### Incident Details Redesign * The incident details experience has been redesigned with improved entity organization, clearer section navigation, and faster load times. * Entity lists in incident details now show enriched context directly in the list view. * Incident tabs have been reordered to show **Comments** first, followed by **Audit**, improving the workflow for analysts reviewing incident activity. ### Data Source Activity Monitoring * Data source activity charts now update in real-time, giving administrators immediate visibility into ingestion health without refreshing. * Added a new "Last Seen" indicator to quickly identify stale or disconnected data sources. ### Agent Center * Improved agent investigation messaging — when an agent investigation takes longer than expected, the notification now indicates that the agent will continue working in the background rather than showing a timeout error. ### Bug Fixes * Fixed time zone display issues in incident timestamps. * Resolved entity context panel occasionally not loading for certain entity types. * Fixed an issue where the Agent Center failed to display available agent updates. * Removed an inaccurate tooltip from the Log Search run button. **2026-02-05** Agent Deployment & Filtering Improvements ### Agent Deployment * Simplified agent deployment with a new guided wizard that validates Azure prerequisites before provisioning. * Added deployment status notifications so administrators know when agents are ready. ### Filter Persistence * Filters across the Command dashboard, Incidents, and Gamebooks pages now persist across sessions, reducing repetitive filter configuration. ### Bug Fixes * Fixed agent configuration page not loading when no agents were deployed. * Resolved intermittent failures when saving notification preferences. * Fixed Gamebook Activity filter not correctly displaying queued Gamebooks. **2026-02-04** Performance & Stability Updates ### Platform Performance * Optimized incident list queries, reducing load times by up to 40% for high-volume workspaces. * Improved caching for workspace metadata, reducing redundant API calls during navigation. * The Incidents page now defaults to a 3-hour time filter instead of 24 hours, improving initial load times for high-volume workspaces. ### Gamebook Execution * Gamebook execution logs now stream in real-time, providing immediate feedback during manual and automated runs. ### Bug Fixes * Fixed memory leak in the incident polling service. * Resolved rare race condition causing duplicate incident entries in the UI. * Fixed an issue where pre-onboarding a new workspace did not correctly assign owner access to the administrator. * Fixed an issue where administrators could not access agent configuration from the Agent Center. **2026-02-03** Workspace Manager & Bug Fixes ### Workspace Manager * Added tooltips to the **CMS** and **Settings** icons in the Workspace Manager, matching the tooltip pattern used elsewhere in the portal. ### Bug Fixes * Fixed an issue where workspace group membership changes were not reflected until page refresh. * Resolved CMS rule deployment failures for workspaces with special characters in their names. * Fixed entity search returning incomplete results for IP addresses. * Corrected tooltip alignment issues in the Command dashboard widgets. * Fixed entity context menu in the Gamebooks workbench requiring a second click to show available actions. * Fixed an error when viewing the Alert Rule tab for incidents from Microsoft Defender for Endpoint and other non-Sentinel sources. * Fixed incident closure failing for Microsoft Defender for Endpoint incidents. * Fixed the **Configure and save** button remaining clickable after completing Microsoft Sentinel configuration. **2026-01-23** CMS Migration, .NET 10 Upgrade, and Agent Improvements ### Content Management System (CMS) Migration * Analytical rules, security content, and CMS capabilities are now fully integrated into the IRIS platform, delivering a unified experience for managing detection rules and security content without switching between tools. ### Platform Upgrade to .NET 10 * The platform has been upgraded to .NET 10, improving performance, security, and long-term supportability across all services. ### Agent Center Enhancements * Administrators can now update agent container images directly from the Agent Center, reducing operational overhead when deploying new agent versions. * Agent efficacy improvements: agents now have access to sign-in logs, directory logs, device timelines, and related incidents as investigation tools — enabling richer, more accurate automated investigations. * Default AI model capacity increased to 150K tokens per minute, improving agent throughput for high-volume environments. ### Gamebook Fixes * Resolved an issue where the gamebook approval button was not functioning correctly in the incident detail modal. ### Notification Settings * Users can now toggle severity-based notifications without requiring recipients to be configured first, simplifying initial notification setup. ### Filtering Experience * Filters across the portal now persist as you navigate between pages, eliminating the need to re-apply filters repeatedly. ### Bug Fixes * Fixed an issue where API error responses with empty bodies caused client-side errors. * Fixed null reference errors when agents array was uninitialized. * Resolved issues with SentinelOne and Azure response module configuration logic. * Fixed security rule detail page errors. **2025-12-23** Command 2.0 Dashboard and Metrics Platform ### Command 2.0 Dashboard * The Command page has been redesigned with a new dashboard layout featuring at-a-glance operational metrics, giving security teams immediate visibility into their security posture. ### New Dashboard Widgets * **Incident Tracker Overview** — Track open, in-progress, and resolved incidents across all workspaces in a single view. * **Closed Incident Rule Trends** — Understand which detection rules are driving the most resolved incidents over time. * **Workspace Closed Incident Trends** — Compare incident resolution performance across workspaces. * **Gamebook Activity Widget** — Monitor active gamebook executions and their current status in real time. * **Gamebook History Widget** — Review past gamebook runs with outcomes and timing for post-incident analysis. ### Agent Deployment Improvements * Added support for selecting preferred AI models in the Agent Center. * Continued support for standard agent deployment alongside newer deployment options for existing customers. ### CrowdStrike Integration Enhancements * Incident descriptions from CrowdStrike are now automatically generated with richer context. * CrowdStrike incident comments are now fetched from audit logs, providing a complete conversation history within IRIS. ### SentinelOne Integration Enhancements * Added support for SentinelOne threat classifications (verdicts), giving analysts clearer disposition information. * Fixed incident description formatting for SentinelOne incidents. ### Bug Fixes * Fixed workspace filter not resetting to "All Workspaces" correctly. * Resolved inaccurate time filtering for the 24-hour filter option. * Fixed custom time filter unable to change from an existing custom selection. * Fixed duplicate rule entity mapping errors. **2025-11-18** Agent GA Readiness, Audit Trail, and Gamebook Improvements ### Audit Trail System * A comprehensive audit trail is now available for incident updates, entity investigations, and status changes. Security teams can review a full history of who did what and when — critical for compliance and post-incident review. * Audit logs for user sign-in and directory events are now queryable within the platform. ### Agent Improvements for General Availability * Agents now automatically trigger investigations on new incidents, reducing mean-time-to-respond without manual intervention. * Real-time gamebook status updates are now streamed to the UI — no more refreshing to see investigation progress. * Gamebook execution results are now visible directly on the Gamebook page. * Agent response flow improved with better error handling and detailed comments when issues occur. * Prevented duplicate agent investigations on the same incident. * Agent UI refined for general availability readiness. ### Workspace Group Management * Group member details, including member lists, are now visible in the group viewing slider within workspace settings. ### Data Source Activity * The data source activity graph has been enhanced for better readability and alignment. ### Bug Fixes * Fixed time filter refresh behavior on the incidents page. * Fixed agent response button remaining active when agent is not properly configured. * Fixed Defender incident comment creation for comments exceeding 1,000 characters. * Resolved incorrect log search results for Microsoft Defender data sources. * Fixed data source query results mapping to use column names instead of index positions, improving reliability. **2025-10-17** Ticketing Orchestrator, Agent Optimization, and Time Filters ### Ticketing Orchestrator * Introduced a new ticketing orchestration layer that improves reliability and consistency when creating and managing tickets across integrated ticketing systems (Jira, ServiceNow, Autotask). ### Agent Flow Optimization * The agent investigation and response flow has been optimized for performance, with improved classification mapping and enriched logging for better troubleshooting. ### Time Filter Improvements * Time filters throughout the portal now correctly display in local time instead of UTC, and the refresh behavior has been improved. ### Bug Fixes * Fixed ticket creation for Microsoft Defender incidents in Autotask. * Resolved entity context menu appearing for non-Microsoft sourced incidents. **2025-09-04** CMS 3.0, Notification System, and Agent Center ### CMS 3.0 Release * The Content Management System has been finalized with an updated user interface, improved rule details pages, and refined commenting capabilities for security content collaboration. ### Notification System * A new notification settings system allows workspace administrators to configure alert recipients, severity thresholds, and notification preferences per workspace — ensuring the right people are notified about the right events. * Notification recipients can be added and removed directly from workspace settings. ### Agent Center * A redesigned Agent Center creation experience with step validation, an Azure region picker for selecting agent resource locations, and an improved configuration details view. * Agent deployment reliability has been significantly increased with improved error handling and processing time. ### Feature Flag Cleanup * Gamebooks 2.0 and Workspace Management features are now generally available — feature flags have been removed, making these capabilities available to all users by default. ### Bug Fixes * Fixed deployment table routing when switching workspaces. * Fixed notification delivery issues identified during QA. * Resolved IAM management component flag check issues. > [!NOTE] > > Questions about the release notes? Contact us at [support@contraforce.com](mailto:support@contraforce.com). # Submit a Support Ticket Source: https://docs.contraforce.com/submit-ticket Open a ContraForce support ticket, choose a category and priority, include the details we need, and track your organization's requests in the Help Center. > [!NOTE] > > Our support team typically responds within **1 business day**. For urgent security incidents, email [support@contraforce.com](mailto:support@contraforce.com) directly with "URGENT" in the subject line. ## Open a Ticket > **[Submit a Support Request](https://help.contraforce.com/helpcenter/support/contact-us)** > > Open the support ticket form. The more detail you provide, the faster we can help. ## Ticket Categories and Priority Choose the category and priority that best match your issue when you fill out the form. Accurate values help us route your ticket to the right person. | Category | Use it for | | - | - | | **General Support** | Questions about ContraForce features or how to use the platform | | **Technical** | Technical issues or questions about specific features or requirements | | **Report a bug** | Errors or bugs you find in the ContraForce platform | | **Suggest a new feature** | Ideas for new features or design enhancements | | Priority | When to choose it | | - | - | | **Low** | Your experience is hindered, but no functionality is broken | | **Medium** | Functionality is broken, but the impact is minor, such as a UI issue or a non-blocking error | | **High** | Critical features are broken, but a workaround is available | | **Urgent** | Critical features are broken and no workaround is available | ## What to Include To help us resolve your issue quickly, please include: > **Workspace Name** > > The exact workspace name where you're experiencing the issue. > **Steps to Reproduce** > > What you were doing when the issue occurred, step by step. > **Screenshots or Errors** > > Any error messages, screenshots, or screen recordings that show the problem. > **Timestamps** > > When the issue started — include date, time, and timezone if possible. ## Other Ways to Reach Us > **[Email Support](mailto:support@contraforce.com)** > > [support@contraforce.com](mailto:support@contraforce.com) > **[Documentation](/overview)** > > Browse our docs for guides. > **[Shared Teams Channel](/guides/general-support/contraforce-success-teams-channel)** > > Set up a shared Microsoft Teams channel with the ContraForce Success Team. ## Track Your Tickets Tickets submitted by anyone in your organization appear in the ContraForce Help Center. Sign in to [view your organization's support requests](https://help.contraforce.com/helpcenter/support/user/requests), or submit a new ticket from there.