Tfpolicy Author

Note: This skill supersedes sentinel-to-tfpolicy. All Sentinel conversion knowledge is now consolidated here to ensure consistent behaviour when generating policies from Sentinel sources.

Use When

• The user describes an enforcement rule and wants a .policy.hcl file (“block public RDS”, “require encryption”, “deny instance types outside an allowlist”).
• The user has a Sentinel .sentinel file (or snippet) and wants the Terraform Policy equivalent.
• The user is migrating a Sentinel policy library to tfpolicy and needs per-policy assessment.
• The user is writing a new resource_policy, module_policy, or provider_policy block.
• The user is asking about tfpolicy language features — filter, locals, enforce, input, operations, prior_attrs, core::* functions, list comprehensions, version constraints, time/date functions.
• The user is asking how to structure a policy that depends on related resources via core::getresources() or core::getdatasource().
• The user is comparing Sentinel and tfpolicy capabilities (“can I express X in tfpolicy?”).

Do not use this skill when:

• The user is writing or debugging a .policytest.hcl test file — use tfpolicy-test.

Capabilities

1. Write Policies from User Intent

Turn natural-language requirements into resource_policy, module_policy, or provider_policy blocks with appropriate filters, locals, enforce blocks, and remediation-focused error messages.

2. Convert Sentinel Policies to Terraform Policy

Translate Sentinel constructs into tfpolicy equivalents, flag non-convertible patterns with practical alternatives, produce idiomatic .policy.hcl from existing Sentinel sources, and apply a quality label to each conversion.

3. Apply Operation Scoping Correctly

Use operations = ["create", "update", "delete"] and prior_attrs.<name> to scope policies to the right plan actions and read pre-change state when relevant.

4. Parameterize with input Blocks

Replace hardcoded allowlists, version constraints, and thresholds with input blocks so policy sets can override values per environment.

5. Structure Cross-Resource Checks Safely

Use core::getresources() at the top level for plan-time joins, with value-based filters when the filter is a known literal or existing ID. Use inline core::getresources() inside resource_policy for apply-time parent+child lookups, when the filter depends on the current resource’s own attribute (e.g. {bucket = attrs.id}). Consult the decision table (line 232) to choose the correct pattern; both top-level and inline are first-class options for their respective scenarios. Understand when cross-references will be unresolved at plan time.

6. Surface Runtime Pitfalls Up Front

Steer the user away from documented runtime hazards — meta.address is undefined in resource_policy, core::try() defaults can silently mask non-compliant resources, sets must be converted to lists for indexing, multi-line boolean expressions break the parser, etc.

Knowledge Base

Policy Types

Required policy.required_providers Block

Every .policy.hcl file must declare a top-level policy { required_providers { ... } } block. tfpolicy validate uses this block to resolve provider schemas for schema-aware validation, and validation fails when the block is omitted.

Use the same top-level policy scaffold shown in the Core Structure and Worked Example sections; only the provider source/version values should vary by policy.

Rules and limitations:

• required_providers is mandatory for .policy.hcl validation.
• Validation is best effort for version ranges. When a range is declared, validation evaluates provider schemas at the lower and upper bounds of the range.
• Wildcard targets such as resource_policy "*" are not schema-validated because they may match multiple resource types.
• required_providers declares provider source and version constraints for validation. This is distinct from meta.version in provider_policy, which exposes the resolved provider version during policy evaluation.

Core Structure

Available Attribute Surfaces

Operation Scoping and prior_attrs

Rules:

• operations = ["create", "update"] — fires on create/update, skips destroy.
• operations = ["delete"] — fires only on destroy; prior_attrs holds pre-change state.
• operations = ["update"] — fires only on updates; prior_attrs available.
• Default (no operations) = create and update (never destroy).
• prior_attrs is only accessible when "create" is NOT in operations.

input Blocks — Parameterization

Policy sets can override input defaults without editing the policy file. Use input for: allowlists, blocklists, version constraints, numeric thresholds — values an operator may need to tune per environment.

Rule — input vs hardcoded locals:

• Use input {} only for operator-tunable values: allowlists, blocklists, thresholds, time windows. If a value varies per environment or policy set, it belongs in input.
• Use locals or inline literals for invariant enforcement constants — values that are part of the policy logic itself and should NOT be overridden (e.g. a fixed list of well-known dangerous ports defined by a security standard, a required protocol name).
• Do NOT promote fixed enforcement constants to input unless the requirement explicitly says they are configurable.

core:: Functions — Common Idioms

• Null safety: core::try(attrs.field, default) — single layer; don’t nest. 🔴 MANDATORY: always use the two-step pattern below when the attribute may be explicitly null.

• Membership: core::contains(list, value) — for lists. For string substring use core::contains_substring.

• Strings: core::startswith, core::endswith, core::contains_substring, core::regex (throws on no match — wrap in core::try), core::split(separator, string) (use with core::parseint() for numeric decomposition — see verified-syntax.md Section 2 for full examples). ❌ Never use + for string concatenation — + is numeric addition only; using it with strings throws Error: Unsuitable value for left operand: a number is required. ✅ Use "${local.var}" string interpolation instead: e.g. "table/${local.table_name}" not "table/" + local.table_name.

• Aggregates: core::length(list_or_map).❌ core::alltrue() and core::anytrue() DO NOT EXIST in tfpolicy runtime — use core::length() with list comprehension: core::length([for b in list : b if b]) > 0 instead of anytrue, core::length([for b in list : b if !b]) == 0 instead of alltrue.

• Ranges: core::range(limit) → [0, 1, …, limit-1]; core::range(lower, upper) → [lower, lower+1, …, upper-1]; core::range(lower, upper, step) → step-incremented list from lower up to (but not including) upper. Works with hardcoded integer literals. ⚠️ With dynamic attrs.* integer values (e.g. attrs.from_port, attrs.to_port) core::range() silently returns an empty list in the policytest framework — prefer the count approach for port-range policies (see verified-syntax.md Mistake 23).

