Proposal: AI-Assisted Threat Modeling Workflow — A Practical Implementation for Complex Systems

[zhangtianqi-james]

Proposal: AI-Assisted Threat Modeling Workflow — A Practical Implementation for Complex Systems

Abstract: Manual threat modeling for complex systems is hard. I've developed an workflow(skills) that reduces effort from 4-8 hours to 10-30 minutes with ~85% validation pass rate. While SecOpsTM's AI dialog generates quick prototypes from single prompts, this skill delivers production-quality threat models through structured 10-step workflows with source traceability, automated validation, and complete output artifacts (model + context + BOM + config/asset_types_community.yaml + config/protocols_community.yaml). Proposing to integrate parts of this workflow (skill) into SecOpsTM mainline.

I'm open to your guidance on:

• Which approach (if any) aligns with SecOpsTM's direction
• What would be most valuable for the community
• Whether to keep this as a separate skill/project

---

Background

After proposing the Custom Asset Type Support feature in discussion #27, I encountered a practical implementation challenge:

When modeling specialized systems (e.g., DJI Power Inspection Drone, industrial IoT, SCADA equipment), manually creating a complete threat model with all required DSL fields is extremely difficult without:

• Complete system architecture documentation
• Detailed network topology information
• Comprehensive asset inventory
• Security control specifications
• Data classification policies

The gap: Even with custom asset type support, users still face a high barrier to entry for creating production-quality threat models.

---

Problem Statement

Current Workflow Limitations

Step	Manual Process	Pain Points
1. Information Gathering	Search documentation, white papers, manuals	❌ No structured checklist; critical information is easily overlooked
2. Asset Identification	Infer component types from descriptions	❌ 31 standard types are insufficient to cover specialized systems
3. Boundary Definition	Design trust boundaries	❌ Requires understanding of system architecture for correct delineation
4. Dataflow Mapping	Document all data flows	❌ Hidden data flows are easily overlooked
5. Custom Type Definition	Define non-standard assets/protocols	❌ Requires manually editing config/asset_types_community.yaml
6. Context/BOM Creation	Generate GDAF context and BOM YAML	❌ Requires manually writing YAML, prone to formatting errors
7. Validation	Run secopstm --model-file model.md	❌ Error feedback is unfriendly, requiring repeated revisions

Real-World Example

Modeling a DJI Power Inspection Drone System requires:

• 15+ servers (drone, ground station, command&control, video streaming, etc.)
• 20+ dataflows (telemetry, video, commands, firmware updates, etc.)
• 5+ boundaries (air space, ground network, cloud, etc.)
• Custom asset types (uav-platform, flight-controller, gcs-software)
• Custom protocols (OCUSync-3, Lightbridge, DJI-SDK)
• GDAF context (attack objectives, threat actors, risk criteria)
• BOM files (OS versions, software versions, known CVEs)

Manual effort: 4-8 hours for an experienced security architect, with high risk of errors.

---

Proposed Solution: AI-Assisted Threat Modeling Workflow

I've developed a structured AI-assisted workflow that addresses these pain points. The workflow is implemented as an Agent skill (for Claude Code / OpenCode) that guides users through a 10-step process:

Workflow Overview

Step 1: Information Gathering → Search public sources, document findings Step 2: Information Staging → Structured storage in .tm-raw/ directory Step 3: Complexity Assessment → Determine single-model vs multi-subsystem Step 4: Custom Type Detection → Auto-detect non-standard assets/protocols Step 5: Strategy Confirmation → Present modeling strategy, wait for user approval Step 6: Model Generation → Generate model.md from staging files Step 7: Context/BOM Generation → Auto-generate YAML files with scripts Step 8: Config Generation → Create config/ for custom types/protocols Step 9: User Review → User supplements sensitive information Step 10: Validation → Run validate_model.py, ensure 0 failures

Key Features

1. Structured Information Collection

{system-name}/.tm-raw/
├── _search-log.md # Search keywords, URLs, timestamps, credibility
├── architecture.md # System architecture
├── assets.md # Asset inventory
├── actors.md # Actor definitions
├── boundaries.md # Boundary information
├── data.md # Data assets
├── dataflows.md # Data flow information
├── security.md # Security controls
├── context.md # GDAF context
├── protocol-styles.md # Protocol styles
├── severity.md # Severity multipliers
├── mitre-mapping.md # Custom MITRE mapping
└── compliance.md # Compliance requirements

Benefits:

• ✅ Source traceability (each info item tagged with source)
• ✅ Conflict detection (marked as Conflict:)
• ✅ Missing info tracking (marked as To be supplemented:)
• ✅ Incremental updates (support multiple collection rounds)

2. Automated Validation

python scripts/validate_model.py --model-dir .

# Validation Checks:
- DSL enum values (all hard-constraint fields use valid values)
- DSL format (use `- **Name**: key=value` list format)
- Boundary references (all `boundary=` references are defined)
- Actor/Dataflow references (all `from=`, `to=`, `data=` references exist)
- BOM correspondence (each Server has corresponding YAML file)
- config/ directory (custom types/protocols are defined)
- YAML syntax (pure YAML format, not nested)
- submodel paths (paths point to existing files)
- Language check (output files all in English)

3. Script-Based Generation

Context YAML Generation:

python scripts/generate_context.py --model model.md --output context/
# Auto-generates: attack_objectives, threat_actors, risk_criteria

BOM YAML Generation:

python scripts/generate_bom.py --model model.md --output BOM/
# Auto-generates: one simple YAML file per Server

Benefits:
✅ No manual YAML writing (avoids format errors)
✅ Consistent structure (follows SecOpsTM conventions)
✅ GDAF-ready (includes all required fields)

