1 of 85

CISO Assistant

Welcome to CISO Assistant

This is CISO Assistant documentation. You'll find advice on how to get started, and details on our vision of risk and compliance assessment.

A different take on Cyber Security Posture Management

explicitly decoupling compliance from cyber-security practices implementation
providing simplified tools for decision-making
providing capabilities for a program, product, or an organization assessment against standard frameworks
you can bring your own framework as well using a simplified DSL
aim to be a one-stop-shop for cyber security management and cover the layers of GRC (Governance, Risk and Compliance)

An open-source GRC tool

CISO Assistant is open source and the code is available on GitHub. Just follow the instructions to deploy it yourself or go to our website to request a cloud trial instance. You can read the about our switch.

About the SaaS and PRO plan

Quick links

Replays

Get Started

In a hurry? checkout the for overviews in English and French 🤗

We've put together some helpful guides for you to get setup with our product quickly and easily.

Model

We've detailed our model to help you understand how everything is organized

Guide

Installation

Docker Compose or Helm for Kubernetes

New! Config Builder

Customize the local deployment according to your needs:

Make sure to have Docker 27 or up. If you get an error about docker compose command not recognized, it's because your Docker version is old and not supported.

Docker compose

Make sure to have Docker and Docker Compose installed on your system.

clone the repo:

git clone https://github.com/intuitem/ciso-assistant-community.git

run the preparation script and follow the instructions:

./docker-compose.sh

you can also find other variants for different setups as a starting point for your specific needs.

Helm chart

Make sure to have Helm binary installed and switch to your cluster context.

add the helm repository

helm repo add intuitem https://intuitem.github.io/ca-helm-chart/

get the default values

helm show values intuitem/ciso-assistant > my-values.yaml

check and adjust them to your needs, specifically the frontendOrigin parameter
create a namesapce for your deployment

kubectl create ns ciso-assistant

install

helm install my-octopus intuitem/ciso-assistant -f my-values.yaml -n ciso-assistant

This setup is based on the fact that Caddy will handle the TLS on your behalf. In case you're experiencing ssl related issues, you might want to patch your ingress-nginx-controller to activate the enable-ssl-passthrough flag.

Understanding decoupling

Decoupling compliance from security operations and controls is a cornerstone of CISO Assistant philosophy. Let's see it through this short animation:

General tips

CISO Assistant is intended to be a multi-paradigm tool to suit everyone's background and approch to cyber security program organisation.

With that being said here are some standard recommendations to get the most of it, if you are just starting:

Map your organisation to the domains/perimeters (or create basic ones)
Add your users and assign them to the groups (SSO and MFA available even in Community)
(recommended) Identify what are the assets to protect
(recommended) Enumerate your existing capabilities/controls
Define your baseline and focus on the basics - pick your controls and/or create new ones
Get your actions implemented and reflect that on your audit progress
Conduct a contextual risk assessment
Share the insights with your organisation, review the priorities, and keep it alive
Expand your coverage: periodic tasks, incidents, TPRM, findings managements, etc.
Always keep focus on the actions and reflect their data on the other concepts

Journeys

"I'm just curious and want to see what the tool is about."

Quick start and pick your framework and/or matrix

"I need to comply with a specific regulation or standard"

Identify the scopes (domains/perimeters)

Creating your first perimeter

Small tutorial to learn how to create your first perimeter and be prepared for risk and compliance assessment

Perimeters were previously named "Projects", but this was misleading

Once logged in, the first step is to create a domain. Let's call it R&D.
Then we create the perimeter inside of it or from the perimeter list view.

That's it! you just created your first perimeter. The next step will be to create a compliance assessment.

Creating your first Audit

Small tutorial to learn how to create your first compliance assessment

After creating the perimeter, we'll have to import a framework, for example ISO/IEC 27001:2022.
Once it is imported, we can now create the compliance assessment (ISO/IEC 27001:2022 is auto-selected as it is the only imported framework).
You can edit it if needed, or go directly into the assessment. Each requirement has a To do status by default.
Finally, we can select a requirement and start its assessment by adding applied controls or evidences and update its status to complete the progress bars.

Now that you're familiar with compliance assessment, let's go a step further with risk assessment.

Overview

Manage your assessments over time

Analytics

The main page to manage your perimeters through time. You can focus on risk or compliance with their respective tabs or have a global view from the governance one.

You can find on the bottom of the governance tab an applied controls ranking score and a watch list to warn you about incoming deadlines on applied controls or risk acceptances.

Applied controls ranking score table is here to help you prioritize

Composer

This is a specific tab where you can cross-referencing analytics from different risk assessments.

It will also tell you if one or many selected risk assessments should be reviewed based on inconsistencies found by x-rays.

X-rays is a CISO Assistant tool which will be detailed in

Calendar

Calendar page has been moved to the "Operations" section

An integrated calendar to track the ETA of upcoming/expired applied controls or risk acceptances.

Extra tools

Some useful tools for following up assessments

X-rays

X-rays page has been moved to the "Operations" section

X-rays is a very useful page to detect inconsistencies across your assessments for each perimeter. There are 3 type of reports:

info: advice or reminder for status and relevant empty fields
warning: potential errors to be determined by the user
error: errors that must be corrected

Scoring Assistant

Scoring Assistant page has been moved to the "Risk" section

Trouble assessing your risk ? 🤔

Based on , scoring assistant is here to help you determine the risk level for your scenario. Choose between technical or business impact and select the appropriate answers to the questions.

Glossary

This is the end of the basic tutorial to start with CISO Assistant 🎬 You can go further by exploring its , or checking the directly on GitHub.

External resources

Community supported content

Live sessions

Understand mapping

Main concepts of the mapping feature

One common challenge when dealing with audits is about being able to reuse your assessment on one framework to move to a different one. This commonly refered to as mapping or crosswalk between standards.

This capability is supported on CISO Assistant and allows the user to create a projection of the content of an audit, given that a mapping is available. Mapping are library objects that can be customized, imported and submitted to the community. To see the available ones, head to the libraries store and filter to mapping:

Mappings are essentially a representation of the links between assessable nodes of a framework, and for which we are using the convention documented on NIST's OLIR project.

Mapping is a directed graph linked a SRC framework to a TGT framework on which the nodes can have one of the following relationships:

