inventory

package
v0.0.0-...-80ccc60 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 59 Imported by: 0

Documentation

Overview

Package inventory extracts a dependency inventory (package list) from either the current working tree or a historical commit snapshot. It leverages google/osv-scalibr plugins to perform language/ecosystem aware scanning.

Three entry points are provided:

  • ScanPackagesWorking – analyzes the present filesystem state without mutating Git
  • ScanPackagesAtCommitSnapshot – materializes a commit into a temp directory for scanning
  • ScanPackagesContainerImage – scans a container image using the image pipeline

The abstractions are intentionally narrow: callers receive raw scalibr Package objects and can layer additional classification or enrichment.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultDependencyInstallDirs = []string{
	"node_modules",
	"site-packages",
	"__pypackages__",
}

DefaultDependencyInstallDirs are directory names that unambiguously denote an installed or vendored third-party dependency tree, never a source-of-truth manifest location. A name qualifies only if it is the canonical install directory for an ecosystem and is not also a common source-directory name: that admits "node_modules", "site-packages", and "__pypackages__" but excludes ambiguous names that are frequently real source dirs ("vendor", "target", "build") and the virtualenv root (".venv"/"venv"), whose vendored manifests live under the unambiguous "site-packages" child matched here.

This backs IsDependencyInstallPath, used by the remediation guard to avoid emitting a fix against a manifest vendored inside an installed tree (a derived copy that cannot be edited in place). It is deliberately small and serves as a version-control-independent backstop, notably for non-git directory scans. Scoping a repository scan to its committed source of truth is handled separately by honoring version control, not by this list.

Functions

func CommitSnapshotWorkspace 

func CommitSnapshotWorkspace(repo *git.Repository, commitHash plumbing.Hash) (workspace.FS, error)

CommitSnapshotWorkspace materializes the commit's tree into an in-memory workspace, giving a ref the same file access a working-tree scan gets from its directory: package extraction and graph edge resolution both read from it. The caller owns the workspace and must Close it.

func CompileExcludePaths 

func CompileExcludePaths(patterns []string) (glob.Glob, error)

CompileExcludePaths compiles a set of path-exclusion glob patterns into a single matcher suitable for scalibr's SkipDirGlob. Patterns are matched against directory paths (slash-separated, relative to the scan root) during the filesystem walk; a match prunes the entire subtree from inventory.

Pattern semantics (gitignore-flavored):

  • Globs use '/' as the path separator; '**' matches across separators.
  • A trailing "/" or "/**" is optional: ".bin", ".bin/", and ".bin/**" all exclude the ".bin" subtree.
  • A pattern WITHOUT a '/' matches a directory of that name at any depth, so ".bin" excludes both "./.bin" and "internal/.bin".
  • A pattern WITH a '/' is anchored to the scan root, so ".github/workflows" excludes only that subdirectory while leaving the rest of ".github" intact.

Returns (nil, nil) when no usable patterns are supplied, so callers can leave SkipDirGlob unset. Returns an error if any pattern is malformed rather than silently ignoring it.

func DefaultScanner 

func DefaultScanner() func(ctx context.Context, ws workspace.FS, ecosystems []string) ([]*extractor.Package, error)

DefaultScanner returns a function that uses the default scanning logic. This adapter is useful for dependency injection in tests or custom pipelines.

func IsDependencyInstallPath 

func IsDependencyInstallPath(p string) bool

IsDependencyInstallPath reports whether p traverses a dependency-install directory (see DefaultDependencyInstallDirs). Path separators may be "/" or "\\"; matching is per path segment, so "a/b/site-packages/pkg/Cargo.toml" matches while "my-site-packages.txt" does not. Used to keep remediation from targeting a manifest vendored inside an installed dependency tree.

func ScanPackagesAtCommitSnapshot 

func ScanPackagesAtCommitSnapshot(ctx context.Context, repo *git.Repository, commitHash plumbing.Hash, opts ScanOptions) ([]*extractor.Package, error)

ScanPackagesAtCommitSnapshot materializes the tree for commitHash from repo into an ephemeral in-memory workspace and scans it for packages. The workspace is discarded after scanning.

func ScanPackagesContainerImage 

