depsdev

Documentation

Overview

Package depsdev is a client for Google's deps.dev API.

One upstream serves three things DragonGuard would otherwise have to build or run separately:

• OpenSSF Scorecard results, without needing a GitHub token or a local scorecard binary, which is what makes the supply-chain risk component usable rather than permanently unscored.
• The resolved dependency graph, with each node marked SELF, DIRECT or INDIRECT. That is what turns "lodash is vulnerable" into "bump express, which is the dependency you actually control".
• Published version lists, so a minimal upgrade can be computed rather than quoted from whatever fixed version an advisory happened to name.

The API is public and unauthenticated. Every call degrades to "unknown" rather than failing a scan: intelligence that cannot be fetched must not become intelligence that reads as an absence of risk.

Index

• type Client
  • func New() *Client
  • func (c *Client) Dependencies(ctx context.Context, sys System, name, version string) (*Graph, error)
  • func (c *Client) Project(ctx context.Context, projectID string) (*projectResponse, error)
  • func (c *Client) ScorecardFor(ctx context.Context, sys System, name, version string) (*Scorecard, error)
  • func (c *Client) SourceRepo(ctx context.Context, sys System, name, version string) (string, error)
  • func (c *Client) Versions(ctx context.Context, sys System, name string) ([]VersionKey, error)
• type Edge
• type Graph
• type Node
• type Relation
• type Scorecard
  • func (s *Scorecard) FailedChecks(threshold int) []ScorecardCheck
• type ScorecardCheck
• type System
  • func SystemFor(ecosystem string) (System, bool)
• type VersionKey

Types

type Client

type Client struct {
	BaseURL string
	HTTP    *http.Client

	// Concurrency bounds in-flight requests. deps.dev is a shared public
	// service; a monorepo with two thousand dependencies should not open two
	// thousand connections to it.
	Concurrency int
	// contains filtered or unexported fields
}

Client talks to deps.dev.

func New

func New() *Client

func (*Client) Dependencies

func (c *Client) Dependencies(ctx context.Context, sys System, name, version string) (*Graph, error)

Dependencies fetches the resolved dependency graph for a package version.

func (*Client) Project

func (c *Client) Project(ctx context.Context, projectID string) (*projectResponse, error)

Project fetches project metadata, including any OpenSSF Scorecard result. A project deps.dev has never assessed returns (nil, nil): unknown, not an error and emphatically not a zero score.

func (*Client) ScorecardFor

func (c *Client) ScorecardFor(ctx context.Context, sys System, name, version string) (*Scorecard, error)

ScorecardFor resolves a package to its source project's Scorecard in one call. Returns nil when the package, the project or the Scorecard is unknown.

func (*Client) SourceRepo

func (c *Client) SourceRepo(ctx context.Context, sys System, name, version string) (string, error)

SourceRepo resolves a package version to the project that publishes it.

Only a SOURCE_REPO relation is accepted. deps.dev also reports issue trackers and homepages, and scoring a package by its issue tracker's Scorecard would be quietly wrong.

func (*Client) Versions

func (c *Client) Versions(ctx context.Context, sys System, name string) ([]VersionKey, error)

Versions lists the published versions of a package, oldest first as deps.dev returns them.

type Edge

type Edge struct {
	FromNode    int    `json:"fromNode"`
	ToNode      int    `json:"toNode"`
	Requirement string `json:"requirement"`
}

Edge is a resolved dependency relationship, carrying the version range the parent asked for. The requirement is what makes a remediation actionable: it says whether a fixed version is even reachable without a major bump.

type Graph

type Graph struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges"`
	Error string `json:"error"`
}

Graph is a resolved dependency graph rooted at a single package version.

type Node

type Node struct {
	VersionKey VersionKey `json:"versionKey"`
	Bundled    bool       `json:"bundled"`
	Relation   Relation   `json:"relation"`
	Errors     []string   `json:"errors"`
}

Node is one package version in a resolved dependency graph.

type Relation

type Relation string

Relation describes how a node reaches the root of the graph.

const (
	RelationSelf     Relation = "SELF"
	RelationDirect   Relation = "DIRECT"
	RelationIndirect Relation = "INDIRECT"
)

type Scorecard

type Scorecard struct {
	Date         string           `json:"date"`
	OverallScore float64          `json:"overallScore"`
	Checks       []ScorecardCheck `json:"checks"`
	Repo         struct {
		Name   string `json:"name"`
		Commit string `json:"commit"`
	} `json:"repository"`
}

Scorecard is a project's OpenSSF Scorecard result.

func (*Scorecard) FailedChecks

func (s *Scorecard) FailedChecks(threshold int) []ScorecardCheck

FailedChecks returns the checks that scored below threshold, ignoring the -1 that Scorecard uses for "not applicable to this project". Treating -1 as a failure would report every project without a package registry as unsafe.

type ScorecardCheck

type ScorecardCheck struct {
	Name          string `json:"name"`
	Score         int    `json:"score"`
	Reason        string `json:"reason"`
	Documentation struct {
		Short string `json:"short"`
	} `json:"documentation"`
}

ScorecardCheck is one OpenSSF Scorecard check result.

type System

type System string

System is a deps.dev package ecosystem.

const (
	SystemNPM      System = "npm"
	SystemGo       System = "go"
	SystemMaven    System = "maven"
	SystemPyPI     System = "pypi"
	SystemCargo    System = "cargo"
	SystemNuGet    System = "nuget"
	SystemRubyGems System = "rubygems"
)

func SystemFor

func SystemFor(ecosystem string) (System, bool)

SystemFor maps the ecosystem strings scanners emit onto deps.dev systems.

Scanners disagree on spelling -- Trivy says "gomod", OSV says "Go", purls say "golang" -- so the mapping is deliberately generous. An unrecognized ecosystem returns false rather than guessing, because querying the wrong system returns a confident answer about the wrong package.

type VersionKey

type VersionKey struct {
	System  string `json:"system"`
	Name    string `json:"name"`
	Version string `json:"version"`
}

VersionKey identifies one published version of a package.