CISO Assistant — Integration Setup

Status: beta. This connector ships and authenticates, and its mapping is exercised against a response shape read from CISO Assistant's own open source. It has not been verified against a response from a live instance. Read "API version assumptions" below before you import anything, and use the migration preview first — it exists for exactly this reason.

CISO Assistant is open source and self-hosted, so this is a migration connector rather than a monitoring one: it reads what your existing GRC programme already concluded and turns it into CMDash risks, control assessments, policies, evidence records, assets and third parties. It is the same migration the CSV importer performs, without exporting five files by hand.

Prerequisites

A CISO Assistant instance reachable from CMDash over HTTPS
A CISO Assistant user with read access to the domains (folders) you want to import — the import only ever reads; nothing is written back
That user's API token
CMDash Essentials tier or above

If your instance is on a private network with no inbound path from CMDash, use the CSV import instead (Migrate → Import from another GRC tool). It maps identically.

Step 1: Create an API token in CISO Assistant

Sign in to CISO Assistant as the user whose access the import should use.
Open My profile → Settings → API tokens (on older releases, the token is issued from the user administration screen).
Create a token named CMDash migration and copy it immediately.

Note: a CISO Assistant token carries the permissions of the user who created it, and folder permissions are what decide what the import can see. Create the token from a user with read-only access to the domains you intend to migrate. A token from an administrator will import everything on the instance, which is rarely what you want on a first run.

Step 2: Connect in CMDash

