Merge pull request #343 from iriusrisk/release/1.21.0

Release/1.21.0 to main

Author: dfernandezvigo

_sl_build/modules.py

@@ -21,8 +21,7 @@
     {'name': 'slp_visio', 'type': 'processor', 'provider_type': 'VISIO', 'allowed_imports': _slp_allowed_imports},
     {'name': 'slp_visio', 'type': 'processor', 'provider_type': 'LUCID', 'allowed_imports': _slp_allowed_imports},
     {'name': 'slp_mtmt', 'type': 'processor', 'provider_type': 'MTMT', 'allowed_imports': _slp_allowed_imports},
-    # TODO Set type to processor to make the endpoint available
-    {'name': 'slp_drawio', 'provider_type': 'DRAWIO', 'allowed_imports': _slp_allowed_imports}
+    {'name': 'slp_drawio', 'type': 'processor', 'provider_type': 'DRAWIO', 'allowed_imports': _slp_allowed_imports}
 ]
 
 """

docs/Quickstart-Guide-for-Beginners.md

@@ -145,7 +145,7 @@ If we take the same mapping file we have downloaded for the `parse` command, we
 
 #### **Diagram mapping files**
 Also described in the processors' documentation, allows you to validate the format of mapping
-files used for diagram conversions as Visio and Lucidchart. 
+files used for diagram conversions as Visio, Lucidchart and Drawio. 
 
 Let's download the IriusRisk's Visio mapping file located in the `examples/visio` folder:
 ```shell
@@ -163,6 +163,12 @@ You can also validate Lucidchart mapping files like it is shown in this example:
     ```shell
     startleft validate --mapping-file iriusrisk-lucid-aws-mapping.yaml --mapping-type LUCID
     ```
+To validate the  IriusRisk's Drawio mapping file located in the `examples/drawio` folder:
+???+ example "Drawio example"
+
+    ```shell
+    startleft validate --mapping-file iriusrisk-drawio-mapping.yaml --mapping-type DRAWIO
+    ```
 #### **External Threat Model mapping files**
 The last type of mapping file we can validate is External Threat Model. This allows you to validate the format of mapping
 files used for External Threat Model conversions as MTMT (Microsoft Threat Modeling Tool):

docs/index.md

@@ -44,6 +44,7 @@ Split by type, the currently supported input formats are:
 
 * **Diagram**:
     * Microsoft Visio (including diagrams exported from Lucidchart).
+    * Drawio
 
 * **Threat Model**:
     * Microsoft Threat Modeling Tool (MTMT).

docs/startleft-processors/diagram/drawio/Drawio-Calculating-Shape-Type.md

@@ -0,0 +1,57 @@
+!!! note ""
+    
+    This page explains how the drawio processor analyzes the shape data to retrieve its `type`
+    to be used as a value when mapping.
+
+The basics of parsing Drawio diagrams and generating threat models is to categorize the 
+shapes into their corresponding component type.
+
+A wide variety of stencils are available at Drawio (even custom). 
+The scope of this processor is to map a subset of these stencils as indicated below.
+
+### Mapping of AWS Stencils
+
+---
+This AWS Stencils can be found under the Networking Section:
+
+![img/shape-type/drawio-aws-stencils.png](img/shape-type/drawio-aws-stencils.png)
+
+Every shape available at those stencils follows the same `style` structure.
+
+Click Edit -> Edit Style...
+
+![img/shape-type/drawio-aws-shape-edit-style.png](img/shape-type/drawio-aws-shape-edit-style.png)
+
+The shape attribute has the information of which type this shape belongs.
+
+![img/shape-type/drawio-aws-shape-style.png](img/shape-type/drawio-aws-shape-style.png)
+
+For example: this shape can be categorized as `AWS EMR (Elastic MapReduce)`.
+
+There are some exceptional cases where the `shape` attribute is not enough 
+and an attribute equivalence has to be used to get the type.
+
+| shape        | equivalence |
+|--------------|-------------|
+| group        | grIcon      |
+| groupCenter  | grIcon      |
+| resourceIcon | resIcon     |
+| productIcon  | prIcon      |
+
+For example, as the shape AWS SNS (Simple Notification Service) has the attribute `productIcon`, 
+then the `prIcon` value will be used instead.
+
+![img/shape-type/drawio-aws-shape-style-pr-icon.png](img/shape-type/drawio-aws-shape-style-pr-icon.png)
+
+> As many components are repeated in different Stencils available and the only difference is the prefix mxgraph.aws[3/4],
+> this prefix is simplified to aws. For example, the `prIcon=mxgraph.aws4.sns` is read as `shape_type: aws.sns`
+
+### Mapping of mxGraph Stencils
+
+---
+Many other stencils at drawio use the previous logic of `shape=mxgraph.{group}.{type}` within their style 
+which we can use to get the type.
+
+When this info is available, the processor will read it and remove the `mxgraph.` prefix to set the `shape_type`.
+For example, the `prIcon=mxgraph.android.phone2` is read as `shape_type: android.phone2`
+

docs/startleft-processors/diagram/drawio/Drawio-Mapping.md

@@ -0,0 +1,82 @@
+# Drawio mapping
+
+
+---
+
+??? note "This mapping configuration only applies to Drawio Processor."
+
+    Please refer to another mapping file configuration documentation if needed. 
+    You can locate each processor's documentation in the left menu under the "StartLeft Processors (SLP)" section. 
+
+A source mapping file (or 'mapping file' for short) describes how to find and map components and
+trust zones in the source Drawio file.
+
+This mapping file is divided into two sections. The syntax and available functions used to define trust zone and 
+component mappings are identical.
+
+* `trustzones`.
+* `components`.
+
+## How mapping works?
+Every shape in the diagram is loaded by the Drawio processor along with its name and internal Drawio type. Extracting 
+the type is a key part of the parsing process and is explained in deep [here](Drawio-Calculating-Shape-Type.md).
+
+Once the shapes are loaded, the mapping files are used to change the type of the components to the one expected in the 
+OTM file. If no coincidence is found, a default type (`empty-component`) is set.
+
+### Mapping preference
+There are two mapping files, the default and the custom ones. Inside them, there are trust zone and component mappings.
+The shapes in the Drawio files can be mapped by its type or name. The preference is the following:
+
+1. Custom mappings prevails over default mappings.
+2. Name matches during mapping prevails over type matches.
+3. Trust zone mappings prevails over component mappings.
+    
+### Mapping functions
+Both for components or trust zones, there are different ways to define mappings. A set of functions are available to 
+simplify the creation of the mapping file. These functions work for mapping by name or type.
+
+#### Mapping by exact match
+The simplest case, when the `label` in the mapping file matches exactly the component name or type.
+
+```yaml
+  - label: aws.s3
+    type: s3
+```
+
+#### Mapping by a Regex
+Instead of searching for an exact match, a regex can be used to leverage the mapping capabilities.
+
+```yaml
+  - label: {$regex: ^aws.s3\_.*$}
+    type: s3
+```
+
+#### Mapping by list
+It is used when a group of name or types must be mapped to the same type in the OTM.
+
+```yaml
+  - label:
+      - aws.ec2
+      - aws.ec2_c6a_instance
+      - aws.ec2_c6gn_instance
+      - aws.ec2_c6i_instance
+      - aws.ec2_c6in_instance
+    type: ec2
+```
+
+### The Default Trust Zone
+The [OTM standard](../../../Open-Threat-Model-(OTM).md) defines that every component in the
+threat model must have a parent. Frequently, the original Drawio diagram has components that are not nested inside any
+parent. In those cases, the trust zone set as a default in the mapping file is included in the OTM as their parent.
+
+```yaml
+  - label: Public Cloud
+    type: public-cloud
+    default: true
+```
+
+!!! note ""
+    Notice that this Trust Zone can be created more than once. If there is a component in the original diagram called
+    "Public Cloud", a Trust Zone object will be created in the OTM. Then, if there are some missing components, a
+    default Trust Zone of the same type will be created again to gather them.