# How to Use the SkillSpector Baseline Feature to Suppress Known Findings

> Learn how to use the SkillSpector baseline feature to suppress known findings. Generate a baseline file and filter out accepted issues with ongoing scans.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-07-11

---

**Use the `skillspector baseline` command to generate a YAML file containing fingerprints of current findings, then run subsequent scans with `--baseline <file>` to filter out accepted issues while preserving the ability to audit suppressed entries with `--show-suppressed`.**

The **SkillSpector** CLI from NVIDIA provides a robust baseline mechanism that lets teams suppress known or accepted security findings without losing auditability. By generating a fingerprint-based baseline file, you can ensure that only new or unreviewed issues surface in CI/CD pipelines. This guide explains how to create, customize, and apply baselines using the suppression engine implemented in the [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py) module.

## What Is a SkillSpector Baseline?

A **baseline** is a YAML (or JSON) file that instructs SkillSpector to ignore specific findings during risk scoring and reporting. According to the module docstring in [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L18-L31】, the file contains two complementary sections:

- **`rules`** — Human-authored glob patterns that match a finding’s `id`, `path`, and/or `message`. These rules tolerate minor code changes such as file moves or line shifts.
- **`fingerprints`** — Exact SHA-256 hash entries generated automatically from the scan state. If a finding’s computed hash appears in this list, it is permanently suppressed.

This dual approach allows you to combine coarse-grained rule-based suppressions with precise fingerprint-based exclusions.

## How the Baseline Feature Works

The baseline integration follows a three-stage pipeline managed by the report node and suppression module:

1. **Loading** — When you invoke `skillspector scan --baseline <file>`, the CLI calls `load_baseline()` in [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L209-L223】 to parse the YAML/JSON into a `Baseline` object.
2. **Partitioning** — The `report` node retrieves the baseline from the analysis state and executes `partition_findings()`【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L227-L247】 to split findings into *active* and *suppressed* buckets.
3. **Scoring & Reporting** — Only active findings contribute to the risk score and SARIF output. Suppressed findings are excluded from scoring but can be rendered in the console report when the `--show-suppressed` flag is set【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/nodes/report.py#L16-L22】.

## Generating a Baseline File

To create a baseline that suppresses every finding from the current scan, use the dedicated `baseline` command. This command scans the skill, collects all findings, and serializes them into fingerprints.

Execute the following to generate a default baseline:

```bash

# Create .skillspector-baseline.yaml in the current directory

skillspector baseline ./my-skill/

# Generate with custom output path and static analysis only (skip LLM checks)

skillspector baseline ./my-skill/ -o team-baseline.yaml --no-llm

```

Under the hood, the `baseline` function in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/cli.py#L88-L46】 orchestrates this by:
- Running `_scan_state` to collect findings,
- Invoking `build_baseline_dict(findings, reason)` to convert each finding into a fingerprint entry【/cache/repos/github.com/NVIDIA/SkillSkillSpector/main/src/skillspector/suppression.py#L249-L66】,
- Writing the result via `dump_baseline()`, which defaults to YAML unless the file extension is `.json`【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L269-L79】.

## Using a Baseline in Subsequent Scans

Once committed to version control, the baseline file acts as a gatekeeper for future scans:

```bash
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

```

During execution, the CLI loads the baseline and the `report` node automatically filters out any finding whose fingerprint matches an entry in the baseline file. This ensures that known issues do not pollute the risk score or SARIF reports.

## Adding Custom Suppression Rules

For findings that evolve (e.g., line numbers shift), manual rules provide more durable suppression than fingerprints. Edit the baseline YAML to add glob-based rules:

```yaml
version: 1
rules:
  - id: "SQP-1"
    reason: "False positive – known safe pattern"
  - path: "*deploy-topology*/SKILL.md"
    message: "*run the exploit*"
    reason: "Test-only phrase"
fingerprints:
  - hash: "sha256:1a2b3c4d5e6f7081"
    reason: "Accepted 2024-09-01"

```

The `rules` section uses standard glob syntax evaluated via `fnmatch.fnmatch` in [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L72-L82】. You can match on `id`, `path`, `message`, or combinations thereof. The `fingerprints` list can also be edited manually if you need to suppress a specific finding without regenerating the entire file.

## Viewing Suppressed Findings

By default, suppressed findings are hidden from the risk summary. To audit what was filtered during a scan, append the `--show-suppressed` flag:

```bash
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed

```

The report node in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/nodes/report.py#L58-L70】 renders a dedicated table listing the rule ID, location, and suppression reason for each excluded finding.

## Programmatic Baseline Usage

You can also manipulate baselines directly in Python for custom tooling:

```python
from skillspector.suppression import load_baseline, partition_findings
from skillspector.models import Finding

# Load an existing baseline

baseline = load_baseline("example-baseline.yaml")

# Partition findings from a custom scan

findings = [...]  # List of Finding objects

kept, suppressed = partition_findings(findings, baseline)

print(f"Active: {len(kept)}  Suppressed: {len(suppressed)}")

```

This API leverages the same `load_baseline` and `partition_findings` functions used internally by the CLI【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L209-L247】.

## Summary

- **Create** a baseline with `skillspector baseline ./skill/` to fingerprint all current findings.
- **Commit** the generated YAML/JSON to version control to share suppressions across the team.
- **Scan** with `--baseline <file>` to filter known issues automatically.
- **Customize** the baseline file with glob-based `rules` for flexible matching or edit `fingerprints` for exact hash suppression.
- **Audit** suppressed entries using `--show-suppressed` without affecting risk scores.

## Frequently Asked Questions

### What file format does SkillSpector use for baselines?

SkillSpector supports both YAML and JSON. The `dump_baseline()` function in [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L269-L79】 defaults to YAML unless the output path ends with `.json`. The structure requires a `version` key and lists for `rules` and `fingerprints`.

### How do I regenerate a baseline after adding new suppressions?

Run the `skillspector baseline` command again with the same output path. This overwrites the file with fresh fingerprints for all current findings. If you have manually added `rules`, back them up first or maintain separate rule files that you merge after regeneration.

### Can I suppress findings by rule ID only?

Yes. Add an entry to the `rules` list with only the `id` field specified. For example, `- id: "SQP-1"` will suppress every instance of that rule regardless of file path or message content, as evaluated by the `fnmatch` logic in [`src/skillspector/suppression.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/suppression.py)【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/suppression.py#L72-L82】.

### Do suppressed findings affect the risk score?

No. The `report` node explicitly excludes suppressed findings from risk-score calculations【/cache/repos/github.com/NVIDIA/SkillSpector/main/src/skillspector/nodes/report.py#L16-L22】. Only active findings contribute to the aggregate score, though suppressed items remain available for display with `--show-suppressed`.