Navigate to Integrations in your CMDash dashboard.
Find CISO Assistant and click Connect.
Enter:
- CISO Assistant URL — your instance URL, for example https://ciso.example.com. Point it at the application host, not at the reverse proxy's login page.
- API token (stored as this connection's credential, sent as Authorization: Token <token>)
- Folder or domain — optional. Leave blank to import everything the token can see, or name one domain to limit the import to it.
- Import assets / Import third parties — leave on to bring the asset register and the third-party list across.
Click Save & Test Connection. The test performs a single authenticated read; it imports nothing.

Step 3: Preview before you import

This is the step that makes the rest safe. Open the connection and choose Preview migration. CMDash runs a complete read of your instance, resolves every row against its own control catalogue and against what your workspace already holds, and reports — without writing anything —

how many rows of each kind it would create,
how many already exist in CMDash and would be left untouched,
how many it could not map, and the reasons why.

If those numbers look wrong, nothing has happened yet. Tell us what you see; do not import.

What syncs

Data type	CISO Assistant API	Becomes
Risk scenarios	`GET /api/risk-scenarios/`	Risks in the CMDash register, with likelihood and impact on CMDash's 1–5 scale
Applied controls	`GET /api/applied-controls/`	Reported only — see "What does not import"
Requirement assessments	`GET /api/requirement-assessments/`	Control assessments on the matching CMDash control, with an imported-from note
Compliance assessments	`GET /api/compliance-assessments/`	Not imported directly — read to learn which framework each requirement belongs to
Policies	`GET /api/policies/`	Policies created from the matching CMDash starter template
Evidences	`GET /api/evidences/`	Evidence records, PENDING, filed against the control their requirement resolves to
Assets	`GET /api/assets/`	Assets in the CMDash inventory (optional)
Entities (third parties)	`GET /api/entities/`	Vendors in the CMDash register (optional)

Collections are read page by page (limit=200, then offset), up to 10,000 rows per collection. The connection test reads GET /api/folders/?limit=1.

How values are mapped

CISO Assistant	CMDash
Applied control `active`	Implemented
Applied control `in_progress`, `on_hold`	In progress
Applied control `to_do`	No claim (CMDash's own default is Not started)
Applied control `deprecated`	Not applicable
Requirement result `compliant`	Implemented
Requirement result `partially_compliant`	In progress
Requirement result `non_compliant`	No claim — the note lands, the status does not
Requirement result `not_applicable`	Not applicable
Requirement result `not_assessed`	No claim
Risk treatment `mitigate`	Being mitigated
Risk treatment `accept`	Accepted
Risk treatment `avoid`, `transfer`, `open`	Open
Risk probability / impact `Very Low … Very High`	1 … 5
Risk probability / impact `--` (not rated)	Not imported — reported instead

The asymmetry is deliberate. A positive claim ("this control is implemented") changes a readiness percentage and an auditor-facing report, so it is only made when the source was unambiguous. Anything else imports the note and leaves the status alone, which costs you a click and cannot manufacture evidence you do not have.

What does not import, and why

Controls with no framework requirement behind them. CMDash matches on the framework-native code — CC6.1, A.5.15, 3.1.1 — never on CISO Assistant's own control key. A key from one tool means nothing in another tool's catalogue, and one that happened to collide with a real control id would be worse than no match at all. Your bespoke controls are reported so you can see them, and are best re-created deliberately.
Frameworks CMDash does not ship, and a bare "NIST CSF" with no version (CMDash ships both 1.1 and 2.0, and their control ids differ).
Frameworks your workspace has not enabled yet. Enable the framework first, then re-run — the preview names which ones are missing.
Policies with no CMDash starter-template counterpart, and policies whose title merely resembles one. Importing the wrong policy text into a library people are then asked to attest to is worse than importing none.
Evidence attachments. The evidence record is created PENDING with a link back to your CISO Assistant instance; the file itself stays where it is. A migration that half-copied your evidence files would leave you unsure which copy an auditor should be shown.
Risks the source never scored.
Third parties beyond your plan's vendor-register capacity. The preview tells you the number before anything is written.

Running it more than once

Safe, by design. A second import updates nothing and duplicates nothing: every kind is matched against what CMDash already holds (a control's existing assessment, a policy or risk title, an evidence record on the same control, an asset or vendor name) and an existing row is reported as already-present and left untouched. Your own work in CMDash is never overwritten by an import.

The same is true across both roads: if you pasted the CSV export during a trial and connect the API afterwards, the API import recognises the rows the CSV import created and leaves them alone.

API version assumptions

CISO Assistant is self-hosted, open source and moves quickly, and it publishes no versioned API contract to pin to. The endpoint paths and field names above were read from the shipped source at commit a3e3db07311f5cb2b5a87c96107f7d9d2c9778b7 (2026-09-11). Treat the mapping as best-effort against your release, not as a guarantee.

Two things are known to vary between releases and are handled explicitly:

a risk-matrix level arrives either as a number or as an object carrying the matrix's label; both are read, and an index outside the configured matrix is reported as unrated rather than rounded into range;
a related object (the requirement behind an assessment, the folder on a row) arrives either nested or as a bare identifier; both are read.

Everything else degrades rather than fails: a field that moved makes its row unreadable, and an unreadable row is counted and reported, never silently dropped. That is what the "fetched N, imported 0" line in the sync log means — the vendor returned rows and none of them matched what this connector expects, which is a version-skew signal, not an empty estate.

The migration preview is the safety net for all of this. Run it first, every time, and especially after upgrading your CISO Assistant instance.

Troubleshooting

"did not return JSON": the URL points at the web UI or a login page rather than the API. Use the application host, without a path.
401 / 403: the token was revoked, or the user it belongs to lost access to the folders being read. CISO Assistant uses the Token scheme, not Bearer; a token pasted into the wrong field authenticates as nobody.
Connection test passes, sync imports nothing: check the folder setting — a folder name that matches nothing on the instance scopes the import to nothing. Blank imports everything the token can see.
Everything reports "no control in the CMDash catalog matches": the framework behind those requirements is one CMDash does not ship, or is shipped but not enabled in your workspace. The preview names it.
Risks import unrated: your instance uses a custom risk matrix whose label words this connector does not recognise. Tell us the labels; nothing is guessed at in the meantime.

Rate limits & sync behavior

Setting	Value
Sync frequency	Every 4 hours by default (`syncInterval` is configurable per connection)
Pagination cap	200 rows per request, 50 pages (10,000 rows) per collection; a truncated read is logged as PARTIAL, never reported as complete
Rate limit handling	Every outbound request is paced through CMDash's shared per-tenant token bucket for this provider, and a vendor `429` (with its `Retry-After`) holds that tenant's budget until the vendor says it is ready
Repeated failures	A connector that keeps failing is tripped open for a cool-off rather than hammered
Failed sync retry	Job queue retries 3 times with exponential backoff (starting at 30s) — see docs/developers/dead-letter.md

Credential rotation

CISO Assistant API tokens do not expire on a fixed schedule. CMDash recommends rotating quarterly, and revoking the token as soon as the migration is done — once your programme lives in CMDash, there is usually no reason to keep a standing read connection to the old system.

To rotate:

In CISO Assistant, issue a new token for the same user.
In CMDash: Settings → Integrations → CISO Assistant → Edit.
Enter the new API token and Save.
Revoke the old token once the connection test passes.

Multiple instances

If you run more than one CISO Assistant instance, each needs its own CMDash connection. To import several domains from one instance, either leave the folder setting blank (everything the token can see) or run the import once per domain.