ciso-assistant-community MCP工具

Requirements

• Python 3.14+
• pip 25.3+
• poetry 2.0+
• node 24+
• npm 10.2+
• pnpm 10.30+
• yaml-cpp (brew install yaml-cpp libyaml or apt install libyaml-cpp-dev)

<details> <summary>[EXPERIMENTAL] Additional requirements for development on Windows without WSL2</summary>

If you want to develop the project without WSL2, you will need to install MSYS2, add the MSYS2 UCRT64 binaries to your system PATH environment variable (usually, the binaries are in C:\msys64\ucrt64\bin) and then install the following dependencies via pacman using MSYS2 UCRT64.

pacman -S mingw-w64-ucrt-x86_64-file mingw-w64-ucrt-x86_64-pango

You will also have to add those 2 system environment variables after installing the dependencies:

MAGIC=Full path to the `magic.mgc` file (usually `C:\msys64\ucrt64\share\misc\magic.mgc`)
WEASYPRINT_DLL_DIRECTORIES=Same path as your MSYS2 UCRT64 binaries

Given that the default encoding on Windows isn't UTF-8 but cp1252, certain python script printing UTF-8 characters such as emojis may cause the backend crash or malfunction in some cases (e.g. library importation). To avoid this issue with this project, enforce the UTF-8 encoding by adding these 2 user environment variables:

PYTHONUTF8=1
PYTHONIOENCODING=utf-8:replace

[!NOTE] ### Known issues - The libmagic library on Windows (MIME detection) struggles to recognize an Excel file (.xlsx) by reading its first 2048 bits as it returns application/octet-stream most of the time when importing an Excel library (backend displays the warning message [warning ] Invalid MIME type). This doesn't prevent the Excel file from being imported thanks to the fallback method in backend/library/views.py:StoredLibraryViewSet.upload_library.

</details>

Requires AZURE_ACCOUNT_NAME. The pod/VM's assigned managed identity is used automatically.

Setup a development mailer with Mailhog for example

export EMAIL_HOST_USER='' export EMAIL_HOST_PASSWORD='' export DEFAULT_FROM_EMAIL=ciso-assistant@ciso-assistantcloud.com export EMAIL_HOST=localhost export EMAIL_PORT=1025 export EMAIL_USE_TLS=True # true for STARTTLS export EMAIL_USE_SSL=False # true for SMTPS

**Other variables**

CISO Assistant will use SQLite by default, but you can setup PostgreSQL by declaring these variables

export POSTGRES_NAME=ciso-assistant export POSTGRES_USER=ciso-assistantuser export POSTGRES_PASSWORD=<XXX> export POSTGRES_PASSWORD_FILE=<XXX> # alternative way to specify password export DB_HOST=localhost export DB_PORT=5432 # optional, default value is 5432

S3 Authentication Option 1: Access Key (for standalone deployments or S3-compatible services)

export AWS_ACCESS_KEY_ID=<XXX> export AWS_SECRET_ACCESS_KEY=<XXX> export AWS_S3_ENDPOINT_URL=<your-bucket-endpoint> # required for S3-compatible services (e.g., MinIO)

S3 Authentication Option 2: IRSA (for Kubernetes/EKS deployments)

Azure Authentication Option 3: Managed Identity (for Azure-hosted deployments)

Non-root docker containers

docker-compose.yml now relies on a non-root user 1001:1001, which is available in the image. Older deployments are using root user, which is still supported. To transition to non-root, use the following steps in the host: - docker compose down - update the docker-compose.yml file - sudo chown -R 1001:1001 db - docker compose up -d

Quick Start 🚀

[!TIP] The easiest way to get started is through the free trial of cloud instance available here.

Alternatively, once you have Docker and Docker-compose installed, on your workstation or server:

clone the repo:

git clone --single-branch -b main https://github.com/intuitem/ciso-assistant-community.git

and run the starter script

./docker-compose.sh     # Linux/MacOS
./docker-compose.ps1    # Windows

If you are looking for other installation options for self-hosting, check the config builder and the docs.

[!NOTE] The docker-compose script uses prebuilt Docker images supporting most of the standard hardware architecture. If you're using Windows, make sure to have Docker Desktop with WSL2 installed and trigger the PowerShell script. It will feed Docker Desktop on your behalf.

The docker compose file can be adjusted to pass extra parameters to suit your setup (e.g. Mailer settings).

[!WARNING] If you're getting warnings or errors about image's platform not matching host platform, raise an issue with the details and we'll add it shortly after. You can also use docker-compose-build.sh instead (see below) to build for your specific architecture.

[!CAUTION] Don't use the main branch code directly for production as it's the merge upstream and can have breaking changes during our development. Either use the tags for stable versions or prebuilt images.

---

export AZURE_CUSTOM_DOMAIN=<your-custom-domain> # optional, e.g., cdn.example.com

Setting up the local AI engine

Read more here: AI engine

Optional: converting libraries to YAML

While Excel files can be loaded directly, it is still possible to convert library source files to YAML using external Python scripts:

• convert_library_v2.py helps you generate a library from a simple Excel file. Once your items are structured in the expected format, run the script to produce the corresponding YAML file.
• The tools directory also contains specialized converters for specific frameworks (for example, CIS or CCM Controls).

Setting up CISO Assistant for development

[!WARNING] ### Important note for Windows users The best working solution for users developing on Windows is to use Ubuntu installed on WSL2 (Docker is not required). It is now also possible to run and develop CISO Assistant natively on Windows without WSL2 nor Docker, but it will require some extra steps. Please note that the native running on Windows is still in EXPERIMENTAL PHASE and should NOT be used if you are unsure of what you are doing, or if you want to ensure stability throughout development. Nevertheless, we would love to hear any suggestions in order to enhance the development experience for Windows users. Please feel free to open an Issue/PR about it!

