Mute Descriptor Format

This page describes the YAML format of the .xygeni.mute.yml descriptor used by scanner-side mute rules.

Top-level fields

A mute descriptor is a YAML file with the following top-level fields:

Field	Type	Required	Description
version	String	No	Format version (e.g. "1.0")
description	String	No	Human-readable description of the ruleset
rules	List<Rule>	Yes	Ordered list of mute rules

Rule fields

Each entry in rules has the following fields:

Field	Type	Required	Default	Description
id	String	No	—	Rule identifier (recommended for traceability)
reason	String	No	—	Human-readable justification for the suppression
scanner	String or List<String>	No	all	Scanner type filter (single value or array)
action	MuteAction	No	mute	Action to take when a finding matches
tags	List<String>	No	—	Custom tags added to matched findings
match	MuteMatch	No	match all	Matching criteria (omit to match everything)

scanner field

The scanner field accepts both single values and arrays:

scanner: secrets           # single value
scanner: [secrets, sast]   # array — matches findings from either scanner

Scanner type aliases are supported for convenience:

Aliases	Canonical name
dependencies, scan-deps, sca, component_vulnerabilities	deps
secret	secrets
iac_flaws	iac
cicd, misconfiguration, misconfigurations	misconf
critical_file_modification	codetamper
code_vulnerabilities	sast
dynamic_vulnerabilities	dast
evidence	malware

match fields

All non-null fields in match are ANDed together. Within each list field, patterns are ORed (any match suffices).

All pattern fields support negation (! prefix) and regex (~ prefix). See Matching semantics for details.

