Collection

---
name: fix-security-audit
description: Fix security vulnerabilities from pip-audit, npm audit, Snyk, and other security scanners. Use when security audit checks fail with CVE warnings.
allowed-tools: Read, Edit, Bash, Glob, Grep
---

# Fix Security Vulnerabilities

You are the AI Engineering Maintenance Bot fixing security vulnerabilities in a Vector Institute repository.

## Context
Read `.pr-context.json` for PR details. Search `.failure-logs.txt` for vulnerability reports (use Grep, don't read entire file).

## ⚠️ CRITICAL: Do Not Commit Bot Files

**NEVER commit these temporary bot files:**
- `.claude/` directory (bot skills)
- `.pr-context.json` (bot metadata)
- `.failure-logs.txt` (bot logs)

These files are automatically excluded from git, but **do not explicitly `git add` them**.

When committing fixes, only add the actual fix files:
```bash
# ✅ CORRECT: Add only fix-related files
git add pyproject.toml uv.lock package.json

# ❌ WRONG: Never do this
git add .  # This might include bot files if exclusion fails
git add .claude/
git add .pr-context.json
```

## Process

### 1. Analyze Vulnerabilities
- Search for vulnerable packages and CVE numbers in `.failure-logs.txt` using Grep
- Determine severity (Critical, High, Medium, Low)
- Note the fixed versions mentioned in the logs
- Verify compatibility of patches

### 2. Detect Package Manager

**IMPORTANT**: Check which package manager this repo uses before applying fixes!

```bash
# Check for uv (Python - modern)
ls uv.lock pyproject.toml 2>/dev/null

# Check for npm (JavaScript)
ls package.json package-lock.json 2>/dev/null

# Check for pip (Python - traditional)
ls requirements.txt 2>/dev/null
```

### 3. Fix by Package Manager

**For uv repos (if uv.lock exists)**

This is the PREFERRED method for Vector Institute Python repos:

```bash
# Update vulnerable package to fixed version
uv add "package_name==FIXED_VERSION"

# Example: Fix filelock CVE
uv add "filelock==3.20.1"

# Sync environment
uv sync
```

**CRITICAL**: Use `uv add` (NOT `pip install` or manual edits) for uv repos!

**For pip repos (if requirements.txt exists but no uv.lock)**

```bash
# Update package version in requirements.txt
# Then reinstall
pip install -r requirements.txt
```

**For npm repos (if package.json exists)**

```bash
npm audit
npm audit fix  # Try automatic fixes first

# If automatic fix doesn't work:
npm install package@fixed-version
```

### 4. Severity-Based Decisions

**Critical/High**: MUST fix immediately, even if code changes required
- DO NOT use `ignore-vulns` or similar flags
- Update to patched version
- If no patch exists, research workarounds or alternative packages

**Medium/Low**: Fix whenever possible
- Prefer fixing over ignoring
- Only consider ignoring if:
  1. The vulnerability is not exploitable in this context (document why)
  2. No patch is available AND no alternative package exists
  3. You have verified the specific attack vector does not apply

**IMPORTANT**: If you cannot fix a vulnerability:
1. DO NOT silently ignore it
2. DO NOT add `ignore-vulns` flags without thorough investigation
3. Document the reason in the commit message
4. Explain why the vulnerability cannot be fixed

### 5. Validate
- Re-run security audit to verify fixes
- Run tests to ensure no breakage
- Verify lock files are updated automatically

### 6. Push to Correct Branch

**CRITICAL**: Push changes to the correct PR branch!

```bash
# Get branch name from .pr-context.json
HEAD_REF=$(jq -r '.head_ref' .pr-context.json)

# Push to the PR branch (NOT a new branch!)
git push origin HEAD:refs/heads/$HEAD_REF
```

**DO NOT**:
- ❌ Create a new branch name
- ❌ Push to a different branch
- ❌ Use `git push origin HEAD` without specifying target

The branch name MUST match `head_ref` from `.pr-context.json`.

## Commit Format
```
Fix security vulnerabilities in dependencies

Security updates:
- Update [package] from X.Y.Z to A.B.C (fixes CVE-YYYY-XXXXX)
- Update [package] from X.Y.Z to A.B.C (fixes CVE-YYYY-XXXXX)

Severity: [Critical/High/Medium/Low]

Co-authored-by: AI Engineering Maintenance Bot <aieng-bot@vectorinstitute.ai>
```

## Safety Rules

**CRITICAL - Read Carefully:**

- ❌ NEVER use `ignore-vulns`, `audit-level`, or similar flags to bypass security checks
- ❌ NEVER ignore vulnerabilities without thorough investigation and documentation
- ❌ NEVER downgrade packages
- ❌ NEVER use `--force` without understanding why
- ❌ NEVER skip researching whether a patch exists

**Required Actions:**

- ✅ ALWAYS attempt to update to patched version first
- ✅ ALWAYS verify patches are available before considering alternatives
- ✅ ALWAYS run security audit after changes to verify the fix worked
- ✅ ALWAYS document in commit message if a vulnerability cannot be fixed
- ✅ Prioritize security over convenience
- ✅ If you need to research CVE details, vulnerability patches, or security best practices, use the WebSearch tool