Trusted configuration

Make policy explicit.Keep review narrow.

Use a reviewed YAML file when your organization needs an extra detector or has a specific, documented exception. Configuration is opt in: repyy never trusts a .repyy.yaml supplied by the repository being scanned.

Version 1 Required top-level versionExternal Pass the file with --configDeclarative Rules match text; they cannot execute commands

Keep the trusted file outside the target

Store your policy in a controlled location, review changes like code, and pass it explicitly: repyy scan ./checkout --config ./policy/repyy.yaml.

Understand the trust boundary

A repository cannot weaken its own scan with a repository-owned configuration file. Only the path you explicitly provide with --config is loaded. This lets you inspect an unfamiliar repository while keeping policy under your control.

Configuration adds custom rules and active suppressions. It does not remove built-in rules, change unrelated findings, or make source execution safe.

Start with valid YAML

The top-level version must be the integer 1. Start with both lists present, even when they are empty.

version: 1
rules: []
suppressions: []

Save as policy.yaml, then validate

repyy rules validate policy.yaml

Validation checks YAML syntax, the version, rule fields, regular expressions, suppression fingerprints, and suppression dates. It does not scan a target.

Use the safe workflow

Write the smallest policy

Add only a rule or exception you can explain and review.

Validate before scanning

Run repyy rules validate policy.yaml and fix every error.

Pass it explicitly

Run the target with --config policy.yaml, then inspect the evidence and coverage.

Complete workflow

repyy rules validate policy.yaml
repyy scan ./checkout --config policy.yaml --format html --output review.html

Custom rule fields

Every custom rule requires id, category, severity, confidence, description, and pattern. The remaining fields add context or narrow matching.

Requiredid, category, severity, confidence, description, pattern

Matchingglobs limits file paths; match_scope is raw (default) or code.

Review contextremediation, rationale, legitimate_use, and disposition.

Advancedallow_context_downgrade controls whether context can lower confidence.

severity is low, medium, high, or critical. confidence is low, medium, or high. disposition is informational, harden, review, or block; it changes presentation.

Walk through a custom rule

This example flags an unapproved bootstrap host only in shell and PowerShell files. The pattern is a regular expression, so punctuation that has regex meaning must be escaped.

version: 1
rules:
  - id: ORG-001
    category: organization-policy
    severity: high
    confidence: medium
    description: Unapproved bootstrap host
    pattern: 'bootstrap\.example\.invalid'
    globs: ['*.sh', '*.ps1']
    match_scope: raw
    disposition: review
    rationale: Our policy requires approval for bootstrap hosts.
    legitimate_use: A reviewed internal host may be expected.
    remediation: Confirm the host with the repository owner.

globs applies to file names or paths using case-insensitive comparisons. raw checks comments and strings as well as code; use code when only executable code should match. Custom rules cannot use structured scope, which is reserved for built-in structured detectors.

Validate then use it

repyy rules validate policy.yaml
repyy scan ./repo --config policy.yaml

Choose the matching scope

rawDefault for custom rules. Matches the raw file, including comments and strings.

codeRestricts a custom rule to executable code according to the scanner’s code extraction.

structuredReserved for built-in structured detectors; rejected in custom configuration.

Start with raw when the policy concerns a literal anywhere in a file. Choose code when comments, examples, or documentation would create noise. Test the choice against representative files before adopting the rule.

Suppress one reviewed finding

Suppressions are tied to a finding’s stable fingerprint. Save a JSON scan, copy the exact fingerprint, record why the match is acceptable, and add the exception to the trusted file.

Save JSON evidence

repyy scan ./repo --format json --output scan.json

Every suppression needs fingerprint and reason. expires is optional and must be an ISO calendar date in YYYY-MM-DD form. Once expired, the suppression stops being active automatically.

version: 1
suppressions:
  - fingerprint: 'sha256:replace-with-report-fingerprint'
    reason: 'Reviewed internal fixture; no executable path.'
    expires: '2026-12-31'

A suppression does not remove the underlying rule or change unrelated findings. Keep the scope narrow and re-review it before its expiry.

Review example: from finding to exception

Read the location

Open the reported file and inspect the matched context. Confirm whether it is executable, test, fixture, or documentation content.

Copy the exact fingerprint

Use the JSON report so the stable sha256:... value is copied without transcription errors.

Write a reason and expiry

Record the reviewer’s decision in YAML. An expiry keeps temporary exceptions from becoming permanent.

Validate and rescan

Run validation, then scan again and confirm only the reviewed finding changed.

Do not suppress to get green CI

Use a suppression only when the evidence supports the exception. If the behavior is not acceptable, fix or remove it instead.

Limits and validation errors

Configuration errors return exit code 3. Common causes are a version other than 1, malformed YAML, an invalid regular expression, structured match scope on a custom rule, an unsupported enum value, or a suppression missing its fingerprint, reason, or valid date.

Fix the YAML and rerun repyy rules validate before scanning. A valid configuration does not guarantee that a target scan will complete; timeouts, permissions, file limits, archive limits, or sandbox failures still produce incomplete coverage and exit code 2.

Validate only

repyy rules validate policy.yaml

For the complete command list, see the CLI reference ↗. For installation, reports, Docker, and the trust model, return to the documentation home ↗.