gem-hunter

The dependabot CLI is a tool for running Dependabot update jobs.

Use any of the following for a pain-free installation:

• If you have go installed, you can run:

  go install github.com/dependabot/cli/cmd/dependabot@latest

  The benefit of this method is that re-running the command will always update to the latest version.
• You can download a pre-built binary from the releases page.
• On Mac or Linux, you can run brew install dependabot

• Docker

Check out our contributing guidelines for instructions on building the project locally, sharing feedback, and submitting pull requests.

$ dependabot
Run Dependabot jobs from the command line.

Usage:
  dependabot [command]

Examples:
  $ dependabot update go_modules dependabot/cli
  $ dependabot test -f input.yml

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  test        Run a smoke test
  update      Perform an update job

Flags:
  -h, --help                   help for dependabot
      --proxy-image string     container image to use for the proxy (default "ghcr.io/dependabot/proxy:latest")
      --skip-image-verification   skip updater, proxy, and configured OpenTelemetry collector image verification for trusted development images
      --updater-image string   container image to use for the updater
  -v, --version                version for dependabot

Use "dependabot [command] --help" for more information about a command.

The CLI requires valid GitHub build attestations for updater and proxy images before it starts any containers. When Collector configuration is supplied, it also requires a valid OpenTelemetry Collector image signature. An attestation is a signed claim about an artifact. Provenance records an image's build origin. Bundles contain the signed claims and verification evidence. This policy is enabled by default for update, test, graph, and the Docker Action in this repository.

An image digest identifies its exact content. The CLI requires a valid signature and matching digest, issuer, repository, workflow identity, and source ref. It uses the verified digest for image pulls and container creation.

The accepted issuer is https://token.actions.githubusercontent.com. Updater and proxy images require SLSA build provenance from refs/heads/main. Collector images require Cosign image signatures from stable refs/tags/vMAJOR.MINOR.PATCH releases. These signatures identify the image and publisher without describing the build. The publisher workflows are:

For a Collector version such as :0.161.0, both the workflow identity and certificate source ref must name refs/tags/v0.161.0. The version is still enforced when the reference also includes a digest. For latest, other non-version tags, and digest-only references, any stable release from that same workflow is accepted. The certificate source ref must still match the release in the workflow identity. Prerelease and manually signed Collector images are not accepted. Collector verification, pull, or startup failures stop the job.

Image overrides must satisfy the same producer policy. Registry mirrors must preserve the image digest and attestation bundles. Missing or invalid attestations cause an error.

With --pull=false, the CLI verifies the cached image's repository digest and runs that image. It does not switch to a newer registry tag. It still needs network access for attestations and Sigstore trust metadata. The CLI uses existing registry credentials, not updater-job credentials, to retrieve bundles.

Storage images are not verified. The CLI records the signed producer commit, but does not enforce an independently approved commit or image freshness. Branch builds and images from other producers require the development bypass below.

Only use --skip-image-verification with trusted development images. This flag disables updater, proxy, and configured Collector verification and prints a warning. For example:

dependabot update go_modules dependabot/cli \
  --updater-image my-updater \
  --skip-image-verification

The Docker Action exposes the same bypass through its skip-image-verification input, which defaults to 'false'. Do not use this bypass to ignore unexpected signatures or provenance in production.

Run the update subcommand to run a Dependabot update job for the provided ecosystem and repo. This does not create PRs, but outputs data that could be used to create PRs. For an example of how to do that see the example CLI usage repo.

$ dependabot update go_modules dependabot/cli
# ...
+----------------------------------------------------+
|        Changes to Dependabot Pull Requests         |
+---------+------------------------------------------+
| created | rsc.io/quote/v3 ( from 3.0.0 to 3.1.0 )  |
| created | rsc.io/sampler ( from 1.3.0 to 1.99.99 ) |
+---------+------------------------------------------+

The first argument specifies the package manager (e.g. go_modules, bundler, npm_and_yarn, or pip). Available values are defined in dependabot-core; by convention, each ecosystem registers itself according to the name of its top-level subdirectory in the repo.

The second argument is the repository name with owner (e.g. dependabot/cli for this repo).

By default, repositories are fetched from GitHub.com. To override this, set the --provider / -p option to azure, bitbucket, codecommit, or gitlab.

To update dependencies in a subdirectory, specify a path with the --directory / -d option.

Set the LOCAL_GITHUB_ACCESS_TOKEN environment variable to a Personal Access Token (PAT), and the CLI will pass that token to the proxy to authenticate API requests to GitHub (for example, to access private repositories or packages).

The command-line interface for the update subcommand provides only a subset of the available options for a Dependabot update job. To perform security updates or authenticate against a private registry, you can pass a job description to the update subcommand using the --file / -f option (this replaces the package manager and repository name arguments).

dependabot update -f job.yaml

# job.yaml
job:
    package-manager: npm_and_yarn
    allowed-updates:
      - update-type: all
    dependencies: # required arg when `security-updates-only: true` set
      - 'express'
    security-advisories:
      - dependency-name: express
        affected-versions:
          - <5.0.0
        patched-versions: []
        unaffected-versions: []
    security-updates-only: true
    source:
        provider: github
        repo: dependabot/smoke-tests
        directory: /
        commit: 66115359e6f6cc3af6a661c5d5ae803720b98cb8
