Working with Libraries

Libraries let you create reusable collections of threats and controls that can be shared across multiple threat models. Build your organization's security knowledge base once, use it everywhere.

Why Use Libraries?

🔄 Consistency

Use the same threat and control definitions across all your threat models. No more copy-pasting or maintaining duplicates.

📊 Metrics

Track which threats and controls are most commonly used across your organization. Identify gaps and priorities.

🚀 Speed

Build new threat models faster by referencing existing library items instead of writing everything from scratch.

📚 Knowledge Base

Build organizational knowledge over time. New team members can learn from your curated threat and control catalog.

Getting Started with Libraries

Setting up your first library items is straightforward:

Step 1: Navigate to Libraries

From your organization's dashboard, click "Libraries" in the navigation. This is your central hub for managing reusable threats and controls.

Step 2: Choose Threat or Control Library

From the Libraries page you can navigate between the Threat Library and Control Library. Each has its own section for managing items relevant to that type.

Step 3: Organize with Folders

Create folders to organize your library items. For example, you might group controls by compliance framework (PCI-DSS, SOC 2) or threats by technology area (Web, API, Cloud).

Step 4: Add Library Items

Use the "New Threat" or "New Control" buttons to add new items to your library. Each item can include a description, metadata, and other details that will be shared when referenced in threat models.

Using Libraries in Threat Models

Once you've created and published library items, you can reference them in your HCL threat model files using the ref   attribute on threat   and control   blocks.

Referencing Library Items

Add a ref   attribute to a threat or control block with the library item's ID. Values like description will default to the library item, but you can specify them locally to override the referenced values:

spec_version = "0.2.4"
backend "threatcl-cloud" {
  organization = "your-org"
  threatmodel = "your-model"
}

threatmodel "app" {
  description = "A special app"
  author = "you"

  threat "sqli" {
    ref = "T-SQLI"
  }

  threat "DDoS" {
    description = "Distributed Denial of Service"

    control "cdn" {
      ref = "C-CDN"
    }
  }
}

Things to Note

• Blocks with a ref   don't need description   attributes — these will default to the library item's values. However, you can specify them locally to override the referenced values.
• The referenced IDs should exist within your Control or Threat Library.
• The referenced items should be "Published", not in Draft.

$ threatcl cloud validate model.hcl
✓ Local Threat model file matches a cloud threat model
⚠ Warning: non-PUBLISHED control refs: [C-CDN (DRAFT)]
✓ 1 threat ref(s) validated (PUBLISHED)

Library Export and Import with Threatcl CLI

The threatcl   CLI lets you export your organization's library items as HCL files, making it easy to back up, share, or manage libraries across environments.

Exporting Libraries

Use threatcl cloud library export   to export your organization's threat and control library as HCL. By default, published items are written to stdout.

# Export all published library items to stdout
$ threatcl cloud library export

# Export to a file
$ threatcl cloud library export -o library.hcl

# Export only threats
$ threatcl cloud library export -type threats -o threats.hcl

# Export only controls with specific tags
$ threatcl cloud library export -type controls -tags "owasp,injection" -o controls.hcl

# Include draft items in the export
$ threatcl cloud library export -include-drafts -o full-library.hcl

Key options:

• -type   — Filter by threats   or controls  
• -status   — Filter by status (e.g. PUBLISHED  , DRAFT  )
• -folder   — Filter by folder path
• -tags   — Comma-separated tag filter
• -o   — Output to a file instead of stdout

Importing Libraries

Use threatcl cloud library import   to import a local HCL library file into Threatcl Cloud. The file must have a .hcl   extension and be no larger than 10MB.

# Import a library file (create-only mode by default)
$ threatcl cloud library import library.hcl

# Import with update mode (create new and update existing items)
$ threatcl cloud library import -mode update library.hcl

# Import with replace mode to a specific org
$ threatcl cloud library import -org-id org-123 -mode replace library.hcl

Import modes:

• create-only   (default) — Only create new items, skip existing ones
• update   — Create new items and update existing ones
• replace   — Replace the entire library with the imported content

HCL Library Format

Exported libraries use a structured HCL format with a library_metadata   block, followed by threat_library   and control_library   blocks. Items can be organized into folders. This is the same format used for importing.

Example:

library_metadata {
  version       = "1.0.0"
  organization  = "acme"
  export_date   = "2026-02-11T13:00:08Z"
  export_source = "threatcl-cloud"
}

threat_library {
  folder "Web Threats" {
    threat "SQL Injection" {
      reference_id         = "T-SQLI"
      status               = "published"
      version              = "2.0.14"
      description          = "SQL Injection attack"
      impacts              = ["Confidentiality"]
      stride               = ["Elevation of Privilege", "Denial of Service"]
      severity             = "critical"
      likelihood           = "very_high"
      recommended_controls = ["C-PQUERY"]
    }
  }
  threat "Repudiation" {
    reference_id = "T-REPUD"
    status       = "published"
    version      = "1.0.3"
    description  = "User denies performing an action"
    stride       = ["Repudiation"]
  }
}

control_library {
  folder "Input Controls" {
    control "Input Validation" {
      reference_id            = "C-INPUTVALID"
      status                  = "published"
      version                 = "1.0.9"
      description             = "Validate and sanitize all input"
      control_type            = "preventive"
      control_category        = "technical"
      implementation_guidance = "Implementation guidance here"
      effectiveness_rating    = 50
      nist_controls           = ["SI-7"]
      cis_controls            = ["4.1"]
      tags                    = ["input", "validation"]
      default_risk_reduction  = 40
    }
    control "Parameterized Queries" {
      reference_id           = "C-PQUERY"
      status                 = "published"
      version                = "1.0.7"
      description            = "Use parameterized queries to prevent injection"
      control_type           = "preventive"
      control_category       = "technical"
      mitigates_threats      = ["T-SQLI"]
      default_risk_reduction = 85
    }
  }
  control "Audit Logging" {
    reference_id           = "C-AUDIT"
    status                 = "published"
    version                = "1.0.5"
    description            = "Comprehensive audit logging"
    control_type           = "detective"
    control_category       = "technical"
    default_risk_reduction = 50
  }
}

Best Practices

1. Start Small

Begin with 10-15 most common threats and controls. Grow your library organically as you create more threat models.

2. Include Implementation Guidance

Add detailed implementation_guidance   to controls so teams know exactly how to implement them.

3. Use Consistent Naming

Use clear, descriptive names for libraries and items. Avoid abbreviations that aren't universally understood.

4. Tag and Categorize

Use custom attributes to categorize items by framework (OWASP, NIST, etc.), technology (web, mobile, cloud), or severity.

5. Review Regularly

Schedule quarterly reviews of your libraries. Update for new threats, emerging vulnerabilities, and evolving best practices.

6. Track Usage

Use Threatcl Cloud's analytics to see which library items are most/least used. This helps identify gaps and redundancies.

Next Steps

Team Collaboration