threatcl

Modellazione delle minacce con HCL

Cosa è successo a hcltm?

hcltm è stato rinominato in threatcl. Benvenuti!

Panoramica

[!TIP] Vuoi leggere la nuova documentazione? Vai su threatcl.dev

Ci sono molti modi diversi in cui un modello di minaccia può essere documentato. Da un semplice file di testo, a documenti Word più dettagliati, fino a modelli di minaccia completamente strumentati in una soluzione centralizzata. Due degli attributi più preziosi di un modello di minaccia sono la capacità di documentare chiaramente le minacce e di poter guidare cambiamenti significativi.

threatcl mira a fornire un approccio DevOps-first alla documentazione di un modello di minaccia di sistema concentrandosi sui seguenti obiettivi:

Formato semplice basato su file di testo
Esperienza utente semplice basata su CLI
Integrazione nei sistemi di controllo versione (VCS)

Questo repository è la sede del software CLI threatcl. La specifica di threatcl è basata su HCL2, il linguaggio di configurazione di HashiCorp, che mira ad essere "piacevole da leggere e scrivere per gli umani, e una variante JSON più facile da generare e analizzare per le macchine". La specifica di threatcl si trova su github.com/threatcl/spec. Combinando il software CLI threatcl e la specifica threatcl, i professionisti possono definire un modello di minaccia di sistema in HCL, ad esempio:```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 }

}

Vedi [Diagramma del Flusso di Dati](#data-flow-diagram) per maggiori informazioni su come costruire diagrammi del flusso di dati che possono essere convertiti automaticamente in PNG.

Per vedere un esempio di come fare riferimento a librerie di controlli predefinite per [OWASP Proactive Controls](https://owasp.org/www-project-proactive-controls/) e [AWS Security Checklist](https://d1.awsstatic.com/whitepapers/Security/AWS_Security_Checklist.pdf) consulta [examples/tm3.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm3.hcl). Abbiamo anche i [MITRE ATT&CK Controls](https://attack.mitre.org/mitigations/enterprise/) [qui](https://github.com/threatcl/threatcl/blob/HEAD/examples/MITRE_ATTACK_controls.hcl).

Puoi anche includere un threatmodel esterno nel tuo, per fare riferimento e utilizzare tutte le sue informazioni. Puoi vedere [examples/including-example/corp-app.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/including-example/corp-app.hcl) come esempio.

Per vedere una descrizione completa delle specifiche, vedi [qui](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl) o esegui:```bash
threatcl generate boilerplate

threatcl elaborerà anche file JSON, ma l'unica avvertenza è che i moduli di importazione e le variabili non funzioneranno. Puoi vedere examples/tm1.json come esempio.

Perché HCL?

HCL è il linguaggio di configurazione principale utilizzato nei prodotti di HashiCorp, in particolare Terraform - il loro software Infrastructure-as-Code open-source. Ho lavorato per un po' in HashiCorp e il linguaggio mi è davvero piaciuto, inoltre, se DevOps e ingegneri del software usano il linguaggio, semplificare il modo in cui documentano i modelli di minaccia è in linea con gli obiettivi di threatcl.

Puoi usare threatcl con JSON, ma perdi alcune funzionalità. Per maggiori informazioni, consulta la cartella examples/.

Perché non documentarli semplicemente in MD?

Mi piaceva l'idea di usare un formato con cui si potesse interagire a livello programmatico.

Ringraziamenti e Riferimenti

Una delle funzionalità di threatcl è la generazione automatica di diagrammi di flusso dei dati dai file HCL. Questo sfrutta il pacchetto go-dfd di Marqeta e Blake Hitchcock. Dai un'occhiata al loro post sul blog su Threat models at the speed of DevOps.

Inoltre, vorrei ringraziare Jamie Finnigan e Talha Tariq di HashiCorp per avermi permesso di continuare a lavorare su questo strumento open-source anche dopo aver concluso il mio rapporto con HashiCorp.

Grazie anche ai ragazzi di IriusRisk per la specifica OpenThreatModel.

threatcl cli

Installazione

Scarica l'ultima versione da releases e sposta il binario threatcl nel tuo PATH.

Installazione con Homebrew

Installa threatcl con Homebrew — la formula si trova in homebrew-core:```bash brew install threatcl

## Eseguire con Docker```bash
docker run --rm -it ghcr.io/threatcl/threatcl:latest

Verifica dei rilasci (provenienza della build)