• Time: core::timestamp(), core::formatdate("EEEE", core::timestamp()) (weekday, UTC), core::parseint(core::formatdate("HH", core::timestamp()), 10) (hour, UTC).

• Semver: core::semverconstraint(version, "~> 4.67.0") — supports =, >=, <, ~>, range, !=. Always wrap in core::try(..., false) to handle non-semver or unparseable version strings gracefully. ⚠️ Prefer this over core::split + core::parseint for all version range checks converted from Sentinel string comparisons — manual integer parsing fails silently for non-numeric version suffixes and null/empty inputs.

  🔴 NEVER place core::semverconstraint directly in a filter = expression. Even with != null and != "" guards in the same expression, semverconstraint is evaluated regardless of short-circuit ordering in the filter context and throws a parse error when the version string is malformed (e.g. a non-semver string like "x.y") or null/empty. Always move it into locals and wrap with core::try(..., false):

  hclCopy

  # ❌ Wrong — crashes when version string is non-semver, null, or empty:
  filter = core::try(attrs.version, null) != null
  
  
  
  
  
  
  
  
  
  
  
  
  

• Null safety — two-step pattern (MANDATORY for any attribute that may be explicitly null): core::try(attrs.field, default) triggers the fallback only when the attribute access throws an error (key absent). When an attribute is explicitly set to null, core::try returns null — not the default. This is a silent pitfall: core::length(null) crashes with Invalid value for "collection" parameter; null == false evaluates as null (not true), causing enforce to trigger unexpectedly.

  Always use the explicit two-step pattern:

  hclCopy

  # Collection attribute (list/map) — safe pattern:
  field_raw = core::try(attrs.field, null)
  field     = local.field_raw != null ? local.field_raw :
  
  
  
  
  
  

• JSON: core::jsondecode(string) — parses a JSON string into an object/list. core::jsonencode(value) — encodes a value as a JSON string. ❌ json::unmarshal does not exist — use core::jsondecode instead.

• Nested block attribute schema — object vs list: Terraform provider schemas define nested blocks as either a list of objects ([{ ... }]) or a single object ({ ... }). Always check the provider schema before accessing nested attributes:

  • List block (e.g. encryption_config = [{ provider = [{ key_arn = "..." }] }]): access via index attrs.encryption_config[0].provider[0].key_arn. Use core::try(attrs.field, []) and field[0].subattr.
  • Object block (e.g. redirect = { port = "443", protocol = "HTTPS" }): access directly attrs.redirect.port. Use core::try(attrs.redirect.port, "").
  • ❌ Never call core::length() on an object — core::length requires a list, map, or tuple. Calling core::length(attrs.redirect) when redirect is an object crashes with collection must be a list, a map or a tuple. To check presence of an object block, use core::try(attrs.redirect, null) != null instead.
  • ❌ Never iterate over an object block with a for expression. for r in core::try(attrs.block, []) — when attrs.block is an object, this iterates over the object’s scalar values, not the object as an element. core::try(r.sub_attr, "") on a string silently returns "". Use direct attribute access instead: core::try(attrs.block.sub_attr, "").
  • When Sentinel mocks use redirect = { ... } (object), the TFPolicy test mock and policy must treat it as an object. When Sentinel mocks use redirect = [{ ... }] (list), use list indexing. Mismatching the shape causes either runtime crashes or silent wrong results.

IAM Policy Checks

When enforcing IAM content rules (e.g. “no admin *:* allowed”, “no wildcard actions”), you MUST cover all 4 inline policy resource types — not just aws_iam_policy.

🔴 Always write 4 resource_policy blocks for IAM content enforcement:

Rule: A policy that only checks aws_iam_policy misses inline policies on roles/users/groups. An admin could bypass it by using aws_iam_role_policy instead of aws_iam_policy.

Note on aws_iam_policy_document: This resource type requires careful distinction between two different use cases:

• As a Terraform data block (the common case in real Terraform configurations) — data_policy does not exist in tfpolicy (Mistake 31). Do NOT write data_policy "aws_iam_policy_document". In this scenario, the policy document content is consumed by one of the 4 inline/managed policy resource types above, and enforcement should target those resource types.
• As a resource in .policytest.hcl mocks and when the Sentinel source reads it via tfstate/v2 — resource_policy "aws_iam_policy_document" is valid and directly targets the document’s statement attribute (lowercase actions, not Action). When a Sentinel policy reads aws_iam_policy_document from tfstate, the correct TFPolicy conversion is resource_policy "aws_iam_policy_document" — do NOT substitute inline/managed policy resource types.

Decision rule: Check the Sentinel import statement. If the Sentinel uses tfstate/v2 to read aws_iam_policy_document resources, convert to resource_policy "aws_iam_policy_document". If the Sentinel reads the consuming resource (aws_iam_role_policy, etc.), target those 4 types instead.

Cross-Resource Lookups

🛑 Self-check — run this BEFORE writing any resource_policy involving a companion/child resource:

“What is the enforcement goal?”

• “Every existing instance of <child_type> must have correct attributes” (e.g., “every aws_lb_listener must use HTTPS”) → anchor resource_policy directly on the child type
• “Every parent must have at least one compliant child” (e.g., “every S3 bucket must have a public_access_block with all four flags set”) → anchor resource_policy on the parent; a child-only policy silently misses parents with no child in the plan

Decision table — choose the correct pattern first:

⚠️ Critical: Never write a resource_policy "child_type" to enforce “every parent must have a child” — if the child resource is absent entirely, the policy never fires for that parent and the violation is silently missed.

🔴 Named companion resources — ALWAYS use the parent as resource_policy anchor when the goal is presence enforcement:

The following Terraform resource types are companion-only — a parent resource can exist in a plan without them. NEVER anchor a standalone resource_policy on these types when checking for their presence:

This pattern applies to all resource families, not just S3. Non-S3 examples: when checking “every VPC has a flow log” → anchor on aws_vpc with inline core::getresources("aws_flow_log", {vpc_id = attrs.id}); when checking “every LB has at least one compliant listener” → anchor on aws_lb with inline core::getresources("aws_lb_listener", {load_balancer_arn = attrs.arn}).

Why this matters: Even if the Sentinel source iterates over the companion type, TFPolicy must anchor on the parent. A Terraform plan can declare an aws_s3_bucket with NO companion resource — anchoring on the companion silently misses that bucket entirely.

⚠️ Parent-anchor means parent-ONLY: Once the decision table says “parent resource” is the anchor, generate resource_policy blocks exclusively on the parent type. Do NOT also generate standalone resource_policy blocks for companion types alongside the parent blocks. Adding companion blocks in parallel:

• still silently misses parents that have no companion
• double-reports violations

All enforcement logic — including every companion check — must live inside the parent resource_policy block, using inline or top-level lookups.

Plan-time pattern — use core::getresources() at the top level only when the filter value is a known constant (not derived from attrs.*). When the filter depends on the current resource’s own attribute, use the inline pattern below instead. ❌ Top-level {} (empty filter) + for-loop or lookup map filtered by attrs.* inside resource_policy is the prohibited anti-pattern — see verified-syntax.md Mistake 13 for both variants.

⚠️ Exception — “companion absence is itself a violation”: When the goal is to enforce that a companion resource exists AND has matching attributes (e.g. a parent resource must have a linked companion with a specific qualifying attribute set), the inline filter pattern produces false negatives: if the companion is absent or has a mismatching linking key, core::getresources() returns [], and !has_companion is true → a condition like !has_companion || check_attr == "VALUE" incorrectly passes. Use the top-level collect-then-filter pattern instead:

This pattern correctly detects:

• Companion absent entirely → has_qualifying = false → filter = false → parent skipped ✓
• Companion present but with no qualifying attribute → qualifying_companions = [] → has_qualifying = false → parent skipped ✓
• Companion with wrong linking_attr value → is_linked = false → is_compliant = false → violation ✓
• Companion with correct linking and correct check_attr → is_compliant = true → passes ✓

⚠️ Choose filter scope carefully: filter = local.has_qualifying (qualifying companions only) skips all parents when no qualifying companions exist — this matches a Sentinel that returns early when no qualifying companions are found. If the Sentinel does NOT skip when non-qualifying companions exist (e.g. it evaluates parents even when only ALB/NLB attachments are present), use filter = core::length(local.all_companions) > 0 instead. With this broader filter, unlinked parents (is_linked = false) are evaluated and correctly fail is_linked && check_attr == VALUE.

🔴 Condition polarity rule: When using the top-level collect-then-filter pattern, always use a positive condition (is_linked && check_attr == VALUE), not a negative condition (!is_linked || check_attr == VALUE). The negative form silently passes any parent that is not linked — which is the opposite of the intended enforcement. With the positive form: unlinked parent → is_linked = false → is_compliant = false → violation (correct). With the negative form: unlinked parent → !false || any = true → is_compliant = true → passes (incorrect).

Apply-time pattern — when the filter value is the current resource’s own attribute (e.g. bucket = attrs.id, or event_bus_name = attrs.name), use an inline core::getresources() call with the direct filter inside resource_policy. The filter cannot resolve at plan time (the attribute value is unknown until apply), but fully resolves once the resource is provisioned. The linking attribute may reference attrs.id, attrs.arn, or attrs.name — check the child resource’s Terraform Registry docs to determine which one.

S3 cross-resource note: Always use attrs.id (not attrs.bucket) when filtering S3 child resources such as aws_s3_bucket_public_access_block, aws_s3_bucket_acl, aws_s3_bucket_server_side_encryption_configuration, and aws_s3_bucket_policy. Terraform providers set the child resource’s linking attribute (bucket) to the parent bucket’s .id. Using attrs.id ensures the filter matches the actual value stored in the child resource’s plan.

Error Message Rules

• ✅ Static strings: "S3 buckets must enable versioning."
• ✅ Safe interpolation: "Instance type '${attrs.instance_type}' is not allowed."
• ❌ Never interpolate ${meta.address} — it is UNDEFINED in resource_policy and crashes at runtime. tfpolicy test will NOT catch this; only a real terraform plan will.
• Use error_message for all enforceable violations (condition can be false).
• Use info_message only in non-convertible stub blocks where condition = true and no real enforcement is possible. Never use info_message in a block that can actually fail a resource.

Comment Conventions — # LIMITATION: vs # NOTE:

These two markers have distinct meanings — do not interchange them:

• # LIMITATION: — tfpolicy cannot fully express or enforce the requirement. Part of the original Sentinel logic had to be omitted or approximated. Always accompanies a Simplify or Not convertible quality label.
  • Example: “LIMITATION: The bucket policy IAM document check is non-convertible — tfpolicy does not expose reference metadata.”
• # NOTE: — The enforcement is complete but has a runtime caveat that does not reduce coverage.
  • Example: “NOTE: This policy contains a cross-resource reference that will not resolve during plan time, but will run successfully during apply time.”

Output Structure Rules — Consistency-Critical

These rules eliminate the most common sources of non-deterministic output between runs:

Rule 1 — One resource_policy block per resource type. Multiple checks on the same resource type MUST be combined into a single resource_policy block using separate locals and multiple enforce blocks. Never split checks into two resource_policy blocks for the same type.

Rule 2 — Non-convertible checks are comments, not stub blocks. When a specific check cannot be converted (reference metadata, etc.), document it as a # LIMITATION: comment inside the existing resource_policy block — do NOT create a separate resource_policy block of the same type as a stub. A dedicated stub block (with condition = true) is only appropriate when the entire policy has no convertible checks at all.

Rule 3 — Per-resource enforcement for all checks. Do NOT aggregate across all resources of a type at the plan level (e.g. “at least one trail in the whole plan is compliant = pass all”). Each resource_policy must evaluate each individual resource independently. tfpolicy’s evaluation model is per-resource — plan-level aggregation via top-level core::getresources() to pass/fail based on a count across all resources is not idiomatic and produces non-deterministic results.

