thothctl
ThothCTL
AI-Powered Infrastructure Lifecycle CLI for DevSecOps, Platform Engineering, and IaC governance.
ThothCTL accelerates the adoption of Internal Developer Platforms by combining security scanning, inventory management, cost analysis, AI-driven code review, and organizational policy enforcement into a single CLI.
Quick Start
pip install --upgrade thothctl
# Scan for security issues
thothctl scan iac -t checkov -t trivy -t opa
# Create infrastructure inventory (SBOM)
thothctl inventory iac --check-versions
# Launch web dashboard
thothctl dashboard launch
# AI-powered security review
thothctl ai-review analyze -d ./terraform -p ollama
Key Features
🔒 Security Scanning
Multi-tool scanning with unified HTML reports and enforcement:
# All scanners with hard enforcement (fails pipeline on violations)
thothctl scan iac -t checkov -t trivy -t kics -t opa -t terraform-compliance --enforcement hard
- 5 integrated tools: Checkov, Trivy, KICS, OPA/Conftest, Terraform-compliance
- Unified HTML reports with severity badges, per-stack breakdown
- Non-compliance findings table on enforcement failure
- SARIF output for GitHub Code Scanning integration
- Organization policy repos via
THOTH_ORG_POLICYenv var (HCL + CloudFormation) - Scan trend tracking with local SQLite history
📦 Infrastructure Inventory (SBOM)
CycloneDX 1.6 compliant Software Bill of Materials:
thothctl inventory iac --check-versions
- Module & provider version tracking with staleness detection
- CycloneDX 1.6 SBOM with formulation, evidence, standards, attestations, dependency graph, hashes, and licenses
- Technical debt scoring with risk levels and recommendations
- Schema compatibility analysis for safe upgrades
- Professional HTML reports with collapsible stack groups
📊 Web Dashboard
Modern FastAPI-based dashboard with dark mode:
thothctl dashboard launch
- Security findings viewer — filter by tool/severity/search, pagination, inline report iframe
- SBOM details browser — CycloneDX metadata, dependency graph, formulation, attestations
- Inventory explorer — collapsible stacks, module/provider tabs, version comparison
- Cost analysis — service breakdown, monthly/annual projections
- Drift detection — severity-classified drifted resources
- AI usage tracking — token counts, costs per request
🤖 AI Agent for IaC Security
Multi-agent system for automated code review and PR decisions:
thothctl ai-review analyze -d ./terraform -p ollama
thothctl ai-review decide -d ./terraform --pr-number 42 --dry-run
- 4 specialized agents: Security, Architecture, Fix, Decision
- Multi-provider: OpenAI, AWS Bedrock, Azure OpenAI, Ollama (local)
- Auto-decisions with confidence thresholds and safety controls
- Adaptive memory: filesystem or S3 (auto-detects runtime)
- MCP integration for AI assistant interoperability
💰 Cost Analysis & Risk Assessment
thothctl check iac -type cost-analysis --recursive
thothctl check iac -type blast-radius --recursive
thothctl check iac -type drift --recursive
- 14 AWS services supported (EC2, RDS, S3, Lambda, EKS, etc.)
- Blast radius with ITIL v4 risk classification
- Drift detection with severity scoring and IaC coverage tracking
🔄 Template Engine & Project Management
thothctl project convert --make-template --template-project-type terraform
thothctl init project -p my-infra --project-type terraform
- Bidirectional conversion between projects and reusable templates
- Backstage integration for self-service consumption
- Template upgrade workflow to keep projects in sync
All Commands
| Command | Description |
|---|---|
scan iac |
Multi-tool security scanning with enforcement |
inventory iac |
Infrastructure SBOM with version tracking |
check iac |
Cost analysis, blast radius, drift detection, structure validation |
ai-review |
AI-powered security analysis and PR decisions |
dashboard launch |
Web dashboard for all reports |
document iac |
Auto-generate documentation |
project convert |
Template ↔ project conversion |
init project |
Scaffold new IaC projects |
mcp |
Model Context Protocol server |
generate |
Generate IaC from rules and components |
Installation
pip install --upgrade thothctl
| Requirements: Python 3.10+ | Linux, macOS, or Windows (WSL) |
Optional system packages:
# Linux/Debian
sudo apt install graphviz libgraph-easy-perl -y
# macOS
brew install graphviz graph-easy
Dev Container
A ready-to-use Dev Container is available with all tools pre-configured:
# Open in VS Code → "Reopen in Container"
# Or use the devcontainer CLI:
devcontainer up --workspace-folder .
Documentation
📖 Full docs: thothforge.github.io/thothctl
- Quick Start
- DevSecOps SDLC Guide
- Scan Command Reference
- Inventory & SBOM
- Dashboard
- AI Review
- Template Engine
- Dev Container Setup
CI/CD Integration
# GitHub Actions
- name: Security scan
run: thothctl scan iac -t checkov -t trivy -t opa --enforcement hard --post-to-pr
- name: Inventory check
run: thothctl inventory iac --check-versions --report-type json
Roadmap
- Multi-tool security scanning with unified reports
- AI Agent for IaC Security (multi-agent, auto-decisions)
- CycloneDX 1.6 SBOM with full supply chain metadata
- Organization policy engine (OPA/Rego, HCL + CloudFormation)
- Web Dashboard with findings viewer and SBOM browser
- Intent-to-IaC generation (natural language → governed Terraform)
- Composable workflow engine (declarative YAML DAG pipelines)
- Graph-aware state visibility (tfstate → queryable resource graph)
- Architecture diagram generation (Mermaid/Graphviz from IaC)
- Strands Agents SDK integration
📖 Full Roadmap
Contributing
Contributions welcome! See CONTRIBUTING.md for guidelines.