SafeBreach — Integration Setup

What this integration is for: SafeBreach simulation results are ingested at the VALIDATED tier — evidence a control was tested, not merely attested. It feeds the same credibility gate as AttackIQ; running both is supported and their evidence merges.

Prerequisites

• A SafeBreach deployment with its own management console hostname (SafeBreach-hosted or self-hosted — SafeBreach does not use a single shared SaaS host)
• A SafeBreach API token
• Completed simulations — an empty simulation feed produces no observations
• The management console reachable from CMDash's sync workers over the public internet (see the base-URL note in Step 2)
• CMDash Essentials tier or above

Step 1: Create an API Token

1. Log in to the SafeBreach management console.
2. Go to Settings → API Keys (exact location varies by console version) and create a key named CMDash Integration.
3. Copy the token immediately.
4. Prefer a token owned by a dedicated, read-only service user.

Minimum privileges. The adapter issues two GET requests and nothing else: the simulation results feed and the attack/playbook catalog. It never runs, schedules, pauses, or edits a simulation, and never touches simulators, deployments, or configuration. Read access to simulation results and the attack catalog is the whole requirement — no operator or admin role is needed.

Token transport. CMDash sends the token as Authorization: Bearer <token>. If your console expects a different header scheme for API keys, the connection will return 401 regardless of how the token is scoped — raise it with CMDash support rather than broadening the token's permissions.

Step 2: Connect in CMDash

1. Navigate to Integrations in your CMDash dashboard.
2. Find SafeBreach and click Connect.
3. Enter:
   • API Key — the SafeBreach token from Step 1 (stored as this connection's access token)
   • Configuration (JSON):
     jsonCopy

     { "baseUrl": "https://acme.safebreach.com" }
     

4. Click Connect.

Base URL format — this is the most common setup failure for SafeBreach, because every customer's console lives on a different hostname:

• Set baseUrl to your management console's hostname. The fallback when it is omitted is https://mgmt.safebreach.com, which is a placeholder default and will not be your console.
• Scheme and host only (plus a port if non-standard). CMDash appends /api/data/v2/... itself; a trailing slash is stripped for you, a trailing /api is not and yields 404.
• The host must be publicly resolvable. CMDash validates it when you save the connection and again on every request; private/reserved addresses and .internal / .local / localhost hosts are refused, so a self-hosted console on an internal network needs a public hostname or reverse proxy.

What Syncs

Each usable simulation becomes a BAS_CONTROL_VALIDATION maturity observation at the VALIDATED tier, timestamped with the simulation's own end time (not the sync time), and linked back to the SafeBreach insight URL when the console supplies one. Statuses map as (case-insensitively):

The attack catalog supplies each simulation's ATT&CK technique (the first tagged technique is used) and, where you have configured SafeBreach's compliance-framework mapping, its control tags. Only two framework labels are recognised, exactly as spelled:

• NIST CSF 2.0
• CIS Controls v8 (and the shorter CIS Controls)

Any other label is deliberately dropped rather than guessed at, and the simulation is still ingested — just without a control stamp. If your SafeBreach mappings use different framework names, renaming them to the two labels above is what turns these simulations into control evidence. A catalog fetch failure is non-fatal for the same reason: simulations still land, without control references.

Troubleshooting

The connection detail page shows the health check's message. The health check calls GET {baseUrl}/api/data/v2/simulations?limit=1, so it exercises the same credential and reachability path a sync does:

• HTTP 401: The token was revoked or regenerated, or the console does not accept a Bearer token.
• HTTP 403: The token's user cannot read simulation results.
• HTTP 404: baseUrl still points at the mgmt.safebreach.com default or another wrong host, or carries an extra path segment.
• URL host not allowed: … / … resolves to a private/reserved address: The console host is internal-only; CMDash's workers cannot reach it by design.
• Request to <host> timed out: No response within 15 seconds.
• SafeBreach circuit open — provider recently failing repeatedly: 5 failures inside 60 seconds tripped the per-tenant breaker; it fails fast for a 30-second cool-off and then probes.
• Sync log shows SafeBreach simulations API failed: <status>: The simulation feed returned non-2xx mid-run. This is the one required dataset, so the whole sync attempt fails and is retried.
• Observations appear with no control reference: Either the attack-catalog fetch failed (logged as SafeBreach attack-catalog fetch failed … — non-fatal by design) or the attack's framework labels are not one of the two recognised strings above.
• Sync reports success but zero observations were created: Every simulation was filtered out. The usual causes are (a) every status was Not-Relevant/Reported or another unrecognised value, or (b) the feed is returning a shape the adapter does not recognise — it expects a JSON array of objects carrying simulationId, attackId, status, and endTime. If your console version returns a paginated envelope or differently-named fields, report it to CMDash support; no permission change will fix it.
• Old simulations stop counting: BAS_CONTROL_VALIDATION observations decay on a 90-day half-life. Re-running the playbook is what refreshes the evidence.

Rate Limits & Sync Behavior

Credential Rotation

SafeBreach API tokens do not carry an expiry CMDash can read, so no expiry warning banner is shown for this integration. Rotate on your own cadence — quarterly, or whenever the owning service user changes.

To rotate:

1. In SafeBreach, create a new API key for the same service user.
2. In CMDash: Settings → Integrations → SafeBreach → Edit.
3. Enter the new API Key and Save.
4. Revoke the old key in SafeBreach once the connection reports healthy.

Multiple Instances / Multi-Site

Each connection reads one SafeBreach console through one token. Separate deployments (e.g. per region, or a lab console alongside production) each need their own CMDash connection with their own baseUrl.

To add another:

1. Create a token in the additional SafeBreach console, following Step 1.
2. In CMDash: Settings → Integrations → Add Integration → SafeBreach.
3. Enter the token and that console's baseUrl.
4. Give the connection a descriptive name (e.g. SafeBreach - Prod, SafeBreach - EU).
5. Click Connect.

Validation evidence from every connection feeds the same control-validation rollup, alongside AttackIQ if you run both.

Compliance Framework Coverage

Like AttackIQ, SafeBreach's control coverage is driven by your own attack mappings rather than a fixed table — the adapter stamps whatever your console reports, provided the framework label is one it recognises.

Simulations whose attacks carry no recognised mapping still count toward control-validation maturity and ATT&CK technique coverage; they simply do not stamp a specific control.