Ogni release con tag include SLSA la provenienza della build — attestazioni senza chiavi firmate con Sigstore, generate dalla pipeline di release di GitHub Actions (GitHub OIDC → Fulcio, nessuna chiave di firma). Puoi verificare che un binario o l'immagine del contenitore sia stata realmente costruita dal workflow di release di questo repository utilizzando il GitHub CLI (gh attestation verify — nessun ulteriore strumento o chiavi fidate da gestire).

Verifica un archivio scaricato (o il file SHA256SUMS):```bash gh attestation verify threatcl_.tar.gz --repo threatcl/threatcl

Verifica l'immagine del container (il tag viene risolto automaticamente nel suo digest):```bash
gh attestation verify oci://ghcr.io/threatcl/threatcl:<version> --repo threatcl/threatcl

Per fissare l'immagine esatta che esegui, risolvi il digest da solo e verifica (e tira) tramite digest:```bash digest=$(docker buildx imagetools inspect ghcr.io/threatcl/threatcl: --format '{{ .Manifest.Digest }}') gh attestation verify oci://ghcr.io/threatcl/threatcl@${digest} --repo threatcl/threatcl

Vedi [docs/SLSA.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/SLSA.md) per la postura completa della catena di fornitura.

## Esecuzione con GitHub Actions

`threatcl` può essere integrato direttamente nei tuoi repository GitHub con https://github.com/threatcl/threatcl-action. Questo è uno dei metodi ideali per gestire i tuoi modelli di minaccia e aiuta a raggiungere l'obiettivo di integrazione nei tuoi sistemi di controllo versione.

## Compilazione dal sorgente

1. Clona questo repository.
2. Spostati nella directory `threatcl`
3. `make bootstrap`
4. `make build`

Per ulteriore aiuto su come contribuire a `threatcl` consulta il [CHANGELOG.md](https://github.com/threatcl/threatcl/blob/HEAD/CHANGELOG.md).

## Utilizzo

Per aiuto su qualsiasi sottocomando usa il 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)

(Opzionale) File di configurazione

La maggior parte dei comandi di threatcl ha un flag -config che permette di specificare un file config.hcl. Il file HCL può essere usato per sovrascrivere alcuni attributi predefiniti di threatcl. Questi sono elencati di seguito:

Dimensioni delle iniziative - predefinito: "Undefined", "Small", "Medium", "Large"
Dimensione predefinita dell'iniziativa - predefinito: "Undefined"
Classificazioni delle informazioni - predefinito: "Restricted", "Confidential", "Public"
Classificazione predefinita delle informazioni - predefinito: "Confidential"
Tipi di impatto - predefinito: "Confidentiality", "Integrity", "Availability"
Elementi STRIDE - predefinito: "Spoofing", "Tampering", "Info Disclosure", "Denial Of Service", "Elevation Of Privilege"
Classificazioni della dipendenza di uptime - predefinito: "none", "degraded", "hard", "operational"
Classificazione predefinita della dipendenza di uptime - predefinito: "none"

Ad esempio:

initiative "My Initiative" {
  size = "Small"

  info_asset "User Data" {
    classification = "Restricted"
    description    = "User PII (Personally Identifiable Information)"
  }

  threat "Data Leak" {
    description = "User data is leaked from the system"
    risk        = 75
    stride      = ["Info Disclosure"]
  }
}
``````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 modifichi questi attributi, dovrai ricordarti di fornire il file di configurazione per altre operazioni, poiché ciò potrebbe influire sulla convalida o sulla creazione della dashboard.

Comandi Cloud

Visita https://threatcl.dev/cloud/overview/ per saperne di più sui sottocomandi cloud.

Elenco e Visualizzazione

I comandi threatcl list e threatcl view possono essere utilizzati per elencare e visualizzare i dati dai file HCL delle specifiche 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

## Validare

Il comando `threatcl validate` viene utilizzato per validare un file HCL di specifica di `threatcl`.```bash
$ threatcl validate examples/*
Validated 3 threatmodels in 3 files

Invarianti

threatcl validate può anche applicare invarianti a livello di organizzazione — regole controllate automaticamente come "nessun endpoint pubblico dovrebbe essere non autenticato" o "tutte le funzionalità esposte su internet devono documentare la registrazione di audit" — contro ogni modello di minaccia convalidato:```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

Gli invarianti risiedono nel proprio file HCL, mirano a una raccolta specifica (minacce, controlli, processi DFD, flussi, ...) ed esprimono la loro condizione come un'espressione HCL nativa. Supportano severità `error`/`warning` ed esenzioni per modello con giustificazioni. Vedi [docs/invariants.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/invariants.md).

