package-search

What this skill does

# 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:
````markdown
```mermaid
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/`:
```bash
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 '...'
   ```
3. **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:
   - List each vuln ID, its current status (in developer-friendly language), decision date, and CWSS priority if available
   - Example: `CVE-2021-44228 — Fixed (2024-01-15)`, `CVE-2023-1234 — Risk accepted (2024-03-01), P3 (52.0)`
   - If `pocs` exist for a vuln, note: `N PoC(s) on file` — do not display PoC URLs or paths in package search output
3. 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:
   - `status: under_investigation`
   - `discovery.source: scan`
   - `discovery.sbom`: path to the relevant `.vulnetix/scans/*.cdx.json` if one exists for this package's manifest
   - `decision.choice: investigating`
   - `decision.reason: "Discovered via /vulnetix:package-search"`
2. 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'
   ```
2. If alerts exist, add a **Dependabot Alerts** column to the comparison table showing the count and highest severity
3. If a Dependabot PR exists for the package, note it: `"Dependabot PR #N open for <package> upgrade"`
4. If a prior memory entry for this package has a `dependabot` section, surface it in the Known History output:
   - 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'
   ```
2. If matching alerts exist, add a **CodeQL Alerts** column to the comparison table showing count and states
3. If a prior memory entry for this package has a `code_scanning` section, surface it in Known History:
   - 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'
   ```
2. 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"
3. 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