thothctl 0.20.2__tar.gz → 0.20.4__tar.gz

{thothctl-0.20.2 → thothctl-0.20.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thothctl
-Version: 0.20.2
+Version: 0.20.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

{thothctl-0.20.2 → thothctl-0.20.4}/docs/dashboard/README.md

@@ -12,6 +12,7 @@ The ThothCTL Dashboard provides a unified web interface to view and manage all y
 - **⚠️ Risk Assessment**: Blast radius analysis and mitigation strategies
 - **🔍 Drift Detection**: Infrastructure drift visualization between IaC and live cloud state
 - **🤖 AI Token Usage**: Track AI provider token consumption and cost metrics
+- **🗺️ Infrastructure Topology** — Mermaid dependency graph with blast radius overlay, zoom controls, AWS architecture PNG download
 - **🔄 Real-time Refresh**: Manual data refresh capability
 - **📱 Responsive Design**: Works on desktop, tablet, and mobile devices
 - **🌙 Complete dark mode support**
@@ -126,6 +127,23 @@ Monitor AI provider consumption:
 - Usage trends over time
 - Budget threshold indicators
 
+### Infrastructure Topology
+
+The infrastructure topology view is integrated within the **Blast Radius** tab, providing a unified visualization of your infrastructure dependencies and change impact:
+
+- **Summary cards**: Total stacks, resources, changed resources, and resource categories at a glance
+- **Color-coded legend**: Resource categories (compute, storage, networking, etc.) with distinct colors for quick identification
+- **Mermaid dependency graph**: Interactive diagram showing resource relationships with blast radius overlay. Includes zoom controls (+/−/Fit) for navigating large topologies
+- **Resources-by-stack tables**: Collapsible tables showing detailed resource breakdown per stack
+- **PNG download**: Export a professional architecture diagram with official AWS icons for documentation and presentations
+
+**Data source**: `Reports/topology/topology.json`
+
+**Generate topology data**:
+```bash
+thothctl check iac -type blast-radius --recursive
+```
+
 ## Architecture
 
 ### Twelve-Factor App Compliance
@@ -177,6 +195,7 @@ class DashboardDataLoader:
 - `GET /api/sbom` - CycloneDX SBOM data
 - `GET /api/cost-analysis` - Cost analysis data
 - `GET /api/blast-radius` - Risk assessment data
+- `GET /api/topology` - Infrastructure topology with mermaid diagram
 - `GET /api/drift` - Drift detection data
 - `GET /api/ai-usage` - AI token/cost usage
 - `GET /api/reports/{path}` - Serve HTML reports for iframe viewing
@@ -231,6 +250,11 @@ Reports/
 │   ├── InventoryIaC_*.json              # Inventory data
 │   ├── InventoryIaC_cyclonedx_*.json    # CycloneDX SBOM data
 │   └── html_reports/                    # Inventory HTML reports
+├── topology/
+│   ├── topology.json                    # Infrastructure topology data
+│   └── architecture.png                 # AWS architecture diagram
+├── blast-radius/
+│   └── blast_radius_*.json              # Blast radius analysis
 ├── opa/
 │   └── html_reports/                    # OPA/compliance HTML reports
 ├── cost_analysis_*.json                 # Cost analysis

{thothctl-0.20.2 → thothctl-0.20.4}/docs/framework/commands/check/blast-radius.md

@@ -257,3 +257,109 @@ Components can be marked with specific criticality levels:
 - [`thothctl check -type plan`](../check/plan.md) - Plan validation
 - [`thothctl inventory iac`](../inventory/iac.md) - Infrastructure inventory
 - [`thothctl scan iac`](../scan/iac.md) - Security scanning
+
+## Blast Radius v0.20.0+ Enhancements
+
+Starting with v0.20.0, the blast radius command includes significant improvements to change detection, topology generation, and report outputs.
+
+### Enhanced Usage
+
+```bash
+thothctl check iac -type blast-radius --recursive
+```
+
+### What it does (v0.20.0+)
+
+1. Finds `tfplan.json` files recursively across all stacks
+2. Filters out no-op/read resources (only create/update/delete/replace affect blast radius)
+3. Propagates changes through the dependency graph
+4. Classifies risk: LOW/MEDIUM/HIGH/CRITICAL using ITIL v4
+5. Generates ITIL change type: STANDARD/NORMAL/EMERGENCY
+6. Saves reports to `Reports/blast-radius/blast_radius_*.json`
+7. Generates infrastructure topology diagram (`Reports/topology/`)
+
+### Report Outputs
+
+```
+Reports/
+├── blast-radius/
+│   └── blast_radius_20260705_*.json    # Risk assessment data
+└── topology/
+    ├── topology.json                    # Full topology + mermaid
+    ├── topology.mmd                     # Standalone mermaid file
+    └── architecture.png                 # Professional AWS diagram
+```
+
+### No-Changes Handling
+
+When terraform plan shows no changes (all no-op), blast radius returns LOW risk with:
+
+- Zero affected components
+- Context about total infrastructure size
+- Clear message that no create/update/delete actions were detected
+
+This ensures pipelines don't fail on plans with no actionable changes while still providing visibility into the existing infrastructure footprint.
+
+### Infrastructure Topology
+
+The blast radius command automatically generates visual topology outputs:
+
+- **Mermaid diagram** with color-coded nodes (create=blue, update=orange, delete=red dashed)
+- **PNG architecture diagram** with official AWS icons via mingrammer/diagrams
+- **Resource-level detail** per stack with category and action badges
+
+The topology files are written to `Reports/topology/` and include both machine-readable JSON and renderable diagram formats suitable for embedding in PRs or documentation.
+
+### Dashboard Integration
+
+The web dashboard shows blast radius + topology in a unified view under the **💥 Blast Radius** tab. This includes:
+
+- Risk summary with ITIL classification
+- Interactive topology diagram
+- Per-stack affected resource breakdown
+- Change action badges (create, update, delete, replace)
+
+## Dual-Mode Cost Analysis (v0.20.0+)
+
+The `thothctl check iac -type cost-analysis` command now provides dual-mode cost estimation:
+
+### Usage
+
+```bash
+thothctl check iac -type cost-analysis --recursive
+```
+
+### Modes
+
+- **Change delta**: Cost of resources being created/modified (for PR reviews). This shows the incremental cost impact of the proposed changes.
+- **Total running cost**: Cost of ALL planned resources (from `planned_values`). This provides a full picture of what the infrastructure costs to run.
+
+### No-Changes Behavior
+
+When no changes are detected in the plan, cost analysis shows the total running cost instead of `$0`. This gives teams continuous visibility into their infrastructure spend even when no modifications are pending.
+
+### JSON Report Fields
+
+The cost analysis JSON report includes:
+
+| Field | Description |
+|-------|-------------|
+| `total_running_monthly_cost` | Monthly cost of all planned resources |
+| `total_running_annual_cost` | Annual projection of all planned resources |
+| `total_planned_resources` | Count of all resources in the plan |
+| `change_delta_monthly_cost` | Monthly cost delta from changes only |
+| `change_delta_annual_cost` | Annual cost delta from changes only |
+
+### Example Output
+
+```json
+{
+  "total_running_monthly_cost": 1250.00,
+  "total_running_annual_cost": 15000.00,
+  "total_planned_resources": 47,
+  "change_delta_monthly_cost": 85.50,
+  "change_delta_annual_cost": 1026.00
+}
+```
+
+This dual-mode approach ensures that PR reviews show the marginal cost of changes while still providing the full cost picture for governance and budgeting.

{thothctl-0.20.2 → thothctl-0.20.4}/docs/framework/commands/scan/scan_overview.md

@@ -138,6 +138,74 @@ warn contains msg if {
 }
 ```
 
+### YAML Data Files for Policy Parameterization (v0.20.2)
+
+OPA/Conftest now supports automatic conversion of YAML data files (`.yaml`/`.yml`) to JSON for policy parameterization. This allows you to externalize policy parameters — such as allowed regions, required tags, and thresholds — from your Rego code into maintainable YAML configuration files.
+
+#### How It Works
+
+- Place YAML files alongside your `.rego` policies (e.g., `policy/config.yaml`)
+- ThothCTL auto-converts YAML data files to JSON before running Conftest
+- Conftest automatically loads the converted JSON as data via its `--data` flag
+- **Caching**: only reconverts if the YAML source is newer than the existing JSON, avoiding unnecessary work on repeated scans
+
+#### Use Case
+
+Externalize policy parameters that change across teams or environments without modifying Rego logic:
+
+- Allowed cloud regions
+- Required resource tags
+- Cost or resource count thresholds
+- Naming convention patterns
+
+#### Example
+
+Define your parameters in YAML:
+
+```yaml
+# policy/config.yaml
+allowed_regions:
+  - us-east-1
+  - eu-west-1
+required_tags:
+  - Environment
+  - Owner
+```
+
+Reference them in your Rego policy via `data.config`:
+
+```rego
+# policy/regions.rego
+package main
+import data.config
+
+deny[msg] {
+  # uses config.allowed_regions from YAML
+  resource := input.resource.aws_instance[name]
+  not resource.provider_region in config.allowed_regions
+  msg := sprintf("Instance '%s' deployed in non-allowed region", [name])
+}
+
+deny[msg] {
+  resource := input.resource.aws_instance[name]
+  missing := {tag | tag := config.required_tags[_]; not resource.tags[tag]}
+  count(missing) > 0
+  msg := sprintf("Instance '%s' missing required tags: %v", [name, missing])
+}
+```
+
+#### Directory Layout
+
+```
+policy/
+├── config.yaml         # Externalized parameters (auto-converted to JSON)
+├── regions.rego        # Policy using data.config.allowed_regions
+├── tagging.rego        # Policy using data.config.required_tags
+└── ...
+```
+
+No additional CLI flags are needed — ThothCTL detects YAML files in the policy directory automatically.
+
 ## Enforcement (v0.19.0)
 
 When `--enforcement hard` is specified, ThothCTL gates the pipeline based on scan findings:

{thothctl-0.20.2 → thothctl-0.20.4}/src/thothctl/commands/scan/commands/iac.py

@@ -83,11 +83,19 @@ class RestoredIaCScanCommand(ClickCommand):
             start_time = time.perf_counter()
             
             # Execute scan with original functionality
+            # Build scanner options
+            scan_options = self._parse_options(options) if options else {}
+
+            # Inject --policy-dir into OPA options if provided
+            policy_dir = kwargs.get('policy_dir')
+            if policy_dir:
+                scan_options['policy_dir'] = policy_dir
+
             results = scan_service.execute_scans(
                 directory=code_directory,
                 reports_dir=reports_dir,
                 selected_tools=tools,
-                options=self._parse_options(options) if options else {},
+                options=scan_options,
                 tftool=tftool,
                 max_workers=max_workers,
                 compact=compact,
@@ -255,8 +263,10 @@ class RestoredIaCScanCommand(ClickCommand):
                     border_style="red"
                 )
                 self.console.print(enforcement_panel)
-                ctx.exit(1)
+                raise SystemExit(1)
 
+        except SystemExit:
+            raise  # Let enforcement exit propagate without showing error panel
         except Exception as e:
             error_panel = Panel(
                 f"[bold red]Security scan could not complete[/bold red]\n\n"
@@ -717,6 +727,14 @@ cli = RestoredIaCScanCommand.as_click_command(
         help="Additional options for scanning tools (key=value,key2=value2)",
         type=str,
     ),
+    click.option(
+        "--policy-dir",
+        help="Policy directory or Git URL for OPA/Conftest (default: 'policy'). "
+             "Supports: local path, absolute path, Git URL (https://...), "
+             "or THOTH_ORG_POLICY env var.",
+        type=str,
+        default=None,
+    ),
     click.option(
         "--tftool",
         default="tofu",

{thothctl-0.20.2 → thothctl-0.20.4}/src/thothctl/services/scan/scanners/opa.py

@@ -163,6 +163,12 @@ class OPAScanner(ScannerPort):
         if options.get("data_dir"):
             cmd_json.extend(["--data", options["data_dir"]])
 
+        # Auto-detect JSON data files in the policy directory and pass via --data
+        # conftest requires explicit --data to load JSON into the data namespace
+        # (the --policy flag only loads .rego files)
+        for data_file in sorted(Path(abs_policy).glob("*.json")):
+            cmd_json.extend(["--data", str(data_file)])
+
         cmd_json.extend(scan_files)
 
         self.ui.start_scan_message(abs_dir)

thothctl-0.20.4/src/thothctl/version.py

@@ -0,0 +1,2 @@
+"""Version module."""
+__version__ = "0.20.4"

thothctl-0.20.2/src/thothctl/version.py

@@ -1,2 +0,0 @@
-"""Version module."""
-__version__ = "0.20.2"