splunk-security_content/docs/ci/yaml_formatting.md

YAML Formatting & Validation Setup

Quick Setup

1. Install Pre-commit Hook

# Install pre-commit
pip install pre-commit

# Install the git hooks
pre-commit install

2. Install yamlfmt

Option A: Using Go

go install github.com/google/yamlfmt/cmd/yamlfmt@latest

Option B: Download Standalone Binary

• Download from: https://github.com/google/yamlfmt/releases
• Place in your PATH or ~/go/bin/
• Alternatively, use --yamlfmt-path flag to specify custom location (see below)

3. Install yamllint

pip install yamllint

---

Usage

Pre-commit (Automatic)

Pre-commit hook runs automatically when you commit files in detections/:

git add detections/endpoint/my_detection.yml
git commit -m "Add detection"
# yamlfmt runs automatically

Skip hook if needed:

git commit --no-verify -m "Skip hooks"

Manual Formatting

Run these from the root directory of security_content

# Format all detection files
yamlfmt detections/

# Format specific file
yamlfmt detections/endpoint/my_detection.yml

# Check what would change (dry run)
yamlfmt -dry detections/

Validation (CI)

# Validate all detections
python scripts/validate_yaml.py detections/

# Validate specific files
python scripts/validate_yaml.py detections/endpoint/file1.yml detections/cloud/file2.yml

# Validate changed files only
python scripts/validate_yaml.py $(git diff --name-only --diff-filter=ACM develop...HEAD | grep '^detections/.*\.yml$')

# Use custom yamlfmt binary path (when Go is not available)
python scripts/validate_yaml.py --yamlfmt-path /path/to/yamlfmt detections/

---

Troubleshooting

yamlfmt not found:

# Make sure Go bin is in PATH
export PATH="$HOME/go/bin:$PATH"

# Or use absolute path
~/go/bin/yamlfmt detections/

# Or specify path with --yamlfmt-path flag
python scripts/validate_yaml.py --yamlfmt-path /path/to/yamlfmt detections/

Pre-commit hook fails:

# Run hook manually to see errors
pre-commit run yamlfmt --files detections/endpoint/file.yml

# Update hooks
pre-commit autoupdate

# Use custom yamlfmt binary in pre-commit
# Edit .pre-commit-config.yaml and add to yamlfmt hook args:
# args: [--yamlfmt-path, /path/to/yamlfmt]

Validation fails in CI:

• Check the script output for specific errors
• Run locally: python scripts/validate_yaml.py detections/
• Ensure files pass both yamllint and yamlfmt --lint

---

Configuration Files

• .yamlfmt - yamlfmt formatting rules (4-space indent, LF line endings)
• .yamllint - yamllint validation rules (syntax checks, no duplicate keys)
• .pre-commit-config.yaml - Pre-commit hook configuration