these environment variables are automatically injected by the pod's service account.

No explicit configuration is needed - just ensure USE_S3=True and AWS_STORAGE_BUCKET_NAME are set.

export AZURE_LOCATION=<path-prefix> # optional, path prefix within the container (e.g., "media")

Azure Authentication Option 1: Account Key

Azure Authentication Option 2: Connection String

To set a fixed secret key, use the environment variable DJANGO_SECRET_KEY.

export DJANGO_SECRET_KEY=...

WARNING: Sandboxing must be enabled in production environments.

export ENABLE_SANDBOX=True # optional, default value is True in production enfironments (DJANGO_DEBUG=False) and False in development environments (DJANGO_DEBUG=True).

Logging configuration

export LOG_LEVEL=INFO # optional, default value is INFO. Available options: DEBUG, INFO, WARNING, ERROR, CRITICAL export LOG_FORMAT=plain # optional, default value is plain. Available options: json, plain

Authentication options

export AUTH_TOKEN_TTL=3600 # optional, default value is 3600 seconds (60 minutes). It defines the time to live of the authentication token export AUTH_TOKEN_AUTO_REFRESH=True # optional, default value is True. It defines if the token TTL should be refreshed automatically after each request authenticated with the token export AUTH_TOKEN_AUTO_REFRESH_TTL=36000 # optional, default value is 36000 seconds (10 hours). It defines the time to live of the authentication token after auto refresh. You can disable it by setting it to 0.

3. Install poetry

Visit the poetry website for instructions: <https://python-poetry.org/docs/#installation>

<details>
<summary>[EXPERIMENTAL] How to install Poetry natively on Windows?</summary>

</details>


4. Install required dependencies.

5. Recommended: Install the pre-commit hooks.

6. If you want to setup Postgres:

- Launch one of these commands to enter in Postgres:
  - `psql as superadmin`
  - `sudo su postgres`
  - `psql`
- Create the database "ciso-assistant"
  - `create database ciso-assistant;`
- Create user "ciso-assistantuser" and grant it access
  - `create user ciso-assistantuser with password '<POSTGRES_PASSWORD>';`
  - `grant all privileges on database ciso-assistant to ciso-assistantuser;`

7. If you want to setup s3 bucket:

- Choose your s3 provider or try s3 feature with miniO with this command:
  - `docker run -p 9000:9000 -p 9001:9001 -e "MINIO_ROOT_USER=XXX" -e "MINIO_ROOT_PASSWORD=XXX" quay.io/minio/minio server /data --console-address ":9001"`
- You can now check your bucket on <http://localhost:9001>
  - Fill the login with the credentials you filled on the docker run env variables
- Export in the backend directory all the env variables asked about S3
  - You can see the list above in the recommanded variables

8. Apply migrations.

9. Create a Django superuser, that will be CISO Assistant administrator.

> If you have set a mailer and CISO_SUPERUSER_EMAIL variable, there's no need to create a Django superuser with `createsuperuser`, as it will be created automatically on first start. You should receive an email with a link to setup your password.

10. Run development server.

<details> <summary>[EXPERIMENTAL] How to run development server natively on Windows?</summary>

When running Django's development server natively on Windows, SvelteKit SSR can open enough concurrent API connections to hit the server's small default listen backlog. This may cause intermittent ECONNREFUSED / TypeError: fetch failed errors in the frontend.

Use the helper scripts documented in tools/.windows/README.md for the native Windows development setup.

</details>

1. For Huey (tasks runner)

• prepare a mailer for testing.
• run python manage.py run_huey -w 2 -k process or equivalent in a separate shell.
• you can use MAIL_DEBUG to have mail on the console for easier debug

Setting CISO Assistant for production

The docker-compose.yml highlights a relevant configuration with a Caddy proxy in front of the frontend. It exposes API calls only for SSO. Note that docker-compose.yml exposes the full API, which is not yet recommended for production.

Set DJANGO_DEBUG=False for security reasons.

[!NOTE] The frontend cannot infer the host automatically, so you need to either set the ORIGIN variable, or the HOST_HEADER and PROTOCOL_HEADER variables. Please see the sveltekit doc on this tricky issue. Beware that this approach does not work with "pnpm run dev", which should not be a worry for production.

[!NOTE] Caddy needs to receive a SNI header. Therefore, for your public URL (the one declared in CISO_ASSISTANT_URL), you need to use a FQDN, not an IP address, as the SNI is not transmitted by a browser if the host is an IP address. Another tricky issue!

[!NOTE] The docker-compose template files are now launching the backend, huey and frontend in non-root mode. If you use an old docker-compose.yml file, it is recommended to update it. The containers are compatible with both root and non-root modes.

API and Swagger

- The interactive API documentation (Swagger UI) is available only in development mode. To enable it, set export DJANGO_DEBUG=True before starting the backend. - Once the server is running, the documentation will be accessible at <backend_endpoint>/api/schema/swagger/, for example: <http://127.0.0.1:8000/api/schema/swagger/>.

To interact with the API via Swagger or directly with HTTP calls:

1. Authenticate by sending a POST request to /api/iam/login/ with your credentials in the request body. The response will include an authentication token.
2. Include this token in the header of subsequent requests as: Authorization: Token <token>

⚠️ Note: use Token, not Bearer.

When using the interactive Swagger UI, simply log in, the token will be automatically handled for subsequent requests.

this [topic](https://stackoverflow.com/questions/15170637/effects-of-changing-djangos-secret-key) for more information).