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.
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.
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.
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.
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.
Governance tab
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.
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
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
Creating your first risk assessment
Small tutorial to learn how to create your first compliance assessment
Firstly, we need to import some external objects before starting our risk assessment: a matrix, threats and reference controls.
We can create the risk assessment, and let's take a look inside.
We find three parts: details about the assessment, the list of associated risk scenarios and the risk matrix view.
Let's add the first scenario and do the current assessment of it.
You can see that I didn't find the threat I was looking for in the imported library, so I decided to create my custom threat.
From now on, you won't necessarily follow the same steps depending on your needs. In this example I choose to mitigate the scenario by creating an applied control for it.
We go back in the scenario edit view, add the freshly created applied control, do the residual assessment and choose a strength of knowledge level.
As you can see, back in the risk assessment view, the current and residual scenario were added in matrix views with a diamond to indicate the strength of knowledge. To find out more about this concept, take a look at the from the .
Congratulation! 🎉
If you followed the three last pages, you have just created your first assessments on CISO Assistant! The following section will show you how to use our management tools 🔎
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.
Understanding decoupling
Decoupling compliance from security operations and controls is a cornerstone of CISO Assistant philosophy. Let's see it through this short animation:
Flash mode
Establishing a security posture in flashcards mode
Mapping explorer
The graph explorer helps you understand and navigate the cross walks between the frameworks.
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:2022is 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 dostatus 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.
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)
Pick your frameworks
Start an audit
Link or create your applied controls
♻️ Track the applied controls progress, attach evidences and reflect the progress on the audit
"I want to conduct risk assessments and keep track on a risk register"
Identify the scopes (domains/perimeters)
Pick your matrix
Add or import your assets
Add or import your threats
"I have multiple vendors that I need to identify their cyber security posture"
Identify the scopes (domains/perimeters)
Create the vendors (entities) and their products or services (solutions)
Identify a framework to assess them and trigger an entity assessment
"I have a list of findings or issues that I need to track"
Identify the scopes (domains/perimeters)
Start a follow-up
Add or import your findings
Link or create the applied controls
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:
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.
Role
A bundle of permissions. Four roles are built-in:
- Domain Manager: can set up and access everything on a domain
- Analyst: can input and read data, but cannot change the settings of a domain
- Reader: can only read the items of a domain
- Approver: can validate workflows on objects for a domain (eg, Risk Acceptance)
Library clean-up
How to delete/remove a loaded library
If you want to delete a load library, make sure it's not used anywhere (for framework, that's an audit is not depending on them, for a risk matrix, that a risk assessment is not relying on it, etc.) and head to the loaded libraries section of your libraries (Governance/Libraries).
If the item is not used, it will show as "deletable" as below:
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.
Data import wizard
Guidelines on data import format
Applicable for: Data import wizard (Pro) and CLI (Community and Pro)
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
📦 Perimeters
Template
Supported fields
ref_id
name*
description
domain
📃 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
severity
👥 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.
Supported fields:
ref_id
name*
description
inherent_impact
⚙️ 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. The supported fields are:
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
internal_id
ref_id
name*
description
Policies
Supported fields
ref_id
name
description
domain
Exceptions
Supported fields
ref_id
name
description
domain
Incidents
Supported fields
ref_id
name
description
domain
Start a risk assessment
♻️ Identify your scenarios, assess them, link or create the applied controls, and the reflect the progress on the risk level
♻️ Track the audits progress, assign controls and make your opinion
♻️ Track the applied controls progress and reflect that on your findings status
User group
A combination of a role and a domain, on which you can have your users.
User groups are automatically created on your behalf whenever you create a domain
Reference Control
A template for a control that can be used as a reference and re-instantiated when needed.
Applied Control
The main component of the action plan. The actual action that you have implemented or will implement. It could be technical, process, policy, documentation, etc.
Evidence
A document, screenshot, config sample, etc., that can prove that an applied control has been properly implemented.
Task
Main component of the task management module. It can be a one-time thing, a periodic one. It supports assignment.
Catalog objects
Reusable objects of CISO Assistant, and are the building blocks of the library (Frameworks, threats, matrix, etc.)
Library
Container object that holds one or multiple catalog objects for CISO Assistant (e.g. Framework, matrix, etc.)
Framework
A set of requirements that covers patterns and expectations to comply with a regulation, prepare a certification, or establish a foundation.
Mapping
Based on the OLIR initiative and allows moving between a framework A to framework B while reusing the previous assessment.
Entity
Scope of an external review, usually the vendor / third party.
Solution
Product or service provided by the entity
Entity assessment
The actual review of the entity, which can trigger or be linked to an audit
Representative
The person that needs to answer the questionnaire and requirement of the entity assessment.
URN
Uniform Resource Name, used as a unique identifier to link to multiple CISO Assistant catalog objects.
When new upgrades are available for a library, you can choose to pull the upgrade on your existing audits. This is pretty useful for applying nondestructive updates such as typo fixes, adding implementation groups, and so on.
Teams
Teams in CISO Assistant are used to group users who work together on the same security activities, such as risk assessments, compliance programs, or audits.
Each team has a Team Leader, optional Deputies, and Members, making it easy to reflect real-world responsibilities and delegation. A team can also have a dedicated team email address for shared communications. Teams centralize ownership, collaboration, and notifications by allowing CISO Assistant to automatically reach the right people based on their role within the team.
Tasks, assessments, assets, applied controls, etc., can be assigned to teams, in the same way as to users.
Please note: if OIDC mode has ben configured before, you must reset the Client ID field to 0 in the OIDC tab and save before proceeding.
Failure to do so will prevent proper SAML configuration. This behavior is known and will be addressed in future releases.
Configure CISO Assistant with SAML
Once you've retrieved the IdP Entity ID, the Metadata URL and the Entity ID from your provider(see the list of providers for specific details), the configuration on CISO Assistant is pretty simple.
Log in into CISO Assistant as an administrator > Extra > Settings
Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.
OpenID Connect (OIDC)
Configure CISO Assistant with OpenID Connect (OIDC)
Once you've retrieved the IdP Entity ID, the Metadata URL and the Entity ID from your provider (see the list of providers for specific details), the configuration on CISO Assistant is pretty simple.
Log in into CISO Assistant as an administrator > Extra > Settings
Navigate to SSO settings
Enable SSO
Select the OpenID Connect provider
Enter the Client ID
Enter the Client secret
Enter the Server URL
And that's it! Don't forget to click the 'Save' button
You should now be able to see the Login with SSO button
Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.
Identity providers
You can log into CISO Assistant with any identity provider (IdP), given that it supports either SAML or OpenID Connect (OIDC).
Don't find documentation on how to set up SSO with your identity provider? Feel free to reach out to us on , or .
Evidences from clipboard
Productivity tips series
If you have a screenshot on your clipboard, you can directly paste it into the file field to have it as evidence instead of going through an intermediate file as illustrated below:
SSO
Configure Single Sign-On with different SAML or OpenID Connect providers
Documented providers
Setting up Multi-Factor Authentication (MFA)
Multi-factor authentication adds an extra layer of security to your account by requiring both your password and a time-based code when you log in.
Prerequisites
A smartphone with an authenticator app installed
Okta
Configure Okta as an Identity Provider for CISO Assistant
Go into your Okta admin console (it should look like this: https://<your_url>.okta.com/admin/dashboard)
In the sidebar menu, click on Applications > Applications
Click now on Create App Integration
Context
This is the place to define the context for risk and compliance management. All items here are optional.
Threat
A threat is the potential cause of an incident that may result in a breach of information security or compromise business operations (ISO 27000). Threats are used to clarify the aim of a requirement or an applied control. They are informative, assessments can be realized without using them.
Threats can be imported from a library, but you can create your own threats in the global domain or in a specific domain.
Organization
You can find here CISO Assistant global organization. All entities will be linked to or contained within these objects.
A folder organization
For Access Control purpose, CISO Assistant data is organized in a tree of folders. Starting from a root folder called Global, it divide into sub-folders called domains. The organization of the tree is not hard-coded, it is entirely determined by configuration. Any object in CISO Assistant is attached to a folder (including folders), either directly or indirectly through a parent object that is attached to a folder.
Add and manage users
Under Organization, click on Users and then Add user:
Set up the email of the new user:
Once created, a new user doesn't have any permissions by default. Click edit and update the user groups:
If you are working on a single domain, or working on solo, you might just set `Global - Administrator`
Microsoft Entra ID
Configure Microsoft Entra ID as an Identity Provider for CISO Assistant
Go into your Azure portal home
Open the sidebar menu and click on Microsoft Entra ID
Risk
This is where risk analyses are managed, from definition to potential acceptance.
Risk assessment
You can create risk assessments in your perimeters. A risk assessment encompasses:
risk identification, when you define your risk scenarios
Google Workspace
Configure Google Workspace as an Identity Provider for CISO Assistant
Google Workspace doesn't allow callbacks to urls containing http or localhost so it can be tricky to test it locally. You should deploy CISO Assistant with a FQDN to bypass these restrictions.
Go into Google Workspace Admin console
Metrics
Expected outcome
define your metrics or import their definition
instantiate them on your domains
Governance
You will set here documents and items that are used as a basis for assessments.
Policy
A policy is a specific type of applied control that consist of a document describing what is expected from some parts of your stakeholders.
Putting your cybersecurity policies in CISO Assistant will make them readlily available for compliance assessments, and will allow you to manage their lifecycle.
Compliance
This is where you can carry out your compliance work based on the framework of your choice.
Framework
The fundamental object of CISO Assistant for compliance is the framework. It corresponds to a given standard, e.g. ISO27001:2022. They can be imported from the library. If you don't find a framework which fits your needs, no worries, you can build your own framework and add it to CISO Assistant!
Local
Basic setup for local deployment and experimentation
The recommended pattern for local deployment is to use Docker Compose. Check the Readme file on the CISO Assistant repo for the latest instructions.
The compose file will manage three containers and set the required variables:
Front
Prerequisites
Prerequisites to Install CISO Assistant On-Premises
Hardware Requirements:
Custom certificates
How to add custom certificates for your remote installation
You can configure your own Certificate by replacing the line tls internal in the docker-compose.yml by tls <cert_file> <key_file>. Here is Caddy documentation on this
Before doing this, there is just one step, you need to add the cert_file and the key_file inside caddy container.
You have basically two ways to do it:
Manage extended result
Minor nonconformity, Major nonconformity, etc.
This tutorial guides you through managing minor nonconformities and major audit results within your compliance assessments
Setting up S3
How to connect your S3 block storage for your installation
By default, CISO Assistant stores attachments on the local filesystem.
You can configure it to use an S3-compatible object storage (AWS S3, MinIO, etc.).
Prerequisitories
A running S3-compatible storage
Setting up mailer
Setup the following environment variables:
Note: Docker Compose Environment Variables
When using Docker Compose, avoid spaces around the = sign in environment variable definitions. Spaces cause variables to be silently ignored.
Correct:MY_VARIABLE=valueIncorrect:MY_VARIABLE = value
Changing the language
Switch the UI language
Bonus: By changing the application language, any framework that is translated to that language will switch automatically to it.
The list of supported languages is available here
Designing your own Libraries
NOTE: This section is still under reworking. For complementary informations, please refer to the .
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.
Keycloak
Configure Keycloak as an Identity Provider for CISO Assistant
If Keycloak and CISO Assistant are both deployed locally with docker, you'll need to make sure that both containers can communicate together. You can do this with a.
Go into your Keycloak admin console
User Groups
User groups are built-in objects giving permissions to all users inside of them, with a specific role across a scope.
For now, it is not possible to create custom role assignments so you need to use built-in user groups. They are linking a domain with a role which contains precise permissions, that will be given to users in this group.
Roles
Let's give some details on the 5 built-in roles:
Role
Permissions
Integration overview
CLI : basic automation and batch actions
n8n node: custom node for no-code / low-code automation leveraging the +1200 integration of n8n ecosystem
CIS Controls / Cloud Controls Matrix (CCM)
Importing CIS Controls or CSA CCM
NOTE: This section is still under reworking. For complementary informations, please refer to the or the.
Since CSA and CIS have more restrictive terms on their licenses, users need to perform an extra action by downloading the sheet on their side and running the preparation script as described in the tools folder.
To import the CIS Controls, you need to prepare the file first. The easy way, once you have python and the , is to copy the Excel sheet as-is (CIS_Controls_Version_8.xlsx) into the tools folder and run
01 - basic audit
Start your audit confidently with CISO Assistant by setting up your organization's domains and security perimeters. This guide helps you create an audit baseline aligned with ISO/IEC 27001:2022 and understand your organization's security context.
Generating a PAT
Personal Access Token to interact with the API
Learn how to generate a Personal Access Token (PAT) for CISO Assistant quickly and securely
Custom roles
For fine-grained permissions management - PRO feature
Learn how to create and customize roles such as DPO and OPS within your organization
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.
Domain export/import
Pro users (eg. consultants) can export a full domain with its affiliated objects
You can import it on Pro or Community edition on the domains list:
Understanding the IAM model
Deep dive into CISO Asisstant IAM model
Access security is a foundational aspect of any risk or compliance management platform. In this article, we’ll explore how authentication, authorization, and accounting — the three pillars of the AAA model — are structured and applied within CISO Assistant.
1. Authentication: SAML vs OIDC
CISO Assistant integrates with leading identity providers (IdPs) via SAML and OIDC, enabling secure and seamless single sign-on (SSO).
Deploy on a VPS
Virtual Private Server - Remote internet-facing VM
This setup aims to expose CISO Assistant on a VPS while using automated Let's Encrypt for certificates management.
provision your VPS and make sure it has a public reachable IP - make sure to have the mentioned on that page.
Setup your DNS zone to point to the IP of your VPS (A record). Give it sometime to propagate (depends on the registrar). It's better to start with this once you get the IP to give it enough time for propagation.
Remote/Virtualization
Experimenting CISO Assistant through remote server or hypervisor
New: Use the config builder at the config folder of the repo for an interactive and reliable experience.
To get started with the config builder, make sure you have python and docker installed. Here is an example on ubuntu:
Frequent questions
Stop and restart
docker compose down
docker compose up -d
Updating your local instance
How to update your local instance. All docker images are available on ghcr with the specific versions matching the repo tags. The latest tag points to the most recent release for both back and front.
Hands-free
The easiest way to update your on-prem/local instance (pro or community)
Run the script update-ciso-assistant:
Helm Chart
instructions for Kubernetes installation with Helm Chart
GH OCI registry
Getting the values
Special cases
Tips and tricks regarding specific cases
SELINUX
If you have selinux enabled on your distro, you might want to check if it's not preventing the mount volume of the docker compose; you can try something like this:
Upgrading a library
getting the incremental updates of your framework, matrix or catalog
In you've updated your instance and didn't see the changes on a loaded library, you can do the following to refresh the library to the latest version:
This also applies to custom framework as long as you respect the incremental step of the library's version.
New - Cyber Risk Quantification
CRQ quick start
This tutorial guides you through performing Cyber Risk Quantification using the CISO Assistant
Submit a library
How to submit a framework, matrix or catalog to the community repository
If you are familiar with Github and Git, the submission is pretty straightforward:
fork the git repo and make sure it's sync-ed up
add the excel sheet under the tools folder,
00 - initial setup
Start your journey with CISO Assistant by setting up your organization (domains, perimeters, and users) and then import some basic libraries to get started with compliance and risk assessment.
Translating the interface
You can contribute to interface translations using a tool called .
Copy the URL of the CISO Assistant GitHub repository:
Visit and paste the URL you just copied.
Jira
Overview
The Jira integration allows you to synchronize applied controls from CISO Assistant with issues in your Jira projects. This helps you track the implementation and status of your controls directly in Jira, leveraging your existing workflows.
When the integration is active, CISO Assistant will allow linking applied controls to Jira issues, or creating new issues when creating an applied control. Updates to the applied control in CISO Assistant will be reflected in the corresponding Jira issue, and vice-versa.
Two sync modes are available:
ServiceNow
ServiceNow Integration Guide
This guide details how to configure the bidirectional synchronization between CISO Assistant and ServiceNow. This integration allows you to:
Automatically create ServiceNow records (e.g. GRC Controls) from CISO Assistant.
Sync updates (Status, Priority, etc.) from CISO Assistant to ServiceNow.
API usage
Access the online documentation
Enable the documentation locally
Reference control
Reference controls are templates for applied controls. They facilitate the creation of an applied control, and help to have consistent applied controls. They are optional, but recommended.
Reference controls can be provided by security frameworks that are imported from a library, but you can create your own reference controls in the global domain or in a specific domain.
Applied control
Applied controls are fundamental objects for compliance and remediation. They can derive from a reference control, which provides better consistency, or be independent.
Applied controls are always defined by the entity and can be attached to the global domain or in a specific domain.
Asset
An asset refers to any piece of information that holds value to an organization. These assets can be digital or physical and encompass a wide range of data types, including customer records, financial information, intellectual property, employee records, proprietary software, marketing materials, and more.
Assets are always defined by the entity and can be attached to the global domain or in a specific domain.
There are two types of assets:
Primary assets are core resources directly contributing to an organization's main objectives, like machinery or intellectual property.
Support assets indirectly aid primary functions, such as IT systems or administrative services.
Risk matrix
To perform risk evaluation, CISO Assistant uses a risk matrix that calculates the risk level as a function of the probability and the impact of a scenario.
Risk matrices have to be imported from a library. Use either one provided by default, or define your own matrix with a custom library, as documented in our github repo.
Most often, entities define an official risk matrix that should be used for all risk assessments. But CISO Assistant let you choose your risk matrix for each assessment if you need to use several of them. However, it is not possible to change the risk matrix once the assessment is created.
Audit
This allows you to assess your compliance with the chosen framework through different statuses for each requirement that requires one of the following:
To do
In progress
Non compliant
Partially compliant
Compliant
Not applicable
Evaluate a requirement inside a compliance assessment is called requirement assessment
Evidence
Evidence allows you to use a description, link or file to justify the status of a compliance requirement or to prove that a control has been applied. They can therefore be associated with different applied controls or requirement assessments.
CPU: 4 cores
RAM: Minimum 8 GB
Storage: Minimum 10 GB (consider more for evidences)
You can start with lower specs of course for testing.
Software Requirements:
Ubuntu/Debian, CentOS, RHEL: LTS versions recommended when applicable*
Docker 27 or up, with Docker compose, or Kubernetes Cluster 1.29 or up
Postgres 16 or up if you are choosing this variant
Any SMTP compatible Mailer
*most Linux distributions supporting Docker should be compatible but have not been tested. Some distributions are not using the official repositories so make sure to follow the instructions from docker page.
Administrator
full access (except approval), and specifically management of domains, users and users rights
Domain manager
full access to selected domains (except approval), in particular managing rights for these domains. Read access to global objects
Analyst
read-write access to selected perimeters/domains. Read access to global and domain objects
Reader
read access to selected perimeters/domains
Approver
like reader, but with additional capability to approve risk acceptances
Django superuser is given administrator rights automatically on startup.
Global user groups
Once your instance is created, four user groups are already present:
Global - Administrator
Global - Analyst
Global - Reader
Global - Approver
They give corresponding permissions on Global scope so on every object of your instance.
Domain user groups
They are created for each domain you add. For example, if you create a domain R&D, there will be:
R&D - Domain Manager
R&D - Analyst
R&D - Reader
R&D - Approver
They give corresponding permissions on the domain scope so on every object inside R&D.
🔸 SAML
legacy protocol based on XML
common in large enterprises, especially for AD
browser-based redirection with signed assertions
🔸 OIDC (OpenID Connect)
modern standard built on OAuth2
uses JWT tokens for identity transport
also browser-based, but more lightweight and versatile
Recommendation: If your IdP supports both, prefer OIDC — it's more modern, flexible, and aligned with today’s security practices.
2. MFA
Multi-Factor Authentication (MFA) is critical for access protection. CISO Assistant supports MFA in two distinct modes, depending on how users authenticate:
🔸SSO-Based Authentication (SAML / federated OIDC)
MFA is handled entirely by the identity provider (IdP)
the IdP enforces the policy (push notifications, TOTP, biometrics, etc.)
🔸Local Authentication
for local accounts, CISO Assistant includes native MFA
based on TOTP (e.g., Google/Microsoft Authenticators)
3. Authorization: Structured and Hierarchical RBAC
CISO Assistant implements a robust Role-Based Access Control (RBAC) model that balances flexibility, clarity, and operational simplicity.
🔸 Fine-Grained Permissions
Each object type has granular CRUD permissions (create, read, update, delete). This model applies across all business entities: users, backups, risks, policies, incidents, data processing, and more. There are more than 200 permissions in CISO Assistant.
🔸 Predefined Roles
Permissions are grouped into a small set of standard roles:
Administrator – full access to all objects and settings
Analyst – full access to most objects, but cannot modify access control
Viewer – read-only access
Approver – strictly limited to approving risk acceptance requests
🔸 Hierarchical Domains
Roles are assigned within a domain — a flexible concept representing any relevant business context.
For example, a domain can represent:
a legal entity
a country or region
a subsidiary
a business unit
any other meaningful organizational structure
Domains are hierarchical: a role assigned to a parent domain (e.g., "Group") automatically applies to all its subdomains (e.g., subsidiaries, teams).
🔸 Role Assignments
Access control is defined via explicit assignments:
A role ➡️ on a domain ➡️ for a group of users
🔸 User Groups
Users do not have direct roles. They inherit permissions through membership in one or more groups.
Groups act as the central pivot for managing access:
receive role assignments
grant users permissions via group membership
defined locally
optionally synced with an IdP (via external plugin)
🚀 This simple yet powerful model accommodates the vast majority of real-world access scenarios. And when needed, the system is fully extensible: it supports custom roles, custom role assignments, and custom user groups to fit even the most specific organizational needs.
4. Machine Identity: Personal Access Tokens with Expiration & Control
CISO Assistant doesn’t just secure human access — it also supports secure, auditable access for automated systems and integrations through Personal Access Tokens (PATs).
🔸Definition
A Personal Access Token is a time-limited secret that allows a script, CI/CD pipeline, or service to authenticate with the platform's API on behalf of a user or machine identity — without requiring an interactive login.
🔸Key features
time-bounded: expiration is mandatory
RBAC-compliant: inherits the creator’s permissions
revocable: can be revoked by user or admin
🔸Governance controls
admins can restrict who may generate PATs
all tokens are auditable and managed via UI or API
This ensures tight control over non-human access, balancing automation flexibility with strict security hygiene.
5. Accounting: Full Audit and Traceability
CISO Assistant includes native tracking of all key actions:
a searchable audit log accessible via the UI or API
This enables complete accountability over critical operations.
🧠 In Summary
CISO Assistant's AAA model is built on:
Open standards (SAML, OIDC, TOTP, RBAC)
A structured yet manageable authorization system
secure automation through scoped, revocable Personal Access Tokens (PATs)
Built-in traceability from the ground up
It supports complex organizations while remaining readable, scalable, and compliant with modern security expectations.
Note on inheritance
Multiple objects of CISO Assistant support a built-in flag called is_published that controls wether an object is visible by affiliated domais ins. This flag is set by default tochildren'sd quite useful to be able to benefit children domains from some controls or evidence covered on their parent domains.
It's expected by Q2/26 to be able to control the behaviour of inheritance in a more fine-grained manner, such as preventing it or managing it between domains with no direct affiliation.
Afterwards, you can upload the generated yaml file as a custom library and load it.
Alternatively, you can run the prep script first (tools/cis/prep_cis.py) and mention any short string as the packager and then pass the new Excel sheet to the convert_library_v2.py
A domain permits to organize your work depending on your use of CISO Assistant. For example, inside a company, you can create a domain for each department for which you need to carry out a variety of perimeters, or if you have different customers, you may as well have a domain for each one in order to delimit your work area.
Utility
A domain is the first thing you create on CISO Assistant. It will bring together all objects you need to complete your different perimeters. Every role/permission a user has on a domain are applicable to all objects/actions across the domain. It's all about organization, the only technical aspect is access control, and this is achieved by adding the user to the relevant user group.
Role assignment
In the first/open source version of CISO Assistant, custom role assignment is not available. So, when you create a domain, user groups concerning this domain are automatically created for each built-in role. All you need to do, is to assign your users to their user groups. To learn more about this, jump to User Groups.
Perimeters
Perimeters are fundamental context objects defined by the entity using CISO Assistant. They are grouped in domains. They will contain all your risk and compliance assessments. Apart from being able to group your various evaluations across the different domains.
There are two specific fields, internal reference and status. Here are the various status options:
-- (None)
Design
Development
Production
End of life
Dropped
The purpose of a perimeter is at first, it's organizational aspect to solve a problem. But it also makes it possible to improve analytics by breaking them down according to the different assessments, whether for risk or compliance, so as to make your project management more precise and reduce noise.
User Groups
User groups go hand in hand with domains. they associate permissions with users and define their scope, by being attached to a domain. They follow a simple and consistent RBAC model from a role containing permissions and a domain determining the perimeter. Go to the User Groups page for more details.
Organization example
When the user are added, and if the mailer is set, he/she will receive an email to set up the password. If not, you can set a temporary password as illustrated above.
risk analysis, when you assess the probability, impact and strength of knowledge for each scenario
risk evaluation, which is done automatically based on the selected risk matrix
In CISO Assistant, risk treatment is combined with risk assessment.
Risk scenario
The scenarios can be defined directly from the risk assessment view or separately via this view.
Risk acceptance
Risk acceptance is when an organization or individual decides to tolerate a certain level of risk without taking further action to reduce it.
This view allows to manage a workflow to get formal approval of risk acceptances by the management.
The approver of a risk acceptance must have a user account with approver role.
To find out more about risk acceptance, you can have a look to the ENISA risk management process.
MCP: plug your agents and/or tools-capable LLM app for a chatting experience
Power BI: Expand and customize your data visualistions
Dispatcher: Listen to a kafka bus to trigger events
ITSM: Interact with your ITSM tool on incoming or outgoing events
Webhooks: wake up external system on events, with thin or full webhooks
chcon -Rt svirt_sandbox_file_t ./db
Back
Caddy (proxy)
Make sure to have a recent version of Docker installed
On a Linux distro with a server flavor, make sure to remove older versions and install the latest one using the proper Docker repos to avoid twisted setups. Check out the instructions at https://docs.docker.com/engine/install/ubuntu/
On Windows, Docker Desktop+WSL is recommended
On MacOS, Docker Desktop covers the requirements
Using prebuilt images
Run:
It will clean up previous images and get the latest stable release.
Once the images are downloaded and migration triggered, you should see a prompt asking you to set the first superuser. Follow the instructions to set it, and you should be ready.
In case you are running on an unsupported architecture, you can open a GitHub issue so that we add its support or use the next steps to build the images locally.
Re-building the images locally
Alternatively, if the previous configuration didn't succeed, run:
SSL Warning
Given that Caddy is using a self-signed certificate, your browser will mention a warning that you can accept and continue.
Adding the two files inside caddy_data directory, as it is already mounted by default in the volumes, and specify the path to the files:
If you don’t have this volume or you want to add another, create a repository at the same level of your docker compose file for example /certs, add the files inside and moun it:
Set the following environment variables in the backend environment:
That's it ! You can now launch your backend and your attachments will be sent to your S3 🔥
Example case : local MinIO block storage
You can test S3 support using MinIO:
Then go on http://localhost:9001 , enter your minio root user/password and create a bucket with the name 'my-ciso-bucket'.
The backend environment variables will be:
You can now see your attachments on the MinIO console after importing them in ciso-assistant.
Add automatically your local CA-certificate
An issue you may encounter when setting up your mailer is that your local CA certificates might not be included inside your Docker container. This could cause problems when sending emails.
To address this, we need to apply some modifications to the compose file in the backend and huey services:
Add a volume to mount the certificate (replace /your/ca-certificate/path/example_CA.crt by the path and the name of your ca-certificate):
Add a command through the entrypoint:
There's already an entrypoint for huey, you can modify it like this:
If you didn't get the prompt to create the first user, or lost the password but you still have access to the infra level, you can trigger the createsuperuser command to fix that.
In your compose file folder, try:
docker compose exec backend poetry run python manage.py createsuperuser
Alternatively, in a docker environment:
docker ps -a | grep backend (this will get you the id of the Backend for CISO Assistant container, keep it for the next step)
docker exec -it <the_container_id> poetry run python manage.py createsuperuser
and you should get a prompt now 😉
Lost the first user password
docker compose exec backend poetry run python manage.py changepassword <user_email>
You'll get a prompt to change the password
Random issues after upgrading
In some rare cases, the migration of database schemas can take longer than expected or fail silently. First thing to check is the backend container logs:
Make sure you share these information if you're reporting an issue on Discord or the Support portal.
If you want to trigger the migration to make sure that all increments have been properly applied:
Healthcheck fails during the installation
most likely because the initialization took longer than expected. Make sure you provide the expected specs or tune the docker compose to give the app more time to finish the init phase.
Don't want / Can't run the init script
The recommended pattern for a first local setup is to go with ./docker-compose.sh ;
In case you can't:
Run
wait for the init to finish and then trigger the first user creation manually:
"Payload too large" when uploading a file to the frontend
By default, the BODY_SIZE_LIMIT environment variable is set to 20 MB in the frontend Dockerfile:
In order to upload larger files, this value must be increased. How to do so depends on you rmode of deployment. Here are relevant docs:
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.
In case you are running it locally with a non reachable FQDN, you might want to consider adding tls internal on the Caddy config for self-signed certificate.
Choose the option 1 or 2 depending of your provider and fill Metadata URLor SSO URL, SLO URL, x509 certificate retrieved from your provider
Check that the SP Entity ID is similar to the Entity/Client ID specified on your provider
And that's it! Don't forget to save changes
You should now be able to see the Login with SSO button
Allow single label domains: This allows you to authenticate through SAML on a single-label domain (e.g. https://ciso-assistant:8443). If this is left unchecked, the only host forms allowed are:
IPv4
IPv6
FQDN (e.g. https://www.example.com/)
localhost
Access to your account settings on CISO Assistant
Enable MFA
Sign in to your account and navigate to 'My profile'
Select the 'Settings' button
Look for the Security section and click 'Enable 2FA'
Set up your authenticator app:
Open your authenticator app on your smartphone
Scan the QR code displayed on your screen
Alternatively, you can manually enter the provided secret code into your authenticator app
Enter the 6-digit verification code shown in your authenticator app
Click 'Enable 2FA' to complete the setup
Important: Save Your Recovery Codes
After enabling MFA, you'll receive a set of recovery codes. These codes are crucial for regaining access to your account if you:
Lose your phone
Uninstall your authenticator app
Cannot access your authenticator app for any reason
Security Warning:
Store your recovery codes in a secure location, separate from your password
Each recovery code can only be used once
Never share your recovery codes with anyone
Consider storing a copy both digitally (in a password manager) and physically (printed in a secure location)
Next Steps
Test your MFA setup by logging out and back in
Reach out for support if you encounter any issues during setup
Select SAML 2.0 and click on Next
Choose an App name and click on Next
Add the Single sign-onURL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/) (see screenshot below)
Add the Audience URI (SP Entity ID), it has to be the same than SP Entity ID in CISO Assistant (see screenshot below)
Choose Email as the Application username
Add Attribute Statements
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname for user's first name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname for user's last name
Click on Next and fill in the Feedback page as you wish then click on Finish
In the Settings box inside SAML 2.0:
Copy the Metadata URL and paste it into the Metadata URL field in CISO Assistant
Copy the Issuer url and paste it into theIdP Entity ID field in CISO Assistant
Go to the Assignments tab
Click on Assign and choose whether you want to assign users or specific groups
Add a user in your application doesn't automatically create the user on CISO Assistant
Enter a name and then click Integrate any other application you don’t find in the gallery (Non-gallery)
Click on Single sign-on from the sidebar menu or on Set up single sign on bellowGetting Started and choose SAML
In the first box Basic SAML Configuration, specify the Entity ID, it has to be the same than SP Entity IDin CISO Assistant (see next screenshot)
Add the Reply URL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/)
In the third box SAML Certificates, copy the App Federation Metadata Url as it is the Metadata URL in CISO Assistant (see next screenshot)
In the fourth box Set up <App_name>, copy the Microsoft Entra Identifier as it is the IdP Entity IDin CISO Assistant
Make sure you use the same Identifier (Entity ID) that you've set earlier and appear on block 1, on CISO Assistant SP Entity ID:
Click on Users and groups in the sidebar menu, and Add user/group to give them access to CISO Assistant with SSO. The matching key will be the email and you'll be able to grant their permissions on the applications.
Click the App registrations section to add a new application for OIDC configuration. You can also use the search bar if you don't find it in the suggestions.
3. Start New Application Registration
4. Name your application
5. Select Web Platform in Redirect URI options
6. Enter the callback URL of your instance
The callback URL is: <ciso_assistant_url>/api/accounts/oidc/openid_connect/login/callback/ for
for instance, for localhost: http://localhost:8000/api/accounts/oidc/openid_connect/login/callback/
7. Complete Application Registration
8. Copy the Application Client ID
9. Past it into the Client ID field
10. Open Certificates & Secrets
11. Create a New Client Secret
12. Add your Client Secret
13. Copy the fresh Client Secret Value
14. Past it into the Secret field
15. Go back to your App Overview
16. Inside Endpoints copy the OpenID Connect metadata URL
17. Paste it into the Server URL field
18. Save your configuration
You have successfully configured OpenID Connect (OIDC) integration with EntraID.
Adding a user in your Entra application doesn't automatically create the user on CISO Assistant
On the sidebar menu, go to Applications > Web and mobile applications
Click on Add an application > Add a custom SAML Application
Enter ciso-assistant or the name of your choice and click on continue
You can copy the SSO URL, Entity Id and x509 certificate here but you'll be able to retreive them later
Fill ACS URL with <base_url>/api/accounts/saml/0/acs/, enter the Entity IDwhich has to be the same than SP entity Id in CISO Assistant (ciso-assistant by default) and choose Email in Name ID Format
Add two mappings for First name and Last Name, fill them with those two values: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
On application home page, you can now find the Entity ID, SSO URL and x509 certificate
Add a user in your application doesn't automatically create the user on CISO Assistant
Consider metric definition as a template of your metric. It serves as the guideline of the actual metric instance that you will track accross your domains.
Importing definitions
1. Introduction
You will learn how to import off-the-shelf metrics definitions on CISO Assistant.
Introduction
2. Open Metric Definitions
Click "Metric definitions".
Open Metric Definitions
3. Click import
Click here to proceed to the next menu.
Click import
4. Import the library matching your criteria
You can also preview the content before importing it.
Import the library matching your criteria
5. Return to Metric Definitions
Click "Metric definitions" to revisit the main metrics page.
Return to Metric Definitions
6. Look for the metric definition you want
Click "Search..." to begin finding specific metrics.
Look for the metric definition you want
7. Select The Specific Metric
You can now instantiate this metric as you see fit for your domains.
Select The Specific Metric
You can now instantiate this metric as needed across your domains. Keep in mind that you can also create your own metric definition directly without going through the library.
Creating a definition
Metrics can be quantitative (number with unit) or qualitative (choices):
Quantitative metric
You can add your options during declaration or afterward:
Qualitative metric
The "higher is better" setting is used to indicate if the trend is a good thing or not.
Metric instance
The metric instance is the projection of the definition to a specific domain and it's what you'll be tracking.
Parameters:
Metric definition (it will inherit its settings)
Domain: the scope of this metric
Status: lifecycle of the metric. The stale is specially interesting as the application will auto-toggle it according to the data freshness
Collection frequency: expected collection frequency, on which we add a grace period before toggling the metric to stale status
Target value: expected target of this metric for this specific domain. This is handy as you can have different targets of the same metric definition according to the domain.
Assigned to: owner of the metric instance and its update.
Metric sample
This is the actual data of the metric instance on a given timestamp.
Keep in mind that you can add the data manually or through all the supported integrations (API, n8n, etc.). Note that data cannot be in the future.
Dashboards
Dashboards are the visual representation of the metrics and support:
custom metrics instance (multiple charts)
built-in metrics (multiple charts)
markdown text widget
In edit mode, you can add different widgets, place and resize them as you see fit:
Once done, you can go back to view mode to see the result:
In addition to the custom metrics for your internal KPI and KRI, you can also include some of the built-in metrics tracked by the platform:
Those are updated on each change of your data and tracked as daily metrics.
Go to your instance
1. Introduction
You will learn how to add extra attribute to your audit through extended result.
Introduction
2. Open your audit
Click "ISO 27002 SOA" to access the relevant compliance assessment for managing audit results.
Open ISO 27002 SOA Assessment
3. Enter Edit Mode
Click "Edit" to enable modifications on the selected compliance assessment.
Enter Edit Mode
4. Access More Options
Click "More" to reveal additional settings and options for the assessment.
Access More Options
5. Enable extended result
Click "on" to activate the desired feature or option within the assessment settings.
Enable Specific Setting
7. Save audit Changes
Click "Save" to apply and store the changes made to the compliance assessment.
Save Assessment Changes
10. Open a requirement
Click "4.1 - Understanding the organization and its context" to examine specific requirements.
Open Context Subsection
11. Choose the value for your extended result
Select the appropriate category such as major nonconformity, minor nonconformity, observation, opportunity for improvement, or good practice.
Choose Nonconformity Type
14. Make sure it's consistent with the audit result
Click the note stating "Major and minor nonconformities are only applicable when result is non-compliant or partially compliant." to understand criteria.
Review Nonconformity Applicability
17. Select the value and save
Click "Save" to store the additional nonconformity or observation details.
Save Additional Entry
21. Use the Observation field for more Information
Click "Save" to finalize and save the observation or nonconformity information entered.
Save Observation Information
You have successfully managed minor nonconformities and major audit results by editing, documenting, and saving relevant compliance assessment details. This ensures accurate tracking and supports effective audit management for your organization.
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:
1
Define the framework structure or use an existing one
Plan the structure and decide whether to start from scratch or reuse an existing framework.
2
Generate a base Excel file (v2 format)
Use the provided tooling to create a valid v2 Excel skeleton.
3
Fill in framework content
Populate the _content tabs with requirements.
4
Convert Excel to YAML
Use the conversion tool to generate a CISO Assistant-compatible YAML library.
5
Import the library into CISO Assistant
Upload and validate the generated YAML in CISO Assistant.
6
Maintain and update the library
Follow versioning and URN stability rules when updating.
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 dedicated README on GitHub 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 example_framework.xlsx.
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
How advanced fields (implementation groups, questions, answers, scoring) are represented
How real-world frameworks should be laid out in Excel
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
1
Open example_framework.xlsx in Excel or LibreOffice and explore the tabs and cell notes.
2
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
locale
ref_id
name
description
copyright
provider
packager
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
name
description
implementation_groups (if applicable)
questions / answers (if applicable)
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)
Annotations (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)
A category (policy, process, technical, physical, procedure) (optional)
An CSF function mapping (optional)
Annotations (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
Impact levels
Risk levels
The risk grid mapping probability × impact to risk
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 tools/excel/matrix.
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 /tools 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)
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.
Relationship type (equal, subset, superset, intersect)
Optional rationale and strength
2
Convert the Mapping to YAML
Once the Excel file is completed:
The conversion tool will:
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
1
Open CISO Assistant
2
In the left navigation menu, go to:
Governance → Libraries
3
Click on the button
4
Select your generated .yaml file
5
Confirm the upload
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
Invalid references to threats, controls, or IGs
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
Questions and answers
Scores and implementation groups
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.
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.
Choose SAML client type and name it ciso-assistant or with your customSP Entity ID
Fill the Home URL with your <base_url>and Valid redirect URIs with <backend_url/*>
If you have some problems to configure these urls you can ask for help on Discord or by emailing us
Go into Keys and disable Signing keys config
Go into Advanced and fill ACS field with <backend_url/api/accounts/saml/0/acs/> (on a cloud instance it is simply <base_url/api/accounts/saml/0/acs/>)
Go to Client scopes and click on ciso-assistant-dedicated
Add a predefined mapper and check all X500 ones
Click on X500 surname and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Click on X500 givenName and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Go into Realm settings > General, you will find the Metadata URL
You'll find inside the Metadata URL the Entity ID
Go into your Keycloak admin console
Open the sidebar menu > Clients and Create client
Choose OpenID Connect client type and give it a Client ID, then click Next
Enable Client authentication, make sure Standard flow is selected, then click Next
Enter your deployment's Root URL. It is the URL of your frontend.
Set it to <frontend_url>
For cloud deployments, you must set it to <base_url>
Set the Home URL to/
Enter your Valid redirect URIs
Set it to <backend_url>/api/accounts/oidc/openid_connect/login/callback/
For cloud deployments, you must set it to <base_url>/api/accounts/oidc/openid_connect/login/callback/
Once your client is created, you can find its Client secret under the Credentials tab. You can copy it from there
Go into Realm settings > General to find the OpenID Endpoint Configuration, which you will have to paste into CISO Assistant's Server URL SSO parameter
Adding a user in your application doesn't automatically create the user on CISO Assistant
Access the Organization settings to begin configuring your domain management.
Click 'Organization'
2. Click "Domains"
Navigate to the Domains section to manage your organization's domain details.
Click 'Domains'
3. Click here
Initiate the process to add a new domain by selecting the appropriate option.
Click here
4. Click here
Enter a descriptive name for your new domain to clearly identify it.
Click here
5. Fill "explainer"
Save the newly created domain to register it within your organization.
Fill 'explainer'
6. Click "Save"
Select the domain you just created to begin setting up its security perimeter.
Click 'Save'
8. Pick "explainer" domain
Start adding a new security perimeter to define the domain's protective scope.
Click 'explainer'
9. Click "Add perimeter"
Choose the option to specify the perimeter's characteristics and settings.
Click 'Add perimeter'
10. Click here
Provide a clear and concise name for the new security perimeter.
Click here
11. Fill "general"
Save the perimeter settings to apply them to the domain.
Fill 'general'
12. Click "Save"
Return to the General settings to prepare for audit creation.
Click 'Save'
13. Click "General"
Begin creating a new audit to assess your organization's security posture.
Click 'General'
14. Click "New Audit"
Select the option to add a new audit baseline for evaluation.
Click 'New Audit'
15. Click here
Name your audit baseline to reflect its purpose or scope.
Click here
16. Fill "my baseline"
Specify the audit type or category to align with your compliance goals.
Fill 'my baseline'
17. Click here
Choose the relevant standard or framework for your audit.
Click here
18. Search "iso"
Select the International standard ISO/IEC 27001:2022 to align with recognized security practices.
Fill 'iso'
19. Click "International standard ISO/IEC 27001:2022"
Confirm and save your audit configuration to proceed.
Click 'International standard ISO/IEC 27001:2022'
20. Click "Save"
Access the detailed audit sections to review specific requirements.
Click 'Save'
21. Open the tree structure
Select the section focused on the organization's context for information security.
Click here
23. Enter an item to review/update it
Ensure your Information Security Management System (ISMS) aligns with your organization's context by addressing these factors.
Click 'Identify internal and external factors that influence the organization’s ability to achieve information security objectives, ensuring the ISMS is aligned with its context.'
This guide walked you through setting up domains and security perimeters, creating an audit baseline, and aligning your ISMS with ISO/IEC 27001:2022 standards. You learned to identify organizational factors critical to achieving information security objectives.
This guide provides clear steps to create, name, set expiration, and copy your PAT for seamless integration.
Introduction
2. Click here
Access your account menu by selecting your profile icon in the application interface.
Click here
3. Click "My profile"
Navigate to the 'My Profile' section to manage your personal account settings.
Click 'My profile'
4. Click "Settings"
Open the 'Settings' tab within your profile to configure advanced options.
Click 'Settings'
5. Click "Generate new token"
Initiate the creation of a new Personal Access Token by selecting 'Generate new token'.
Click 'Generate new token'
6. Click here
Click the input field to name your token, providing a clear and descriptive label.
Click here
7. Fill "testing"
Enter a meaningful token name to help you identify its purpose later.
Fill 'testing'
8. Click "30"
Set the token's expiration by choosing a predefined duration from the available options.
Click '30'
9. Fill "90"
Alternatively, specify a custom expiration period to suit your security needs.
Fill '90'
10. Click "Generate new token"
Confirm the token generation by clicking the 'Generate new token' button.
Click 'Generate new token'
11. Click "Copy"
Securely copy the newly created token to your clipboard for immediate use.
Click 'Copy'
12. Click "Done"
Complete the process by clicking 'Done' to save your settings and exit the token creation workflow.
Click 'Done'
This guide walked you through generating a Personal Access Token for CISO Assistant. Make sure that you save it and use it using secure channels/tools and be cautious of its impact as it inherents your permissions on the app.
Once created, the value cannot be seen nor edited. You'll have to generate a new one to do so.
Sign in as an Admin on your CISO Assistant instance and follow the steps below.
1. Introduction
This guide walks you through setting permissions and assigning user groups to streamline your CISO Assistant's role management.
Introduction
2. Click "Organization"
Navigate to the Organization section to begin managing your team's roles.
Click 'Organization'
3. Click "Roles"
Access the Roles tab to view and modify existing roles.
Click 'Roles'
4. Click here
Initiate creating a new role by selecting the option to add one.
Click here
5. Fill "DPO"
Enter the name for the new role, such as 'DPO', to define its identity.
Fill 'DPO'
6. Click "Save"
Save the newly created role to confirm its addition to your organization.
Click 'Save'
7. Click here
Open the permissions settings for the new role to customize access.
Click here
8. Click here
Expand the permissions list to view all available options.
Click here
9. Click "Select all"
Select all permissions to grant comprehensive access to the role.
Click 'Select all'
10. Click "Save"
Save the permission settings to apply them to the role.
Click 'Save'
11. Click here
Start creating another role by selecting the add role option again.
Click here
12. Fill "OPS"
Name this role, for example 'OPS', to specify its function.
Fill 'OPS'
13. Click "Save"
Save the role to add it to your organization's role list.
Click 'Save'
14. Click here
Access the permissions for the newly created role to tailor its access.
Click here
15. Click here
Open the detailed permissions menu to adjust specific controls.
Click here
16. Click here
Select the option to edit applied controls for fine-tuning.
Click here
17. Click "Edit applied control"
Modify the applied control by entering a specific control number, such as '205'.
Click 'Edit applied control'
18. You can select an individual permission
Confirm the changes made to the applied control settings.
Fill '205'
19. Click here
View the applied control details to verify the configuration.
Click 'View applied control'
20. Click here
Update the applied control with another control number, like '207', if needed.
Fill '207'
21. Click here
Return to the permissions overview to continue adjustments.
Click here
22. Or you can click "Select all"
Select all permissions to ensure full access for the role.
Click 'Select all'
23. Click "Save"
Save all permission changes to finalize the role's capabilities.
Click 'Save'
24. Click "User groups" to see your newly added roles
Switch to the User Groups section to manage group memberships.
Click 'User groups'
26. Click "Users"
Navigate to the Users tab to assign roles to individuals.
Click 'Users'
27. Click here
Select a user to modify their group memberships and roles.
Click here
28. Click here
Open the user's group assignment settings to begin editing.
Click here
29. Fill "OPS"
Enter the role name, such as 'OPS', to assign it to the user.
Fill 'OPS'
30. Click "ACME - OPS"
Choose the corresponding user group, like 'ACME - OPS', for the role.
Click 'ACME - OPS'
31. Fill "DPO"
Input another role name, for example 'DPO', for additional assignments.
Fill 'DPO'
32. Click "Global - DPO"
Select the matching user group, such as 'Global - DPO', for this role.
Click 'Global - DPO'
33. Pick your user groups
Review all assigned user groups and roles to ensure accuracy.
34. Click "Save"
Save the user group and role assignments to complete the process.
Click 'Save'
This guide detailed how to create and configure custom roles like DPO and OPS, assign comprehensive permissions, and manage user group memberships effectively. It ensures your organization’s roles are tailored and users are properly assigned for optimal access control.
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.
Simpler security model - The AI client spawns the MCP server as a subprocess. No need for API keys between the client and MCP server, or dealing with CORS and network authentication.
Works offline - The MCP server itself runs locally. Only the actual CISO Assistant API calls require network access.
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
Navigate to the cli folder inside
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 Create Token
Give it a name (e.g., "MCP Integration")
Copy the token - you'll need it in the next step
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.
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
Find Integrations section
Click the Install button
Select Edit mcp.json
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 with the token from Step 1
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 \\
Restart Claude Desktop completely (quit, don't just close)
"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.
on the following I'm using ubuntu 24.04. So adjust the packages installation according to your OS
ssh to your server and perform the following commands:
Follow the instructions and make sure to do the following:
select VM/Remote
Internet facing and ACME ready - yes
Provide the FQDN you've set on your registrar
Port to use: 443
It should look like something like this:
Keep track of the URL mentioned at the end of the config generator. You can review the generated yml file and adapt it if needed.
Wait for the app to initialize and you will get a prompt to enter the first admin user and the password.
You can go back and update the docker-compose.yml according to your needs or restart the interactive guide to create a new one.
You can choose Traefik or BunkerWeb instead of Caddy using the config builder. Please note that BunkerWeb deployment is still experimental at the moment.
👉 Notes
The generated file in the config directory will be named docker-compose-custom.yml For subsequent operations with compose, you'll need to specify it with -f
If you're running docker compose without the -f, it could conflict with the default one on the repository root directory.
If you're starting a production environment:
make sure to disable the debug mode,
have your docker-compose-custom renamed and stored out of the repo,
You cannot use IP addresses on the configuration and you need to have a FQDN mapped to it.
If you aim to expose the VM to internet, use this dedicated guide: Deploy on a VPS
If you aim to connect from the VM
If you aim to connect to the VM from your network
From the VM
This means that you will be using a browser from within the VM so localhost settings are applicable. You can simply use the default ./docker-compose.sh at the root of the repository or trigger the config builder with the following settings:
run ./docker-compose.sh and connect from within the VM using https://localhost:8443
From your network / host OS
setup a FQDN for your VM and make sure it's known by the host you are connecting from. This will vary depending on your OS. For instance, for linux/mac, you can add a line to your /etc/hosts file such as:
192.168.1.87 ca.homelab.local
in this example, the first part is your VM's ip and the second one will be the FQDN you'll be providing to the config builder and that you will use to connect later on.
Run the config builder and provide the following settings:
run ./docker-compose.sh and connect from your host this time using https://ca.homelab.local:8443
Notes:
If you don't want to have a specific port, use the port 443 during the settings, given it's not used by another application on your system.
In the remote setup, if you also want to connect from within the VM, you can add your custom FQDN to the /etc/hosts of your VM but mapped to 127.0.0.1
---
Legacy - Kept for reference purposes
Let's say that you want to setup or experiment with CISO Assistant on a Network or Virtualized environment (eg. Hypervisor) on a remote host, for instance, to use with multiple users:
Install a recent version of Docker on your remote server
Given that we are using TLS with Caddy, we need to have DNS entries and not IPs
The workstations need to be able to reach the remote using an FQDN (DNS entry). If not you can add an entry on your /etc/hosts. Keep track of the remote server DNS as you'll put it on the next step, let's say the remote is cool-vm for instance
Clone the repo, but don't run anything yet. Edit the docker-compose.yml file as follows:
(red is for deletion and green for addition); your diff should look like:
Five lines need to be edited. Save the file and move to the next step
If you're getting SSL_ERROR_INTERNAL ERROR_ALERT (Can be different on other browsers) blocking you from continuing, make sure that you've made the 5 changes above.
The tls internal (equivalent to -i in CLI mode) parameter of Caddy can present some security issues and is not recommended for production and internet exposure. You should consider proper certificates for that.
You're all set, and you can simply run:
Your CISO Assistant can be reached now from https://cool-vm:8443, and you can skip the SSL warning for the self-signed certificate.
Go to your instance
1. Introduction
You will learn how to create and configure risk studies, define scenarios with associated assets and threats, apply treatments, run simulations, and analyze results to make informed cybersecurity decisions. Before starting, ensure you have access to the CISO Assistant platform and necessary permissions to create and edit risk studies.
Introduction
2. Click "Risk"
Click "Risk" to access the risk management section where you can start your cyber risk quantification process.
Click 'Risk'
3. Click "CRQ studies"
Click "CRQ studies" to view and manage your Cyber Risk Quantification studies.
Click 'CRQ studies'
4. Click here
Click here to create a new study for your risk analysis.
Click here
5. Fill the required fields of the study
Fill "a study" to name your new study, which helps identify it later.
Fill the required fields of the study
6. Choose a domain
Click "DEMO" to select the demo environment or dataset for your study.
Choose a domain
7. Click "Save"
Click "Save" to store your new study configuration.
Click 'Save'
8. Click "Add scenario"
Click "Add scenario" to define a new risk scenario within your study.
Click 'Add scenario'
9. Create your first scenario
Fill "first scenario" to name your initial risk scenario for clarity and tracking.
Create your first scenario
10. You can select an asset now or do it later
Click "DEMO/Ecommerce portal Primary" to assign the primary ecommerce portal asset to your scenario.
You can select an asset now or do it later
11. You can select a threat now or do it later
Click "DEMO/Ransomware" to specify ransomware as the threat type for this scenario.
You can select a threat now or do it later
12. Click "Save"
Click "Save" to save your scenario settings.
Click 'Save'
13. Click here
Click here to move to the next configuration section.
Click here
14. Select the existing controls that serve as a baseline
Click "Treatment" to define the risk treatment options for your scenario.
Select the existing controls that serve as a baseline
15. Click "Simulation Parameters"
Click "Simulation Parameters" to set parameters for your risk simulation.
Click 'Simulation Parameters'
16. Fill the probability of the current baseline
Fill "0.40" to set the probability or impact factor for the simulation.
Fill the probability of the current baseline
17. Setup your lower bound (best case scenario)
Click here to proceed to the next parameter.
Setup your lower bound (best case scenario)
18. and your upper bound (worst case scenario)
Fill "100000" to set the worst-case loss estimate for the scenario.
and your upper bound (worst case scenario)
19. Click "Save"
Click "Save" to apply your simulation parameters.
Click 'Save'
20. Click on the hypothesis and then Click "Run simulation"
Click "Run simulation" to start the risk quantification process based on your inputs.
Click on the hypothesis and then Click 'Run simulation'
21. You'll notice that your LEC chart has been generated as well as multiple risk insights
You can hove over the chart for a fine grained review
22. Click here to go back to the scenario
Click "first scenario" to select the scenario for which you want to view simulation results.
Click here to go back to the scenario
23. Let's create a new hypothesis
Click "New hypothesis" to create a what-if analysis for alternative risk treatments.
Let's create a new hypothesis
24. Click "Treatment"
Click "Treatment" to assign treatments to your new hypothesis.
Click 'Treatment'
25. and pick one of the controls you want to implement
Click "DEMO/Deploy EDR solution" to select the deployment of an Endpoint Detection and Response solution as a treatment.
and pick one of the controls you want to implement
26. Click "Simulation Parameters"
Click "Simulation Parameters" to adjust parameters for the hypothesis simulation.
Click 'Simulation Parameters'
27. update the simulation parameters of this hypothesis
based on your estimate of risk reduction with this treatment plan
update the simulation parameters of this hypothesis
28. Update the probability and/or the UB/LB
Fill "0.2" to set the updated probability or impact factor for the hypothesis.
Update the probability and/or the UB/LB
29. Click "Save"
Click "Save" to store your hypothesis simulation parameters.
Click 'Save'
30. Click "Run simulation"
Click "Run simulation" to execute the what-if analysis and compare results.
Click 'Run simulation'
31. Let's go back to the scenario to compare the two hypotheses
Click "first scenario" to return to the main scenario view.
Let's go back to the scenario to compare the two hypotheses
32. What if the ROSI is not calculated?
Click your control to jump to its details.
What if the ROSI is not calculated?
33. Click "Edit"
Click "Edit" to modify treatment or scenario settings as needed.
Click 'Edit'
34. Click "Cost"
Click "Cost" to enter the financial impact or cost associated with the treatment.
Click 'Cost'
35. Describe the Build and Run cost structure
Click here to open the cost input field.
Describe the Build and Run cost structure
36. Click "Save"
Click "Save" to apply your cost settings.
Click 'Save'
37. The ROSI will get refreshed when you access the scenario again
Accessing a residual hypothesis details section will show you the calculation of ROSI
38. What if I want a summary of all my scenarios and a portfolio overview
Click "Executive Summary" to view a high-level overview of your risk quantification results.
What if I want a summary of all my scenarios and a portfolio overview
39. You can go "Back to Study" anytime to refine the scenarios and hypotheses
Click "Back to Study" to return to detailed study configuration.
You can go 'Back to Study' anytime to refine the scenarios and hypotheses
40. What if I want to set a loss threshold
Click "Edit" to make further changes to your study settings.
What if I want to set a loss threshold
41. Click "Tolerance settings"
Click "Tolerance settings" to adjust risk tolerance thresholds for your analysis.
Click 'Tolerance settings'
42. Click here
Click here to open tolerance input fields.
Click here
43. Click "Save"
Click "Save" to confirm your tolerance settings.
Click 'Save'
44. Tip: click "Retrigger All Simulations" to refresh all simulations and insights
Click "Retrigger All Simulations" to rerun simulations with updated parameters and settings.
Tip: click 'Retrigger All Simulations' to refresh all simulations and insights
45. Don't forget to use this to go to the parent object
From a hypothesis to its parent scenario, or from a scenario to its parent study
Don't forget to use this to go to the parent object
You have successfully completed a Cyber Risk Quantification study using the CISO Assistant. By defining scenarios, assigning assets and threats, configuring treatments, and running simulations, you can now analyze potential risks and their financial impacts. To verify success, review the Executive Summary and ensure simulations reflect your updated parameters. Next, consider exploring advanced hypothesis testing or adjusting tolerance settings to refine your risk management strategy.
This guide walks you through configuring essential security frameworks and risk matrices to establish a robust compliance foundation.
Introduction
2. Click "Organization"
Navigate to the Organization section to begin configuring your company settings.
Click 'Organization'
3. Click "Domains"
Access the Domains tab to manage your organization's domain information.
Click 'Domains'
4. Click here
Initiate adding a new domain by clicking the add button.
Click here
5. Click here
Open the domain creation form to input new domain details. Markdown is supported for the description.
Click here
6. Fill "ACME" (or any relevant domain name)
Enter your organization's domain name to register it within the system.
Fill 'ACME' (or any relevant domain name)
7. Click "Save"
Confirm and save the new domain to apply changes.
Click 'Save'
8. Click "ACME"
Select the newly created domain to configure its specific settings.
Click 'ACME'
9. Click "Add perimeter"
Start adding a security perimeter to define access boundaries for the domain.
Click 'Add perimeter'
10. Click here
Open the perimeter creation interface to specify perimeter details.
Click here
11. Fill "Common"
Name the new perimeter to identify it clearly within your domain.
Fill 'Common'
12. Click "Save"
Save the perimeter settings to establish the defined boundary.
Click 'Save'
13. Click "Users"
Go to the Users section to manage user accounts and permissions.
Click 'Users'
14. Click here
Begin adding a new user by selecting the add user option.
Click here
15. Click here
Open the user creation form to input user details.
Click here
16. Fill "alice@company.com"
Enter the user's email address to create their account.
Fill 'alice@company.com'
17. Click "Save"
Save the new user profile to register them in the system.
Click 'Save'
18. Click "alice@company.com"
Select the newly added user to modify their settings.
Click 'alice@company.com'
19. Click "Edit"
Access the edit mode to update user roles and permissions.
Click 'Edit'
20. Click here
Open the role assignment dropdown to select user roles.
Click here
21. Click "ACME - Analyst"
Choose the appropriate role for the user within the organization.
Click 'ACME - Analyst'
22. Click "Save"
Save the updated user role to apply changes.
Click 'Save'
23. Click "Catalog"
Navigate to the Catalog section to explore available frameworks and resources.
Click 'Catalog'
24. Click "Frameworks"
Access the Frameworks tab to browse compliance and security frameworks.
Click 'Frameworks'
25. Click here
Open the framework search interface to find specific standards.
Click here
26. Click "Search..."
Use the search bar to locate a framework by name or keyword.
Click 'Search...'
27. Fill "iso 27"
Enter the ISO 27001 framework to find relevant compliance information.
Fill 'iso 27'
28. Click here
Select the ISO 27001 framework from the search results to view details.
Click here
29. Fill "nist csf"
Open the NIST CSF framework details for review and mapping.
Fill 'nist csf'
30. Click here
Use the search function to find specific frameworks or resources.
Click here
31. Click "nist csf"
Access the Risk Matrices section to manage risk assessment tools.
Click 'nist csf'
32. Fill "Search..."
Open the risk matrix search to locate specific matrices.
Fill 'Search...'
33. Click "Risk matrices"
Search for critical risk matrices to prioritize high-impact risks.
Click 'Risk matrices'
34. Click here
Select the critical risk matrix to analyze and manage risks.
Click here
35. Click "Search..."
Navigate to the Mappings section to link frameworks and risk matrices.
Click 'Search...'
36. Fill "critic"
Access the Risk Matrices tab within Mappings to review associations.
Fill 'critic'
37. Click here
Switch to the Frameworks tab to manage framework mappings.
Click here
38. Click "Risk matrices"
Review the filtered entries to find specific standards and mappings.
Click 'Risk matrices'
39. Click "Frameworks"
Examine the details of the ISO/IEC 27001:2022 standard for information security compliance.
Click 'Frameworks'
This guide covered setting up your organization in CISO Assistant, including domain and perimeter creation, user management, role assignments, and exploring compliance frameworks and risk matrices. It also detailed how to map frameworks to risk matrices for comprehensive security management.
Incoming sync (pull): Relies on webhooks to reflect changes made on a Jira issue to its linked applied control
Outgoing sync (push): Pushes changes made on an applied control to its linked Jira issue through the Jira REST API
You can enable one or both of these modes.
Prerequisites
A CISO Assistant instance.
A Jira Cloud service account with administrative privileges to create API tokens, outgoing webhooks and manage projects.
Alignement between the jira status options (on your board) and CISO Assistant options for status. They are case-sensitive for now.
Outgoing sync
Configuration
To configure the integration, you will need to perform steps on both the Jira and CISO Assistant sides.
1. Configure Jira
Create a Jira API Token
Log in to your Jira account.
Go to your Atlassian account settings: click on your profile picture in the bottom left, then "Profile". In the new page, click on "Manage your account".
In your Atlassian account page, navigate to Security > API token.
Click on Create and manage API tokens.
Click Create API token.
Give your token a descriptive label, for example, "CISO Assistant Integration".
Copy the generated API token. You will not be able to see it again. Store it in a safe place. You will need it to configure CISO Assistant.
Identify your Jira Project Key
In Jira, go to the project you want to integrate with CISO Assistant.
The project key is a short identifier for your project (e.g., 'PROJ', 'CIS'). You can find it in the project details or in the URL.
2. Configure CISO Assistant
Log in to your CISO Assistant instance.
Navigate to the integrations settings page. Find the Jira integration section.
Configure outgoing sync:
Enter the following information:
Jira URL: The URL of your Jira instance (e.g., https://your-company.atlassian.net).
Jira Username/Email: The email address you use to log in to Jira.
Incoming sync
This is only useful if you wish to enable incoming sync on CISO Assistant. Incoming sync requires outgoing ones.
Log in to your Jira account
Go to System settings > WebHooks
Click the + Create WebHook button on the top-right corner
You might need to filter the associated JQL to only send events on you specific project.
Webhook secret: The webhook secret you have generated when configuring your outgoing webhook on Jira.
URL: This is the URL where CISO Assistant will receive incoming webhooks from Jira. It is of the following form: <API_URL/api/integrations/webhook/<INTEGRATION_CONFIG_ID>/ . You can find your webhook URL on the bottom of CISO Assistant's Jira integration settings, located in Extra > Settings > Integrations > Jira
Save the configuration
Once the integration is configured and enabled, CISO Assistant will start synchronizing applied controls with Jira issues.
For each applied control, a new issue will be created in the configured Jira project if you check 'Create remote object' in the applied control creation form.
The Jira issue will contain information from the applied control, such as its name, description, and status.
A link to the Jira issue will be displayed on the applied control page in CISO Assistant.
The synchronization is automatic. Any update on an applied control in CISO Assistant will be reflected in the corresponding Jira issue.
Attaching an applied control to a Jira issue
There are several ways to link an applied control to a Jira issue:
On applied control creation:
Open the Integrations dropdown menu located at the bottom of the form
Select the Jira integration provider
Check the Create remote object checkbox.
This will create a Jira issue on the board specified in CISO Assistant's Jira integration settings. This issue will then be linked to the applied control.
On an existing applied control:
Go to an applied control's edit form
Open the Integrations dropdown menu located at the bottom of the form
Select the Jira integration provider
Select the Jira issue you wish to link to your applied control.
Outgoing sync (Push)
Creating an applied control
Updating an applied control
Incoming sync (Pull)
jira:issue_created
jira:issue_update
jira:issue_deleted
Notes:
The default sync period on SaaS is at 60 seconds.
The API needs to be enabled and the instance reachable. If you're on SaaS plan, you can reach the support to do so.
For on-premises deployments, you might want to adapt scheduler-interval value on Huey
Receive real-time updates from ServiceNow back into CISO Assistant via Webhooks.
For now, you are only able to sync CISO Assistant's applied controls to a ServiceNow table.
Prerequisites
Before starting, ensure you have:
ServiceNow Credentials: A service account with permissions to read/write to your target table (e.g., grc_control) and access the REST API.
ServiceNow Admin Access: Required to create Outbound REST Messages and Business Rules for the inbound sync.
CISO Assistant Details:
Your Instance URL.
The Webhook Secret generated in your Integration Configuration panel.
Part 1: Outgoing Sync
First, configure CISO Assistant to connect to your ServiceNow instance.
Create Integration:
Go to Settings > Integrations.
Add a new ServiceNow integration.
Connection Details:
Instance URL: Enter your full instance URL (e.g., https://dev12345.service-now.com).
Username/Password: Enter the credentials for the service account.
Discovery & Mapping:
Target Table: Select the ServiceNow table you want to sync with (e.g., Control [grc_control]).
Field Mapping: Map CISO Assistant fields (Name, Description, Status) to the corresponding ServiceNow columns.
Save
Part 2: Incoming Sync
If you with to receive updates from ServiceNow, you first have to enable incoming sync in the ServiceNow integration settings panel.
Configure incoming sync in CISO Assistant
Generate a shared secret.
This secret is only shown once, make sure you Copy it before proceeding.
Configure ServiceNow
To receive updates from ServiceNow, you must configure a Business Rule that pushes data to CISO Assistant.
Create the Outbound REST Message
This defines where ServiceNow sends the data.
Log in to ServiceNow.
Navigate to System Web Services > Outbound > REST Message.
Click New.
Configure the message:
Name:CISO_Assistant_Sync
Endpoint: Paste your Webhook URL from Part 1.
Click Submit.
Crucial: Re-open the record and note the API Name field (e.g., x_12345_ciso_assistant_sync or just CISO_Assistant_Sync). You will need this for the script.
Configure the HTTP Method
In the REST Message record, scroll to the HTTP Methods list.
Create a New method (or edit the default one):
Name:POST_Event
HTTP Method:POST
Endpoint: Paste your Webhook URL again.
Add Authentication Header:
Scroll to HTTP Request Headers.
Add a new row:
Click Submit.
Create the Business Rule
This triggers the sync whenever a record changes.
Navigate to System Definition > Business Rules.
Click New.
Name:Push to CISO Assistant.
Table: Select the same table you chose in Part 1 (e.g., Control).
Advanced: Check this box.
When to run:
When:After
Insert: Checked.
Advanced (Script): Paste the following code.
Replace 'CISO_Assistant_Sync' in line 4 with the API Name you noted in Step 2.1.
Click Submit.
Usage
Once the integration is configured and enabled, CISO Assistant will start synchronizing applied controls with ServiceNow records.
For each applied control, a new record will be created in the configured ServiceNow table if you check 'Create remote object' in the applied control creation form.
The ServiceNow record will contain information from the applied control, such as its name, description, and status.
A link to the ServiceNow record will be displayed on the applied control page in CISO Assistant.
The synchronization is automatic. Any update on an applied control in CISO Assistant will be reflected in the corresponding ServiceNow record.
Attaching an applied control to a ServiceNow record
There are several ways to link an applied control to a ServiceNow record:
On applied control creation:
Open the Integrations dropdown menu located at the bottom of the form
Select the ServiceNow integration provider
Check the Create remote object checkbox.
This will create a ServiceNow record on the board specified in CISO Assistant's ServiceNow integration settings. This record will then be linked to the applied control.
On an existing applied control:
Go to an applied control's edit form
Open the Integrations dropdown menu located at the bottom of the form
Select the ServiceNow integration provider
Select the ServiceNow record you wish to link to your applied control.
Notes:
The default sync period on SaaS is at 60 seconds.
The API needs to be enabled and the instance reachable. If you're on SaaS plan, you can reach the support to do so.
For on-premises deployments, you might want to adapt scheduler-interval value on Huey
Verification & Troubleshooting
How to Verify
Create a new Control in CISO Assistant. Check ServiceNow to see if the record appears.
Update the State of that record in ServiceNow. Refresh CISO Assistant to see the status change.
Common Errors
Symptom
Cause
Solution
HTTP 401/403 in ServiceNow Logs
Secret Mismatch
Ensure the X-CISO-Secret header in ServiceNow matches the Webhook Secret in CISO Assistant exactly.
"RESTMessageV2 is not defined"
Scope Issue
Ensure the script uses the correct API Name for the REST Message (e.g., x_scope_ciso_sync).
CISO Assistant doesn't update
Missing Filter
Check the Business Rule filter conditions. Ensure the change you made (e.g., just changing a description) is covered by the filter.
Dropdowns empty in Setup
Permissions
Ensure the service account has read access to sys_db_object and sys_dictionary.
Enable debug mode
Start the backend server (make sure that dependencies are installed):
Use this token to form your Authorization header, it needs to be as follows:
Authorization: Token <your_token>
Then you can use with any rest client or within your application or script:
Example with Bruno (Postman alternative)
Or with curl:
Notes
make sure to add the trailing slash '/'
your endpoint is your instance URL. If the proxy settings are the default ones, it will be the same url but with /api/ (in which case you don't need to add it)
Pro SaaS users need to open a support request to expose the API on their instance. It's disabled by default.
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
git clone https://github.com/intuitem/ciso-assistant-community.git
cd ciso-assistant-community/cli
cd /path/to/ciso-assistant-community/cli
cp .mcp.env.example .mcp.env
# Your Personal Access Token from Step 1
TOKEN=your-token-here
# Your CISO Assistant API URL
API_URL=http://localhost:8000/api
# Set to "true" if using HTTPS with a valid certificate
# Set to "false" for local development or self-signed certs
VERIFY_CERTIFICATE=false
Jira API Token: The API token you created in the previous step.
Jira Project Key: The key of the Jira project you want to synchronize with.
Note that the configuration object must exist for you to see the webhook endpoint URL. If you do not see it at the bottom of the page, finish filling the settings form and press Save. It will then appear.
Tick the issue created, updated, deleted events. Other events are not tracked.
You can test the connection to your ServiceNow instance by pressing the Test Connection button
Value Mapping: For "Choice" fields like Status and Priority, map your local values (e.g., In Progress) to the specific ServiceNow logic (e.g., 2 - Work in Progress).
Authentication:
No Authentication
(we will use a header token).
Name:X-CISO-Secret
Value: Paste your Webhook Secret from Part 1.
Add a second row:
Name:Content-Type
Value:application/json
Update: Checked.
Filter Conditions: (Recommended) Add conditions to reduce noise, e.g., State changes OR Priority changes.
Navigate to App Registrations
Start New Application Registration
Name your application
Select Web Platform in Redirect URI options
Enter the callback URL of your instance
Complete Application Registration
Copy the Application Client ID
Past it into the Client ID field
Open Certificates & Secrets
Create a New Client Secret
Add your Client Secret
Copy the fresh Client Secret Value
Past it into the Secret field
Go back to your App Overview
Inside Endpoints copy the OpenID Connect metadata URL
Paste it into the Server URL field
Save your configuration
Convert mapping to YAML
python convert_library_v2.py mapping.xlsx
Third-party integrations
Integrate CISO Assistant with third-party providers
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.
Decoupling concept - full screen is recommended for a better experience
How to create a perimeter
illustration of implementation groups
How to create a risk assessment
How to create a compliance assessment
CI/CD Gates: Trigger a build pipeline scan when a specific policy is updated.
appliedcontrol.deleted
Assets:
asset.created
asset.updated
asset.deleted
Why choose this: This is the most secure method. It ensures that the receiving system has the correct permissions to view the data and guarantees you are always processing the latest version of the object.
Full Payloads (Recommended for Simplicity):
What it sends: The complete JSON representation of the object at the time of the event.
How to process: Use the data directly from the POST body.
Why choose this: Reduces integration effort by removing the need for a callback API request. Ideal for simple notifications (e.g., Slack alerts).
).
Select Payload Type: Choose "Full" or "Thin" based on your security requirements.
Save & Copy Secret: Copy the whsec_... secret immediately. You will need this for your consumer.
Develop: Write your consumer code (see examples below).
: The payload data (varies by "Thin" or "Full").
: Unix timestamp of the send attempt.
webhook-signature: The signature string, e.g., v1,BmX...
Calculate the HMAC-SHA256 of this string using your whsec_... secret.
Compare your calculated signature with the one provided in the header.
Retry Schedule: If delivery fails, we will retry approximately 5 times over a 15-minute window with exponential backoff.
Message Loss: If the endpoint is still unreachable after the final retry, the message is discarded. We currently do not provide a UI to replay failed messages manually.
import hmac
import hashlib
import base64
import time
def verify_webhook(request, secret):
# 1. Get Headers
msg_id = request.headers.get("webhook-id")
msg_timestamp = request.headers.get("webhook-timestamp")
signature_header = request.headers.get("webhook-signature")
if not (msg_id and msg_timestamp and signature_header):
raise ValueError("Missing webhook headers")
# 2. Verify Timestamp (Replay Protection)
# Reject if older than 5 minutes
now = int(time.time())
if now - int(msg_timestamp) > 300:
raise ValueError("Message timestamp too old")
# 3. Construct Signed Content
# IMPORTANT: Use the raw bytes of the request body
body = request.body.decode("utf-8")
to_sign = f"{msg_id}.{msg_timestamp}.{body}"
# 4. Calculate Expected Signature
# The header format is "v1,signature_hash"
# We only support v1 (HMAC-SHA256) for now
secret_bytes = secret.encode("utf-8")
to_sign_bytes = to_sign.encode("utf-8")
digest = hmac.new(secret_bytes, to_sign_bytes, hashlib.sha256).digest()
calculated_signature = base64.b64encode(digest).decode()
# 5. Compare Securely
# Extract the hash from "v1,..."
provided_signature = signature_header.split(",")[1]
if not hmac.compare_digest(calculated_signature, provided_signature):
raise ValueError("Invalid signature")
return True
