thothctl

DevSecOps SDLC for IaC with ThothCTL

Overview

This guide demonstrates how ThothCTL enables a complete DevSecOps Software Development Lifecycle (SDLC) for Infrastructure as Code, from planning to production deployment.

Quick Start with Workflow Command

The thothctl workflow devsecops command abstracts the entire SDLC into a single composable command:

# Run the full pipeline
thothctl workflow devsecops --phase all

# Run a specific phase
thothctl workflow devsecops --phase secure

# Pre-deployment gate (blocks on failures)
thothctl workflow devsecops --phase pre-deploy --enforcement hard

# With organization policies
thothctl workflow devsecops --phase secure \
  --policy-dir https://github.com/myorg/iac-policies.git@main

Phase	Workflow Command	What It Runs
📋 Plan	`--phase plan`	cost-analysis + blast-radius
💻 Develop	`--phase develop`	check environment + check project + document
🔨 Build	`--phase build`	inventory with version checks
✅ Test	`--phase test`	tfplan validation
🔒 Secure	`--phase secure`	checkov + trivy + opa
🚀 Deploy	`--phase deploy`	security gate (hard enforcement)
📊 Monitor	`--phase monitor`	drift detection

For detailed command reference, see: Workflow Command Documentation

The sections below explain each phase in detail, including the individual commands that the workflow orchestrates.

The DevSecOps SDLC Phases

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#3f51b5','primaryTextColor':'#ffffff','primaryBorderColor':'#303f9f','lineColor':'#536dfe','secondaryColor':'#536dfe','tertiaryColor':'#fff','background':'transparent','mainBkg':'#3f51b5','secondBkg':'#536dfe','tertiaryBkg':'#90caf9','textColor':'#ffffff','nodeTextColor':'#ffffff','fontSize':'14px'}}}%%
graph TB
    A["Plan<br/>📋 Cost Estimation<br/>Risk Assessment<br/>Template Selection"] --> B["Develop<br/>💻 Environment Check<br/>Structure Validation<br/>Best Practices"]
    B --> C["Build<br/>🔨 Inventory Creation<br/>Dependency Tracking<br/>Version Management"]
    C --> D["Test<br/>✅ Plan Validation<br/>Blast Radius<br/>Change Impact"]
    D --> E["Secure<br/>🔒 Security Scanning<br/>Compliance Check<br/>Vulnerability Detection"]
    E --> F["Deploy<br/>🚀 Pre-Deploy Checks<br/>Risk Mitigation<br/>Approval Gates"]
    F --> G["Operate<br/>🔧 Config Management<br/>Project Updates<br/>Documentation"]
    G --> H["Monitor<br/>📊 Dashboard<br/>Continuous Scan<br/>Drift Detection"]
    H --> A
    
    classDef planStyle fill:#01579b,stroke:#0288d1,stroke-width:2px,color:#ffffff
    classDef devStyle fill:#1b5e20,stroke:#2e7d32,stroke-width:2px,color:#ffffff
    classDef buildStyle fill:#e65100,stroke:#ef6c00,stroke-width:2px,color:#ffffff
    classDef testStyle fill:#4a148c,stroke:#6a1b9a,stroke-width:2px,color:#ffffff
    classDef secureStyle fill:#b71c1c,stroke:#c62828,stroke-width:2px,color:#ffffff
    classDef deployStyle fill:#004d40,stroke:#00695c,stroke-width:2px,color:#ffffff
    classDef operateStyle fill:#880e4f,stroke:#ad1457,stroke-width:2px,color:#ffffff
    classDef monitorStyle fill:#33691e,stroke:#558b2f,stroke-width:2px,color:#ffffff
    
    class A planStyle
    class B devStyle
    class C buildStyle
    class D testStyle
    class E secureStyle
    class F deployStyle
    class G operateStyle
    class H monitorStyle

ThothCTL Coverage by Phase

Phase	DevSecOps Practices	ThothCTL Commands
Plan	Cost estimation, Risk assessment, Template selection	`init project`, `check iac -type cost-analysis`
Develop	Environment validation, Structure enforcement, Standards	`check environment`, `check project iac`
Build	Dependency management, Version tracking, SBOM	`inventory iac --check-versions --check-provider-versions`
Test	Plan validation, Impact analysis, Change assessment	`check iac -type tfplan`, `-type blast-radius`
Secure	Security scanning, Compliance validation, CVE detection	`scan iac -t checkov -t trivy -t opa`
Deploy	Pre-deployment validation, Risk gates, Approval workflow	`check iac -type blast-radius`, `scan iac --enforcement hard`
Operate	Configuration management, Updates, Documentation	`project upgrade`, `document iac`
Monitor	Continuous monitoring, Drift detection, Dashboards	`dashboard launch`, `check iac -type drift`

