threatcl

نمذجة التهديدات باستخدام HCL

ماذا حدث لـ hcltm؟

تمت إعادة تسمية hcltm إلى threatcl. مرحبًا!

نظرة عامة

[!TIP] هل تريد قراءة الوثائق الجديدة؟ تفضل بزيارة threatcl.dev

هناك العديد من الطرق المختلفة التي يمكن بها توثيق نموذج التهديد. بدءًا من ملف نصي بسيط، وصولاً إلى مستندات Word أكثر تفصيلاً، وحتى نماذج التهديدات المدمجة بالكامل في حل مركزي. من بين أكثر السمات قيمة لنموذج التهديد هي القدرة على توثيق التهديدات بوضوح، والقدرة على إحداث تغيير قيّم.

يهدف threatcl إلى توفير نهج DevOps-first لتوثيق نموذج تهديد النظام من خلال التركيز على الأهداف التالية:

تنسيق ملف نصي بسيط
تجربة مستخدم بسيطة تعتمد على سطر الأوامر
التكامل مع أنظمة التحكم في الإصدارات (VCS)

هذا المستودع هو موطن برنامج threatcl لواجهة سطر الأوامر. تعتمد مواصفات threatcl spec على HCL2، لغة تكوين HashiCorp، التي تهدف إلى أن تكون "ممتعة في القراءة والكتابة للبشر، وصيغة قائمة على JSON يسهل على الآلات إنشاؤها وتحليلها". تعيش مواصفات threatcl على github.com/threatcl/spec. الجمع بين برنامج threatcl ومواصفات threatcl يسمح للممارسين بتعريف نموذج تهديد النظام بلغة HCL، على سبيل المثال:

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
  }

}

انظر مخطط تدفق البيانات للحصول على مزيد من المعلومات حول كيفية إنشاء مخططات تدفق البيانات التي يمكن تحويلها إلى صور PNG تلقائيًا.

لرؤية مثال على كيفية الرجوع إلى مكتبات التحكم المحددة مسبقًا لـ ضوابط OWASP الاستباقية وقائمة أمان AWS انظر examples/tm3.hcl. لدينا أيضًا ضوابط MITRE ATT&CK هنا.

يمكنك أيضًا تضمين نموذج تهديد خارجي في نموذجك الخاص، للإشارة إلى جميع معلوماته واستخدامها. يمكنك الاطلاع على examples/including-example/corp-app.hcl كمثال.

لرؤية وصف كامل للمواصفات، انظر هنا أو قم بتشغيل:```bash threatcl generate boilerplate

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

## لماذا HCL؟

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

يمكنك استخدام `threatcl` مع JSON، لكنك تفقد بعض الميزات. للمزيد، راجع مجلد [examples/](https://github.com/threatcl/threatcl/blob/main/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

التشغيل باستخدام Docker```bash

docker run --rm -it ghcr.io/threatcl/threatcl:latest

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

كل إصدار موسوم يأتي مع [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 gh attestation verify oci://ghcr.io/threatcl/threatcl: --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

راجع docs/SLSA.md للحصول على وضع سلسلة التوريد الكامل.

threatcl v0.6.1