No project description provided
Project description
pytmac
Python based threat modelling as code tool (Python T.M.A.C).
Installation
pytmac is available via PyPi, and can be installed with pip:
pip3 install pytmac
In order for DFD diagrams to be generated, plantuml must be installed on the system. If it is not installed, pytmac will continue to execute but the output will not include a DFD diagram.
Usage
Once installed, pytmac can be called from the command line with an array of arguments which are described in the help page:
pytmac --help
options:
-h, --help show this help message and exit
--version Option to print the current version only
--demo Run pytmac in demo mode using the demo config and resources
--output-dir OUTPUT_DIR
[Default: reports] Set the directory for report output
--resources-file RESOURCES_FILE
The path to the resources file
--config-file CONFIG_FILE
The path to the config file
--defaults-file DEFAULTS_FILE
The path to the defaults file
--security-checks-file SECURITY_CHECKS_FILE
[Default: security_checks.yaml] The path to the security-checks file
--swagger-file SWAGGER_FILE
[Default: None] The path to the swagger file (optional)
Demonstration
To generate an example report based on some pre-defined resources, run the following command:
pytmac --demo
This will write to a file called report-[today-date].md
which can be viewed in a markdown viewer.
Configuration
Resources
Resources are defined as any asset that is part of the system being modelled under the following categories:
- Databases
- Networks
- Systems
- Users
Resources are provided to pytmac in a yaml file, which can be passed with the --resources-file
argument.
An example of a resources.yaml
can be found in the pytmac repository at ./docs/resources.yaml
.
Resource config defines characteristics of a given resource. Default settings for a given resource type can be set in the resource yaml as follows (following the same format for a resource type).
resources:
networks:
- name: office_network
- name: aws_public_subnet
- config:
is_cloud: true
Defaults
Defaults are defined as any setting that is common across all resources. These are provided to pytmac in a yaml file, which can be passed with the --defaults-file
argument.
An example of a defaults.yaml
can be found in the pytmac repository at ./docs/defaults.yaml
.
Defaults can be overridden by resource config, and are applied to all resources unless overridden.
Security Checks
Security checks have been included to cover use cases for the Owasp top 10, however you may want to extend pytmac with custom checks can be written and added to ./docs/security_checks.yaml
. These files should be written as below, the
checks are iterated over and executed individually, all fields are required.
Severity should be used as a combination of Risk vs Likelihood, any security findings are prioritised by severity in the report output.
user_owned_device:
name: Non company device used
description: Checks for users with company_user true and company_device false.
remediation: Understand and remediate or document known exception.
severity: 3
resource_scope:
- users
check_query:
- resources[resource]["company_user"] and not resources[resource]["company_device"]
Outputs
The primary output of pytmac is a generated Markdown report, including a DFD (Data Flow Diagram) generated from the provided resources, and a programmatically generated list of security concerns using fields from the configuration (including overrides).
Additionally, a yaml report is generated of all resources and their config - To ease reviewing the findings during a threat modelling session.
Release Details
This project uses semantic versioning for releases, which are determined and managed by python-semantic-release.
Python-semantic-release relies on conventional commits being used for all commit messages to determine the next version number / semantic release type (major/minor/patch).
Once the new version number has been determined, a new release is created on github, and the new version is published to PyPi.
gpush
You can use my other project gpush to ensure you always push commits with the correct format for this project, otherwise, details on commit message structure can be found on the conventional commits website.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.