thothctl 0.24.2__tar.gz → 0.24.4__tar.gz

thothctl-0.24.4/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.1.11
+  hooks:
+    # Run the linter (includes import sorting with --fix).
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+
+#-   repo: https://github.com/PyCQA/bandit
+#    rev: 1.7.6
+#    hooks:
+#    - id: bandit
+
+
+#   repo: https://github.com/Lucas-C/pre-commit-hooks-safety
+#   rev: v1.7.2
+#   hooks:
+#   -   id: python-safety-dependencies-check
+#       args: [check, --full-report, --file]
+
+-   repo: https://github.com/PyCQA/pydocstyle
+    rev: 6.3.0
+    hooks:
+    -   id: pydocstyle

thothctl-0.24.4/.pydocstyle

@@ -0,0 +1,15 @@
+[pydocstyle]
+# Use Google convention as baseline.
+convention = google
+# Ignore:
+# D100-D107: Missing docstrings (adopt incrementally)
+# D200: One-line docstring should not occupy multiple lines
+# D202: No blank lines allowed after function docstring
+# D205: 1 blank line required between summary and description
+# D209: Multi-line docstring closing quotes on separate line
+# D212: Multi-line docstring summary should start at the first line
+# D403: First word should be properly capitalized
+# D415: First line should end with a period/question/exclamation
+# D417: Missing argument descriptions in docstring
+# D419: Docstring is empty
+add_ignore = D100,D101,D102,D103,D104,D105,D107,D200,D202,D205,D209,D212,D403,D415,D417,D419

