convert
The purpose of the convert
action is to convert a threat modelling document to a model of the document, according to a scheme. The model is the common format of the document, only containing relevant information, that other actions operate on.
Common uses of the convert
action include:
Verifying/debugging the scheme definition is correct by manual inspection of the output of
convert
(a.k.a a model of the document)Determining if all appropriate information in the threat model is being captured (as the output of
convert
is stored by threatware’smanage
actions)To capture the model of the threat modelling document for manually putting in storage
To feed the model of the threat modelling document to some other process
convert
takes the following parameters
scheme
- the scheme name to use. This defines how to convert the threat model document to the model format.docloc
- the document ID of the threat model document (in the document location specified byscheme
)meta
- defines which meta data should be captured in the output model. The output model is just a hierarchy of key/value pairs. They keys have associated metadata e.g. a tag indicating how to validate the value. Possible values are:none
- the output model will contain no additional metadata relating to the keys. This is useful for capturing just the data of a threat model (with no threatware specific key metadata), which is useful for passing to other processes, or to be consumed by humans.tags
- (default value) the output model will contain the tags that are associated to each key (tags are defined in the scheme file). This is useful for debugging issues with the scheme definition.properties
- the output model will contain the tags and properties associated to each key (properties are metadata captured during the coverting of the document). This is useful for advanced debugging of issues with the scheme definition. Theproperties
value should only be used when the output format parameter isyaml
, as json is not (natively) capable of complex objects as keys. This format is a complete internal representation of what threatware uses, and the only format that threatware can consume when a model is stored (relevant for somemanage
actions).
Examples:
Using convert
with threatware as a lambda to debug a scheme definition, being used on a threat model document in Confluence. This relies on the default value of meta
= tags
:
https://<lambda-url>/threatware?action=convert&scheme=confluence_1.0&docloc=123456
Using convert
threatware as a CLI to generate a human readable version of a threat model document in Google Docs
python3 -m actions.handler convert -scheme googledoc_1.0 -docloc 123456 -meta none