Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Small tutorial to learn how to create your first project and be prepared for risk and compliance assessment
Once logged in, the first step is to create a domain. Let's call it R&D.
Then we create the project inside of it or from the project list view.
That's it! you just created your first project. The next step will be to create a compliance assessment.
This is CISO Assistant documentation. You'll find advice on how to get started, and details on our vision of risk and compliance assessment.
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)
CISO Assistant is open source, so you can find our source code on GitHub and implement it yourself or go to our website to request a cloud trial instance. Please read the full article about the community editions on our blog.
We've put together some helpful guides for you to get setup with our product quickly and easily.
We've detailed our model to help you understand how everything is organized
Small tutorial to learn how to create your first compliance assessment
After creating the project, we'll have to import a framework, for example ISO/IEC 27001:2022.
Once it is imported, we can now create the compliance assessment (ISO/IEC 27001:2022 is auto-selected as it is the only imported framework).
You can edit it if needed, or go directly into the assessment. Each requirement has a To do status by default.
Finally, we can select a requirement and start its assessment by adding applied controls or evidences and update its status to complete the progress bars.
Now that you're familiar with compliance assessment, let's go a step further with risk assessment.
Small tutorial to learn how to create your first compliance assessment
Firstly, we need to import some external objects before starting our risk assessment: a matrix, threats and reference controls.
We can create the risk assessment, and let's take a look inside.
We find three parts: details about the assessment, the list of associated risk scenarios and the risk matrix view.
Let's add the first scenario and do the current assessment of it.
You can see that I didn't find the threat I was looking for in the imported library, so I decided to create my custom threat.
From now on, you won't necessarily follow the same steps depending on your needs. In this example I choose to mitigate the scenario by creating an applied control for it.
We go back in the scenario edit view, add the freshly created applied control, do the residual assessment and choose a strength of knowledge level.
As you can see, back in the risk assessment view, the current and residual scenario were added in matrix views with a diamond to indicate the strength of knowledge. To find out more about this concept, take a look at the Risk analysis introduction from the Society of Risk Analysis.
Manage your assessments over time
The main page to drive your projects through time. You can focus on risk or compliance assessment with their respective tab or have a global view from the governance one.
You can find on the bottom of the governance tab an applied controls ranking score and a watch list to warn you about incoming deadlines on applied controls or risk acceptances.
Applied controls ranking score table is here to help you prioritize
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.
An integrated calendar to track the ETA of upcoming/expired applied controls or risk acceptances.
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.
Establishing a security posture in flashcards mode
Some useful tools for following up assessments
X-rays is a very useful page to detect inconsistencies across your assessments for each project. 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
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
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.
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.
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.
Configure Single Sign-On with different SAML providers
Log in into CISO Assistant as an administrator > Extra > Settings
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
Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.
Configure Microsoft Entra ID as an Identity Provider for CISO Assistant
Go into your Azur portal home
Open the sidebar menu and click on Microsoft Entra ID
Click on Add button > Entreprise application
Click on Create your own application
Enter a name and then click Integrate any other application you don’t find in the gallery (Non-gallery)
Click on Single sign-on from the sidebar menu or on Set up single sign on bellow Getting Started and choose SAML
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)
Add the Reply URL: <base_url>/api/accounts/saml/0/acs/
(for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/
)
In the third box SAML Certificates, copy the App Federation Metadata Url as it is the Metadata URL in CISO Assistant (see next screenshot)
In the fourth box Set up <App_name>, copy the Microsoft Entra Identifier as it is the IdP Entity ID in CISO Assistant
Click on Users and groups in the sidebar menu, and Add user/group to give them access to CISO Assistant with SSO
Add a user in your application doesn't automatically create the user on CISO Assistant
Configure Okta as an Identity Provider for CISO Assistant
Go into your Okta admin console (it should look like this: https://<your_url>.okta.com/admin/dashboard
)
In the sidebar menu, click on Applications > Applications
Click now on Create App Integration
Select SAML 2.0 and click on Next
Choose an App name and click on Next
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)
Add the Audience URI (SP Entity ID), it has to be the same than SP Entity ID in CISO Assistant (see screenshot below)
Choose Email as the Application username
Add Attribute Statements
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
for user's first name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
for user's last name
Click on Next and fill in the Feedback page as you wish then click on Finish
In the Settings box inside SAML 2.0:
Copy the Metadata URL and paste it into the Metadata URL field in CISO Assistant
Copy the Issuer url and paste it into the IdP Entity ID field in CISO Assistant
Go to the Assignments tab
Click on Assign and choose whether you want to assign users or specific groups
Add a user in your application doesn't automatically create the user on CISO Assistant
You can now with the 3 parameters you've retrieved.
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:
Configure Keycloak as an Identity Provider for CISO Assistant
If Keycloak and CISO Assistant are both deployed locally with docker, you'll need to make sure that both containers can communicate together. You can do this with a bridge network.
Go into your Keycloak admin console
Open the sidebar menu > Clients and Create client
Choose SAML client type and name it ciso-assistant or with your custom SP Entity ID
Fill the Home URL by your <base_url>
and Valid redirect URIs by <backend_url/*>
If you have some problems to configure these urls you can ask for help on Discord or by mailing us
Go into Keys and disable Signing keys config
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/>
)
Go to Client scopes and click on ciso-assistant-dedicated
Add a predefined mapper and check all X500 ones
Click on X500 surname and replace SAML Attribute name by http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Click on X500 givenName and replace SAML Attribute name by http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Go into Realm settings > General, you will find the Metadata URL
You'll find inside the Metadata URL the Entity ID
Add a user in your application doesn't automatically create the user on CISO Assistant
You can now configure CISO Assistant with the 3 parameters you've retrieved.
Configure Google Workplace as an Identity Provider for CISO Assistant
Google Workspace doesn't allow callbacks to urls containing http
or localhost
so it can be tricky to test it locally. You should deploy CISO Assistant with a FQDN to bypass these restrictions.
Go into Google Workspace Admin console
On the sidebar menu, go to Applications > Web and mobile applications
Click on Add an application > Add a custom SAML Application
Enter ciso-assistant or the name of your choice and click on continue
You can copy the SSO URL, Entity Id and x509 certificate here but you'll be able to retreive them later
Fill ACS URL with <base_url>/api/accounts/saml/0/acs/
, enter the Entity 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
Add two mappings for First name and Last Name, fill them with those two values: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
On application home page, you can now find the Entity ID, SSO URL and x509 certificate
Add a user in your application doesn't automatically create the user on CISO Assistant
You can now configure CISO Assistant with the 3 parameters you've retrieved.
You can find here CISO Assistant global organization. All entities will be linked to or contained within these objects.
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.
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 projects, or if you have different customers, you may as well have a domain for each one in order to delimit your work area.
A domain is the first thing you create on CISO Assistant. It will bring together all objects you need to complete your different projects. 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.
Projects 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 project 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.
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.
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.
Let's give some details on the 5 built-in roles:
Django superuser is given administrator rights automatically on startup.
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.
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.
Role | Permissions |
---|
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 projects/domains. Read access to global and domain objects |
Auditor | read access to selected projects/domains |
Approver | like reader, but with additional capability to approve risk acceptances |
You will set here documents and items that are used as a basis for assessments.
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.
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 is the place to define the context for risk and compliance management. All items here are optional.
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 are can be imported from a library, but you can create your own threats in the global domain or in a specific domain.
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 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.
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.
This is where you can carry out your compliance work based on the framework of your choice.
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!
This allows you to assess your compliance with the chosen framework through different statuses for each requirement that requires one of the following:
To do
In progress
Non compliant
Partially compliant
Compliant
Not applicable
Evaluate a requirement inside a compliance assessment is called requirement assessment
Evidence allows you to use a description, link or file to justify the status of a compliance requirement or to prove that a control has been applied. They can therefore be associated with different applied controls or requirement assessments.
Hardware Requirements:
CPU: Minimum 2 cores (3 recommended)
RAM: Minimum 2 GB (4 recommended)
Storage: Minimum 1 GB available (+10 GB recommended for evidence storage )
Software Requirements:
Ubuntu/Debian, CentOS, RHEL: LTS versions recommended*
Docker 25 or up, with Docker compose, or Kubernetes Cluster 1.29 or up
Postgres 15 or up
Any SMTP compatible Mailer
*most Linux distributions supporting Docker should be compatible but have not been tested.
This is where risk analyses are managed, from definition to potential acceptance.
You can create risk assessments in your projects. 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.
The scenarios can be defined directly from the risk assessment view or separately via this view.
Risk acceptance is when an organization or individual decides to tolerate a certain level of risk without taking further action to reduce it. This view allows to manage a workflow to get formal approval of risk acceptances by the management. The approver of a risk acceptance must have a user account with approver role. To find out more about risk acceptance, you can have a look to the ENISA risk management process.
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 Windows, Docker Desktop+WSL is recommended
On MacOS, Docker Desktop covers the requirements
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.
Alternatively, if the previous configuration didn't succeed, run:
Given that Caddy is using a self-signed certificate
, your browser will mention a warning that you can accept and continue.
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
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 docker-based 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> python manage.py createsuperuser
and you should get a prompt now 😉
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.
Backup your db file outside of the repo folder, always a good practice
cp db/ciso-assistant.sqlite3 ../ciso-assistant-backup.sqlite3
Stop the containers
docker compose stop
Delete the containers instances (you will need to confirm)
docker compose rm
Clean up the previous docker images
docker rmi ghcr.io/intuitem/ciso-assistant-community/backend:latest ghcr.io/intuitem/ciso-assistant-community/frontend:latest 2> /dev/null
Trigger compose up to refresh the images
docker compose up -d
importing CIS Controls
To import the CIS Controls, you need to prepare the file first. The easy way is to copy the Excel sheet as-is (CIS_Controls_Version_8.xlsx
) into the tools folder and run convert_cis.sh
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
Experimenting CISO Assistant through remote server or hypervisor
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.
Setup the following environment variables:
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 /tools
of the Github repository root.
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.
Clone the repo and make sure you are at its root
Make sure you have Python installed (including pip), version 3.11 or higher is recommended
cd to /tools
run
pip install -r requirements.txt
to install the script dependencies
copy the sample directory, including the file within, to a new directory at the same level, for instance, myframework/my-custom-framework.xlsx
Edit the first tab (library_content
) to describe your framework metadata
Implementation groups and score descriptions are optional, so if they don't apply, you can simply remove lines
Edit the Excel sheet according to the expected hierarchy.
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
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.
If everything is good, you'll get a message confirming the generation of the file generating myframework/my-custom-framework.yaml
Open CISO Assistant. On the side menu, go to Extra/Libraries
then to the Libraries store
tab
Scroll down to get to Upload your own library
section and select your file.
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
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: