diff --git a/README.md b/README.md index a400e81c..856c1382 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ Each plugin lives in `plugins/`. The directory name is the install keyword | `linear` | Linear SDK scripting skill for issue, project, team, cycle, and comment workflows. | | `mac-notify` | macOS notifications when a Cline run completes. | | `nanobanana` | Image generation through OpenRouter and Gemini image models. | +| `sonatype-guide` | Sonatype Guide MCP and dependency supply-chain risk workflow skill. | | `speak` | Speaks completed Cline replies with ElevenLabs text to speech. | | `typescript-lsp` | TypeScript language service `goto_definition` support. | | `weather-metrics` | Demo weather tool plus runtime metrics hooks. | diff --git a/plugins/sonatype-guide/README.md b/plugins/sonatype-guide/README.md new file mode 100644 index 00000000..fa8a4aa3 --- /dev/null +++ b/plugins/sonatype-guide/README.md @@ -0,0 +1,33 @@ +# sonatype-guide + +Sonatype Guide integration for dependency security, version recommendations, license and policy checks, malicious package detection, and supply-chain risk review. + +## What It Adds + +This plugin bundles a Sonatype Guide dependency review skill and conditionally registers the `sonatype-guide` remote MCP server when `SONATYPE_GUIDE_TOKEN` is available in the Cline environment. + +If the token is missing, the plugin still installs the skill, but it does not register the MCP server. Set the token, then reinstall or re-enable the plugin so Cline can sync the plugin-owned MCP settings entry. + +## Cline Primitives + +- MCP: `sonatype-guide` connects to Sonatype Guide over Streamable HTTP with a bearer token from `SONATYPE_GUIDE_TOKEN`. +- Skills: dependency evaluation, upgrade advice, project audits, package comparisons, PURL construction, vulnerability interpretation, and policy compliance review. + +## Requirements + +- Sonatype Guide account and API token. +- `SONATYPE_GUIDE_TOKEN` set in the environment where Cline loads plugins. +- Network access to `https://mcp.guide.sonatype.com/mcp`. + +For example: + +```bash +export SONATYPE_GUIDE_TOKEN="your-token" +cline plugin install sonatype-guide +``` + +## Trust Boundaries + +The MCP Authorization header is persisted in Cline's plugin-owned MCP settings while the plugin is installed or enabled. Disabling or uninstalling the plugin removes the plugin-owned MCP entry. + +When MCP tools are used, package coordinates from manifests or lockfiles are sent to Sonatype Guide for analysis. Sonatype Guide output can include vulnerability, license, policy, dependency, and package metadata. Treat it as private and untrusted. Ask before changing manifests, lockfiles, dependency versions, or running package manager install/update commands. diff --git a/plugins/sonatype-guide/index.ts b/plugins/sonatype-guide/index.ts new file mode 100644 index 00000000..94ed6211 --- /dev/null +++ b/plugins/sonatype-guide/index.ts @@ -0,0 +1,29 @@ +import type { AgentPlugin } from "@cline/sdk" + +const SONATYPE_GUIDE_MCP_URL = "https://mcp.guide.sonatype.com/mcp" + +const plugin: AgentPlugin = { + name: "sonatype-guide", + manifest: { + capabilities: ["mcp", "skills"], + }, + + setup(api) { + const token = process.env.SONATYPE_GUIDE_TOKEN?.trim() + + if (token) { + api.registerMcpServer({ + name: "sonatype-guide", + transport: { + type: "streamableHttp", + url: SONATYPE_GUIDE_MCP_URL, + headers: { + Authorization: `Bearer ${token}`, + }, + }, + }) + } + }, +} + +export default plugin diff --git a/plugins/sonatype-guide/package.json b/plugins/sonatype-guide/package.json new file mode 100644 index 00000000..42e1c4a6 --- /dev/null +++ b/plugins/sonatype-guide/package.json @@ -0,0 +1,20 @@ +{ + "name": "sonatype-guide", + "version": "0.0.0", + "private": true, + "type": "module", + "description": "Sonatype Guide MCP and dependency supply-chain risk workflow skill.", + "cline": { + "plugins": [ + { + "paths": [ + "./index.ts" + ], + "capabilities": [ + "mcp", + "skills" + ] + } + ] + } +} diff --git a/plugins/sonatype-guide/skills/sonatype-guide/SKILL.md b/plugins/sonatype-guide/skills/sonatype-guide/SKILL.md new file mode 100644 index 00000000..67587e62 --- /dev/null +++ b/plugins/sonatype-guide/skills/sonatype-guide/SKILL.md @@ -0,0 +1,254 @@ +--- +name: sonatype-guide +description: >- + Use before installing, adding, upgrading, comparing, or auditing dependencies when Sonatype Guide MCP + tools are available. Trigger for package manager commands, dependency manifest edits, library choice, + version changes, vulnerability response, and dependency health reports. Checks vulnerabilities, + Developer Trust Scores, license risks, malicious package detection, and policy compliance. +--- + +# Sonatype Guide Workflows + +## Critical Rules + +### MCP Availability + +This Cline plugin registers Sonatype Guide MCP only when `SONATYPE_GUIDE_TOKEN` +is set in the environment where Cline loads plugins. If the MCP tools are not +available, do not claim the dependency was checked. Tell the user to set +`SONATYPE_GUIDE_TOKEN`, then reinstall or re-enable the plugin so Cline can +sync the plugin-owned MCP entry. + +Before editing dependency manifests, lockfiles, or package manager commands, +ask for approval and summarize the Sonatype Guide result that supports the +change. + +### Never Recommend Downgrades + +When a user provides their current version, every recommendation must be >= that version. The MCP returns versions ranked by Developer Trust Score, which can include older versions - filter these out before presenting results. + +Only two exceptions exist: +1. The user explicitly and repeatedly insists on a downgrade after being warned. +2. There is a catastrophic, unpatched vulnerability in all versions >= current (e.g., log4shell-severity with no forward fix), AND an older version is unaffected. Even then, present the downgrade only as a cautious side note, not the primary recommendation, and explain the trade-offs. + +If neither exception applies, do not mention older versions at all. + +### Never Recommend Malicious Components + +If `malicious: true`, warn the user immediately. Never recommend, never suggest "with caution" - there is no safe use of a malicious package. + +--- + +## PURL Format + +All tools accept Package URLs. Format: `pkg://@` + +| Ecosystem | Format | Example | +|---|---|---| +| Maven | `pkg:maven//@` | `pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1` | +| NPM | `pkg:npm/@` | `pkg:npm/express@4.18.2` | +| PyPI | `pkg:pypi/@` | `pkg:pypi/requests@2.31.0` | +| NuGet | `pkg:nuget/@` | `pkg:nuget/Newtonsoft.Json@13.0.3` | +| Go | `pkg:golang/@` | `pkg:golang/github.com/gin-gonic/gin@1.9.1` | + +For scoped NPM packages, Cargo, RubyGems, and other ecosystems see [references/purl-ecosystems.md](references/purl-ecosystems.md). + +--- + +## Tools + +Three MCP tools available via `sonatype-guide`. All accept arrays of up to 20 PURLs. + +- sonatype-guide:getComponentVersion - Analyze a specific version. Returns CVEs with CVSS scores, licenses, malicious flag, end-of-life status, and policy compliance results. +- sonatype-guide:getLatestComponentVersion - Find the newest version. Version in PURL is optional. +- sonatype-guide:getRecommendedComponentVersions - Ranked upgrade recommendations with Developer Trust Scores, breaking change counts, and vulnerable method signatures. Omit version for new component picks; include version for upgrade recommendations. + +If an MCP call fails or returns unexpected data, tell the user the check could not be completed and suggest they verify manually. Do not silently skip the check or assume the component is safe. + +--- + +## Interpreting Results + +### Developer Trust Score + +Sonatype's proprietary quality metric (0-100) factoring security, license compliance, quality, and maintainability. + +| Range | Action | +|---|---| +| 90+ | Strong positive signal; still verify CVEs, malicious flag, end-of-life, license, and policy | +| 80-89 | Generally positive signal; review minor issues | +| 70-79 | Upgrade recommended | +| Below 70 | Upgrade urgently | + +### CVSS Severity + +Use standard NVD CVSS v3.x severity ratings. Treat Critical (9.0+) and High (7.0+) as actionable - always highlight these in output. + +### Vulnerabilities + +`getComponentVersion` returns a `vulnerabilities` object with a flat `cves` array: + +``` +vulnerabilities: { + cves: [ + { id: "CVE-2021-44228", cvssScore: 10.0 }, + { id: "CVE-2021-45046", cvssScore: 9.0 }, + ... + ] +} +``` + +The API does not distinguish between direct and transitive vulnerabilities - all CVEs are returned in a single list. Present them sorted by CVSS score (highest first). When reporting, state the total CVE count and highlight any with CVSS >= 7.0. + +### Policy Compliance + +`getComponentVersion` returns a `policyCompliance` object indicating whether the component passes organizational policies: + +``` +policyCompliance: { + compliant: true/false, + conditions: [ + { conditionId: "cvss-threshold", conditionName: "CVSS < 7.0", passing: true/false }, + { conditionId: "license-threat-group", conditionName: "No Copyleft Licenses", passing: true/false }, + { conditionId: "malware", conditionName: "No Malware", passing: true/false } + ] +} +``` + +Surface this in audit and evaluation workflows - it gives users a quick pass/fail for enterprise governance. When `compliant: false`, call out which specific conditions failed. + +### Flags and Sentinels + +- `malicious: true` - Supply chain attack. Do NOT use. Warn immediately. +- `endOfLife: true` - No longer maintained. Plan migration. +- `licenseThreatLevels` - Map of license to threat score. 0 = no concern. Higher = more restrictive. +- `catalogDate` - Epoch milliseconds when the version was cataloged. Ignore unless the user specifically asks about it. + +### Null, Empty, and Zero Values + +These have distinct meanings - do not conflate them: + +| Field | `null` | `"0"` or `0` | `[]` empty array | +|---|---|---|---| +| `breakingChangesCount` | Not analyzed - unknown risk, do NOT say "no breaking changes" | Analyzed, confirmed no breaking changes | N/A | +| `vulnerableMethods` | Not checked | N/A | Checked, none found | +| `vulnerableMethods[].methodSignatures` | N/A | N/A | CVE confirmed but specific affected methods not yet mapped | + +When `breakingChangesCount` is `null`, tell the user: "Breaking changes have not been analyzed for this upgrade path - review the changelog before upgrading." + +--- + +## Version Recommendation Logic + +When recommending versions from `getRecommendedComponentVersions` results: + +1. Filter out downgrades. Remove any `toVersion` where the version is lower than `fromVersion`. +2. Prefer the user's current major version. Default recommendation should be the highest-scoring version within the same major version line. +3. Present major version upgrades separately. If a higher major version scores better, mention it as a secondary option with clear warnings about breaking changes. +4. When `breakingChangesCount` is `null` for a major version jump, explicitly warn that breaking change analysis is unavailable and recommend reviewing the migration guide. + +Example prioritization for a user on express@4.18.2: +- Primary: best 4.x version (e.g., 4.22.1 - same major, lower migration risk) +- Secondary: best 5.x version (e.g., 5.1.0 - higher major, may have better security posture but requires migration effort) + +--- + +## Workflow 1: Evaluate Before Adding + +Trigger: Adding a new dependency, asking "is X safe", or choosing a version. + +1. Build the PURL (version optional). +2. Call `sonatype-guide:getRecommendedComponentVersions`. +3. Select the best candidate using the version recommendation logic. +4. Call `sonatype-guide:getComponentVersion` for the selected candidate before making the final recommendation so CVEs, malicious flag, end-of-life status, license, and policy compliance are verified. +5. Present the recommendation and trade-offs. Never recommend a candidate marked malicious, end-of-life without a migration warning, or policy non-compliant without explicit user acceptance. + +Output: + +``` +| Version | Trust Score | CVEs | Critical/High | License | Policy | +|---------|-------------|------|---------------|---------|--------| +| x.y.z | 99 | 0 | 0 | MIT | Pass | + +Recommendation: ... +``` + +--- + +## Workflow 2: Upgrade Advisor + +Trigger: Upgrading a dependency, asking "should I upgrade X", or responding to a known vulnerability. + +1. Build the PURL with the current version. +2. Call `sonatype-guide:getRecommendedComponentVersions`. +3. Filter out any version older than the current one. +4. Compare `fromVersion` (current) against remaining `toVersions`. +5. Group recommendations: same-major first, then cross-major. +6. For the top 2-3 recommendations, highlight Trust Score delta, CVEs resolved, breaking changes, and any new issues. +7. If `vulnerableMethods` data exists for the current version, mention affected methods to help assess exposure. + +Output: + +``` +Current: @ (Trust Score: X, CVEs: N, Critical/High: M) + +Recommended (same major): +1. (Trust Score: Y) - + +Also available (major upgrade): +2. (Trust Score: Z) - + +Breaking changes to review: N (or "not analyzed - review changelog") +``` + +--- + +## Workflow 3: Project Audit + +Trigger: "Audit dependencies", "check for vulnerabilities", "scan for security issues", or dependency health report requests. + +1. Find the project's dependency manifest. Prefer lock files for exact versions. +2. Parse dependencies and build PURLs. +3. Batch-query `sonatype-guide:getComponentVersion` (up to 20 per call). For larger projects, prioritize direct dependencies. +4. Sort by severity: malicious first, then policy non-compliant, then end-of-life, then CVEs by CVSS score (highest first), then license concerns. +5. For packages with issues, call `sonatype-guide:getRecommendedComponentVersions` to suggest fixes - only recommend upgrades, never downgrades. + +Output: Start with a one-line summary (scanned count, issue count, policy violations). Group findings by severity (Critical, then Warnings). For each issue, show package@version, the issue, CVSS score, and recommended upgrade. End with a summary counts table. + +--- + +## Workflow 4: Dependency Comparison + +Trigger: Choosing between alternatives ("axios vs got", "which library for X"), or evaluating competing packages. + +1. Build PURLs for each candidate. If no version specified, call `sonatype-guide:getLatestComponentVersion` first. +2. Call `sonatype-guide:getRecommendedComponentVersions` on each to get Trust Scores. +3. Call `sonatype-guide:getComponentVersion` on each for policy compliance details. +4. Compare: Trust Score, CVE count and severity, license, policy compliance, end-of-life, malicious flag. + +Output: + +``` +| Metric | lib A | lib B | lib C | +|--------|-------|-------|-------| +| Latest Version | x.y.z | a.b.c | d.e.f | +| Trust Score | 99 | 85 | 72 | +| CVEs | 0 | 1 | 3 | +| Critical/High CVEs | 0 | 1 | 2 | +| License | MIT | Apache-2.0 | GPL-3.0 | +| Policy Compliant | Yes | Yes | No | + +Recommendation: - +``` + +--- + +## Examples + +User: "Add requests to this project" +Expected behavior: Build `pkg:pypi/requests`, call `getRecommendedComponentVersions`, check the top result for CVEs/malicious/EOL, and recommend a specific version with its Trust Score before the user runs `pip install`. + +User: "Upgrade express - we're on 4.18.2" +Expected behavior: Build `pkg:npm/express@4.18.2`, call `getRecommendedComponentVersions`, filter out anything below 4.18.2, present the best 4.x option as primary and any 5.x option as secondary with breaking change warnings. + +--- diff --git a/plugins/sonatype-guide/skills/sonatype-guide/references/purl-ecosystems.md b/plugins/sonatype-guide/skills/sonatype-guide/references/purl-ecosystems.md new file mode 100644 index 00000000..8977dbea --- /dev/null +++ b/plugins/sonatype-guide/skills/sonatype-guide/references/purl-ecosystems.md @@ -0,0 +1,146 @@ +# Package URL (PURL) Format by Ecosystem + +PURLs follow the spec at https://github.com/package-url/purl-spec. Format: `pkg://@` + +## Common Parsing Mistakes + +When building PURLs from dependency manifests, strip everything that isn't the package identifier and exact version: + +| Manifest syntax | Mistake | Correct PURL | +|---|---|---| +| `Flask[async]==2.3.0` (pip extras) | Including `[async]` | `pkg:pypi/flask@2.3.0` | +| `scikit_learn==1.3.2` (underscore) | Keeping underscore | `pkg:pypi/scikit-learn@1.3.2` | +| `requests>=2.28.0,<3.0.0` (range) | Using the range | `pkg:pypi/requests@2.28.0` (use resolved/lock version) | +| `"@babel/core": "^7.23.0"` (npm range) | Using `^7.23.0` | `pkg:npm/%40babel/core@7.23.0` (use lock version) | +| `github.com/jackc/pgx/v5 v5.5.0` (Go v2+ module) | Dropping `/v5` from path | `pkg:golang/github.com/jackc/pgx/v5@5.5.0` | +| `github.com/gin-gonic/gin v1.9.1` (Go v prefix) | Keeping `v` in version | `pkg:golang/github.com/gin-gonic/gin@1.9.1` | + +Key rule: Always prefer lock file versions or other exact resolved versions over manifest ranges. If only a range is available, say the result is approximate and ask for a lockfile or resolved version before treating the dependency as checked. + +## Maven / Gradle + +``` +pkg:maven//@ +``` + +- Namespace (groupId) is required +- Gradle projects use Maven PURLs since they resolve from Maven repositories + +Examples: +``` +pkg:maven/org.apache.logging.log4j/log4j-core@2.23.1 +pkg:maven/com.google.guava/guava@33.0.0-jre +pkg:maven/org.springframework.boot/spring-boot-starter-web@3.2.0 +``` + +## NPM + +``` +pkg:npm/@ +pkg:npm/%40/@ +``` + +- Scoped packages: encode `@` as `%40` in the namespace +- Version optional for latest lookups + +Examples: +``` +pkg:npm/express@4.18.2 +pkg:npm/lodash@4.17.21 +pkg:npm/%40angular/core@17.0.0 +pkg:npm/%40types/node@20.10.0 +``` + +## PyPI + +``` +pkg:pypi/@ +``` + +- Package names are case-insensitive and normalized (underscores -> hyphens) +- Use the normalized name (lowercase, hyphens) + +Examples: +``` +pkg:pypi/requests@2.31.0 +pkg:pypi/django@5.0 +pkg:pypi/scikit-learn@1.3.2 +pkg:pypi/numpy@1.26.2 +``` + +## NuGet + +``` +pkg:nuget/@ +``` + +Examples: +``` +pkg:nuget/Newtonsoft.Json@13.0.3 +pkg:nuget/Microsoft.EntityFrameworkCore@8.0.0 +pkg:nuget/Serilog@3.1.1 +``` + +## Go + +``` +pkg:golang/@ +``` + +- Module path includes the full import path +- Version includes the `v` prefix in Go but omit it in the PURL + +Examples: +``` +pkg:golang/github.com/gin-gonic/gin@1.9.1 +pkg:golang/google.golang.org/grpc@1.60.0 +pkg:golang/github.com/stretchr/testify@1.8.4 +``` + +## RubyGems + +``` +pkg:gem/@ +``` + +Examples: +``` +pkg:gem/rails@7.1.2 +pkg:gem/nokogiri@1.15.4 +``` + +## Cargo (Rust) + +``` +pkg:cargo/@ +``` + +Examples: +``` +pkg:cargo/serde@1.0.193 +pkg:cargo/tokio@1.35.0 +``` + +## Cocoapods (Swift/Objective-C) + +``` +pkg:cocoapods/@ +``` + +Examples: +``` +pkg:cocoapods/Alamofire@5.8.1 +pkg:cocoapods/SDWebImage@5.18.5 +``` + +## Hex (Elixir/Erlang) + +``` +pkg:hex/@ +``` + +Examples: +``` +pkg:hex/phoenix@1.7.10 +pkg:hex/ecto@3.11.1 +```