4. Output Structure

Single-Model (≤15 Servers):
{system-name}/
├── model.md
├── context/
│ └── {system-name}_context.yaml
├── BOM/
│ └── {asset_name}.yaml
└── config/ # Optional
├── asset_types_community.yaml
└── protocols_community.yaml

Multi-Subsystem (>15 Servers):
{project-name}/
├── main.md # Top-level architecture
├── context/
│ └── {project-name}_context.yaml # Global Context
├── {subsystem1}/
│ ├── model.md
│ └── BOM/
└── config/ # Optional
├── asset_types_community.yaml
└── protocols_community.yaml

---

Implementation Status

Current State

The workflow is implemented as an Agent skill (for Agents like Claude Code / OpenCode) with:
✅ 10-step structured workflow
✅ Information staging format (.tm-raw/ directory)
✅ Validation scripts (validate_model.py)
✅ Generation scripts (generate_context.py, generate_bom.py)
✅ Comprehensive documentation (11 reference files)
✅ Example projects (DJI Power Inspection Drone System)

Skill Repository Structure

tm-en/
├── SKILL.md # Main skill instructions (316 lines)
├── references/
│ ├── workflow.md # Information collection checklist
│ ├── dsl-syntax.md # DSL syntax details
│ ├── staging-format.md # Information staging format
│ ├── naming-conventions.md # Naming conventions
│ ├── custom-asset-types.md # Custom types/protocols
│ ├── modeling-strategy.md # Single/multi-subsystem
│ ├── context-format.md # Context YAML format
│ ├── bom-format.md # BOM YAML format
│ └── ... (3 more files)
└── scripts/
├── generate_context.py # Context YAML generator
├── generate_bom.py # BOM YAML generator
├── validate_model.py # Model validator
└── requirements.txt

Attachment

I've prepared the full skill implementation as a reference attachment tm-skill.zip

Skill Repository: skill-tm/ directory (SKILL.md + reference/ + scripts/)
Agent output model files: dji-power-inspection/
Example Project report: DJI_Power_Inspection_Drone_System_20260517_203033/ (real-world example)

Please review when convenient. I'm happy to provide more details or discuss implementation specifics. Sharing this skill as a reference contribution — hoping to help make SecOpsTM even better. Feel free to adapt any parts that might be useful.

[ellipse2v]

hi

Thank you @zhangtianqi-james for this thorough contribution. this is exactly the kind of community work that moves the project forward.

Answers to your three questions

Does this align with SecOpsTM's direction?
Yes, strongly. SecOpsTM already uses AI to enrich existing threat models. This skill fills the gap upstream: guiding an AI agent through building a complete model from scratch for complex, unfamiliar systems. The structured workflow, staged information collection, and automated validation make the DSL accessible to users who don't already have a full architecture picture in their head.

What is most valuable for the community?
In priority order:

1. secopstm validate as a standalone CLI command — useful to every user regardless of Claude Code
2. The skill itself for Claude Code users tackling complex or specialized systems
3. The DJI example as a reference template for embedded/UAV systems

Should this stay as a separate project?
No — integrate into mainline. A separate fork would fragment the user base and go stale as the DSL evolves. The skill belongs in the repo so it ships with every clone, zero separate installation required.

---

Integration plan

1. Skill → .claude/skills/secopstm-threat-modeling/

Placing the skill (SKILL.md + references/ + scripts/) under .claude/skills/ means Claude Code discovers it automatically for anyone who clones the repo. No install step, no configuration.

This is a genuine innovation for the project. The 10-step workflow — information gathering, staging, complexity assessment, model generation, BOM/context scaffolding, validation
— covers a use case nothing else handles today: building a production-quality threat model for a system you're discovering as you go. The DJI example proves it works: 15 servers, full BOM, GDAF context, custom asset types, all generated in a structured, traceable way.

2. secopstm validate — new CLI subcommand

validate_model.py is the most valuable standalone piece and will be exposed as secopstm validate --model-dir ., usable from CI pipelines and pre-commit hooks without Claude Code.

One structural fix is required before merge: the DSL_ENUMS dict in the script duplicates the enum definitions in model_parser.py. If a new server type or boundary attribute is added to SecOpsTM, the validator silently goes out of sync.
The fix is to move the authoritative enum definitions into the SecOpsTM package and have validate_model.py import
from there — keeping a single source of truth.

3. DJI example → threatModel_Template/UAV_Drone_System/

The most complete and realistic template in the collection. Will be added as-is (the .tm-raw/ staging directory is workflow scaffolding and won't be committed — it's already well documented in the skill references).

4. dsl-syntax.md → official documentation

At 598 lines, this is the most comprehensive DSL reference that exists. It will feed directly into the official docs.

---

One prerequisite before merge

All code comments and docstrings in the scripts must be translated to English — this is a project-wide convention. The logic itself is solid, this is purely a translation pass.

Looking forward to getting this in. Thanks again.

[ellipse2v]

hi @zhangtianqi-james i'm working on it https://github.com/ellipse2v/SecOpsTM/tree/skills de66d9b

[zhangtianqi-james]

hi @ellipse2v Great to see the skills branch, thanks for picking this up so quickly. Also available to test the integration once it's ready.

[ellipse2v]

Hi @zhangtianqi-james, the feature is now deployed. Thanks a lot for your contribution! You can test it out now. :)

Would you be open to a private discussion? I'd love to tag you on LinkedIn to give you credit for this idea if that's okay with you! in order to try yo have more users

[zhangtianqi-james]

Hi @ellipse2v, I actually don't use LinkedIn, but feel free to reach me at [zhangtianqi_81@163.com]. Happy to chat! :)