Redaction rules file (advanced)

This page documents hand-written redaction.yaml rules files for Alloy Edge v0.7 to v0.9.8. The rule editor in Edge settings can write these rules for you; see Configure.

# Required from v0.9.0.
version: 1

# Optional. Merge named functions from additional files.
includes:
  - /etc/alloy/transforms-common.yaml

# Topic-level allow/deny. Runs before any other rule.
channels:
  allow: ["*"]
  deny: ["/user/*", "/audio/**"]

# Salt for hash(...). ${VAR} is read from the environment at load time.
hash_salt: "${ALLOY_HASH_SALT}"

# Per-channel mappings. First match wins.
transforms: [...]

# Per-metadata-record mappings. Same shape as transforms.
metadata: [...]

# The named-function library. Referenced by transforms / metadata via `function:`.
functions: { ... }

# Optional. Rule-file-level audit defaults. Settings in edge-sync.yaml's
# `audit:` block and CLI flags take precedence.
audit:
  embed_in_mcap: true

Top-level

channels

Topic-level allow/deny. It runs before any other rule.

Globs use shell-style wildcards. * matches any characters, including /, so deny: ["/user/*"] also drops /user/a/b.

transforms[] / metadata[]

Each entry has exactly one of function: or transform:. Both or neither → load-time error.

Match selector

Two equivalent forms — pick the shorthand for the common case.

# Shorthand — channel only (or record-name only for `metadata:`)
match: "/diagnostics"

# Object form — full selector
match:
  channel: "/diagnostics"
  schema: "diagnostic_msgs/DiagnosticArray"   # disambiguates same-topic-different-schema (rare but legal)
  encoding: "cdr"                             # or "ros2msg", "protobuf", etc.

For the metadata: block, the shorthand maps to record_name instead of channel:

match: "operator_*"           # shorthand → record_name

match:
  record_name: "operator_*"   # object form
  key: "operator_email"       # optional inner-key glob

Transform bodies

Each transform body has a type: field. These types are available in every version from v0.7 to v0.9.8:

From v0.9.1, metadata: rules can also use drop_if. It drops the matched value when a condition is true. Set operator to equals, not_equals, contains, empty, or not_empty, and set value for the operators that compare. transforms: rules reject drop_if.

type: put — whitelist

Spell out the entire output. Fields not mentioned in the template disappear. New upstream fields don't leak.

type: patch — denylist

Pass everything through, override only the listed fields.

functions

Named transform bodies. Same shape as a transform: entry, minus the match: key (which lives on the call site).

functions:
  # Identity put: the message passes through unchanged.
  identity_pass:
    type: put

  # Whitelist redactor for an operator-command message.
  redact_operator_cmd:
    type: put
    schema: "your_msgs/OperatorCommand"
    template: |-
      {
        "operator_id": {{ operator_id | hash(algo="sha256") | tojson }},
        "command": {{ command | tojson }},
        "timestamp": {{ timestamp | tojson }}
      }

  # Denylist counterpart — same schema, only override two fields.
  redact_operator_cmd_lite:
    type: patch
    schema: "your_msgs/OperatorCommand"
    overrides:
      operator_id: '{{ original | hash(algo="sha256") }}'
      notes: '""'

Functions from includes: land in the same namespace; local definitions in the entry-point file always win on collision.

Template helpers

template: and overrides: expressions use Jinja2 syntax. On top of the standard filters, Alloy Edge adds these helpers. Each one works as a filter and as a function.

hash_salt must be set if any rule calls hash(...). sha256_short does not consume the salt.

Resolution rules

1. Channel filter runs first. Denied topics are dropped before any other rule runs.
2. First match wins per channel / record name. A topic not listed in transforms: passes through unchanged.
3. includes: merge in declaration order (last include wins on function-name collision); local functions: in the entry-point file override every include.
4. Bad templates fail at load time. A Jinja syntax error in any template / override expression rejects the rules file before the agent starts.

Reload semantics

Alloy Edge reads the rules file, and every included file, when the sync process starts. Restart Alloy Edge after you edit them.

The merged config is hashed (sha256:<hex>, recorded as rules_hash on every audit entry) so you can prove later which version of the rules produced a given file.