To create yours, you can follow one of the examples on /tools or bootstrap a starter using the prepare_mappingscript.

To apply a mapping, you needt to first load a mapping from the library. Then, head to your audit and click on apply mappingand select the targeted framework and see the projected being created ✨.

Note: the apply mapping feature can also be reused to clone the audit and create a new revision, if the same framework and same scope are selected.

Glossary

Concept

Explanation

Domain

A division within your organisation on which you want to enforce an isolation of objects and the RBAC. Demo and Starter are reserved for internal features.

Perimeter

An organisation can split a domain and link its audits, risk assessments, and other relevant objects to it. Doesn't enforce RBAC.

Data import wizard

Guidelines on data import format

Applicable for: Data import wizard UI (Pro) and CLI (Community or Pro)

Importing existing data from excel sheets is supported on the Pro plan through the UI and CLI, and on Community edition through the dedicated CLI, not a django command. The cli is available on the cli folder with the associated instructions. Keep in mind that the CLI needs to reach the API as it wraps its actions around it. The mention to the API is regarding the fact that users on both plans can still interact with the API directly in case they have some data prep phase on their end for batch import or equivalent.

Connection Error

If you encounter this error, it could be due to the Excel file being protected by Information Rights Management (IRM)

Overview

The Data Import Wizard and the CLI both support batch creation and updates of fields. They provide the same capabilities; the only difference lies in how the import is initiated:

through the user interface for the Data Import Wizard
through the command line for the CLI

When an object already exists during an import, one of the following conflict-resolution strategies can be applied:

Stop the import (default): the import is aborted as soon as a conflict is detected
Skip the row: the existing field is left unchanged and the import continues
Update the row: the existing field is updated with the imported data

The Update strategy enables batch updates of existing fields and is particularly useful for changes that could technically be performed through the graphical interface, but become tedious or error-prone when repeated across many objects. In such cases, downloading the existing objects, applying the required transformations in an Excel file, and re-importing the updated data can be significantly faster and more reliable than performing the same actions manually in the UI. This approach reduces repetitive interactions, minimizes the risk of manual mistakes, and provides a clear, auditable workflow for large-scale updates.

In this workflow, it is strongly recommended to retain the field IDs (UUIDs) in the import schema. Doing so ensures reliable object matching during re-import, even if other attributes (such as names or labels) have changed, making the update process fail-safe.

If the imported object supports the domain attribute, the wizard will attempt to assign it to the specified domain, provided you have the required permissions. If no domain is specified, the wizard will automatically fall back to the default domain configured in the wizard form.

Fields with (*) are mandatory and don't have any supported fallback.

Unless marked as mandatory, ref_id fields can be left blank but the column must still exist.

📦 Assets

Template

Supported fields

ref_id
name*
description
domain

Special considerations

type will default to supporting if the column does not exist

⚙️ Applied controls

Template

Supported fields

ref_id
name*
description
domain

Special considerations

status will default to to_do
csf_function will default to govern
The owner field resolves against existing users (by email) and teams (by name). Ensure any referenced users and teams are created before importing. Unresolved entries are skipped with a warning and will not block the import.

📦 Perimeters

Template

Supported fields

ref_id
name*
description
domain

Special considerations

If the default_assignee column is present and empty, the import would end up cleaning existing assignee.

📃 Audits

Template

To avoid any mixup on the expected fields and the requirements reference, you can get a template for the expected framework by going into Catalog/Frameworks

The framework needs to be loaded and when clicking on it, you'll see a button to get the excel file.

Supported fields

urn*
assessable
ref_id*
name

Special considerations

The wizard will attempt to match based on the ref_id and fallback to the urn otherwise. If none could be used, the row will be skipped.
name and description columns are not used but serve as an anchor point for reference.
Assessable will fallback to false

🐞 Findings followup (eg. pentest)

Template

Supported fields

ref_id
name*
description

👥 Users

Template

Supported fields

email*
first_name
last_name

☣️ Risk assessment

The risk assessment is an advanced object that needs special considerations. Make sure to pick the matrix that will be used to map your labels to the values on CISO Assistant. If you have a specific matrix, you should start by including it as a custom library.

inherent_level, current_level and residual_level are kept on the excel sample just for visual aid. The application computes them based on impact and probability to ensure consistency with the matrix definition.

Controls are created on picked based on the perimeter's domain. Line breaks are used as seperator.

Template:

Supported fields:

ref_id: String
name*: String
description: String

1: The string must represent a value present in the chosen risk matrix

🏢 Business Impact Analysis

The BIA export/import uses a multi-sheet Excel file:

Summary sheet - one row per BIA
<BIA name> sheet - one row per asset assessment for that BIA
<BIA name> - thresholds sheet - one row per escalation threshold for that BIA

Template

Summary sheet

Supported fields

name*
description
perimeter - name of the perimeter

Special considerations

status defaults to planned if not provided
perimeter and risk_matrix are resolved by UUID, ref_id, or name (in that order)

Asset assessment sheets (<BIA name>)

One sheet per BIA, named after the BIA. Each row is an asset assessment.

Supported fields

bia_name* - name of the parent BIA (injected automatically on re-import)
asset* - name of the asset
asset_ref_id - ref_id of the asset (alternative lookup)

Special considerations

asset is resolved by UUID, ref_id, or name (in that order)
Boolean fields accept true/false, yes/no, 1/0

Threshold sheets (<BIA name> - thresholds)

One sheet per BIA, named <BIA name> - thresholds. Each row is an escalation threshold.

Supported fields

bia_name* - name of the parent BIA
asset* - name of the asset (used to resolve the asset assessment)
asset_ref_id - ref_id of the asset (alternative lookup)

Special considerations

The asset assessment is resolved by matching (bia_name, asset) — both must already exist before thresholds are imported
point_in_time combined with the asset assessment forms the unique key for update/deduplication
quali_impact defaults to -1

⚙️ Elementary actions

Elementary actions are useful to model a killchain during the 4th workshop of an EBIOS RM study.

Supported fields:

ref_id
name*
description
attack_stage*

Reference controls

Reference controls are templates of the controls to apply.

Supported fields:

ref_id
name
description
category

Reference controls can be bundled also as a library.

Threats

ref_id
name
description
domain

