thothctl 0.24.2__tar.gz → 0.24.3__tar.gz

{thothctl-0.24.2 → thothctl-0.24.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thothctl
-Version: 0.24.2
+Version: 0.24.3
 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

thothctl-0.24.3/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)

thothctl-0.24.3/docs/framework/commands/space/space_overview.md

@@ -0,0 +1,264 @@
+# Space Command
+
+The `space` command manages ThothCTL spaces — logical contexts that group configuration, credentials, VCS providers, and governance policies. Spaces enable multi-team and multi-environment workflows.
+
+## Overview
+
+Spaces provide:
+
+- Active context for credential resolution (Azure DevOps, GitHub, GitLab)
+- Organization-level policy repository configuration
+- Terraform registry and orchestration tool defaults
+- Team-level isolation for projects
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `activate` | Set a space as the active context |
+| `show` | Display space configuration summary |
+| `update` | Modify space settings (policy repo, VCS, tools) |
+
+## Usage
+
+```bash
+# Activate a space
+thothctl space activate my-space
+
+# Show space configuration
+thothctl space show my-space
+
+# Update space settings
+thothctl space update my-space --policy-repo https://github.com/myorg/policies.git
+thothctl space update my-space --vcs-provider azure_repos
+thothctl space update my-space --orchestration-tool terragrunt
+```
+
+## Subcommand Reference
+
+### activate
+
+Set a space as the active context. All subsequent commands use this space for credential resolution and defaults.
+
+```bash
+thothctl space activate <SPACE_NAME>
+```
+
+**Effect:**
+- Writes space name to `~/.thothcf/active_space`
+- New projects default to this space unless `--space` is specified
+- Commands that need VCS credentials (e.g., `--post-to-pr`) use this space's stored PAT
+
+**Example:**
+```bash
+$ thothctl space activate lab-azure
+🌐 Active space set to 'lab-azure'
+New projects will use this space by default unless --space is specified.
+```
+
+---
+
+### show
+
+Display the full configuration of a space.
+
+```bash
+thothctl space show <SPACE_NAME>
+```
+
+**Displays:**
+- Space name and version
+- VCS provider and settings (organization, project, repository)
+- Terraform registry configuration
+- Orchestration tool (terragrunt, terramate, none)
+- Policy repository URL (if configured)
+- Credentials status (encrypted PAT present/missing)
+
+---
+
+### update
+
+Modify space configuration settings.
+
+```bash
+thothctl space update <SPACE_NAME> [OPTIONS]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `-pr, --policy-repo` | Text | Git URL or local path for organization policies |
+| `-tr, --terraform-registry` | Text | Terraform registry URL |
+| `-ot, --orchestration-tool` | Choice | `terragrunt`, `terramate`, or `none` |
+| `-vcs, --vcs-provider` | Choice | `azure_repos`, `github`, or `gitlab` |
+| `-d, --description` | Text | Space description |
+
+**Examples:**
+```bash
+# Set organization policy repository
+thothctl space update production --policy-repo https://github.com/myorg/iac-policies.git
+
+# Change VCS provider
+thothctl space update production --vcs-provider github
+
+# Set orchestration tool
+thothctl space update production --orchestration-tool terragrunt
+
+# Update Terraform registry (private registry)
+thothctl space update production --terraform-registry https://app.terraform.io
+```
+
+## Space Configuration Structure
+
+Spaces are stored at `~/.thothcf/spaces/<space-name>/`:
+
+```
+~/.thothcf/spaces/my-space/
+├── space.toml                    # Main configuration
+├── vcs/
+│   ├── azure_repos.toml          # Azure DevOps settings
+│   ├── github.toml               # GitHub settings
+│   └── gitlab.toml               # GitLab settings
+├── credentials/
+│   └── vcs.enc                   # Encrypted PAT token
+├── terraform/
+│   └── registry.toml             # Registry configuration
+└── orchestration/
+    └── terragrunt.toml           # Orchestration settings
+```
+
+### space.toml Example
+
+```toml
+[space]
+name = "production"
+version = "1.0.0"
+
+[credentials]
+path = "credentials"
+
+[version_control]
+path = "vcs"
+default_provider = "azure_repos"
+providers = ["azure_repos", "github", "gitlab"]
+
+[terraform]
+path = "terraform"
+registry_url = "https://registry.terraform.io"
+auth_method = "none"
+
+[orchestration]
+path = "orchestration"
+default_tool = "terragrunt"
+tools = ["terragrunt", "terramate", "none"]
+```
+
+### VCS Provider Configuration
+
+#### Azure DevOps (`vcs/azure_repos.toml`)
+```toml
+provider = "azure_repos"
+
+[settings]
+organization = "myorg"
+project = "infrastructure"
+repository = "iac-modules"
+branch = "main"
+auth_method = "pat"
+```
+
+#### GitHub (`vcs/github.toml`)
+```toml
+provider = "github"
+
+[settings]
+organization = "myorg"
+repository = "infrastructure"
+branch = "main"
+auth_method = "pat"
+```
+
+## Creating Spaces
+
+Spaces are created with `thothctl init space`:
+
+```bash
+# Interactive creation
+thothctl init space --space-name production
+
+# The init wizard prompts for:
+# - VCS provider (azure_repos, github, gitlab)
+# - Organization/project details
+# - PAT token (stored encrypted)
+# - Terraform registry
+# - Orchestration tool
+```
+
+## How Spaces Are Used
+
+### Credential Resolution
+
+When a command needs VCS credentials (e.g., `--post-to-pr`, `--reuse` for templates):
+
+```
+1. Check --space flag → use that space
+2. Check active space (~/.thothcf/active_space) → use active
+3. Check project .thothcf.toml [thothcf] space field → use project's space
+4. Fail with "no space configured"
+```
+
+### Policy Repository
+
+When `thothctl scan iac -t opa` needs policies:
+
+```
+1. Check --policy-dir flag → explicit path/URL
+2. Check THOTH_ORG_POLICY env var → URL
+3. Check active space → governance.policy_repo field
+4. Check local ./policy directory → default
+```
+
+### PR Comments
+
+When `--post-to-pr` is used:
+
+```
+1. Detect CI environment (Azure Pipelines, GitHub Actions)
+2. Resolve space credentials for the VCS provider
+3. Post scan summary as PR comment using the stored PAT
+```
+
+## Examples
+
+### Multi-Environment Setup
+
+```bash
+# Create spaces for each environment
+thothctl init space --space-name dev
+thothctl init space --space-name staging
+thothctl init space --space-name production
+
+# Activate for current work
+thothctl space activate dev
+
+# Override for specific commands
+thothctl scan iac --post-to-pr --space production
+```
+
+### Organization Policy Binding
+
+```bash
+# Bind org policies to a space
+thothctl space update production \
+  --policy-repo https://github.com/myorg/iac-policies.git
+
+# Now any scan in this space auto-uses org policies
+thothctl space activate production
+thothctl scan iac -t opa  # Uses org policies automatically
+```
+
+## Related
+
+- [Space Management Use Case](../../use_cases/space_management.md)
+- [Init Space Command](../init/)
+- [Scan Command — Policy Resolution](../scan/scan_overview.md)
+- [Workflow Command](../workflow/workflow_overview.md)