CISO Assistant Integration Guide

Overview

The CISO Assistant integration lets your NINA workflows drive CISO Assistant, the open-source Governance, Risk & Compliance (GRC) platform by intuitem. It turns everyday GRC bookkeeping into automation: create and query assets, incidents, compliance assessments, applied controls, evidence and the organizational hierarchy (folders/perimeters), then read back analytics such as an assessment's global score.

CISO Assistant organizes work into folders (domains), perimeters (audit scopes), frameworks (imported control catalogs such as ISO 27001, NIST CSF, GDPR), compliance assessments (a framework evaluated against a perimeter — which automatically generates one requirement assessment per framework requirement), applied controls, evidences, assets and incidents. The integration exposes all of these so you can seed data, keep it in sync from other systems, or extract it for reporting.

Status

The integration is spec-driven and comprehensive: it exposes every operation the CISO Assistant REST API defines for the eleven supported resources — full CRUD plus the custom actions, exports and analytics endpoints — generated directly from the instance's live OpenAPI schema. Nothing is synthesized: an operation appears only if the API documents it.

Supported resources: assets, incidents, compliance-assessments, requirement-assessments, folders, perimeters, frameworks, requirement-nodes, applied-controls, evidences, filtering-labels.

Out of scope (for now):

• The remaining CISO Assistant domains (risk assessments, threats, reference controls, vulnerabilities, users/roles, etc.).
• OAuth flows — authentication is by Personal Access Token only.
• Loading a framework from a library. Frameworks are expected to be loaded into the instance beforehand (Catalog → Frameworks → Load); the integration then references them by id.

Credential Configuration

Before using the integration you must configure a credential.

Authentication Method

The CISO Assistant integration uses API Token (Knox) authentication. The token is sent on every request as Authorization: Token <token>.

Field	Description	Example
Base URL	Your CISO Assistant instance URL (no trailing path)	https://grc.acme.com
API Token	Personal Access Token from your CISO Assistant profile	9c3f… (Knox token)

How to get your API Token:

1. Log in to your CISO Assistant instance.
2. Open your profile (upper-right avatar) → My profile → Settings.
3. Under Personal Access Tokens, create a new token, give it a name and an expiry.
4. Copy the token value shown once — it is not retrievable later.

⚠️ IP allow-listing (most common cause of failures). CISO Assistant can restrict API access by source IP (Settings → Infrastructure → Allowed IPs). If it is enabled, requests from a non-allowed IP are rejected with HTTP 403 before they reach the app — a correct token will still fail. You must allow-list the outbound (egress) IP of the environment running the integration, which is generally not your own workstation's IP. Ask your Zynap administrator for the platform's egress IP for your environment and add it there.

Creating a CISO Assistant Credential

1. Navigate to the Credentials section in NINA.
2. Click Add New Credential.
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "CISO Assistant Production").
   • Integration Service: Select "CISO Assistant".
   • Auth Type: "API Token (Knox)" (selected automatically).
   • Base URL: Your instance URL, e.g. https://grc.acme.com.
   • API Token: The Personal Access Token you generated.
4. Click Test Connection to verify the credentials.
5. Click Save.

Supported Resources and Operations

Every resource supports standard CRUD where the API allows it — list, get, create, update, partial_update, delete — plus the custom actions below. This is a representative summary; the full operation list is always available in the node's Operation dropdown.

Folders (domains)

The organizational hierarchy. A folder is the "domain" that owns perimeters, controls and evidence.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
org_tree_retrieve	Full organization tree
get_accessible_objects_retrieve, my_assignments_retrieve	Access-scoped views
import_create, export_retrieve	Domain import/export

Perimeters

Audit scopes within a folder.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
names_retrieve, ids_retrieve, lc_status_retrieve	Lookups and lifecycle status

Frameworks

Imported control catalogs (ISO 27001, NIST CSF, GDPR, …).

