Supply Chain Risk Auditor

Supply chain risk auditor

Contract

Inputs

1. Project path (required): directory containing a manifest file (package.json, requirements.txt / pyproject.toml, or go.mod).
2. Lockfile (optional): if present (package-lock.json, poetry.lock, Pipfile.lock, go.sum), the auditor resolves transitive dependencies and matches advisories to exact resolved versions. If absent, direct dependencies are assessed against declared version constraints and all transitive dependencies are marked unassessable.
3. Output directory (required): directory where findings.json and report.md are written. Defaults to a directory adjacent to the audited project.

Refusal

• Missing manifest: return findings.json with an empty dependencies array and all counts zero; report.md states no recognized manifest was found.
• Network failure or rate limit: mark affected queries as unassessable; return partial results for completed queries. Never retry with widened scope.
• Malformed advisory response: mark the affected dependency as unassessable; do not guess vulnerability status.
• Any step would require execution: stop and mark the dependency as unassessable. The procedure never installs, builds, imports, or executes the audited project or its dependencies. It never reads dependency source code.

Procedure

1. Identify the ecosystem from the manifest file type. If no recognized manifest exists, mark all dependencies as unassessable and proceed to step 5. Done when: the ecosystem is identified or all dependencies are marked unassessable.

2. Parse the manifest to extract direct dependencies with their declared version constraints. For npm: parse package.json dependencies and devDependencies. For PyPI: parse requirements.txt lines or pyproject.toml [project.dependencies] and [tool.poetry.dependencies]. For Go: parse go.mod require blocks, distinguishing direct (// indirect absent) from indirect. Done when: direct dependencies are enumerated with version constraints.

3. Resolve exact versions. If a lockfile is present, parse it to resolve exact versions and enumerate transitive dependencies. For npm: parse package-lock.json packages for resolved versions. For PyPI: parse poetry.lock or Pipfile.lock for pinned versions. For Go: parse go.sum for module hashes and go.mod for versions; go.sum confirms module integrity but go.mod carries the version. If no lockfile is present, use declared version constraints from the manifest for direct dependencies and mark all transitive dependencies as unassessable with reason no-lockfile. Done when: exact versions are resolved for direct dependencies, and transitive dependencies are enumerated or marked unassessable.

4. Query the ecosystem advisory source for each dependency. Load references/ecosystem-queries.md and apply the query method for the detected ecosystem. Record advisory ID, severity, affected version ranges, and fixed version for each match. Classify each direct dependency into one of three states:

   • assessed-clean: advisory query succeeded and returned no matching vulnerabilities for the resolved version.
   • assessed-flagged: advisory query returned one or more matching vulnerabilities.
   • unassessable: advisory source was unreachable, rate-limited, returned malformed data, the dependency has no resolved version, or the dependency is transitive with no lockfile. Done when: every direct dependency has a state and every query is attempted.

5. Compile findings.json with the structure: { dependencies: [{ name, version, ecosystem, direct, state, advisories }], summary: { total, assessed_clean, assessed_flagged, unassessable } }. Done when: findings.json is written.

6. Generate report.md containing: direct-dependency risk findings with per-dependency state and advisory detail, lockfile-wide version-matched advisories for transitive dependencies (if the lockfile was available), coverage summary with counts for each of the three states, unassessable dependencies with their reason, and remediation recommendations prioritized by severity and clearly separated from measured findings. Done when: report.md is written.

Failure modes

• Rollback: delete findings.json and report.md from the output directory.
• Unrecognized manifest: write findings.json with empty dependencies and zero counts; report.md states no recognized manifest was found.
• Network failure: mark affected dependencies unassessable with reason network-failure; continue with completed queries.
• Malformed advisory response: mark the affected dependency unassessable with reason malformed-response; do not guess vulnerability status.

Output

findings.json (structured JSON with per-dependency risk assessment, advisory matches, coverage summary, and unassessable reasons) and report.md (human-readable report with direct-dependency findings, lockfile-wide advisories, three-state coverage, unassessable dependencies with reasons, and separated remediation guidance).