io.github.bmoldo/terraback

Scan and generate Terraform HCL + import blocks for a batch of resources. Everything is scanned into an isolated staging area first; nothing is written to output_dir unless the batch is within your license's resource cap. Nothing is imported into Terraform state by this tool - it only generates code. License cap: on the Community tier, a single call is capped at 25 total resources (after tag_filters are applied, before exclude_managed is applied). If the scope has more than that, this tool returns {"error": "resource_cap_exceeded", "total", "cap", "counts_by_type", "hint"} and writes nothing - narrow the request with `types` or `tag_filters`, or upgrade to Professional/Enterprise for unlimited batch size. exclude_managed behavior (v1): when True and state_files are given, resources whose scanned id/ARN already appears in one of the local state files are fully excluded from the generated output (not merely flagged). Requires state_files - if omitted, a warning is returned and nothing is excluded. v1 supports LOCAL state file paths only. Args: provider: Cloud provider - "aws", "azure", or "gcp". scope: AWS = region, Azure = subscription ID, GCP = project ID. types: Optional list of resource type names to restrict the batch to. tag_filters: Optional dict of tag key/value pairs a resource must match on (all pairs required). output_dir: Directory to write the generated Terraform into. exclude_managed: Drop resources already present in state_files. state_files: Paths to local Terraform state JSON files. profile: AWS named profile to use (ignored for azure/gcp). Returns: On success: {"output_dir", "files": [...], "resource_counts": {...}, "total", "warnings": [...], "errors": [...]}.

Generate Terraform HCL and an import block for exactly one resource. Scans just the requested resource type in the given scope, locates the resource matching resource_id, and writes a single .tf file plus a matching import JSON entry into output_dir. Nothing is imported into Terraform state by this tool - it only generates code; import is a separate, explicit step outside this MCP interface. Args: provider: Cloud provider - "aws", "azure", or "gcp". scope: AWS = region, Azure = subscription ID, GCP = project ID. type: Resource type name, bare (e.g. "ec2") or full registry key (e.g. "aws_ec2"). Call list_supported_resources to see valid types. resource_id: The cloud-provider id (or ARN) of the resource to codify. output_dir: Directory to write the generated Terraform into. profile: AWS named profile to use (ignored for azure/gcp). Returns: {"hcl": "<generated .tf file contents>", "import_block": {...}, "files": [<tf file path>, <import json path>], "dependencies": [...]} Raises: If the type is unknown or the resource_id is not found, an error result is returned listing up to 20 available ids for that type/scope so the caller can self-correct.

Diff a live cloud inventory against local Terraform state to find unmanaged resources. Read-only: runs a scan_infrastructure-equivalent scan and compares resource ids/ARNs against what your Terraform state already tracks. Nothing is written to state and nothing is imported. v1 limitation: state_files must be LOCAL file paths (e.g. a checked-out `terraform.tfstate`, or the output of `terraform state pull > state.json`). Remote backends (S3, azurerm, GCS, Terraform Cloud/Enterprise) are not read directly - pull the state to a local file first. Args: provider: Cloud provider - "aws", "azure", or "gcp". scope: AWS = region, Azure = subscription ID, GCP = project ID. state_files: Paths to one or more local Terraform state JSON files. types: Optional list of resource type names to restrict the scan to. workdir: Directory for scratch scan output and the inventory file. Returns: {"unmanaged": {"<type>": [resource, ...], ...}, "managed_count": N, "unmanaged_count": N, "state_files_read": [...], "warnings": [...]}

List resource types terraback can scan/codify, grouped by provider. Read-only and does not touch any cloud provider - this only reports what terraback's scan registry supports. Args: provider: Restrict the listing to one provider - "aws", "azure", or "gcp". Omit to list all three. Returns: {"providers": {"aws": [{"type": "aws_ec2", "tier": "community"}, ...], "azure": [...], "gcp": [...]}, "counts": {"aws": N, "azure": N, "gcp": N, "total": N}}. "tier" is "community", "professional", or "enterprise" - types above your license tier will fail if scanned.

Run a read-only inventory scan of live cloud infrastructure. This is a discovery tool: it enumerates what currently exists in the given scope. It never writes Terraform files, never touches Terraform state, and never imports anything - it only reads from the cloud provider's API. Args: provider: Cloud provider - "aws", "azure", or "gcp". scope: The scan boundary. For AWS this is a region (e.g. "us-east-1"). For Azure this is a subscription ID. For GCP this is a project ID. types: Optional list of resource type names to restrict the scan to, e.g. ["ec2", "aws_vpc"]. Both bare names and full registry keys are accepted. Omit to scan every resource type registered for the provider (call list_supported_resources first to see the full list). tag_filters: Optional dict of tag key/value pairs a resource must match on (all pairs required). Resources with no discoverable tags are excluded whenever this is supplied. workdir: Directory to use for scratch scan output and the full inventory JSON file. Defaults to a directory under the system temp directory if omitted. profile: AWS named profile to use (ignored for azure/gcp). Returns: A dict with "summary" (total count and counts by resource type), "inventory_file" (path to the full JSON inventory on disk - always written, useful when the inventory is large), "resources" (the full list of {type, id, name, provider, scope} entries, only included inline when there are 200 or fewer - for larger inventories, read inventory_file instead), and "errors" (per resource-type scan failures, if any - a failing scanner does not abort the rest of the scan).

Run a read-only `terraform plan` against a generated directory and report drift. Never applies, imports, or otherwise mutates Terraform state - this only runs `terraform init` (if needed) and `terraform plan`. Requires Terraform >= 1.5 (import block support) installed and on PATH. Args: terraform_dir: Directory containing the generated .tf files. Returns: On success: {"drift": "none"|"drift_detected"|"plan_failed", "summary": {"imports", "adds", "changes", "destroys"}, "add_resources": [...], "change_resources": [...], "destroy_resources": [...]}. "drift" is "none" when adds == changes == destroys == 0 - pending imports alone are expected and are not drift. On a missing/too-old Terraform binary: {"error", "detail"}.