control "Guards" {
  description = "Trained guards patrol tower"
  risk_reduction = 75
}

Veja o [Diagrama de Fluxo de Dados](#data-flow-diagram) para mais informações sobre como construir diagramas de fluxo de dados que podem ser convertidos para PNGs automaticamente.

Para ver um exemplo de como referenciar bibliotecas de controle pré-definidas para os [OWASP Proactive Controls](https://owasp.org/www-project-proactive-controls/) e [AWS Security Checklist](https://d1.awsstatic.com/whitepapers/Security/AWS_Security_Checklist.pdf), consulte [examples/tm3.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm3.hcl). Também temos os [MITRE ATT&CK Controls](https://attack.mitre.org/mitigations/enterprise/) [aqui](https://github.com/threatcl/threatcl/blob/HEAD/examples/MITRE_ATTACK_controls.hcl).

Você também pode incluir um threatmodel externo no seu próprio, para referenciar e usar todas as suas informações. Você pode ver [examples/including-example/corp-app.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/including-example/corp-app.hcl) como exemplo.

Para ver a descrição completa da especificação, veja [aqui](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl) ou execute:

threatcl generate boilerplate
```
`threatcl` também processará arquivos JSON, mas a única ressalva é que módulos de importação e variáveis não funcionarão. Você pode ver [examples/tm1.json](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm1.json) como exemplo.

## Por que HCL?

HCL é a principal linguagem de configuração usada nos produtos da HashiCorp, em particular, [Terraform](https://www.terraform.io/) – seu software de Infraestrutura como Código de código aberto. Trabalhei na HashiCorp por um tempo e a linguagem realmente me conquistou; além disso, se profissionais de DevOps e Engenheiros de Software estão usando a linguagem, então simplificar como eles documentam modelos de ameaças está alinhado com os objetivos do `threatcl`.

Você pode usar `threatcl` com JSON, mas perde algumas funcionalidades. Para mais informações, veja a pasta [examples/](https://github.com/threatcl/threatcl/blob/HEAD/examples/).

## Por que não documentá-los apenas em MD?

Achei interessante a ideia de usar um formato que pudesse ser manipulado programaticamente.

## Agradecimentos e Referências

Uma das funcionalidades do `threatcl` é a geração automática de [diagramas de fluxo de dados](#data-flow-diagram) a partir de arquivos HCL. Isso aproveita o pacote [go-dfd](https://github.com/marqeta/go-dfd) da Marqeta e [Blake Hitchcock](https://github.com/rbhitchcock). Não deixe de conferir o post deles no blog sobre [Modelos de ameaças na velocidade do DevOps](https://community.marqeta.com/t5/engineering-blogs/threat-models-at-the-speed-of-devops/ba-p/40).

Além disso, gostaria de agradecer a [Jamie Finnigan](https://twitter.com/chair6) e [Talha Tariq](https://twitter.com/0xtbt) na HashiCorp por me permitirem continuar trabalhando nesta ferramenta de código aberto mesmo depois de ter finalizado minha contribuição na HashiCorp.

Também agradeço ao pessoal da IriusRisk pela [especificação OpenThreatModel](https://github.com/iriusrisk/OpenThreatModel).

# threatcl cli

## Instalação

Baixe a versão mais recente em [releases](https://github.com/threatcl/threatcl/releases) e mova o binário `threatcl` para seu PATH.

## Instalar com Homebrew

Instale `threatcl` com [Homebrew](https://brew.sh/) — a fórmula reside no homebrew-core:```bash
brew install threatcl
```
## Executar com Docker```bash
docker run --rm -it ghcr.io/threatcl/threatcl:latest
```
## Verificando lançamentos (proveniência de construção)

Cada lançamento etiquetado fornece proveniência de construção [SLSA](https://slsa.dev) —
Atestados sem chave, assinados pelo Sigstore, gerados pelo pipeline de lançamento do GitHub Actions
(GitHub OIDC → Fulcio, sem chaves de assinatura). Você pode verificar que um binário ou
a imagem do contêiner foi realmente construída a partir do fluxo de trabalho de lançamento deste repositório usando
a [GitHub CLI](https://cli.github.com) (`gh attestation verify` — sem necessidade de
ferramentas extras ou chaves confiáveis para gerenciar).

Verifique um arquivo baixado (ou o arquivo `SHA256SUMS`):```bash
gh attestation verify threatcl_<version>_<os>_<arch>.tar.gz --repo threatcl/threatcl
```
Verifique a imagem do contêiner (a tag é resolvida automaticamente para seu digest):```bash
gh attestation verify oci://ghcr.io/threatcl/threatcl:<version> --repo threatcl/threatcl
```
Para fixar a imagem exata que você executa, resolva o digest você mesmo e verifique (e faça pull) pelo digest:```bash
digest=$(docker buildx imagetools inspect ghcr.io/threatcl/threatcl:<version> --format '{{ .Manifest.Digest }}')
gh attestation verify oci://ghcr.io/threatcl/threatcl@${digest} --repo threatcl/threatcl
```
Consulte [docs/SLSA.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/SLSA.md) para a postura completa da cadeia de fornecimento.

## Executar com GitHub Actions

O `threatcl` pode ser integrado diretamente nos seus repositórios do GitHub com https://github.com/threatcl/threatcl-action. Este é um dos métodos ideais para gerenciar seus modelos de ameaça e ajuda a atingir o objetivo de integração em seus sistemas de controle de versão.

## Compilar a partir do código-fonte

1. Clone este repositório.
2. Acesse o diretório `threatcl`
3. `make bootstrap`
4. `make build`

Para mais ajuda sobre como contribuir com o `threatcl`, consulte o [CHANGELOG.md](https://github.com/threatcl/threatcl/blob/HEAD/CHANGELOG.md).

## Uso

Para ajuda sobre qualquer subcomando, use a flag `-h`.```bash
$ threatcl
Usage: threatcl [--version] [--help] <command> [<args>]

Available commands are:
    cloud        Interact with ThreatCL Cloud services
    dashboard    Generate markdown files from existing HCL threatmodel file(s)
    dfd          Generate Data Flow Diagram PNG or DOT files from existing HCL threatmodel file(s)
    export       Export threat models into other formats
    generate     Generate an HCL Threat Model
    list         List Threatmodels found in HCL file(s)
    mcp          Model Context Protocol (MCP) server for threatcl
    mermaid      Output raw mermaid source from 'mermaid' blocks in existing HCL threatmodel file(s)
    query        Execute GraphQL queries against threat model data
    server       Start a GraphQL API server for threat models
    terraform    Parse output from 'terraform show -json'
    validate     Validate existing HCL Threatmodel file(s)
    view         View existing HCL Threatmodel file(s)

```
## (Opcional) Arquivo de configuração

A maioria dos comandos do `threatcl` possui uma flag `-config` que permite especificar um arquivo `config.hcl`. O HCL dentro deste arquivo pode ser usado para sobrescrever alguns atributos padrão do `threatcl`. Estes estão listados abaixo:

- **Tamanhos de Iniciativa** - padrão "Undefined", "Small", "Medium", "Large"
- **Tamanho Padrão de Iniciativa** - padrão "Undefined"
- **Classificações de Informação** - padrão "Restricted", "Confidential", "Public"
- **Classificação Padrão de Informação** - padrão "Confidential"
- **Tipos de Impacto** - padrão "Confidentiality", "Integrity", "Availability"
- **Elementos STRIDE** - padrão "Spoofing", "Tampering", "Info Disclosure", "Denial Of Service", "Elevation Of Privilege"
- **Classificações de Dependência de Uptime** - padrão "none", "degraded", "hard", "operational"
- **Classificação Padrão de Dependência de Uptime** - padrão "none"

Por exemplo:```hcl
initiative_sizes = ["S", "M", "L"]
default_initiative_size = "M"
info_classifications = ["1", "2"]
default_info_classification = "1"
impact_types = ["big", "small"]
strides = ["S", "T"]
uptime_dep_classifications = ["N", "D"]
default_uptime_dep_classification = "N"
```
Se você modificar esses atributos, precisará se lembrar de fornecer o arquivo de configuração para outras operações, pois isso pode impactar a validação ou a criação de dashboards.

## Cloud commands

Visite https://threatcl.dev/cloud/overview/ para ler mais sobre os subcomandos `cloud`.

## List and View

Os comandos `threatcl list` e `threatcl view` podem ser usados para listar e visualizar dados de arquivos HCL de especificação `threatcl`.```bash
$ threatcl list examples/*
#  File              Threatmodel      Author
1  examples/tm1.hcl  Tower of London  @xntrik
2  examples/tm1.hcl  Fort Knox        @xntrik
3  examples/tm2.hcl  Modelly model    @xntrik
```
## Validar

O comando `threatcl validate` é usado para validar um arquivo HCL de spec `threatcl`.```bash
$ threatcl validate examples/*
Validated 3 threatmodels in 3 files
```
### Invariantes

`threatcl validate` também pode impor invariantes em toda a organização — regras verificadas por máquina,
como "nenhum endpoint público deve ser não autenticado" ou "todos
os recursos voltados para internet devem documentar o logging de auditoria" — contra cada
modelo de ameaça validado:```bash
$ threatcl validate -invariants=invariants.hcl ./models/
Validated 4 threatmodels in 3 files
Invariant violation [error] 'threats_have_implemented_controls': threat 'Credential theft' in threatmodel 'Payments' (models/payments.hcl): Every threat must have at least one implemented control
Checked 3 invariants against 4 threatmodels: 1 errors, 0 warnings, 1 exemptions
```
Invariantes vivem em seu próprio arquivo HCL, têm como alvo uma coleção específica (ameaças,
controles, processos DFD, fluxos, ...) e expressam sua condição como uma expressão
nativa HCL. Eles suportam severidades `error`/`warning` e isenções por modelo
com justificativas. Veja [docs/invariants.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/invariants.md).

## Exportação

O comando `threatcl export` é usado para exportar um modelo de ameaças `threatcl` (ou modelos) para a representação JSON nativa (por padrão), ou para a representação json do [OTM](https://github.com/iriusrisk/OpenThreatModel), ou até mesmo de volta para `hcl` (O que é útil para gerar HCL novo a partir de modelos de ameaças dinâmicos). Você também pode salvá-los diretamente em um arquivo com a flag `-output`.```bash
$ threatcl export -format=otm examples/tm1.hcl
[{"assets":[{"description":"including the imperial state crown","id":"crown-jewels","name":"crown jewels","risk":{"availability":0,"confidentiality":0,"integrity":0}}],"mitigations":[{"attributes":{"implementation_notes":"They are trained to be guards as well","implemented":true},"description":"Lots of guards patrol the area","id":"lots-of-guards","name":"Lots of Guards","riskReduction":80}],"otmVersion":"0.2.0","project":{"attributes":{"initiative_size":"Small","internet_facing":true,"network_segment":"dmz","new_initiative":true},"description":"A historic castle","id":"tower-of-london","name":"Tower of London","owner":"@xntrik"},"threats":[{"categories":["Confidentiality"],"description":"Someone who isn't the Queen steals the crown","id":"threat-1","name":"Threat 1","risk":{"impact":0,"likelihood":null}}]},{"assets":[{"description":"Lots of gold","id":"gold","name":"Gold","risk":{"availability":0,"confidentiality":0,"integrity":0}}],"mitigations":[{"attributes":{"implemented":true},"description":"A large wall surrounds the fort","id":"big-wall","name":"Big Wall","riskReduction":80}],"otmVersion":"0.2.0","project":{"attributes":{"initiative_size":"Small","internet_facing":true,"new_initiative":false},"description":"A .. fort?","id":"fort-knox","name":"Fort Knox","owner":"@xntrik"},"threats":[{"categories":["Confidentiality"],"description":"Someone steals the gold","id":"threat-1","name":"Threat 1","risk":{"impact":0,"likelihood":null}}]}]
```
## Gerar

O comando `threatcl generate` é usado para gerar um arquivo HCL de especificação `threatcl` `boilerplate` genérico, ou, interativamente, fazer perguntas ao usuário para então gerar um arquivo HCL de especificação `threatcl`.

### Gerar Interativo

Veja o exemplo a seguir de:```bash
threatcl generate interactive
```
<p align="center">
  <img width="600" src="https://xntrik.wtf/hcltm.svg" />
</p>

### Gerar Editor Interativo

Se preferir trabalhar diretamente no seu `$EDITOR`, execute:```bash
threatcl generate interactive editor
```
Isso abrirá seu editor com um modelo de ameaça HCL básico. Se você quiser validar o modelo após a criação, use a flag `-validate`.

## MCP

O comando `threatcl mcp` expõe um servidor [MCP](https://modelcontextprotocol.io/introduction) local para que você possa interagir com arquivos hcl do threatcl através de um Host MCP, por exemplo, aplicações de IA/LLM como [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/) ou qualquer outra aplicação que suporte MCP.

O comando aceita um único argumento opcional, `-dir=<path>`, que permite que Ferramentas MCP adicionais interajam com arquivos dentro desse caminho. Sem essa configuração, as Ferramentas MCP podem interagir com strings, mas dependerão de outros mecanismos dentro do Host MCP para interagir com o sistema de arquivos subjacente.

É justo dizer que essa funcionalidade está bem em fase beta no momento.

## LSP (Language Server)

O comando `threatcl lsp` executa um servidor [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) sobre stdio, fornecendo a editores compatíveis com LSP diagnósticos ao vivo, conclusão, hover, símbolos de documento e formatação para modelos de ameaça HCL do threatcl.

É iniciado pelo cliente LSP do seu editor, em vez de ser executado manualmente. Como os arquivos threatcl compartilham a extensão `.hcl` com Terraform e outros dialetos HCL, a correspondência com `*.tm.hcl` (ou escopar o cliente para seu workspace de modelo de ameaça) evita conflitos com um servidor de linguagem Terraform.

Veja [docs/lsp.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/lsp.md) para configuração de editores (Neovim, Helix, VS Code, Zed) e limitações atuais.

## Server (GraphQL API)

O comando `threatcl server` inicia um servidor de API GraphQL que expõe seus modelos de ameaça via HTTP para consulta e integração programáticas.

### Basic Usage```bash
# Start the server
$ threatcl server -dir ./examples

# With file watching for auto-reload
$ threatcl server -dir ./examples -watch

# Custom port
$ threatcl server -dir ./examples -port 3000
```
Navegue até `http://localhost:8080` para acessar o GraphQL Playground interativo.

### Exemplo de Consulta```graphql
query {
  stats {
    totalThreatModels
    totalThreats
    implementedControls
  }

  threatModels(filter: { internetFacing: true }) {
    name
    threats {
      description
      controls {
        name
        implemented
      }
    }
  }
}
```
### Documentação

Para documentação completa da API, referência de esquema, consultas avançadas e exemplos de integração, veja:
- **Documentação Completa da API**: [docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md)
- **Exemplos de Consultas**: [examples/graphql-queries.md](https://github.com/threatcl/threatcl/blob/HEAD/examples/graphql-queries.md)

## Consulta (GraphQL CLI)

O comando `threatcl query` executa consultas GraphQL diretamente da linha de comando sem iniciar um servidor. Isso é ideal para automação, pipelines CI/CD e scripts de shell.

### Uso Básico```bash
# Get statistics
$ threatcl query -dir ./examples -query '{ stats { totalThreats } }'

# Query from file
$ threatcl query -dir ./examples -file queries/get-stats.graphql

# Use in scripts
$ THREATS=$(threatcl query -dir ./examples \
    -query '{ stats { totalThreats } }' \
    -output compact | jq -r '.data.stats.totalThreats')
$ echo "Found $THREATS threats"
```
### Formatos de Saída

- `pretty` (padrão): JSON formatado com indentação
- `json`: Mesmo que pretty
- `compact`: JSON de linha única para scripts

### Consulta com Variáveis```bash
$ threatcl query -dir ./examples \
    -query 'query($author: String) { threatModels(filter: {author: $author}) { name } }' \
    -vars '{"author": "John Doe"}'
```
### Exemplo de CI/CD```bash
#!/bin/bash
# Check if all controls are implemented before deployment

UNIMPLEMENTED=$(threatcl query -dir ./threatmodels \
  -query '{ stats { totalControls implementedControls } }' \
  -output compact | jq -r '.data.stats.totalControls - .data.stats.implementedControls')

if [ "$UNIMPLEMENTED" -gt 0 ]; then
  echo "ERROR: $UNIMPLEMENTED controls are not yet implemented"
  exit 1
fi

echo "All controls implemented, proceeding with deployment"
```
Consulte [docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md) para consultas disponíveis e o esquema GraphQL.

## Painel

O comando `threatcl dashboard` recebe arquivos HCL de especificação do `threatcl` e gera vários arquivos markdown e png, colocando-os em uma pasta selecionada.```bash
$ threatcl dashboard -overwrite -outdir=dashboard-example examples/*
Created the 'dashboard-example' directory
Writing dashboard markdown files to 'dashboard-example' and overwriting existing files
Successfully wrote to 'dashboard-example/tm1-toweroflondon.md'
Successfully wrote to 'dashboard-example/tm1-fortknox.md'
Successfully wrote to 'dashboard-example/tm2-modellymodel.png'
Successfully wrote to 'dashboard-example/tm2-modellymodel.md'
Successfully wrote to 'dashboard-example/dashboard.md'
```
### Modelos Markdown Personalizados

O comando `threatcl dashboard` também pode aceitar flags opcionais para especificar modelos personalizados (de acordo com o [text/template](https://pkg.go.dev/text/template) do Golang).

Para especificar um arquivo de modelo de dashboard, use a flag `-dashboard-template`. Para um exemplo, veja [dashboard-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/dashboard-template.tpl).

Para especificar um arquivo de modelo de threatmodel, use a flag `-threatmodel-template`. Para um exemplo, veja [threatmodel-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/threatmodel-template.tpl).

### Nome de Arquivo Personalizado para o Arquivo de Índice do Dashboard

O comando `threatcl dashboard` também pode aceitar uma flag opcional para especificar um nome de arquivo para o arquivo de dashboard "index" gerado. Por padrão, este arquivo é `dashboard.md`. Use a flag `-dashboard-filename` sem extensão para alterar este nome de arquivo.

## Diagrama de Fluxo de Dados

De acordo com a [especificação](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl), um `threatmodel` pode incluir blocos `data_flow_diagram_v2`. Um exemplo de um DFD simples está disponível [aqui](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm2.hcl). O antigo bloco de uso único `data_flow_diagram` será descontinuado em algum momento, por isso é melhor usar blocos nomeados `data_flow_diagram_v2`, assim você pode ter vários DFDs associados.

O comando `threatcl dfd` recebe arquivos HCL da especificação `threatcl` e gera vários arquivos png, colocando-os em uma pasta selecionada.

Se o arquivo HCL não incluir um bloco `threatmodel` com um bloco `data_flow_diagram` ou `data_flow_diagram_v2`, nada é gerado.

O comando em si é muito semelhante ao comando Dashboard.```bash
$ threatcl dfd -overwrite -outdir testout examples/*
Successfully created 'testout/tm2-modellymodel.png'
```
Se o seu `threatmodel` não incluir um `diagram_link`, mas incluir um `data_flow_diagram`, este também será renderizado ao executar `threatcl dashboard`.

## Mermaid

Conforme a [especificação](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl), um `threatmodel` também pode incluir blocos `mermaid` livres. Diferentemente do `data_flow_diagram_v2` (que o `threatcl` renderiza para você), um bloco `mermaid` incorpora o código-fonte bruto [mermaid](https://mermaid.js.org/) literalmente — o mermaid infere o tipo de diagrama (sequência, estado, fluxograma, etc.) a partir da primeira linha do conteúdo.

O comando `threatcl mermaid` extrai esse código-fonte bruto para que possa ser direcionado a outras ferramentas de renderização. Ele não renderiza imagens por si só.

Por padrão, o código-fonte é impresso na STDOUT:```bash
$ threatcl mermaid examples/tm2.hcl
sequenceDiagram
  User->>App: credentials
  App->>Auth: verify
  Auth-->>App: token
```
Isso facilita o envio para um renderizador como [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):```bash
$ threatcl mermaid model.hcl | mmdc -o diagram.svg -i -
```
Se houver múltiplos blocos `mermaid`, selecione um com `-index=n`, ou escreva todos em um diretório com `-outdir` (um arquivo `.mmd` por bloco). Você também pode escrever um único bloco em um arquivo com `-out`.```bash
$ threatcl mermaid -outdir testout model.hcl
Successfully created 'testout/model-mymodelloginsequence.mmd'
```
## Terraform

O comando `threatcl terraform` é capaz de extrair recursos de dados do `terraform show -json` [documentação aqui](https://www.terraform.io/docs/cli/commands/show.html) da saída de arquivos de plano, ou arquivos de estado ativos, e convertê-los em blocos `information_asset` rascunhados para inclusão em arquivos `threatcl`.

Se você estiver em uma pasta com estado existente, pode executar o seguinte:```bash
terraform show -json | threatcl terraform -stdin
```
Isto irá gerar algo semelhante a isto:```bash
information_asset "aws_rds_cluster default" {
  description                = "cluster_identifier: aurora-cluster-demo, database_name: mydb"
  information_classification = ""
  source                     = "terraform state"
}
information_asset "aws_s3_bucket example" {
  description                = "bucket: terraform-20211107232017071500000001"
  information_classification = ""
  source                     = "terraform state"
}
```
Você também pode ver uma saída semelhante de um arquivo de plano que ainda não foi aplicado com o Terraform executando:```bash
terraform show -json <plan-file> | threatcl terraform -stdin
```
Se você deseja atualizar um arquivo de modelo de ameaça `threatcl` existente ("threatmodel.hcl"), você pode com:```bash
terraform show -json <plan> | threatcl terraform -stdin -add-to-existing=threatmodel.hcl > new-threatmodel.hcl
```
Com a flag `-add-to-existing`, você também pode especificar `-tm-name=<string>` se precisar especificar um modelo de ameaça específico do arquivo de origem, se houver múltiplos. E você também pode aplicar uma classificação padrão, com a flag `-default-classification=Confidential`.

Esses comandos também podem aceitar um arquivo como entrada, nesse caso, omita a flag `-stdin`.

Os recursos do terraform que `threatcl` conhece estão codificados em [pkg/terraform/terraform.go](https://github.com/threatcl/threatcl/blob/HEAD/pkg/terraform/terraform.go). Se você quiser que o comando `threatcl terraform` produza outros recursos `information_asset` que não estão lá, você pode fornecer sua própria versão deste json através da flag `-tf-collection=<json file>`.