iriusrisk-cli 0.6.2
AI-powered threat modeling integration for IriusRisk. Command line interface and MCP server for security analysis.
Requires Python: >=3.8
Keywords: security, threat-modeling, iriusrisk, cli, mcp, ai, threat-analysis, security-testing, compliance, cybersecurity

# IriusRisk CLI

An AI-powered threat modeling integration that brings IriusRisk security analysis directly into your development workflow. Designed primarily for use with AI-enabled IDEs through MCP (Model Context Protocol), this tool enables AI assistants to help you create threat models, analyze security risks, and implement countermeasures seamlessly within your coding environment.

> :warning: This software has been released IriusRisk Labs as public beta. It is provided as-is, without warranty or guarantee of any kind. Features may change, data structures may evolve, and occasional issues should be expected. Use at your own discretion.

> 🎉 **What's New in v0.6.0**: Agent Skills and MCP Tool Filtering! All workflow prompts converted to portable **Agent Skills** following the [Agent Skills open standard](https://agentskills.io) - now works across any agent (Cursor, Windsurf, Cline, etc.). Skills organized by LLM capability (reasoning, general, code-focused). Plus **MCP tool filtering** for fine-grained control over which tools are exposed to AI clients. See [CHANGELOG.md](CHANGELOG.md) for details.

## Primary Use Case: AI-Enabled IDE Integration

This tool is designed to work alongside AI assistants in your IDE, enabling:

- **AI-Guided Threat Modeling**: Let AI assistants analyze your code and automatically create comprehensive threat models
- **Intelligent Security Analysis**: Get AI-powered insights on threats and countermeasures specific to your codebase
- **Contextual Security Recommendations**: Receive security guidance based on your actual code changes and architecture
- **Automated Security Workflows**: Have AI assistants track threat status, implement countermeasures, and generate reports

## What You Can Do

- **Agent Skills**: Portable AI workflow skills that work across any compatible agent (Cursor, Windsurf, Cline, etc.), organized by LLM capability
- **MCP Tool Filtering**: Fine-grained control over which MCP tools are exposed to AI clients, with category-based and per-tool filtering
- **CI/CD Security Verification**: Automated security drift detection in CI/CD pipelines with three specialized tools:
  - Compare threat model versions to detect architectural and security changes
  - Verify security control implementations in code
  - Generate comprehensive security reports for PR reviews and deployments
- **Multi-Repository Threat Models**: Unite security across microservices, infrastructure, and frontend repos into one comprehensive view
- **AI-Guided Threat Modeling**: Let AI assistants analyze your code and automatically create threat models
- **Import/Export Threat Models**: Use OTM (Open Threat Model) format to create and update projects, with automatic schema validation
- **Intelligent Questionnaires**: AI analyzes your code to answer security questionnaires, refining threat models based on actual implementation
- **Analyze Threats**: View, filter, search, and update threat status with scope-based filtering for multi-repo projects
- **Track Countermeasures**: Monitor implementation, update status, and create tracking issues
- **Generate Reports**: Create compliance and security reports in multiple formats (PDF, HTML, XLSX, CSV)
- **Version Control**: Automatic snapshots of your threat models to track changes over time
- **Issue Tracker Integration**: Connect countermeasures to your issue tracking system
- **MCP Integration**: Enable AI assistants to perform all operations through Model Context Protocol

## Key Features

### 🆕 Agent Skills - Portable AI Workflows (v0.6.0)