credentials:
  - type: npm_registry
    registry: https://npm.pkg.github.com
    token: $LOCAL_GITHUB_ACCESS_TOKEN

This example describes an update job responsive to a hypothetical security advisory affecting express package releases earlier than version 5.0.0. When performing this job, Dependabot will consult the private registry specified using the provided credentials instead of the default NPM registry.

Before running an update job, the dependabot CLI replaces any $-prefixed values in the YAML file with values from the environment. (e.g. $LOCAL_GITHUB_ACCESS_TOKEN).

Note

The job description file format isn't documented formally yet, but you can find examples in the smoke tests and look at the model directory for how the CLI models the job.

When you run the update subcommand, the CLI does the following:

1. Pulls the updater and proxy images from the container registry
2. Creates and configures container networks so the updater communicates exclusively through the proxy
3. Starts the proxy
4. Starts the updater, using the job description as input
5. Records calls made by the updater to create and manage pull requests
6. Writes recorded calls as YAML (if --output / -o option is specified)

sequenceDiagram
    CLI->>Proxy: Starts the proxy
    CLI->>Updater: Starts the updater
    Updater->>GitHub: Fetches repo
    loop
    Updater->>Registry: Fetches package information
    Updater->>CLI: Records calls to create or updates PRs
    end
    CLI->>YAML file: Writes recorded calls to output file (if specified)

All network requests made by the updater go through the proxy. The proxy injects credentials into outbound requests so that the updater doesn't have access to secrets. This isolation is especially important for package managers that run untrusted code during an update job, such as when evaluating manifest files or executing install scripts.

Run the test subcommand with a smoke test file specified by the --file / -f option to test the expected behavior for a Dependabot update job.

$ dependabot test -f smoke-test.yaml
# ...
+------------------------------------------+
|   Changes to Dependabot Pull Requests    |
+---------+--------------------------------+
| created | ubuntu ( from 17.04 to 22.04 ) |
+---------+--------------------------------+

time="2022-09-28T08:15:26Z" level=info msg="15/15 calls cached (100%)"

A smoke test describes the input and expected output of a Dependabot job.

# smoke-test.yaml
input:
    job:
        package-manager: docker
        allowed-updates:
          - update-type: all
        ignore-conditions:
          - dependency-name: ubuntu
            source: tests/smoke-docker.yaml
            version-requirement: '>22.04'
        source:
            provider: github
            repo: dependabot/smoke-tests
            directory: /
            commit: 832e37c1a7a4ef89feb9dc7cfa06f62205191994
output:
  - type: create_pull_request
    expect:
        data:
            base-commit-sha: 832e37c1a7a4ef89feb9dc7cfa06f62205191994
            dependencies:
              - name: ubuntu
                previous-requirements:
                  - file: Dockerfile
                    groups: []
                    requirement: null
                    source:
                        tag: "17.04"
                previous-version: "17.04"
                requirements:
                  - file: Dockerfile
                    groups: []
                    requirement: null
                    source:
                        tag: "22.04"
                version: "22.04"

This example smoke test describes the expected behavior for Dependabot to update the base image of a Dockerfile from ubuntu:17.04 to ubuntu:22.04.

• The input field consists of a job and any credentials. (this is equivalent a job description file).
• The output field comprises an array of expectation objects. These correspond to requests made by the updater to the Dependabot API service when performing an update job.

Note

The smoke test format isn't documented publicly, but you can find examples in the smoke-tests repo and check the Job class in dependabot-core.

To produce a smoke test that tests Dependabot behavior for a given repo, run the update subcommand and set the --output / -o option to a file path.

dependabot update go_modules dependabot/cli -o go-smoke-test.yml

Run the test subcommand for the generated smoke test, specifying a cache directory with the --cache option.

dependabot test -f go-smoke-test.yml --cache ./tmp/cache

While performing the update job, the CLI writes cached responses to requests in the specified directory.

Run the above command a second time, and you should see a line that looks like this at the bottom of the output:

time="2022-09-28T08:14:01Z" level=info msg="117/117 calls cached (100%)"

When the cache coverage for a smoke test is 100%, subsequent runs of the test subcommand are most likely to be fast and deterministic. Any cache misses indicate an external request made by the updater, which may cause tests to fail unexpectedly (for example, when a new version of a package is released).

See the debugging doc for details.

failed to pull ghcr.io/dependabot/proxy:latest:
Error response from daemon: dial unix docker.raw.sock: connect: no such file or directory

The CLI requires Docker to be running on your machine. Follow the instructions on Docker's website to get the latest version of Docker installed and running.

You can verify that Docker is running locally with the following command:

docker --version

failed to start container: Error response from daemon: network internet is ambiguous (2 matches found on name)

This error can occur when the CLI exits before having an opportunity to clean up (e.g. terminating with ^C). Run the following command to remove all unused networks:

docker network prune

When locally running the CLI, if you do not set the --api-url argument, the default is to connect to host.docker.internal which is effectively a "loopback" endpoint that just logs the commands set to it. The default IP address used for sending these requests is 0.0.0.0 which normally works in Linux.

However, when running under WSL2, for some (currently unknown) reason, the 0.0.0.0 default setting does not work. The workaround is to add this to your CLI environment:

export FAKE_API_HOST=127.0.0.1

This allows the requests to go through on WSL2.

Security-wise, it would actually be better if this was the default. For more background on the issue, see #113 (comment)

$ script/build go_modules