# Mute Rules

Mute rules let you **suppress**, **downgrade**, **tag**, or **discard** scan findings on the scanner side, using declarative rules stored in a YAML file next to your code.

They are applied as a post-processing step after any scanner completes (Secrets, SAST, IaC, SCA, Suspect Deps, Malware, Misconf, CodeTamper, etc.), and are intended for managing false positives and accepted risks without requiring server access — keeping suppression rules co‑located with the source they apply to.

## How to suppress findings in Xygeni

Xygeni offers two complementary mechanisms for handling false positives, noisy findings, or explicitly accepted risks ("don't care" findings). Pick the one that best matches the situation:

| Mechanism                               | Where                                                                               | Granularity                                                                             | Best for                                                                                                                                                                                                                                           |
| --------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scanner-side mute rules** (this page) | `.xygeni.mute.yml` (in repo) or `--mute` CLI option, or a named server-side ruleset | **Rule-based** — match by detector, file, severity, CWE, dependency, secret value, etc. | Broad, predictable suppressions co-located with code: test code patterns, known test secrets, accepted IaC risks, noisy detectors, etc. Applies automatically on every scan — no manual review needed. Works offline / in air-gapped environments. |
| **Web UI server-side mute action**      | Xygeni Web UI, per issue                                                            | **Per-issue** — one finding at a time                                                   | One-off decisions by security reviewers: "this specific SQL injection is a false positive because X". Leaves a per-issue audit trail in the platform.                                                                                              |

**Rule of thumb**

* If you find yourself muting the **same kind of finding repeatedly** across scans (same detector, same file pattern, same dependency, same test value), use a **scanner-side mute rule** in `.xygeni.mute.yml`. It is versioned with your code, visible in code review, and applies consistently on every scan and for every developer.
* If you need to mute **a single specific finding** after reviewing it in context, use the **server-side mute action** in the Xygeni Web UI. Server-side mutes are ideal for individual, carefully-reviewed decisions.

The two mechanisms are additive: a finding can be muted by a scanner-side rule, by a Web UI action, or both. Either mechanism excludes the finding from guardrail failure criteria while keeping it visible in the platform for audit.

## Quick Start

Create a file named `.xygeni.mute.yml` in your project root:

```yaml
version: "1.0"
description: "Suppress test-only secrets"

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

Run your scan as usual. Matching findings will be tagged as `suppressed` and `muted-by-config`, and excluded from guardrails.

See [Mute Descriptor Format](/xygeni-scanner-cli/xygeni-cli-overview/mute-rules/descriptor-format.md) for the full YAML reference, all match fields, actions, and worked examples.

## Loading and Usage

### CLI `--mute` option

Pass a mute descriptor explicitly on the command line:

```bash
# From a local file (absolute or relative path)
xygeni secrets -d /path/to/project --mute path/to/.xygeni.mute.yml

# From a named, server-side ruleset (prefix with '#')
xygeni scan --mute '#my-ruleset-name'
```

{% hint style="info" %}
Relative paths passed to `--mute` are resolved against the project base directory (`-d`) first, and then — as a fallback — against your current working directory. This matches the common CLI convention when you run the scanner from a directory different from the project directory.
{% endhint %}

### Auto-discovery

When `enableConfigurationMutes` is `true` in `xygeni.yml`, the scanner automatically looks for a `.xygeni.mute.yml` file in the project base directory (the `-d` option). No `--mute` argument is needed.

### Configuration in `xygeni.yml`

The `mutes` section in `xygeni.yml` controls mute behavior:

```yaml
mutes:
  # Auto-discover .xygeni.mute.yml in the project directory
  enableConfigurationMutes: true
  # Enable inline mute rules in code comments (reserved for future use)
  enableInlineMutes: false
  # Token prefix for inline mutes in comments
  inlineMuteToken: "xygeni:mute"
```

### Precedence

* An explicit `--mute` argument always takes precedence over auto-discovery.
* If `--mute` is not given and `enableConfigurationMutes` is `true`, the scanner auto-discovers `.xygeni.mute.yml` in the base directory.
* If `enableConfigurationMutes` is `false` and no `--mute` is given, no mute rules are applied.

## Reporting and guardrails

* Muted findings are **still uploaded** to the Xygeni platform, marked as muted. This preserves full visibility and audit trail.
* Muted findings are **excluded from guardrail failure criteria**, so they will not break your CI/CD pipeline.
* Findings removed with `action: discard` are **not uploaded** and leave no trace in the report. Prefer `mute` over `discard` unless you explicitly want the finding to disappear.

## Next steps

* [Mute Descriptor Format](/xygeni-scanner-cli/xygeni-cli-overview/mute-rules/descriptor-format.md) — full YAML reference, match criteria, actions, matching semantics and worked examples.
* [Server-Side Mute Rulesets](/xygeni-scanner-cli/xygeni-cli-overview/mute-rules/server-side-rulesets.md) — manage named rulesets on the Xygeni server with `xygeni util mute` and share them across projects via `--mute '#name'`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/mute-rules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.