Third parties ecosystems

Adding entities, solutions and contracts go through the same file to be able to keep consistent relationships. Each concept needs to be on a separate tab of the excel sheet.

The file has to be divided into 3 sheets namely "Entities", "Solutions" and "Contracts"

Supported fields

*: Required fields

Entities

ref_id
name *
description

Solutions

ref_id
name *
description

Contracts

ref_id
name *
description

Processings

Template

Supported fields

ref_id
name*
description
status

Policies

Supported fields

ref_id
name
description
domain

Exceptions

Supported fields

ref_id
name
description
domain

Incidents

Supported fields

ref_id
name
description
domain

Vulnerability

Supported fields

ref_id
name*
description
status

📁 Folders

Folders (domains) are the top-level organisational units in CISO Assistant. Importing them lets you pre-populate a domain hierarchy before importing other objects.

Supported fields

name*
description
domain - name of the parent folder, must match exactly one existing folder name (case-insensitive)

Template

Special considerations

Conflict detection is performed by name + parent folder.
When domain is left blank the folder is attached to the root of the tenant.
An error is returned if domain matches more than one folder name.

✅ Tasks (incoming)

Tasks in CISO Assistant are modelled as TaskTemplates (definitions) with TaskNodes (individual occurrences). A non-recurrent task has one node; recurrent tasks generate one node per scheduled occurrence.

The wizard imports both in a single multi-sheet Excel file: a Summary sheet for the templates, plus one sheet per template that contains its past occurrences. A flat CSV upload is also accepted and imports templates only.

Template

Supported fields — Summary sheet

ref_id — reference identifier; used as the primary conflict-detection key when present
name*
description

Supported fields - per-template node sheets

Each sheet is named N-template name (truncated to 31 characters) and contains one row per past occurrence.

due_date* - date (YYYY-MM-DD); rows with a future date are skipped automatically
scheduled_date - date (YYYY-MM-DD); defaults to due_date when blank
status

Special considerations

Folder is a fallback. Each row's folder column is resolved first; the domain selected in the wizard is only used when a row has no folder.
Future nodes are skipped. Rows whose due_date is after today are ignored - those occurrences will be regenerated automatically from the schedule.
Round-trip safe. Exporting then re-importing with

Notifications

CISO Assistant can send you email notifications to keep you informed about deadlines, assignments, and status changes.

Prerequisites

Email notifications must be enabled by your administrator under Extra > Settings > Enable email notifications. Your CISO Assistant instance also needs an outgoing mail server configured. If you are not receiving emails, contact your administrator.

Notifications are sent to the email address associated with your account.

Notification types

Assignments

You receive an email whenever something is assigned to you.

Object

Field to fill

Your role

Deadlines & Expiry reminders

CISO Assistant sends reminders automatically 30 days, 7 days, and 1 day before a deadline or expiry date. These emails are sent every morning.

For reminders to fire, both fields below must be filled in.

Applied Control

Notification

Required field

Who receives it

Compliance Assessment

Notification

Required field

Who receives it

Evidence

Notification

Required field

Who receives it

Validation Flow

Notification

Required field

Who receives it

Task

Notification

Required field

Who receives it

Note for recurring tasks: reminders are automatically skipped if the recurrence interval is shorter than the reminder horizon (e.g., a daily task will not receive a 7-day warning).

Overdue alerts

If a deadline has already passed and the item is still open, you will receive an overdue alert.

Object

Required field

Alert sent to

Compliance assignment workflow

When working on a Requirement Assignment inside a compliance assessment, notifications follow the review workflow automatically — no extra fields to fill.

Event

Who is notified

Validation flows

Event

Who is notified

Account notifications

Event

Who is notified

Third-party questionnaires (TPRM)

If your organisation uses the Third-Party Risk Management module, external contacts receive an email when a questionnaire is sent to them. This email contains a link to fill in the questionnaire.

Quick reference — what to fill in

If you want this notification…

Fill in these fields

Frequently asked questions

I am not receiving any emails. What should I check? First confirm that email notifications are enabled with your administrator. Then verify that your account email address is correct in your profile. Finally, check your spam folder.

I filled in the fields but still got no email. Why? Check that the field contains an exact date — reminders are sent only on specific days (30, 7, and 1 day before). If the deadline is sooner than 30 days from when you set it, the 30-day reminder will not fire.

I am receiving too many reminders. Can I opt out? Per-user opt-out is not yet available.

At what time are reminders sent? Reminders are sent in the early morning (between 6 AM and 7 AM server time).

Will I get a reminder every day until the deadline? No. Reminders are sent only on specific days: 30 days before, 7 days before, and 1 day before the deadline. Overdue alerts are sent daily until the item is resolved.

Features focus

Controls autosuggestion

The recommendation system allow you to create applied controls and automatically assign them to your audit requirements, based on the reference controls of the catalog:

Multi-level support

Through implementation groups

Multiple frameworks have their requirements organized into subgroups, mostly cumulative but not always. We introduced it in v1.3.x better support for such a concept using the concept of implementation groups from CIS, but with a generic implementation to cover both cases.

When creating a new audit with a framework that supports implementation groups (IG), you'll get a drop-down menu to select the ones you want to use. They can be combined to suit your needs. If no implementation group is selected, the audit will start with all the requirements, and you can still update it to add or remove other IG.

CyFun and CIS, and FedRamp have been updated to take advantage of this feature. Other relevant frameworks are currently being updated.

Model

Deployment

Customization

Contributing

CA Journeys

Integration

Data import wizard

Guidelines on data import format

Applicable for: Data import wizard UI (Pro) and CLI (Community or Pro)

Connection Error

If you encounter this error, it could be due to the Excel file being protected by Information Rights Management (IRM)

Overview

The Data Import Wizard and the CLI both support batch creation and updates of fields. They provide the same capabilities; the only difference lies in how the import is initiated:

through the user interface for the Data Import Wizard
through the command line for the CLI

When an object already exists during an import, one of the following conflict-resolution strategies can be applied:

Stop the import (default): the import is aborted as soon as a conflict is detected
Skip the row: the existing field is left unchanged and the import continues
Update the row: the existing field is updated with the imported data

Fields with (*) are mandatory and don't have any supported fallback.