All workflow prompts are now available as portable **Agent Skills** following the [Agent Skills open standard](https://agentskills.io). Skills work across any agent that supports the standard (Cursor, Windsurf, Cline, etc.) and are organized by LLM capability—reasoning, general, and code-focused. Version-controlled and shareable across projects and teams.

See the [Agent Skills](#agent-skills---portable-ai-workflows) section for the full skill catalog and usage instructions.

### 🆕 MCP Tool Filtering (v0.6.0)

Control which MCP tools are exposed to AI clients by filtering based on categories or specific tool names. Reduce scope for specific clients, use custom workflow instructions instead of built-in guidance, or create specialized MCP configurations for different roles and teams.

See the [Filtering MCP Tools](#filtering-mcp-tools) section for configuration details.

### CI/CD Security Verification (v0.5.0)

Automated security drift detection and control verification for CI/CD pipelines. Three specialized MCP tools enable AI-powered security reviews: version comparison for drift detection, countermeasure verification against code, and comprehensive orchestrated security gates for pre-deployment checks.

See the [CI/CD Security Verification](#cicd-security-verification-v050) section for detailed workflows and examples.

### Multi-Repository Threat Modeling (v0.4.0)

Multiple repositories can now contribute to a single unified threat model—perfect for microservices, infrastructure-as-code, and distributed architectures. Each repository defines its **scope** (what it represents), and the AI intelligently merges contributions into a comprehensive security view.

**Key benefits**:
- Unified security view across all repositories
- Each team maintains their own codebase while contributing to shared threat model
- AI-driven intelligent merging based on scope definitions
- Scope-based filtering shows only relevant threats per repository

See the [Multi-Repository Threat Modeling](#multi-repository-threat-modeling) section for detailed examples and workflows.

### Questionnaire-Driven Threat Model Refinement (v0.3.0)

IriusRisk questionnaires help refine your threat model based on your actual implementation details. The CLI downloads questionnaires during sync operations, and when using the MCP integration, AI assistants can analyze your source code to automatically answer these questions. Your answers trigger IriusRisk's rules engine to regenerate your threat model with more accurate, context-specific threats and countermeasures.

**How it works**:
1. Import or create your initial threat model
2. Run `iriusrisk sync` to download questionnaires
3. AI assistant analyzes your code and answers the questions
4. Sync automatically pushes answers back to IriusRisk
5. IriusRisk regenerates your threat model based on actual implementation

### AI-Powered Security Analysis

Through MCP integration, AI assistants can analyze your codebase, create threat models, answer questionnaires, implement countermeasures, and track progress—all within your IDE. The AI understands your code context and provides intelligent, specific security guidance.

### Automatic Threat Model Regeneration

The CLI automatically triggers IriusRisk's rules engine to regenerate your threat model when needed—after answering questionnaires, making manual edits, or updating your architecture. This happens seamlessly during sync operations without manual intervention.

### Enhanced Auto-Versioning

The CLI automatically creates backup snapshots **before** any update operation. Roll back changes anytime and track your threat model's evolution over time. Works consistently across all import scenarios (CLI commands, MCP tools, project updates).

# MCP Integration for AI-Enabled IDEs

## Setting Up MCP Integration

The IriusRisk CLI is designed to work with AI assistants through MCP (Model Context Protocol). This enables your AI assistant to:

- Analyze your codebase and create threat models automatically
- Provide security recommendations based on your specific code
- Track and update threat and countermeasure status
- Generate security reports and documentation

### Configuration for MCP

1. Install the IriusRisk CLI (see installation instructions below)
2. Configure your IriusRisk connection with environment variables
3. Your AI assistant will automatically detect and use the MCP integration

### AI Assistant Capabilities

When integrated through MCP, AI assistants can:

- **Analyze Source Code**: Examine your application code, infrastructure, and documentation to identify security-relevant components
- **Create Threat Models**: Generate comprehensive OTM (Open Threat Model) files from your codebase
- **Import to IriusRisk**: Automatically upload threat models to IriusRisk for professional analysis
- **Answer Questionnaires**: Analyze your code to answer project and component questionnaires, refining the threat model based on actual implementation details
- **Review Threats**: Help you understand and prioritize security threats identified by IriusRisk
- **Implement Countermeasures**: Guide you through implementing security controls and track their status
- **Sync Changes**: Automatically synchronize threat model updates between your local environment and IriusRisk
- **Generate Reports**: Create compliance reports and security documentation

## Agent Skills - Portable AI Workflows

**New in v0.6.0**: All workflow prompts have been converted to portable **Agent Skills** following the [Agent Skills open standard](https://agentskills.io).

Agent Skills are portable, version-controlled packages that teach AI agents how to perform domain-specific tasks. They work across any agent that supports the standard (Cursor, Windsurf, Cline, etc.) and can be shared, versioned, and reused.

### Skills by Category

Skills are organized by LLM capability to help you choose the right model for each task:

#### Reasoning Models (Complex Analysis)

Best for: Claude Sonnet, GPT-4, o1, other reasoning-capable models

- **ci-cd-verification** - Orchestrate comprehensive CI/CD security reviews
- **compare-versions** - Compare threat model versions, interpret structured diffs
- **countermeasure-verification** - Verify security controls are correctly implemented in code

#### General Models (Standard Workflows)

Best for: Most modern LLMs (Claude, GPT-4, Gemini, etc.)

- **architecture-design-review** - Architecture/design review trigger point
- **initialize-iriusrisk-workflow** - Complete workflow instructions for all IriusRisk operations
- **analyze-source-material** - Analyze repositories to extract components for threat modeling
- **create-threat-model** - Step-by-step OTM file creation with validation
- **threats-and-countermeasures** - Analyze threats/countermeasures, provide implementation guidance
- **security-development-advisor** - Help developers assess security impact

#### Code-Focused (Heavy Analysis)

Best for: Models with strong code analysis capabilities

- **questionnaire-guidance** - Analyze source code to answer IriusRisk questionnaires

#### Shared (Reference Material)

Best for: All models

- **otm-layout-guidance** - Detailed OTM component layout and positioning guidance
- **otm-validation-guidance** - Validation rules for trust zones and component types

### Using Agent Skills

In Cursor and other compatible agents, skills are automatically discovered from the `skills/` directory in your project or globally from `~/.cursor/skills/`.

**To use a skill:**
1. Type `/` in Agent chat
2. Search for the skill name
3. Or let the agent automatically apply it based on context

**Learn more:** See [skills/README.md](skills/README.md) for detailed documentation on each skill and model recommendations.

## Example AI Workflows

### Single Repository
1. **Code Analysis**: "Analyze my web application for security threats"
2. **Threat Model Creation**: AI examines your code and creates a comprehensive threat model
3. **IriusRisk Integration**: Threat model is uploaded to IriusRisk for professional analysis
4. **Questionnaire Completion**: AI analyzes your code to answer questionnaires, refining the threat model
5. **Threat Review**: AI helps you understand and prioritize identified threats
6. **Implementation Guidance**: AI guides you through implementing security countermeasures
7. **Status Tracking**: Progress is tracked and synchronized with IriusRisk

### Multi-Repository
1. **First Repo (Backend)**: "Threat model this API" → AI creates initial threat model with API components
2. **Second Repo (Infrastructure)**: "Update threat model with AWS infrastructure" → AI exports existing model, adds infrastructure, shows API running in ECS
3. **Third Repo (Frontend)**: "Add frontend to threat model" → AI merges frontend components, creates complete system view
4. **Result**: Single comprehensive threat model showing frontend → load balancer → API → database with all security threats across the stack

## Multi-Repository Threat Modeling

Modern applications are often distributed across multiple repositories (microservices, infrastructure-as-code, frontend/backend separation). The IriusRisk CLI supports **scope definitions** that enable multiple repositories to contribute different perspectives to a single comprehensive threat model.

### How It Works

Each repository defines its **scope**—a description of what part of the system it represents. The AI assistant then exports any existing threat model, analyzes the current repository based on its scope, intelligently merges contributions with existing components, and updates the unified threat model in IriusRisk.

### Example: Microservices Architecture

```bash
# Repository 1: Backend API
$ cd backend-api/
$ iriusrisk init -n "E-commerce Platform" --scope "Node.js REST API for order processing..."
# AI creates initial threat model with API components

# Repository 2: Infrastructure
$ cd ../terraform-aws/
$ iriusrisk init -r "ecommerce-platform" --scope "AWS infrastructure - ECS, RDS, VPC..."
# AI exports existing model, adds AWS infrastructure, merges intelligently

# Repository 3: Frontend
$ cd ../web-frontend/
$ iriusrisk init -r "ecommerce-platform" --scope "React SPA for customer interface..."
# AI exports existing model, adds frontend components, creates complete view
```

**Result**: A single, comprehensive threat model showing frontend → infrastructure → backend services and how they all connect and interact, with complete security coverage across the entire stack.

### Defining Scope

A good scope description includes what this repository contains, how it relates to other repositories, where components are deployed, external integrations, and trust boundaries.

**Example scope definitions:**

```json
{
  "scope": "Node.js REST API implementing core business logic for order processing, 
            inventory management, and user accounts. Exposes REST endpoints consumed 
            by web frontend (separate repo) and mobile apps. Connects to PostgreSQL 
            database and Redis cache. Deployed as containerized service (infrastructure 
            in terraform repo). Integrates with external payment gateway (Stripe) and 
            shipping APIs."
}
```

```json
{
  "scope": "AWS cloud infrastructure via Terraform. Provisions ECS Fargate containers 
            for the API backend (api-backend repo), RDS PostgreSQL database, ElastiCache 
            Redis, Application Load Balancer, CloudFront CDN for frontend static assets 
            (web-frontend repo), S3 buckets, and VPC with public/private subnet isolation. 
            All application components from other repos run within these AWS services."
}
```

### Setting Up Multi-Repository Projects

**First repository (creates project):**
```bash
$ cd backend-api/
$ iriusrisk init -n "E-commerce Platform"
# Optional: Add scope when prompted, or skip for complete system view
```

**Additional repositories (connect to existing project):**
```bash
$ cd ../terraform-aws/
$ iriusrisk init -r "ecommerce-platform"
# Prompted for scope to define this repository's contribution
```

Or use the `--scope` flag to skip prompts:
```bash
$ iriusrisk init -r "ecommerce-platform" --scope "AWS infrastructure via Terraform..."
```

### Working with Multi-Repository Projects

When you ask the AI to create or update a threat model, it automatically runs `sync()` to download the latest threat model, analyzes your code based on the repository's scope, merges your contribution with existing components, and updates the unified threat model in IriusRisk. The `sync()` command saves the current model to `.iriusrisk/current-threat-model.otm`, making it immediately available for intelligent merging.

**Important:** The AI creates ALL OTM files in the `.iriusrisk/` directory with clear temporary naming (e.g., `.iriusrisk/temp-update-20260206-143022.otm`). It ALWAYS runs `sync()` first to download the current state, then uses IDENTICAL merge logic whether updating a single repository or merging multi-repository contributions. This ensures:
- Changes made in IriusRisk (questionnaires, threat status, countermeasures) are never overwritten
- Existing component layout positions are preserved
- All updates follow the same reliable merge algorithm

### Scope-Based Filtering

AI assistants automatically filter threats, countermeasures, and questionnaires to show only items relevant to your repository's scope. Infrastructure repos see infrastructure threats, application repos see application-level threats, and frontend repos see client-side threats. Each repository stays focused on its own security concerns while contributing to the unified threat model.

## CI/CD Security Verification (v0.5.0)

Automated security drift detection and control verification for CI/CD pipelines. Three specialized MCP tools enable AI-powered security reviews at different stages of your development workflow.

### The Three Tools

**1. `compare_versions` - Version Comparison**

Compare any two threat model versions to detect architectural and security changes. Returns structured JSON diff showing what changed.

```
# Simple drift detection
"Compare baseline version to current"

# Historical audit
"Compare v1.0-approved to v2.0-approved"
```

**Use when:** Checking for security drift, auditing changes, understanding threat model evolution.

**2. `countermeasure_verification` - Control Implementation Verification**

Verify that security controls linked to issue tracker tasks (Jira, GitHub Issues, etc.) are correctly implemented in code.

```
# Verify specific issue
"Verify that PROJ-1234 is correctly implemented"

# Verify all linked controls in PR
"Check if security controls are properly implemented"
```

**Use when:** Reviewing PRs that claim to fix security issues, validating control implementations, ensuring countermeasures match code.

**3. `ci_cd_verification` - Comprehensive Security Review**

Orchestrator that coordinates complete security reviews by combining version comparison, control verification, risk analysis, and reporting.

```
# Full CI/CD security gate
"Run comprehensive security verification against baseline"
```

**Use when:** CI/CD pipelines, pre-deployment security gates, comprehensive PR reviews requiring multiple analyses.

### Headless Automation Script

For CI/CD pipelines, use the included `iriusrisk-verification.sh` script:

```bash
# Run from your project directory
./iriusrisk-verification.sh --type <verification-type>

# Types:
# drift          - Detect drift from baseline
# pr             - Full PR security review  
# control        - Verify control implementation
# comprehensive  - Complete security gate
# audit          - Historical version comparison
```

**Example CI/CD Integration:**

```yaml
# .github/workflows/security-check.yml
name: Security Verification
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Security Verification
        run: |
          ./iriusrisk-verification.sh --type pr
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          IRIUSRISK_API_TOKEN: ${{ secrets.IRIUSRISK_API_TOKEN }}
          IRIUSRISK_DOMAIN: release.iriusrisk.com
```

### What Gets Detected

**Architectural Changes:**
- Components added, removed, or modified
- Dataflows added, removed, or modified (including trust boundary crossings)
- Trust zone changes (components moved between security zones)

**Security Changes:**
- New threats introduced (with severity levels)
- Threat severity increases
- Countermeasures added or removed
- Critical security control removals

**Control Implementation:**
- Whether security controls are correctly implemented in code
- Evidence-based verification with specific file/line references
- Pass/fail status with detailed reasoning

### Workflow Examples

**Drift Detection:**
```
> Compare baseline version to current state

AI will:
1. Compare versions using compare_versions tool
2. Identify architectural and security changes
3. Generate DRIFT_REPORT.md with findings
```

**PR Security Review:**
```
> Run security review of this pull request

AI will:
1. Analyze current code and create updated OTM
2. Import OTM to IriusRisk
3. Compare against baseline version
4. Generate PR_REPORT.md with security assessment
```

**Control Verification:**
```
> Verify that PROJ-1234 is correctly implemented

AI will:
1. Find countermeasure linked to PROJ-1234
2. Analyze code changes
3. Verify implementation matches requirement
4. Generate CONTROL_VERIFICATION_REPORT.md with pass/fail status
```

# Using the CLI

## Installation

### From PyPI

Eventually users will be able to install the CLI using:

```bash
$ pip install iriusrisk-cli
```

For Mac users using Homebrew, we suggest installing it with:

```bash
$ pipx install iriusrisk-cli
```

### For Development

Clone this repository and install in development mode:

```bash
$ git clone <repository-url>

$ cd iriusrisk_cli
$ pip install -e .
```


## Configuration

Before using the CLI, you need to configure your IriusRisk connection. The CLI supports multiple configuration methods with a clear priority order.

### Recommended: User-Level Configuration

Set up your credentials once for use across all projects:

```bash
# Set your default IriusRisk hostname
iriusrisk config set-hostname https://your-instance.iriusrisk.com

# Set your API key (prompts securely, not stored in shell history)
iriusrisk config set-api-key

# View your current configuration
iriusrisk config show
```

This approach:
- Keeps your API key secure (not in project files)
- Works across all projects automatically
- Can be overridden per-project or per-session

### Configuration Priority

The CLI checks configuration sources in this order (highest to lowest):

1. **Environment variables** - `IRIUS_HOSTNAME` and `IRIUS_API_KEY` (or `IRIUS_API_TOKEN`)
2. **Project .env file** - `.env` in your project directory
3. **Project config** - `.iriusrisk/project.json` (hostname only, never API credentials)
4. **User config** - `~/.iriusrisk/config.json` (set via `iriusrisk config` commands)

Each setting is resolved independently, so you can mix sources (e.g., API key from user config, hostname from environment variable).

### Alternative Configuration Methods

#### Option 2: Project .env file

Create a `.env` file in your project directory:

```bash
cat > .env << EOF
IRIUS_HOSTNAME=https://your-instance.iriusrisk.com
IRIUS_API_KEY=your-api-token-here
EOF
```

**Warning**: If using `.env` files, add them to `.gitignore` to avoid committing credentials.

#### Option 3: Environment variables

```bash
export IRIUS_HOSTNAME=https://your-instance.iriusrisk.com
export IRIUS_API_KEY=your-api-token-here
```

#### Option 4: Project-specific hostname

For teams working with different IriusRisk instances, you can set a hostname in the project config:

```bash
# Manually edit .iriusrisk/project.json and add:
{
  "hostname": "https://dev-instance.iriusrisk.com",
  "project_id": "...",
  ...
}
```

**Note**: API credentials should never be stored in project config files.

## Logging and Output Control

The IriusRisk CLI provides flexible logging options to control output verbosity:

### Default Behavior
By default, the CLI operates quietly with minimal output - only showing command results and critical errors.

### Logging Options

```bash
# Enable verbose output (shows progress and status messages)
iriusrisk --verbose project list

# Enable debug output (shows detailed API calls and timing)
iriusrisk --debug project list

# Suppress all non-essential output (quiet mode)
iriusrisk --quiet project list

# Write logs to a specific file
iriusrisk --log-file debug.log --debug project list

# Set specific log level
iriusrisk --log-level INFO project list
```

### Environment Variables
You can also control logging through environment variables:

```bash
# Enable debug mode
export IRIUSRISK_DEBUG=1

# Set log file path
export IRIUSRISK_LOG_FILE=debug.log
```

### Output Destinations
- **stdout**: Command results and data (for piping/redirection)
- **stderr**: Status messages, progress, warnings, errors, debug info
- **Log files**: Only when explicitly requested via `--log-file`

## Testing API Connection

After configuration, test your connection to ensure everything is working correctly:

```bash
# Test your IriusRisk connection
iriusrisk test
```

This command will:
- Test connectivity to your IriusRisk instance
- Verify your authentication credentials
- Display your IriusRisk version information

Example output:
```
Testing connection to IriusRisk...
✓ Connection successful!
✓ IriusRisk version: 4.47.19-0-g41bcb27de1f-30/09/2025 17:48
```

If the test fails, it will provide specific error information to help you troubleshoot configuration issues.

## Getting help

Users can get help using the following commands:

```bash
$ iriusrisk help    # Detailed help with examples and configuration
$ iriusrisk --help  # Basic command help
$ iriusrisk --version  # Show version information
```

## Quick Start

After installation and configuration:

```bash
# Test the installation
$ iriusrisk --version

# Test your API connection
$ iriusrisk test

# Get detailed help
$ iriusrisk help

# Basic help
$ iriusrisk --help

# List projects
$ iriusrisk project list

# List projects with filtering
$ iriusrisk project list --name "web" --format json
```

## Available Commands

### Project Initialization

Initialize a new project or connect to an existing one:

```bash
# Initialize new project interactively
$ iriusrisk init

# Initialize with specific name
$ iriusrisk init -n "My Web Application"

# Initialize with name and project ID
$ iriusrisk init -n "My App" -p abc123

# Connect to existing project by reference ID
$ iriusrisk init -r "my-project-ref"

# Connect to existing project with scope definition (multi-repository)
$ iriusrisk init -r "my-project-ref" --scope "AWS infrastructure via Terraform"

# Initialize with scope for multi-repository project
$ iriusrisk init -n "My App" --scope "Backend API services and business logic"

# Overwrite existing configuration
$ iriusrisk init --force
```

**Multi-Repository Projects**: Use the `--scope` parameter to define how this repository contributes to a unified threat model. The scope helps AI assistants merge contributions from multiple repositories. See the Multi-Repository Threat Modeling section above for details.

### Projects

```bash
# List all projects
$ iriusrisk project list

# List projects with pagination
$ iriusrisk project list --page 1 --size 10

# Filter by name (partial match)
$ iriusrisk project list --name "web application"

# Filter by tags
$ iriusrisk project list --tags "production critical"

# Filter by workflow state
$ iriusrisk project list --workflow-state "in-progress"

# Show only non-archived projects
$ iriusrisk project list --not-archived

# Include version information
$ iriusrisk project list --include-versions

# Output as JSON
$ iriusrisk project list --format json

# Output as CSV
$ iriusrisk project list --format csv

# Advanced filtering with custom expressions
$ iriusrisk project list --filter "'name'~'web':AND:'tags'~'prod'"

# Show detailed project information
$ iriusrisk project show <project_id>

# Show project info as JSON
$ iriusrisk project show <project_id> --format json
```

### OTM (Open Threat Model) Import/Export

Work with threat models using the standard OTM format:

```bash
# Generate example OTM file for reference
$ iriusrisk otm example

# Import OTM file (automatically creates new or updates existing project)
$ iriusrisk otm import example.otm

# Import with JSON output
$ iriusrisk otm import example.otm --format json

# Import and reset diagram layout (forces IriusRisk auto-layout)
$ iriusrisk otm import example.otm --reset-layout

# Export project as OTM format
$ iriusrisk otm export PROJECT_ID

# Export to specific file
$ iriusrisk otm export PROJECT_ID -o threat-model.otm

# Export as JSON
$ iriusrisk otm export PROJECT_ID --format json

# Export existing threat model for multi-repository merging
$ iriusrisk otm export -o existing-model.otm
```

**Note**: The CLI automatically detects whether you're creating a new project or updating an existing one during import. If auto-versioning is enabled in your project configuration, a backup snapshot is automatically created before updates.

#### OTM Schema Validation

All OTM files are automatically validated against the official [Open Threat Model JSON schema](https://github.com/iriusrisk/OpenThreatModel) before import. This catches structural issues early and prevents data loss:

```bash
$ iriusrisk otm import threat-model.otm
🔍 Validating OTM file against schema...
✓ OTM validation passed
Importing OTM file: threat-model.otm
...
```

If validation fails, you'll see clear error messages:

```
❌ OTM validation failed!

Validation errors:
  • At 'project': 'id' is a required property
  • At 'components -> 0': 'parent' is a required property
  • At 'dataflows -> 0 -> source': 'component-xyz' does not exist

OTM file summary:
  Project: My App (ID: None)
  Trust Zones: 2
  Components: 5
  Dataflows: 3
  Threats: 0
  Mitigations: 0

⚠️  Please fix the validation errors before importing.
See OTM specification: https://github.com/iriusrisk/OpenThreatModel
```

**What validation catches:**
- Missing required fields:
  - `otmVersion` (required at root)
  - `project.name` and `project.id` (required)
  - `component.parent` (trustZone or component - required)
  - `trustZone.risk.trustRating` (required)
  - `dataflow.source` and `dataflow.destination` (required)
- Invalid data types (strings vs numbers, etc.)
- Malformed structure
- Schema violations

**Benefits:**
- **Prevents data loss** - Catches issues before they reach IriusRisk
- **Clear errors** - Shows exactly what's wrong and where
- **Early detection** - Fails fast before API calls
- **Spec compliance** - Ensures OTM files follow official specification
- **Better AI output** - AI can see validation errors and fix them

**Dependencies:**
- Requires `jsonschema>=4.0.0` (automatically installed)
- Requires `pyyaml>=6.0.0` (automatically installed)

#### Layout Reset Feature

Use `--reset-layout` to strip all component positions and sizes, forcing IriusRisk to auto-layout the diagram from scratch:

```bash
# One-time layout reset
$ iriusrisk otm import threat-model.otm --reset-layout
```

Or enable automatic layout reset for all imports in `.iriusrisk/project.json`:

```json
{
  "name": "My Project",
  "reference_id": "my-project-abc",
  "auto_versioning": true,
  "auto_reset_layout": false
}
```

**When to use layout reset:**
- Diagram has become messy after multiple updates
- Major architectural refactoring makes old positions irrelevant
- Want IriusRisk's auto-layout to reorganize everything
- Testing/debugging with fresh layout

**AI usage:** When calling `import_otm()` via MCP, use `reset_layout=True` parameter to reset layout.

**Multi-Repository Use**: When contributing to an existing threat model from a new repository, export the current threat model first. This allows AI assistants to merge your contribution with existing components intelligently based on your repository's scope definition.

#### OTM File Management Best Practices

**All OTM files go in `.iriusrisk/` directory:**
- AI creates temporary OTM files with clear naming: `.iriusrisk/temp-update-YYYYMMDD-HHMMSS.otm`
- Never creates OTM files in repository root
- Temporary files can be deleted after successful import

**Always sync first:**
- AI ALWAYS runs `iriusrisk sync` before any threat modeling operation
- Downloads `.iriusrisk/current-threat-model.otm` with current state from IriusRisk
- This is the ONLY authoritative local copy

**Identical merge logic for all updates:**
- Whether updating a single repository or merging multi-repo contributions
- AI uses the SAME merge algorithm:
  1. Read `current-threat-model.otm`
  2. Preserve ALL existing components, IDs, and layout positions
  3. Add NEW components with calculated positions
  4. Save to `.iriusrisk/temp-update-YYYYMMDD-HHMMSS.otm`
  5. Import the temporary file

**Correct workflow:**
```bash
# AI workflow (automatic)
$ iriusrisk sync                                    # ALWAYS first - downloads current state
# AI reads .iriusrisk/current-threat-model.otm
# AI merges changes preserving existing components and layout
# AI creates .iriusrisk/temp-update-20260206-143022.otm
$ iriusrisk otm import .iriusrisk/temp-update-20260206-143022.otm

# Manual workflow (if needed)
$ iriusrisk sync                                    # Get current state
# Manually edit .iriusrisk/current-threat-model.otm
# Save as .iriusrisk/temp-update-20260206-143022.otm
$ iriusrisk otm import .iriusrisk/temp-update-20260206-143022.otm
```

**What NOT to do:**
```bash
# ❌ WRONG - Skip sync
# ❌ WRONG - Create OTM files in repo root
# ❌ WRONG - Use different logic for single-repo vs multi-repo
# ❌ WRONG - Ignore existing layout positions
```

### Data Synchronization

Sync threat model data between IriusRisk and your local environment:

```bash
# Sync all data from default project
$ iriusrisk sync

# Sync specific project
$ iriusrisk sync <project_id>

# Sync only threats
$ iriusrisk sync --threats-only

# Sync only countermeasures
$ iriusrisk sync --countermeasures-only

# Sync only questionnaires
$ iriusrisk sync --questionnaires-only

# Sync only components
$ iriusrisk sync --components-only

# Sync to custom output directory
$ iriusrisk sync -o /path/to/output
```

The sync command downloads:
- **Threats**: All identified security threats for your project
- **Countermeasures**: Security controls and their implementation status
- **Questionnaires**: Questions to refine your threat model based on implementation details
- **Components**: System components from the IriusRisk library and your architecture
- **Current Threat Model (OTM)**: The complete threat model exported from IriusRisk for multi-repository merging

Data is saved to `.iriusrisk/` directory by default and can be used for offline analysis or AI-assisted review.

**Multi-Repository Support**: The `current-threat-model.otm` file enables multiple repositories to merge their contributions intelligently. AI assistants automatically detect and use this file as the basis for updates when contributing from additional repositories.

### Questionnaires

**New in 0.3.0**: Questionnaires help refine your threat model based on actual implementation details.

```bash
# Download questionnaires during sync
$ iriusrisk sync

# View questionnaires in .iriusrisk/questionnaires.json
```

Questionnaires are automatically downloaded during sync operations. When using the MCP integration, AI assistants can analyze your source code and automatically answer these questions, triggering IriusRisk's rules engine to regenerate your threat model with more accurate threats and countermeasures.

**How it works**:
1. Import or create a threat model
2. Run `iriusrisk sync` to download questionnaires
3. AI assistant analyzes your code to answer questions
4. Sync pushes answers back to IriusRisk
5. IriusRisk automatically regenerates threat model based on answers

### Threats

```bash
# List all threats from default project
$ iriusrisk threat list

# List threats from specific project
$ iriusrisk threat list <project_id>

# Show detailed threat information
$ iriusrisk threat show <threat_id>

# Search threats by keyword
$ iriusrisk threat search "SQL injection"

# Search with project specification
$ iriusrisk threat search "XSS" --project-id <project_id>

# Update threat status
$ iriusrisk threat update <threat_id> --status accept --reason "Mitigated by WAF"

# List threats with specific status
$ iriusrisk threat list --status required

# Output as JSON or CSV
$ iriusrisk threat list --format json
```

**Available threat statuses**: `required`, `recommended`, `accept`, `expose`, `not-applicable`

### Countermeasures

```bash
# List all countermeasures from default project
$ iriusrisk countermeasure list

# List countermeasures from specific project
$ iriusrisk countermeasure list <project_id>

# Show detailed countermeasure information
$ iriusrisk countermeasure show <countermeasure_id>

# Search countermeasures by keyword
$ iriusrisk countermeasure search "authentication"

# Update countermeasure status
$ iriusrisk countermeasure update <cm_id> --status implemented

# Create issue tracker ticket for countermeasure
$ iriusrisk countermeasure create-issue <cm_id>

# Create issue with specific tracker
$ iriusrisk countermeasure create-issue <cm_id> --tracker "Jira"

# List countermeasures by status
$ iriusrisk countermeasure list --status required

# Output as JSON or CSV
$ iriusrisk countermeasure list --format json
```

**Available countermeasure statuses**: `required`, `recommended`, `implemented`, `rejected`, `not-applicable`

### Components

View and search system components in your architecture:

```bash
# List all components
$ iriusrisk component list

# List components from specific project
$ iriusrisk component list <project_id>

# Show detailed component information
$ iriusrisk component show <component_id>

# Search components by keyword
$ iriusrisk component search "database"

# Filter by category
$ iriusrisk component list --category "Database"

# Filter by type
$ iriusrisk component list --type "project-component"

# Output as JSON
$ iriusrisk component list --format json
```

### Reports

Generate security and compliance reports:

```bash
# Generate default countermeasure report (PDF)
$ iriusrisk reports generate

# Generate threat report
$ iriusrisk reports generate --type threat

# Generate compliance report
$ iriusrisk reports generate --type compliance --standard owasp-top-10-2021

# Generate report in different format
$ iriusrisk reports generate --format html

# Save to specific location
$ iriusrisk reports generate -o /path/to/report.pdf

# List available report types
$ iriusrisk reports types

# List available compliance standards
$ iriusrisk reports standards

# List generated reports
$ iriusrisk reports list
```

**Available report types**: `countermeasure`, `threat`, `compliance`, `risk-summary`

**Available formats**: `pdf`, `html`, `xlsx`, `csv`, `xls`

### Project Versions

**New in 0.3.0**: Enhanced auto-versioning creates backup snapshots before updates.

```bash
# Create a version snapshot
$ iriusrisk project versions create "v1.0" --description "Initial release"

# List all versions for a project
$ iriusrisk project versions list

# List versions for specific project
$ iriusrisk project versions list <project_id>

# Show version details
$ iriusrisk project versions show <version_id>

# Compare two versions
$ iriusrisk project versions compare <version_id_1> <version_id_2>
```

**Auto-versioning**: Enable in `.iriusrisk/project.json`:

```json
{
  "auto_version": true,
  "auto_version_prefix": "auto-backup-"
}
```

When enabled, the CLI automatically creates version snapshots before OTM imports and updates, protecting your work.

### Updates Tracking

Track threat and countermeasure status changes before syncing to IriusRisk:

```bash
# View pending updates
$ iriusrisk updates show

# View updates for specific project
$ iriusrisk updates show <