KnowBe4 — Integration Setup

Privacy note, up front: CMDash never stores a per-employee identifier from KnowBe4. Recipient and enrollment rows are read into memory for a single sync, reduced to counts and percentages, and discarded. KnowBe4 remains the only system of record for "who clicked which simulation"; CMDash holds only the resulting aggregates.

Prerequisites

• A KnowBe4 subscription that includes the Reporting API (Platinum/Diamond tiers, or an add-on on lower tiers)
• KnowBe4 account-admin access, to generate the Reporting API key
• At least one completed (Closed) phishing security test — an account with only in-flight tests produces no observations
• CMDash Essentials tier or above

Step 1: Generate a Reporting API Key

1. Log in to the KnowBe4 console.
2. Go to Account Settings → Account Integrations → API (labelled Reporting API / API Keys depending on console version).
3. Enable the Reporting API if it is not already enabled, and click to generate a key.
4. Copy the key immediately — it is shown only once.
5. Note your console's region (the hostname you log in to, e.g. training.knowbe4.com, eu.knowbe4.com) — you need the matching API host in Step 2.

Minimum privileges. KnowBe4's Reporting API key is a single account-wide read-only credential — there is no scope selector, and it grants no write access to campaigns, users, or training. The adapter reads only phishing security tests, their recipients, training campaigns, enrollments, and (optionally) groups and group members; it never creates or modifies anything in KnowBe4. If your KnowBe4 edition offers a choice between the Reporting API and the User Event API, only the Reporting key is needed.

Step 2: Connect in CMDash

1. Navigate to Integrations in your CMDash dashboard.
2. Find KnowBe4 and click Connect.
3. Enter:
   • API Key — the Reporting API key from Step 1 (stored as this connection's access token, sent as Authorization: Bearer <key>)
   • Configuration (JSON):
     jsonCopy

     {
       "baseUrl": "https://us.api.knowbe4.com",
       "businessUnitGroupMap": {
         "Engineering": "<cmdash-business-unit-id>",
         "Finance": "<cmdash-business-unit-id>"
       }
     }
     

4. Click Connect.

Base URL format. KnowBe4 serves the Reporting API from a region-specific host, and a key issued in one region returns 401/404 against another — this is the most common setup failure for this integration.

• The default when baseUrl is omitted is the US host, https://us.api.knowbe4.com.
• Use your account's region host instead if you are not on US: the pattern is https://<region>.api.knowbe4.com, matching the region of the console you log in to. Confirm the exact host in KnowBe4's API documentation for your account before saving.
• Scheme and host only — CMDash appends /v1/... itself. A trailing slash is stripped for you.
• The host must be publicly resolvable; CMDash validates it on save and rejects private/reserved addresses and .internal/.local/localhost hosts.

businessUnitGroupMap (optional) maps a KnowBe4 group name to a CMDash business-unit id, and is the only way this integration can produce a per-business-unit breakdown. Names are matched exactly as KnowBe4 reports them, so copy them from Users → Groups rather than retyping. Omit the key entirely and every observation is emitted tenant-wide.

What Syncs

CMDash bounds itself to the 5 most recently started tests with status Closed each sync. From those it emits, as HUMAN_RISK maturity observations at the OBSERVED tier:

• Phishing fail rate, one observation per test, taken directly from KnowBe4's own phish_prone_percentage — no per-recipient arithmetic involved.
• Repeat-clicker ratio — of the recipients who appear in at least two tests in that window, the fraction who clicked in at least two. This is the one metric with no vendor-side equivalent, so it is derived from recipient rows in memory. If nobody has been exposed twice yet, the observation is omitted rather than reported as 0%.
• Training completion, one observation per campaign, from KnowBe4's own completion_percentage.
• Average time to complete, derived from enrollments that have a completion date and a recorded time_spent. It is disclosure-only context and does not independently move the maturity score.
• Per-business-unit phishing fail rate, repeat-clicker ratio, and training completion, when businessUnitGroupMap resolves membership for at least one person.

Every observation carries the control reference NIST CSF 2 PR.AT-01. Per-BU aggregates are stored honestly at ingest and suppressed at display time by a minimum-group-size (k-anonymity) floor, so a small unit's numbers are collected but not shown.

Troubleshooting

The connection detail page shows the health check's message. The health check calls GET {baseUrl}/v1/account, so it fails on exactly the credential and region problems a sync would hit:

• HTTP 401: The key is wrong or was regenerated in KnowBe4 — or, very commonly, the key belongs to a different region than baseUrl points at.
• HTTP 403: The Reporting API is not enabled for the account, or the subscription tier does not include it.
• HTTP 404: baseUrl includes a path (it should be scheme + host only) or points at the console host rather than the API host.
• HTTP 429: KnowBe4's own rate limit. CMDash paces itself at 240 requests/minute for this provider, but a very large account plus other API consumers can still hit KnowBe4's daily/short-window caps.
• URL host not allowed: … / … resolves to a private/reserved address: baseUrl is not a public host.
• Request to <host> timed out: No response within 15 seconds.
• KnowBe4 circuit breaker open — skipping this cycle: 5 failures inside 60 seconds tripped the per-tenant breaker; it fails fast for a 30-second cool-off, then probes.
• Sync succeeds but no phishing observations appear: There are no tests with status Closed. Tests still running, or in any other state, are ignored by design.
• No repeat-clicker observation: Either the recipient fetch failed (logged as KnowBe4 recipients fetch failed for pst <id> …, which deliberately does not fail the sync) or no recipient has appeared in two of the last five closed tests yet.
• No per-business-unit breakdown: businessUnitGroupMap is absent, the KnowBe4 group names in it do not match exactly, or the group/member fetch failed (logged as KnowBe4 group membership fetch failed …). Org-wide observations are unaffected in all three cases.
• No time-to-complete figure: Enrollments returned no rows with both a completion date and a time_spent value, or the enrollment fetch failed (logged, non-fatal).
• A business unit's numbers are missing from the UI even though it syncs: The k-anonymity floor is suppressing a group that is too small to show without identifying individuals.

Rate Limits & Sync Behavior

Credential Rotation

KnowBe4 Reporting API keys do not expire on a fixed schedule. CMDash stores the key as a non-expiring credential and cannot show an expiry warning banner for it; rotate on your own cadence (quarterly is a reasonable default).

To rotate:

1. In KnowBe4: Account Settings → Account Integrations → API, generate a new key.
2. In CMDash: Settings → Integrations → KnowBe4 → Edit.
3. Enter the new API Key and Save.
4. Revoke the old key in KnowBe4 once the connection reports healthy.

Multiple Instances / Multi-Site

Each connection reads one KnowBe4 account in one region. Separate accounts (e.g. a subsidiary with its own KnowBe4 subscription) each need their own CMDash connection, with their own key, baseUrl, and businessUnitGroupMap.

To add another account:

1. Generate a Reporting API key in the additional KnowBe4 account, following Step 1.
2. In CMDash: Settings → Integrations → Add Integration → KnowBe4.
3. Enter the key and a baseUrl for that account's region.
4. Give the connection a descriptive name (e.g. KnowBe4 - Corp, KnowBe4 - EU Subsidiary).
5. Click Connect.

Observations from all connections roll up into the same human-risk maturity dimension.

Compliance Framework Coverage

The KnowBe4 integration provides evidence for the following controls. Coverage is automatically mapped when data is synced.