Skip to content

Latest commit

 

History

History
82 lines (50 loc) · 6.07 KB

README.md

File metadata and controls

82 lines (50 loc) · 6.07 KB
Raw

threatware

Simplifies the review and management of threat models in documents

threatware is an AWS lambda function (or CLI tool) with methods to help review threat models and provide a process to manage threat models. It works directly with threat models as Confluence/Google Docs documents.

Installation

threatware requires a recent version of python (3.9 or above, and you should have pip installed as well (instructions)) and that a recent version of git is installed (instructions). You may also want to consider installing threatware in a virtual environment

python3 -m pip install threatware

Download

threatware is available on PyPI https://pypi.org/project/threatware/

The documentation is hosted at: https://threatware.readthedocs.io

Code

The code and issue tracker are hosted on GitHub: https://github.com/samadhicsec/threatware

Details

Who is this for?

It's for people/teams who do threat modelling or want to do threat modelling.

threatware has different features to suit those who are beginning to threat model, and those who are experienced.

Beginners

  • threatware provides a Threat Modelling template that works out of the box. The template is available as either a Confluence page or a Google Doc. (no tool lock-in)
  • threatware documentation includes detailed instructions on how to populate the template, aimed at developers, not threat modelling experts. (scalable)
  • threatware can verify the populated Threat Model template and report back on errors and missing threats. (automation)
  • threatware can help define a management process for threat models by storing versioned: status, metadata and a model of your Threat Model document in a git repo of your choice. (auditors love this)

Intermediates

  • minor changes to the template (new table columns, changing header names) can easily be supported to allow capturing relevant data for your organisation. (flexible)
  • the basic Threat Modelling template can be pre-populated with common information relevant to different systems. (less effort to populate)
  • create many different templates for different tech stacks, with appropriate pre-populated values. (more relevant, less effort to populate)
  • threatware supports localisation. (increase adoption)

Experts

  • threatware allows extensive customisation of the template, by defining your own 'scheme' (which is used to parse the threat modelling document - it's a custom document definition language, sorry, we couldn't find an existing one that worked). If you have existing documents or specific information that you want gathered, you can define this.
  • the template can be part of existing product/system documentation, threatware will extract the relevant information (as defined by the 'scheme')
  • the verification of the threat model is customisable, and defined in configuration files, which allows enabling/disabling verification rules, or adding additional rules
  • the verification of the threat model is extensible (in python), as verification methods are dispatched via configuration files, so you can easily extend threatware by writing your own verifiers and updating configuration files to get them called

How do I use it?

Of course that is up to you, but here is an idea of how it has been successfully used (assuming you have installed threatware and configured it):

  1. Make a copy of the threat model template available somewhere in your orgnisation i.e. copy the default template somewhere local to your organisation
  2. When you need to create a threat model, make a copy of your local threat model template. This will be the document you edit.
  3. Identify the people who need to populate the template (i.e. system owners/experts) and point them at the documentation and how to invoke threatware verify
  4. Have sessions to begin populating the threat model. Use threatware verify to make sure no information is missing (look for reference-validation errors first). You'll like need 3-5 sessions, including off-line time spent populating.
  5. Use threatware verify to make sure your have threats covering all your assets (look for coverage-validation errors)
  6. Once threatware verify returns no errors, sense check the threat model for completness
  7. Get someone appropriate in your organisation to add their approval to the threat model
  8. Use threatware submit to create a record of the approved threat model in a git repository

As 3-4 threat models are completed, your local threat model template can be updated to include common components, assets and threats, which makes the next threat models easier to complete. It's fine to add things that might not be relevant to some systems, as removing them from the copy of your threat model template is easy.

AWS lambda

See Authentication for full details on how to configure authentication.

Put Confluence/Google credentials, and git credentials into AWS Secret Store. Change manage/manage_config.yaml to point to your chosen git repo.

Clone this repo and build the dockerfile. Upload docker image to ACS. Create AWS lambda using docker image. Adjust timeout on lambda to 1 minute. Trigger lambda via API Gateway (please restict access to your lambda to at least your organisation's IP range).

CLI

See Authentication for full details on how to configure authentication.

Run threatware convert -d 123, this will fail but the configuration will be downloaded.

Put Confluence credentials in ~/.threatware/.atlassian. Google Doc credentials will be automatically capture on first attempt to access a Google Doc (requires creating Google App credentials first). threatware will use your existing git credentials SSH keys. Change manage/manage_config.yaml to point to your chosen git repo.

Run threatware -h to see command line options.