threatmodel "my-threat-model" {
  description = "My threat model"

  author "coolguy" {
    email = ["[email protected]", "[email protected]"]
  }

  information "Stakeholders" {
    description = <<-DESCRIPTION
      This is a description of the stakeholders
    DESCRIPTION
  }

  threat {
    id = "Inform the driver of account status"
    description = "An attacker could possibly determine if an account exists"
    risk = "Low"
    status = "Recommend"
    control = "Implement an authentication mechanism that does not reveal account information"
    stride = "Information Disclosure"
  }

  component "api-gateway" {
    description = "This is the API Gateway"
    threat {
      id = "Authenticate requests"
      description = "An attacker may be able to access the API"
      risk = "High"
      status = "Mitigated"
      control = "All requests to the API must have a valid authorization token"
      stride = "Spoofing"
    }
    data-flow "read-user" {
      description = "Read user data"
      source = "api-gateway"
      destination = "user-db"
      protocol = "tcp"
      threat {
        id = "TLS"
        description = "An attacker could read data in transit"
        risk = "High"
        status = "Mitigated"
        control = "All data in transit must use TLS"
        stride = "Tampering"
      }
    }
  }
}

threatcl plan
``````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
  }

}

`threatcl` سيعالج أيضًا ملفات JSON، لكن التحذير الوحيد هو أن وحدات الاستيراد والمتغيرات لن تعمل. يمكنك رؤية [examples/tm1.json](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm1.json) كمثال.

## لماذا HCL؟

