deps.dev Documentation

The semver package provides tools for parsing, ordering, and matching versions according to the Semantic Versioning 2.0.0 specification. It includes support for specific extensions and quirks used by various package managers such as Cargo, Go, Maven, NPM, NuGet, PyPI, RubyGems, and Composer.

To handle different package manager behaviors, use the predefined dialect objects (e.g., semver.NPM, semver.Go, etc.) to parse version strings.

v1, err := semver.NPM.Parse("1.2.3")
v2, err := semver.NPM.Parse("2.3.4")
if v1.Compare(v2) < 0 { 
    // v1 is less than v2
}

The scan-dependencies skill automates auditing package dependencies by querying the deps.dev API to check for active security findings (advisories and vulnerabilities). It outputs an action plan: ALLOW, CAUTION, or BLOCK.

CRITICAL: This scan MUST be performed BEFORE any new package is imported or added to dependencies.

Important Note on Risk: A dependency that does not appear in the findings list is not guaranteed to be safe; it simply means no known issues were detected. Treat unflagged dependencies as having unknown risk levels.

The deps.dev HTTP API returns JSON data and can be accessed using any standard HTTP client. When querying for specific packages, ensure that special characters in the package name (such as @ or /) are percent-encoded in the URL.

For complete documentation, visit docs.deps.dev.

curl 'https://api.deps.dev/v3/systems/npm/packages/%40colors%2Fcolors'

Cargo dependencies are represented by Requirements_Cargo_Dependency. Key fields include:

• Name: The package name.
• Requirement: The version requirement.
• Kind: The type of dependency (e.g., normal, dev-dependency, or build-dependency).
• Optional: Boolean indicating if it is an optional dependency.
• PackageAlias: The name used in source code.
• UsesDefaultFeatures: Boolean for default feature usage.
• Features: A list of enabled features.
• Target: The specific platform target.

Requirements_Cargo_Feature describes features and the list of other features or dependencies they Implies.

The API supports batching for both Version and Project information to improve efficiency.

Version Batching:

• Use GetVersionBatchRequest to request information for up to 5,000 versions at once.
• Use VersionBatch to receive the results. If NextPageToken is present, more results are available.

Project Batching:

• Use GetProjectBatchRequest to request information for up to 5,000 projects.
• Use ProjectBatch to receive the results. If NextPageToken is present, more results are available.

The Requirements_Go_Dependency type represents a module requirement in a go.mod file. It contains:

• Name: The module name.
• Requirement: The version query (e.g., "v1.2.3").

Additionally, Requirements_Go_Replace handles replace directives in go.mod:

• Src: The Requirements_Go_Dependency to be replaced.
• Replacement: A Requirements_Go_Dependency representing the new module (remote).
• LocalPath: A string path to a local directory containing the replacement module. Note that either Replacement or LocalPath must be set, but not both.

NuGet requirements are structured around target frameworks and dependency groups.

Key Types:

• Requirements_NuGet_DependencyGroup: A group of dependencies associated with a specific target_framework.
• Requirements_NuGet_FrameworkAssembly: Represents a framework assembly with an assembly_name and target_framework.
• Requirements_NuGet_FrameworkReference: Represents a framework reference with a name and target_framework.
• Requirements_NuGet_DependencyGroup_Dependency: An individual dependency within a group, containing name, requirement, include, and exclude fields.

The deps.dev v3 API provides several types for Python/PyPI dependencies:

PyPI Dependencies

Requirements_PyPI_Dependency represents a standard dependency:

• ProjectName: The name of the package.
• Extras: Extra features/capabilities.
• VersionSpecifier: The version requirement.
• EnvironmentMarker: PEP 508 environment markers.

External Dependencies

Requirements_PyPI_ExternalDependency represents dependencies that cannot be managed by the Python package manager but must be installed on the system. It includes Name, VersionSpecifier, and EnvironmentMarker.

A resolved dependency graph is composed of Dependencies_Node and Dependencies_Edge objects.

Nodes

Dependencies_Node represents a package version in the graph:

• VersionKey: The package and version information.
• Bundled: Indicates if this is a bundled dependency (e.g., a dependency embedded within another package).
• Relation: The DependencyRelation (direct or indirect).
• Errors: Human-readable error messages associated with this node (e.g., unresolved requirements).

Edges

Dependencies_Edge represents the relationship between two nodes:

• FromNode: The index of the node declaring the dependency.
• ToNode: The index of the node resolving the dependency.
• Requirement: The specific requirement string that was resolved by this edge (e.g., "^1.0.0" resolved to "1.2.3").

A Finding represents a single actionable item. It contains:

• Type: The category of the finding (e.g., Finding_Type).
• Risk: The urgency level (e.g., Finding_Risk).
• Context: A oneof field providing specific details based on the finding type:
  • DeprecatedContext: Details for Finding_Deprecated findings.
  • CooldownContext: Details for Finding_Cooldown findings.
  • LowUsageContext: Details for Finding_LowUsage findings.