scan-dependencies

# Skill: Evaluate Dependency Security via deps.dev Findings API Adapted from the [deps.dev example skill](https://github.com/google/deps.dev/blob/main/examples/skills/scan-dependencies/SKILL.md) (Apache License 2.0), with a complete lookup script and an explicit finding-to-action policy based on the [v3alpha API definition](https://github.com/google/deps.dev/blob/main/api/v3alpha/apiv3alpha.proto). ## Description This skill automates the process of auditing package dependencies before adoption. By querying the Open Source Insights (deps.dev) API, it checks a batch of package versions for active security findings (advisories and vulnerabilities) and outputs a clear action plan (ALLOW, CAUTION, or BLOCK). ## Inputs An array of target dependencies. Each dependency must contain: - `system`: The ecosystem name. Must be uppercase: `NPM`, `PYPI`, `MAVEN`, `GO`, `CARGO`, `NUGET`, or `RUBYGEMS`. - `name`: The canonical name of the package (e.g., `org.apache.logging.log4j:log4j-core` for Maven, or normalized lowercase for PyPI/NuGet). - `version`: The explicit version string to audit. This may be unset. Only set the version field if you know the exact version of the package. This field should **not** be set if only a version range is known (for example, `^1.0.0` is not acceptable). --- ## Execution Protocol ### Step 1: Construct the JSON Payload Map the incoming dependency list into a single JSON batch request object. Ensure all items are nested inside the `"requests"` array under a `"versionKey"` or `"packageKey"` parameter. **Payload Schema Example:** ```json { "requests": [ { "versionKey": { "system": "NPM", "name": "express", "version": "4.17.1" } }, { "packageKey": { "system": "PYPI", "name": "requests" } } ] } ``` ### Step 2: Execute the Live Lookup Write the payload built in Step 1 from the actual input list (not the example above) to a file, then POST it. Follow `nextPageToken` until it is absent so the result set is complete. `-f` makes HTTP errors fail the command instead of returning an error body. ```bash echo "Scanning dependencies for safety..." # deps-request.json holds the Step 1 payload, e.g. built with jq: # jq -n '{requests: [{versionKey: {system: "NPM", name: "express", version: "4.17.1"}}]}' > deps-request.json rm -f deps-findings-*.json page_token="" page=0 while :; do page=$((page + 1)) jq --arg t "$page_token" 'if $t == "" then . else . + {pageToken: $t} end' \ deps-request.json > "deps-request-page.json" || exit 1 curl -fsS -X POST https://api.deps.dev/v3alpha/findingsbatch \ -H 'Content-Type: application/json' \ --data-binary @deps-request-page.json \ -o "deps-findings-$page.json" || { echo "Lookup failed: unknown risk"; exit 1; } jq -e . "deps-findings-$page.json" > /dev/null || { echo "Invalid JSON: unknown risk"; exit 1; } page_token="$(jq -r '.nextPageToken // ""' "deps-findings-$page.json")" [ -z "$page_token" ] && break done jq -s '[.[].responses[]?]' deps-findings-*.json > deps-findings.json ``` If the request fails, returns invalid JSON, or pagination cannot be completed, the scan result is **unknown risk** for every dependency in the batch. Report that to the user before proceeding; do not treat it as `ALLOW`. ### Step 3: Decide an Action per Dependency Match each input dependency to its entry in `responses[]` (the `request` field echoes the request as sent, before canonicalization). A dependency with no matching response, or a response without `findings`, is **unknown risk** and gets `CAUTION`. Collect the findings that apply to it: - `findings.packageFindings[]` (package-scoped; apply to every version). - For a `versionKey` request: `findings.requestedVersion.findings[]`. - For a `packageKey` request: `findings.defaultVersion.findings[]` (the version that would be installed without an explicit version). Each finding has a `type` and a `risk`. Choose the most severe action: | Action | When | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BLOCK` | Any finding with `type: MALICIOUS`, or any finding with `risk: RISK_CRITICAL`. | | `CAUTION` | Any other finding whose `type` is not `REMEDIATION` (e.g. `VULNERABLE`, `DEPRECATED`, `LOW_USAGE`, `COOLDOWN`, `NOT_FOUND`, or an unrecognized type), whatever its `risk`; any `REMEDIATION` finding with `risk: RISK_HIGH`, `RISK_MEDIUM`, or an unrecognized risk (including `RISK_UNSPECIFIED`); or missing/incomplete results. | | `ALLOW` | No findings at all, or only `REMEDIATION` findings with `risk: RISK_LOW` or `RISK_INFORMATIONAL`. | Notes: - `COOLDOWN` means the version is newer than the deps.dev cooldown. Pick an older version or wait; never bypass the project's own cooldowns (package manager age gates, Dependabot cooldowns) to adopt it. - `findings.recommendedVersions[]` lists lower-risk versions; suggest one when the result is `BLOCK` or `CAUTION`. ### Step 4: Report Output one line per dependency with its action and the findings (type, risk, and any `deprecatedContext.reason` or `lowUsageContext.alternativePackages`) that drove it. Do not proceed on `BLOCK`; surface `CAUTION` to the user before proceeding. Note that just because a dependency doesn't show up in this list, that doesn't mean we are 100% sure that it is safe. CRITICAL: Treat unflagged dependencies as having unknown risk levels. You must state clearly that the scanner only detects known issues and cannot guarantee absolute security.