Vulnerability Resolver Skill Requirements

Vulnerability Resolver Skill Requirements

Executive Summary

The Vulnerability Resolver skill provides automated assistance for managing security vulnerabilities detected by OWASP Dependency-Check. It enables developers to efficiently triage, fix, or suppress CVEs while maintaining a documented audit trail of security decisions.

Background

Context

FINOS active projects require CVE scanning alongside Dependabot. morphir-dotnet implemented OWASP Dependency-Check scanning in PR #273, which runs:

• On push/PR to main
• Weekly on Monday at 3:00 UTC
• Fails builds on CVSS score >= 7

PR #276 addressed initial vulnerabilities, identifying that some reported CVEs were false positives due to binary scanning misidentification of package versions or confusion with similarly-named packages.

Problem Statement

When dependency scanning detects vulnerabilities:

1. Developers must manually research each CVE to determine if it’s genuine or a false positive
2. There’s no standardized process for documenting suppression decisions
3. Suppression files must be manually created following OWASP Dependency-Check XML schema
4. No easy way to trigger scans on specific branches during development
5. No guided workflow for fix vs. suppress decisions

Success Criteria

1. Automation: Reduce manual effort for vulnerability resolution by 70%
2. Documentation: 100% of suppressions have documented rationale
3. Auditability: Clear audit trail for all security decisions
4. Developer Experience: Interactive prompts guide users through resolution
5. CI Integration: Ability to trigger scans on any branch

Functional Requirements

FR-1: Scan Triggering

FR-1.1: Trigger dependency-check workflow on any branch

# Example invocation
@skill vulnerability-resolver
Scan branch feature/new-dependency for vulnerabilities

FR-1.2: Support manual workflow dispatch with parameters:

• Branch/ref to scan
• Fail threshold (CVSS score, default 7)
• Output format (HTML, JSON, XML)
• Suppression file path

FR-1.3: Report scan status and provide link to workflow run

FR-2: Vulnerability Analysis

FR-2.1: Parse dependency-check reports (HTML, JSON, XML formats)

FR-2.2: For each vulnerability, extract:

• CVE identifier
• CVSS score and severity
• Affected package/file
• Package identifier (purl, CPE)
• Description and references
• Whether it’s a transitive dependency

FR-2.3: Categorize vulnerabilities by:

• Severity (Critical, High, Medium, Low)
• Fix availability (update available, no fix, N/A)
• False positive likelihood (based on patterns)

FR-3: Interactive Resolution

FR-3.1: Present vulnerabilities with resolution options:

CVE-2022-4742 (CVSS 9.8) in JsonPointer.Net@6.0.0

Options:
1. Fix: Update to version 6.0.1 (recommended)
2. Suppress: Mark as false positive with reason
3. Skip: Handle later
4. Research: Open CVE details in browser

FR-3.2: For each resolution choice:

• Fix: Generate package update commands, verify fix in scan
• Suppress: Create/update suppression XML with documented rationale
• Skip: Track for follow-up, don’t block

FR-3.3: Detect false positive patterns:

• Version misidentification in binary scanning
• Package name confusion (e.g., Cecil vs Mono.Cecil)
• Already-fixed transitive dependencies
• Suggest suppression when patterns match

FR-4: Suppression Management

FR-4.1: Create and manage suppression file (dependency-check-suppressions.xml)

FR-4.2: Suppression file structure following OWASP schema:

<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.3.xsd">
  <suppress until="2025-12-31">
    <notes><![CDATA[
      False positive: CVE-2023-4914 targets Cecil static site generator,
      not Mono.Cecil library. Verified package source.
      Suppressed by: @username
      Date: 2024-01-15
      Review: Quarterly
    ]]></notes>
    <cve>CVE-2023-4914</cve>
  </suppress>
</suppressions>

FR-4.3: Suppression methods supported:

• By CVE identifier
• By package URL (purl)
• By CPE
• By file path (regex)
• By SHA1 hash

FR-4.4: Required suppression metadata:

• Reason for suppression
• Who approved the suppression
• Date of suppression
• Review date (recommended: quarterly)
• Optional expiration date (until attribute)

FR-4.5: Integrate suppression file with workflow:

args: >
  --failOnCVSS 7
  --enableRetired
  --suppression ./dependency-check-suppressions.xml

FR-5: Fix Automation

FR-5.1: Generate fix commands for different package managers:

# NuGet (Directory.Packages.props)
# Update JsonPointer.Net from 6.0.0 to 6.0.1

# In Directory.Packages.props:
<PackageVersion Include="JsonPointer.Net" Version="6.0.1" />

