verify

The purpose of verify is to detect verification errors in your threat model document.

The verify actions allows:

  • uses who are not experts at creating threat models to get feedback on a partially complete threat model document, telling them about issues that need to be resolved before a threat model should be submitted for approval

  • an approver of a threat model to get a degree (but not complete) assurance that a threat model has been populated and is free of various common mistakes/omissions/errors

Parameters

verify 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 (e.g. Confluence, Google Doc) specified by scheme)

  • doctemplate - the document ID of the threat model template document (in the document location (e.g. Confluence, Google Doc) specified by scheme)

  • reports - what reports to return in addition to the verification issues

    • none - (the default) do not return any reports

    • assets - return a report showing the controls covering each asset per (in-scope) storage location

    • controls - return a report showing which assets each control covers per (in-scope) storage location

    • all - return all (i.e. assets and controls) reports

Examples

Lambda

Using verify with threatware as a lambda, to verify a threat model document in Confluence:

https://<lambda-url>/threatware?format=html&action=verify&scheme=confluence_1.0&docloc=123456&doctemplate=67890

Note: we only need to pass in the document ID (docloc=123456) because the scheme parameter is set to confluence_1.0, which configures threatware to look for a Confluence page with that ID using the Confluence location and credentials configured for Authentication

Tip

For the verify action threatware supports returning an HTML version of the threat model where any errors are highlighted and tooltips are present to describe the error.

It’s a much nicer experience (compared to looking through JSON output) and is recommended for anyone using the verify action. However, the reports parameter will be ignored when the format is html.

API

Using verify with threatware as an API, to verify a threat model document in Confluence:

https://<api-hostname>/verify?format=html&scheme=confluence_1.0&docloc=123456&doctemplate=67890

Note: we only need to pass in the document ID (docloc=123456) because the scheme parameter is set to confluence_1.0, which configures threatware to look for a Confluence page with that ID using the Confluence location and credentials configured for Authentication

CLI

Using verify threatware as a CLI, to verify a threat model document in Google Docs:

python3 -m actions.handler verify -scheme googledoc_1.0 -docloc 123456 -doctemplate 67890 -reports all

Note: we only need to pass in the document ID (docloc=123456) because the scheme parameter is set to googledoc_1.0, which configures threatware to look for a Google Document with that ID using the Google credentials configured for Authentication

Practically, you’ll likely want to redirect the output of the command to a file to review the results e.g.

python3 -m actions.handler verify -scheme googledoc_1.0 -docloc 123456 -doctemplate 67890 -reports all > results.json

or

python3 -m actions.handler -f html verify -scheme googledoc_1.0 -docloc 123456 -doctemplate 67890 > results.html