Phase 1: Plan 📋

Objective

Define infrastructure requirements, estimate costs, and assess risks before writing code.

ThothCTL Commands

1.1 Initialize Project Space

# Create a new space for your organization/team
thothctl init space --name production \
  --vcs github \
  --ci-system github-actions

What it does:

Sets up organizational structure
Configures VCS integration
Establishes CI/CD pipelines

1.2 Initialize Project

# Create new IaC project from template
thothctl init project -p my-infrastructure \
  --project-type terraform \
  --space production

What it does:

Scaffolds project structure
Applies best practices
Sets up configuration files

1.3 Cost Estimation (Before Writing Code)

=== “Terragrunt”

```bash
# Generate plans for all stacks with JSON output
terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false

# Run cost analysis on all generated plans
thothctl check iac -type cost-analysis --plan-file tfplan/ --recursive
```

=== “Terraform”

```bash
# Generate plan
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json

# Run cost analysis
thothctl check iac -type cost-analysis --plan-file tfplan.json
```

=== “CloudFormation”

```bash
# Cost estimation from template
thothctl check iac -type cost-analysis --template template.yaml
```

=== “CDK”

```bash
# Synthesize and estimate costs
cdk synth --output cdk.out
thothctl check iac -type cost-analysis --template cdk.out/MyStack.template.json
```

Output:

Monthly/annual cost projections
Service-by-service breakdown
Optimization recommendations
Budget alerts

Phase 2: Develop 💻

Objective

Write IaC code following best practices and organizational standards.

ThothCTL Commands

2.1 Check Environment Setup

# Verify all required tools are installed
thothctl check environment

Validates:

Terraform/OpenTofu/Terragrunt
Security scanners (Checkov, Trivy, KICS)
Documentation tools
Version control

2.2 Validate Project Structure

# Ensure project follows standards
thothctl check project iac

Checks:

Directory structure
File naming conventions
Required files (README, .gitignore)
Configuration standards

2.3 Generate Documentation

# Auto-generate documentation
thothctl document iac --recursive

Creates:

README.md with module descriptions
Input/output documentation
Dependency graphs
Architecture diagrams

Phase 3: Build 🔨

Objective

Create infrastructure inventory, validate dependencies, and generate Software Bill of Materials (SBOM).

ThothCTL Commands

3.1 Create Infrastructure Inventory

# Scan and catalog all IaC components (modules + providers)
thothctl inventory iac --check-versions --check-provider-versions

# Specify framework type explicitly
thothctl inventory iac --check-versions --framework-type terragrunt

# Generate CycloneDX SBOM (OWASP standard)
thothctl inventory iac --check-versions --report-type cyclonedx

Generates:

Component catalog (modules, providers, resources)
Module dependencies with source URLs
Provider versions and registries
CycloneDX 1.6 SBOM with formulation, evidence, and attestations
Technical debt scoring with risk levels

3.2 Check for Updates

# Full version analysis: modules + providers + schema compatibility
thothctl inventory iac \
  --check-versions \
  --check-provider-versions \
  --check-schema-compatibility \
  --report-type html

# Check only provider versions (faster, no module analysis)
thothctl inventory iac --check-provider-versions --report-type json

# Use OpenTofu registry instead of Terraform
thothctl inventory iac --check-versions --provider-tool tofu

# Include hidden folders (.terraform, .terragrunt-cache) for full analysis
thothctl inventory iac --check-versions --complete

# Custom project name for reports
thothctl inventory iac --check-versions --project-name "my-platform" --report-type blast-radius

Available flags:

