Writing a rule

A rule pack is a directory containing one or more YAML files. Each file has pack metadata and rules:

name: studio-policy
version: 1.0.0
description: Studio-specific shipped-build checks
rules:
  - id: studio.admin-token
    title: Studio admin token shipped in build
    description: A privileged server token is present in client content.
    severity: critical
    confidence: 0.98
    applies_to: [text, config-file, string-table]
    paths: ['**/*']
    match:
      regex: '(?i)admin_token\s*[:=]\s*["'']?(?P<token>[A-Z0-9_-]{32,})'
      report: true
    entropy:
      min: 3.5
      group: token
      min_length: 32
    redact: token
    max_matches: 5
    allowlist:
      stopwords: [example, placeholder]
      paths: ['**/testdata/**']
    remediation: Revoke the token and move the privileged operation to a server.
    references:
      - https://example.invalid/security/admin-tokens
    tags: [secret, studio]
    fixture: testdata/admin-token.txt

Rules use Go RE2 regular expressions: no lookaround or backreferences. RE2 keeps matching linear-time on hostile inputs. Boolean conditions support all, any and not; leaves support regex, contains, icontains, path_glob, kind, min_size and max_size. Mark one location-producing leaf with report: true when a condition tree has several candidates.

Redaction

Secret rules MUST use the default redact: match, a named capture group, or redact: line. A named group narrows the location to the credential. Secret excerpts contain only a four-character identifying prefix and a redaction marker; surrounding source is intentionally omitted because it may contain a second credential. Use redact: none only for non-secret evidence such as URLs, versions and debug flags.

Fixtures

Every contributed rule needs an obviously fake positive fixture. Prefer a format-valid value containing XILAFAKE; never use a credential that was once active. Add negative fixtures for plausible placeholders or documentation that would otherwise match.

xila rules test ./rules/studio-policy
xila rules show studio.admin-token ./rules/studio-policy
xila scan ./Build --rules ./rules/studio-policy

The test command validates IDs, severity, condition shape, regexes, redaction groups, references and fixture behavior. Keep patterns narrow: false positives train developers to ignore real findings.