Operation	Description
list, get	Browse loaded frameworks
names_retrieve, tree_retrieve, mappings_retrieve	Names, control tree, cross-mappings
excel_template_retrieve	Excel template export
report_retrieve	Cross-assessment report — requirement-assessment rows across every compliance assessment using this framework

Compliance Assessments

A framework evaluated against a perimeter. Creating one auto-generates a requirement assessment per framework requirement.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
global_score_retrieve	The assessment's global score
requirements_list_retrieve, tree_retrieve	Requirement breakdown
donut_data_retrieve, per_status_retrieve, progress_ts_retrieve	Analytics
word_report_retrieve, action_plan_pdf_retrieve, action_plan_xlsx_retrieve, export_retrieve	Reports & exports

Requirement Assessments

The per-requirement results generated by a compliance assessment.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
result_retrieve, status_retrieve, per_status_retrieve	Result/status views
todo_retrieve, to_review_retrieve	Work queues

Applied Controls

Controls implemented in the organization.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
todo_retrieve, to_review_retrieve, per_status_retrieve	Work queues & status
get_gantt_data_retrieve, priority_chart_data_retrieve, sunburst_data_retrieve	Analytics
export_csv_retrieve, export_xlsx_retrieve	Exports

Evidences

Documents and artifacts supporting controls and assessments.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
upload_create, batch_upload_create, attachment_retrieve	Attachment handling

Assets

Primary and supporting assets under management.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
graph_retrieve, security_objectives_retrieve, disaster_recovery_objectives_retrieve	Asset analytics
export_csv_retrieve, export_xlsx_retrieve	Exports

Incidents

Security incident records.

Operation	Description
list, get, create, update, partial_update, delete	Standard CRUD
summary_stats_retrieve, monthly_metrics_retrieve, severity_breakdown_retrieve	Metrics
pdf_retrieve, export_csv_retrieve, export_xlsx_retrieve	Reports & exports

Requirement Nodes & Filtering Labels

requirement-nodes expose the individual nodes of a framework's requirement tree; filtering-labels are the tag labels used across the platform. Both support standard CRUD.

Parameter Merging

The CISO Assistant integration uses NINA's standard parameter merging.

Parameter Sources (in order of precedence)

1. Node Parameters — values set directly on the integration node (e.g. query filters like limit, search).
2. Extracted Parameters — values automatically pulled from the input data.
3. Input Data — the merged output of upstream nodes.

For write operations (create, update, partial_update) the request body is taken from the input data. The standard pattern is therefore a small prep node before each write that emits exactly the JSON body the operation expects, including any foreign-key ids collected from earlier nodes (see the examples below).

Path vs. body parameters

• get, update, delete, and single-object custom actions (e.g. global_score_retrieve) need an id — provide it in the input data as id.
• list operations take query parameters (limit, offset, search, resource-specific filters such as compliance_assessment).
• create operations take the object body.

Examples

List frameworks

{
  "resource": "frameworks",
  "operation": "list",
  "parameters": {}
}

Returns the frameworks loaded in the instance ({count, results:[{id, name, …}]}).

Create a folder (domain)

Feed the body from an upstream prep node:

{
  "resource": "folders",
  "operation": "create",
  "parameters": {}
}

Upstream prep-node output (becomes the request body):

{ "name": "Acme EU Compliance" }

Create a compliance assessment (with foreign keys)

A compliance assessment needs a framework id and a perimeter id. Collect them from the framework list and the perimeter you created, then emit the body:

{ "name": "ISO 27001 Q3 Audit", "framework": "<framework-id>", "perimeter": "<perimeter-id>" }

{
  "resource": "compliance-assessments",
  "operation": "create",
  "parameters": {}
}

On creation, CISO Assistant automatically generates one requirement assessment per framework requirement.

Read back the requirement assessments and global score

{
  "resource": "requirement-assessments",
  "operation": "list",
  "parameters": {}
}

with input { "compliance_assessment": "<assessment-id>", "limit": 5 }, and

