arrow-left

Only this pageAll pages
gitbookPowered by GitBook
1 of 80

CISO Assistant

Loading...

Guide

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Features focus

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Model

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Deployment

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Customization

Loading...

Loading...

Loading...

Contributing

Loading...

Loading...

Loading...

CA Journeys

Loading...

Loading...

Loading...

Integration

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Understanding decoupling

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

Internationalization

How to contribute to CISO Assistant internationalization

  • Translating the libraries (in-coming)

Translating the interface

Translating the interface

You can contribute to interface translations using a tool called finkarrow-up-right.

  1. Copy the URL of the CISO Assistant GitHub repository: https://github.com/intuitem/ciso-assistant-communityarrow-up-right

  2. Visit finkarrow-up-right and paste the URL you just copied.

  3. Sign in using your GitHub account.

  4. Click the 'fork' button at the bottom of the page. You may need to refresh the page to start contributing.

  5. Select the language(s) you wish to translate, or add new ones.

  6. Edit translations.

  7. When you are done, you can press the button at the bottom of the page to push the changes you made.

  8. When your translations are ready, on .

Read for more information.

submit a pull requestarrow-up-right
https://github.com/intuitem/ciso-assistant-communityarrow-up-right
fink's user guidearrow-up-right

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.

  • 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.


hashtag
Prerequisites

Before starting, ensure you have:

  1. ServiceNow Credentials: A service account with permissions to read/write to your target table (e.g., grc_control) and access the REST API.

  2. ServiceNow Admin Access: Required to create Outbound REST Messages and Business Rules for the inbound sync.

  3. CISO Assistant Details:


hashtag
Part 1: Outgoing Sync

First, configure CISO Assistant to connect to your ServiceNow instance.

  1. Create Integration:

    • Go to Settings > Integrations.

    • Add a new ServiceNow integration.


hashtag
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.

hashtag
Configure incoming sync in CISO Assistant

  1. Generate a shared secret.

  2. This secret is only shown once, make sure you Copy it before proceeding.

hashtag
Configure ServiceNow

To receive updates from ServiceNow, you must configure a Business Rule that pushes data to CISO Assistant.

hashtag
Create the Outbound REST Message

This defines where ServiceNow sends the data.

  1. Log in to ServiceNow.

  2. Navigate to System Web Services > Outbound > REST Message.

  3. Click New.

hashtag
Configure the HTTP Method

  1. In the REST Message record, scroll to the HTTP Methods list.

  2. Create a New method (or edit the default one):

    • Name: POST_Event

hashtag
Create the Business Rule

This triggers the sync whenever a record changes.

  1. Navigate to System Definition > Business Rules.

  2. Click New.

  3. Name: Push to CISO Assistant.

circle-exclamation

Replace 'CISO_Assistant_Sync' in line 4 with the API Name you noted in Step 2.1.

Click Submit.


hashtag
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.

hashtag
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

  • 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

hashtag
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

hashtag
Verification & Troubleshooting

hashtag
How to Verify

  1. Create a new Control in CISO Assistant. Check ServiceNow to see if the record appears.

  2. Update the State of that record in ServiceNow. Refresh CISO Assistant to see the status change.

