ThothCTL Inventory Command

Overview

The thothctl inventory command creates, manages, and updates inventories of your infrastructure components. This command helps you track modules, their versions, sources, and dependencies, providing valuable insights into your infrastructure composition and enabling version management.

Available Inventory Commands

inventory iac

Creates an inventory of Infrastructure as Code (IaC) components in your project, including modules, providers, and their versions. Generates CycloneDX 1.6 SBOM reports.

thothctl inventory iac [OPTIONS]

Core Options:

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)
`--check-schema-compatibility`		Analyze breaking changes between current and latest versions
`--check-providers`		Report provider information for each stack
`--report-type`	`-r`	Output: `html`, `json`, `cyclonedx`, or `all` (default: html)
`--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
`--project-name`	`-pj`	Custom project name for reports
`--inventory-path`	`-iph`	Custom output path (default: `./Reports`)
`--inventory-action`	`-iact`	Action: `create`, `update`, `restore` (default: create)
`--update-dependencies-path`	`-updep`	Pass inventory JSON for dependency updates
`--auto-approve`	`-auto`	Auto-approve dependency updates (for CI/CD)
`--post-to-pr`		Post inventory summary as PR comment
`--vcs-provider`		VCS for PR comments: `auto`, `azure_repos`, `github`
`--space`		Space name for credential resolution
`--terragrunt-args`	`-tg-args`	Additional terragrunt arguments

Detailed documentation for inventory iac

Basic Usage

Create an Inventory

thothctl inventory iac

This creates an inventory of all IaC components in the current directory and generates an HTML report in the default location (./Reports/Inventory).

Create an Inventory with Version Checking

thothctl inventory iac --check-versions

This creates an inventory and checks if the modules are using the latest available versions.

Check Provider Versions

# Check provider versions (independently from module versions)
thothctl inventory iac --check-provider-versions

# Check both modules and providers
thothctl inventory iac --check-versions --check-provider-versions

# Analyze schema compatibility (breaking changes between versions)
thothctl inventory iac --check-versions --check-provider-versions --check-schema-compatibility

Generate CycloneDX SBOM

# Generate OWASP CycloneDX 1.6 compliant SBOM
thothctl inventory iac --check-versions --report-type cyclonedx

# Generate all report types (HTML + JSON + CycloneDX)
thothctl inventory iac --check-versions --report-type all

The CycloneDX SBOM includes:

Formulation (how components are assembled)
Evidence (proof of component presence)
Standards mapping
Attestations
Dependency graph
Hashes and licenses

Post Results to PR

# Post inventory summary as a PR comment (auto-detects CI environment)
thothctl inventory iac --check-versions --post-to-pr

# Specify VCS provider explicitly
thothctl inventory iac --check-versions --post-to-pr --vcs-provider github

Generate Different Report Types

thothctl inventory iac --report-type json

This creates an inventory and generates a JSON report.

thothctl inventory iac --report-type all

This creates an inventory and generates both HTML and JSON reports.

Framework Type Options

The command supports different IaC frameworks:

Auto-detect Framework (Default)

thothctl inventory iac --framework-type auto

This automatically detects the framework type based on the files in your project.

Terraform Framework

thothctl inventory iac --framework-type terraform

This analyzes only Terraform files (.tf) in your project.

Terragrunt Framework

thothctl inventory iac --framework-type terragrunt

This analyzes only Terragrunt files (terragrunt.hcl) in your project, excluding .terragrunt-cache directories.

Mixed Terraform-Terragrunt Framework

thothctl inventory iac --framework-type terraform-terragrunt

This analyzes both Terraform and Terragrunt files in your project.

Inventory Actions

The command supports three main actions:

1. Create (Default)

thothctl inventory iac --inventory-action create

This action scans your IaC files and creates a new inventory.

2. Update

thothctl inventory iac --inventory-action update --inventory-path ./path/to/inventory.json

This action updates your IaC files based on the inventory. It can be used to apply version updates or other changes.

3. Restore

thothctl inventory iac --inventory-action restore --inventory-path ./path/to/inventory.json

This action restores your IaC files to the state recorded in the inventory.

Inventory Reports

The command generates detailed reports about your infrastructure components:

HTML Report

The HTML report includes:

Project overview and framework type
Module list with versions and sources
Dependency graph visualization
Version status (latest vs. current)
File locations

JSON Report

The JSON report contains structured data about your infrastructure:

{
  "version": 2,
  "projectName": "my-project",
  "projectType": "terragrunt",
  "components": [
    {
      "path": "./modules",
      "components": [
        {
          "type": "terragrunt_module",
          "name": "vpc",
          "version": ["3.14.0"],
          "source": ["terraform-aws-modules/vpc/aws"],
          "file": "modules/terragrunt.hcl",
          "latest_version": "5.19.0",
          "source_url": "https://registry.terraform.io/v1/modules/terraform-aws-modules/vpc/aws",
          "status": "Outdated"
        }
      ]
    }
  ]
}

Use Cases

Infrastructure Auditing

Create an inventory to audit your infrastructure components:

thothctl inventory iac --check-versions --report-type all

Version Management

Identify outdated modules and update them:

# First create an inventory with version checking
thothctl inventory iac --check-versions --report-type json

# Then update modules to latest versions
thothctl inventory iac --inventory-action update --inventory-path ./Reports/Inventory/InventoryIaC_20250602_121227.json

Documentation

Generate documentation about your infrastructure:

thothctl inventory iac --report-type html

Disaster Recovery

Create regular inventories for disaster recovery purposes:

thothctl inventory iac --report-type all --inventory-path ./backups/$(date +%Y-%m-%d)

Examples

Basic Inventory Creation

thothctl inventory iac

Terragrunt Project Inventory

thothctl inventory iac --framework-type terragrunt

Comprehensive Inventory with Version Checking

thothctl inventory iac --check-versions --report-type all --inventory-path ./docs/inventory

Update Infrastructure to Latest Versions

# First create an inventory with version checking
thothctl inventory iac --check-versions --report-type json

# Then update modules to latest versions
thothctl inventory iac --inventory-action update --inventory-path ./Reports/Inventory/InventoryIaC_20250602_121227.json

Restore Infrastructure from Backup

thothctl inventory iac --inventory-action restore --inventory-path ./backups/2023-01-01/inventory.json

Best Practices

Regular Inventories: Create inventories regularly to track changes over time
Version Checking: Use --check-versions to identify outdated modules
Multiple Report Types: Use --report-type all to generate both HTML and JSON reports
Backup Inventories: Store inventories in a version-controlled location
CI/CD Integration: Add inventory creation to your CI/CD pipeline
Framework Specification: Explicitly specify the framework type for more accurate results

Troubleshooting

Common Issues

No Components Found

Warning: No components found in the specified directory.

Solution: Ensure you're running the command in a directory containing Terraform (.tf) or Terragrunt (terragrunt.hcl) files.

Version Checking Failures

Error: Failed to check versions for module xyz

Solution: Ensure you have internet connectivity and the module source is accessible.

Report Generation Failures

Error: Failed to generate HTML report

Solution: Ensure you have write permissions to the output directory.

Debugging

For more detailed logs, run ThothCTL with the --debug flag:

thothctl --debug inventory iac

Related Commands

thothctl check iac: Check IaC components against best practices
thothctl scan: Scan infrastructure code for security issues

Uh oh!

FilesExpand file tree

inventory_command.md

Latest commit

History