Package: pytmac
pytmacPython based threat modelling as code tool (Python T.M.A.C).Installationpytmac is available via PyPi, and can be installed with pip:pip3 install pytmacIn order for DFD diagrams to be generated,plantumlmust be installed on the system. If it is not installed, pytmac will continue to execute but the output will not include a DFD diagram.UsageOnce installed, pytmac can be called from the command line with an array of arguments which are described in the help page:pytmac --helpDemonstrationTo generate an example report based on some pre-defined resources, run the following command:pytmac --demoThis will write to a file calledreport-[today-date].mdwhich can be viewed in a markdown viewer.ConfigurationInit modepytmac can be run in init mode to generate configuration files using a combination of inputs provided and default project settings. This can be done with the following command:pytmac--initOnce the initialisation has completed, you should review the generated files and make any changes required (Primary focus should be on the defaults file as this will globally define security settings for all generated resources in your project.Config filepytmac on launch will look for a file in the current directory named.pytmacas a source of settings. This file can be used to set the following settings:resource_file: "docs/resources.yaml"
config_file: "docs/config.yaml"
defaults_file: "docs/defaults.yaml"If both a config file value and a manual override is added via the command line, the command line value will take precedence.Eg if you have a .pytmac file with the following:resource_file: "docs/resources.yaml"and call pytmac with the following:pytmac --resources-file resources.yamlthe resources.yaml file will be used over the one defined in the .pytmac file.ResourcesResources are defined as any asset that is part of the system being modelled under the following categories:DatabasesNetworksSystemsUsersResources are provided to pytmac in a yaml file, which can be passed with the--resources-fileargument.An example of aresources.yamlcan 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: trueDefaultsDefaults 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-fileargument.An example of adefaults.yamlcan 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 ChecksSecurity 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"]OutputsThe 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 DetailsThis project usessemantic versioningfor releases, which are determined and managed bypython-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.gpushYou can use my other projectgpushto ensure you always push commits with the correct format for this project, otherwise, details on commit message structure can be found on theconventional commitswebsite.DocumentationDocumentation is generated usingmkdocs, and is hosted on github pages. To generate the documentation locally, run the following command:NOTE: Before running for the first time you will need to ensure that you have the required packages installed, you can do this as:pip3 install -r requirements.docs.txtNow run the following make command to generate and serve the docsmakemkdocsThis will generate a new copy of the documentation in the./docsdirectory and serve it onhttp://localhost:8000.NOTE: This action will also run during CI to ensure the documentation is up-to-date.