Flag	Short	Description
`--check-versions`	`-cv`	Check latest versions for modules against Terraform Registry
`--check-provider-versions`	`-cpv`	Check latest versions for providers (Terraform/OpenTofu registry)
`--check-schema-compatibility`		Analyze breaking changes between current and latest provider versions
`--report-type`	`-r`	Output format: `html`, `json`, `cyclonedx`, or `all`
`--framework-type`	`-ft`	Framework: `auto`, `terraform`, `terragrunt`, `terraform-terragrunt`, `module`, `cdkv2`
`--provider-tool`		Registry to query: `tofu` (default) or `terraform`
`--complete`		Include .terraform/.terragrunt-cache in analysis
`--check-providers`		Report provider information for each stack
`--project-name`	`-pj`	Custom project name for report headers
`--inventory-path`	`-iph`	Custom path for saving reports (default: `./Reports`)
`--post-to-pr`		Post inventory summary as PR comment (GitHub/Azure DevOps)
`--vcs-provider`		VCS for PR comments: `auto`, `azure_repos`, `github`
`--space`		Space name for credential resolution
`--terragrunt-args`	`-tg-args`	Additional terragrunt arguments (e.g., `--feature=ci=false`)

Provides:

Latest available versions (modules and providers)
Staleness classification (current, outdated, unknown)
Breaking changes warnings (via schema compatibility analysis)
Update recommendations with risk levels
Technical debt score (0–100) with remediation guidance
Module compatibility analysis for safe upgrades
Professional HTML reports with collapsible stack groups

3.3 Update Dependencies

# Update dependencies based on inventory analysis (interactive)
thothctl inventory iac --inventory-action update --inventory-path ./Reports/inventory.json

# Auto-approve updates (for CI/CD)
thothctl inventory iac --inventory-action update --auto-approve

Phase 4: Test ✅

Objective

Validate infrastructure changes before deployment.

ThothCTL Commands

4.1 Plan Generation by Framework

Plan validation requires generating a plan file first. Each IaC framework has different commands and considerations.

=== “Terragrunt”

**Single Stack Plan**
```bash
# Plan a single stack
cd stacks/foundation/network/vpc
terragrunt plan -out=tfplan.binary -lock=false
terragrunt show -json tfplan.binary > tfplan.json
```

**All Stacks Plan (Recommended for CI/CD)**
```bash
# Plan all stacks with JSON output for ThothCTL analysis
# --working-dir: root of your infrastructure stacks
# --out-dir: directory to store binary plan files
# --json-out-dir: directory to store JSON plan files for ThothCTL
terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false
```

**Layer-Specific Plan**
```bash
# Plan only the foundation layer
terragrunt run \
  --working-dir stacks/foundation \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false

# Plan only the platform layer
terragrunt run \
  --working-dir stacks/platform \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false
```

**Environment-Specific Plan**
```bash
# Plan for production environment
TF_VAR_ENVIRONMENT=prd terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false

# Plan for QA environment
TF_VAR_ENVIRONMENT=qa terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false
```

**Stack Generation (Terragrunt 1.1)**
```bash
# Generate stack units from terragrunt.stack.hcl before planning
terragrunt stack generate

# Then plan the generated stacks
terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false
```

**Change-Based Plan (CI/CD Optimization)**
```bash
# Only plan stacks affected by changes (Terragrunt 1.1)
# Uses CAS + file tracking to detect which units are impacted
terragrunt run \
  --working-dir stacks/ \
  --all \
  --filter 'reading=stacks/foundation/network/vpc/terragrunt.hcl' \
  --out-dir tfplan \
  --json-out-dir tfplan \
  -- plan -lock=false
```

**Plan Output Structure**
```
tfplan/
├── foundation/
│   ├── network/vpc/tfplan.binary
│   ├── network/vpc/tfplan.json
│   ├── network/security-groups/tfplan.binary
│   └── iam/roles/tfplan.json
├── platform/
│   ├── containers/eks/tfplan.json
│   └── data/rds/tfplan.json
└── application/
    ├── compute/alb/tfplan.json
    └── storage/s3/tfplan.json
```

!!! tip "Terragrunt Plan Best Practices"
    - Use `-lock=false` in CI/CD to avoid state lock conflicts during plan
    - Always use `--out-dir` and `--json-out-dir` to capture plans for ThothCTL analysis
    - Use `--working-dir` instead of `cd` for reproducible commands
    - Leverage `TF_VAR_ENVIRONMENT` to plan specific environments
    - Use change-based filtering in CI to reduce plan time on large estates

=== “Terraform”

**Standard Plan**
```bash
# Generate plan
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
```