Unless marked as mandatory, ref_id fields can be left blank but the column must still exist.

📦 Assets

Template

Supported fields

ref_id
name*
description
domain

Special considerations

type will default to supporting if the column does not exist

⚙️ Applied controls

Template

Supported fields

ref_id
name*
description
domain

Special considerations

status will default to to_do
csf_function will default to govern
The owner field resolves against existing users (by email) and teams (by name). Ensure any referenced users and teams are created before importing. Unresolved entries are skipped with a warning and will not block the import.

📦 Perimeters

Template

Supported fields

ref_id
name*
description
domain

Special considerations

If the default_assignee column is present and empty, the import would end up cleaning existing assignee.

📃 Audits

Template

To avoid any mixup on the expected fields and the requirements reference, you can get a template for the expected framework by going into Catalog/Frameworks

The framework needs to be loaded and when clicking on it, you'll see a button to get the excel file.

Supported fields

urn*
assessable
ref_id*
name

Special considerations

The wizard will attempt to match based on the ref_id and fallback to the urn otherwise. If none could be used, the row will be skipped.
name and description columns are not used but serve as an anchor point for reference.
Assessable will fallback to false

🐞 Findings followup (eg. pentest)

Template

Supported fields

ref_id
name*
description

👥 Users

Template

Supported fields

email*
first_name
last_name

☣️ Risk assessment

Controls are created on picked based on the perimeter's domain. Line breaks are used as seperator.

Template:

Supported fields:

ref_id: String
name*: String
description: String

1: The string must represent a value present in the chosen risk matrix

🏢 Business Impact Analysis

The BIA export/import uses a multi-sheet Excel file:

Summary sheet - one row per BIA
<BIA name> sheet - one row per asset assessment for that BIA
<BIA name> - thresholds sheet - one row per escalation threshold for that BIA

Template

Summary sheet

Supported fields

name*
description
perimeter - name of the perimeter

Special considerations

status defaults to planned if not provided
perimeter and risk_matrix are resolved by UUID, ref_id, or name (in that order)

Asset assessment sheets (<BIA name>)

One sheet per BIA, named after the BIA. Each row is an asset assessment.

Supported fields

bia_name* - name of the parent BIA (injected automatically on re-import)
asset* - name of the asset
asset_ref_id - ref_id of the asset (alternative lookup)

Special considerations

asset is resolved by UUID, ref_id, or name (in that order)
Boolean fields accept true/false, yes/no, 1/0

Threshold sheets (<BIA name> - thresholds)

One sheet per BIA, named <BIA name> - thresholds. Each row is an escalation threshold.

Supported fields

bia_name* - name of the parent BIA
asset* - name of the asset (used to resolve the asset assessment)
asset_ref_id - ref_id of the asset (alternative lookup)

Special considerations

The asset assessment is resolved by matching (bia_name, asset) — both must already exist before thresholds are imported
point_in_time combined with the asset assessment forms the unique key for update/deduplication
quali_impact defaults to -1

⚙️ Elementary actions

Elementary actions are useful to model a killchain during the 4th workshop of an EBIOS RM study.

Supported fields:

ref_id
name*
description
attack_stage*

Reference controls

Reference controls are templates of the controls to apply.

Supported fields:

ref_id
name
description
category

Reference controls can be bundled also as a library.

Threats

ref_id
name
description
domain

Third parties ecosystems

Adding entities, solutions and contracts go through the same file to be able to keep consistent relationships. Each concept needs to be on a separate tab of the excel sheet.

The file has to be divided into 3 sheets namely "Entities", "Solutions" and "Contracts"

Supported fields

*: Required fields

Entities

ref_id
name *
description

Solutions

ref_id
name *
description

Contracts

ref_id
name *
description

Processings

Template

Supported fields

ref_id
name*
description
status

Policies

Supported fields

ref_id
name
description
domain

Exceptions

Supported fields

ref_id
name
description
domain

Incidents

Supported fields

ref_id
name
description
domain

Vulnerability

Supported fields

ref_id
name*
description
status

📁 Folders

Folders (domains) are the top-level organisational units in CISO Assistant. Importing them lets you pre-populate a domain hierarchy before importing other objects.

Supported fields

name*
description
domain - name of the parent folder, must match exactly one existing folder name (case-insensitive)

Template

Special considerations

Conflict detection is performed by name + parent folder.
When domain is left blank the folder is attached to the root of the tenant.
An error is returned if domain matches more than one folder name.

✅ Tasks (incoming)

Template

Supported fields — Summary sheet

ref_id — reference identifier; used as the primary conflict-detection key when present
name*
description

Supported fields - per-template node sheets

Each sheet is named N-template name (truncated to 31 characters) and contains one row per past occurrence.

due_date* - date (YYYY-MM-DD); rows with a future date are skipped automatically
scheduled_date - date (YYYY-MM-DD); defaults to due_date when blank
status

Special considerations

Folder is a fallback. Each row's folder column is resolved first; the domain selected in the wizard is only used when a row has no folder.
Future nodes are skipped. Rows whose due_date is after today are ignored - those occurrences will be regenerated automatically from the schedule.
Round-trip safe. Exporting then re-importing with

Designing your own Libraries

NOTE: This section is still under reworking. For complementary informations, please refer to the dedicated README on GitHub.

This documentation explains how to create, maintain and evolve custom libraries for CISO Assistant using Excel, YAML, and the official tools provided in the community repository.

1. What is a Library in CISO Assistant?

A library is a container that bundles one or more governance objects that can be imported into CISO Assistant.

A single library may contain:

Framework
Threats
Reference controls
Risk matrices

In practice, Risk matrices and Mappings between frameworks have their own library for practical reasons.

Libraries are versioned, portable, and reusable across projects.

In practice:

Excel (.xlsx) is the authoring format
YAML (.yaml) is the import/export format
Python tools are used to convert and validate data

2. Key Concepts

Before creating your first library, it is important to understand a few core concepts.

2.1 Frameworks and Requirements

A framework is a hierarchical structure representing a standard, regulation, or internal control model.

A framework is composed of:

Organizational nodes (categories, sections, subsections, information, ...)
Requirements, which are the assessable elements

Only requirements can be assessed during audits.

2.2 Assessable vs Non-assessable Nodes

In a framework:

Categories and sections are structural
Requirements are assessable

This distinction is explicit in Excel via the assessable column.

2.3 Hierarchy and Depth

Frameworks are hierarchical by nature.

Each row in Excel has a depth
Depth starts at 1
Deeper levels represent nested structures

CISO Assistant supports deep hierarchies, but depths above 6 are strongly discouraged for readability.

2.4 URNs and ref_id

Each object is uniquely identified by a URN.

ref_id is the human-defined identifier
URNs are generated using urn_prefix + ref_id
URNs must remain stable across versions

Changing URNs breaks mappings and historical data.

2.5 Implementation Groups (IG)

Implementation Groups allow you to:

Scope requirements
Build subsets of a framework
Adapt questionnaires to context or maturity level

They are optional but highly recommended for complex frameworks.

2.6 Scores and Answers

Frameworks can define:

Scoring models
Answer sets
Conditional questions
Weighted scoring

These elements allow frameworks to behave as questionnaires, not just checklists.

2.7 Mappings

Mappings describe relationships between requirements from different frameworks.

They are used to:

Translate compliance
Compare standards
Build equivalency views

Mappings are directional and typed (equal, subset, superset, intersect).

3. Recommended Workflow

Here is the recommended procedure for creating and maintaining custom libraries:

Define the framework structure or use an existing one

Plan the structure and decide whether to start from scratch or reuse an existing framework.

4. Creating a Framework using Excel (v2 format)

This section doesn't explain all the object types yet, neither the type of values to put in the columns. In the meantime, you can refer to the for more up-to-date information.

4.1 Why Excel?

Excel is the recommended authoring format because:

It is accessible to non-developers
It enforces structure
It reduces YAML syntax errors
It supports collaboration and review

Excel files are converted to YAML only at the final step.

4.2 Excel file structure (v2)

Excel files follow strict conventions.

Tabs are divided into:

_meta tabs → configuration and metadata
_content tabs → actual objects and data

Each object type has:

One _meta tab
One _content tab (except library_meta)

4.3 Example Framework (Strongly Recommended)

Before creating or editing your own framework, we strongly recommend reviewing the provided example file .

This file is a reference implementation of the Excel v2 format and is designed to help users understand how a valid framework is structured.

Why this example matters

The Excel v2 format is powerful but can be confusing at first. The example framework helps you understand:

How _meta and _content tabs are organized
How hierarchy is expressed using depth and row order
The difference between structural nodes and assessable requirements

The file is intentionally:

Color-coded to highlight structure
Annotated with cell notes (look for the small triangle in the top-right corner of cells)

Recommended way to use the example

Open example_framework.xlsx in Excel or LibreOffice and explore the tabs and cell notes.

If you would like to see what this example looks like directly in CISO Assistant, convert it using the standard conversion tool:

When to come back to the example framework

Use the example file whenever you:

Start a new framework from scratch
Are unsure about the meaning of a column
Encounter validation errors during conversion
Want to check whether your Excel file follows best practices

Before opening a support ticket related to framework creation, consulting the example framework may sometimes solve your problem.

4.4 The `library_meta` Tab

This tab defines the library itself.

Mandatory fields include:

type
urn
version

Versioning is critical. If the custom framework is already imported into CISO Assistant and the version number has not been incremented, CISO Assistant will not suggest an update.

4.5 Framework definition Tabs

A framework is defined using:

One _meta tab of type framework
One _content tab listing all nodes

The _content tab is ordered top-to-bottom and defines the hierarchy.

Important columns:

assessable
depth
ref_id

Order matters: the hierarchy is inferred from row order + depth.

4.6 Threats

Threats represent events or situations that may negatively impact an organization.

Typical examples include:

Data breach
Ransomware attack
Insider threat
Loss of availability

Threats are designed to be reusable across multiple frameworks and libraries.

Structure

Threats are defined using:

One _meta tab of type threats
One _content tab listing individual threats

Each threat includes:

A ref_id
A name
A description (optional)

Threats are usually referenced from framework requirements using their URN.

A library may contain only threats, without any framework. This is a common pattern when building shared threat catalogs reused across multiple frameworks.

4.7 Reference Controls

Reference controls describe controls or safeguards that can mitigate threats or help fulfill requirements.

They are typically used to:

Document expected controls
Link requirements to best practices
Support evidence collection and audits

Examples:

Access control policy
Backup procedures
Network segmentation
Incident response process

Structure

Reference controls are defined using:

One _meta tab of type reference_controls
One _content tab listing individual controls

Each control include:

A ref_id
A name
A description (optional)

Reference controls can be defined independently of any framework and packaged in their own library, exactly like threats.

4.8 Risk Matrices

Risk matrices are used to model risk evaluation logic, typically combining probability and impact into a resulting risk level.

They define how risk is calculated, not how compliance is assessed.

Typical usage

Risk matrices are usually:

Independent from frameworks
Shared across multiple projects
Maintained separately from compliance libraries

For this reason, they are most often packaged alone in their own library, without any framework.

Structure

A risk matrix is defined using:

One _meta tab of type risk_matrix
One _content tab describing:
- Probability levels

The grid defines the logical relationship between values. The visual rendering (orientation, colors, layout) is handled by the CISO Assistant interface.

Important Note: Use Existing Examples

Risk matrices are not trivial to design correctly, especially the grid logic.

For this reason, we strongly recommend starting from one of the existing examples available in .

These examples:

Are already valid and tested
Follow best practices
Can be adapted to your own risk model

Risk matrices can be converted and imported using the same tools as other library objects.

5. Using the Tools

All tools described below are located in the directory of the community repository.

These tools are designed to:

Reduce human errors
Enforce the CISO Assistant data model
Make libraries easier to maintain over time

You do not need to use all tools in every project. Each tool addresses a specific user intent, described below.

Prerequisites

Before using any of the conversion or preparation tools, make sure your environment is correctly set up.

You will need:

Python 3.12 or higher and pip (included with Python)
A local copy of the community repository

In the /tools directory, run the following commands:

This installs all required Python dependencies needed to run the tools.

This setup only needs to be done once.

5.1 Creating a Framework Skeleton (Recommended Starting Point)

Tool:

This tool helps you create a clean and valid Excel file that already follows the v2 format rules.

Typical use cases