{
  "resource": "compliance-assessments",
  "operation": "global_score_retrieve",
  "parameters": {}
}

with input { "id": "<assessment-id>" }.

Integration in Workflow Context

The integration shines when chained with prep nodes (Script or Scripting Agent) that build request bodies and thread foreign-key ids between steps.

Common Workflow Patterns

1. Self-seeding compliance demo (end-to-end):

   • Input → Seed (prep) → List_Frameworks → Extract framework (prep) → Create_Domain → Create_Perimeter → Create_Compliance_Assessment → List_Requirement_Assessments + Assessment_Global_Score → Build report (prep) → Output.
   • Each Create_* is preceded by a prep node that merges the seed names with the parent object's id into the exact body the operation expects.

2. Continuous GRC sync:

   • Schedule → source system (CMDB/SIEM) integration → prep node (map to CISO Assistant schema) → assets/incidents create/update.

3. Evidence collection:

   • Trigger → fetch artifact → evidences create → evidences upload_create (attach the file).

4. Compliance reporting:

   • compliance-assessments global_score_retrieve + requirements_list_retrieve → Report node → email/web output.

Foreign keys and the prep-node pattern

Because write bodies come from the input data, the reliable pattern is: one prep node per write, fanning in the seed/config node and the parent object's output, emitting { …fields, <fk>: <parent id> }. Keep the field names exactly as the API expects (folder, perimeter, framework, compliance_assessment, …).

Response Structure

list operations return the standard paginated envelope:

{
  "count": 23,
  "next": "/api/requirement-assessments/?compliance_assessment=…&limit=5&offset=5",
  "previous": null,
  "results": [ { "id": "…", "…": "…" } ]
}

get/create return the object directly. Export and report operations (export_csv_retrieve, word_report_retrieve, action_plan_pdf_retrieve, …) return non-JSON files; the node wraps them in a base64 file envelope so downstream nodes can persist them:

{ "fileName": "assessment.csv", "mimeType": "text/csv", "size": 2048, "encoding": "base64", "data": "…" }

Troubleshooting

Issue	Resolution
HTTP 403 (Forbidden)	The instance's IP allow-list (Settings → Infrastructure) is blocking the caller. Add the platform's egress IP for your environment (not your workstation IP) to the allowed list. This is the single most common failure.
HTTP 401 "Invalid token"	The Personal Access Token is wrong, mistyped or expired. Regenerate it and update the credential.
HTTP 404 on get/update/delete	Missing or wrong id in the input data, or the object lives in a folder your token can't see.
HTTP 400 on create	The body is missing a required field or a foreign key. Verify the prep node emits every required field with the exact API field names (folder, perimeter, framework, …).
Empty results	Check list filters. Some resources are folder-scoped; ensure the token's role can access the target folder.
Framework not found when creating an assessment	The framework must be loaded in the instance first (Catalog → Frameworks → Load), then referenced by its id.
Connection errors / timeouts	Verify the Base URL includes the scheme (https://) and is reachable from the platform; check TLS on self-hosted instances.

Best Practices

1. Allow-list the right IP. Confirm the platform's egress IP with your administrator and add it to CISO Assistant's allowed IPs before your first run.
2. Use a scoped token. Create a dedicated Personal Access Token with an expiry for automation, and rotate it periodically.
3. One prep node per write. Build each create/update body in an upstream Script or Scripting Agent node; keep API field names exact and pass foreign keys explicitly.
4. Reference, don't reinvent, frameworks. Load frameworks from the library in the UI; use the integration to reference them by id.
5. Read back to verify. After a create, follow up with get/list/global_score_retrieve to confirm the side effects (e.g. auto-generated requirement assessments).
6. Handle exports as files. Export/report operations return a base64 file envelope — write it out with an Output node rather than treating it as JSON.
7. Page through large lists. Use limit/offset; don't assume a single page holds everything (count tells you the total).
8. Least privilege on folders. Scope the automation user's role to the folders it needs.

Updated: 2026-07-24