FR-5.2: Verify fix effectiveness:

• Check if new version resolves CVE
• Warn if update introduces breaking changes
• Validate update doesn’t introduce new CVEs

FR-5.3: Handle transitive dependencies:

• Identify which direct dependency pulls the vulnerable package
• Suggest upgrade path
• Note when fix requires waiting for upstream update

FR-6: Reporting and Documentation

FR-6.1: Generate resolution summary:

## Vulnerability Resolution Summary

**Scan Date**: 2024-01-15
**Branch**: main
**Total Vulnerabilities**: 4

### Fixed (1)
- CVE-2022-4742 in JsonPointer.Net: Updated 6.0.0 → 6.0.1

### Suppressed (3)
- CVE-2023-36415 in Azure.Identity: Already fixed in 1.17.1 (transitive)
- CVE-2023-4914 in Mono.Cecil.Mdb: False positive (different package)
- CVE-2012-2055 in Octokit: Not applicable to this library

### Pending (0)
None

FR-6.2: Maintain resolution history for audit purposes

FR-6.3: Generate PR description for vulnerability fixes

Non-Functional Requirements

NFR-1: Security

• Never expose actual vulnerability details in logs
• Suppression decisions must be committed to version control
• Support for security team review workflow

NFR-2: Performance

• Skill invocation < 5 seconds for analysis
• Report parsing < 10 seconds for typical reports
• No impact on regular CI pipeline speed

NFR-3: Maintainability

• Follow existing skill template patterns
• Reusable scripts for automation
• Clear documentation for manual fallback

NFR-4: Auditability

• All suppressions traceable to commits
• Suppression history preserved
• Quarterly review reminders

Technical Design

Workflow Modifications

Update .github/workflows/cve-scanning.yml to support:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 3 * * 1'
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to scan'
        required: false
        default: 'main'
      fail-cvss:
        description: 'Fail on CVSS score >= N'
        required: false
        default: '7'
      suppression-file:
        description: 'Path to suppression file'
        required: false
        default: './dependency-check-suppressions.xml'

Skill Files Structure

.claude/skills/vulnerability-resolver/
├── SKILL.md              # Main skill definition
├── README.md             # Quick reference
├── MAINTENANCE.md        # Maintenance guide
├── scripts/
│   ├── scan-branch.fsx          # Trigger scan on branch
│   ├── parse-report.fsx         # Parse DC reports
│   ├── create-suppression.fsx   # Generate suppression XML
│   └── verify-fixes.fsx         # Verify CVE fixes
└── templates/
    ├── suppression-entry.xml    # Suppression template
    └── resolution-summary.md    # Summary template

Integration Points

QA Tester Skill: Coordinate for regression testing after dependency updates Release Manager Skill: Ensure no unresolved vulnerabilities before release AOT Guru Skill: Verify dependency updates don’t break AOT compatibility

User Stories

US-1: Developer Fixes Vulnerability

As a developer, when the dependency check fails, I want to quickly identify which vulnerabilities are genuine and how to fix them so I can unblock my PR.

US-2: Security Review for False Positive

As a developer, when I identify a false positive, I want to suppress it with proper documentation so future scans don’t flag the same issue.

US-3: Pre-merge Vulnerability Check

As a developer, I want to check my branch for vulnerabilities before creating a PR so I can address issues proactively.

US-4: Quarterly Security Review

As a maintainer, I want to review all active suppressions quarterly to ensure they’re still valid and no fixes have become available.

US-5: Audit Trail

As a security auditor, I want to see a complete history of vulnerability decisions so I can verify the project follows security best practices.

Implementation Phases

Phase 1: Core Infrastructure (MVP)

• Update workflow for manual dispatch
• Create suppression file with initial false positives
• Basic skill definition with manual resolution workflow
• Create GitHub issue for tracking

Phase 2: Automation

• Report parsing scripts
• Suppression generation scripts
• Fix verification scripts
• Interactive resolution prompts

Phase 3: Integration

• Integration with other skills
• Quarterly review automation
• Resolution history tracking
• PR description generation

Appendix

A. Known False Positive Patterns

B. OWASP Dependency-Check References

• Suppression Files
• GitHub Action
• Analyzer Reference

C. Related Issues/PRs

• #272: Add code scanning tools to the repo
• #273: Add CVE scanning workflow for vulnerability detection
• #275: Fix reported dependency vulnerabilities
• #276: Fix CVE-2022-4742 by updating JsonPointer.Net

Document Version: 1.0.0 Status: Draft Author: Claude Code Date: 2024-12-19