> For the complete documentation index, see [llms.txt](https://intuitem.gitbook.io/ciso-assistant/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intuitem.gitbook.io/ciso-assistant/product-docs/contributing/framework.md).

# Frameworks and libraries

CISO Assistant's catalogue is extended through **libraries** — YAML files that bundle one or more catalogue objects. Anything you contribute under this path follows the same submission flow regardless of what's in the library.

## What you can contribute

A single library may contain:

* **Frameworks** — a hierarchy of requirements covering a standard, regulation, or internal control model.
* **Mappings** — directed graphs linking the requirements of one framework to another (NIST OLIR convention).
* **Threat catalogues** — reusable lists of threats referenced across frameworks and risk assessments.
* **Risk matrices** — probability × impact grids used by risk assessments.
* **Reference controls** — templates that applied controls can derive from.

Each of these can ship in its own library, or be bundled together where it makes sense (a framework with its companion reference-control catalogue, for example). See [Designing your own libraries](/ciso-assistant/product-docs/configuration/libraries/custom-libraries.md) for the format and authoring tooling.

## If you're comfortable with Git

1. Fork the [community repository](https://github.com/intuitem/ciso-assistant-community) and make sure it's in sync with `main`.
2. Add your Excel source under the `tools` folder.
3. Optionally also commit the generated YAML under `backend/library/libraries/` (only if you've tested that it loads cleanly).
4. Open a pull request and accept the **Contributor Licence Agreement** when prompted.

We'll take it from there.

## If you'd rather use the GitHub UI

The walkthrough below uses a framework as the example, but the same flow works for matrices, threat catalogues, mappings, and reference controls.

1. **Author the Excel source.** Start from one of the samples in `tools/` (frameworks) or `tools/excel/matrix/` (risk matrices). The library type drives which sample to copy.
2. **Convert it to YAML** using the `convert_library_v2.py` tool to validate the structure end-to-end.

<figure><img src="/files/WFbyS4PeLmyCUn0BSLwp" alt=""><figcaption></figcaption></figure>

3. **Test the YAML** by loading it into a local CISO Assistant instance and checking it renders as expected.

<figure><img src="/files/IWzPL5xoHoGW2KnfqjrO" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/oZY1UX8qfEEEAOhUriW8" alt=""><figcaption></figcaption></figure>

4. **Fork the repository** on GitHub (and make sure your fork is up to date if you've contributed before).

<figure><img src="/files/lmsXZln1NuD7y3e84QFo" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/86P4w73UXNG6WAybI7eS" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/AvIBh1HYTUY3Nm7RMKNs" alt=""><figcaption></figcaption></figure>

5. **Upload the Excel file** to the `tools/` folder via **Add file → Upload files**.

<figure><img src="/files/Ku6YxrMa7Xq0ohLyzcHk" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Mnv4yv7PNQGa29PsvtxW" alt=""><figcaption></figcaption></figure>

6. **Commit** with a clear message ("Submitting framework X" or "Submitting risk matrix Y").

<figure><img src="/files/ZuAedlzBhlWsad5AYkh9" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/vVeXHiBz1dRGxKclX633" alt=""><figcaption></figcaption></figure>

7. **(Optional)** repeat the upload step for the YAML under `backend/library/libraries/`.

<figure><img src="/files/LkrMAGJxhliab3kcj75X" alt=""><figcaption></figcaption></figure>

8. **Open the pull request** and accept the CLA when prompted.

<figure><img src="/files/FLXPZ0bK29X2ZZivGlxv" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/9aF1lSakiZhM0o1zbEIB" alt=""><figcaption></figcaption></figure>

## What we look for during review

* The Excel source compiles cleanly with `convert_library_v2.py`.
* URN prefixes don't collide with existing libraries.
* For frameworks: hierarchy depth stays reasonable; assessable vs structural nodes are correctly marked.
* For mappings: source and target framework URNs resolve; relationship types are valid (equal, subset, superset, intersect).
* For risk matrices: the probability/impact/risk grid is internally consistent.
* Licensing — only contribute content you're allowed to redistribute. Restrictively-licensed standards (CIS, CSA CCM) ship as converters, not bundled content.

## Related

* [Designing your own libraries](/ciso-assistant/product-docs/configuration/libraries/custom-libraries.md)
* [Libraries concept](/ciso-assistant/product-docs/concepts/catalog/libraries.md)
* [Mappings feature](/ciso-assistant/product-docs/features/mappings.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://intuitem.gitbook.io/ciso-assistant/product-docs/contributing/framework.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.