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

См. [Диаграмму потоков данных](#data-flow-diagram) для получения дополнительной информации о том, как создавать диаграммы потоков данных, которые могут быть автоматически преобразованы в PNG.

Чтобы увидеть пример того, как ссылаться на предопределенные библиотеки элементов управления для [OWASP Proactive Controls](https://owasp.org/www-project-proactive-controls/) и [AWS Security Checklist](https://d1.awsstatic.com/whitepapers/Security/AWS_Security_Checklist.pdf), смотрите [examples/tm3.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm3.hcl). Также у нас есть [MITRE ATT&CK Controls](https://attack.mitre.org/mitigations/enterprise/) [здесь](https://github.com/threatcl/threatcl/blob/HEAD/examples/MITRE_ATTACK_controls.hcl).

Вы также можете включить внешнюю модель угроз в свою собственную, чтобы ссылаться на всю ее информацию и использовать ее. В качестве примера смотрите [examples/including-example/corp-app.hcl](https://github.com/threatcl/threatcl/blob/HEAD/examples/including-example/corp-app.hcl).

Чтобы увидеть полное описание спецификации, смотрите [здесь](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl) или запустите:```bash
threatcl generate boilerplate

## Запуск с Docker```bash
docker run --rm -it ghcr.io/threatcl/threatcl:latest

Проверьте образ контейнера (тег автоматически разрешается в его дайджест):```bash
gh attestation verify oci://ghcr.io/threatcl/threatcl:<version> --repo threatcl/threatcl

См. [docs/SLSA.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/SLSA.md) для получения полной информации о цепочке поставок.

## Запуск с GitHub Actions

`threatcl` можно напрямую интегрировать в ваши репозитории GitHub с помощью https://github.com/threatcl/threatcl-action. Это один из идеальных способов управления вашими моделями угроз, который помогает достичь цели интеграции в ваши системы контроля версий.

## Сборка из исходного кода

1. Клонируйте этот репозиторий.
2. Перейдите в каталог `threatcl`
3. `make bootstrap`
4. `make build`

Для получения дополнительной помощи по участию в `threatcl` смотрите [CHANGELOG.md](https://github.com/threatcl/threatcl/blob/HEAD/CHANGELOG.md).

## Использование

Для получения справки по любой подкоманде используйте флаг `-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)

Если вы измените эти атрибуты, не забудьте указать конфигурационный файл для других операций, так как это может повлиять на валидацию или создание панели управления.

## Команды Cloud

Посетите https://threatcl.dev/cloud/overview/ чтобы узнать больше о подкомандах `cloud`.

## List и View

Команды `threatcl list` и `threatcl view` можно использовать для вывода списка и просмотра данных из HCL-файлов спецификации `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

### Инварианты

`threatcl validate` может также применять общеорганизационные инварианты — машинно-проверяемые
правила, такие как "нет публичных конечных точек без аутентификации" или "все
функции с выходом в интернет должны документировать аудит логирования" — к каждой
проверенной модели угроз:```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

## Генерация

Команда `threatcl generate` используется для вывода общего шаблонного (`boilerplate`) файла спецификации `threatcl` HCL или для интерактивного опроса пользователя с последующим выводом файла спецификации `threatcl` HCL.

### Интерактивная генерация

См. следующий пример:```bash
threatcl generate interactive

Это откроет ваш редактор с минимальной HCL-моделью угроз. Если вы хотите проверить модель после создания, используйте флаг `-validate`.

## MCP

Команда `threatcl mcp` запускает локальный [MCP](https://modelcontextprotocol.io/introduction) сервер, позволяя вам взаимодействовать с HCL-файлами threatcl через MCP-хост, например, через AI/LLM-приложения, такие как [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/) или любые другие приложения, поддерживающие MCP.

Команда принимает один необязательный аргумент `-dir=<path>`, который позволяет дополнительным MCP-инструментам взаимодействовать с файлами внутри этого пути. Без этой настройки MCP-инструменты могут взаимодействовать со строками, но будут полагаться на другие механизмы MCP-хоста для взаимодействия с файловой системой.

Справедливости ради стоит отметить, что эта функциональность пока находится на стадии беты.

## LSP (Языковой сервер)

Команда `threatcl lsp` запускает сервер [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) через stdio, предоставляя редакторам с поддержкой LSP живую диагностику, автодополнение, всплывающие подсказки, символы документа и форматирование для HCL-моделей угроз threatcl.

Он запускается LSP-клиентом вашего редактора, а не вручную. Поскольку файлы threatcl используют расширение `.hcl` вместе с Terraform и другими HCL-диалектами, сопоставление с `*.tm.hcl` (или ограничение клиента вашей рабочей областью модели угроз) позволяет избежать конфликтов с языковым сервером Terraform.

См. [docs/lsp.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/lsp.md) для настройки редакторов (Neovim, Helix, VS Code, Zed) и текущих ограничений.

## Сервер (GraphQL API)

Команда `threatcl server` запускает GraphQL API сервер, который предоставляет ваши модели угроз через HTTP для программных запросов и интеграции.

### Базовое использование```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

### Документация

Для полной документации API, справки по схеме, продвинутых запросов и примеров интеграции см.:
- **Полная документация API**: [docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md)
- **Примеры запросов**: [examples/graphql-queries.md](https://github.com/threatcl/threatcl/blob/HEAD/examples/graphql-queries.md)

## Запрос (GraphQL CLI)

Команда `threatcl query` выполняет GraphQL-запросы прямо из командной строки без запуска сервера. Это идеально подходит для автоматизации, CI/CD конвейеров и написания сценариев оболочки.

### Основное использование```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"

### Пример 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"

### Пользовательские шаблоны Markdown

Команда `threatcl dashboard` также может принимать необязательные флаги для указания пользовательских шаблонов (в соответствии с [text/template](https://pkg.go.dev/text/template) от Golang).

Чтобы указать файл шаблона панели управления, используйте флаг `-dashboard-template`. Пример см. в [dashboard-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/dashboard-template.tpl).

Чтобы указать файл шаблона модели угроз, используйте флаг `-threatmodel-template`. Пример см. в [threatmodel-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/threatmodel-template.tpl).

### Пользовательское имя файла для индексного файла панели управления

Команда `threatcl dashboard` также может принимать необязательный флаг для указания имени файла для сгенерированного индексного файла панели управления. По умолчанию этот файл называется `dashboard.md`. Используйте флаг `-dashboard-filename` без расширения, чтобы изменить это имя файла.

## Диаграмма потоков данных

Согласно [спецификации](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl), `threatmodel` может содержать блоки `data_flow_diagram_v2`. Пример простой DFD доступен [здесь](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm2.hcl). Старый одноразовый блок `data_flow_diagram` будет в какой-то момент объявлен устаревшим, поэтому лучше использовать именованные блоки `data_flow_diagram_v2`, чтобы можно было иметь несколько связанных DFD.

Команда `threatcl dfd` принимает HCL-файлы спецификации `threatcl` и генерирует несколько PNG-файлов, помещая их в выбранную папку.

Если HCL-файл не содержит блок `threatmodel` с блоком `data_flow_diagram` или `data_flow_diagram_v2`, то ничего не выводится.

Сама команда очень похожа на команду Dashboard.```bash
$ threatcl dfd -overwrite -outdir testout examples/*
Successfully created 'testout/tm2-modellymodel.png'

Это упрощает передачу в рендерер, такой как [mermaid-cli](https://github.com/mermaid-js/mermaid-cli):```bash
$ threatcl mermaid model.hcl | mmdc -o diagram.svg -i -

## Terraform

Команда `threatcl terraform` может извлекать ресурсы данных из вывода `terraform show -json` [документация здесь](https://www.terraform.io/docs/cli/commands/show.html) файлов планов или активных файлов состояния и преобразовывать их в черновики блоков `information_asset` для включения в файлы `threatcl`.

Если вы находитесь в папке с существующим состоянием, вы можете выполнить следующее:```bash
terraform show -json | threatcl terraform -stdin

Вы также можете просмотреть похожий вывод из файла плана, который еще не был применён с помощью Terraform, выполнив команду:```bash
terraform show -json <plan-file> | threatcl terraform -stdin

С флагом `-add-to-existing` вы также можете указать `-tm-name=<string>`, если необходимо указать конкретную модель угроз из исходного файла, если их несколько. Также можно применить классификацию по умолчанию с флагом `-default-classification=Confidential`.

Эти команды также могут принимать файл в качестве входных данных; в этом случае опустите флаг `-stdin`.

Ресурсы Terraform, известные `threatcl`, жестко закодированы в [pkg/terraform/terraform.go](https://github.com/threatcl/threatcl/blob/HEAD/pkg/terraform/terraform.go). Если вы хотите, чтобы команда `threatcl terraform` выводила другие ресурсы `information_asset`, которые там отсутствуют, вы можете предоставить свою собственную версию этого json через флаг `-tf-collection=<json file>`.