Creating a framework from scratch
Avoiding mistakes in _meta and _content tabs
Standardizing framework creation across teams

What this tool does

Generates a fully structured Excel file
Creates required _meta and _content tabs
Adds metadata and columns directly inside Excel cells

Recommended usage (simple)

By default, the tool uses a configuration file named prepare_framework_v2_config.xlsx, which:

Is self-documented
Can be edited directly
Avoids complex command-line arguments

Advanced usage

You may also use a YAML configuration file:

This is intended for advanced users who prefer YAML-driven configuration.

After running this tool, the library_meta tab and the framework _meta tab usually do not need to be modified again, except if you want to:

Add translations

5.2 Converting an Excel file to a Library (Main conversion step)

Tool:

This is the most frequently used tool.

It converts one or more Excel files into CISO Assistant-compatible YAML libraries.

Typical use cases

Generating a YAML file from an Excel framework
Validating Excel consistency
Importing libraries into CISO Assistant
Updating an existing framework

Basic usage (recommended for most users)

This will:

Validate the Excel file
Generate my_framework.yaml
Report clear errors if something is wrong

In most situations, this command is sufficient.

Verbose mode (recommended during troubleshooting)

Verbose mode:

Explains what the tool is doing
Helps understand validation errors
Is very useful during early framework design

Bulk mode (multiple frameworks)

This will:

Convert all .xlsx files in the folder
Generate one YAML file per Excel file

Optional output directory:

Compatibility modes (advanced users)

Compatibility modes exist only for legacy or special cases.

If you are unsure, do not use compatibility modes.

--compat 0 (default): Recommended for all new libraries
--compat 1: Used only to maintain libraries created before v1.9.20
--compat 2: Prevents URN cleaning (advanced / niche use cases)

5.3 Migrating Legacy Frameworks (v1 → v2)

Tool:

This tool helps migrate old v1 frameworks to the v2 format, as the v1 Excel format is deprecated.

Typical use cases

Updating legacy frameworks
Preserving historical identifiers
Preparing old content for long-term maintenance

Usage

This produces a new v2-compatible file.

If you use convert_library_v2.py on an Excel file converted into v2, the YAML structure may be completely different from your original YAML file and break your audits if you import it into CISO Assistant!

You can use the convert_v1_to_v2.py script if you created your framework using the v1 format and provided that you HAVE NOT YET imported your framework into CISO Assistant.

You can also use it if you notice that the URNs in the YAML file created with the v2 version of your framework are identical to the URNs in the YAML file of the v1 version of your framework. You can also try using the script's compatibility modes to recover the old structure.

The result must be reviewed manually. Migration fixes Excel structure, not design quality. In some cases, you should still simplify and clean legacy content afterward.

6. Creating Mappings between Frameworks

Mappings describe how requirements from two frameworks relate to each other.

They are used for:

Compliance translation
Framework comparison
Cross-standard reporting

Generate a Mapping Excel file

Tool:

Usage:

This tool:

7. Importing a Custom Library into CISO Assistant

Once your Excel file has been successfully converted into a YAML file, the final step is to import the library into CISO Assistant.

This operation is performed directly from the CISO Assistant interface and does not require any additional tooling.

7.1 Prerequisites

Before importing your library, make sure that:

Your Excel file has been successfully converted using convert_library_v2.py
The resulting .yaml file contains no validation errors

7.2 Importing the Library

Open CISO Assistant

If the file is valid:

The import will be accepted immediately
The library will be added to your available libraries

7.3 After import: Where to find your Framework

Once the library is imported, go to Compliance → Frameworks.

Your custom framework will appear in the list (you can search it in the search bar). It can now be used in audits if it's a framework, or used as mapping of it's a mapping

7.4 Common import errors

If the import fails, CISO Assistant will display an explicit error message.

Common causes include:

Missing mandatory fields in library_meta
Invalid or duplicated URNs
Inconsistent framework hierarchy

In most cases:

Fix the issue in Excel
Re-run convert_library_v2.py
Re-import the updated YAML file

7.5 Testing your Framework after import

After importing a framework, it is strongly recommended to:

Create a test audit using the framework
Verify:
- Hierarchy rendering
- Assessable requirements

This validation step ensures that:

The framework behaves as expected
No structural or logical issues remain

8. Updating and Maintaining Libraries

8.1 Version Management

Always increment version in the library_meta sheet.

If the version is unchanged, CISO Assistant will ignore the update.

8.2 URN Stability

Never change:

urn_prefix
ref_id of existing nodes

Changing URNs breaks:

Mappings
Historical assessments
References

8.3 Best Practices

Start small, then extend
Test with minimal frameworks
Avoid deep hierarchies
Use Implementation Groups early (if necessary)

9. Common Pitfalls

Forgetting to increment the version
Using v1 format instead of v2 format
Changing ref_id on existing nodes

10. Final Notes

For advanced or low-level options, always refer to the .

(Old) Videos

IMPORTANT NOTICE: The following sections contain information that is no longer up to date, but some parts are still useful today. Please consult them with caution.

Testing your custom framework

Full guide (French)

MCP setup guide

This guide explains how to connect your AI assistant to CISO Assistant using the Model Context Protocol (MCP). Once set up, you'll be able to ask your AI to create risk assessments, manage compliance

Compatible with: SaaS or on-premises, CE or Pro

Tested MCP clients: Claude Desktop, Claude Code, LM Studio, OpenWebUI

What is MCP?

MCP (Model Context Protocol) allows AI assistants like Claude to interact with external tools and services. Think of it as giving your AI a set of capabilities to read and write data in CISO Assistant.

The CISO Assistant MCP server provides 90+ tools covering:

Risk management (assessments, scenarios, matrices)
Compliance audits (frameworks, requirements)
Asset management
Third-party risk management (TPRM)

Why stdio Transport?

The MCP server uses stdio (standard input/output) transport instead of HTTP. Here's why:

Local file access - stdio allows the server to read and process local files on your machine, which HTTP-based servers cannot do securely.
Network control - All API calls to CISO Assistant go through your local machine. You have full visibility and control over network traffic, and can use your existing firewall rules and proxies.
No open ports - Unlike HTTP servers, stdio doesn't require opening any ports on your machine, reducing your attack surface.

