threatcl

Modelagem de Ameaças com HCL

O que aconteceu com hcltm?

hcltm foi renomeado para threatcl. Bem-vindo!

Visão Geral

[!TIP] Quer ler a nova documentação? Acesse threatcl.dev

Existem muitas maneiras diferentes de documentar um modelo de ameaça. Desde um simples arquivo de texto, até documentos word mais detalhados, até modelos de ameaça totalmente instrumentados em uma solução centralizada. Dois dos atributos mais valiosos de um modelo de ameaça são a capacidade de documentar claramente as ameaças e de impulsionar mudanças valiosas.

threatcl visa fornecer uma abordagem DevOps-first para documentar um modelo de ameaça de sistema focando nos seguintes objetivos:

• Formato de arquivo de texto simples
• Experiência de usuário simples orientada por CLI
• Integração com sistemas de controle de versão (VCS)

Este repositório é a casa do software CLI threatcl. O spec do threatcl é baseado em HCL2, a Linguagem de Configuração da HashiCorp, que visa ser "agradável de ler e escrever para humanos, e uma variante baseada em JSON que é mais fácil para máquinas gerarem e analisarem". O spec do threatcl está em github.com/threatcl/spec. A combinação do software CLI threatcl e do spec threatcl permite que profissionais definam um modelo de ameaça de sistema em HCL, por exemplo:```hcl threatmodel "Tower of London" { description = "A historic castle" author = "@xntrik"

attributes { new_initiative = "true" internet_facing = "true" initiative_size = "Small" }

information_asset "crown jewels" { description = "including the imperial state crown" information_classification = "Confidential" }

usecase { description = "The Queen can fetch the crown" }

third_party_dependency "community watch" { description = "The community watch helps guard the premise" uptime_dependency = "degraded" }

threat "Crown theft" { description = "Someone who isn't the Queen steals the crown" impacts = ["Confidentiality"]

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

}

data_flow_diagram_v2 "dfd name" { // ... see below for more information }

}

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/main/examples/tm3.hcl). Também temos os [MITRE ATT&CK Controls](https://attack.mitre.org/mitigations/enterprise/) [aqui](https://github.com/threatcl/threatcl/blob/main/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/main/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/main/spec.hcl) ou execute:

threatmodel generate <model.hcl>

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/main/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/main/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/main/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/main/CHANGELOG.md).

## Uso
```