hashtag
Common Errors

  • Your Instance URL.

  • The Webhook Secret generated in your Integration Configuration panel.

  • 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.

    • You can test the connection to your ServiceNow instance by pressing the Test Connection button

  • 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.

    • 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).

  • Save

  • Configure the message:

    • Name: CISO_Assistant_Sync

    • Endpoint: Paste your Webhook URL from Part 1.

    • Authentication: No Authentication (we will use a header token).

  • 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.

  • HTTP Method: POST

  • Endpoint: Paste your Webhook URL again.

  • Add Authentication Header:

    • Scroll to HTTP Request Headers.

    • Add a new row:

      • Name: X-CISO-Secret

      • Value: Paste your Webhook Secret from Part 1.

    • Add a second row:

      • Name: Content-Type

      • Value: application/json

  • Click Submit.

  • Table: Select the same table you chose in Part 1 (e.g., Control).

  • Advanced: Check this box.

  • When to run:

    • When: After

    • Insert: Checked.

    • Update: Checked.

    • Filter Conditions: (Recommended) Add conditions to reduce noise, e.g., State changes OR Priority changes.

  • Advanced (Script): Paste the following code.

  • 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.

  • Select the ServiceNow integration provider

  • Select the ServiceNow record you wish to link to your applied control.

  • 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.

    (function executeRule(current, previous) {
    
        try {
            // Initialize REST Message ('API Name', 'Method Name')
            // REPLACE 'CISO_Assistant_Sync' with your actual API Name if different!
            var r = new sn_ws.RESTMessageV2('CISO_Assistant_Sync', 'POST_Event');
    
            // Determine Event Type
            var eventType = 'sn_update';
            if (current.operation() == 'insert') {
                eventType = 'sn_create';
            } else if (current.operation() == 'delete') {
                eventType = 'sn_delete';
            }
    
            // Build Payload (Mapping raw database values)
            var payload = {
                "event": eventType,
                "sys_id": current.getValue("sys_id"),
                "number": current.getValue("number"),
                "short_description": current.getValue("short_description"),
                "description": current.getValue("description"),
                "state": current.getValue("state"),
                "priority": current.getValue("priority"),
                "due_date": current.getValue("due_date"),
                "sys_updated_on": current.getValue("sys_updated_on")
            };
    
            // Send Request
            r.setRequestBody(JSON.stringify(payload));
            var response = r.execute();
            
            // Log Errors
            var httpStatus = response.getStatusCode();
            if (httpStatus < 200 || httpStatus >= 300) {
                gs.error("CISO Sync Failed: " + httpStatus + " " + response.getBody());
            }
    
        } catch (ex) {
            gs.error("CISO Sync Error: " + ex.message);
        }
    
    })(current, previous);

    General tips

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

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

    1. Map your organisation to the domains/perimeters (or create basic ones)

    2. Add your users and assign them to the groups (SSO and MFA available even in Community)

    3. (recommended) Identify what are the assets to protect

    4. (recommended) Enumerate your existing capabilities/controls

    5. Define your baseline and focus on the basics - pick your controls and/or create new ones

    6. Get your actions implemented and reflect that on your audit progress

    7. Conduct a contextual risk assessment

    8. Share the insights with your organisation, review the priorities, and keep it alive

    9. Expand your coverage: periodic tasks, incidents, TPRM, findings managements, etc.

    10. Always keep focus on the actions and reflect their data on the other concepts

    Installation

    Docker Compose or Helm for Kubernetes

    hashtag
    New! Config Builder

    Customize the local deployment according to your needs:

    circle-exclamation

    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.

    hashtag
    Docker compose

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

    • clone the repo:

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

    • run the preparation script and follow the instructions:

    ./docker-compose.sh

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

    hashtag
    Helm chart

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

    1. add the helm repository

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

    1. get the default values

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

    1. check and adjust them to your needs, specifically the frontendOrigin parameter

    2. create a namesapce for your deployment

    kubectl create ns ciso-assistant

    1. install

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

    circle-info

    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.

    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.

    hashtag
    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)

    hashtag
    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.

    hashtag
    About the SaaS and PRO plan

    hashtag
    Quick links

    hashtag

    hashtag
    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.

    hashtag

    hashtag
    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

    1. Firstly, we need to import some external objects before starting our risk assessment: a matrix, threats and reference controls.

    2. We can create the risk assessment, and let's take a look inside.

    3. We find three parts: details about the assessment, the list of associated risk scenarios and the risk matrix view.

    4. Let's add the first scenario and do the current assessment of it.

    circle-exclamation

    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.

    1. 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.

    2. 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.

    circle-info

    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 πŸ”Ž

    Creating your first perimeter

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

    circle-exclamation

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

    1. Once logged in, the first step is to create a domain. Let's call it R&D.

    2. Then we create the perimeter inside of it or from the perimeter list view.

    circle-check

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

    Remote/Virtualization
    Deploy on a VPS
    full articlearrow-up-right
    🌐 External resources
    πŸ—οΈCreating your first perimeterchevron-right
    πŸ“ŠCreating your first risk assessmentchevron-right
    βœ…Creating your first Auditchevron-right
    🧰Extra toolschevron-right
    πŸ“Organizationchevron-right
    βš™οΈContextchevron-right
    πŸ›οΈGovernancechevron-right
    πŸ’£Riskchevron-right
    πŸ“‹Compliancechevron-right
    Risk analysis introductionarrow-up-right
    Society of Risk Analysisarrow-up-right

    Creating your first Audit

    Small tutorial to learn how to create your first compliance assessment

    1. After creating the perimeter, we'll have to import a framework, for example ISO/IEC 27001:2022.

    2. Once it is imported, we can now create the compliance assessment (ISO/IEC 27001:2022 is auto-selected as it is the only imported framework).

    3. You can edit it if needed, or go directly into the assessment. Each requirement has a To do status by default.

    4. 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.

    circle-check

    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

    Overview

    Manage your assessments over time

    hashtag
    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.

    circle-info

    Applied controls ranking score table is here to help you prioritize

    hashtag
    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.

    circle-info

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

    hashtag
    Calendar

    circle-exclamation

    Calendar page has been moved to the "Operations" section

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

  • 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

  • Extra tools
    Focus on watch list
    Select targets
    Composer

    Data import wizard

    Guidelines on data import format

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

    hashtag
    Overview

    If the object supports the domain column, the wizard will attempt to add the object to it, given you have the permission to do so. If the domain is not set, the wizard will default to the fallback domain set on 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.

    hashtag
    πŸ“¦ Assets

    hashtag
    Template

    hashtag
    Supported fields

    • ref_id

    • name*

    • description

    • domain

    hashtag
    Special considerations

    • type will default to supporting if the column does not exist

    hashtag
    βš™οΈ Applied controls

    hashtag
    Template

    hashtag
    Supported fields

    • ref_id

    • name*

    • description

    • domain

    hashtag
    Special considerations

    • status will default to to_do

    • csf_function will default to govern

    hashtag
    πŸ“¦ Perimeters

    hashtag
    Template

    hashtag
    Supported fields

    • ref_id

    • name*

    • description

    • domain

    hashtag
    πŸ“ƒ Audits

    hashtag
    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.

    hashtag
    Supported fields

    • urn*

    • assessable

    • ref_id*

    • name

    hashtag
    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

    hashtag
    🐞 Findings followup (eg. pentest)

    hashtag
    Template

    hashtag
    Supported fields

    • ref_id

    • name*

    • description

    • severity

    hashtag
    πŸ‘₯ Users

    hashtag
    Template

    hashtag
    Supported fields

    • email*

    • first_name

    • last_name

    hashtag
    ☣️ 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

    hashtag
    βš™οΈ 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*

    hashtag
    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.

    hashtag
    Threats

    • ref_id

    • name

    • description

    • domain

    hashtag
    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"

    hashtag
    Supported fields

    *: Required fields

    hashtag
    Entities

    • ref_id

    • name *

    • description

    hashtag
    Solutions

    • ref_id

    • name *

    • description

    hashtag
    Contracts

    • ref_id

    • name *

    • description

    hashtag
    Processings

    hashtag
    Template

    hashtag
    Supported fields

    • internal_id

    • ref_id

    • name*

    • description

    hashtag
    Policies

    hashtag
    Supported fields

    • ref_id

    • name

    • description

    • domain

    hashtag
    Exceptions

    hashtag
    Supported fields

    • ref_id

    • name

    • description

    • domain

    hashtag
    Incidents

    hashtag
    Supported fields

    • ref_id

    • name

    • description

    • domain

    External resources

    Community supported content

    hashtag
    Live sessions

    LinkedIn

    hashtag
    Youtube

    hashtag
    # Social medias

    hashtag
    Users reviews

    hashtag
    Blogs

    Understand mapping

    Main concepts of the mapping feature

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

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

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

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

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

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

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

    type

    • PR : primary

    • SP : supporting

    status

    • to_do

    • in_progress

    • on_hold

    • active

    • deprecated

  • category

    • policy

    • process

    • technical

    • physical

    • procedure

  • priority

    • integer from 1 to 4

  • csf_function

    • govern

    • identify

    • protect

    • detect

    • respond

    • recover

  • status

    • undefined

    • in_design

    • in_dev

    • in_prod

    • eol

    • dropped

    description

  • compliance_result

    • not_assessed

    • partially_compliant

    • non_compliant

    • compliant

    • not_applicable

  • requirement_progress

    • to_do

    • in_progress

    • in_review

    • done

  • score

    • integer from 0 to 100

  • observations

  • Unassessable rows are skipped.
  • low

  • medium

  • high

  • critical

  • status*

    • identified

    • confirmed

    • dismissed

    • assigned

    • in_progress

    • mitigated

    • resolved

    • deprecated

  • filtering_labels

  • inherent_proba

  • existing_controls

  • current_impact

  • current_proba

  • additional_controls

  • residual_impact

  • residual_proba

  • treatment

    • open, mitigate, accept, avoid, transfer

  • (in English)

    • know

    • enter

    • discover

    • exploit

  • (in French)

    • connaitre

    • entrer

  • icon

    • server

    • computer

    • cloud

    • file

    • diamond

    • phone

    • cube

    • blocks

    • shapes

    • network

    • database

    • key

    • search

    • carrot

    • money

    • skull

    • globe

    • usb

  • domain

  • function

  • domain

  • mission

  • country (Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2arrow-up-right)

  • currency (ISO 4217 format https://en.wikipedia.org/wiki/ISO_4217arrow-up-right)

  • parent_entity_id

  • dependency(Integer in [0,4])

  • penetration (Integer in [0,4])

  • maturity (Integer in [1,4])

  • trust (Interger in [1,4])

  • domain *

  • provider_entity_ref_id *

  • criticality (Integer in [1,4])

  • provider_entity_ref_id

  • solution_ref_id

  • status can be draft , active,expired or terminated

  • start_date (YYY-MM-DD format https://en.wikipedia.org/wiki/ISO_8601arrow-up-right)

  • end_date (YYY-MM-DD format https://en.wikipedia.org/wiki/ISO_8601arrow-up-right)

  • annual_expense

  • currency (ISO 4217 format https://en.wikipedia.org/wiki/ISO_4217arrow-up-right)

  • domain

  • lei

  • euid

  • vat

  • duns

  • status

    • Approved

    • Draft

    • In review

    • Deprecated

  • processing_nature

  • domain

  • assigned_to

  • labels

  • dpia_required

    • FALSE

    • TRUE

  • dpia_reference

  • status

  • link

  • status

    • draft, in_review, approved, resolved, expired, deprecated

  • severity

    • undefined, info, low, medium, high, critical

  • expiration_date

    • YYYY-MM-DD

  • observation

  • status

    • new, ongoing, resolved, closed, dismissed

  • severity

    • critical/sev1(1), major/sev2(2), moderate/sev3(3), minor/sev4(4), low/sev5(5), unknown(6)

  • detection

    • internal/internally_detected, external/externally_detected

  • reported_at

    • DateTime

  • file-download
    9KB
    sample001.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    sample002.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    sample003.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    sample004.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    sample005.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    risk_assessment_template.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    sample007.xlsx
    arrow-up-right-from-squareOpen
    file-download
    6KB
    sample_reference_controls.xlsx
    arrow-up-right-from-squareOpen
    file-download
    5KB
    sample_threats.xlsx
    arrow-up-right-from-squareOpen
    file-download
    11KB
    third_parties_ecosystem_template.xlsx
    arrow-up-right-from-squareOpen
    file-download
    6KB
    sample-processings.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    policies_template.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    exceptions_template.xlsx
    arrow-up-right-from-squareOpen
    file-download
    9KB
    incidents_template.xlsx
    arrow-up-right-from-squareOpen
    https://www.linkedin.com/posts/nathan-lemaire-cyber_ciso-assistant-guide-pas-%C3%A0-pas-activity-7282010527881433088-r_Lgarrow-up-right
    https://www.linkedin.com/posts/activity-7193144709987401729-oZW1arrow-up-right
    Blog Quercylibrearrow-up-right

    Extra tools

    Some useful tools for following up assessments

    hashtag
    X-rays

    circle-exclamation

    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

    hashtag
    Scoring Assistant

    circle-exclamation

    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.

    hashtag
    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.

    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:

    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)

    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:

    Flash mode

    Establishing a security posture in flashcards mode

    Library upgrade

    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.

    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.

    Mapping explorer

    The graph explorer helps you understand and navigate the cross walks between the frameworks.

    trouver
  • exploiter

  • 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.

    OWASP Risk Rating Methodologyarrow-up-right
    glossary
    data modelarrow-up-right
    Compliance assessment x-rays
    Risk assessment x-rays
    Score assistant

    SAML

    triangle-exclamation

    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.

    hashtag
    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.

    1. Log in into CISO Assistant as an administrator > Extra > Settings

    circle-exclamation

    Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.

    SSO

    Configure Single Sign-On with different SAML or OpenID Connect providers

    hashtag
    Documented providers

    • Microsoft Entra ID

    OpenID Connect (OIDC)

    hashtag
    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.

    1. Log in into CISO Assistant as an administrator > Extra > Settings

    2. Navigate to SSO settings

    3. Enable SSO

    4. Select the OpenID Connect provider

    5. Enter the Client ID

    6. Enter the Client secret

    7. Enter the Server URL

    8. And that's it! Don't forget to click the 'Save' button

    9. You should now be able to see the Login with SSO button

    circle-exclamation

    Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.

    Okta
    Keycloak
    Google Workspace

    Identity providers

    circle-check

    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 Discordarrow-up-right, or contribute to the docsarrow-up-right.

  • Enable SSO

  • Enter the Idp Entity ID

  • Choose the option 1 or 2 depending of your provider and fill Metadata URL or 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

    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)

    1. In the sidebar menu, click on Applications > Applications

    2. Click now on Create App Integration

    3. Select SAML 2.0 and click on Next

    4. Choose an App name and click on Next

    5. Add the Single sign-on URL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/) (see screenshot below)

    6. Add the Audience URI (SP Entity ID), it has to be the same than SP Entity ID in CISO Assistant (see screenshot below)

    7. Choose Email as the Application username

    8. 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

    9. Click on Next and fill in the Feedback page as you wish then click on Finish

    10. 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 the IdP Entity ID

    11. Go to the Assignments tab

    12. Click on Assign and choose whether you want to assign users or specific groups

    circle-exclamation

    Add a user in your application doesn't automatically create the user on CISO Assistant

    You can now with the 3 parameters you've retrieved.

    Google Workspace

    Configure Google Workspace as an Identity Provider for CISO Assistant

    triangle-exclamation

    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

    1. On the sidebar menu, go to Applications > Web and mobile applications

    2. Click on Add an application > Add a custom SAML Application

    3. Enter ciso-assistant or the name of your choice and click on continue

    4. You can copy the SSO URL, Entity Id and x509 certificate here but you'll be able to retreive them later

    5. Fill ACS URL with <base_url>/api/accounts/saml/0/acs/, enter the Entity ID which has to be the same than SP entity Id in CISO Assistant (ciso-assistant by default) and choose Email in Name ID Format

    6. 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

    7. On application home page, you can now find the Entity ID, SSO URL and x509 certificate

    circle-exclamation

    Add a user in your application doesn't automatically create the user on CISO Assistant

    You can now with the 3 parameters you've retrieved.

    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.

    hashtag
    Prerequisites

    • A smartphone with an authenticator app installed

    • Access to your account settings on CISO Assistant

    hashtag
    Enable MFA

    1. Sign in to your account and navigate to 'My profile'

    1. Select the 'Settings' button

    2. Look for the Security section and click 'Enable 2FA'

    3. Set up your authenticator app:

    hashtag
    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

    circle-exclamation

    Security Warning:

    • Store your recovery codes in a secure location, separate from your password

    hashtag
    Next Steps

    • Test your MFA setup by logging out and back in

    • Reach out for support if you encounter any issues during setup

    Keycloak

    Configure Keycloak as an Identity Provider for CISO Assistant

    triangle-exclamation

    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 bridge networkarrow-up-right.

    Go into your Keycloak admin console

    1. Open the sidebar menu > Clients and Create client

    2. Choose SAML client type and name it ciso-assistant or with your custom SP Entity ID

    3. 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 or by emailing us

    4. Go into Keys and disable Signing keys config

    5. 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/>)

    6. Go to Client scopes and click on ciso-assistant-dedicated

    7. Add a predefined mapper and check all X500 ones

    8. Click on X500 surname and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

    9. Click on X500 givenName and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

    10. Go into Realm settings > General, you will find the Metadata URL

    11. You'll find inside the Metadata URL the Entity ID

    Go into your Keycloak admin console

    1. Open the sidebar menu > Clients and Create client

    2. Choose OpenID Connect client type and give it a Client ID, then click Next

    circle-exclamation

    Adding a user in your application doesn't automatically create the user on CISO Assistant

    You can now with the parameters you've retrieved.

    Microsoft Entra ID

    Configure Microsoft Entra ID as an Identity Provider for CISO Assistant

    Go into your Azure portal home

    1. Open the sidebar menu and click on Microsoft Entra ID

    2. Click on Add button > Entreprise application

    3. Click on Create your own application

    4. Enter a name and then click Integrate any other application you don’t find in the gallery (Non-gallery)

    5. Click on Single sign-on from the sidebar menu or on Set up single sign on bellow Getting Started and choose SAML

    6. In the first box Basic SAML Configuration, specify the Entity ID, it has to be the same than SP Entity ID in CISO Assistant (see next screenshot)

    7. Add the Reply URL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/)

    8. In the third box SAML Certificates, copy the App Federation Metadata Url as it is the Metadata URL in CISO Assistant (see next screenshot)

    9. In the fourth box Set up <App_name>, copy the Microsoft Entra Identifier as it is the IdP Entity ID in CISO Assistant

    10. 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:

    11. 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.

    12. You can now with the 3 parameters you've retrieved.

    hashtag
    1. Introduction

    Go to your Microsoft Azure Portal

    hashtag
    2. Navigate to App Registrations

    circle-exclamation

    Adding a user in your Entra application doesn't automatically create the user on CISO Assistant

    configure CISO Assistantarrow-up-right
    field in CISO Assistant

    configure CISO Assistantarrow-up-right
    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

  • 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)

  • 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.

    1. Set it to <frontend_url>

    2. For cloud deployments, you must set it to <base_url>

  • Set the Home URL to /

  • Enter your Valid redirect URIs

    1. Set it to <backend_url>/api/accounts/oidc/openid_connect/login/callback/

    2. 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

  • Discordarrow-up-right
    configure CISO Assistantarrow-up-right
    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.
    Navigate to App Registrations

    hashtag
    3. Start New Application Registration

    Start New Application Registration

    hashtag
    4. Name your application

    Name your application

    hashtag
    5. Select Web Platform in Redirect URI options

    Select Web Platform in Redirect URI options

    hashtag
    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/

    Enter the callback URL of your instance

    hashtag
    7. Complete Application Registration

    Complete Application Registration

    hashtag
    8. Copy the Application Client ID

    Copy the Application Client ID

    hashtag
    9. Past it into the Client ID field

    Past it into the Client ID field

    hashtag
    10. Open Certificates & Secrets

    Open Certificates & Secrets

    hashtag
    11. Create a New Client Secret

    Create a New Client Secret

    hashtag
    12. Add your Client Secret

    Add your Client Secret

    hashtag
    13. Copy the fresh Client Secret Value

    Copy the fresh Client Secret Value

    hashtag
    14. Past it into the Secret field

    Past it into the Secret field

    hashtag
    15. Go back to your App Overview

    Go back to your App Overview

    hashtag
    16. Inside Endpoints copy the OpenID Connect metadata URL

    Inside Endpoints copy the OpenID Connect metadata URL

    hashtag
    17. Paste it into the Server URL field

    Paste it into the Server URL field

    hashtag
    18. Save your configuration

    Save your configuration
    circle-check

    You have successfully configured OpenID Connect (OIDC) integration with EntraID.

    configure CISO Assistant
    Introduction

    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.


    hashtag
    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).

    hashtag
    πŸ”Έ SAML

    • legacy protocol based on XML

    • common in large enterprises, especially for AD

    • browser-based redirection with signed assertions

    hashtag
    πŸ”Έ 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.


    hashtag
    2. MFA

    Multi-Factor Authentication (MFA) is critical for access protection. CISO Assistant supports MFA in two distinct modes, depending on how users authenticate:

    hashtag
    πŸ”Έ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.)

    hashtag
    πŸ”ΈLocal Authentication

    • for local accounts, CISO Assistant includes native MFA

    • based on TOTP (e.g., Google/Microsoft Authenticators)


    hashtag
    3. Authorization: Structured and Hierarchical RBAC

    CISO Assistant implements a robust Role-Based Access Control (RBAC) model that balances flexibility, clarity, and operational simplicity.

    hashtag
    πŸ”Έ 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.

    hashtag
    πŸ”Έ 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

    hashtag
    πŸ”Έ 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

    Domains are hierarchical: a role assigned to a parent domain (e.g., "Group") automatically applies to all its subdomains (e.g., subsidiaries, teams).

    hashtag
    πŸ”Έ Role Assignments

    Access control is defined via explicit assignments:

    A role ➑️ on a domain ➑️ for a group of users

    hashtag
    πŸ”Έ 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.


    hashtag
    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).

    hashtag
    πŸ”Έ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.

    hashtag
    πŸ”ΈKey features

    • time-bounded: expiration is mandatory

    • RBAC-compliant: inherits the creator’s permissions

    • revocable: can be revoked by user or admin

    hashtag
    πŸ”Έ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.

    hashtag
    5. Accounting: Full Audit and Traceability

    CISO Assistant includes native tracking of all key actions:

    • logins, restorations, configuration changes, approvals…

    • a searchable audit log accessible via the UI or API

    This enables complete accountability over critical operations.

    hashtag
    🧠 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)

    It supports complex organizations while remaining readable, scalable, and compliant with modern security expectations.

    hashtag
    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.

    Metrics

    hashtag
    Expected outcome

    • define your metrics or import their definition

    • instantiate them on your domains

    • feed data to your metric instances

    • create dashboards with builtin and custom metrics

    hashtag
    Key concepts


    hashtag
    Metric definitions

    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.

    hashtag
    Importing definitions

    hashtag
    1. Introduction

    You will learn how to import off-the-shelf metrics definitions on CISO Assistant.

    hashtag
    2. Open Metric Definitions

    Click "Metric definitions".

    hashtag
    3. Click import

    Click here to proceed to the next menu.

    hashtag
    4. Import the library matching your criteria

    You can also preview the content before importing it.

    hashtag
    5. Return to Metric Definitions

    Click "Metric definitions" to revisit the main metrics page.

    hashtag
    6. Look for the metric definition you want

    Click "Search..." to begin finding specific metrics.

    hashtag
    7. Select The Specific Metric

    You can now instantiate this metric as you see fit for your domains.

    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.

    hashtag
    Creating a definition

    Metrics can be quantitative (number with unit) or qualitative (choices):

    You can add your options during declaration or afterward:

    The "higher is better" setting is used to indicate if the trend is a good thing or not.


    hashtag
    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

    hashtag
    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.

    hashtag
    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.

    Custom roles

    For fine-grained permissions management - PRO feature

    hashtag
    Custom roles for CISO Assistantarrow-up-right

    Learn how to create and customize roles such as DPO and OPS within your organization

    hashtag
    Sign in as an Admin on your CISO Assistant instance and follow the steps below.

    hashtag
    1. Introduction

    This guide walks you through setting permissions and assigning user groups to streamline your CISO Assistant's role management.

    hashtag
    2. Click "Organization"

    Navigate to the Organization section to begin managing your team's roles.

    hashtag
    3. Click "Roles"

    Access the Roles tab to view and modify existing roles.

    hashtag
    4. Click here

    Initiate creating a new role by selecting the option to add one.

    hashtag
    5. Fill "DPO"

    Enter the name for the new role, such as 'DPO', to define its identity.

    hashtag
    6. Click "Save"

    Save the newly created role to confirm its addition to your organization.

    hashtag
    7. Click here

    Open the permissions settings for the new role to customize access.

    hashtag
    8. Click here

    Expand the permissions list to view all available options.

    hashtag
    9. Click "Select all"

    Select all permissions to grant comprehensive access to the role.

    hashtag
    10. Click "Save"

    Save the permission settings to apply them to the role.

    hashtag
    11. Click here

    Start creating another role by selecting the add role option again.

    hashtag
    12. Fill "OPS"

    Name this role, for example 'OPS', to specify its function.

    hashtag
    13. Click "Save"

    Save the role to add it to your organization's role list.

    hashtag
    14. Click here

    Access the permissions for the newly created role to tailor its access.

    hashtag
    15. Click here

    Open the detailed permissions menu to adjust specific controls.

    hashtag
    16. Click here

    Select the option to edit applied controls for fine-tuning.

    hashtag
    17. Click "Edit applied control"

    Modify the applied control by entering a specific control number, such as '205'.

    hashtag
    18. You can select an individual permission

    Confirm the changes made to the applied control settings.

    hashtag
    19. Click here

    View the applied control details to verify the configuration.

    hashtag
    20. Click here

    Update the applied control with another control number, like '207', if needed.

    hashtag
    21. Click here

    Return to the permissions overview to continue adjustments.

    hashtag
    22. Or you can click "Select all"

    Select all permissions to ensure full access for the role.

    hashtag
    23. Click "Save"

    Save all permission changes to finalize the role's capabilities.

    hashtag
    24. Click "User groups" to see your newly added roles

    Switch to the User Groups section to manage group memberships.

    hashtag
    26. Click "Users"

    Navigate to the Users tab to assign roles to individuals.

    hashtag
    27. Click here

    Select a user to modify their group memberships and roles.

    hashtag
    28. Click here

    Open the user's group assignment settings to begin editing.

    hashtag
    29. Fill "OPS"

    Enter the role name, such as 'OPS', to assign it to the user.

    hashtag
    30. Click "ACME - OPS"

    Choose the corresponding user group, like 'ACME - OPS', for the role.

    hashtag
    31. Fill "DPO"

    Input another role name, for example 'DPO', for additional assignments.

    hashtag
    32. Click "Global - DPO"

    Select the matching user group, such as 'Global - DPO', for this role.

    hashtag
    33. Pick your user groups

    Review all assigned user groups and roles to ensure accuracy.

    hashtag
    34. Click "Save"

    Save the user group and role assignments to complete the process.

    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.

    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.

    hashtag
    Roles

    Let's give some details on the 5 built-in roles:

    Role
    Permissions
    circle-info

    Django superuser is given administrator rights automatically on startup.

    hashtag
    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.

    hashtag
    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.

    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`

    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.

    Organization

    You can find here CISO Assistant global organization. All entities will be linked to or contained within these objects.

    hashtag
    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.

    Organization example

    hashtag
    So, what is a domain?

    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.

    hashtag
    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.

    hashtag
    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 .

    hashtag
    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

    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.

    hashtag
    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 page for more details.

    Approver – strictly limited to approving risk acceptance requests
    a business unit
  • any other meaningful organizational structure

  • Built-in traceability from the ground up

    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

    End of life

  • Dropped

  • User Groups
    User Groups
    folder organization

    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.

    Context

    This is the place to define the context for risk and compliance management. All items here are optional.

    hashtag
    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.

    hashtag
    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.

    hashtag
    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.

    hashtag
    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.

    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.

  • Introduction
    Open Metric Definitions
    Click import
    Import the library matching your criteria
    Return to Metric Definitions
    Look for the metric definition you want
    Select The Specific Metric
    Quantitative metric
    Qualitative metric
    Introduction
    Click 'Organization'
    Click 'Roles'
    Click here
    Fill 'DPO'
    Click 'Save'
    Click here
    Click here
    Click 'Select all'
    Click 'Save'
    Click here
    Fill 'OPS'
    Click 'Save'
    Click here
    Click here
    Click here
    Click 'Edit applied control'
    Fill '205'
    Click 'View applied control'
    Fill '207'
    Click here
    Click 'Select all'
    Click 'Save'
    Click 'User groups'
    Click 'Users'
    Click here
    Click here
    Fill 'OPS'
    Click 'ACME - OPS'
    Fill 'DPO'
    Click 'Global - DPO'
    Click 'Save'

    Risk

    This is where risk analyses are managed, from definition to potential acceptance.

    ISO 27005 risk management workflow

    hashtag
    Risk assessment

    You can create risk assessments in your perimeters. A risk assessment encompasses:

    • risk identification, when you define your risk scenarios

    • 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.

    hashtag
    Risk scenario

    The scenarios can be defined directly from the risk assessment view or separately via this view.

    hashtag
    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 .

    Compliance

    This is where you can carry out your compliance work based on the framework of your choice.

    hashtag
    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!

    hashtag
    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

    circle-info

    Evaluate a requirement inside a compliance assessment is called requirement assessment

    hashtag
    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 or requirement assessments.

    Manage extended result

    Minor nonconformity, Major nonconformity, etc.

    hashtag
    Manage Minor Nonconformities And Audit Results Efficientlyarrow-up-right

    This tutorial guides you through managing minor nonconformities and major audit results within your compliance assessments

    hashtag
    Go to your instance

    hashtag
    1. Introduction

    You will learn how to add extra attribute to your audit through extended result.

    hashtag
    2. Open your audit

    Click "ISO 27002 SOA" to access the relevant compliance assessment for managing audit results.

    hashtag
    3. Enter Edit Mode

    Click "Edit" to enable modifications on the selected compliance assessment.

    hashtag
    4. Access More Options

    Click "More" to reveal additional settings and options for the assessment.

    hashtag
    5. Enable extended result

    Click "on" to activate the desired feature or option within the assessment settings.

    hashtag
    7. Save audit Changes

    Click "Save" to apply and store the changes made to the compliance assessment.

    hashtag
    10. Open a requirement

    Click "4.1 - Understanding the organization and its context" to examine specific requirements.

    hashtag
    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.

    hashtag
    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.

    hashtag
    17. Select the value and save

    Click "Save" to store the additional nonconformity or observation details.

    hashtag
    21. Use the Observation field for more Information

    Click "Save" to finalize and save the observation or nonconformity information entered.

    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.

    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.

    1. provision your VPS and make sure it has a public reachable IP - make sure to have the Prerequisites mentioned on that page.

    2. 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.

    3. on the following I'm using ubuntu 24.04. So adjust the packages installation according to your OS

    4. ssh to your server and perform the following commands:

    1. 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

    It should look like something like this:

    1. 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.

    hashtag
    πŸ‘‰ 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:

    hashtag
    Clean up

    Governance

    You will set here documents and items that are used as a basis for assessments.

    hashtag
    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.

    Prerequisites

    hashtag
    Prerequisites to Install CISO Assistant On-Premises

    1. Hardware Requirements:

    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:

    hashtag
    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.

    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.

    1. Software Requirements:

      1. Ubuntu/Debian, CentOS, RHEL: LTS versions recommended when applicable*

      2. Docker 27 or up, with Docker compose, or Kubernetes Cluster 1.29 or up

      3. Postgres 16 or up if you are choosing this variant

      4. 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.

    Compliant

  • Not applicable

  • applied controlsarrow-up-right
    ENISA risk management processarrow-up-right
    Port to use: 443
  • make sure to disable the debug mode,

  • have your docker-compose-custom renamed and stored out of the repo,

  • have your db folder outside of the repo.

  • #update ubuntu repository and OS
    sudo apt update
    sudo apt upgrade 
    
    # install docker
    sudo snap install docker
    
    #install python
    sudo apt install python3-pip python3.12-venv
    
    #clone the repo
    git clone https://github.com/intuitem/ciso-assistant-community.git
    
    #go to the config generator
    cd ciso-assistant-community
    cd config
    
    # setting up the python project and dependencies 
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    
    # run the interactive config generator
    python make_config.py
    # switch to sudo. This can be avoided depending on your docker setup
    sudo su 
    ./docker-compose.sh
    cd config
    # stop and remove containers
    docker compose -f docker-compose-custom.yml rm -fs
    # delete the db and proxy config
    git clean -fdx .
    Introduction
    Open ISO 27002 SOA Assessment
    Enter Edit Mode
    Access More Options
    Enable Specific Setting
    Save Assessment Changes
    Open Context Subsection
    Choose Nonconformity Type
    Review Nonconformity Applicability
    Save Additional Entry
    Save Observation Information

    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.).

    hashtag
    Prerequisitories

    • A running S3-compatible storage

    • An existing bucket (must be created before starting CISO Assistant)

    • Valid access credentials (Access Key / Secret Key)

    hashtag
    Configure environment variables

    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 πŸ”₯

    hashtag
    Example case : local MinIO block storage

    You can test S3 support using MinIO:

    Then go on , 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.

    Remote/Virtualization

    Experimenting CISO Assistant through remote server or hypervisor

    circle-exclamation

    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:

    triangle-exclamation

    You cannot use IP addresses on the configuration and you need to have a FQDN mapped to it.

    1. If you aim to expose the VM to internet, use this dedicated guide:

    2. If you aim to connect from the VM

    3. If you aim to connect to the VM from your network

    hashtag
    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

    hashtag
    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

    ---

    hashtag
    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

    • 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.

    Frequent questions

    hashtag
    Stop and restart

    docker compose down

    docker compose up -d

    hashtag
    Getting the logs

    All services logs combined:

    docker compose logs

    Specific service:

    docker compose logs backend

    hashtag
    Didn't get the prompt for the first user

    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 πŸ˜‰

    hashtag
    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

    hashtag
    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:

    hashtag
    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.

    hashtag
    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:

    hashtag
    "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:

    circle-info

    If you use helm, this value is overwritten by the bodySizeLimit variable. Note the camel case here.

    Setting up mailer

    Setup the following environment variables:

    DEFAULT_FROM_EMAIL=purple@ciso-assistant.fr
    EMAIL_HOST=localhost
    EMAIL_PORT=1025
    EMAIL_HOST_USER=purple
    EMAIL_HOST_PASSWORD=dummy-unsafe-example
    EMAIL_USE_TLS=True

    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=value Incorrect: MY_VARIABLE = value

    hashtag
    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:

    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 https://caddyserver.com/docs/caddyfile/directives/tlsarrow-up-right

    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:

    • 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:

    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

    • 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

    • On Windows, Docker Desktop+WSL is recommended

    hashtag
    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.

    hashtag
    Re-building the images locally

    Alternatively, if the previous configuration didn't succeed, run:

    hashtag
    SSL Warning

    Given that Caddy is using a self-signed certificate, your browser will mention a warning that you can accept and continue.

    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.

    hashtag
    Hands-free

    The easiest way to update your on-prem/local instance (pro or community)

    Run the script update-ciso-assistant:

    Special cases

    Tips and tricks regarding specific cases

    hashtag
    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:

    Getting your custom framework

    triangle-exclamation

    IMPORTANT NOTICE: This section is NOT up to date and will be reworked. In the meantime, you can refer to the for more up-to-date information.

    circle-exclamation

    WARNING:

    CIS Controls / Cloud Controls Matrix (CCM)

    importing CIS Controls or CSA CCM

    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 conver_library depdencencies installed, is to copy the Excel sheet as-is (CIS_Controls_Version_8.xlsx) into the tools folder and run convert_cis.sh

    CIS controls converter can be found under tools/excel/cis

    CCM converter can be found under tools/excel/ccm

    Afterwards, you can upload the generated yaml file as a custom library and load it.

    Alternatively, you can run the prep script first (cis/prep_cis.py) and mention any short string as the packager and then pass the new Excel sheet to the convert_library.py

    http://localhost:9001arrow-up-right

    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:

    Deploy on a VPS
    https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/arrow-up-right
    https://helm.sh/docs/helm/helm_env/arrow-up-right
    https://docs.docker.com/reference/cli/docker/container/run/#envarrow-up-right
    backend (or huey):
      ...
      volumes:
        ...
        - /your/ca-certificate/path/example_CA.crt:/usr/local/share/ca-certificates/root_CA.crt:ro
    caddy:
        container_name: caddy
        image: caddy:2.10.0
        ...
        volumes:
          - ./caddy_data:/data
        command: |
          sh -c 'echo $$CISO_ASSISTANT_URL "{
          reverse_proxy /api/* backend:8000
          reverse_proxy /* frontend:3000
          tls /data/<path>/cert_file /data/<path>/key_file
          }" > Caddyfile && caddy run'

    On MacOS, Docker Desktop covers the requirements

    https://docs.docker.com/engine/install/ubuntu/arrow-up-right
    chcon -Rt svirt_sandbox_file_t ./db
    hashtag
    Detailled steps

    In case of issues (unsupported shell, windows, etc.) here are the steps to consider:

    1. backup your db:

      1. if you're using sqlite, copy the file under a different name

      2. if it's postgresql you can use something like pgdump

    1. stop and clean the containers, this won't affect your data

    docker compose rm -fs

    1. restart the compose and let it handle the migration

    docker compose up -d

    hashtag
    Edge cases

    Force remove the previous docker images to get the new ones

    export USE_S3=True
    export AWS_ACCESS_KEY_ID=<your-access-key>
    export AWS_SECRET_ACCESS_KEY=<your-secret-key>
    export AWS_STORAGE_BUCKET_NAME=<your-bucket-name>
    export AWS_S3_ENDPOINT_URL=<your-s3-endpoint>
    docker run -d \
      --name minio \
      -p 9000:9000 \
      -p 9001:9001 \
      -e MINIO_ROOT_USER=ciso-assistant-admin \
      -e MINIO_ROOT_PASSWORD=not_secure_password \
      -v minio_data:/data \
      minio/minio server /data --console-address ":9001"
    export USE_S3=True
    export AWS_ACCESS_KEY_ID=ciso-assistant-admin
    export AWS_SECRET_ACCESS_KEY=not_secure_password
    export AWS_STORAGE_BUCKET_NAME=my-ciso-bucket
    export AWS_S3_ENDPOINT_URL=http://localhost:9000
    #update ubuntu repository and OS
    sudo apt update
    sudo apt upgrade 
    
    # install docker
    sudo snap install docker
    
    #install python
    sudo apt install python3-pip python3.12-venv
    
    #clone the repo
    git clone https://github.com/intuitem/ciso-assistant-community.git
    
    #go to the config generator
    cd ciso-assistant-community
    cd config
    
    # setting up the python project and dependencies 
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    
    # run the interactive config generator
    python make_config.py
    ./docker-compose.sh
    docker compose logs backend
    docker compose exec backend poetry run python manage.py migrate
    docker compose up -d
    docker compose exec backend poetry run python manage.py createsuperuser
    # frontend/Dockerfile
    
    ENV BODY_SIZE_LIMIT=20000000 
    backend:
      ...
      entrypoint:
        - /bin/sh
        - -c
        - |
          update-ca-certificates
          poetry run bash ./startup.sh
    huey:
      ...  
      entrypoint:  
        - /bin/sh
        - -c
        - |
          update-ca-certificates
          poetry run python manage.py run_huey -w 2 --scheduler-interval 60
    caddy:
        container_name: caddy
        image: caddy:2.10.0
        ...
        volumes:
          - ./caddy_data:/data
          - ./certs:/certs
        command: |
          sh -c 'echo $$CISO_ASSISTANT_URL "{
          reverse_proxy /api/* backend:8000
          reverse_proxy /* frontend:3000
          tls /certs/cert_file /certs/key_file
          }" > Caddyfile && caddy run'
    ./docker-compose.sh
    ./docker-compose-build.sh
    ./update-ciso-assistant.sh
    docker rmi ghcr.io/intuitem/ciso-assistant-community/backend:latest ghcr.io/intuitem/ciso-assistant-community/frontend:latest 2> /dev/null
    This section refers to the
    v1
    format of frameworks. The
    v1
    format is deprecated. If you created your framework following this documentation and provided that you
    HAVE NOT YET
    imported your framework into CISO Assistant, we strongly recommend updating your Excel file in
    v2
    format using the
    script.

    CISO Assistant allows you to manage your custom frameworks. The format is a text-based YAML file that you can customize, but it can be tricky to maintain and debug. To manage this, we've introduced a simpler approach to convert Excel sheets using the convert_library.py utility available at the /toolsarrow-up-right of the Githubarrow-up-right repository root.

    hashtag
    Structure

    Hierarchy-based file

    The first thing to consider is structuring your requirements into a hierarchy, as illustrated in the example above. Most standards, frameworks, and law documents are already organized this way. This is the depth concept and CISO Assistant has been tested with nodes up to the 8th level depth (documents beyond 6 are mostly hard to read anyway)

    Then, the other vital aspect to think about will be which items are actually assessable. For instance, the categories, sections, and subsections are for organization and, therefore, won't be assessable unlike the requirements.

    Here is what a standard file should look like accordingly:

    This is taken from the sample file available under /tools/sample/sample.xlsx and can be used as a reference.

    Implementation groups are an optional argument that can be used to create subset of the requirements per level or a scope of applicability. They can be combined or isolated depending on the framework structure.

    hashtag
    File conversion steps

    1. Clone the repo and make sure you are at its root

    2. Make sure you have Python installed (including pip), version 3.11 or higher is recommended

    3. cd to /tools

    4. run pip install -r requirements.txt to install the script dependencies

    5. copy the sample directory, including the file within, to a new directory at the same level, for instance, myframework/my-custom-framework.xlsx

    6. Edit the first tab (library_meta) to describe your framework metadata

      1. Implementation groups and score descriptions are optional, so if they don't apply, you can simply remove lines

    7. Edit the Excel sheet according to the expected hierarchy.

      1. The order of the items is essential and will be used to build the tree on CISO Assistant. So make sure you're following the previously described structure

    8. From the tools folder, run python3 convert_library_v2.py myframework/my-custom-framework.xlsx to generate the yaml file, if a mandatory field is missing, you'll get an error explaining the issue.

    9. If everything is good, you'll get a message confirming the generation of the file generating myframework/my-custom-framework.yaml

    hashtag
    importing

    1. Open CISO Assistant. On the side menu, go to Governance/Libraries then to the Libraries store tab

    2. Scroll down to get to Upload your own library section and select your file.

    3. If the file is consistent and correct, you'll get a confirmation and it will get straight ahead to your imported frameworks under Compliance/Frameworks section

    hashtag
    testing your custom framework

    We have simplified the steps of testing custom frameworks starting version 1.3.4 where you can experiment with the same flexibility for both on-premises and SaaS version: \

    hashtag
    NEW: Full guide (French)

    dedicated README on GitHubarrow-up-right
    convert_v1_to_v2.pyarrow-up-right

    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 https://github.com/intuitem/ciso-assistant-community#supported-languages-arrow-up-right

    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.

    Helm Chart

    instructions for Kubernetes installation with Helm Chart

    hashtag
    GH OCI registry

    1. Getting the values

    1. customize as you see fit

    2. Install the chart

    hashtag
    Legacy

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

    1. add the helm repository

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

    1. get the default values

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

    1. check and adjust them to your needs, specifically the frontendOrigin parameter

    2. create a namesapce for your deployment

    kubectl create ns ciso-assistant

    1. install

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

    circle-info

    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.

    00 - initial setup

    hashtag
    CISO Assistant: initial setuparrow-up-right

    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.

    hashtag
    Go to

    hashtag
    1. Introduction

    This guide walks you through configuring essential security frameworks and risk matrices to establish a robust compliance foundation.

    hashtag
    2. Click "Organization"

    Navigate to the Organization section to begin configuring your company settings.

    hashtag
    3. Click "Domains"

    Access the Domains tab to manage your organization's domain information.

    hashtag
    4. Click here

    Initiate adding a new domain by clicking the add button.

    hashtag
    5. Click here

    Open the domain creation form to input new domain details. Markdown is supported for the description.

    hashtag
    6. Fill "ACME" (or any relevant domain name)

    Enter your organization's domain name to register it within the system.

    hashtag
    7. Click "Save"

    Confirm and save the new domain to apply changes.

    hashtag
    8. Click "ACME"

    Select the newly created domain to configure its specific settings.

    hashtag
    9. Click "Add perimeter"

    Start adding a security perimeter to define access boundaries for the domain.

    hashtag
    10. Click here

    Open the perimeter creation interface to specify perimeter details.

    hashtag
    11. Fill "Common"

    Name the new perimeter to identify it clearly within your domain.

    hashtag
    12. Click "Save"

    Save the perimeter settings to establish the defined boundary.

    hashtag
    13. Click "Users"

    Go to the Users section to manage user accounts and permissions.

    hashtag
    14. Click here

    Begin adding a new user by selecting the add user option.

    hashtag
    15. Click here

    Open the user creation form to input user details.

    hashtag
    16. Fill "alice@company.com"

    Enter the user's email address to create their account.

    hashtag
    17. Click "Save"

    Save the new user profile to register them in the system.

    hashtag
    18. Click "alice@company.com"

    Select the newly added user to modify their settings.

    hashtag
    19. Click "Edit"

    Access the edit mode to update user roles and permissions.

    hashtag
    20. Click here

    Open the role assignment dropdown to select user roles.

    hashtag
    21. Click "ACME - Analyst"

    Choose the appropriate role for the user within the organization.

    hashtag
    22. Click "Save"

    Save the updated user role to apply changes.

    hashtag
    23. Click "Catalog"

    Navigate to the Catalog section to explore available frameworks and resources.

    hashtag
    24. Click "Frameworks"

    Access the Frameworks tab to browse compliance and security frameworks.

    hashtag
    25. Click here

    Open the framework search interface to find specific standards.

    hashtag
    26. Click "Search..."

    Use the search bar to locate a framework by name or keyword.

    hashtag
    27. Fill "iso 27"

    Enter the ISO 27001 framework to find relevant compliance information.

    hashtag
    28. Click here

    Select the ISO 27001 framework from the search results to view details.

    hashtag
    29. Fill "nist csf"

    Open the NIST CSF framework details for review and mapping.

    hashtag
    30. Click here

    Use the search function to find specific frameworks or resources.

    hashtag
    31. Click "nist csf"

    Access the Risk Matrices section to manage risk assessment tools.

    hashtag
    32. Fill "Search..."

    Open the risk matrix search to locate specific matrices.

    hashtag
    33. Click "Risk matrices"

    Search for critical risk matrices to prioritize high-impact risks.

    hashtag
    34. Click here

    Select the critical risk matrix to analyze and manage risks.

    hashtag
    35. Click "Search..."

    Navigate to the Mappings section to link frameworks and risk matrices.

    hashtag
    36. Fill "critic"

    Access the Risk Matrices tab within Mappings to review associations.

    hashtag
    37. Click here

    Switch to the Frameworks tab to manage framework mappings.

    hashtag
    38. Click "Risk matrices"

    Review the filtered entries to find specific standards and mappings.

    hashtag
    39. Click "Frameworks"

    Examine the details of the ISO/IEC 27001:2022 standard for information security compliance.

    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.

    01 - basic audit

    hashtag
    CISO Assistant: starting an auditarrow-up-right

    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.

    hashtag
    Go to

    hashtag
    1. Click "Organization"

    Access the Organization settings to begin configuring your domain management.

    hashtag
    2. Click "Domains"

    Navigate to the Domains section to manage your organization's domain details.

    hashtag
    3. Click here

    Initiate the process to add a new domain by selecting the appropriate option.

    hashtag
    4. Click here

    Enter a descriptive name for your new domain to clearly identify it.

    hashtag
    5. Fill "explainer"

    Save the newly created domain to register it within your organization.

    hashtag
    6. Click "Save"

    Select the domain you just created to begin setting up its security perimeter.

    hashtag
    8. Pick "explainer" domain

    Start adding a new security perimeter to define the domain's protective scope.

    hashtag
    9. Click "Add perimeter"

    Choose the option to specify the perimeter's characteristics and settings.

    hashtag
    10. Click here

    Provide a clear and concise name for the new security perimeter.

    hashtag
    11. Fill "general"

    Save the perimeter settings to apply them to the domain.

    hashtag
    12. Click "Save"

    Return to the General settings to prepare for audit creation.

    hashtag
    13. Click "General"

    Begin creating a new audit to assess your organization's security posture.

    hashtag
    14. Click "New Audit"

    Select the option to add a new audit baseline for evaluation.

    hashtag
    15. Click here

    Name your audit baseline to reflect its purpose or scope.

    hashtag
    16. Fill "my baseline"

    Specify the audit type or category to align with your compliance goals.

    hashtag
    17. Click here

    Choose the relevant standard or framework for your audit.

    hashtag
    18. Search "iso"

    Select the International standard ISO/IEC 27001:2022 to align with recognized security practices.

    hashtag
    19. Click "International standard ISO/IEC 27001:2022"

    Confirm and save your audit configuration to proceed.

    hashtag
    20. Click "Save"

    Access the detailed audit sections to review specific requirements.

    hashtag
    21. Open the tree structure

    Select the section focused on the organization's context for information security.

    hashtag
    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.

    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.

    Jira

    hashtag
    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:

    • 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.

    hashtag
    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.

    hashtag
    Outgoing sync

    hashtag
    Configuration

    To configure the integration, you will need to perform steps on both the Jira and CISO Assistant sides.

    hashtag
    1. Configure Jira

    Create a Jira API Token

    1. Log in to your Jira account.

    2. 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".

    3. In your Atlassian account page, navigate to Security > API token.

    Identify your Jira Project Key

    1. In Jira, go to the project you want to integrate with CISO Assistant.

    2. 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.

    hashtag
    Incoming sync

    circle-info

    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

    hashtag
    2. Configure CISO Assistant

    1. Log in to your CISO Assistant instance.

    2. Navigate to the integrations settings page. Find the Jira integration section.

    3. Configure outgoing sync:

    hashtag
    Usage

    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.

    hashtag
    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

    • 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

    hashtag
    Outgoing sync (Push)

    • Creating an applied control

    • Updating an applied control

    hashtag
    Incoming sync (Pull)

    • jira:issue_created

    • jira:issue_update

    • jira:issue_deleted

    hashtag
    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

    New - Cyber Risk Quantification

    CRQ quick start

    hashtag
    Cyber Risk Quantification on CISO Assistantarrow-up-right

    This tutorial guides you through performing Cyber Risk Quantification using the CISO Assistant

    hashtag
    Go to your instance

    hashtag
    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.

    hashtag
    2. Click "Risk"

    Click "Risk" to access the risk management section where you can start your cyber risk quantification process.

    hashtag
    3. Click "CRQ studies"

    Click "CRQ studies" to view and manage your Cyber Risk Quantification studies.

    hashtag
    4. Click here

    Click here to create a new study for your risk analysis.

    hashtag
    5. Fill the required fields of the study

    Fill "a study" to name your new study, which helps identify it later.

    hashtag
    6. Choose a domain

    Click "DEMO" to select the demo environment or dataset for your study.

    hashtag
    7. Click "Save"

    Click "Save" to store your new study configuration.

    hashtag
    8. Click "Add scenario"

    Click "Add scenario" to define a new risk scenario within your study.

    hashtag
    9. Create your first scenario

    Fill "first scenario" to name your initial risk scenario for clarity and tracking.

    hashtag
    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.

    hashtag
    11. You can select a threat now or do it later

    Click "DEMO/Ransomware" to specify ransomware as the threat type for this scenario.

    hashtag
    12. Click "Save"

    Click "Save" to save your scenario settings.

    hashtag
    13. Click here

    Click here to move to the next configuration section.

    hashtag
    14. Select the existing controls that serve as a baseline

    Click "Treatment" to define the risk treatment options for your scenario.

    hashtag
    15. Click "Simulation Parameters"

    Click "Simulation Parameters" to set parameters for your risk simulation.

    hashtag
    16. Fill the probability of the current baseline

    Fill "0.40" to set the probability or impact factor for the simulation.

    hashtag
    17. Setup your lower bound (best case scenario)

    Click here to proceed to the next parameter.

    hashtag
    18. and your upper bound (worst case scenario)

    Fill "100000" to set the worst-case loss estimate for the scenario.

    hashtag
    19. Click "Save"

    Click "Save" to apply your simulation parameters.

    hashtag
    20. Click on the hypothesis and then Click "Run simulation"

    Click "Run simulation" to start the risk quantification process based on your inputs.

    hashtag
    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

    hashtag
    22. Click here to go back to the scenario

    Click "first scenario" to select the scenario for which you want to view simulation results.

    hashtag
    23. Let's create a new hypothesis

    Click "New hypothesis" to create a what-if analysis for alternative risk treatments.

    hashtag
    24. Click "Treatment"

    Click "Treatment" to assign treatments to your new hypothesis.

    hashtag
    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.

    hashtag
    26. Click "Simulation Parameters"

    Click "Simulation Parameters" to adjust parameters for the hypothesis simulation.

    hashtag
    27. update the simulation parameters of this hypothesis

    based on your estimate of risk reduction with this treatment plan

    hashtag
    28. Update the probability and/or the UB/LB

    Fill "0.2" to set the updated probability or impact factor for the hypothesis.

    hashtag
    29. Click "Save"

    Click "Save" to store your hypothesis simulation parameters.

    hashtag
    30. Click "Run simulation"

    Click "Run simulation" to execute the what-if analysis and compare results.

    hashtag
    31. Let's go back to the scenario to compare the two hypotheses

    Click "first scenario" to return to the main scenario view.

    hashtag
    32. What if the ROSI is not calculated?

    Click your control to jump to its details.

    hashtag
    33. Click "Edit"

    Click "Edit" to modify treatment or scenario settings as needed.

    hashtag
    34. Click "Cost"

    Click "Cost" to enter the financial impact or cost associated with the treatment.

    hashtag
    35. Describe the Build and Run cost structure

    Click here to open the cost input field.

    hashtag
    36. Click "Save"

    Click "Save" to apply your cost settings.

    hashtag
    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

    hashtag
    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.

    hashtag
    39. You can go "Back to Study" anytime to refine the scenarios and hypotheses

    Click "Back to Study" to return to detailed study configuration.

    hashtag
    40. What if I want to set a loss threshold

    Click "Edit" to make further changes to your study settings.

    hashtag
    41. Click "Tolerance settings"

    Click "Tolerance settings" to adjust risk tolerance thresholds for your analysis.

    hashtag
    42. Click here

    Click here to open tolerance input fields.

    hashtag
    43. Click "Save"

    Click "Save" to confirm your tolerance settings.

    hashtag
    44. Tip: click "Retrigger All Simulations" to refresh all simulations and insights

    Click "Retrigger All Simulations" to rerun simulations with updated parameters and settings.

    hashtag
    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

    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.

    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

    • 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

    helm show values oci://ghcr.io/intuitem/helm-charts/ce/ciso-assistant > custom.yaml

    Third-party integrations

    Integrate CISO Assistant with third-party providers

    Decoupling concept - full screen is recommended for a better experience
    helm install ciso-assistant-release oci://ghcr.io/intuitem/helm-charts/ce/ciso-assistant -f custom.yaml
    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.

  • You might need to filter the associated JQL to only send events on you specific project.

    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.

    • 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.

  • Configure incoming sync

    1. Enter the following information:

      • 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

        • 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.

  • Save the configuration

  • 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.

  • Select the Jira integration provider

  • Select the Jira issue you wish to link to your applied control.

  • your-ciso-assistant-instancearrow-up-right
    Powered by guiddearrow-up-right
    Introduction
    Click 'Organization'
    Click 'Domains'
    Click here
    Click here
    Fill 'ACME' (or any relevant domain name)
    Click 'Save'
    Click 'ACME'
    Click 'Add perimeter'
    Click here
    Fill 'Common'
    Click 'Save'
    Click 'Users'
    Click here
    Click here
    Fill 'alice@company.com'
    Click 'Save'
    Click 'alice@company.com'
    Click 'Edit'
    Click here
    Click 'ACME - Analyst'
    Click 'Save'
    Click 'Catalog'
    Click 'Frameworks'
    Click here
    Click 'Search...'
    Fill 'iso 27'
    Click here
    Fill 'nist csf'
    Click here
    Click 'nist csf'
    Fill 'Search...'
    Click 'Risk matrices'
    Click here
    Click 'Search...'
    Fill 'critic'
    Click here
    Click 'Risk matrices'
    Click 'Frameworks'
    localhost:5173arrow-up-right
    Powered by guiddearrow-up-right
    Click 'Organization'
    Click 'Domains'
    Click here
    Click here
    Fill 'explainer'
    Click 'Save'
    Click 'explainer'
    Click 'Add perimeter'
    Click here
    Fill 'general'
    Click 'Save'
    Click 'General'
    Click 'New Audit'
    Click here
    Fill 'my baseline'
    Click here
    Fill 'iso'
    Click 'International standard ISO/IEC 27001:2022'
    Click 'Save'
    Click here
    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.'
    Powered by guiddearrow-up-right
    Introduction
    Click 'Risk'
    Click 'CRQ studies'
    Click here
    Fill the required fields of the study
    Choose a domain
    Click 'Save'
    Click 'Add scenario'
    Create your first scenario
    You can select an asset now or do it later
    You can select a threat now or do it later
    Click 'Save'
    Click here
    Select the existing controls that serve as a baseline
    Click 'Simulation Parameters'
    Fill the probability of the current baseline
    Setup your lower bound (best case scenario)
    and your upper bound (worst case scenario)
    Click 'Save'
    Click on the hypothesis and then Click 'Run simulation'
    Click here to go back to the scenario
    Let's create a new hypothesis
    Click 'Treatment'
    and pick one of the controls you want to implement
    Click 'Simulation Parameters'
    update the simulation parameters of this hypothesis
    Update the probability and/or the UB/LB
    Click 'Save'
    Click 'Run simulation'
    Let's go back to the scenario to compare the two hypotheses
    What if the ROSI is not calculated?
    Click 'Edit'
    Click 'Cost'
    Describe the Build and Run cost structure
    Click 'Save'
    What if I want a summary of all my scenarios and a portfolio overview
    You can go 'Back to Study' anytime to refine the scenarios and hypotheses
    What if I want to set a loss threshold
    Click 'Tolerance settings'
    Click here
    Click 'Save'
    Tip: click 'Retrigger All Simulations' to refresh all simulations and insights
    Don't forget to use this to go to the parent object

    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,

    • you can also add the generated yaml (assuming you have tested it) under backend/library/libraries

    • open a pull request and make sure you accept the CLA

    and we'll take it from there πŸ‘

    If you're not familiar with Github and the handling Git, you can follow these simplified steps using just the UI :

    • create your excel sheet based on one of the samples in tools folder

    • convert it to yaml using the convert_library.py tool

    • Test it to make sure it can be parsed by the app and matches what you are expecting

    • sign up on github to create an account and head to ciso assistant repository

    • create your fork of the repository

    • if it's not your first time, make sure your fork is up to date

    • go to the tools folder

    • click Add file and click Upload files

    • drag and drop the excel file you've prepared or pull it from your filesystem.

    • add a commit message, something like "Submitting framework x"

    • commit the changes

    • if everything went well, you should see a message indicating that you're 1 commit ahead.

    • Optional: you can repeat this process to add the yaml file as well but on the backend/library/libraries/ folder instead.

    • You can now open the pull request:

    There are of course other ways to achieve this in a much cleaner approach, but this is intended for a beginer discovering git and GitHub πŸ˜‰

    Generating a PAT

    Personal Access Token to interact with the API

    hashtag
    Getting a PAT (Personal Access Token) for CISO Assistantarrow-up-right

    Learn how to generate a Personal Access Token (PAT) for CISO Assistant quickly and securely

    hashtag
    First you need to sign into your instance

    hashtag
    1. Introduction

    This guide provides clear steps to create, name, set expiration, and copy your PAT for seamless integration.

    hashtag
    2. Click here

    Access your account menu by selecting your profile icon in the application interface.

    hashtag
    3. Click "My profile"

    Navigate to the 'My Profile' section to manage your personal account settings.

    hashtag
    4. Click "Settings"

    Open the 'Settings' tab within your profile to configure advanced options.

    hashtag
    5. Click "Generate new token"

    Initiate the creation of a new Personal Access Token by selecting 'Generate new token'.

    hashtag
    6. Click here

    Click the input field to name your token, providing a clear and descriptive label.

    hashtag
    7. Fill "testing"

    Enter a meaningful token name to help you identify its purpose later.

    hashtag
    8. Click "30"

    Set the token's expiration by choosing a predefined duration from the available options.

    hashtag
    9. Fill "90"

    Alternatively, specify a custom expiration period to suit your security needs.

    hashtag
    10. Click "Generate new token"

    Confirm the token generation by clicking the 'Generate new token' button.

    hashtag
    11. Click "Copy"

    Securely copy the newly created token to your clipboard for immediate use.

    hashtag
    12. Click "Done"

    Complete the process by clicking 'Done' to save your settings and exit the token creation workflow.

    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.

    API usage

    hashtag
    Access the online documentation

    hashtag
    Enable the documentation locally

    Enable debug mode

    Start the backend server (make sure that dependencies are installed):

    Access the swagger documentation here:

    Or redoc format here:

    hashtag
    Interacting with the API

    • Start by creating a PAT, instructions here

    • 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:

    Or with curl:

    hashtag
    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.

    Outgoing webhooks

    hashtag
    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.

    hashtag

    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.

    • CI/CD Gates: Trigger a build pipeline scan when a specific policy is updated.


    hashtag
    Supported Events

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

    • Applied controls:

      • appliedcontrol.created

      • appliedcontrol.updated

      • appliedcontrol.deleted

    • Assets:

      • asset.created

      • asset.updated


    hashtag
    Configuration & Security Features

    CISO Assistant adheres to the Standard Webhooks v1.0.0arrow-up-right specificationarrow-up-right. We prioritize security to ensure that the data sent to your systems is authentic and has not been tampered with.

    hashtag
    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.

      • 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.

    hashtag
    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:

    1. Authenticity: The message definitely came from CISO Assistant.

    2. Integrity: The message content was not altered in transit.

    hashtag
    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).

    hashtag
    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.


    hashtag
    The Integration Journey

    1. Enable the Webhooks feature flag in Settings > Feature flags

    2. Create an Endpoint: In the CISO Assistant UI, navigate to Settings > Webhooks.

    3. Configure: Enter your receiver URL and select the events you want to listen to (e.g., appliedcontrol.updated).

    4. Select Payload Type: Choose "Full" or "Thin" based on your security requirements.

    5. Save & Copy Secret: Copy the whsec_... secret immediately. You will need this for your consumer.

    6. Develop: Write your consumer code (see examples below).


    hashtag
    Technical Reference

    hashtag
    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: The payload data (varies by "Thin" or "Full").

    Example: Thin Payload

    Example: Full Payload

    hashtag
    Headers

    We send the following headers with every request:

    • Content-Type: application/json

    • webhook-id: Unique message ID (for idempotency).

    • webhook-timestamp: Unix timestamp of the send attempt.

    • webhook-signature: The signature string, e.g., v1,BmX...


    hashtag
    Verifying the Signature

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

    The Algorithm:

    1. Extract the webhook-id, webhook-timestamp, and webhook-signature.

    2. Concatenate strings to form the signed content: [webhook-id].[webhook-timestamp].[raw_body].

    3. Calculate the HMAC-SHA256 of this string using your whsec_... secret.

    4. Compare your calculated signature with the one provided in the header.

    Python Example (Django/FastAPI/Flask)


    hashtag
    Operational Details

    hashtag
    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.

    • 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.

    hashtag
    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.

    http://127.0.0.1:8000/api/schema/swagger/arrow-up-right
    Generating a PAT
    Example with Bruno (Postman alternative)
    Example with Bruno (Postman alternative)
    Introduction
    Click here
    Click 'My profile'
    Click 'Settings'
    Click 'Generate new token'
    Click here
    Fill 'testing'
    Click '30'
    Fill '90'
    Click 'Generate new token'
    Click 'Copy'
    Click 'Done'

    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

    hashtag
    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.

    {
      "type": "appliedcontrol.created",
      "timestamp": "2025-11-13T14:35:06Z",
      "data": {
        "id": "53709ff2-ade7-4172-9dee-daa580cbba5b"
      }
    }
    {
      "type": "appliedcontrol.created",
      "timestamp": "2025-11-13T14:35:06Z",
      "data": {
        "id": "53709ff2-ade7-4172-9dee-daa580cbba5b",
        "name": "MFA Enforcement",
        "status": "active",
        "owner": "john.doe@example.com",
        ...
      }
    }
    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
    export DJANGO_DEBUG=True
    python3 manage.py runserver
    curl --request GET \
      --url http://127.0.0.1:8000/api/assets/ \
      --header 'authorization: Token a6a120f....'
    asset.deleted
    Why choose this: Reduces integration effort by removing the need for a callback API request. Ideal for simple notifications (e.g., Slack alerts).
    The CISO Assistant MCP server provides 90+ tools covering:
    • Risk management (assessments, scenarios, matrices)

    • Compliance audits (frameworks, requirements)

    • Asset management

    • Third-party risk management (TPRM)

    • EBIOS RM methodology

    • And more...

    hashtag
    Why stdio Transport?

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

    1. Local file access - stdio allows the server to read and process local files on your machine, which HTTP-based servers cannot do securely.

    2. 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.

    3. No open ports - Unlike HTTP servers, stdio doesn't require opening any ports on your machine, reducing your attack surface.

    4. 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.

    5. Works offline - The MCP server itself runs locally. Only the actual CISO Assistant API calls require network access.

    hashtag
    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.

    hashtag
    Option A: Clone with Git (recommended)

    This makes it easy to update later with git pull.

    hashtag
    Option B: Download as ZIP

    1. Go to https://github.com/intuitem/ciso-assistant-community

    2. Click the green Code button

    3. Select Download ZIP

    4. Extract the ZIP file to a folder of your choice

    5. 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.


    hashtag
    Prerequisites

    Before you begin, make sure you have:

    1. 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.

    2. Python 3.12+ installed

    3. uv package manager (recommended) - Install with:

    hashtag
    Step 1: Generate a Personal Access Token (PAT)

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

    1. Log in to CISO Assistant

    2. Click on your profile icon (top right)

    3. Go to Settings β†’ Personal Access Tokens

    4. Click Create Token

    5. Give it a name (e.g., "MCP Integration")

    6. 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.

    hashtag
    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


    hashtag
    Setup for Claude Desktop

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

    hashtag
    Find your config file location

    Operating System
    Config File Path

    macOS

    ~/Library/Application Support/Claude/claude_desktop_config.json

    Windows

    %APPDATA%\Claude\claude_desktop_config.json

    Linux

    ~/.config/Claude/claude_desktop_config.json

    hashtag
    Create or edit the config file

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

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

    hashtag
    Example paths by OS

    macOS:

    Windows:

    Linux:

    hashtag
    Alternative: Pass credentials via environment

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

    hashtag
    Restart Claude Desktop

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

    hashtag
    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.


    hashtag
    Setup for Claude Code (CLI)

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

    hashtag
    Create the config file

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

    hashtag
    Config file locations

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

    1. Current working directory

    2. Home directory (~/.mcp.json)

    hashtag
    Alternative: Specify full path to uv

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

    Find uv's location with:

    hashtag
    Verify it works

    Start Claude Code and ask:

    "List all risk assessments in CISO Assistant"


    hashtag
    Setup for LM Studio

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

    hashtag
    Step 1: Open the MCP configuration

    1. Open LM Studio

    2. Go to Settings (gear icon)

    3. Click on the Program tab

    4. Find Integrations section

    5. Click the Install button

    6. Select Edit mcp.json

    hashtag
    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

    hashtag
    Example (macOS)

    hashtag
    Step 3: Save and restart

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


    hashtag
    Troubleshooting

    hashtag
    "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/

    hashtag
    "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

    hashtag
    "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

    hashtag
    MCP server not appearing in Claude Desktop

    1. Check the config file location is correct for your OS

    2. Verify the JSON syntax is valid (use a JSON validator)

    3. Make sure paths use forward slashes / (even on Windows) or escape backslashes \\

    4. Restart Claude Desktop completely (quit, don't just close)

    hashtag
    "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

    hashtag
    Check MCP server logs

    Test the server directly from terminal:

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


    hashtag
    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?"


    hashtag
    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.

    hashtag
    Need Help?

    • CISO Assistant Documentation: https://intuitem.gitbook.io

    • GitHub: https://github.com/intuitem/ciso-assistant-community

    • Discord: https://discord.gg/qvkaMdQ8daarrow-up-right


    hashtag
    Quick Reference: Environment Variables

    Variable
    Required
    Default
    Description

    TOKEN

    Yes

    -

    Personal Access Token from CISO Assistant

    API_URL

    No

    http://localhost:8000/api

    CISO Assistant API endpoint

    VERIFY_CERTIFICATE

    No

    false

    # 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
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "/path/to/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "/Users/yourname/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "C:\\Users\\yourname\\ciso-assistant-community\\cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "/home/yourname/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "/path/to/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ],
          "env": {
            "TOKEN": "your-token-here",
            "API_URL": "http://localhost:8000/api",
            "VERIFY_CERTIFICATE": "false"
          }
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "uv",
          "args": [
            "--directory",
            "/path/to/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "/Users/yourname/.cargo/bin/uv",
          "args": [
            "--directory",
            "/path/to/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ]
        }
      }
    }
    which uv  # macOS/Linux
    where uv  # Windows
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "/path/to/uv",
          "args": [
            "--directory",
            "/path/to/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ],
          "env": {
            "TOKEN": "your-personal-access-token",
            "VERIFY_CERTIFICATE": "false",
            "API_URL": "http://localhost:8000/api"
          }
        }
      }
    }
    {
      "mcpServers": {
        "ciso-assistant": {
          "command": "/Users/yourname/.cargo/bin/uv",
          "args": [
            "--directory",
            "/Users/yourname/ciso-assistant-community/cli",
            "run",
            "ca_mcp.py"
          ],
          "env": {
            "TOKEN": "your-personal-access-token",
            "VERIFY_CERTIFICATE": "false",
            "API_URL": "http://localhost:8000/api"
          }
        }
      }
    }
    cd /path/to/ciso-assistant-community/cli
    uv run ca_mcp.py

    SSL certificate verification

    How to create a risk assessment
    CISO Assistant: PRO Planintuitemchevron-right
    Join the CISO Assistant - GRC community Discord Server!Discordchevron-right
    Logo
    intuitem - CISO Assistant - Open source GRCintuitemchevron-right
    How to create a compliance assessment
    How to create a perimeter
    GitHub - intuitem/ciso-assistant-community: CISO Assistant is a one-stop-shop GRC platform for Risk Management, AppSec, Compliance & Audit, TPRM, Privacy, and Reporting. It supports 100+ global frameworks with automatic control mapping, including ISO 27001, NIST CSF, SOC 2, CIS, PCI DSS, NIS2, DORA, GDPR, HIPAA, CMMC, and more.GitHubchevron-right
    https://www.linkedin.com/events/cisoassistant-lagrcop-rationnel7279514036780601344/www.linkedin.comchevron-right
    https://www.youtube.com/live/BphsE5Z5lEMwww.youtube.comchevron-right
    πŸ‡¨πŸ‡΅ French session
    πŸ‡¬πŸ‡§ English session
    πŸ‡¨πŸ‡΅ French session
    πŸ‡¨πŸ‡΅ French session
    illustration of implementation groups
    spinner
    Logo
    Testing your custom framework
    CISO Assistant API - Experimentalca-api-doc.pages.devchevron-right
    http://127.0.0.1:8000/api/schema/redoc/127.0.0.1chevron-right
    Logo
    Logo