Step 0: Get the MCP Server Code

The MCP server code is included in the CISO Assistant repository. You need to download it to your machine first.

Option A: Clone with Git (recommended)

This makes it easy to update later with git pull.

Option B: Download as ZIP

Go to https://github.com/intuitem/ciso-assistant-community
Click the green Code button
Select Download ZIP
Extract the ZIP file to a folder of your choice

Note: The MCP server lives in the cli folder. You'll need the full path to this folder for the configuration steps below.

Prerequisites

Before you begin, make sure you have:

CISO Assistant running - Either locally or on a server (can be the same machine or a remote server). If you're on a SaaS instance, you need to have the API enabled. You can open a support request to do, and keep in mind that it requires ip filtering to be enabled as well.
Python 3.12+ installed
uv package manager (recommended) - Install with:

Step 1: Generate a Personal Access Token (PAT)

You need a token to authenticate the MCP server with CISO Assistant:

Log in to CISO Assistant
Click on your profile icon (top right)
Go to Settings → Personal Access Tokens
Click

Important: Save this token somewhere safe. You won't be able to see it again.

Step 2: Configure the MCP Server

Navigate to the cli folder in your CISO Assistant installation:

Create your configuration file:

Edit .mcp.env with your details:

Common API URLs:

Local Docker setup: http://localhost:8000/api
Local development: http://127.0.0.1:8000/api
Production server: https://your-server.com/api

Setup for Claude Desktop

Claude Desktop uses a JSON configuration file to know about MCP servers.

Find your config file location

Operating System

Config File Path

Create or edit the config file

If the file doesn't exist, create it. Add the following configuration:

Replace /path/to/ciso-assistant-community/cli with your actual path.

Example paths by OS

macOS:

Windows:

Linux:

Alternative: Pass credentials via environment

Instead of using .mcp.env, you can pass credentials directly in the config:

Restart Claude Desktop

After saving the config file, completely quit and restart Claude Desktop. The MCP server should now be available.

Verify it works

In Claude Desktop, try asking:

"What folders exist in CISO Assistant?"

If configured correctly, Claude will use the MCP tools to query your CISO Assistant instance.

Setup for Claude Code (CLI)

Claude Code reads MCP configuration from a .mcp.json file.

Create the config file

In your home directory or project folder, create .mcp.json:

Config file locations

Claude Code looks for .mcp.json in these locations (in order):

Current working directory
Home directory (~/.mcp.json)

Alternative: Specify full path to uv

If uv isn't in your PATH, use the full path:

Find uv's location with:

Verify it works

Start Claude Code and ask:

"List all risk assessments in CISO Assistant"

Setup for LM Studio

LM Studio supports MCP servers through an mcp.json configuration file, similar to Claude Desktop.

Step 1: Open the MCP configuration

Open LM Studio
Go to Settings (gear icon)
Click on the Program tab

Step 2: Add the CISO Assistant server

Add the following configuration to your mcp.json:

Replace:

/path/to/uv with your actual uv path (find it with which uv on macOS/Linux)
/path/to/ciso-assistant-community/cli with your actual cli folder path
your-personal-access-token

Example (macOS)

Step 3: Save and restart

Save the mcp.json file and restart LM Studio for the changes to take effect

Troubleshooting

"Connection refused" or "Cannot connect to API"

Make sure CISO Assistant is running
Verify the API_URL is correct
Check if you can access the API in your browser: http://localhost:8000/api/

"Authentication failed" or "401 Unauthorized"

Verify your token is correct in .mcp.env
Make sure the token hasn't expired
Generate a new token if needed

"Certificate verification failed"

For local development, set VERIFY_CERTIFICATE=false
For production with self-signed certs, also set to false
For production with valid SSL, set to true

MCP server not appearing in Claude Desktop

Check the config file location is correct for your OS
Verify the JSON syntax is valid (use a JSON validator)
Make sure paths use forward slashes / (even on Windows) or escape backslashes \\

"uv: command not found"

Install uv (see Prerequisites section)
Use the full path to uv in your config
On macOS/Linux, you may need to add ~/.cargo/bin to your PATH

Check MCP server logs

Test the server directly from terminal:

If there are configuration errors, they'll appear here.

What Can You Do With It?

Once connected, try these example prompts:

Explore your data:

"Show me all risk assessments"
"List the compliance frameworks I have imported"
"What assets are in the Production folder?"

Create new items:

"Create a new folder called 'IT Security'"
"Add a risk scenario for ransomware affecting the CRM system"
"Create a compliance assessment for ISO 27001"

Analyze and report:

"Show me the gap analysis for my SOC2 audit"
"What are the high-risk scenarios in my assessment?"
"List all controls that are not yet implemented"

Manage third parties:

"List all our vendors"
"Create an entity assessment for Acme Corp"
"What contracts are expiring soon?"

FAQ

What about ChatGPT compatiblity?
- chatGPT custom mcp support has been introduced on Q4/2025 but is not mature enough yet. Users can set it up but would require enabling developper mode, some extra proxification and internet exposure which we don't recommend for now. We're monitoring their MCP support and we'll update the page accordingly.

Need Help?

CISO Assistant Documentation: https://intuitem.gitbook.io
GitHub: https://github.com/intuitem/ciso-assistant-community
Discord:

Quick Reference: Environment Variables

Variable

Required

Default

Description

Outgoing webhooks

Outgoing Webhooks

Webhooks allow CISO Assistant to notify external systems in real-time when specific events occur within your GRC platform. Instead of polling our API every few minutes to check for changes, we will push data to you as soon as it happens.

When to use Webhooks

Webhooks are ideal for building automation pipelines and keeping external systems in sync. Common use cases include:

ChatOps: Notify a Slack or Teams channel when a new Risk is identified.
Ticket Sync: Automatically create a Jira ticket when an AppliedControl fails validation.
Audit Logging: Archive all deleted events to an external immutable storage bucket for compliance evidence.

Supported Events

You can subscribe to events at a granular level. Currently, CISO Assistant supports the following events:

Applied controls:
- appliedcontrol.created
- appliedcontrol.updated

Configuration & Security Features

CISO Assistant adheres to the . We prioritize security to ensure that the data sent to your systems is authentic and has not been tampered with.

1. Payload Strategies: Full vs. Thin