Sentinel → Terraform Policy Conversion

Use this section when the input is an existing Sentinel .sentinel file. Follow Steps 1–5 below; apply the authoring guidance above when generating the policy HCL.

Sentinel → Terraform Policy construct mapping

When converting Sentinel summary {} output or print() statements, do not reproduce address-listing behavior. Terraform Policy diagnostics already identify the failing resource — prefer remediation-focused messages instead.

Sentinel features that ARE convertible

1. Time-based rules — core::timestamp() + core::formatdate() + core::parseint() cover Sentinel’s time import. All values are UTC; document that assumption in policy comments.
2. param blocks — direct equivalent: input blocks with type and default.
3. rc.change.before for update/delete — prior_attrs is available when operations does NOT include "create".
4. Integer range checks — Sentinel policies that check whether all ports within [from_port, to_port] are authorized CAN be converted. Use the count approach: filter authorized_ports to those within the range and compare the count to to_port - from_port + 1. Do not use core::range() with dynamic attrs.* values. See verified-syntax.md Mistake 23.
5. tfconfig/v2 reference count — each resource reference is stored twice in .references (once as resource.name, once as resource.name.id). When simplifying a reference-count check to a direct core::length(attrs.attribute) check, halve the threshold: references > 2 → core::length(attrs.attribute) >= 2.

Plan-Time vs Apply-Time Policies

Terraform Policy can enforce controls at plan time (before terraform apply) or apply time (during terraform apply). Most policies are plan-time, but cross-resource lookups that depend on newly-created resource IDs only fully resolve at apply time.

When a Sentinel policy uses cross-resource references with a value-based filter from a newly-created resource:

• Generate the policy using an inline core::getresources() call with the direct filter inside resource_policy.
• Add this note in the conversion report (not a limitation label): “This policy contains a cross-resource reference that will not resolve during plan time, but the policy will run successfully during apply time.”
• Do not label this as Simplify or Not convertible — it is a valid Good conversion.

For cross-resource patterns, apply the registry check (Steps A and B) described in “Cross-Resource Lookups” above. The registry check fully determines the policy structure, regardless of whether the Sentinel’s violations iterated the parent or the child type. Dependent child resource types must never have a standalone resource_policy block.

Cannot Convert (Explain the Alternative)

1. Mocking/testing infrastructure (import "tfconfig-functions") — tfpolicy uses .policytest.hcl. See the tfpolicy-test skill.
2. Custom Sentinel imports — limited plugin support; use HTTP plugins or native functions if available.
3. Sentinel simulator / built-in test framework — replace with .policytest.hcl test files.
4. Cross-workspace data access — tfpolicy evaluates a single plan. Use workspace tags (meta.tfe_workspace.tags) or external plugins.
5. print() / debug statements — no debug output mechanism; rely on concise error_message / info_message text only when it adds remediation context.
6. Stateful logic across evaluations — policies are stateless; use external systems via plugins if state is required.
7. rc.change.before outside delete/update — for first-time creates there is no pre-state.
8. Cross-resource reference navigation via reference metadata (res.config.attribute["references"], res.config.to) — tfpolicy does not expose which Terraform resource a value points to. When the Sentinel policy uses the resolved value of an attribute (not the reference path itself), convert using core::getresources() with a value-based filter — see “Plan-Time vs Apply-Time Policies” above.
9. Data source content inspection by address — core::getdatasource() requires filter attributes and cannot query by Terraform address.
10. Complex resource-graph traversal via reference metadata — cannot traverse the Terraform resource graph by reference (e.g. “find all subnets that reference this VPC”). Only resolved attribute values are available. If the Sentinel policy traverses by resolved attribute value (e.g. bucket = attrs.id), convert using core::getresources() with a value-based filter and mark as an apply-time policy — see “Plan-Time vs Apply-Time Policies” above.

⚠️ Partial reference dependence — do not skip the whole policy. Items 8 and 10 apply to the specific check that uses reference metadata, not the entire policy. If only some checks in a Sentinel policy rely on res.config.attribute["references"] or graph traversal, convert the remaining checks as normal, apply the Simplify label to the overall policy, and document each skipped check in the report with: “This check was omitted — tfpolicy does not expose reference metadata (res.config.attribute["references"]).” Only label the entire policy as Not convertible if its core enforcement logic is wholly dependent on reference metadata with no convertible remainder.

❌ Do not approximate reference-metadata checks with cross-resource JSON value matching. A common workaround is to retrieve all instances of a related resource via core::getresources() and compare their serialized attribute values (e.g. attrs.policy == doc.json) as a proxy for “this resource references that data source.” This is not a faithful conversion — it produces false negatives when the referenced resource is already deployed and absent from the current plan, and enforces a different semantic (value equality) than the original (structural reference). When the only check IS reference metadata, generate a stub policy instead:

hclCopy

# <policy_name> — Non-Convertible (Reference Metadata)
resource_policy "<resource_type>" "<policy_name>_stub" {
  enforce {
    condition     = true
    info_message  = "Automated enforcement not available: this policy requires reference metadata inspection which tfpolicy does not support. Manual compliance review required."
  }
}

⚠️ Partial exception — direct content inspection via the parent bucket. The cross-resource approximation prohibition applies to comparing JSON across resources (e.g. fetching all aws_iam_policy_document outputs and matching against a bucket policy). It does not prohibit inspecting a bucket’s own policy content. When the Sentinel reference-metadata check is really enforcing content (e.g. “the bucket policy must not grant public read access”), convert it by anchoring on resource_policy "aws_s3_bucket", fetching the child aws_s3_bucket_policy via core::getresources("aws_s3_bucket_policy", { bucket = attrs.id }), and inspecting its policy attribute via core::jsondecode() inside the parent block. This follows the standard dependent-child pattern — aws_s3_bucket_policy always requires a parent bucket. Label the overall policy Simplify (because the reference-path check is omitted) and add a # NOTE: that the content-based check achieves a similar security outcome.

