Preview Rule Diffs

The Preview API shows you exactly what Operational Rules will change in a module before you download it. You get a unified diff for every file that a rule modifies, along with the full rules manifest — without downloading the transformed module.

What the Preview API will do

1. Accept a module, version, framework, and rule set
2. Run the rule transformations in a dry-run mode
3. Return a diff for every modified file, plus the rules manifest
4. No module is cached or stored — this is a read-only preview

This lets platform teams and developers inspect rule changes before they reach a terraform init. It is particularly useful when enabling a new rule for your org, or when reviewing what a per-request override will produce.

Expected request format

curl -X POST \
  -H "Authorization: Bearer $CTF_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.compliance.tf/v1/rules/preview \
  -d '{
    "module": "terraform-aws-modules/s3-bucket/aws",
    "version": "5.0.0",
    "framework": "soc2",
    "rules": [
      { "id": "prevent_destroy_data" },
      { "id": "ignore_tag_changes" }
    ]
  }'

Expected response format

{
  "module": "terraform-aws-modules/s3-bucket/aws",
  "version": "5.0.0",
  "framework": "soc2",
  "diffs": [
    {
      "file": "main.tf",
      "hunks": [
        {
          "header": "@@ -45,6 +45,10 @@",
          "lines": [
            "   bucket = var.bucket",
            " ",
            "   tags = var.tags",
            "+",
            "+  lifecycle {",
            "+    prevent_destroy = true",
            "+    ignore_changes  = [tags, tags_all]",
            "+  }",
            " }"
          ]
        }
      ]
    }
  ],
  "rules_manifest": {
    "ctf_version": "1.0",
    "rules_applied": [
      {
        "name": "Prevent Destroy Data",
        "id": "prevent_destroy_data",
        "resources_affected": ["aws_s3_bucket.this"],
        "changes": ["prevent_destroy = true"]
      },
      {
        "name": "Ignore Tag Changes",
        "id": "ignore_tag_changes",
        "resources_affected": ["aws_s3_bucket.this", "aws_s3_bucket_logging.this"],
        "changes": ["ignore_changes = [tags, tags_all]"]
      }
    ],
    "rules_hash": "a1b2c3d4e5f6a7b8"
  }
}

How to read the diff output

The diffs array contains one entry per modified file. Each entry includes:

• file — the path of the modified file within the module
• hunks — one or more diff hunks in unified diff format

Lines prefixed with + are additions. Lines prefixed with - are removals. Lines without a prefix are context (unchanged).

If no files are modified (e.g., the module does not contain any resources matching the rule's targets), the diffs array will be empty and the rules manifest will show empty resources_affected lists.

Understanding the rules manifest

The rules_manifest in the preview response is identical to the .ctf-rules-manifest.json file that would be included in the downloaded module. Use it to verify:

• Which rules ran and which resources they affected
• The rules_hash — compare this across environments to confirm identical rulesets
• Whether any rules had no effect (empty resources_affected)

Availability

The Preview API will be available on paid tiers. It is a read-only operation and does not affect cached modules or org configuration.