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

"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

• Start a risk assessment

• ♻️ Identify your scenarios, assess them, link or create the applied controls, and the reflect the progress on the risk level

"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

• ♻️ Track the audits progress, assign controls and make your opinion

"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

• ♻️ Track the applied controls progress and reflect that on your findings status

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

A different take on Cyber Security Posture Management

• explicitly decoupling compliance from cyber-security practices implementation

• providing simplified tools for decision-making

• providing capabilities for a program, product, or an organization assessment against standard frameworks

• you can bring your own framework as well using a simplified DSL

• aim to be a one-stop-shop for cyber security management and cover the layers of GRC (Governance, Risk and Compliance)

An open-source GRC tool

About the SaaS and PRO plan

Quick links

Get Started

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

Model

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

Analytics

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

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

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.

Calendar

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

X-rays

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

• info: advice or reminder for status and relevant empty fields

• warning: potential errors to be determined by the user

• error: errors that must be corrected

Scoring Assistant

Glossary

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.

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.

📦 Assets

Template

Supported fields

• ref_id

• name*

• description

• domain

• type

  • PR : primary

  • SP : supporting

Special considerations

• type will default to supporting if not set

⚙️ Applied controls

Template

Supported fields

• ref_id

• name*

• description

• domain

• 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

Special considerations

• status will default to to_do

• csf_function will default to govern

📦 Perimeters

Template

Supported fields

• ref_id

• name*

• description

• domain

• status

  • undefined

  • in_design

  • in_dev

  • in_prod

  • eol

  • dropped

📃 Audits

Template

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

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

Supported fields

• urn*

• assessable

• ref_id*

• name

• 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

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.

• Unassessable rows are skipped.

Findings followup (eg. pentest)

Template

Supported fields

• ref_id

• name*

• description

• severity

  • low

  • medium

  • high

  • critical

• status

  • identified

  • confirmed

  • dismissed

  • assigned

  • in_progress

  • mitigated

  • resolved

  • deprecated

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.

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.

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.

New! Config Builder

Customize the local deployment according to your needs:

Docker compose

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

• clone the repo:

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

• run the preparation script and follow the instructions:

./docker-compose.sh

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

Helm chart

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

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

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:

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.

Go into your Azur 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
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.

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.

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.

Reference control

Reference controls are templates for applied controls. They facilitate the creation of an applied control, and help to have consistent applied controls. They are optional, but recommended. Reference controls can be provided by security frameworks that are imported from a library, but you can create your own reference controls in the global domain or in a specific domain.

Applied control

Applied controls are fundamental objects for compliance and remediation. They can derive from a reference control, which provides better consistency, or be independent. Applied controls are always defined by the entity and can be attached to the global domain or in a specific domain.

Asset

An asset refers to any piece of information that holds value to an organization. These assets can be digital or physical and encompass a wide range of data types, including customer records, financial information, intellectual property, employee records, proprietary software, marketing materials, and more. Assets are always defined by the entity and can be attached to the global domain or in a specific domain. There are two types of assets:

• Primary assets are core resources directly contributing to an organization's main objectives, like machinery or intellectual property.

• Support assets indirectly aid primary functions, such as IT systems or administrative services.

Prerequisites to Install CISO Assistant On-Premises

1. Hardware Requirements:

   1. CPU: 4 cores

   2. RAM: Minimum 8 GB

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

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

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.

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.

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.

Utility

A domain is the first thing you create on CISO Assistant. It will bring together all objects you need to complete your different perimeters. Every role/permission a user has on a domain are applicable to all objects/actions across the domain. It's all about organization, the only technical aspect is access control, and this is achieved by adding the user to the relevant user group.

Role assignment

In the first/open source version of CISO Assistant, custom role assignment is not available. So, when you create a domain, user groups concerning this domain are automatically created for each built-in role. All you need to do, is to assign your users to their user groups. To learn more about this, jump to User Groups.

Perimeters

Perimeters are fundamental context objects defined by the entity using CISO Assistant. They are grouped in domains. They will contain all your risk and compliance assessments. Apart from being able to group your various evaluations across the different domains.

There are two specific fields, internal reference and status. Here are the various status options:

• -- (None)

• Design

• Development

• Production

• End of life

• Dropped

The purpose of a perimeter is at first, it's organizational aspect to solve a problem. But it also makes it possible to improve analytics by breaking them down according to the different assessments, whether for risk or compliance, so as to make your project management more precise and reduce noise.

User Groups

User groups go hand in hand with domains. they associate permissions with users and define their scope, by being attached to a domain. They follow a simple and consistent RBAC model from a role containing permissions and a domain determining the perimeter. Go to the User Groups page for more details.

Providers

Configure CISO Assistant with SAML