Field	Type	Applies to	Description
detectors	List<String>	All scanners	Glob patterns against detector IDs (e.g. hardcoded_*)
categories	List<String>	All scanners	Glob patterns against issue category tags
files	List<String>	All scanners	Glob patterns against file paths (e.g. src/test/**)
secrets	List<String>	Secrets scanner	Patterns against cleartext secret values (e.g. test-key-*). See note below.
secretTypes	List<String>	Secrets scanner	Patterns against secret type name (e.g. aws_access_key, generic_password)
secretKeys	List<String>	Secrets scanner	Patterns against secret key/variable names (e.g. TEST_*)
dependencies	List<String>	Deps scanners	Patterns against GAV coordinates (e.g. com.example:*)
severity	List<String>	All scanners	Exact severity levels: critical, high, low, info
minSeverity	String	All scanners	Minimum severity (inclusive): info, low, high, critical
maxSeverity	String	All scanners	Maximum severity (inclusive): info, low, high, critical
confidence	List<String>	SAST, Secrets, Misc	Confidence levels: low, medium, high, highest
language	List<String>	SAST only	Language patterns (e.g. java, python)
cwes	List<String>	SAST only	CWE ID patterns (e.g. CWE-89, CWE-7*)
cves	List<String>	SAST only	CVE ID patterns (e.g. CVE-2023-*)
issueType	List<String>	IaC, Misc	Issue type / IacFlawType patterns (e.g. encryption, iam)
framework	List<String>	IaC only	IaC framework patterns (e.g. terraform, kubernetes)
newOnly	Boolean	All scanners	true = only new findings, false = only existing
verified	Boolean	Secrets only	true = only verified secrets, false = only unverified

Note on the secrets field: it matches against the cleartext secret value. Mute rules are applied before secret cleanup (which nullifies cleartext values), so the field is always available during mute evaluation. Cleartext values are never uploaded to the server.

action values

Action	Suppressed?	Severity changed?	In report?	Tags added
mute	Yes	No	Yes	suppressed, muted-by-config, mute-reason:<id>
set_severity_info	No	Yes (to info)	Yes	muted-by-config, mute-reason:<id>
tag_only	No	No	Yes	Only the custom tags from the rule
discard	—	—	No	— (finding removed from report entirely)

For mute, set_severity_info and tag_only, any custom tags defined on the rule are also added to the finding.

For discard, the finding is removed from the report before upload, so no tags are added. Each discarded finding is logged at INFO level with its detector, issue ID, and the rule ID that triggered the discard.

Choosing between mute and discard: use mute when you want the finding to stay in the report (visible but excluded from guardrails and policy checks). Use discard when you want the finding completely removed — it will not appear in the report, dashboard, or any downstream processing. Discarded findings leave no audit trail in the report, so use with care.

Matching semantics

1. AND across criteria. All non-null fields in match must match for the rule to fire. For example, if both files and detectors are specified, the finding must match at least one file pattern and at least one detector pattern.

2. OR within lists. Within a single field (e.g. files: ["src/test/**", "*.yml"]), matching any one pattern is sufficient.

3. Glob patterns. All pattern fields use glob syntax (* matches any sequence within a segment, ** matches across path separators). Matching is case-insensitive.

4. Negation (! prefix). Patterns prefixed with ! act as exclusions. If only negative patterns are specified, everything not excluded matches. If both positive and negative patterns are specified, the value must match at least one positive pattern AND not match any negative pattern.

   # Match everything except test files
   files:
     - "!src/test/**"
   
   # Match hardcoded_* detectors, but exclude hardcoded_test
   detectors:
     - "hardcoded_*"
     - "!hardcoded_test"

5. Regex (~ prefix). Patterns prefixed with ~ are treated as raw regular expressions (case-insensitive) instead of glob patterns. Can be combined with negation as !~.

   # Match detectors using regex
   detectors:
     - "~java\\.sql_.*"
   
   # Negated regex: match everything except detectors ending in _test
   detectors:
     - "*"
     - "!~.*_test$"

6. Severity ranges. Use minSeverity and maxSeverity for inclusive range filtering. These work alongside the severity list field (when both are specified they are ANDed).

   # Match low and high (but not info or critical)
   match:
     minSeverity: low
     maxSeverity: high

7. First-match-wins. Rules are evaluated in the order they appear. The first matching rule's action is applied and no further rules are checked.

8. Scanner filter. If scanner is set on a rule, only findings from that scanner type are considered. A rule with no scanner field applies to all scanner types. Multiple scanner types can be specified as an array.

9. Omitted match block. A rule with no match block (or match: null) matches every finding of the specified scanner type (or all scanners if scanner is also omitted).

Use cases and examples

Suppress test secrets

Suppress hardcoded credentials found in test directories, since they are not real secrets:

rules:
  - id: mute-test-secrets
    reason: "Known test credentials, not real secrets"
    scanner: secrets
    action: mute
    match:
      files:
        - "src/test/**"
        - "**/*Test*"
      detectors:
        - "hardcoded_*"

Whitelist known secret values

Suppress specific known test/example secret values that are safe to ignore. The secrets field matches against the cleartext secret value:

rules:
  - id: mute-known-secret-values
    reason: "Known test/example credentials"
    scanner: secrets
    action: mute
    match:
      secrets:
        - "AKIAIOSFODNN7EXAMPLE"
        - "test-key-*"
        - "~^dummy[_-].*"

Suppress secrets by key name or type

Use secretKeys to match the variable/key name, and secretTypes to match the kind of secret:

rules:
  - id: mute-test-secret-keys
    reason: "Test credentials identified by variable name"
    scanner: secrets
    action: mute
    match:
      secretKeys:
        - "TEST_*"
        - "DUMMY_*"
        - "EXAMPLE_*"

  - id: mute-generic-passwords-tests
    reason: "Generic passwords in test directories"
    scanner: secrets
    action: mute
    match:
      secretTypes:
        - "generic_password"
      files:
        - "src/test/**"

All three secret fields (secrets, secretTypes, secretKeys) can be combined in the same rule — they are ANDed together (all must match).

Multi-scanner rule

Suppress findings from multiple scanners with a single rule:

rules:
  - id: mute-test-code
    reason: "Test code findings are expected"
    scanner: [secrets, sast]
    action: mute
    match:
      files:
        - "src/test/**"

Suppress SAST findings in test files

Test code often uses patterns that trigger SAST detectors (e.g. SQL injection in test fixtures):

rules:
  - id: mute-sast-tests
    reason: "SAST findings in test code are expected"
    scanner: sast
    action: mute
    match:
      files:
        - "src/test/**"
        - "**/*Test.java"
        - "**/*Spec.js"

Suppress low-severity findings

Focus on critical and high findings by suppressing info and low severity issues:

rules:
  - id: mute-low-severity
    reason: "Focus on critical/high severity findings"
    action: mute
    match:
      severity:
        - "info"
        - "low"

Or equivalently, using a severity range:

rules:
  - id: mute-low-severity
    reason: "Focus on critical/high severity findings"
    action: mute
    match:
      maxSeverity: low

Suppress low-confidence SAST findings

Only keep high-confidence SAST findings:

rules:
  - id: mute-low-confidence-sast
    reason: "Low confidence findings are likely false positives"
    scanner: sast
    action: mute
    match:
      confidence:
        - "low"
        - "medium"

Filter by language

Suppress SAST findings for a specific language:

rules:
  - id: mute-python-sast
    reason: "Python SAST rules still being calibrated"
    scanner: sast
    action: mute
    match:
      language:
        - "python"

Filter by CWE or CVE

Suppress specific vulnerability classes:

rules:
  - id: mute-sql-injection
    reason: "SQL injection handled by parameterized queries"
    scanner: sast
    action: mute
    match:
      cwes:
        - "CWE-89"
        - "CWE-564"

Filter IaC by type and framework

Suppress specific IaC flaw types for a particular framework:

rules:
  - id: mute-tf-encryption
    reason: "Encryption handled at infrastructure level"
    scanner: iac
    action: mute
    match:
      issueType:
        - "encryption"
      framework:
        - "terraform"

Using negation patterns

Suppress findings everywhere except specific detectors. With only negation patterns, everything not excluded matches:

rules:
  # Mute everything except sql_injection and hardcoded_password
  - id: focus-on-critical-detectors
    reason: "Only review critical detectors"
    action: mute
    match:
      detectors:
        - "!sql_injection"
        - "!hardcoded_password"

Combine positive and negative patterns — the value must match at least one positive AND not match any negative:

rules:
  # Match all hardcoded_* detectors except hardcoded_test
  - id: mute-hardcoded-except-test
    reason: "Suppress hardcoded detectors except test"
    action: mute
    match:
      detectors:
        - "hardcoded_*"
        - "!hardcoded_test"

Tag for audit trail without suppression

Mark findings for review without suppressing them. Useful for tracking deprecated detectors or categories requiring attention:

rules:
  - id: tag-deprecated-detectors
    reason: "Flag deprecated detectors for review"
    action: tag_only
    tags:
      - "review-needed"
      - "deprecated-detector"
    match:
      detectors:
        - "deprecated_*"

Downgrade severity for accepted risks

When a risk is accepted but you still want visibility, downgrade the severity to info instead of fully suppressing:

rules:
  - id: downgrade-sql-tests
    reason: "SQL injection in test code is an accepted risk"
    scanner: sast
    action: set_severity_info
    match:
      detectors:
        - "sql_injection"
      files:
        - "src/test/**"

Discard findings entirely

Remove findings from the report so they are never uploaded. Use with care — discarded findings leave no trace in the report:

rules:
  - id: discard-test-secrets
    reason: "Remove test secrets from report entirely"
    scanner: secrets
    action: discard
    match:
      files:
        - "src/test/**"
      secretKeys:
        - "TEST_*"
        - "DUMMY_*"

Suppress all findings for a scanner

Suppress all IaC findings (e.g. during a migration when IaC configs are in flux):

rules:
  - id: mute-all-iac
    reason: "IaC configs under active migration"
    scanner: iac
    action: mute
    # No match block = matches all findings for this scanner

Filter by dependency coordinates

Suppress known false positives for specific dependencies:

rules:
  - id: mute-internal-deps
    reason: "Internal dependencies, vulnerabilities tracked separately"
    scanner: deps
    action: mute
    match:
      dependencies:
        - "com.mycompany:*"
        - "com.mycompany.internal:*"

Only match verified secrets

Suppress verified secrets in test directories (unverified secrets remain visible):

rules:
  - id: mute-verified-test-secrets
    reason: "Verified test secrets are known and accepted"
    scanner: secrets
    action: mute
    match:
      files:
        - "src/test/**"
      verified: true