## Export

Il comando `threatcl export` viene utilizzato per esportare un modello di minaccia `threatcl` (o più modelli) nella rappresentazione JSON nativa (per impostazione predefinita), o nella rappresentazione JSON [OTM](https://github.com/iriusrisk/OpenThreatModel), o anche di nuovo in `hcl` (utile per generare HCL fresco da modelli di minaccia dinamici). Puoi anche salvarli direttamente in un file con il 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}}]}]

Generare

Il comando threatcl generate viene utilizzato per produrre un file HCL boilerplate generico per una specifica threatcl, oppure per chiedere interattivamente all'utente delle domande per poi produrre un file HCL per una specifica threatcl.

Generazione Interattiva

Vedi il seguente esempio di:```bash threatcl generate interactive

<p align="center">
  <img width="600" src="https://xntrik.wtf/hcltm.svg" />
</p>

### Genera l'Editor Interattivo

Se preferisci lavorare direttamente nel tuo `$EDITOR` esegui:```bash
threatcl generate interactive editor

Questo aprirà il tuo editor con un modello di minaccia HCL essenziale. Se desideri convalidare il modello dopo la creazione, usa il flag -validate.

MCP

Il comando threatcl mcp espone un server MCP locale in modo da poter interagire con i file HCL di threatcl tramite un host MCP, ad esempio applicazioni AI/LLM come Claude Desktop, Cursor o qualsiasi altra applicazione che supporti MCP.

Il comando accetta un singolo argomento opzionale, -dir=<path>, che consente a strumenti MCP aggiuntivi di interagire con i file all'interno di quel percorso. Senza questa impostazione, gli strumenti MCP possono interagire con le stringhe, ma si affideranno ad altri meccanismi all'interno dell'host MCP per interagire con il filesystem sottostante.

È giusto dire che questa funzionalità è ancora in fase beta.

LSP (Language Server)

Il comando threatcl lsp esegue un server Language Server Protocol su stdio, fornendo agli editor compatibili con LSP diagnostica in tempo reale, completamento, hover, simboli del documento e formattazione per i modelli di minaccia HCL di threatcl.

Viene avviato dal client LSP del tuo editor, non eseguito manualmente. Poiché i file threatcl condividono l'estensione .hcl con Terraform e altri dialetti HCL, l'uso di *.tm.hcl (o la limitazione del client al tuo workspace di modelli di minaccia) evita conflitti con un language server di Terraform.

Vedi docs/lsp.md per la configurazione negli editor (Neovim, Helix, VS Code, Zed) e le limitazioni attuali.

Server (GraphQL API)

Il comando threatcl server avvia un server API GraphQL che espone i tuoi modelli di minaccia tramite HTTP per interrogazioni e integrazione programmatica.

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

Vai a `http://localhost:8080` per accedere al Playground GraphQL interattivo.

### Query di esempio```graphql
query {
  stats {
    totalThreatModels
    totalThreats
    implementedControls
  }

  threatModels(filter: { internetFacing: true }) {
    name
    threats {
      description
      controls {
        name
        implemented
      }
    }
  }
}

Documentazione

Per la documentazione completa dell'API, il riferimento dello schema, le query avanzate e gli esempi di integrazione, vedere:

Documentazione API completa: docs/graphql-api.md
Esempi di query: examples/graphql-queries.md

Query (GraphQL CLI)

Il comando threatcl query esegue query GraphQL direttamente dalla riga di comando senza avviare un server. È ideale per automazione, pipeline CI/CD e scripting di shell.

Utilizzo di base```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"

### Output Formats

- `pretty` (default): JSON formattato con indentazione
- `json`: Uguale a pretty
- `compact`: JSON su singola riga per script

### Query con Variabili```bash
$ threatcl query -dir ./examples \
    -query 'query($author: String) { threatModels(filter: {author: $author}) { name } }' \
    -vars '{"author": "John Doe"}'

Esempio 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"

Vedi [docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md) per le query disponibili e lo schema GraphQL.

## Dashboard

Il comando `threatcl dashboard` prende file HCL di specifica `threatcl` e genera un numero di file markdown e png, inserendoli in una cartella selezionata.```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'

Modelli Markdown Personalizzati

Il comando threatcl dashboard può anche accettare flag opzionali per specificare modelli personalizzati (come da text/template di Golang).

Per specificare un file modello per la dashboard, usa il flag -dashboard-template. Per un esempio, vedi dashboard-template.tpl.

Per specificare un file modello per il threat model, usa il flag -threatmodel-template. Per un esempio, vedi threatmodel-template.tpl.

Nome File Personalizzato per il File Indice della Dashboard

Il comando threatcl dashboard può anche accettare un flag opzionale per specificare un nome file per il file dashboard generato "index". Di default questo file è dashboard.md. Usa il flag -dashboard-filename senza estensione per cambiare questo nome file.

Diagramma di Flusso Dati

Come da specifica, un threatmodel può includere blocchi data_flow_diagram_v2. Un esempio di un semplice DFD è disponibile qui. Il vecchio blocco monouso data_flow_diagram verrà deprecato a un certo punto, quindi è meglio usare blocchi nominati data_flow_diagram_v2, in questo modo puoi avere più DFD associati.

Il comando threatcl dfd accetta file HCL di specifica threatcl e genera una serie di file png, inserendoli in una cartella selezionata.

Se il file HCL non include un blocco threatmodel con un blocco data_flow_diagram o data_flow_diagram_v2, non viene prodotto nulla.

Il comando stesso è molto simile al comando Dashboard.```bash $ threatcl dfd -overwrite -outdir testout examples/* Successfully created 'testout/tm2-modellymodel.png'

If il tuo `threatmodel` non include un `diagram_link`, ma include un `data_flow_diagram`, anche questo verrà renderizzato quando esegui `threatcl dashboard`.

## Mermaid

Come da [specifica](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl), un `threatmodel` può anche includere blocchi `mermaid` a forma libera. A differenza di `data_flow_diagram_v2` (che `threatcl` renderizza per te), un blocco `mermaid` incorpora il codice sorgente grezzo [mermaid](https://mermaid.js.org/) così com'è – mermaid deduce il tipo di diagramma (sequenza, stato, flowchart, ecc.) dalla prima riga del contenuto.

Il comando `threatcl mermaid` estrae quel codice sorgente grezzo in modo che possa essere reindirizzato ad altri strumenti di rendering. Non genera immagini da solo.

Per impostazione predefinita, il codice viene stampato su STDOUT:```bash
$ threatcl mermaid examples/tm2.hcl
sequenceDiagram
  User->>App: credentials
  App->>Auth: verify
  Auth-->>App: token

Questo rende facile l'invio tramite pipe a un renderer come mermaid-cli:```bash $ threatcl mermaid model.hcl | mmdc -o diagram.svg -i -

Se ci sono più blocchi `mermaid`, selezionane uno con `-index=n`, oppure scrivili tutti in una directory con `-outdir` (un file `.mmd` per blocco). Puoi anche scrivere un singolo blocco in un file con `-out`.```bash
$ threatcl mermaid -outdir testout model.hcl
Successfully created 'testout/model-mymodelloginsequence.mmd'

Terraform

Il comando threatcl terraform è in grado di estrarre risorse dati dall'output di terraform show -json documentazione qui di file di piano, o file di stato attivi, e convertirli in blocchi information_asset in bozza da includere nei file threatcl.

Se ti trovi in una cartella con uno stato esistente, puoi eseguire il seguente comando:```bash terraform show -json | threatcl terraform -stdin

Questo produrrà un output simile a questo:```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"
}

Puoi anche vedere un output simile da un file di piano che non è stato ancora applicato con Terraform eseguendo:```bash terraform show -json | threatcl terraform -stdin

Se vuoi aggiornare un file di modello di minaccia `threatcl` esistente ("threatmodel.hcl") puoi farlo con:```bash
terraform show -json <plan> | threatcl terraform -stdin -add-to-existing=threatmodel.hcl > new-threatmodel.hcl

Con l'opzione -add-to-existing, puoi anche specificare -tm-name=<string> se hai bisogno di indicare un particolare modello di minaccia dal file sorgente, qualora ce ne siano più di uno. E puoi anche applicare una classificazione predefinita con l'opzione -default-classification=Confidential.

Questi comandi possono accettare anche un file come input, nel qual caso ometti l'opzione -stdin.

Le risorse terraform di cui threatcl è a conoscenza sono codificate direttamente in pkg/terraform/terraform.go. Se desideri che il comando threatcl terraform restituisca altre risorse information_asset che non sono presenti, puoi fornire la tua versione di questo json tramite l'opzione -tf-collection=<json file>.

threatcl v0.6.5

Categorie