1. Log in into CISO Assistant as an administrator > Extra > Settings
2. Enable SSO
3. Enter the Idp Entity ID
4. 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
5. Check that the SP Entity ID is similar to the Entity/Client ID specified on your provider
6. And that's it ! Don't forget to save changes

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

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 by your <base_url> and Valid redirect URIs by <backend_url/*>
4. Go into Keys and disable Signing keys config
5. Go into Advanced and fill ACS field by <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 by http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
9. Click on X500 givenName and replace SAML Attribute name by 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

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.

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.

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 field in CISO Assistant
11. Go to the Assignments tab
12. Click on Assign and choose whether you want to assign users or specific groups

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

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.

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!

Audit

This allows you to assess your compliance with the chosen framework through different statuses for each requirement that requires one of the following:

• To do

• In progress

• Non compliant

• Partially compliant

• Compliant

• Not applicable

Evidence

Let's say that you want to setup or experiment with CISO Assistant on a Network or Virtualized environment (eg. Hypervisor) on a remote host, for instance, to use with multiple users:

• Install a recent version of Docker on your remote server

• Given that we are using TLS with Caddy, we need to have DNS entries and not IPs

• The workstations need to be able to reach the remote using an FQDN (DNS entry). If not you can add an entry on your /etc/hosts. Keep track of the remote server DNS as you'll put it on the next step, let's say the remote is cool-vm for instance

• Clone the repo, but don't run anything yet. Edit the docker-compose.yml file as follows: (red is for deletion and green for addition); your diff should look like:

• Five lines need to be edited. Save the file and move to the next step

If you're getting SSL_ERROR_INTERNAL ERROR_ALERT (Can be different on other browsers) blocking you from continuing, make sure that you've made the 5 changes above.

The tls internal (equivalent to -i in CLI mode) parameter of Caddy can present some security issues and is not recommended for production and internet exposure. You should consider proper certificates for that.

You're all set, and you can simply run:

Your CISO Assistant can be reached now from https://cool-vm:8443, and you can skip the SSL warning for the self-signed certificate.

This setup aims to expose CISO Assistant on a VPS while using automated Let's Encrypt for certificates management.

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

• Port to use: 443

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.

👉 Notes

• The generated file in the config directory will be named docker-compose-custom.yml For subsequent operations with compose, you'll need to specify it with -f

• If you're running docker compose without the -f, it could conflict with the default one on the repository root directory.

• If you're starting a production environment:

  • make sure to disable the debug mode,

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

  • have your db folder outside of the repo.

Clean up

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:

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.

Risk scenario

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

Risk acceptance

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 Windows, Docker Desktop+WSL is recommended

• On MacOS, Docker Desktop covers the requirements

Using prebuilt images

Run:

It will clean up previous images and get the latest stable release.

Once the images are downloaded and migration triggered, you should see a prompt asking you to set the first superuser. Follow the instructions to set it, and you should be ready.

In case you are running on an unsupported architecture, you can open a GitHub issue so that we add its support or use the next steps to build the images locally.

Re-building the images locally

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

SSL Warning

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

Prerequisites

• A smartphone with an authenticator app installed

• Access to your account settings on CISO Assistant

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:

   • 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
4. Enter the 6-digit verification code shown in your authenticator app

5. Click 'Enable 2FA' to complete the setup

Important: Save Your Recovery Codes

After enabling MFA, you'll receive a set of recovery codes. These codes are crucial for regaining access to your account if you:

• Lose your phone

• Uninstall your authenticator app

• Cannot access your authenticator app for any reason

Next Steps

• Test your MFA setup by logging out and back in

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

Live sessions

LinkedIn

Youtube

# Social medias

Users reviews

Blogs

GH OCI registry

1. Getting the values

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

1. customize as you see fit

2. Install the chart

helm install ciso-assistant-release oci://ghcr.io/intuitem/helm-charts/ce/ciso-assistant -f custom.yaml

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

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.

Hands-free

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

Run the script update-ciso-assistant:

./update-ciso-assistant.sh

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

Edge cases

Force remove the previous docker images to get the new ones

docker rmi ghcr.io/intuitem/ciso-assistant-community/backend:latest ghcr.io/intuitem/ciso-assistant-community/frontend:latest 2> /dev/null

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:

chcon -Rt svirt_sandbox_file_t ./db

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

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

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

Structure

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.

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

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

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

NEW: Full guide (French)

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 😉

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:

docker compose logs backend

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:

docker compose exec backend poetry run python manage.py migrate

Healthcheck fails during the installation

most likely because the initialization took longer than expected. Make sure you provide the expected specs or tune the docker compose to give the app more time to finish the init phase.

Don't want / Can't run the init script

The recommended pattern for a first local setup is to go with ./docker-compose.sh ; In case you can't:

Run

docker compose up -d

wait for the init to finish and then trigger the first user creation manually:

docker compose exec backend poetry run python manage.py createsuperuser

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

# frontend/Dockerfile

ENV BODY_SIZE_LIMIT=20000000 

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:

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

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:

For now, it is not possible to create custom role assignments so you need to use built-in user groups. They are linking a domain with a role which contains precise permissions, that will be given to users in this group.

Roles

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

Global user groups

Once your instance is created, three user groups are already present:

• Global - Administrator

• Global - Approver

• Global - Auditor

They give corresponding permissions on Global scope so on every object of your instance.

Domain user groups

They are created for each domain you add. For example, if you create a domain R&D, there will be:

• R&D - Domain Manager

• R&D - Analyst

• R&D - Approver

• R&D - Auditor

They give corresponding permissions on the domain scope so on every object inside R&D.

• Translating the libraries (in-coming)

Bonus: By changing the application language, any framework that is translated to that language will switch automatically to it.

Outline

1. Pick or define a framework

2. Declare entities, solutions and representatives (enable user creation)

3. Trigger an entity assessment with audit enabled

4. The (external) representative will get a link to connect to the instance, answer the questions and attach evidences

5. The (internal) analyst will review the answers and make an opinion/decision

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.

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.

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.

This work-in-progress section will host the content for CISO Assistant Academy that will illustrate the user journey around standard use cases.

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.