When configuring an endpoint, you can choose between two payload strategies.

Thin Payloads (PRO) (Recommended for Security):
- What it sends: Only the id of the changed resource.
- How to process: Your system receives the ID, then makes an authenticated API call back to CISO Assistant to fetch the details.

2. Secret Keys & Signatures

When you create a webhook endpoint, you can generate a unique secret key (whsec_...). You will only be shown this secret once.

Every request we send to you is signed using this secret (via HMAC-SHA256). By verifying this signature, you ensure:

Authenticity: The message definitely came from CISO Assistant.
Integrity: The message content was not altered in transit.

3. Replay Protection (Timestamps)

Attackers may try to intercept a valid webhook request and "replay" it later to trick your system (e.g., triggering a deployment twice).

To prevent this, we include a timestamp in the signature. Your application should reject any request that is older than your tolerance window (e.g., 5 minutes).

4. Idempotency (IDs)

Network issues may cause us to retry sending a webhook, resulting in your server receiving the same message twice. Every webhook includes a unique webhook-id. You should log these IDs and ensure you do not process the same ID more than once.

The Integration Journey

Enable the Webhooks feature flag in Settings > Feature flags
Create an Endpoint: In the CISO Assistant UI, navigate to Settings > Webhooks.
Configure: Enter your receiver URL and select the events you want to listen to (e.g., appliedcontrol.updated).

Technical Reference

Payload Structure

All payloads follow the Standard Webhooks JSON structure.

Top-Level Fields:

type: The event name (e.g., appliedcontrol.created).
timestamp: When the event happened (ISO 8601).
data

Example: Thin Payload

Example: Full Payload

Headers

We send the following headers with every request:

Content-Type: application/json
webhook-id: Unique message ID (for idempotency).
webhook-timestamp

Verifying the Signature

You MUST verify the signature to ensure security. Do not trust the payload content until verification passes.

The Algorithm:

Extract the webhook-id, webhook-timestamp, and webhook-signature.
Concatenate strings to form the signed content: [webhook-id].[webhook-timestamp].[raw_body].

Python Example (Django/FastAPI/Flask)

Operational Details

Retries & Reliability

We use a "best effort" delivery system.

Success: We consider a delivery successful if your server returns any 2xx HTTP status code (e.g., 200 OK, 201 Created).
Failure: Any other status code (400, 401, 500) or a connection timeout is considered a failure.

IP Allowlisting (Compensatory Controls)

If your receiving endpoint is behind a corporate firewall, you may need to allowlist the IP address of the CISO Assistant server.

SaaS Users: ???
On-Prem Users: The webhooks originate from the IP address of the server running the huey worker process. Ensure your firewall allows inbound HTTPS traffic from this internal or external IP.

CISO Assistant

Welcome to CISO Assistant

hashtagA different take on Cyber Security Posture Management

hashtagAn open-source GRC tool

hashtagAbout the SaaS and PRO plan

hashtagQuick links

hashtagReplays

hashtagGet Started

hashtag

hashtagModel

Guide

Installation

hashtagNew! Config Builder

hashtagDocker compose

hashtagHelm chart

Understanding decoupling

General tips

Journeys

Creating your first perimeter

Creating your first Audit

Overview

hashtagAnalytics

hashtagComposer

hashtagCalendar

Extra tools

hashtagX-rays

hashtagScoring Assistant

hashtagGlossary

External resources

hashtagLive sessions

Understand mapping

Glossary

Data import wizard

hashtagApplicable for: Data import wizard UI (Pro) and CLI (Community or Pro)

hashtagConnection Error

hashtagOverview

hashtag📦 Assets

hashtagTemplate

hashtagSupported fields

hashtagSpecial considerations

hashtag⚙️ Applied controls

hashtagTemplate

hashtagSupported fields

hashtagSpecial considerations

hashtag📦 Perimeters

hashtagTemplate

hashtagSupported fields

hashtagSpecial considerations

hashtag📃 Audits

hashtagTemplate

hashtagSupported fields

hashtagSpecial considerations

hashtag🐞 Findings followup (eg. pentest)

hashtagTemplate

hashtagSupported fields

hashtag👥 Users

hashtagTemplate

hashtagSupported fields

hashtag☣️ Risk assessment

hashtagTemplate:

hashtagSupported fields:

hashtag🏢 Business Impact Analysis

hashtagTemplate

hashtagSummary sheet

hashtagSupported fields

hashtagAsset assessment sheets (<BIA name>)

hashtagThreshold sheets (<BIA name> - thresholds)

hashtagSupported fields

hashtag⚙️ Elementary actions

hashtagSupported fields:

hashtagReference controls

hashtagSupported fields:

hashtagThreats

hashtagThird parties ecosystems

hashtagSupported fields

hashtagEntities

hashtagSolutions

hashtagContracts

hashtagProcessings

hashtagTemplate

A different take on Cyber Security Posture Management

An open-source GRC tool

About the SaaS and PRO plan

Quick links

Replays

Get Started

Model

New! Config Builder

Docker compose

Helm chart

Analytics

Composer

Calendar

X-rays

Scoring Assistant

Glossary

Live sessions

Applicable for: Data import wizard UI (Pro) and CLI (Community or Pro)

Connection Error

Overview

📦 Assets

Template

Supported fields

Special considerations

⚙️ Applied controls

Template

Supported fields

Special considerations

📦 Perimeters

Template

Supported fields

Special considerations

📃 Audits

Template

Supported fields

Special considerations

🐞 Findings followup (eg. pentest)

Template

Supported fields

👥 Users

Template

Supported fields

☣️ Risk assessment

Template:

Supported fields:

🏢 Business Impact Analysis

Template

Summary sheet

Supported fields

Asset assessment sheets (<BIA name>)

Threshold sheets (<BIA name> - thresholds)

Supported fields

⚙️ Elementary actions

Supported fields:

Reference controls

Supported fields:

Threats

Third parties ecosystems

Supported fields

Entities

Solutions

Contracts

Processings

Template

Supported fields

Policies

Supported fields

Exceptions

Supported fields

Incidents

Supported fields

Vulnerability

Supported fields

📁 Folders

Supported fields

Template

Special considerations

✅ Tasks (incoming)

Template

Supported fields — Summary sheet