HCL هي لغة التهيئة الأساسية المستخدمة في منتجات HashiCorp، وبشكل خاص [Terraform](https://www.terraform.io/) - برنامج البنية التحتية كرمز مفتوح المصدر. عملت في HashiCorp لفترة وتعلقت باللغة حقًا، بالإضافة إلى أنه إذا كان مهندسو DevOps والبرمجيات يستخدمون اللغة، فإن تبسيط كيفية توثيق نماذج التهديدات يتماشى مع أهداف `threatcl`.

يمكنك استخدام `threatcl` مع JSON، لكنك تفقد بعض الميزات. للمزيد، راجع مجلد [examples/](https://github.com/threatcl/threatcl/blob/HEAD/examples/).

## لماذا لا توثقها ببساطة في MD؟

أحببت فكرة استخدام تنسيق يمكن التفاعل معه برمجيًا.

## الشكر والمراجع

إحدى ميزات `threatcl` هي التوليد التلقائي لـ [رسوم تدفق البيانات](#data-flow-diagram) من ملفات HCL. هذا يستخدم حزمة [go-dfd](https://github.com/marqeta/go-dfd) من Marqeta و [Blake Hitchcock](https://github.com/rbhitchcock). تأكد من الاطلاع على مقالهم [Threat models at the speed of DevOps](https://community.marqeta.com/t5/engineering-blogs/threat-models-at-the-speed-of-devops/ba-p/40).

بالإضافة إلى ذلك، أود أن أتقدم بالشكر إلى [Jamie Finnigan](https://twitter.com/chair6) و [Talha Tariq](https://twitter.com/0xtbt) في HashiCorp للسماح لي بمواصلة العمل على هذه الأداة مفتوحة المصدر حتى بعد أن انتهيت من عملي مع HashiCorp.

وأيضًا شكر لأعضاء IriusRisk على [مواصفات OpenThreatModel](https://github.com/iriusrisk/OpenThreatModel).

# threatcl cli

## التثبيت

قم بتنزيل أحدث إصدار من [releases](https://github.com/threatcl/threatcl/releases) وانقل الملف الثنائي `threatcl` إلى مسار PATH الخاص بك.

## التثبيت باستخدام Homebrew

قم بتثبيت `threatcl` باستخدام [Homebrew](https://brew.sh/) — الصيغة موجودة في homebrew-core:```bash
brew install threatcl

## التحقق من الإصدارات (أصل البناء)

كل إصدار موسوم يأتي مع [SLSA](https://slsa.dev) لأصل البناء — شهادات موقعة من Sigstore، بدون مفاتيح، تم إنشاؤها بواسطة خط أنابيب إصدار GitHub Actions (GitHub OIDC ← Fulcio، بدون مفاتيح توقيع). يمكنك التحقق من أن ملفًا ثنائيًا أو صورة الحاوية قد بُنيت بالفعل من سير عمل الإصدار لهذا المستودع باستخدام [GitHub CLI](https://cli.github.com) (`gh attestation verify` — لا حاجة لأدوات إضافية أو مفاتيح موثوقة لإدارتها).

تحقق من أرشيف تم تنزيله (أو ملف `SHA256SUMS`):```bash
gh attestation verify threatcl_<version>_<os>_<arch>.tar.gz --repo threatcl/threatcl

لتثبيت الصورة المحددة التي تقوم بتشغيلها، قم بحل الملخص بنفسك وتحقق (واسحب) من خلال الملخص:```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

## (اختياري) ملف التهيئة

معظم أوامر `threatcl` تحتوي على علامة `-config` تتيح لك تحديد ملف `config.hcl`. يمكن استخدام HCL داخل هذا الملف لتجاوز بعض السمات الافتراضية لـ `threatcl`. هذه السمات مذكورة أدناه:

- **أحجام المبادرات** - القيم الافتراضية هي "Undefined", "Small", "Medium", "Large"
- **حجم المبادرة الافتراضي** - القيمة الافتراضية هي "Undefined
- **تصنيفات المعلومات** - القيم الافتراضية هي "Restricted", "Confidential", "Public"
- **تصنيف المعلومات الافتراضي** - القيمة الافتراضية هي "Confidential"
- **أنواع التأثير** - القيم الافتراضية هي "Confidentiality", "Integrity", "Availability"
- **عناصر STRIDE** - القيم الافتراضية هي "Spoofing", "Tampering", "Info Disclosure", "Denial Of Service", "Elevation Of Privilege"
- **تصنيفات الاعتماد على وقت التشغيل** - القيم الافتراضية هي "none", "degraded", "hard", "operational"
- **تصنيف الاعتماد على وقت التشغيل الافتراضي** - القيمة الافتراضية هي "none"

على سبيل المثال:```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"

## التحقق

يُستخدم الأمر `threatcl validate` للتحقق من ملف HCL لمواصفات `threatcl`.```bash
$ threatcl validate examples/*
Validated 3 threatmodels in 3 files

تعيش الثوابت (Invariants) في ملف HCL خاص بها، وتستهدف مجموعة محددة (التهديدات، الضوابط، عمليات DFD، التدفقات، ...)، وتعبر عن شرطها كتعبير HCL أصلي. وهي تدعم مستويات الخطورة `error`/`warning` والإعفاءات لكل نموذج مع مبررات. انظر [docs/invariants.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/invariants.md).

## التصدير

يُستخدم الأمر `threatcl export` لتصدير نموذج تهديد (أو نماذج) `threatcl` إلى تمثيل JSON الأصلي (افتراضيًا)، أو إلى تمثيل [OTM](https://github.com/iriusrisk/OpenThreatModel) بصيغة json، أو حتى العودة إلى صيغة `hcl` (وهو مفيد لإخراج HCL جديد من نماذج التهديد الديناميكية). يمكنك أيضًا حفظها مباشرة في ملف باستخدام العلامة `-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}}]}]

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

### إنشاء محرر تفاعلي

إذا كنت تفضل العمل مباشرة في `$EDITOR`، فقم بتشغيل:```bash
threatcl generate interactive editor

انتقل إلى `http://localhost:8080` للوصول إلى واجهة GraphQL Playground التفاعلية.

### مثال على الاستعلام```graphql
query {
  stats {
    totalThreatModels
    totalThreats
    implementedControls
  }

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

### صيغ الإخراج

- `pretty` (افتراضي): JSON منسق مع مسافة بادئة
- `json`: نفس pretty
- `compact`: JSON في سطر واحد للبرمجة النصية

### استعلام مع متغيرات```bash
$ threatcl query -dir ./examples \
    -query 'query($author: String) { threatModels(filter: {author: $author}) { name } }' \
    -vars '{"author": "John Doe"}'

اطّلع على [docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md) للاستعلامات المتاحة ومخطط GraphQL.

## لوحة التحكم

يقوم الأمر `threatcl dashboard` بأخذ ملفات HCL الخاصة بمواصفات `threatcl`، ويقوم بتوليد عدد من ملفات markdown و png، ووضعها في مجلد محدد.```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'

إذا كان نموذج التهديد `threatmodel` الخاص بك لا يتضمن `diagram_link`، ولكنه يتضمن `data_flow_diagram`، فسيتم عرض ذلك أيضًا عند تشغيل `threatcl dashboard`.

## Mermaid

وفقًا لـ [المواصفات](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl)، قد يتضمن نموذج التهديد `threatmodel` أيضًا كتل `mermaid` حرة الشكل. على عكس `data_flow_diagram_v2` (التي يقوم `threatcl` بعرضها لك)، تقوم كتلة `mermaid` بتضمين مصدر [mermaid](https://mermaid.js.org/) الخام حرفيًا - يقوم mermaid باستنتاج نوع الرسم البياني (تسلسل، حالة، مخطط تدفق، إلخ) من السطر الأول من المحتوى.

يقوم أمر `threatcl mermaid` باستخراج ذلك المصدر الخام ليتم توجيهه إلى أدوات عرض أخرى. لا يقوم هو نفسه بعرض الصور.

افتراضيًا، تتم طباعة المصدر إلى STDOUT:```bash
$ threatcl mermaid examples/tm2.hcl
sequenceDiagram
  User->>App: credentials
  App->>Auth: verify
  Auth-->>App: token

إذا كان هناك عدة كتل `mermaid`، قم باختيار واحد باستخدام `-index=n`، أو كتابتها جميعًا إلى مجلد باستخدام `-outdir` (ملف `.mmd` واحد لكل كتلة). يمكنك أيضًا كتابة كتلة واحدة إلى ملف باستخدام `-out`.```bash
$ threatcl mermaid -outdir testout model.hcl
Successfully created 'testout/model-mymodelloginsequence.mmd'

سيُنتج هذا شيئًا مشابهًا لهذا:```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"
}

إذا كنت تريد تحديث ملف نموذج التهديد `threatcl` الموجود ("threatmodel.hcl") يمكنك ذلك باستخدام:```bash
terraform show -json <plan> | threatcl terraform -stdin -add-to-existing=threatmodel.hcl > new-threatmodel.hcl