update readme files

README.md

@@ -129,9 +129,9 @@ Checkout the [library](/backend/library/libraries/) and [tools](/tools/) for the
 - UK Cyber Essentials
 - and much more: just ask on [Discord](https://discord.gg/qvkaMdQ8da). If it's an open standard, we'll do it for you, _free of charge_ 😉
 
-### Add your own framework
+### Add your own library (framework, threat catalog, reference controls catalog or matrix)
 
-Have a look in the tools directory and its dedicated readme. The convert_framework.py script will help you create your library from a simple Excel file. A typical framework can be ingested in a few hours.
+Have a look in the tools directory and its dedicated readme. The convert_library.py script will help you create your library from a simple Excel file. A typical framework can be ingested in a few hours.
 
 You will also find some specific converters in the tools directory (e.g. for CIS or CCM Controls).
 

tools/README.md

@@ -1,6 +1,6 @@
 # Library workbench
 
-The convert-framework.py script can be used to transform an Excel file to a CISO Assistant library.
+The convert-library.py script can be used to transform an Excel file to a CISO Assistant library.
 
 Have a look to the given examples.
 
@@ -9,7 +9,7 @@ Have a look to the given examples.
 To launch it, open a shell in a command line, and type:
 
 ```bash
-python convert-framework.py your_library_file.xlsx
+python convert-library.py your_library_file.xlsx
 ```
 
 This will produce a file name your_library_file.yaml
@@ -20,26 +20,34 @@ This will produce a file name your_library_file.yaml
 Conventions:
     | means a cell separation, <> means empty cell
     The first tab shall be named "library_content" and contain the description of the library in the other tabs
-        library_urn                 | <urn>
-        library_version             | <version>
-        library_locale              | <en/fr/...>
-        library_ref_id              | <ref_id>
-        library_name                | <name>
-        library_description         | <description>
-        library_copyright           | <copyright>
-        library_provider            | <provider>
-        library_packager            | <packager>
-        library_dependencies        | <urn1, urn2...
-        framework_urn               | <urn>
-        framework_ref_id            | <ref_id>
-        framework_name              | <name>
-        framework_description       | <description>
-        reference_control_base_urn  | <base_urn>            | id
-        threat_base_urn             | <base_urn>            | id
-        tab                         | <tab_name>            | requirements       | <section_name>
-        tab                         | <tab_name>            | threats            | <base_urn>
-        tab                         | <tab_name>            | reference_controls | <base_urn>
-
+        library_urn                | <urn>
+        library_version            | <version>
+        library_locale             | <en/fr/...>
+        library_ref_id             | <ref_id>
+        library_name               | <name>
+        library_description        | <description>
+        library_copyright          | <copyright>
+        library_provider           | <provider>
+        library_packager           | <packager>
+        library_dependencies       | <urn1, urn2...
+        framework_urn              | <urn>
+        framework_ref_id           | <ref_id>
+        framework_name             | <name>
+        framework_description      | <description>
+        framework_min_score        | <min_score>
+        framework_max_score        | <max_score>
+        reference_control_base_urn | <base_urn> | id
+        threat_base_urn            | <base_urn> | id
+        risk_matrix_urn            | <urn>
+        risk_matrix_ref_id         | <ref_id>
+        risk_matrix_name           | <name>
+        risk_matrix_description    | <description>
+        tab                        | <tab_name> | requirements
+        tab                        | <tab_name> | threats            | <base_urn>
+        tab                        | <tab_name> | reference_controls | <base_urn>
+        tab                        | <tab_name> | scores
+        tab                        | <tab_name> | implementation_groups
+        tab                        | <tab_name> | risk_matrix
 
     For requirements:
         If no section_name is given, no upper group is defined, else an upper group (depth 0) with the section name is used.
@@ -64,6 +72,16 @@ Conventions:
             - description
             - category (policy/process/techncial/physical).
             - annotation
+    For risk matrices:
+        The first line is a header, with the following mandatory fields:
+            - type: probability/impact/risk.
+            - id: a number from 0 to n-1 (depending of the number of objects for a given type)
+            - abbreviation: the abbreviation for the object
+            - name: name of the object
+            - description: description of the object
+            - grid: several columns describing the matrix with colors.
+        The grid shall be aligned with the probability objects, the columns being the impact in order of id, and the content of each cell being the id of the risk.
+        This is a topological representation. The display on the screen (transposition, direction of axes) will be managed in the frontend, not in the data model. 
     A library has a single locale. Translated libraries have the same urns, they are merged during import.
     Dependencies are given as a comma or blank separated list of urns.
 ```