Quick Start / Installation

1. Clone the repository:

   git clone https://github.com/ellipse2v/SecOpsTM.git
       cd SecOpsTM
   

2. Install Python dependencies:

   pip install -e .
   

   This command installs all project dependencies and sets up the project in “editable” mode, which is recommended for development. For a standard installation (e.g., for deployment), you can use:

   pip install .
   

   Note on Installation Modes:

   • pip install -e .: Installs the project in “editable” mode. This is recommended for development as any changes you make to the source code in your project directory are immediately reflected without needing to reinstall.
   • pip install .: Performs a standard installation, copying the project files into your Python environment. Use this for deployment or when using the package as a dependency.
3. Install Graphviz (for diagram generation):
   • Windows: https://graphviz.org/download/
   • macOS: brew install graphviz
   • Linux: sudo apt-get install graphviz

After installation, restart your terminal or IDE.

Features

• Markdown-based Threat Modeling: Use a simple DSL to describe your architecture and flows.
• Automated STRIDE Analysis: Detects threats for each element and flow.
• MITRE ATT&CK Mapping: Each threat is mapped to relevant MITRE tactics and techniques.
• Severity Calculation: Customizable scoring (base, target, protocol).
• Comprehensive Reporting:
  • HTML report with integrated threat statistics, detailed threat information, STRIDE/MITRE mapping, and D3FEND mitigations.
  • JSON export for integration or further analysis.
• Visual Diagrams:
  • DOT, SVG, and HTML diagrams with threat highlights.
• Navigable Project Reports:
  • Generate a unified, navigable HTML report for complex projects with multiple nested threat models.
  • Diagrams are interactive, with hover effects (zoom, shadow) on clickable elements.
  • Fully self-contained and works offline, with all necessary assets (like svg-pan-zoom.js) included locally.
• Real-time Markdown Editing: Edit your threat model in Markdown with live diagram preview.
• Extensible: All mappings and calculations are modular and easy to override.
• PyTM Compatibility: Supports PyTM’s model structure and can be extended with PyTM’s features.

1. Command Line Interface (CLI) Mode

Use the CLI mode for automated threat analysis, report generation, and diagram creation. This is ideal for integration into CI/CD pipelines or batch processing.

1. Edit threatModel_Template/threat_model.md to describe your architecture.
2. Run the analysis:

   python -m threat_analysis --model-file threatModel_Template/threat_model.md --navigator
   

   (You can omit --model-file threatModel_Template/threat_model.md if your model file is named threatModel_Template/threat_model.md and is in the root directory.)

3. Generate Attack Flow diagrams: Add the --attack-flow flag to any analysis command to generate optimized Attack Flow .afb files for key objectives.

   python -m threat_analysis --model-file path/to/your_model.md --attack-flow
   

   This will generate one .afb file for each of the main objectives (Tampering, Spoofing, Information Disclosure, Repudiation) found in your model, selecting the highest-scoring path for each.

4. View the results in the generated output/ folder:
   • HTML report
   • JSON export
   • DOT/SVG/HTML diagrams
   • MITRE ATT&CK Navigator layer (JSON)
   • Optimized Attack Flow .afb files

2. Project Mode: Hierarchical Threat Models

The framework excels at handling complex projects with multiple, nested threat models. By structuring your models in directories (e.g., projects/my_app/main.md, projects/my_app/backend/model.md), you can generate a unified, navigable report.

1. Organize your project in the threatModel_Template/projects/ directory (see examples).
2. Run the analysis on the project folder:

   python -m threat_analysis --project threatModel_Template/projects/example_2
   

3. Explore the output: A fully interactive, cross-linked HTML report will be generated in the output/ directory. Diagrams for sub-models are placed in corresponding sub-directories, with all links and asset paths adjusted automatically.

3. Infrastructure as Code (IaC) Integration (Ansible Example)

This framework can automatically generate a complete threat model directly from IaC configurations. It automatically includes a set of default protocol styles from threatModel_Template/base_protocol_styles.md to ensure consistent visualization.

Here’s how to use the Ansible plugin with a sample playbook:

1. Ensure you have the test playbook: The sample Ansible playbook is located at tests/ansible_playbooks/simple_web_server/simple_web_server.yml.
2. Run the analysis with the Ansible plugin:

   python -m threat_analysis --ansible-path tests/ansible_playbooks/simple_web_server/simple_web_server.yml
   

   This command will generate a complete threat model based on the Ansible playbook. The generated Markdown model will be saved in the output/ directory with a filename derived from your Ansible playbook (e.g., simple_web_server.md).

   If you wish to specify a different output file for the generated model, you can use the --model-file option:

   python -m threat_analysis --ansible-path tests/ansible_playbooks/simple_web_server/simple_web_server.yml --model-file my_generated_model.md
   