**With Variable Files**
```bash
# Plan with environment-specific variables
terraform plan \
  -var-file=environments/dev.tfvars \
  -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
```

**Targeted Plan**
```bash
# Plan specific resources only
terraform plan \
  -target=module.vpc \
  -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
```

=== “CloudFormation”

**Generate Change Set**
```bash
# Create a change set (CloudFormation equivalent of plan)
aws cloudformation create-change-set \
  --stack-name my-stack \
  --template-body file://template.yaml \
  --change-set-name my-changeset \
  --parameters ParameterKey=Environment,ParameterValue=dev

# Describe the change set for ThothCTL
aws cloudformation describe-change-set \
  --stack-name my-stack \
  --change-set-name my-changeset \
  --output json > changeset.json
```

**With SAM**
```bash
# SAM build and package
sam build
sam package --output-template-file packaged.yaml

# Create change set from SAM template
aws cloudformation create-change-set \
  --stack-name my-sam-stack \
  --template-body file://packaged.yaml \
  --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
  --change-set-name deploy-changeset
```

=== “CDK”

**CDK Diff (Plan Equivalent)**
```bash
# Synthesize and diff
cdk synth
cdk diff 2>&1 | tee cdk-diff.txt

# Generate CloudFormation template for analysis
cdk synth --output cdk.out
```

**CDK with Specific Stack**
```bash
# Diff a specific stack
cdk diff MyVpcStack
cdk diff MyEksStack

# Export template for ThothCTL scan
cdk synth MyVpcStack > template.yaml
```

4.2 ThothCTL Plan Validation

Once plan files are generated, use ThothCTL to validate them:

# Validate plan file (single)
thothctl check iac -type tfplan --plan-file tfplan.json

# Validate all plans in a directory (Terragrunt multi-stack)
thothctl check iac -type tfplan --plan-file tfplan/ --recursive

Validates:

Resource changes (create, update, destroy)
Dependency order
Configuration syntax
State consistency
Drift from expected state

4.3 Blast Radius Assessment

# Assess impact of changes (single plan)
thothctl check iac -type blast-radius --plan-file tfplan.json

# Assess across all stacks (Terragrunt)
thothctl check iac -type blast-radius --plan-file tfplan/ --recursive

Analyzes:

Affected resources count and type
Change propagation across dependencies
Risk levels (Low/Medium/High/Critical) using ITIL v4 classification
Rollback complexity
Mitigation strategies

Phase 5: Secure 🔒

Objective

Identify and remediate security vulnerabilities using multi-tool scanning.

ThothCTL Commands

5.1 Multi-Tool Security Scanning

# Run all available scanners
thothctl scan iac -t checkov -t trivy -t kics -t opa -t terraform-compliance

# Single tool scan (default: checkov)
thothctl scan iac -t checkov

# With hard enforcement (fails pipeline on violations)
thothctl scan iac -t checkov -t trivy --enforcement hard

# With organization policies (OPA/Rego)
thothctl scan iac -t opa --policy-dir git::https://github.com/myorg/iac-policies.git

# Post results to PR comment
thothctl scan iac -t checkov -t trivy --post-to-pr

# Output as SARIF for GitHub Code Scanning
thothctl scan iac -t checkov --output sarif

Available tools:

Tool	Flag	Detects
Checkov	`-t checkov`	Misconfigurations, compliance (CIS/SOC2/HIPAA), best practices
Trivy	`-t trivy`	CVEs, exposed secrets, insecure configs, license issues
KICS	`-t kics`	Security vulnerabilities (requires Docker)
OPA/Conftest	`-t opa`	Custom policy-as-code (Rego), org policies
Terraform Compliance	`-t terraform-compliance`	BDD-style compliance testing

Scan options:

Flag	Description
`--enforcement`	`soft` (report only, exit 0) or `hard` (fail pipeline, exit 1)
`--policy-dir`	Policy directory or Git URL for OPA/Conftest
`--post-to-pr`	Post scan summary as PR comment
`--output`	Output format: `text`, `json`, or `sarif`
`--reports-dir` / `-r`	Directory for reports (default: `Reports`)
`--tftool`	Use `terraform` or `tofu`
`--max-workers`	Parallel checkov scans (default: 2)
`--compact`	Reduce memory usage on constrained CI agents
`--verbose`	Enable verbose output

5.2 Organization Policy Enforcement