thothctl-0.24.4/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: thothctl
+Version: 0.24.4
+Summary: A CLI for Developer Control Plane. Accelerate your cloud IaC deployments.
+Project-URL: SourceCode, https://github.com/thothforge/thothctl
+Project-URL: HomePage, https://github.com/thothforge/thothctl
+Author-email: Alejandro Velez <velez94@pm.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: argcomplete>=3.4.0
+Requires-Dist: argparse>=1.4.0
+Requires-Dist: azure-devops==7.1.0b4
+Requires-Dist: bc-python-hcl2>=0.4.2
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: checkov==3.2.451
+Requires-Dist: click>=8.0.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: gitdb>=4.0.11
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: inquirer>=3.3.0
+Requires-Dist: json2html>=1.3.0
+Requires-Dist: junit2html>=30.1.3
+Requires-Dist: junitparser>=2.0.0
+Requires-Dist: mcp>=1.9.4
+Requires-Dist: pre-commit>=3.7.1
+Requires-Dist: psutil
+Requires-Dist: pyfiglet>=1.0.2
+Requires-Dist: pymsteams>=0.2.2
+Requires-Dist: pytest-cov>=5.0.0
+Requires-Dist: pytest>=8.2.2
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: pyyaml<7.0.0,>=6.0.0
+Requires-Dist: requests
+Requires-Dist: rich>=13.7.1
+Requires-Dist: terraform-compliance>=1.3.48
+Requires-Dist: toml>=0.10.2
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: xmltodict>=0.13.0
+Requires-Dist: zipp>=3.19.2
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-instrumentation-logging>=0.41b0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+[![Publish Python Package](https://github.com/thothforge/thothctl/actions/workflows/python-publish.yml/badge.svg)](https://github.com/thothforge/thothctl/actions/workflows/python-publish.yml)
+[![Documentation](https://github.com/thothforge/thothctl/actions/workflows/docs.yml/badge.svg)](https://thothforge.github.io/thothctl/)
+[![PyPI version](https://img.shields.io/pypi/v/thothctl)](https://pypi.org/project/thothctl/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
+
+# ThothCTL
+
+**AI-Powered Infrastructure Lifecycle CLI** for DevSecOps, Platform Engineering, and IaC governance.
+
+![ThothCTL](./docs/img/framework/thothctl_mcp.png)
+
+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
+
+```bash
+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:
+
+```bash
+# 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_POLICY` env var (HCL + CloudFormation)
+- **Scan trend tracking** with local SQLite history
+
+### 📦 Infrastructure Inventory (SBOM)
+
+CycloneDX 1.6 compliant Software Bill of Materials:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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
+
+```bash
+thothctl project convert --make-template --template-project-type terraform
+thothctl init project --name my-infra --template terraform-aws
+```
+
+- **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
+
+```bash
+pip install --upgrade thothctl
+```
+
+**Requirements**: Python 3.10+ | Linux, macOS, or Windows (WSL)
+
+**Optional system packages**:
+```bash
+# Linux/Debian
+sudo apt install graphviz libgraph-easy-perl -y
+
+# macOS
+brew install graphviz graph-easy
+```
+
+### Dev Container
+
+A ready-to-use [Dev Container](.devcontainer/) is available with all tools pre-configured:
+
+```bash
+# Open in VS Code → "Reopen in Container"
+# Or use the devcontainer CLI:
+devcontainer up --workspace-folder .
+```
+
+## Documentation
+
+📖 **Full docs**: [thothforge.github.io/thothctl](https://thothforge.github.io/thothctl/)
+
+- [Quick Start](docs/quick_start.md)
+- [DevSecOps SDLC Guide](docs/framework/use_cases/devsecops_sdlc.md)
+- [Scan Command Reference](docs/framework/commands/scan/scan_overview.md)
+- [Inventory & SBOM](docs/framework/commands/inventory/inventory_overview.md)
+- [Dashboard](docs/dashboard/README.md)
+- [AI Review](docs/framework/commands/ai-review/README.md)
+- [Template Engine](docs/template_engine/template_engine.md)
+- [Dev Container Setup](docs/installation/devcontainer_setup.md)
+
+## CI/CD Integration
+
+```yaml
+# 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
+
+- [x] Multi-tool security scanning with unified reports
+- [x] AI Agent for IaC Security (multi-agent, auto-decisions)
+- [x] CycloneDX 1.6 SBOM with full supply chain metadata
+- [x] Organization policy engine (OPA/Rego, HCL + CloudFormation)
+- [x] 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](docs/framework/roadmap_fdi.md)
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[Apache-2.0](LICENSE)

thothctl-0.24.4/docs/framework/commands/dashboard/dashboard_overview.md

@@ -0,0 +1,159 @@
+# Dashboard Command
+
+The `dashboard` command launches a local web application that provides a unified view of all ThothCTL analysis results — security scans, inventory, cost analysis, blast radius, drift detection, and topology.
+
+## Overview
+
+The dashboard aggregates data from the `Reports/` directory and project configuration to present:
+
+- Security scan findings with severity breakdown
+- Infrastructure inventory (modules, providers, versions)
+- Software Bill of Materials (SBOM) viewer
+- AWS cost analysis projections
+- Blast radius impact visualization
+- Infrastructure drift status
+- Network topology diagrams
+- AI usage and decision history
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `launch` | Start the dashboard web server |
+
+## Usage
+
+```bash
+# Launch with defaults (port 8080, opens browser)
+thothctl dashboard launch
+
+# Custom port
+thothctl dashboard launch --port 3000
+
+# Without auto-opening browser
+thothctl dashboard launch --no-browser
+
+# Debug mode
+thothctl dashboard launch --debug
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-p, --port` | Integer | 8080 | Port to run the dashboard on |
+| `-h, --host` | Text | 127.0.0.1 | Host to bind the dashboard to |
+| `--debug` | Flag | false | Run in debug mode with auto-reload |
+| `--no-browser` | Flag | false | Do not open browser automatically |
+
+## Dashboard Sections
+
+### 📊 Project Overview
+
+Displays project metadata, type (Terraform/Terragrunt/CDK), and available ThothCTL commands for the detected project type.
+
+### 🔒 Security Findings
+
+Shows aggregated scan results from Checkov, Trivy, KICS, and OPA:
+- Severity breakdown (critical, high, medium, low)
+- Findings per tool
+- Trend over time (from scan history)
+
+### 📦 Inventory
+
+Module and provider catalog:
+- Current vs latest versions
+- Source URLs
+- Outdated dependency alerts
+- CycloneDX SBOM data
+
+### 💰 Cost Analysis
+
+AWS cost projections from tfplan analysis:
+- Monthly/annual estimates
+- Per-service breakdown
+- Optimization recommendations
+
+### 💥 Blast Radius
+
+Change impact visualization:
+- Resources affected by plan
+- Create/update/delete breakdown
+- Risk assessment
+
+### 🔄 Drift Detection
+
+Infrastructure drift status:
+- Resources with state mismatch
+- Drift history and trends
+- Coverage metrics
+
+### 🗺️ Topology
+
+Infrastructure topology visualization:
+- Resource dependency graph
+- Network architecture diagram
+
+### 🤖 AI Usage
+
+AI-powered analysis history:
+- Decisions made by AI review
+- Cost tracking per provider
+- Session history
+
+## API Endpoints
+
+The dashboard exposes a REST API for programmatic access:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/project` | Project info (type, name, commands) |
+| `GET /api/inventory` | Module and provider inventory |
+| `GET /api/sbom` | CycloneDX SBOM data |
+| `GET /api/scan-results` | Security scan results |
+| `GET /api/findings` | Detailed findings list |
+| `GET /api/cost-analysis` | Cost projections |
+| `GET /api/blast-radius` | Blast radius data |
+| `GET /api/drift` | Drift detection results |
+| `GET /api/topology` | Infrastructure topology |
+| `GET /api/ai-usage` | AI decision history |
+| `GET /api/refresh` | Reload all data from Reports/ |
+
+## Prerequisites
+
+The dashboard reads data from the `Reports/` directory. Run analysis commands first:
+
+```bash
+# Generate data for the dashboard
+thothctl scan iac -t checkov -t trivy -t opa       # Security findings
+thothctl inventory iac --check-versions             # Inventory + SBOM
+thothctl check iac -type cost-analysis              # Cost analysis
+thothctl check iac -type blast-radius               # Blast radius
+thothctl check iac -type drift                      # Drift detection
+```
+
+Or use the workflow command to run everything:
+
+```bash
+thothctl workflow devsecops --phase all
+thothctl dashboard launch
+```
+
+## Example
+
+```bash
+# Run full pipeline then view results
+$ thothctl workflow devsecops --phase all
+$ thothctl dashboard launch --port 3000
+
+🌐 Dashboard running at http://127.0.0.1:3000
+📊 Loaded: 22 findings, 45 modules, 3 cost reports
+🔧 Press Ctrl+C to stop
+```
+
+## Related
+
+- [Scan Command](../scan/scan_overview.md)
+- [Inventory Command](../inventory/)
+- [Check Command](../check/)
+- [Workflow Command](../workflow/workflow_overview.md)