3. View the results in the generated output/ folder, which will now include elements from your Ansible configuration.

4. CVE-Based Threat Generation (Optional)

This framework can generate threats based on a list of Common Vulnerabilities and Exposures (CVEs) that you provide for specific components in your threat model.

Prerequisites

To use this feature, you must first clone the CVE2CAPEC repository from GitHub next to the SecOpsTM project directory.

# In the same directory where you cloned SecOpsTM
git clone https://github.com/Galeax/CVE2CAPEC.git

This will create a directory structure like this:

/your/development/folder/
├── SecOpsTM/
└── CVE2CAPEC/

The tool will then use the CVE2CAPEC database to map your specified CVEs to CAPEC attack patterns, which are then used to identify relevant MITRE ATT&CK techniques.

Usage

1. Create cve_definitions.yml: In the root of the SecOpsTM project, create a file named cve_definitions.yml.

2. Define CVEs for your equipment: In this file, list the equipment (servers or actors from your threat model) and the CVEs associated with them.

   Example cve_definitions.yml:

   # The equipment name must match the name of a server or actor in your threat_model.md file.
   
   WebServer:
     - CVE-2021-44228 # Log4Shell
     - CVE-2023-1234
   
   DatabaseServer:
     - CVE-2022-5678
   

3. Run the analysis: Run the analysis as usual. The tool will automatically detect the cve_definitions.yml file, generate threats based on the CVEs, and include them in the report.

   python -m threat_analysis --model-file path/to/your_model.md
   

   The new CVE-based threats will appear in the generated report, linked to the corresponding equipment.

Web-based Graphical User Interface (GUI) Mode (Optional)

Launch the interactive web editor to visualize your threat model in real-time, edit Markdown content, and export various formats directly from your browser.

