Skip to content

Commit 2b0d4fc

Browse files
DamianReevesDamianReeves
authored
feat: implement Vulnerability Resolver skill for CVE management (#282)
* feat: implement Vulnerability Resolver skill for CVE management - Add vulnerability-resolver skill with SKILL.md, README.md, MAINTENANCE.md - Create suppression and resolution summary templates - Update CVE scanning workflow with manual dispatch support - Add branch, fail-cvss, and enable-suppressions parameters - Integrate suppression file for false positive handling - Create dependency-check-suppressions.xml with documented false positives: - CVE-2023-36415 (Azure.Identity) - version misidentification - CVE-2023-4914 (Mono.Cecil) - package name confusion - CVE-2012-2055 (Octokit) - stale CVE not applicable - Add comprehensive PRD in docs/contributing/design/prds/ - Update skills-reference.md and CLAUDE.md with new skill The skill provides: - Scan triggering on any branch via workflow_dispatch - Evidence-based false positive detection patterns - Interactive fix vs. suppress decision guidance - Documented suppressions with required metadata - Quarterly review process for security posture Fixes #281 🤖 Generated with [Claude Code](https://claude.com/claude-code) * fix: enable suppressions by default for all CVE scan triggers The previous logic only enabled suppressions when inputs.enable-suppressions was explicitly true, which didn't work for non-dispatch triggers (push, PR, schedule) where the input is undefined. Now suppressions are enabled by default for all triggers. Use workflow_dispatch with enable-suppressions=false to see all vulnerabilities without filtering. 🤖 Generated with [Claude Code](https://claude.com/claude-code) * refactor: move suppression file to .github/vuln-scanning/ Organize vulnerability scanning files in a dedicated directory: - Move dependency-check-suppressions.xml to .github/vuln-scanning/ - Update workflow to reference new path - Update skill documentation with new location 🤖 Generated with [Claude Code](https://claude.com/claude-code) * fix(ci): correct suppression file conditional for non-dispatch triggers The previous expression `inputs.enable-suppressions != false` did not work correctly when inputs.enable-suppressions was null/undefined (for push, PR, and schedule triggers). Changed to `inputs.enable-suppressions == false` which correctly defaults to including the suppression file unless explicitly disabled via workflow_dispatch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) * fix(security): update suppressions for expired and new false positives - Extended CVE-2023-36415 suppression expiration to 2026-03-31 (was expired at 2025-06-30) - Added CVE-2022-4742 suppression - false positive due to package name confusion between JavaScript json-pointer npm package and .NET JsonPointer.Net library (prototype pollution is JS-specific) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent 1b25725 commit 2b0d4fc

File tree

10 files changed

+1893
-3
lines changed

10 files changed

+1893
-3
lines changed

‎.agents/skills-reference.md‎

Lines changed: 191 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
The morphir-dotnet project provides specialized expert skills for domain-specific tasks. Each skill combines deep domain knowledge, automation scripts, and review capabilities to help agents deliver higher quality results more efficiently.
88

99
**Key Features:**
10-
- **Domain Expertise**: Specialized knowledge in QA testing, AOT optimization, release management, and technical documentation
10+
- **Domain Expertise**: Specialized knowledge in QA testing, AOT optimization, release management, technical documentation, and vulnerability management
1111
- **Automation Scripts**: F# scripts that save agent tokens and accelerate common tasks
1212
- **Review Capabilities**: Built-in quality checks and continuous monitoring
1313
- **Cross-Agent Compatible**: Accessible via documentation and scripts regardless of your agent
@@ -16,7 +16,7 @@ The morphir-dotnet project provides specialized expert skills for domain-specifi
1616

1717
**For Claude Code Users:**
1818
- Skills are available as interactive tools via `@skill {skill-name}`
19-
- Examples: `@skill qa-tester`, `@skill aot-guru`, `@skill release-manager`, `@skill technical-writer`
19+
- Examples: `@skill qa-tester`, `@skill aot-guru`, `@skill release-manager`, `@skill technical-writer`, `@skill vulnerability-resolver`
2020
- Skills can run automation scripts and provide guided assistance
2121
- **Note**: Some skills document common aliases, but these are **not supported** by Claude Code (documentation only)
2222

@@ -47,6 +47,9 @@ Prepare release for version 1.0.0
4747
4848
@skill technical-writer
4949
Audit documentation for consistency and completeness
50+
51+
@skill vulnerability-resolver
52+
Scan for CVEs and help resolve security vulnerabilities
5053
```
5154

5255
**Features**:
@@ -1076,6 +1079,191 @@ Important content here
10761079

10771080
---
10781081

1082+
### 5. Vulnerability Resolver
1083+
1084+
**Full Documentation**: [.claude/skills/vulnerability-resolver/SKILL.md](../.claude/skills/vulnerability-resolver/SKILL.md)
1085+
1086+
#### Scope and Purpose
1087+
Specialized security vulnerability management for morphir-dotnet. Helps developers efficiently triage, fix, and document security vulnerabilities detected by OWASP Dependency-Check, maintaining a clear audit trail of all security decisions.
1088+
1089+
#### Core Competencies
1090+
1091+
1. **Vulnerability Scanning**
1092+
- Trigger dependency-check scans on any branch
1093+
- Configure CVSS thresholds
1094+
- Monitor workflow progress
1095+
- Download and analyze reports
1096+
1097+
2. **Vulnerability Analysis**
1098+
- Parse dependency-check reports (HTML, JSON, XML)
1099+
- Categorize by severity (Critical, High, Medium, Low)
1100+
- Assess fix availability and false positive likelihood
1101+
- Identify transitive dependency issues
1102+
1103+
3. **Resolution Guidance**
1104+
- Interactive fix vs. suppress decision prompts
1105+
- Evidence-based false positive detection
1106+
- Clear resolution options with trade-offs
1107+
- Research assistance with NVD links
1108+
1109+
4. **Suppression Management**
1110+
- Create documented suppressions for false positives
1111+
- Follow OWASP suppression file schema
1112+
- Required metadata (reason, reviewer, date, review date)
1113+
- Support for expiration dates
1114+
1115+
5. **Fix Automation**
1116+
- Generate package update commands
1117+
- Verify fix effectiveness with re-scan
1118+
- Handle transitive dependency upgrades
1119+
- Detect breaking changes
1120+
1121+
6. **Security Documentation**
1122+
- Resolution summaries for audit trail
1123+
- Suppression rationale with evidence
1124+
- Quarterly review reminders
1125+
- PR descriptions for security fixes
1126+
1127+
#### Review Capability
1128+
1129+
**Suppression Review**
1130+
- Quarterly review of all active suppressions
1131+
- Check if fixes have become available
1132+
- Validate suppression rationale still applies
1133+
- Update expiration dates
1134+
1135+
**Security Posture Assessment**
1136+
- Unresolved vulnerability tracking
1137+
- Suppression quality checks
1138+
- New fix availability detection
1139+
- Documentation completeness
1140+
1141+
**Review Triggers:**
1142+
- Quarterly scheduled review
1143+
- Before releases (pre-release gate)
1144+
- After dependency updates
1145+
- Manual via `@skill vulnerability-resolver review`
1146+
1147+
#### Automation Scripts
1148+
1149+
Location: `.claude/skills/vulnerability-resolver/scripts/` (to be created)
1150+
1151+
**scan-branch.fsx**
1152+
- Trigger CVE scan on specified branch
1153+
- Configure CVSS threshold and suppression settings
1154+
- **Token Savings**: ~500 tokens (vs manual workflow triggering)
1155+
1156+
**parse-report.fsx**
1157+
- Parse dependency-check HTML/JSON report
1158+
- Extract CVE details and categorize
1159+
- **Token Savings**: ~2000 tokens (vs manual report reading)
1160+
1161+
**create-suppression.fsx**
1162+
- Generate properly formatted suppression XML
1163+
- Include required metadata
1164+
- **Token Savings**: ~300 tokens (vs manual XML creation)
1165+
1166+
**verify-fixes.fsx**
1167+
- Verify package updates resolve CVEs
1168+
- Re-run scan after fix
1169+
- **Token Savings**: ~400 tokens (vs manual verification)
1170+
1171+
#### Manual Workflow for Non-Claude Agents
1172+
1173+
**To scan for vulnerabilities:**
1174+
```bash
1175+
# Option 1: Use automation script
1176+
dotnet fsi .claude/skills/vulnerability-resolver/scripts/scan-branch.fsx [branch]
1177+
1178+
# Option 2: Manual trigger
1179+
gh workflow run cve-scanning.yml
1180+
gh workflow run cve-scanning.yml --ref feature/my-branch
1181+
gh workflow run cve-scanning.yml -f fail-cvss=9
1182+
```
1183+
1184+
**To monitor a scan:**
1185+
```bash
1186+
gh run list --workflow=cve-scanning.yml --limit 3
1187+
gh run watch <run-id>
1188+
gh run download <run-id> -n "Depcheck report"
1189+
```
1190+
1191+
**To create a suppression:**
1192+
```bash
1193+
# Option 1: Use automation script
1194+
dotnet fsi .claude/skills/vulnerability-resolver/scripts/create-suppression.fsx \
1195+
--cve CVE-2023-4914 --reason "Package name confusion"
1196+
1197+
# Option 2: Use template
1198+
cp .claude/skills/vulnerability-resolver/templates/suppression-entry.xml .
1199+
# Fill in template and add to dependency-check-suppressions.xml
1200+
```
1201+
1202+
#### Decision Trees
1203+
1204+
**"A CVE scan failed, what do I do?"**
1205+
```
1206+
1. Download the report artifact
1207+
gh run download <run-id> -n "Depcheck report"
1208+
1209+
2. For each vulnerability:
1210+
A. Is CVSS >= 7 (High/Critical)?
1211+
YES → Prioritize resolution
1212+
NO → Can address in normal sprint
1213+
1214+
B. Is update available?
1215+
YES → Check if breaking change, apply update
1216+
NO → Investigate if false positive
1217+
1218+
C. False positive indicators present?
1219+
- Version mismatch (assembly vs package)
1220+
- Package name confusion
1221+
- Stale CVE (age > 5 years)
1222+
- CVE targets different technology
1223+
1224+
YES → Create documented suppression with evidence
1225+
NO → Track upstream, document workaround
1226+
```
1227+
1228+
**"Should I suppress or fix?"**
1229+
```
1230+
Can I update the package?
1231+
├─ YES, minor/patch update → FIX (preferred)
1232+
├─ YES, but major update
1233+
│ └─ CVSS >= 9? → FIX with migration
1234+
│ └─ CVSS < 9 → Suppress temporarily + plan upgrade
1235+
└─ NO, no fix available
1236+
└─ False positive?
1237+
├─ YES → SUPPRESS with documentation
1238+
└─ NO → Document risk, track upstream
1239+
```
1240+
1241+
#### Pattern Catalog
1242+
1243+
**False Positive Patterns:**
1244+
1245+
| Pattern | Detection | Example |
1246+
|---------|-----------|---------|
1247+
| Version Misidentification | Unusual version format | Azure.Identity@1.1700.x (assembly version, not package) |
1248+
| Package Name Confusion | CVE mentions different tech | Cecil (SSG) vs Mono.Cecil (.NET library) |
1249+
| Stale CVE | CVE date >> package date | CVE-2012-2055 for Octokit@14.0.0 |
1250+
| Already Fixed Transitive | Lock file shows newer version | Transitive at 1.17.1 but reported as 1.10.0 |
1251+
1252+
**Suppression Best Practices:**
1253+
- Always include detailed rationale
1254+
- Provide evidence for false positive claim
1255+
- Set expiration dates for time-limited suppressions
1256+
- Review suppressions quarterly
1257+
- Never suppress without documentation
1258+
1259+
#### Integration with Other Skills
1260+
1261+
- **QA Tester**: Run regression tests after dependency updates
1262+
- **Release Manager**: Pre-release security verification gate
1263+
- **AOT Guru**: Verify dependency updates don't break AOT compatibility
1264+
1265+
---
1266+
10791267
## Cross-Agent Compatibility
10801268

10811269
See [capabilities-matrix.md](./capabilities-matrix.md) for detailed cross-agent compatibility information.
@@ -1145,6 +1333,7 @@ Savings: ~500-700 tokens (60-70% reduction)
11451333
- [AOT Guru](../.claude/skills/aot-guru/skill.md)
11461334
- [Release Manager](../.claude/skills/release-manager/skill.md)
11471335
- [Technical Writer](../.claude/skills/technical-writer/SKILL.md)
1336+
- [Vulnerability Resolver](../.claude/skills/vulnerability-resolver/SKILL.md)
11481337

11491338
2. **Run automation scripts directly**:
11501339
```bash

‎.claude/skills/vulnerability-resolver/MAINTENANCE.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Vulnerability Resolver Skill Maintenance Guide
2+
3+
## Overview
4+
5+
This document provides guidance for maintaining and evolving the Vulnerability Resolver skill.
6+
7+
## Maintenance Schedule
8+
9+
### Weekly
10+
- Monitor CVE scanning workflow runs
11+
- Address any new vulnerabilities in main branch
12+
13+
### Quarterly
14+
- Review all active suppressions
15+
- Check if fixes became available for suppressed CVEs
16+
- Update expiration dates as appropriate
17+
- Generate quarterly security summary
18+
19+
### On Dependency Updates
20+
- Verify updates don't introduce new vulnerabilities
21+
- Remove obsolete suppressions
22+
- Update documentation if patterns change
23+
24+
## Key Maintenance Tasks
25+
26+
### 1. Suppression File Hygiene
27+
28+
**Review suppressions quarterly:**
29+
```bash
30+
# List all suppressions with expiration dates
31+
grep -E "(until=|<cve>)" .github/vuln-scanning/dependency-check-suppressions.xml
32+
33+
# Check for expired suppressions
34+
# Look for dates before current date
35+
```
36+
37+
**For each suppression, verify:**
38+
- [ ] Rationale is still valid
39+
- [ ] No fix has become available
40+
- [ ] Documentation is complete
41+
- [ ] Expiration date is appropriate
42+
43+
### 2. Workflow Updates
44+
45+
**When OWASP Dependency-Check releases updates:**
46+
1. Check for new features or breaking changes
47+
2. Update action version in workflow if needed
48+
3. Test workflow with new version
49+
4. Update skill documentation if behavior changes
50+
51+
**Current workflow version:**
52+
```yaml
53+
uses: dependency-check/Dependency-Check_Action@1b5d19fd4a32ff0ff982e8c9d8e27dbf7ac8a46c
54+
```
55+
56+
### 3. Pattern Catalog Updates
57+
58+
**Add new patterns when discovered:**
59+
1. Document the false positive pattern
60+
2. Add detection criteria
61+
3. Provide resolution template
62+
4. Update SKILL.md pattern catalog
63+
64+
### 4. Script Maintenance
65+
66+
**Scripts to maintain:**
67+
- `scripts/scan-branch.fsx` - Workflow triggering
68+
- `scripts/parse-report.fsx` - Report parsing
69+
- `scripts/create-suppression.fsx` - Suppression generation
70+
71+
**When to update scripts:**
72+
- GitHub CLI changes
73+
- Report format changes
74+
- New suppression methods added
75+
76+
## Troubleshooting
77+
78+
### Common Issues
79+
80+
**Workflow fails but no vulnerabilities:**
81+
- Check if suppression file syntax is valid
82+
- Verify suppression file path in workflow
83+
- Check GitHub Actions logs for errors
84+
85+
**False positive not suppressed:**
86+
- Verify CVE ID matches exactly
87+
- Check suppression XML syntax
88+
- Confirm suppression file is enabled
89+
90+
**Report not uploaded:**
91+
- Check artifact upload step
92+
- Verify reports directory exists
93+
- Check disk space in runner
94+
95+
### Debugging
96+
97+
```bash
98+
# Validate suppression XML syntax
99+
xmllint --noout dependency-check-suppressions.xml
100+
101+
# Run scan locally (requires dependency-check CLI)
102+
dependency-check --project morphir-dotnet --scan . --format HTML --out reports
103+
104+
# Check workflow logs
105+
gh run view <run-id> --log
106+
```
107+
108+
## Version History
109+
110+
| Version | Date | Changes |
111+
|---------|------|---------|
112+
| 1.0.0 | 2024-12-19 | Initial release |
113+
114+
## Related Documentation
115+
116+
- [SKILL.md](./SKILL.md) - Full skill definition
117+
- [README.md](./README.md) - Quick reference
118+
- [Requirements PRD](../../../docs/content/docs/contributing/design/prds/vulnerability-resolver-skill-requirements.md)
119+
120+
## Contact
121+
122+
For questions or issues:
123+
- Create issue with label `skill:vulnerability-resolver`
124+
- Tag @morphir-dotnet/maintainers

0 commit comments

Comments
 (0)