SkillSpector Scan Exit Codes Explained: A Complete Reference for NVIDIA's CLI

NVIDIA SkillSpector uses three distinct exit codes—0 for successful low-risk scans, 1 for high-risk detections exceeding the threshold, and 2 for execution failures—to enable reliable automation in CI/CD pipelines.

NVIDIA SkillSpector is a security scanning tool for AI skill bundles that communicates scan results through standardized exit codes. Understanding these exit codes is essential for integrating SkillSpector into automated workflows and interpreting scan outcomes programmatically. This guide breaks down each exit code based on the implementation in the NVIDIA/SkillSpector source code.

SkillSpector Exit Code Reference

The skillspector CLI, implemented in src/skillspector/cli.py, returns three specific exit codes that indicate scan status:

Exit Code 0: Success

When a scan completes without errors and the final risk score is less than or equal to the RISK_THRESHOLD (default 50), SkillSpector exits with code 0. This indicates the skill bundle is considered safe for deployment.

Exit Code 1: High Risk Detected

Exit code 1 indicates a security concern. The CLI raises typer.Exit(code=1) when (result.get("risk_score") or 0) > RISK_THRESHOLD, meaning the scan detected vulnerabilities exceeding the acceptable risk threshold.

Exit Code 2: Execution Error

Exit code 2 covers all failure conditions that prevent the scan from completing. The CLI raises typer.Exit(code=2) for FileNotFoundError or ValueError during input loading, unexpected exceptions during graph execution, or missing optional dependencies when launching the MCP server.

How Exit Codes Are Determined in the Source Code

The exit code logic resides in src/skillspector/cli.py and depends on the RISK_THRESHOLD constant defined in src/skillspector/constants.py.

Risk Threshold Comparison

The threshold comparison that determines exit code 1 appears in the CLI driver:

if (result.get("risk_score") or 0) > RISK_THRESHOLD:
    raise typer.Exit(code=1)

Exception Handling for Code 2

File-related and generic exceptions map to exit code 2:

except (FileNotFoundError, ValueError) as e:
    console.print(f"[red]Error:[/red] {e}")
    raise typer.Exit(code=2) from e
except Exception as e:
    # ...

    raise typer.Exit(code=2) from e

Threshold Constant Definition

The threshold value itself is defined in src/skillspector/constants.py:

RISK_THRESHOLD = 50

Configuring the Risk Threshold

While the default RISK_THRESHOLD is 50, this value can be modified in src/skillspector/constants.py before building from source. When the risk score produced by the graph execution in src/skillspector/graph.py exceeds this threshold, the CLI exits with code 1, signaling that the skill bundle requires review.

Practical Usage Examples

Checking exit codes in shell scripts:

# Successful scan (exit code 0)

skillspector scan ./my-skill/
echo $?  # Output: 0

# High-risk detection (exit code 1)

skillspector scan ./suspicious-skill/
echo $?  # Output: 1

# Execution error (exit code 2)

skillspector scan ./nonexistent-path/
echo $?  # Output: 2

Integrating into Python automation:

import subprocess

result = subprocess.run(
    ["skillspector", "scan", "my-skill/"],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("Scan passed: No high-risk findings")
elif result.returncode == 1:
    print("Scan flagged high risk: Review required")
elif result.returncode == 2:
    print("Scan failed: Check input and dependencies")

Summary

• Exit code 0 indicates a successful scan with risk score ≤ 50 (safe).
• Exit code 1 signals high-risk findings when the risk score exceeds RISK_THRESHOLD.
• Exit code 2 represents execution errors including missing files or dependency failures.
• The logic is implemented in src/skillspector/cli.py using typer.Exit().
• The threshold is defined as RISK_THRESHOLD = 50 in src/skillspector/constants.py.

Frequently Asked Questions

What does exit code 1 mean in SkillSpector?

Exit code 1 means the scan detected a risk score above the configured threshold (default 50), indicating potential security issues in the skill bundle that require manual review before deployment.

How can I change the threshold that triggers exit code 1?

Modify the RISK_THRESHOLD constant in src/skillspector/constants.py and rebuild the package, or check if your version supports the SKILLSPECTOR_RISK_THRESHOLD environment variable for runtime configuration.

Why does SkillSpector return exit code 2 when the file exists?

Exit code 2 typically indicates a ValueError during input parsing or missing optional dependencies (such as MCP server components) rather than simple file existence. Check the stderr output for specific error details.

Which source file contains the exit code logic?

The exit code determination logic is implemented in src/skillspector/cli.py, specifically in the scan command handler that compares the risk score against RISK_THRESHOLD and raises typer.Exit() with the appropriate code.

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