# Use org policies from Git repo (auto-detected from space config)
export THOTH_ORG_POLICY="git::https://github.com/myorg/iac-policies.git@main"
thothctl scan iac -t opa

# Or pass explicitly
thothctl scan iac -t opa --policy-dir ./policies/

# Terraform-compliance with BDD features
thothctl scan iac -t terraform-compliance --policy-dir ./compliance/

Validates:

Regulatory compliance (SOC2, HIPAA, PCI-DSS, CIS)
Organizational policies (naming, tagging, architecture)
Security baselines (encryption, network exposure, IAM)
Custom rules (OPA/Rego)

Phase 6: Deploy 🚀

Objective

Deploy infrastructure safely with proper validation.

ThothCTL Commands

6.1 Pre-Deployment Checks

# Run all checks before deployment
thothctl check iac -type blast-radius --plan-file tfplan.json

# For Terragrunt multi-stack (all plans in directory)
thothctl check iac -type blast-radius --plan-file tfplan/ --recursive

Performs:

Cost analysis
Blast radius assessment
Security scanning
Compliance validation

6.2 Apply Infrastructure Changes

=== “Terragrunt”

```bash
# Apply all stacks (respects dependency order)
terragrunt run \
  --working-dir stacks/ \
  --all \
  -- apply -auto-approve

# Apply a specific layer only
terragrunt run \
  --working-dir stacks/foundation \
  --all \
  -- apply -auto-approve

# Apply with saved plan files (safer — matches what was reviewed)
terragrunt run \
  --working-dir stacks/ \
  --all \
  --out-dir tfplan \
  -- apply

# Apply for specific environment
TF_VAR_ENVIRONMENT=prd terragrunt run \
  --working-dir stacks/ \
  --all \
  -- apply -auto-approve
```

=== “Terraform”

```bash
# Apply saved plan
terraform apply tfplan.binary
```

=== “CloudFormation”

```bash
# Execute the change set
aws cloudformation execute-change-set \
  --stack-name my-stack \
  --change-set-name my-changeset
```

=== “CDK”

```bash
# Deploy all stacks
cdk deploy --all --require-approval never

# Deploy specific stack
cdk deploy MyVpcStack
```

6.3 Generate Deployment Report

# Create comprehensive deployment report
thothctl check iac -type blast-radius \
  --plan-file tfplan/ \
  --recursive \
  --output deployment-report.html

Includes:

Change summary
Risk assessment
Cost impact
Security findings
Approval checklist

Phase 7: Operate 🔧

Objective

Manage day-to-day operations of deployed infrastructure: keep dependencies current, generate documentation, and clean up residual artifacts.

ThothCTL Commands

7.1 Keep Infrastructure Up to Date

# Check which modules and providers are outdated
thothctl inventory iac --check-versions --check-provider-versions

# Analyze upgrade safety before updating
thothctl inventory iac --check-versions --check-provider-versions --check-schema-compatibility

# Generate upgrade report
thothctl inventory iac --check-versions --report-type html

Provides:

Outdated module/provider detection with staleness scoring
Breaking change warnings before upgrades
Schema compatibility analysis with recommendations
Technical debt tracking over time

7.2 Generate and Update Documentation

# Auto-generate documentation for all stacks
thothctl document iac --recursive

# Generate dependency graph (Mermaid diagram)
thothctl document iac --framework terragrunt --graph-type mermaid

# Generate documentation for a specific stack
thothctl document iac --directory stacks/foundation/network/vpc

Creates:

README.md with module descriptions and inputs/outputs
Dependency graphs (Mermaid, Graphviz)
Architecture diagrams

7.3 Project Cleanup

# Remove residual files (.terraform, .terragrunt-cache, etc.)
thothctl project cleanup

# Dry run to see what would be removed
thothctl project cleanup --dry-run

Removes:

.terraform/ directories
.terragrunt-cache/ directories
Orphaned lock files
Temporary plan files

7.4 Bootstrap Development Environment

# Set up pre-commit hooks, IDE settings, and development tools
thothctl project bootstrap

# Preview without applying
thothctl project bootstrap --dry-run

Configures:

Pre-commit hooks (terragrunt-hclfmt, terraform-fmt, tflint)
Git configuration
IDE settings (.vscode, .idea)
ThothCTL configuration (.thothcf.toml)

