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:
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:
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
scanner fieldThe scanner field accepts both single values and arrays:
Scanner type aliases are supported for convenience:
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
match fieldsAll 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.
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 valuesmute
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
AND across criteria. All non-null fields in
matchmust match for the rule to fire. For example, if bothfilesanddetectorsare specified, the finding must match at least one file pattern and at least one detector pattern.OR within lists. Within a single field (e.g.
files: ["src/test/**", "*.yml"]), matching any one pattern is sufficient.Glob patterns. All pattern fields use glob syntax (
*matches any sequence within a segment,**matches across path separators). Matching is case-insensitive.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.Regex (
~prefix). Patterns prefixed with~are treated as raw regular expressions (case-insensitive) instead of glob patterns. Can be combined with negation as!~.Severity ranges. Use
minSeverityandmaxSeverityfor inclusive range filtering. These work alongside theseveritylist field (when both are specified they are ANDed).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.
Scanner filter. If
scanneris set on a rule, only findings from that scanner type are considered. A rule with noscannerfield applies to all scanner types. Multiple scanner types can be specified as an array.Omitted
matchblock. A rule with nomatchblock (ormatch: null) matches every finding of the specified scanner type (or all scanners ifscanneris also omitted).
Use cases and examples
Suppress test secrets
Suppress hardcoded credentials found in test directories, since they are not real secrets:
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:
Suppress secrets by key name or type
Use secretKeys to match the variable/key name, and secretTypes to match the kind of secret:
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:
Suppress SAST findings in test files
Test code often uses patterns that trigger SAST detectors (e.g. SQL injection in test fixtures):
Suppress low-severity findings
Focus on critical and high findings by suppressing info and low severity issues:
Or equivalently, using a severity range:
Suppress low-confidence SAST findings
Only keep high-confidence SAST findings:
Filter by language
Suppress SAST findings for a specific language:
Filter by CWE or CVE
Suppress specific vulnerability classes:
Filter IaC by type and framework
Suppress specific IaC flaw types for a particular framework:
Using negation patterns
Suppress findings everywhere except specific detectors. With only negation patterns, everything not excluded matches:
Combine positive and negative patterns — the value must match at least one positive AND not match any negative:
Tag for audit trail without suppression
Mark findings for review without suppressing them. Useful for tracking deprecated detectors or categories requiring attention:
Downgrade severity for accepted risks
When a risk is accepted but you still want visibility, downgrade the severity to info instead of fully suppressing:
Discard findings entirely
Remove findings from the report so they are never uploaded. Use with care — discarded findings leave no trace in the report:
Suppress all findings for a scanner
Suppress all IaC findings (e.g. during a migration when IaC configs are in flux):
Filter by dependency coordinates
Suppress known false positives for specific dependencies:
Only match verified secrets
Suppress verified secrets in test directories (unverified secrets remain visible):
Last updated