func ScanPackagesContainerImage(ctx context.Context, img scalibrimage.Image, opts ScanOptions) ([]*extractor.Package, error)

ScanPackagesContainerImage scans a container image using OSV-Scalibr's image pipeline. When opts.DetectBaseImage is true, it also runs the baseimage enricher to populate the InBaseImage field in LayerDetails, which requires network access to query deps.dev.

func ScanPackagesVMImage 

func ScanPackagesVMImage(ctx context.Context, fsys scalibrfs.FS, opts ScanOptions) ([]*extractor.Package, error)

ScanPackagesVMImage scans a VM image filesystem using OSV-Scalibr. The provided fs.FS must implement fs.ReadDirFS and fs.StatFS (which scalibrfs.FS requires).

Performance Note: VM image scanning uses pure Go filesystem parsing for portability (no root required, no kernel mounts). This is slower than kernel-mounted filesystems. Large images (>5GB virtual size) may take 2-5 minutes to scan.

TODO(performance): Consider these optimizations to improve VM image scan performance:

  • Path filtering: Skip known-uninteresting directories (/usr/share/doc, /var/cache, etc.)
  • Parallel extraction: Run multiple extractors concurrently on different paths
  • Metadata caching: Cache ext4 inode/block lookups for repeated access patterns
  • Early termination: Stop filesystem traversal once all package databases are found
  • Progress reporting: Add scan progress callbacks for better UX on large images

See also: docs/guides/vm-images.md for user-facing performance guidance.

func ScanPackagesWorking 

func ScanPackagesWorking(ctx context.Context, ws workspace.FS, opts ScanOptions) ([]*extractor.Package, error)

ScanPackagesWorking scans the provided workspace and returns the discovered package inventory. The workspace may be backed by the host filesystem or be a virtual in-memory filesystem.

Types

type DependencyMatcher 

type DependencyMatcher struct {
	// contains filtered or unexported fields
}

DependencyMatcher wraps the scalibr filesystem extractors used for inventory scans and reuses their FileRequired logic to decide whether a path qualifies as a dependency manifest or lockfile. It keeps Deputy’s heuristics aligned with osv-scalibr instead of relying on bespoke filename lists.

func GetDependencyMatcher 

func GetDependencyMatcher(opts ScanOptions) (*DependencyMatcher, error)

GetDependencyMatcher returns a DependencyMatcher for the provided scan options, caching instances so repeated calls avoid re-instantiating the underlying osv-scalibr plugins. The cache key is derived from the normalized ecosystem list (with "all" collapsing to a single entry).

func NewDependencyMatcher 

func NewDependencyMatcher(opts ScanOptions) (*DependencyMatcher, error)

NewDependencyMatcher instantiates the filesystem extractors for the provided scan options and captures them for later path checks. The matcher mirrors the plugin selection performed during inventory scans, ensuring callers ask the same question scalibr would when deciding whether to inspect a file.

func (*DependencyMatcher) AnyMatch 

func (m *DependencyMatcher) AnyMatch(paths []string) bool

AnyMatch reports whether at least one of the provided paths would be consumed by the configured extractors, returning true on the first match.

func (*DependencyMatcher) Matches 

func (m *DependencyMatcher) Matches(path string) bool

Matches reports whether any configured extractor would consider the provided path relevant (i.e., its FileRequired method returns true for that file).

type Execution 

type Execution struct {
	Result    Result
	Workspace workspace.FS // Optional: file access for graph edge resolution
	// contains filtered or unexported fields
}

Execution wraps an inventory result and cleanup function. Always call Close() when done to release temporary resources.

func Collect 

func Collect(ctx context.Context, target string, opts Options) (*Execution, error)

Collect extracts package inventory from any supported target type. It auto-detects the target kind and routes to the appropriate collector.

Supported targets:

  • Local directories (e.g., ".", "/path/to/project")
  • Git repositories (local or remote URLs)
  • Container images (e.g., "docker://nginx:1.25", "ghcr.io/owner/app:v1")
  • Git refs (use CollectRepository for explicit ref control)

Example: 