!!! note “Platform Engineering Commands” The following commands are for platform engineering teams building reusable templates and project scaffolds, not for day-to-day operations:

```bash
# Convert a project into a reusable template (platform team)
thothctl project convert --make-template --template-project-type terraform

# Upgrade project scaffold from remote template (platform team)
thothctl project upgrade --interactive
```

Phase 8: Monitor 📊

Objective

Track infrastructure health, detect drift, and maintain compliance.

ThothCTL Commands

8.1 Launch Dashboard

# Start web dashboard with all reports
thothctl dashboard launch

# Custom port
thothctl dashboard launch --port 9090

Displays:

Security scan findings (filter by tool/severity/search)
SBOM details (CycloneDX metadata, dependency graph)
Inventory explorer (collapsible stacks, module/provider tabs)
Cost analysis (service breakdown, monthly/annual projections)
Drift detection (severity-classified drifted resources)
Blast radius visualization (topology + risk)
AI usage tracking (token counts, costs)

8.2 Drift Detection

# Detect configuration drift
thothctl check iac -type drift --recursive

# With AI-powered analysis (root cause, remediation plan)
thothctl check iac -type drift --recursive --ai-provider ollama

# Filter by tags
thothctl check iac -type drift --filter-tags "env=prod,team=platform"

Detects:

Resources that have drifted from desired state
Severity classification (critical/high/medium/low)
AI-powered root cause analysis
Remediation recommendations
Historical drift tracking

8.3 Continuous Monitoring (CI/CD)

# Scheduled scan with enforcement
thothctl scan iac -t checkov -t trivy --enforcement hard --output sarif

# Inventory freshness check
thothctl inventory iac --check-versions --check-provider-versions --report-type json

# Cost drift monitoring
thothctl check iac -type cost-analysis --recursive

Tracks:

Security posture over time (SQLite history)
Compliance drift
Cost trends
Version staleness
Infrastructure drift

Complete Workflow Example

Scenario: Deploy New AWS Infrastructure

# 1. PLAN: Initialize project
thothctl init project -p aws-prod --project-type terraform

# 2. DEVELOP: Check environment
thothctl check environment

# 3. BUILD: Create inventory with version checks
thothctl inventory iac --check-versions --check-provider-versions --report-type html

# 4. TEST: Validate plan
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json
thothctl check iac -type tfplan --plan-file tfplan.json

# 5. SECURE: Run security scans (multi-tool)
thothctl scan iac -t checkov -t trivy -t opa --enforcement hard

# 6. ASSESS: Check blast radius
thothctl check iac -type blast-radius --plan-file tfplan.json

# 7. COST: Estimate expenses
thothctl check iac -type cost-analysis --plan-file tfplan.json

# 8. DEPLOY: Apply changes
terraform apply tfplan.binary

# 9. DOCUMENT: Generate docs
thothctl document iac --recursive

# 10. MONITOR: Launch dashboard
thothctl dashboard launch

CI/CD Integration

GitHub Actions Example

name: IaC DevSecOps Pipeline

on: [pull_request, push]

jobs:
  devsecops:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup ThothCTL
        run: pip install thothctl

      - name: Check Environment
        run: thothctl check environment

      - name: Validate Structure
        run: thothctl check project iac

      - name: Create Inventory
        run: thothctl inventory iac --check-versions --check-provider-versions --report-type json

      - name: Security Scan
        run: thothctl scan iac -t checkov -t trivy --enforcement hard --output sarif

      - name: Terraform Plan
        run: |
          terraform init
          terraform plan -out=tfplan.binary
          terraform show -json tfplan.binary > tfplan.json

      - name: Blast Radius Assessment
        run: thothctl check iac -type blast-radius --plan-file tfplan.json

      - name: Cost Analysis
        run: thothctl check iac -type cost-analysis --plan-file tfplan.json

      - name: Generate Documentation
        run: thothctl document iac --recursive

Automated Workflow: One-Command Pipeline

The phases described above can be executed individually, or you can use the workflow command to orchestrate them automatically. This provides two levels of automation:

Level 1: CLI Workflow (Traditional)

