How to Use the SkillSpector Baseline Feature to Suppress Known Findings

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 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【/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【/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:

# 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【/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:

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:

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【/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:

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

The report node in 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:

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【/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【/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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}