exec, err := inventory.Collect(ctx, ".", inventory.Options{})
if err != nil { return err }
defer exec.Close()
for _, pkg := range exec.Result.Packages {
    fmt.Println(pkg.Name, pkg.Version)
}

func CollectAtCommit 

func CollectAtCommit(ctx context.Context, repo *git.Repository, commitHash plumbing.Hash, opts Options) (*Execution, error)

CollectAtCommit extracts inventory from a specific git commit.

func CollectBinary 

func CollectBinary(ctx context.Context, path string, opts Options) (*Execution, error)

CollectBinary extracts inventory from a Go or Rust binary file. It uses SCALIBR's gobinary and cargoauditable extractors.

For Go binaries, this extracts the embedded buildinfo which includes:

  • The main module path and version
  • All dependency module paths and versions

For Rust binaries built with cargo-auditable, this extracts:

  • All crate dependencies with versions

Note: Standard Rust binaries without cargo-auditable metadata will return an empty inventory, not an error.

func CollectContainerImage 

func CollectContainerImage(ctx context.Context, target string, targetOpts map[string]string, opts Options) (*Execution, error)

CollectContainerImage extracts inventory from a container image.

The target can be:

  • Remote registry: "docker://nginx:1.25", "ghcr.io/owner/app:v1"
  • Docker daemon: "docker-daemon://myapp:latest"
  • Tarball: "tarball:///path/to/image.tar"
  • OCI archive: "oci-archive:///path/to/image.tar"
  • OCI layout: "oci-layout:///path/to/layout"

targetOpts supports:

  • "platform": target platform (e.g., "linux/amd64")
  • "transport": override auto-detected transport

func CollectDirectory 

func CollectDirectory(ctx context.Context, path string, opts Options) (*Execution, error)

CollectDirectory extracts inventory from a local directory (no git context).

func CollectDockerfile 

func CollectDockerfile(ctx context.Context, target string, opts Options) (*Execution, error)

CollectDockerfile parses a Dockerfile without scanning packages. Use CollectContainerImage to scan packages in referenced images.

func CollectPURL 

func CollectPURL(ctx context.Context, purlStr string, opts Options) (*Execution, error)

CollectPURL extracts inventory for a single PURL. This creates a minimal inventory with just the one package.

func CollectRepository 

func CollectRepository(ctx context.Context, target, ref string, refProvided bool, opts Options) (*Execution, error)

CollectRepository extracts inventory from a git repository. The target can be a local path or remote URL.

Parameters:

  • target: local path or git URL
  • ref: git reference (branch, tag, commit hash), or "HEAD"
  • refProvided: true if the caller explicitly provided ref
  • opts: collection options

func CollectRepositoryAtRef 

func CollectRepositoryAtRef(ctx context.Context, target, ref string, opts Options) (*Execution, error)

CollectRepositoryAtRef extracts inventory from a git repository at a specific reference. Unlike CollectRepository which scans the working tree, this function materializes the tree at the specified ref into memory and scans that snapshot.

This provides consistent behavior with `deputy diff` which properly scans at refs.

func CollectSBOM 

func CollectSBOM(ctx context.Context, target string, opts Options) (*Execution, error)

CollectSBOM extracts inventory from an SBOM file or stdin. Supports protobom-json, cyclonedx-json, and spdx-json formats.

func CollectVMImage 

func CollectVMImage(ctx context.Context, target string, targetOpts map[string]string, opts Options) (*Execution, error)

CollectVMImage scans a VM disk image or rootfs image for packages. Supported formats: qcow2, vmdk, vhd, vhdx, vdi, raw, and ext4 rootfs images.

func (*Execution) Close 

func (e *Execution) Close() error

Close releases any temporary resources (e.g., cloned repos).

type Options 

type Options struct {
	// Ecosystems limits extraction to specific package ecosystems.
	// Empty means all supported ecosystems.
	Ecosystems []string

	// Platform specifies container image platform (e.g., "linux/amd64").
	Platform string

	// DetectBaseImage enables base image detection for container image scans.
	// When true, the baseimage enricher queries deps.dev to determine if layers
	// belong to known base images, populating LayerDetails.InBaseImage.
	// This requires network access and adds latency to the scan.
	DetectBaseImage bool

	// ExcludePaths lists glob patterns for directory paths to skip during the
	// filesystem walk (e.g., ".bin/**"). Matching subtrees are never inventoried.
	// See [CompileExcludePaths] for pattern semantics.
	ExcludePaths []string
}