The thothctl workflow devsecops command chains all phases with live progress, enforcement gates, and consolidated reporting:

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#3f51b5','primaryTextColor':'#ffffff','primaryBorderColor':'#303f9f','lineColor':'#536dfe','secondaryColor':'#536dfe','tertiaryColor':'#fff','background':'transparent','mainBkg':'#3f51b5','secondBkg':'#536dfe','tertiaryBkg':'#90caf9','textColor':'#ffffff','nodeTextColor':'#ffffff','fontSize':'14px'}}}%%
graph LR
    subgraph Workflow ["thothctl workflow devsecops --phase all"]
        A["📋 Plan"] --> B["💻 Develop"]
        B --> C["🔨 Build"]
        C --> D["✅ Test"]
        D --> E["🔒 Secure"]
        E --> F["🚀 Deploy"]
        F --> G["📊 Monitor"]
    end

    subgraph Gate ["Enforcement Gate"]
        H{"Violations?"}
        H -->|"Yes + hard"| I["⛔ Block"]
        H -->|"No"| J["✅ Continue"]
    end

    E --> H

    classDef phaseStyle fill:#3f51b5,stroke:#303f9f,stroke-width:2px,color:#ffffff
    classDef gatePass fill:#1b5e20,stroke:#2e7d32,stroke-width:2px,color:#ffffff
    classDef gateFail fill:#b71c1c,stroke:#c62828,stroke-width:2px,color:#ffffff
    classDef gateCheck fill:#e65100,stroke:#ef6c00,stroke-width:2px,color:#ffffff

    class A,B,C,D,E,F,G phaseStyle
    class H gateCheck
    class I gateFail
    class J gatePass

Run Full Pipeline

# All phases sequentially with soft enforcement (report only)
thothctl workflow devsecops --phase all

# All phases with hard enforcement (exit 1 on violations)
thothctl workflow devsecops --phase all --enforcement hard

Run Individual Phases

# Cost estimation and risk assessment (requires tfplan.json)
thothctl workflow devsecops --phase plan

# Environment + structure + documentation
thothctl workflow devsecops --phase develop

# Inventory with version analysis
thothctl workflow devsecops --phase build

# Plan validation (requires tfplan.json)
thothctl workflow devsecops --phase test

# Multi-tool security scanning
thothctl workflow devsecops --phase secure

# Deployment gate (always enforces hard)
thothctl workflow devsecops --phase deploy --enforcement hard

# Drift detection (requires cloud credentials)
thothctl workflow devsecops --phase monitor

Run Composite Phases

# Pre-deployment: test + secure (ideal for PR validation)
thothctl workflow devsecops --phase pre-deploy --enforcement hard

# With organization OPA policies from Git
thothctl workflow devsecops --phase pre-deploy \
  --policy-dir https://github.com/myorg/iac-policies.git@main \
  --enforcement hard

CI/CD Integration

=== “GitHub Actions”

```yaml
name: DevSecOps Pipeline

on: [pull_request]

jobs:
  devsecops:
    runs-on: ubuntu-latest
    env:
      THOTH_ORG_POLICY: $
    steps:
      - uses: actions/checkout@v4
      - run: pip install thothctl

      - name: Generate Plans
        run: |
          terraform init
          terraform plan -out=tfplan.binary
          terraform show -json tfplan.binary > tfplan.json

      - name: DevSecOps Gate
        run: thothctl workflow devsecops --phase pre-deploy --enforcement hard
```

=== “Azure Pipelines”

```yaml
trigger:
  - main

pool:
  vmImage: ubuntu-latest

variables:
  THOTH_ORG_POLICY: "https://$(POLICY_PAT)@dev.azure.com/myorg/myproject/_git/iac-policies@main"

steps:
  - checkout: self
  - script: pip install thothctl
    displayName: Install ThothCTL

  - script: |
      terragrunt run-all plan --out-dir tfplan --json-out-dir tfplan
    displayName: Generate Plans

  - script: |
      thothctl workflow devsecops --phase pre-deploy --enforcement hard
    displayName: DevSecOps Gate
```

=== “GitLab CI”

```yaml
devsecops:
  stage: validate
  image: python:3.12
  script:
    - pip install thothctl
    - terraform init && terraform plan -out=tfplan.binary
    - terraform show -json tfplan.binary > tfplan.json
    - thothctl workflow devsecops --phase pre-deploy --enforcement hard
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
```

Level 2: AI Agent (Kiro CLI)

