package-search

Vulnetix Package Search Skill

This skill searches for packages across ecosystems and provides a comprehensive security risk assessment before adding them as dependencies.

Output & Analysis Guidelines

Primary output format: Markdown. All reports, tables, summaries, and diffs MUST be presented as formatted markdown text directly — never generate scripts or programs to produce output that can be expressed as markdown.

Visual data — use Mermaid diagrams to display data visually when it aids comprehension. Mermaid renders natively in markdown and requires no external tools. Use it for:

• Dependency trees / upgrade paths → graph TD or graph LR
• Version comparison timelines → timeline
• Risk breakdowns → pie or quadrantChart
• Decision flow (add/skip/alternatives) → flowchart

Example — vulnerability distribution for a package:

pie title Vulnerability Severity "Critical" : 1 "High" : 2 "Medium" : 5 "Low" : 3

If uv is available, richer visualizations can be generated with Python (matplotlib, plotly) and saved to .vulnetix/:

command -v uv &>/dev/null && uv run --with matplotlib python3 -c '
import matplotlib.pyplot as plt
# ... generate chart ...
plt.savefig(".vulnetix/chart.png", dpi=150, bbox_inches="tight")
'

When Python charts are generated, display them inline and keep the Mermaid version as a text fallback.

Data processing — tooling cascade (strict order):

1. jq / yq + bash builtins (preferred) — jq for JSON, yq for YAML. Pipe to head, tail, cut, sed, grep, sort, uniq, wc for shaping.
2. uv (for complex analysis or charts) — If aggregation, statistics, or visualization beyond Mermaid are needed, check uv first:

``bash command -v uv &>/dev/null && uv run --with pandas,matplotlib python3 -c '...' ``

1. python3 stdlib (last resort) — Only if uv is unavailable. Use json, csv, collections, statistics modules — no pip dependencies:

``bash command -v python3 &>/dev/null && python3 -c 'import json, sys; ...' ``

Never assume any runtime is available — always check with command -v before use. If all programmatic tools are unavailable, analyze manually with the Read tool and present results as markdown with Mermaid diagrams.

Version detection commands (pip show, go list -m, cargo pkgid, etc.) are exempt — they query package managers directly and are tried as-available per the version detection priority in Step 1b.

Vulnerability Memory (.vulnetix/memory.yaml)

This skill reads the .vulnetix/memory.yaml file in the repository root to surface prior vulnerability history for packages being searched. This file is shared with /vulnetix:fix and /vulnetix:exploits.

At the start of every invocation:

1. Use Glob to check if .vulnetix/memory.yaml exists in the repo root
2. If it exists, use Read to load it
3. Use Glob for .vulnetix/scans/*.cdx.json — if CycloneDX SBOMs exist from prior scans (pre-commit hook or fix skill), cross-reference package names against SBOM component lists for additional vulnerability context

During risk assessment (Step 4):

1. For each package in the search results, check if any vulnerabilities in the memory file reference that package name
2. If prior entries exist, add a Known History column or section to the output:
3. List each vuln ID, its current status (in developer-friendly language), decision date, and CWSS priority if available
4. Example: CVE-2021-44228 — Fixed (2024-01-15), CVE-2023-1234 — Risk accepted (2024-03-01), P3 (52.0)
5. If pocs exist for a vuln, note: N PoC(s) on file — do not display PoC URLs or paths in package search output
6. If a package has unresolved vulnerabilities (affected or under_investigation), flag this prominently in the risk assessment. If CWSS priority is P1 or P2, add a warning: "Active exploit intelligence available — run /vulnetix:exploits <vuln-id> for details"

After completing the search:

1. If the search reveals new vulnerabilities (from vulnerabilityCount or maxSeverity in the API response) that are NOT already tracked in the memory file, record them as new entries with:
2. status: under_investigation
3. discovery.source: scan
4. discovery.sbom: path to the relevant .vulnetix/scans/*.cdx.json if one exists for this package's manifest
5. decision.choice: investigating
6. decision.reason: "Discovered via /vulnetix:package-search"
7. Append to history: event: discovered, detail: "Found via package search for <query>"

VEX-to-developer-language: When surfacing prior decisions, use developer-friendly language:

• not_affected → "Not affected", affected → "Vulnerable", fixed → "Fixed", under_investigation → "Investigating"

Dependabot Integration

When gh CLI is available (check with gh auth status 2>/dev/null), query Dependabot alerts for packages in the search results to enrich the risk assessment.

During Step 4 (Risk Assessment):

1. For each package in the results, check for open Dependabot alerts:

``bash gh api repos/{owner}/{repo}/dependabot/alerts?state=open --jq '[.[] | select(.dependency.package.name == "'"$PACKAGE_NAME"'")] | length' ``

1. If alerts exist, add a Dependabot Alerts column to the comparison table showing the count and highest severity
2. If a Dependabot PR exists for the package, note it: "Dependabot PR #N open for <package> upgrade"
3. If a prior memory entry for this package has a dependabot section, surface it in the Known History output:
4. Example: CVE-2021-44228 — Fixed (2024-01-15, Dependabot: merged PR #187)

During Step 5 (Propose Dependency Addition):

• If a Dependabot PR already proposes the same version upgrade, suggest reviewing and merging that PR instead of manual editing: "Dependabot PR #N already proposes this upgrade — consider merging it instead"

This avoids duplicate work and leverages Dependabot's existing CI validation.

Code Scanning (CodeQL) Integration

When gh CLI is available, check if CodeQL has flagged issues related to packages being searched. The canonical state-to-VEX mapping is defined in /vulnetix:fix.

During Step 4 (Risk Assessment):

1. For each package with known vulnerabilities, check if CodeQL alerts match the associated CWEs:

``bash gh api repos/{owner}/{repo}/code-scanning/alerts --jq '[.[] | select(.rule.tags[]? | test("CWE-<NUMBER>"; "i"))] | length' ``

1. If matching alerts exist, add a CodeQL Alerts column to the comparison table showing count and states
2. If a prior memory entry for this package has a code_scanning section, surface it in Known History:
3. Example: CVE-2021-44228 — Fixed (2024-01-15, CodeQL: alert #15 fixed)
4. If CodeQL default setup is not configured, note: "CodeQL not enabled — consider enabling for code-level detection"

During Step 5 (Propose Dependency Addition):

• If a CodeQL autofix is available for related alerts, mention it: "CodeQL also has an AI-suggested code fix for the related code pattern"

Secret Scanning Integration

When gh CLI is available, check for secret scanning alerts relevant to packages handling authentication or credentials.

During Step 4 (Risk Assessment):

1. If a package being evaluated handles auth/secrets (e.g., jsonwebtoken, bcrypt, passport, oauth2, crypto, keyring), check for open secret scanning alerts:

``bash gh api repos/{owner}/{repo}/secret-scanning/alerts?state=open --jq 'length' ``

1. If active secrets exist alongside a package that handles credentials, flag: "Active secrets detected in this repo — adding/upgrading this package should include a secret rotation review"
2. If a prior memory entry has a secret_scanning section, surface it in Known History

Workflow

Step 1: Detect Repository Ecosystems

Check cached manifest data first: If .vulnetix/memory.yaml has a