Options configures inventory collection.

type Result 

type Result struct {
	// Target describes what was scanned.
	Target Target

	// GeneratedAt is when the inventory was collected.
	GeneratedAt time.Time

	// Packages are the discovered dependencies.
	Packages []*extractor.Package

	// Direct maps package keys to whether they are direct dependencies.
	// For Go, this is derived from go.mod. For other ecosystems, heuristics apply.
	Direct map[string]bool

	// ImageInfo contains container image configuration (for image targets).
	ImageInfo *image.Info

	// DockerfileInfo contains parsed Dockerfile data (for dockerfile targets).
	DockerfileInfo *dockerfile.Info

	// DockerfileAnalysis contains static analysis results (for dockerfile targets).
	DockerfileAnalysis *dockerfile.Analysis
}

Result is the output of inventory collection. It contains discovered packages and metadata about the target.

type ScanOptions 

type ScanOptions struct {
	Ecosystems []string
	// UseGitignore applies .gitignore handling for real local source workspaces.
	// Directory ignores are enforced before scanning; SCALIBR handles file-level
	// ignores best-effort. The option is ignored for virtual workspaces because
	// commit snapshots already represent exact tracked contents.
	UseGitignore bool
	// DetectBaseImage enables base image detection for container image scans.
	// When true, the baseimage enricher queries deps.dev to determine if layers
	// belong to known base images, populating LayerDetails.InBaseImage.
	// This requires network access and adds latency to the scan.
	DetectBaseImage bool
	// ExcludePaths lists glob patterns for directory paths to skip during the
	// filesystem walk (e.g., ".bin/**", "**/testdata"). Matching subtrees are
	// never inventoried. See [CompileExcludePaths] for pattern semantics.
	ExcludePaths []string
}

ScanOptions configures how scalibr scans a workspace.

type Target 

type Target struct {
	Kind         targets.Kind
	DisplayPath  string
	LocalPath    string
	Ref          string
	EffectiveRef string
	CommitHash   string
	OriginURL    string
	Cloned       bool
	Provenance   map[string]string
}

Target describes the source of the inventory.

type TargetHint 

type TargetHint struct {
	// Kind explicitly specifies the target type.
	// Zero value means auto-detect.
	Kind targets.Kind

	// ImageTransport specifies how to fetch container images.
	// Values: "remote" (default), "daemon", "tarball", "oci-archive", "oci-layout".
	ImageTransport string
}

TargetHint provides explicit target type hints when auto-detection is insufficient.

Source Files

View all Source files

Directories

Path Synopsis
Package manifests provides helpers for associating files with package managers and manifest paths.
 Package manifests provides helpers for associating files with package managers and manifest paths.
Package plugin provides a client for invoking extractor plugins.
 Package plugin provides a client for invoking extractor plugins.
plugins
asdf/asdfx
Package asdfx extracts dev-toolchain dependencies from the asdf .tool-versions format.
 Package asdfx extracts dev-toolchain dependencies from the asdf .tool-versions format.
docker/dockerfilex
Package dockerfilex extracts container base image dependencies from Dockerfiles.
 Package dockerfilex extracts container base image dependencies from Dockerfiles.
github/actionsx
Package actionsx extracts GitHub Actions dependencies from workflow and action manifests.
 Package actionsx extracts GitHub Actions dependencies from workflow and action manifests.
java/gradlex
Package gradlex provides Gradle dependency extractors for Deputy.
 Package gradlex provides Gradle dependency extractors for Deputy.
mise/misex
Package misex extracts dev-toolchain dependencies from mise-en-place configuration (mise.toml, .mise.toml, .config/mise/config.toml, and related drop-ins).
 Package misex extracts dev-toolchain dependencies from mise-en-place configuration (mise.toml, .mise.toml, .config/mise/config.toml, and related drop-ins).
ruby/gemspecx
Package registry provides a thread-safe registry for extractor plugins.
 Package registry provides a thread-safe registry for extractor plugins.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.