For conversational, context-aware automation, use the ThothCTL MCP server with Kiro CLI:

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#3f51b5','primaryTextColor':'#ffffff','primaryBorderColor':'#303f9f','lineColor':'#536dfe','secondaryColor':'#536dfe','tertiaryColor':'#fff','background':'transparent','mainBkg':'#3f51b5','secondBkg':'#536dfe','tertiaryBkg':'#90caf9','textColor':'#ffffff','nodeTextColor':'#ffffff','fontSize':'14px'}}}%%
graph TB
    A["🤖 Developer<br/>Natural Language Intent"] --> B["Kiro CLI<br/>AI Agent + Skill"]
    B --> C["MCP Server<br/>thothctl mcp server --stdio"]
    C --> D["workflow_devsecops<br/>Orchestrates Phases"]
    D --> E["📊 Results + Remediation<br/>AI analyzes and explains"]
    E --> A

    classDef userStyle fill:#3f51b5,stroke:#303f9f,stroke-width:2px,color:#ffffff
    classDef aiStyle fill:#7b1fa2,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    classDef mcpStyle fill:#004d40,stroke:#00695c,stroke-width:2px,color:#ffffff
    classDef wfStyle fill:#e65100,stroke:#ef6c00,stroke-width:2px,color:#ffffff
    classDef resultStyle fill:#1b5e20,stroke:#2e7d32,stroke-width:2px,color:#ffffff

    class A userStyle
    class B aiStyle
    class C mcpStyle
    class D wfStyle
    class E resultStyle

Example Conversations

# Start Kiro CLI with ThothCTL agent
kiro-cli chat --agent thoth

User Says	AI Executes
“Check if my code is ready for production”	`workflow devsecops --phase pre-deploy`
“Run security scan”	`workflow devsecops --phase secure`
“What would this change cost?”	`workflow devsecops --phase plan`
“Full audit of my infrastructure”	`workflow devsecops --phase all`
“Is there drift in production?”	`workflow devsecops --phase monitor`

The AI agent adds intelligence on top:

Adapts commands based on project type (Terraform vs Terragrunt vs CDK)
Explains findings in context with specific remediation steps
Remembers previous results to track improvement over time
Routes to the right phase based on natural language intent

For full AI integration details, see: AI-Powered Development Lifecycle

Comparison: Manual vs Workflow vs AI

Aspect	Manual (Individual Commands)	Workflow Command	AI Agent
Entry point	Multiple `thothctl` commands	Single `thothctl workflow devsecops`	Natural language
Best for	Learning, debugging, custom flows	CI/CD pipelines, standardized gates	Exploration, remediation guidance
Enforcement	Per-command `--enforcement`	Single flag for all phases	AI decides based on context
Prerequisites	User must know command order	Automatic phase ordering	AI detects and guides
Output	Per-command reports	Consolidated table + reports	Explained findings + fixes
CI/CD	Script multiple commands	One-liner in pipeline	Not applicable

Best Practices

For Beginners

Start with templates: Use thothctl init project with templates
Check environment first: Run thothctl check environment
Use interactive mode: Add --interactive flag for guidance
Review reports: Always check HTML reports for details
Start with soft validation: Use --mode soft initially

For Professionals

Automate everything: Integrate into CI/CD pipelines
Use strict validation: Apply --mode hard for enforcement
Track inventory: Regular inventory iac scans
Monitor costs: Set up cost alerts and budgets
Enforce compliance: Use terraform-compliance policies
Version control: Track all changes with Git
Document continuously: Auto-generate docs on every change

Key Benefits

Phase	Without ThothCTL	With ThothCTL
Plan	Manual cost estimation	Automated cost analysis with AWS pricing
Develop	Inconsistent structure	Enforced standards and templates
Build	Manual dependency tracking	Automated inventory with version checking
Test	Basic terraform validate	Comprehensive plan validation + blast radius
Secure	Manual security reviews	Automated multi-tool scanning
Deploy	High risk	Risk-assessed with mitigation strategies
Operate	Manual updates	Automated upgrade paths
Monitor	Scattered metrics	Unified dashboard

Next Steps

Install ThothCTL: pip install thothctl
Initialize your first project: thothctl init project
Run your first scan: thothctl scan iac -t checkov
Explore the dashboard: thothctl dashboard launch
Read detailed docs: Visit thothctl.readthedocs.io

Support

Documentation: https://thothctl.readthedocs.io
GitHub: https://github.com/thothforge/thothctl
Issues: Report bugs or request features

This site is open source. Improve this page.