hclCopy

# ✅ Content-based alternative to reference-metadata check on bucket policies
# NOTE: This policy contains a cross-resource reference that will not resolve during plan time,
# but the policy will run successfully during apply time.
resource_policy "aws_s3_bucket" "no_public_read_policy" {
  locals {
    bucket_policy       = core::getresources("aws_s3_bucket_policy", { bucket = attrs.id })
    policy_doc          = core::try(core::jsondecode(core::try(local.bucket_policy[0].policy, "{}")), { Statement = [] })
    statements_enriched = [for s in core::try(local.policy_doc.Statement, []) : { effect = core::lower(core::try(s.Effect, "Allow")), action = core::try(s.Action, []), principal_str = core::try(s.Principal, ""), principal_aws = core::try(core::try(s.Principal, {}).
    public_read_stmts   = [for s in local.statements_enriched : s if s.effect == "allow" && (core::contains(s.action, "s3:GetObject") || core::contains(s.action, "s3:*") || core::contains(s.action, "*")) && (s.principal_str 
  }
  enforce {
    condition     = core::length(local.public_read_stmts) == 0
    error_message = "S3 bucket policy must not grant public read access (Principal: * with s3:GetObject or s3:*)."
  }
}

Conversion quality labels

• Perfect — Same enforcement intent and behavior expressed directly in tfpolicy with no known semantic gap.
• Good — Preserves the important enforcement outcome using idiomatic tfpolicy structure (not a one-to-one translation).
• Simplify — Only part of the original Sentinel behavior can be reproduced; document the missing checks explicitly.
• Not convertible — tfpolicy lacks the runtime data or language features required for a safe translation.

Conversion Strategy

Steps to Convert a Sentinel Policy

Step 1 — Parse the Sentinel Structure

Identify imports (tfplan, tfconfig, tfstate, custom), filter logic and resource selection, main and sub-rules, and enforcement level (advisory vs mandatory). Ask: What resources are being checked? Which attributes are validated? Does the policy depend on before/after diff? Are there cross-resource dependencies? Are data sources inspected? Does it rely on reference metadata or graph traversal?

Identify the enforcement target and the parent type: For any policy involving cross-resource dependencies, first perform the registry check (Steps A and B in “Cross-Resource Lookups” above) to identify which resource types are dependent children and which are parent types. Then use the Sentinel’s violations expression to confirm the parent type — this is the type your resource_policy targets. Write resource_policy on the parent type. Every dependent child type is accessed exclusively via core::getresources() inside that parent block; all conditions on child resources are evaluated there, and all violations are reported on the parent. Do not write a standalone resource_policy on any resource type that the registry identifies as a dependent child — this rule holds regardless of whether the Sentinel’s violations iterated the child or the parent, and regardless of whether the check is about a missing child or a misconfigured one.

Cross-resource policies — use the Terraform Registry to identify the parent, linking attribute, and filter value. For any child resource type involved in a cross-resource lookup, fetch its documentation at https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/website/docs/r/{resource_name_without_aws_prefix}.html.markdown. Look for a (Required) argument referencing a parent resource in “Argument Reference” and confirm with the usage examples (.id vs .arn). The required argument name is the linking attribute; use the corresponding attrs.id or attrs.arn in the core::getresources() filter. This applies to all resource families — not just S3.

Do not over-constrain the enforcement condition beyond the Sentinel intent. When the Sentinel checks “at least one item in a collection satisfies condition X”, the correct tfpolicy translation is core::length([for item in local.items : item if <condition>]) > 0. Do NOT translate this to “every item must satisfy X” (i.e. core::length([for item in local.items : item if !<condition>]) == 0) unless the Sentinel explicitly enforces ALL items. Over-constraining the condition creates false violations for valid configurations that the Sentinel would pass.

Distinguish enforcement intent from Sentinel implementation detail. Sentinel code often accesses a collection element by index (e.g. origins[0]) as a traversal shortcut rather than an intentional “only check the first item” rule. Before encoding an index access as a scope restriction, ask:

• Is the indexed access repeated for all resources in a filter loop? (If so, it is a loop artifact, not a one-item intent.)
• Does the policy name or comment indicate intent that applies to “all” items?
• Would checking only the first item leave a real security gap?
• Is this collection a structurally singleton block in the provider schema (e.g. max_items = 1) — in which case [0] is intentional?

When the answer to any of the first three questions is “yes” and the fourth is “no”, convert the check to iterate all items in the collection, not just [0]. Document the interpretation in the requirements as: “Sentinel source accesses collection[0]; interpreted as checking all items to preserve full enforcement intent.”

Step 2 — Assess Convertibility

Check for non-convertible patterns above. Document what cannot be converted and assign a quality label.

Step 3 — Map to tfpolicy Constructs

Use the mapping table above. In practice, focus on (in order): matching resource scope, translating attribute access and null handling, replacing collection helpers with list comprehensions, and splitting compound logic into locals + multiple enforce blocks.

Step 4 — Generate the policy

Follow the authoring guidance in the Knowledge Base sections above. Apply the cross-resource decision table and companion-anchor rules.

Error-message rules:

• ✅ Static strings, or safe ${attrs.fieldname} interpolation.
• ❌ Never interpolate ${meta.address} — it is UNDEFINED in resource_policy and throws Error: Unsupported attribute at runtime for every evaluated resource. tfpolicy test will not catch this; only a real terraform plan --policies= run will.

Step 5 — Document the Conversion

Include the quality label, test success rate (if tests written), any limitations or simplifications made, behavioral differences from Sentinel, and references to related documentation.

• tfpolicy-author.md — guided first-policy walkthrough.
• tfpolicy-author.md — reusable patterns (attribute checks, allowlists, cross-resource enforcement, etc.).
• verified-syntax.md — verified syntax tables, runtime limitations, common-mistake corrections. Source of truth — defer to this file when this SKILL.md disagrees.

Usage Instructions — Write a New Policy from User Intent

Step 1 — Clarify requirements

• Which resources / modules / providers to target.
• The specific condition to enforce.
• Whether create, update, and/or destroy should be in scope (operations).
• Whether any value should be tunable per policy set (→ input block).
• The desired error message and whether attrs.* interpolation is helpful.

Step 2 — Design the structure

• Choose the policy type (resource / module / provider).
• Decide whether a wildcard label ("*") is appropriate.
• Plan the filter for performance and to exclude resources where the attribute is meaningfully absent. Two cases:
  • Attribute absent = resource out of scope (e.g. no acl block set at all → resource doesn’t configure ACLs → skip it): use filter = core::try(attrs.field, null) != null.
  • Attribute absent = AWS provider default applies (e.g. encrypted absent → AWS defaults to false → resource is still in scope and may violate the policy): do not filter on null. Use core::try(attrs.field, <aws_provider_default>) in the condition instead so absent resources are evaluated against the effective default.
• Move complex predicates into locals for readability.

Step 3 — Generate the policy

• Start every .policy.hcl with a top-level policy { required_providers { ... } } block.
• Use provider sources and version constraints that match the resource types referenced by the policy.
• Run tfpolicy validate after authoring to confirm the policy parses and the referenced provider schemas can be resolved.
• See Required policy.required_providers Block for validation limitations such as version-range best-effort checks and wildcard-target behavior.
• Wrap optional attributes in core::try().
• Keep each boolean expression on a single line.
• Use multiple enforce blocks when you want independent diagnostics.
• Never interpolate ${meta.address} in error_message.

Step 4 — Document the policy

• Header comment with description, resources checked, and any compliance reference.
• Note operation scope and any parameterization.

Worked Example

User request: “Ensure all S3 buckets have versioning enabled.”

Include the top-level policy { required_providers { ... } } block shown in Core Structure.

Best Practices

Policy Writing

1. Use descriptive policy names.
2. Add a comprehensive header comment with description, resources checked, and compliance references.
3. Always use core::try() for optional attributes.
4. Break down complex logic with locals.
5. Provide actionable, remediation-focused error messages.
6. Cover all variations of a resource family (e.g. AWS security groups: aws_security_group, aws_security_group_rule, aws_vpc_security_group_ingress_rule, aws_default_security_group).
7. Use filter to skip resources that don’t apply (saves work and avoids false positives).
8. Cache core::getresources() results in top-level locals when the filter is a known literal or an existing resource ID — this avoids O(N) overhead per resource. Exception: when the filter depends on the current resource’s own attribute (e.g. {bucket = attrs.id}, {event_bus_name = attrs.name}), the call cannot be pre-computed at top level because attrs is only available inside resource_policy — use the inline pattern instead (see item 15). ❌ Do NOT work around this by fetching all child resources at the top level with {} and building a lookup map — that is the same anti-pattern restructured.
9. Avoid core::getdatasource() inside resource_policy — it calls provider APIs.
10. Build lookup maps once for O(1) matching when iterating many resources.
11. Keep each boolean expression on a single line (HCL parser limitation in beta).
12. Use clear variable names (scanning_config, not sc).
13. Convert sets to lists before indexing: [for item in set : item][0].
14. Don’t use core::try() defaults to mask missing values that should fail the policy — use filter instead.
15. For cross-resource lookups where the filter value is the current resource’s own attribute: use an inline core::getresources() with the direct filter inside resource_policy. To find the correct linking attribute name and filter value, fetch the child resource’s Terraform Registry documentation at https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/website/docs/r/{resource_name_without_aws_prefix}.html.markdown and look for the (Required) or (Optional) argument that references the parent resource. Check whether the usage examples assign it .id, .arn, or .name — use attrs.id, attrs.arn, or attrs.name accordingly. ⚠️ Some linking attributes are (Optional) in the schema (e.g. event_bus_name on aws_cloudwatch_event_bus_policy defaults to the default bus) but still represent a parent-child link — treat them the same way. Always add this comment in the policy: “This policy contains a cross-resource reference that will not resolve during plan time, but the policy will run successfully during apply time.” Do not use a top-level cache + for-loop for this pattern.
16. Cross-resource enforcement — registry check determines the structure unconditionally:
    • First, verify every resource type via the Terraform Registry. For any resource type involved in a cross-resource check, fetch https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/website/docs/r/{resource_name_without_aws_prefix}.html.markdown. A resource is a dependent child if it has a (Required) argument whose description or usage examples reference another AWS resource by .id, .arn, or .name. The argument name is the linking attribute; the assignment in examples tells you whether to use attrs.id, attrs.arn, or attrs.name. The resource that the linking attribute points to is the parent type.
    • When the enforcement goal is to ensure every parent has a compliant child, the dependent child must NEVER have a standalone resource_policy block. Write the resource_policy block on the parent type. Fetch the dependent child inside the parent block via core::getresources("<child_type>", {<linking_attr> = attrs.id_or_arn_or_name}). Evaluate all attribute checks on those lookup results. Report all violations on the parent. When the goal is only to check every existing child’s own attributes, a standalone resource_policy on the child type is valid — see Self-check above.
    • Concrete examples: aws_s3_bucket_public_access_block, aws_s3_bucket_policy, aws_s3_bucket_acl (all require bucket) → never standalone for any enforcement goal; always fetched inside resource_policy "aws_s3_bucket". aws_lb_listener → standalone resource_policy "aws_lb_listener" is valid when checking every listener’s own attributes (e.g., protocol, ssl_policy); use resource_policy "aws_lb" with inline lookup only when the goal is “every LB must have at least one compliant listener”.
    • Always add this comment when using this pattern: “This policy contains a cross-resource reference that will not resolve during plan time, but the policy will run successfully during apply time.”

Communication

1. Ask clarifying questions; don’t assume requirements.
2. Show sample passing and failing resources alongside the policy.
3. Explain enforcement-level trade-offs.
4. Offer simplifications when an exact rule isn’t expressible.

See Also

• tfpolicy-test — write .policytest.hcl files to validate the policies authored here.
• ../../examples/README.md — side-by-side Sentinel + .policy.hcl examples with quality labels and per-example READMEs.
• verified-syntax.md — shared source-of-truth syntax reference.

Purpose: Quick reference for AI agents to start writing Terraform Policy (tfpolicy) Status: All behaviors verified during private beta (2026-02-19) Compatible with: Any AI system capable of reading markdown and generating HCL code

Quick Start for AI Agents

When a user asks you to write a Terraform Policy:

1. Identify the policy type: resource_policy, module_policy, or provider_policy
2. Use the correct structure: filter (optional), locals (optional), enforce (required)
3. Remember: ALL built-in functions need core:: prefix
4. For versions: Always use core::semverconstraint(), never direct comparison
5. Validate: Check examples in this guide for patterns

Table of Contents

1. Critical Rules
2. Policy Structure
3. Policy Types
4. Core Functions Reference
5. Semantic Versioning

See Also:

• Common Patterns - Common policy patterns and examples
• tfpolicy-author - Complete authoring reference for this sub-skill

Critical Rules

✅ Rule 1: ALL Functions Need core:: Prefix

ALWAYS use core:: prefix for built-in Terraform functions

✅ Rule 2: Use Semantic Versioning for ALL Version Comparisons

NEVER use direct comparison operators for versions

✅ Rule 3: ALL Policy Types Support locals and filter

Don’t avoid using locals or filter - they work in all policy types

Note: Language servers during private beta may show false errors for locals in provider_policy. These are safe to ignore.

Policy Structure

Basic Template

Execution Flow

1. filter - Applied first, determines which resources/modules/providers to evaluate
2. locals - Computed once per filtered item
3. enforce - Each block evaluated; all must pass for policy to pass

Performance Best Practices

Critical for large configurations — choose the pattern based on what the filter depends on:

1. Top-level core::getresources() only when the filter is a known literal/constant

   • Use when the filter value is a hardcoded string, a fixed ID, or another stable literal — not derived from attrs.*
   • Executes once for the entire policy evaluation; result is reused by every resource_policy block
   • ❌ Do not use a top-level empty-filter call ({}) and then filter by attrs.* inside resource_policy — that is the prohibited anti-pattern (O(N²) with silent correctness bugs)

   hclCopy

   locals {
       # OK — filter is a known literal, cached once for all resources
       all_buckets = core::getresources("aws_s3_bucket", {})
   }
   
   resource_policy "aws_s3_bucket" "example" {
       locals {
           bucket_count = core::length(local.all_buckets)  # Reuse cached value
       }
   }

2. Inline core::getresources() inside resource_policy when the filter depends on the resource’s own attribute

   • Use when “every parent must have at least one compliant child” and the linking key is attrs.id, attrs.arn, or attrs.name
   • The filter value is unknown at plan time (it’s the current resource’s own attribute), so a top-level cache is impossible
   • Executes once per evaluated resource (apply-time); the lookup fully resolves once the resource is provisioned
   • This is not a performance compromise — it is the correct and required pattern for parent+child presence enforcement

   hclCopy

   # NOTE: This policy contains a cross-resource reference that will not resolve during
   # plan time, but the policy will run successfully during apply time.
   resource_policy "aws_s3_bucket" "s3_block_public_access" {
       locals {
           public_access_block = core::getresources("aws_s3_bucket_public_access_block", {
               bucket 
   
   
   
   
   
   
   

3. Use filter to reduce evaluation scope

   • Skip resources that don’t need checking
   • Significantly improves performance

See Advanced Patterns Guide for detailed performance guidance

Policy Types

1. resource_policy

Purpose: Validate Terraform resource configurations

Available attributes:

• attrs.<attribute_name> - Resource attributes from configuration
• meta.provider_type - Provider type (e.g., aws)
• ⚠️ meta.address is UNDEFINED for resource_policy in real plan evaluation — do not use it

⚠️ Understanding Provider Schema (Blocks vs Attributes):

Terraform providers expose their raw schema, where some attributes are blocks that require special handling:

Common AWS provider blocks requiring [0] index:

• default_tags[0].* (AWS provider configuration)
• assume_role[0].* (AWS provider configuration)
• versioning[0].enabled (S3 bucket)
• server_side_encryption_configuration[0].* (S3 bucket)
• metadata_options[0].* (EC2 instance)

Best practice: Always use core::length() checks before accessing blocks:

See Verified Syntax Reference for complete details

Wildcards:

2. module_policy

Purpose: Validate Terraform module sources and versions

Available attributes:

• meta.source - Module source (e.g., app.terraform.io/org/module/provider)
• meta.version - Module version (works with core::semverconstraint())
• meta.address - Module address (e.g., module.vpc)

⚠️ Current Limitations (Private Beta):

• ❌ attrs.* (module inputs) NOT accessible yet - work in progress
• ❌ meta.tfe_workspace NOT available - only in resource_policy

Targeting:

• Use full module source to target specific module: module_policy "app.terraform.io/myorg/vpc/aws"
• Use "*" wildcard to match all modules: module_policy "*"
• ❌ Substring matching does NOT work: module_policy "vpc" won’t match modules with “vpc” in source

3. provider_policy

Purpose: Validate provider versions and configurations

Available attributes:

• meta.source - Full provider source (e.g., registry.terraform.io/hashicorp/aws)
• meta.version - Provider version (e.g., 4.67.0)
• meta.alias - Provider alias (if configured)
• attrs.* - Provider configuration attributes (region, profile, etc.)

Note: meta.name and meta.type are NOT confirmed available in reference/verified-syntax.md. Do not rely on them — use meta.source to identify a provider and meta.version for version checks.

Accessing provider configuration with attrs:

⚠️ Provider configuration blocks require [0] index:

Wildcards:

Core Functions Reference

⚠️ String Function Limitations

Terraform Policy has VERY LIMITED string functions:

✅ String functions available:

• ✅ core::startswith(string, prefix) - Returns bool; e.g. core::startswith(meta.version, ">") ✅
• ✅ core::endswith(string, suffix) - Returns bool
• ✅ core::contains_substring(string, substr) - Returns bool
• ❌ core::contains(string, substring) - Does NOT work for strings (only lists!)
• ✅ core::split(separator, string) - Splits string into list; e.g. core::split("-", "80-443") → ["80", "443"]

✅ What IS Also Available — core::regex(pattern, string):

• Pattern and substring matching via core::regex()
• Important: core::regex() throws on no match (does NOT return null) — always wrap with core::try()

Note: For prefix/suffix checking, prefer core::startswith() / core::endswith() over core::regex(). Use core::split() with core::parseint() for numeric string decomposition (e.g. port-range strings like "80-443").

List Functions

Safe Access

⚠️ CRITICAL: Cannot Check Attribute Existence Without try()

Direct attribute access fails when attributes don’t exist, even with null checks:

Why: Terraform Policy cannot test attribute existence before accessing (no "attr" in attrs syntax). Always use core::try() first, then check the result.

Semantic Versioning

Resource Queries

⚠️ Filter caveat: core::getresources(type, { attr = value }) performs equality matching, but candidates whose target attribute is unknown at plan time (e.g. bucket = aws_s3_bucket.x.id for a resource being created in the same plan) are conservatively included. On first-time-create plans with cross-references you’ll get every candidate back. Most reliable on update plans against existing infrastructure. See reference/verified-syntax.md.

CRITICAL: core::getresources() Attribute Access

Resources returned by core::getresources() have attributes at the top level (NOT through .attrs):

Why: This is DIFFERENT from current resource context where you use attrs.name. Returned resources have a different structure.

Pattern for Cross-Resource Validation:

Semantic Versioning

Constraint Operators

Multiple Constraints (AND logic)

OR Logic

Version Allowlist Pattern

Next: Advanced Patterns & Best Practices

Purpose: Common patterns for writing Terraform policies Status: All patterns verified during private beta (Updated: 2026-02-24)

Pattern 1: Required Attribute

Pattern 2: Attribute Must Match Value

Pattern 3: Allowlist Check

Pattern 4: Tag Validation

Pattern 5: Module Source Restriction

Note: core::contains() only supports exact full-string matching. For prefix or namespace matching, use core::regex():

Pattern 6: Provider Version Range

Pattern 7: Conditional Enforcement

Pattern 8: Multiple Checks with Detailed Errors

Pattern 9: Provider Configuration Policies

Validate provider configuration attributes and blocks:

Key points:

• attrs.* provides access to provider configuration
• Provider blocks (default_tags, assume_role) require [0] index
• Version checking uses meta.version with core::semverconstraint()
• Security checks (no hardcoded credentials) are important

Pattern 10: Cross-Resource Enforcement

Enforce that one resource type has a corresponding companion resource:

aws_s3_bucket_server_side_encryption_configuration is a dependent child of aws_s3_bucket — its bucket argument always references attrs.id. The filter value is derived from attrs.*, so the top-level cache pattern is prohibited (Mistake 13 in verified-syntax.md). Always use the inline filter pattern for S3 companion resources.

Key points:

• The filter value (attrs.id) is the current resource’s own attribute — a top-level cache is impossible; use the inline call
• Both checks (presence and KMS algorithm) live in one resource_policy block with multiple enforce blocks — never split checks on the same resource type into two blocks (SKILL.md Output Structure Rule 1)
• Always include the apply-time # NOTE: comment

Pattern 11: Resource Count Limits

Limit the total number of resources of a specific type:

Key points:

• Policy runs for each resource but references global count
• All resources will fail if limit is exceeded
• Use top-level locals to count once

Pattern 12: Cross-Resource Attribute Validation

Validate that one resource’s attribute matches another resource’s attribute:

Key points:

• aws_vpc.id is the linking attribute referenced by attrs.vpc_id — this is an attrs.*-derived key so the top-level cache + map-index pattern is prohibited (Mistake 13 in verified-syntax.md); always use inline core::getresources
• Use core::try() for safe attribute access
• Check both existence and value matching

Pattern 13: Sentinel Conversion - DMS Endpoint SSL Mode

Source policy: HashiCorp PCI DSS library - dms-endpoints-should-use-ssl.sentinel

Conversion quality: Perfect

Why this converts cleanly:

• Single resource type
• Direct attribute check on planned values
• No cross-resource dependency or reference metadata
• Sentinel collection.reject() becomes one focused enforce condition

Pattern 14: Sentinel Conversion - Elasticsearch HTTPS Required

Source policy: HashiCorp PCI DSS library - elasticsearch-https-required.sentinel

Conversion quality: Good

Why this is Good instead of Perfect:

• The Sentinel policy uses helper functions and nested map lookups; tfpolicy rewrites that logic into direct block access with core::try()
• The enforcement intent is preserved, but the structure is idiomatic tfpolicy rather than one-to-one

Pattern 15: Sentinel Conversion - EventBridge Bus Must Have Attached Policy

Source policy: HashiCorp PCI DSS library - eventbridge-custom-event-bus-should-have-attached-policy.sentinel

Conversion quality: Limited

Why this is only Limited:

• This relies on value matching through core::getresources(), not Terraform graph/reference metadata
• It works best when event_bus_name is explicit and already resolved
• New resources with unresolved references can produce different behavior from Sentinel or fail to match on first creation

Previous: Quick Start Guide Back to: Main README

For filter expressions that must exclude both null and empty-string values: filter = core::try(attrs.field, null) != null && core::try(attrs.field, "") != "". The two-step rule applies at every nesting level. When a scalar is accessed through a nested path (e.g. core::try(local.list[0].scalar_attr, default)), apply the same pattern: if the attribute may be null, use core::try(..., null) and normalize explicitly.