yamlpolicy

Documentation

Overview

Package yamlpolicy provides security-focused YAML parsing primitives.

This package centralizes YAML security checks that must be applied consistently across all YAML parsing in the codebase (config files, lockfiles, etc.).

Security Properties

• Alias bomb detection: Prevents exponential expansion attacks
• Size limits: Enforces maximum input size before parsing
• Consistent enforcement: Single source of truth for YAML security policy

Usage

// Check for alias bombs before parsing
if err := yamlpolicy.CheckAliasAbuse(data); err != nil {
    return err
}

// Or use the combined check
if err := yamlpolicy.ValidateBeforeParse(data, limits.ConfigFile.Bytes()); err != nil {
    return err
}

YAML Alias Bombs

YAML alias bombs exploit the alias/anchor feature to cause exponential expansion:

a: &a ["x","x"]
b: &b [*a,*a]      # 4 elements
c: &c [*b,*b]      # 8 elements
d: &d [*c,*c]      # 16 elements

This package detects such patterns by counting aliases vs anchors BEFORE the YAML is expanded during unmarshaling.

Index

• func CheckAliasAbuse(data []byte) error
• func CountAliasesInNode(node *yaml.Node) (anchors, aliases int)
• func ValidateBeforeParse(data []byte, maxSize int64) error

Functions

func CheckAliasAbuse

func CheckAliasAbuse(data []byte) error

CheckAliasAbuse scans raw YAML for potential alias bomb patterns BEFORE parsing. This prevents DoS attacks where aliases expand exponentially.

YAML alias bombs work by defining anchors and then referencing them multiple times, causing exponential expansion. For example:

a: &a ["x","x"]
b: &b [*a,*a]
c: &c [*b,*b]  # Now c has 8 elements
d: &d [*c,*c]  # Now d has 16 elements

We detect this by parsing the YAML into nodes WITHOUT expanding aliases, then checking the ratio of alias references to anchors.

SECURITY: This must be called BEFORE yaml.Unmarshal, which expands aliases during parsing.

func CountAliasesInNode

func CountAliasesInNode(node *yaml.Node) (anchors, aliases int)

CountAliasesInNode counts anchors and aliases in a YAML node tree. Returns (anchorCount, aliasCount). Exported for testing and advanced use cases.

func ValidateBeforeParse

func ValidateBeforeParse(data []byte, maxSize int64) error

ValidateBeforeParse performs all security checks that must happen before YAML parsing. This includes size limit enforcement and alias bomb detection.

SECURITY: Call this BEFORE yaml.Unmarshal to prevent DoS attacks.