Documentation
¶
Overview ¶
Package depaudit is AgentGuard's dependency safety auditor.
It answers one question across every ecosystem the project ships (Go module, Python SDK, TypeScript SDK): is each dependency on a *safe* version? "Safe" is defined deliberately loosely so the gate does not become busywork that fails the build every time an upstream cuts a routine release:
A dependency is SAFE if it is on the latest version, OR it is behind the latest version but the gap introduces no known security vulnerability and no known performance regression. Being merely "behind" is fine. A dependency is UNSAFE only when its current version is hit by a known security vulnerability or a known performance regression that an available upgrade would resolve. That — and only that — fails the gate.
The list of "known" issues lives in advisories.json (embedded below), a curated registry maintained from govulncheck / pip-audit / npm audit output and from upstream release notes / benchmark evidence for performance regressions (for which no automated database exists). See advisories.md.
This package is intentionally stdlib-only and has zero production import surface: it is a CI/dev tool, not part of the <3ms hot path.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Advisory ¶
type Advisory struct {
ID string `json:"id"`
Ecosystem string `json:"ecosystem"` // go | python | npm
Package string `json:"package"`
Kind Kind `json:"kind"`
Summary string `json:"summary"`
Reference string `json:"reference"`
Affected []VersionRange `json:"affected"`
}
Advisory is one known security or performance issue affecting a package.
type Dependency ¶
type Dependency struct {
Ecosystem string // go | python | npm
Name string
// Current is an exact version (Go pins, npm lockfile-resolved) or a PEP 508 /
// npm version constraint when no exact version is available (Python extras).
Current string
Constraint bool // true when Current is a range, not an exact version
Scope string // direct | indirect | dev | optional:<extra> | build
}
Dependency is one audited package across any ecosystem.
func CollectDependencies ¶
func CollectDependencies(root string) ([]Dependency, error)
CollectDependencies parses every manifest under root into a flat list.
type Finding ¶
type Finding struct {
Dependency
Latest string // best-effort; populated only when online lookup is enabled
Safe bool // false ⇒ fails the gate
Reason string // human-readable explanation for the report
Advisory *Advisory // the matched registry advisory when Safe is false
Source string // what flagged it: "registry" | "osv.dev"
Reference string // advisory URL for the report
OSVChecked bool // true ⇒ current version was cross-checked live against OSV.dev
// contains filtered or unexported fields
}
Finding is the per-dependency audit verdict.
func Evaluate ¶
func Evaluate(deps []Dependency, reg *Registry, fetchLatest bool) []Finding
Evaluate is the backward-compatible entry point: registry-only verdict with an optional best-effort latest-version lookup for the report.
func EvaluateWithOptions ¶
func EvaluateWithOptions(deps []Dependency, reg *Registry, opts Options) []Finding
EvaluateWithOptions produces a Finding for each dependency. The verdict is the union of two sources:
- The curated registry (always, offline) — covers performance regressions, which no database tracks, plus any manually-pinned advisory.
- OSV.dev (when Options.CheckOSV, online) — the authoritative, always-current security database, queried per exact pinned version across Go/PyPI/npm.
OSV only ever *adds* findings; a network failure degrades to registry-only without erroring, so the gate cannot flake red on an OSV outage. Latest is fetched only when Options.FetchLatest and never affects Safe.
type Kind ¶
type Kind string
Kind classifies why an upgrade matters. Only these two kinds fail the gate.
type Options ¶
type Options struct {
// FetchLatest populates Finding.Latest via the ecosystem registries
// (informational only — never affects the Safe verdict).
FetchLatest bool
// CheckOSV cross-checks each exact-version dependency against the live
// OSV.dev database. This is what makes "behind but safe" a *verified*
// statement about the gap's security content rather than an assumption.
CheckOSV bool
}
Options controls how Evaluate runs.
type Registry ¶
type Registry struct {
Advisories []Advisory `json:"advisories"`
}
Registry is the parsed advisories.json.
func LoadRegistry ¶
LoadRegistry parses the embedded advisory registry.
type VersionRange ¶
VersionRange is an OSV-style affected interval: [Introduced, Fixed). Introduced "0" (or "") means "from the beginning". Fixed "" means no fixed release exists yet — in that case an upgrade would NOT resolve the issue, so per the contract it does not fail the gate (it is surfaced as a note).
Source Files