pytm: Um framework Pythonico para modelagem de ameaças

Introdução

A modelagem de ameaças tradicional muitas vezes chega tarde à festa, ou às vezes nem chega. Além disso, criar fluxos de dados e relatórios manuais pode ser extremamente demorado. O objetivo do pytm é deslocar a modelagem de ameaças para a esquerda, tornando-a mais automatizada e centrada no desenvolvedor.

Funcionalidades

Com base na sua entrada e definição do design arquitetural, o pytm pode gerar automaticamente os seguintes itens:

• Diagrama de Fluxo de Dados (DFD)
• Diagrama de Sequência
• Ameaças relevantes ao seu sistema

Requisitos

• Linux/MacOS
• Python 3.11+
• Pacote Graphviz
• Java (OpenJDK 10 or 11)
• plantuml.jar

Primeiros Passos

O tm.py é um modelo de exemplo. Você pode executá-lo para gerar o relatório e os arquivos de imagem do diagrama que ele referencia:``` mkdir -p tm ./tm.py --report docs/basic_template.md | pandoc -f markdown -t html > tm/report.html ./tm.py --dfd | dot -Tpng -o tm/dfd.png ./tm.py --seq | java -Djava.awt.headless=true -jar $PLANTUML_PATH -tpng -pipe > tm/seq.png

Há também um exemplo de `Makefile` que encapsula todos estes em targets que podem ser facilmente compartilhados para múltiplos modelos. Se você tem [GNU make](https://www.gnu.org/software/make/) instalado (disponível por padrão em distribuições Linux mas não no OSX), simplesmente execute:```
make MODEL=the_name_of_your_model_minus_.py

Você deve ter o plantuml.jar no mesmo diretório que seu modelo, ou definir PLANTUML_PATH.

Para evitar instalar todas as dependências, como pandoc ou Java, o script pode ser executado dentro de um container:```

do this only once

export USE_DOCKER=true make image

call this after every change in your model

make

### Começando - Variante Devbox

Para simplificar o uso do `pytm`, as dependências do host podem ser completamente isoladas usando o [`Devbox`](https://github.com/jetify-com/devbox). Isso geralmente é uma alternativa de menor sobrecarga e mais conveniente em relação à abordagem de contêiner OCI.

- Instale o Devbox no Linux/MacOS: `curl -fsSL https://get.jetify.com/devbox | bash`
- Instale o Devbox no [Windows/WSL](https://www.jetify.com/docs/devbox/installing-devbox/index#installing-wsl2)
- Atualize para a versão mais recente do devbox: `devbox version update`
- Defina seu token de acesso do GitHub no arquivo `~/.config/nix/nix.conf` file file: `access-tokens = github.com=YOUR_TOKEN_HERE`
- Crie um novo ambiente de shell isolado que inclua todas as ferramentas e pacotes especificados no arquivo `devbox.json` do projeto: `devbox shell`
- Exiba o caminho completo para o executável Python que será usado quando você simplesmente digitar `python` no terminal, usando o comando which python. A saída deve ser o seguinte caminho: `.devbox/nix/profile/default/bin/python`
- Teste executando o seguinte comando, que deve gerar um DFD como um arquivo PNG chamado `sample.png`: `./tm.py --dfd | dot -Tpng -o sample.png`
- Saia do ambiente de shell do Devbox: `exit`

## Uso

Todos os argumentos disponíveis:```text
usage: tm.py [-h] [--debug] [--dfd] [--report REPORT] [--exclude EXCLUDE]
             [--seq] [--list] [--colormap] [--describe DESCRIBE]
             [--list-elements] [--json JSON] [--levels LEVELS [LEVELS ...]]
             [--stale_days STALE_DAYS]

options:
  -h, --help            show this help message and exit
  --debug               print debug messages
  --dfd                 output DFD
  --report REPORT       output report using the named template file (sample
                        template file is under docs/template.md)
  --exclude EXCLUDE     specify threat IDs to be ignored
  --seq                 output sequential diagram
  --list                list all available threats
  --colormap            color the risk in the diagram
  --describe DESCRIBE   describe the properties available for a given element
  --list-elements       list all elements which can be part of a threat model
  --json JSON           output a JSON file
  --levels LEVELS [LEVELS ...]
                        Select levels to be drawn in the threat model (int
                        separated by comma).
  --stale_days STALE_DAYS
                        checks if the delta between the TM script and the code
                        described by it is bigger than the specified value in
                        days

O argumento stale_days tenta determinar a distância em dias entre o script do modelo (que você está escrevendo) e o código que implementa o sistema sendo modelado. Idealmente, eles devem estar bastante próximos na maioria dos casos de um sistema ativamente desenvolvido. Você pode executar isso periodicamente para medir o pulso do seu projeto e a 'atualidade' do seu modelo de ameaças.

Os elementos atualmente disponíveis são: TM, Element, Server, ExternalEntity, Datastore, Actor, Process, SetOfProcesses, Dataflow, Boundary, Lambda, LLM and Agent.