Launch the GUI: bash python -m threat_analysis --gui The console will display the address (e.g., http://127.0.0.1:5001) where you can access the GUI in your web browser.

Note: When using --gui, the --model-file option can be used to load an initial threat model as a template into the editor. If not provided, the GUI will start with an an empty editor.

Threat Model DSL & Examples (threatModel_Template/threat_model.md)

This framework leverages PyTM’s modeling primitives. For a comprehensive reference of all available attributes and their usage, please refer to the PyTM Documentation. Note that this framework may extend PyTM with additional attributes or behaviors.

# Threat Model: Advanced DMZ Architecture

## Description
A network with a DMZ, external/internal firewalls, and a command zone. The goal is to identify STRIDE threats and map them to MITRE ATT&CK.

## Boundaries
- **Internet**: color=lightcoral
- **DMZ**: color=khaki
- **Intranet**: color=lightgreen
- **Command Zone**: color=lightsteelblue

## Actors
- **External Client 1**: boundary=Internet
- **Operator**: boundary=Command Zone

## Servers
- **External Firewall**: boundary=DMZ
- **Internal Firewall**: boundary=Intranet
- **Central Server**: boundary=Intranet

## Data
- **Web Traffic**: classification=public, lifetime=transient

## Dataflows
- **External Client to External Firewall**: from="External Client 1", to="External Firewall", protocol="HTTPS", data="Web Traffic", is_encrypted=True

## Severity Multipliers
- **Central Server**: 1.5
- **External Firewall**: 2.0

## Custom Mitre Mapping
- **Protocol Tampering**: tactics=["Impact", "Defense Evasion"], techniques=[{"id": "T1565", "name": "Data Manipulation"}]

Common Attributes

Several elements in the threat model DSL support common attributes to enhance their representation and behavior:

• color: Specifies the color of the element in the generated diagrams.
  • Applies to: Boundaries, Actors, Dataflows, Protocol Styles.
  • Values: Can be a standard HTML color name (e.g., red, blue, lightgray), or a hexadecimal color code (e.g., #FF0000).
• line_style: Defines the style of lines for dataflows or protocols in diagrams.
  • Applies to: Protocol Styles.
  • Values: solid, dashed, dotted.
• is_trusted: Indicates whether a Boundary is considered trusted. This can influence threat analysis.
  • Applies to: Boundaries.
  • Values: True or False.
• is_encrypted: Specifies whether a Dataflow is encrypted. This is crucial for information disclosure threat analysis.
  • Applies to: Dataflows.
  • Values: True or False.

Protocol Styles and Legends

To ensure that protocols are correctly styled in diagrams and appear in the legend, you must define them in the ## Protocol Styles section of your threat model. The system intentionally does not assign default colors to new protocols. This gives you full control over the final visualization.

How it works:

1. Use a protocol in a Dataflow, e.g., protocol="NEW_PROTO".
2. Define its style under ## Protocol Styles to make it appear in the legend: ```markdown

   Protocol Styles

   • HTTPS: color=darkgreen, line_style=solid
   • HTTP: color=red, line_style=solid
   • NEW_PROTO: color=cyan, line_style=dotted ```

If you skip step 2, the protocol will be drawn in the diagram with a default style, but it will not be included in the legend.

Bidirectional Dataflow Visualization

This makes bidirectional communications visually clear and reduces clutter in your architecture diagrams.

Example:

If your model contains:

## Dataflows
- A to B: from="A", to="B", protocol="HTTPS"
- B to A: from="B", to="A", protocol="HTTPS"

The diagram will show:

A <--> B

(with a single arrow using dir="both" in DOT/Graphviz)

This feature is enabled by default and works for all protocols.

Report

After running the analysis, you will find a timestamped folder in output/ (e.g., output/example) containing:

• stride_mitre_report.html:
  
• mitre_analysis.json:

  {
    "analysis_date": "2025-06-29T15:31:56.517773",
    "threats_detected": 183,
    "threat_types": [
      "Threat",
      "Tampering",
      "Information Disclosure",
      "Elevation of Privilege",
      "Spoofing",
      "Denial of Service",
      "Repudiation"
    ],
    "mitre_mapping": {
      "Spoofing": {
        "tactics": [
          "Initial Access",
          "Defense Evasion",
          "Credential Access"
        ],
        "techniques": [
          {
            "id": "T1566",
            "name": "Phishing",
            "description": "Identity spoofing via phishing"
          }
        ]
      },
      "Tampering": {
        "tactics": [
          "Defense Evasion",
          "Impact",
          "Initial Access",
          "Execution"
        ],
        "techniques": [
          {
            "id": "T1565",
            "name": "Data Manipulation",
            "description": "Unauthorized data modification"
          }
        ]
      }
    },
    "detailed_threats": [
      {
        "type": "Threat",
        "description": "Vulnerability in the management interface of External Firewall",
        "target": "External Firewall",
        "severity": {"score": 8.5, "level": "HIGH"},
        "mitre_techniques": [{"id": "T1068", "name": "Exploitation for Privilege Escalation"}],
        "stride_category": "Elevation of Privilege"
      },
      {
        "type": "Threat",
        "description": "Lateral movement from Central Server to other systems in the network",
        "target": "Central Server",
        "severity": {"score": 8.5, "level": "HIGH"},
        "mitre_techniques": [{"id": "T1021", "name": "Remote Services"}],
        "stride_category": "Elevation of Privilege"
      },
      {
        "type": "Threat",
        "description": "Insecure security configuration or hardening on App Server 1",
        "target": "App Server 1",
        "severity": {"score": 6.0, "level": "MEDIUM"},
        "mitre_techniques": [{"id": "T1562", "name": "Impair Defenses"}],
        "stride_category": "Information Disclosure"
      },
      {
        "type": "Threat",
        "description": "Data exfiltration or leakage from Application Database",
        "target": "Application Database",
        "severity": {"score": 8.5, "level": "HIGH"},
        "mitre_techniques": [{"id": "T1041", "name": "Exfiltration Over C2 Channel"}],
        "stride_category": "Information Disclosure"
      }
    ]
  }
  

• tm_diagram__example.dot:
  (Graphviz DOT format for architecture)

• tm_diagram__example.svg:
  

• Project Structure Example:

• MITRE ATT&CK Navigator Integration:

Note: All screenshots and example files are located in the output/example/ directory for easy preview and documentation.

Roadmap

• Vulnerability Database Integration: Link ATT&CK techniques to CVEs for deeper context.
• Attack Path Simulation: Algorithms to identify and visualize potential attack paths.
• Expanded IaC Support: New plugins for Terraform and CloudFormation.
• ML-Enhanced Threat Identification: Using machine learning to predict new threats.
• Offline LLM Enhancement: Integrate a local LLM for advanced contextual threat analysis.
• Attack path generation: compatible with Attack Flow.

Tooling Scripts Documentation

This document provides an explanation for each of the Python scripts located in the tooling/ directory. These scripts are used for data acquisition, data processing, and quality assurance for the threat modeling framework.

build_stride_capec_mapping.py

• Purpose: Builds the stride_to_capec.json file, which maps STRIDE threat categories to specific CAPEC (Common Attack Pattern Enumeration and Classification) entries.
• Process:
  1. Scrapes data from Markdown files on ostering.com.
  2. Applies manual corrections from a hardcoded CORRECTIONS dictionary.
  3. Enriches the data with supplemental mappings from a SUPPLEMENTAL_MAPPINGS dictionary.
  4. Writes the final data to threat_analysis/external_data/stride_to_capec.json.
• Usage: A data maintenance tool to be run when the source data changes or when manual corrections need to be updated.

capec_mitre_parser.py

• Purpose: A web scraper to parse and extract detailed information from the official CAPEC and MITRE ATT&CK websites.
• Functionality:
  • parse_capec_entry(capec_id): Fetches a specific CAPEC page and extracts details like title, description, severity, mitigations, etc.
  • parse_mitre_attack_technique(technique_id): Fetches a specific MITRE ATT&CK technique page and extracts details like tactics, platforms, mitigations, etc.
  • Saves the aggregated results into a capec_mitre_results.json file.
• Usage: An ad-hoc tool for deep-diving into specific attack patterns or techniques for research purposes.

capec_to_mitre_builder.py

• Purpose: Creates the capec_to_mitre_structured_mapping.json file, which bridges CAPEC attack patterns and MITRE ATT&CK techniques.
• Process:
  1. Downloads a ZIP file with CAPEC data in CSV format from the MITRE website.
  2. Parses the CSV to extract CAPEC ID, name, and linked ATT&CK techniques.
  3. Uses a web scraping fallback to fetch ATT&CK techniques from the CAPEC HTML page if they are missing in the CSV.
  4. Adds a few hardcoded manual mappings.
  5. Saves the structured JSON to threat_analysis/external_data/capec_to_mitre_structured_mapping.json.
• Usage: A crucial data-building script that should be run periodically to keep the CAPEC to ATT&CK mapping up-to-date.

cis_controls_parser.py

• Purpose: Parses the official CIS Controls to MITRE ATT&CK mapping from an Excel file and converts it to a structured JSON file.
• Process:
  1. Reads the CIS_Controls_v8_to_Enterprise_ATTCK_v82_Master_Mapping__5262021.xlsx file.
  2. Extracts the CIS Safeguard ID, title, and the corresponding MITRE ATT&CK Technique ID.
  3. Generates a documentation URL for each CIS control.
  4. Saves the data as cis_to_mitre_mapping.json in threat_analysis/external_data/.
• Usage: Generates a key data file for suggesting CIS Control mitigations. Run if the source Excel file is updated.

copy_cve_data.py

• Purpose: A utility to copy the CVE-to-CAPEC mapping database from an external repository into the project’s external_data directory.
• Process:
  1. Assumes the CVE2CAPEC repository is cloned next to the project directory.
  2. Copies the database directory from CVE2CAPEC to threat_analysis/external_data/cve2capec.
• Usage: Must be run by a developer after cloning the CVE2CAPEC repository to enable the optional CVE-based threat generation feature.

download_attack_data.py

• Purpose: Downloads data from MITRE.
• Functionality: The active code is configured to download a CSV file from capec.mitre.org and save it as CAPEC_VIEW_ATT&CK_Related_Patterns.csv.
• Usage: A data acquisition script. (Note: There is a discrepancy between the script’s comments, which mention enterprise-attack.json, and its active code).

download_nist_data.py

• Purpose: Downloads the official NIST 800-53 R5 to MITRE ATT&CK mapping file.
• Process:
  1. Downloads the nist800-53-r5-mappings.xlsx file from the “Center for Threat-Informed Defense” GitHub repository.
  2. Saves the file to threat_analysis/external_data/.
• Usage: Acquires the necessary data file for providing NIST 800-53 control suggestions.

generate_attack_flow.py

• Purpose: A library of helper functions to programmatically generate .afb files compatible with the attack-flow application.
• Functionality: Provides functions like create_action_object, create_asset_object, and create_connection_objects to build the components of an attack flow diagram.
• Usage: This script is a toolkit used by other parts of the application (like the AttackFlowGenerator class) to construct attack flow diagrams. It does not perform any analysis itself.

validate_capec_json.py

• Purpose: Validates the local stride_to_capec.json file against the official MITRE CAPEC website to ensure descriptions are correct.
• Process:
  1. Loads the local JSON file.
  2. For each entry, it scrapes the official CAPEC definition page on capec.mitre.org.
  3. It compares the local description with the official online description.
  4. It prints a summary report of any mismatches found.
• Usage: A quality assurance tool to be run after build_stride_capec_mapping.py to check for data drift or scraping errors.