StackGuardian / StackGuardian/tirith

feat(core): YAML policy format with transformation functions via `!` tags

Open
#375 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
165
Forks
42
Avg merge
1d 3h
Merged PRs (30d)
11

Description

Policies are JSON-only today. Support YAML as a first-class policy format: the same schema (YAML is
a superset, so every existing policy has a 1:1 YAML twin), plus YAML custom tags — the ! prefix —
as declarative transformation functions inline in the policy:

meta:
  version: v1
  provider: stackguardian/terraform_plan
evaluators:
  - id: task_def_count
    provider_args:
      operation_type: attribute
      terraform_resource_type: aws_ecs_task_definition
      terraform_resource_attribute: !json_decode container_definitions
    condition:
      type: LessThanEqualTo
      value: !length

Design constraints

  • Tags are data, not code: a fixed whitelist of transformation tags (e.g. !length,
    !json_decode, !lower) parsed with a safe YAML loader — an unknown tag is a validation error,
    never an arbitrary constructor. This keeps the format Builder-friendly.
  • The tags are surface syntax over the same transformation pipeline planned for
    condition.transform — one implementation, two spellings. A minimal function set can ship with
    the format; the fuller coercion layer (dates, CIDR, sizes) extends it later.
  • Each transformation step wraps errors per value (a failed decode is a provider error on that
    resource, not a crashed run).
  • tirith lint / tirith fmt (#366) must accept and format YAML policies; validation and the
    interactive builder round-trip both formats.

Acceptance. A .yaml policy evaluates identically to its JSON twin; ! tags apply the shared
transformations with per-value error handling; an unknown tag fails validation with a clear
message; tirith lint/fmt handle YAML; docs show a side-by-side JSON/YAML example.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the existing JSON policy validation and evaluation path, then trace the tirith lint and tirith fmt entry points mentioned in the issue and related work in #366. Done means YAML policies evaluate like JSON, approved tags transform values with per-value errors, unknown tags fail clearly, lint/format and builder round-trips work, and the documentation includes a JSON/YAML comparison.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.