Skip to content

Policy file reference

Policyglass policies are YAML documents.

Schema

version: 1
required_paths:
  - README.md
forbidden_globs:
  - '*.pem'
ignore_globs:
  - '.git/'
size_limits:
  - glob: 'dist/*.whl'
    max_bytes: 10000000
content_scan_max_bytes: 1000000
content_regex_timeout_ms: 100
forbidden_content_patterns:
  - pattern: 'AKIA[0-9A-Z]{16}'
    message: 'Possible AWS key'

Fields

version

Positive integer policy version. The current implementation accepts any positive integer and treats 1 as the baseline schema.

required_paths

List of paths that must exist relative to the scan root. Entries can refer to files or directories.

For safety, these entries must stay within the scan root. Absolute paths and paths containing .. are rejected.

forbidden_globs

List of glob patterns that must not match any scanned file path.

ignore_globs

List of path globs excluded from scanning. Directory-style entries ending in / exclude the directory and everything under it.

size_limits

List of objects with:

  • glob: glob pattern to match file paths
  • max_bytes: positive integer upper bound in bytes

A file can match multiple rules. Each violated rule yields a finding.

forbidden_content_patterns

List of objects with:

  • pattern: regular expression accepted by the Python regex engine
  • message: human-readable explanation shown in findings

Patterns are evaluated against the decoded text content of each scanned file. The complete decoded file is searched, so matches can span any byte position within the configured budget; there are no streaming chunk boundaries.

content_scan_max_bytes

Positive integer byte budget for each file considered by content rules. The default is 1000000 bytes and the maximum accepted value is 100000000 bytes. A larger file is not read or regex-scanned and instead produces a failing content_scan_too_large finding. Reads are also capped at the budget plus one sentinel byte so a file that grows after its size check cannot cause an unbounded allocation.

content_regex_timeout_ms

Positive integer CPU-safety timeout, in milliseconds, applied independently to every content pattern search. The default is 100 and the maximum accepted value is 60000. The regex engine enforces this limit; a timed-out search produces a failing content_regex_timeout finding instead of being treated as no match.

Validation behavior

Policyglass rejects malformed policies early, including:

  • non-mapping top-level YAML documents
  • non-list values where lists are expected
  • required_paths entries that try to escape the scan root with absolute paths or ..
  • missing glob, pattern, or message fields
  • non-positive max_bytes
  • invalid, non-positive, or above-maximum content byte budgets and regex timeouts
  • invalid regular expressions in forbidden_content_patterns
  • invalid or non-positive version

Design notes

This schema is intentionally conservative. It is easier to extend a small rule language than to stabilize an overly broad one.

Content bytes are decoded as UTF-8 with invalid byte sequences ignored, preserving the original scanner behavior. Timeout enforcement depends on the third-party regex engine rather than the standard-library re module, which has no enforceable per-search timeout. Total scan CPU remains proportional to the number of scanned files and configured patterns; each individual search is bounded by content_regex_timeout_ms.