├── .github ├── CODEOWNERS └── workflows │ ├── release-branch.yml │ └── release.yml ├── LICENSE ├── README.md ├── docs ├── docker_scout.yaml ├── docker_scout_attestation.yaml ├── docker_scout_attestation_add.yaml ├── docker_scout_cache.yaml ├── docker_scout_cache_df.yaml ├── docker_scout_cache_prune.yaml ├── docker_scout_compare.yaml ├── docker_scout_config.yaml ├── docker_scout_cves.yaml ├── docker_scout_docker-cli-plugin-hooks.yaml ├── docker_scout_enroll.yaml ├── docker_scout_environment.yaml ├── docker_scout_help.yaml ├── docker_scout_integration.yaml ├── docker_scout_integration_configure.yaml ├── docker_scout_integration_delete.yaml ├── docker_scout_integration_list.yaml ├── docker_scout_policy.yaml ├── docker_scout_push.yaml ├── docker_scout_quickview.yaml ├── docker_scout_recommendations.yaml ├── docker_scout_repo.yaml ├── docker_scout_repo_disable.yaml ├── docker_scout_repo_enable.yaml ├── docker_scout_repo_list.yaml ├── docker_scout_sbom.yaml ├── docker_scout_stream.yaml ├── docker_scout_version.yaml ├── docker_scout_watch.yaml ├── scout.md ├── scout_attestation.md ├── scout_attestation_add.md ├── scout_cache.md ├── scout_cache_df.md ├── scout_cache_prune.md ├── scout_compare.md ├── scout_config.md ├── scout_cves.md ├── scout_docker-cli-plugin-hooks.md ├── scout_enroll.md ├── scout_environment.md ├── scout_help.md ├── scout_integration.md ├── scout_integration_configure.md ├── scout_integration_delete.md ├── scout_integration_list.md ├── scout_policy.md ├── scout_push.md ├── scout_quickview.md ├── scout_recommendations.md ├── scout_repo.md ├── scout_repo_disable.md ├── scout_repo_enable.md ├── scout_repo_list.md ├── scout_sbom.md ├── scout_stream.md ├── scout_version.md └── scout_watch.md └── install.sh /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @docker/ssc-dev-features-back 2 | -------------------------------------------------------------------------------- /.github/workflows/release-branch.yml: -------------------------------------------------------------------------------- 1 | name: Test and Release 2 | 3 | on: 4 | pull_request: 5 | types: 6 | - opened 7 | - reopened 8 | - synchronize 9 | workflow_dispatch: 10 | 11 | jobs: 12 | test: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - name: Checkout 16 | uses: actions/checkout@v4 17 | - name: Hub Login 18 | uses: docker/login-action@v2 19 | with: 20 | username: ${{ secrets.DOCKER_USER }} 21 | password: ${{ secrets.DOCKER_PAT }} 22 | - name: Prepare scout binary 23 | run: | 24 | tar -xf dist/docker-scout_*_linux_amd64.tar.gz -C . 25 | chmod +x docker-scout 26 | - name: TEST docker scout version 27 | run: ./docker-scout version 28 | - name: TEST docker scout quickview 29 | run: ./docker-scout quickview alpine:latest 30 | - name: TEST docker scout cves 31 | run: ./docker-scout cves docker/scout-demo-service:main 32 | - name: Set up QEMU 33 | uses: docker/setup-qemu-action@v3 34 | - name: Set up Docker Buildx 35 | uses: docker/setup-buildx-action@v3 36 | - name: Build 37 | uses: docker/build-push-action@v5 38 | with: 39 | context: https://github.com/docker/scout-demo-service.git#fix-all-cves 40 | push: false 41 | load: true 42 | tags: docker/scout-demo-service:fix 43 | - name: TEST docker scout compare 44 | run: ./docker-scout compare registry://docker/scout-demo-service:main --to local://docker/scout-demo-service:fix 45 | 46 | release: 47 | if: startsWith(github.head_ref, 'release/v') 48 | permissions: 49 | contents: write 50 | outputs: 51 | tag: ${{ steps.tagname.outputs.value }} 52 | runs-on: ubuntu-latest 53 | needs: test 54 | steps: 55 | - name: Checkout 56 | uses: actions/checkout@v4 57 | with: 58 | fetch-depth: 0 59 | - name: Tag name 60 | uses: mad9000/actions-find-and-replace-string@2 61 | id: tagname 62 | with: 63 | source: ${{ github.head_ref }} 64 | find: 'release/' 65 | replace: '' 66 | - name: Merge and Tag 67 | run: | 68 | git config --unset-all http.https://github.com/.extraheader 69 | git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" 70 | git config --global user.name "${GITHUB_ACTOR}" 71 | git merge --ff-only origin/${{ github.head_ref }} 72 | git tag ${{ steps.tagname.outputs.value }} 73 | git push https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main --tags 74 | 75 | create_release: 76 | needs: 77 | - release 78 | uses: ./.github/workflows/release.yml 79 | permissions: 80 | contents: write 81 | with: 82 | tag: ${{ needs.release.outputs.tag }} -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: release 2 | 3 | on: 4 | push: 5 | tags: 6 | - 'v*.*.*' 7 | workflow_dispatch: 8 | workflow_call: 9 | inputs: 10 | tag: 11 | required: true 12 | type: string 13 | description: "The tag to release" 14 | 15 | jobs: 16 | release: 17 | runs-on: ubuntu-latest 18 | permissions: 19 | contents: write 20 | env: 21 | RELEASE_REF: ${{ github.event_name == 'push' && github.ref_name || inputs.tag }} 22 | steps: 23 | - name: Check out code 24 | uses: actions/checkout@v4 25 | with: 26 | fetch-depth: 0 27 | ref: ${{ env.RELEASE_REF }} 28 | - name: Create Release 29 | uses: softprops/action-gh-release@v1 30 | with: 31 | draft: true 32 | tag_name: ${{ env.RELEASE_REF }} 33 | files: | 34 | dist/docker-scout_* 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The Docker Scout CLI is released under the Terms and Conditions of the 2 | Docker Subscription Service Agreement. Please review the agreement at 3 | https://www.docker.com/legal/docker-subscription-service-agreement/ 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | - [Docker Scout](#docker-scout) 2 | - [Usage](#usage) 3 | - [CLI Plugin Installation](#cli-plugin-installation) 4 | - [Run as container](#run-as-container) 5 | - [CI integration](#ci-integration) 6 | - [License](#license) 7 | 8 | # Docker Scout 9 | 10 | [Docker Scout](https://www.docker.com/products/docker-scout/) is a set of software supply chain features integrated into Docker's user interfaces and command line interface (CLI). These features offer comprehensive visibility into the structure and security of container images. 11 | This repository contains installable binaries of the `docker scout` CLI plugin. 12 | 13 | ## Usage 14 | 15 | The [CLI documentation is available in this repository](./docs/scout.md). 16 | 17 | See the [reference documentation](https://docs.docker.com/scout) to learn about Docker Scout including Docker Desktop and Docker Hub integrations. 18 | 19 | ### Environment Variables 20 | 21 | The following environment variables are available to configure the Scout CLI: 22 | 23 | | Name | Format | Description | 24 | | ---- | ------ | ----------- | 25 | | `DOCKER_SCOUT_CACHE_FORMAT` | String | Format of the local image cache; can be `oci` or `tar` | 26 | | `DOCKER_SCOUT_CACHE_DIR` | String | Directory where the local SBOM cache is stored | 27 | | `DOCKER_SCOUT_NO_CACHE` | Boolean | Disable the local SBOM cache | 28 | | `DOCKER_SCOUT_OFFLINE` | Boolean | Offline mode during SBOM indexing | 29 | | `DOCKER_SCOUT_REGISTRY_TOKEN` | String | Registry Access token to authenticate when pulling images | 30 | | `DOCKER_SCOUT_REGISTRY_USER` | String | Registry user name to authenticate when pulling images | 31 | | `DOCKER_SCOUT_REGISTRY_PASSWORD` | String | Registry password/PAT to authenticate when pulling images | 32 | | `DOCKER_SCOUT_HUB_USER` | String | Docker Hub user name to authenticate against the Docker Scout backend | 33 | | `DOCKER_SCOUT_HUB_PASSWORD` | String | Docker Hub password/PAT to authenticate against the Docker Scout backend | 34 | | `DOCKER_SCOUT_NEW_VERSION_WARN` | Boolean | Warn about new versions of the Docker Scout CLI | 35 | | `DOCKER_SCOUT_EXPERIMENTAL_WARN` | Boolean | Warn about experimental features | 36 | | `DOCKER_SCOUT_EXPERIMENTAL_POLICY_OUTPUT` | Boolean | Disable experimental policy output | 37 | 38 | You can found further information about environment variables [here](https://docs.docker.com/scout/how-tos/configure-cli/). 39 | 40 | 41 | ## CLI Plugin Installation 42 | 43 | ### Docker Desktop 44 | 45 | `docker scout` CLI plugin is available by default on [Docker Desktop](https://docs.docker.com/desktop/) starting with version `4.17`. 46 | 47 | ### Manual Installation 48 | 49 | To install it manually: 50 | 51 | - Download the `docker-scout` binary corresponding to your platform from the [latest](https://github.com/docker/scout-cli/releases/latest) or [other](https://github.com/docker/scout-cli/releases) releases. 52 | - Uncompress it as 53 | - `docker-scout` on _Linux_ and _macOS_ 54 | - `docker-scout.exe` on _Windows_ 55 | - Copy the binary to the `scout` directory 56 | - `$HOME/.docker/scout` on _Linux_ and _macOS_ 57 | - `%USERPROFILE%\.docker\scout` on _Windows_ 58 | - Make it executable on _Linux_ and _macOS_ 59 | - `chmod +x $HOME/.docker/scout/docker-scout` 60 | - Authorize the binary to be executable on _macOS_ 61 | - `xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout` 62 | - Add the `scout` directory to your `.docker/config.json` as a plugin directory 63 | - `$HOME/.docker/config.json` on _Linux_ and _macOS_ 64 | - `%USERPROFILE%\.docker\config.json` on _Windows_ 65 | - Add the `cliPluginsExtraDirs` property to the `config.json` file 66 | ``` 67 | { 68 | ... 69 | "cliPluginsExtraDirs": [ 70 | "" 71 | ], 72 | ... 73 | } 74 | ``` 75 | 76 | ### Script Installation (macOS and Linux) 77 | 78 | To install, run the following command in your terminal: 79 | 80 | ```shell 81 | curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- 82 | ``` 83 | 84 | ## Run as container 85 | 86 | A container image to run the Docker Scout CLI in containerized environments is available at [docker/scout-cli](https://hub.docker.com/r/docker/scout-cli). 87 | 88 | ## CI Integration 89 | 90 | Docker Scout CLI can be used in CI environments. See below for the various ways to integrate the CLI into your CI pipelines. 91 | 92 | ### GitHub Action 93 | 94 | An early prototype of running the Docker Scout CLI as part of a GitHub Action workflow is available at [docker/scout-action](https://github.com/docker/scout-action). 95 | 96 | The following GitHub Action workflow can be used as a template to integrate Docker Scout: 97 | 98 | ```yaml 99 | name: Docker 100 | 101 | on: 102 | push: 103 | tags: [ "*" ] 104 | branches: 105 | - 'main' 106 | pull_request: 107 | branches: [ "**" ] 108 | 109 | env: 110 | # Use docker.io for Docker Hub if empty 111 | REGISTRY: docker.io 112 | IMAGE_NAME: ${{ github.repository }} 113 | SHA: ${{ github.event.pull_request.head.sha || github.event.after }} 114 | 115 | jobs: 116 | build: 117 | 118 | runs-on: ubuntu-latest 119 | permissions: 120 | contents: read 121 | packages: write 122 | 123 | steps: 124 | - name: Checkout repository 125 | uses: actions/checkout@v3 126 | with: 127 | ref: ${{ env.SHA }} 128 | 129 | - name: Setup Docker buildx 130 | uses: docker/setup-buildx-action@v2.5.0 131 | 132 | # Login against a Docker registry except on PR 133 | # https://github.com/docker/login-action 134 | - name: Log into registry ${{ env.REGISTRY }} 135 | uses: docker/login-action@v2.1.0 136 | with: 137 | registry: ${{ env.REGISTRY }} 138 | username: ${{ secrets.DOCKER_USER }} 139 | password: ${{ secrets.DOCKER_PAT }} 140 | 141 | # Extract metadata (tags, labels) for Docker 142 | # https://github.com/docker/metadata-action 143 | - name: Extract Docker metadata 144 | id: meta 145 | uses: docker/metadata-action@v4.4.0 146 | with: 147 | images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} 148 | labels: | 149 | org.opencontainers.image.revision=${{ env.SHA }} 150 | tags: | 151 | type=edge,branch=$repo.default_branch 152 | type=semver,pattern=v{{version}} 153 | type=sha,prefix=,suffix=,format=short 154 | 155 | # Build and push Docker image with Buildx (don't push on PR) 156 | # https://github.com/docker/build-push-action 157 | - name: Build and push Docker image 158 | id: build-and-push 159 | uses: docker/build-push-action@v4.0.0 160 | with: 161 | context: . 162 | push: true 163 | tags: ${{ steps.meta.outputs.tags }} 164 | labels: ${{ steps.meta.outputs.labels }} 165 | cache-from: type=gha 166 | cache-to: type=gha,mode=max 167 | 168 | - name: Docker Scout 169 | id: docker-scout 170 | if: ${{ github.event_name == 'pull_request' }} 171 | uses: docker/scout-action@dd36f5b0295baffa006aa6623371f226cc03e506 172 | with: 173 | command: cves 174 | image: ${{ steps.meta.outputs.tags }} 175 | only-severities: critical,high 176 | exit-code: true 177 | ``` 178 | 179 | ### GitLab 180 | 181 | Use the following pipeline definition as a template to get Docker Scout integrated in GitLab CI: 182 | 183 | ```yaml 184 | docker-build: 185 | image: docker:latest 186 | stage: build 187 | services: 188 | - docker:dind 189 | before_script: 190 | - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY 191 | 192 | # Install curl and the Docker Scout CLI 193 | - | 194 | apk add --update curl 195 | curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- 196 | apk del curl 197 | rm -rf /var/cache/apk/* 198 | # Login to Docker Hub required for Docker Scout CLI 199 | - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin 200 | script: 201 | - | 202 | if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then 203 | tag="" 204 | echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'" 205 | else 206 | tag=":$CI_COMMIT_REF_SLUG" 207 | echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag" 208 | fi 209 | - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" . 210 | 211 | - | 212 | if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then 213 | # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected 214 | docker scout cves "$CI_REGISTRY_IMAGE${tag}" --exit-code --only-severity critical,high 215 | else 216 | # Compare image from branch with latest image from the default branch and fail if new critical or high CVEs are detected 217 | docker scout compare "$CI_REGISTRY_IMAGE${tag}" --to "$CI_REGISTRY_IMAGE:latest" --exit-on vulnerability,policy --only-severity critical,high --ignore-unchanged 218 | fi 219 | 220 | - docker push "$CI_REGISTRY_IMAGE${tag}" 221 | rules: 222 | - if: $CI_COMMIT_BRANCH 223 | exists: 224 | - Dockerfile 225 | ``` 226 | 227 | ### CircleCI 228 | 229 | Use the following pipeline definition as a template to get Docker Scout integrated in CircleCI project: 230 | 231 | ```yaml 232 | version: 2.1 233 | 234 | jobs: 235 | 236 | build: 237 | 238 | docker: 239 | - image: cimg/base:stable 240 | 241 | environment: 242 | IMAGE_TAG: docker/scout-demo-service:latest 243 | 244 | steps: 245 | # Checkout the repository files 246 | - checkout 247 | 248 | # Set up a separate Docker environment to run `docker` commands in 249 | - setup_remote_docker: 250 | version: 20.10.24 251 | 252 | # Install Docker Scout and login to Docker Hub 253 | - run: 254 | name: Install Docker Scout 255 | command: | 256 | env 257 | curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /home/circleci/bin 258 | echo $DOCKER_HUB_PAT | docker login -u $DOCKER_HUB_USER --password-stdin 259 | 260 | # Build the Docker image 261 | - run: 262 | name: Build Docker image 263 | command: docker build -t $IMAGE_TAG . 264 | 265 | # Run Docker Scout 266 | - run: 267 | name: Scan image for CVEs 268 | command: | 269 | docker-scout cves $IMAGE_TAG --exit-code --only-severity critical,high 270 | 271 | workflows: 272 | build-docker-image: 273 | jobs: 274 | - build 275 | ``` 276 | 277 | ### Microsoft Azure DevOps Pipelines 278 | 279 | Use the following pipeline definition as a template to get Docker Scout integrated in Azure DevOps Pipelines: 280 | 281 | ```yaml 282 | trigger: 283 | - main 284 | 285 | resources: 286 | - repo: self 287 | 288 | variables: 289 | tag: '$(Build.BuildId)' 290 | image: 'vonwig/nodejs-service' 291 | 292 | stages: 293 | - stage: Build 294 | displayName: Build image 295 | jobs: 296 | - job: Build 297 | displayName: Build 298 | pool: 299 | vmImage: ubuntu-latest 300 | steps: 301 | - task: Docker@2 302 | displayName: Build an image 303 | inputs: 304 | command: build 305 | dockerfile: '$(Build.SourcesDirectory)/Dockerfile' 306 | repository: $(image) 307 | tags: | 308 | $(tag) 309 | - task: CmdLine@2 310 | displayName: Find CVEs on image 311 | inputs: 312 | script: | 313 | # Install the Docker Scout CLI 314 | curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- 315 | # Login to Docker Hub required for Docker Scout CLI 316 | docker login -u $(DOCKER_HUB_USER) -p $(DOCKER_HUB_PAT) 317 | # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected 318 | docker scout cves $(image):$(tag) --exit-code --only-severity critical,high 319 | ``` 320 | 321 | ### Jenkins 322 | 323 | The following snippet can be added to a `Jenkinsfile` to install and analyze images: 324 | 325 | ```groovy 326 | stage('Analyze image') { 327 | steps { 328 | // Install Docker Scout 329 | sh 'curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /usr/local/bin' 330 | 331 | // Log into Docker Hub 332 | sh 'echo $DOCKER_HUB_PAT | docker login -u $DOCKER_HUB_USER --password-stdin' 333 | 334 | // Analyze and fail on critical or high vulnerabilities 335 | sh 'docker-scout cves $IMAGE_TAG --exit-code --only-severity critical,high' 336 | } 337 | } 338 | ``` 339 | 340 | This example assume two secrets to be available to authenticate against Docker Hub, called `DOCKER_HUB_USER` and `DOCKER_HUB_PAT`. 341 | 342 | ### Bitbucket 343 | 344 | Use the following pipeline definition as a template to get Docker Scout integrated in Bitbucket Pipelines: 345 | 346 | ```yaml 347 | image: docker 348 | 349 | pipelines: 350 | default: 351 | - step: 352 | name: Build 353 | services: 354 | - docker 355 | caches: 356 | - docker 357 | script: 358 | - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin $CI_REGISTRY 359 | 360 | # Install curl and the Docker Scout CLI 361 | - | 362 | export DOCKER_BUILDKIT=0 363 | apk add --update curl 364 | curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- 365 | apk del curl 366 | rm -rf /var/cache/apk/* 367 | # Login to Docker Hub required for Docker Scout CLI 368 | - echo "$DOCKER_HUB_PAT" | docker login --username "$DOCKER_HUB_USER" --password-stdin 369 | 370 | - | 371 | export DEVELOPMENT_BRANCH="main" 372 | if [[ "$BITBUCKET_BRANCH" == "$DEVELOPMENT_BRANCH" ]]; then # Bitbucket uses master by default, adjust if your default branch is different 373 | tag=":latest" 374 | echo "Running on default branch '$DEVELOPMENT_BRANCH': tag = 'latest'" 375 | else 376 | tag=":$BITBUCKET_COMMIT" 377 | echo "Running on branch '$BITBUCKET_BRANCH': tag = $tag" 378 | fi 379 | - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" . 380 | 381 | - | 382 | if [[ "$BITBUCKET_BRANCH" == "$DEVELOPMENT_BRANCH" ]]; then 383 | # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected 384 | docker scout cves "$CI_REGISTRY_IMAGE${tag}" --exit-code --only-severity critical,high 385 | else 386 | # Compare image from branch with latest image from the default branch and fail if new critical or high CVEs are detected 387 | docker scout compare "$CI_REGISTRY_IMAGE${tag}" --to "$CI_REGISTRY_IMAGE:latest" --exit-on vulnerability,policy --only-severity critical,high --ignore-unchanged 388 | fi 389 | - docker push "$CI_REGISTRY_IMAGE${tag}" 390 | 391 | definitions: 392 | services: 393 | docker: 394 | memory: 2048 # Optional: Increase if needed 395 | ``` 396 | 397 | This example assumes two secrets to be available to authenticate against Docker Hub, called `DOCKER_HUB_USER` and `DOCKER_HUB_PAT`, also is necessary more two secrets called `CI_REGISTRY`, `CI_REGISTRY_IMAGE` about registry info. 398 | 399 | ## License 400 | 401 | The Docker Scout CLI is licensed under the Terms and Conditions of the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement/). 402 | -------------------------------------------------------------------------------- /docs/docker_scout.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout 2 | short: Command line tool for Docker Scout 3 | long: Command line tool for Docker Scout 4 | usage: docker scout [command] 5 | pname: docker 6 | plink: docker.yaml 7 | cname: 8 | - docker scout attestation 9 | - docker scout cache 10 | - docker scout compare 11 | - docker scout config 12 | - docker scout cves 13 | - docker scout enroll 14 | - docker scout environment 15 | - docker scout help 16 | - docker scout integration 17 | - docker scout policy 18 | - docker scout push 19 | - docker scout quickview 20 | - docker scout recommendations 21 | - docker scout repo 22 | - docker scout version 23 | - docker scout watch 24 | clink: 25 | - docker_scout_attestation.yaml 26 | - docker_scout_cache.yaml 27 | - docker_scout_compare.yaml 28 | - docker_scout_config.yaml 29 | - docker_scout_cves.yaml 30 | - docker_scout_enroll.yaml 31 | - docker_scout_environment.yaml 32 | - docker_scout_help.yaml 33 | - docker_scout_integration.yaml 34 | - docker_scout_policy.yaml 35 | - docker_scout_push.yaml 36 | - docker_scout_quickview.yaml 37 | - docker_scout_recommendations.yaml 38 | - docker_scout_repo.yaml 39 | - docker_scout_version.yaml 40 | - docker_scout_watch.yaml 41 | options: 42 | - option: debug 43 | value_type: bool 44 | default_value: "false" 45 | description: Debug messages 46 | deprecated: false 47 | hidden: true 48 | experimental: false 49 | experimentalcli: false 50 | kubernetes: false 51 | swarm: false 52 | - option: verbose-debug 53 | value_type: bool 54 | default_value: "false" 55 | description: Verbose debug 56 | deprecated: false 57 | hidden: true 58 | experimental: false 59 | experimentalcli: false 60 | kubernetes: false 61 | swarm: false 62 | deprecated: false 63 | experimental: false 64 | experimentalcli: false 65 | kubernetes: false 66 | swarm: false 67 | 68 | -------------------------------------------------------------------------------- /docs/docker_scout_attestation.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout attestation 2 | aliases: docker scout attestation, docker scout attest 3 | short: Manage attestations on image indexes 4 | long: Manage attestations on image indexes 5 | pname: docker scout 6 | plink: docker_scout.yaml 7 | cname: 8 | - docker scout attestation add 9 | clink: 10 | - docker_scout_attestation_add.yaml 11 | inherited_options: 12 | - option: debug 13 | value_type: bool 14 | default_value: "false" 15 | description: Debug messages 16 | deprecated: false 17 | hidden: true 18 | experimental: false 19 | experimentalcli: false 20 | kubernetes: false 21 | swarm: false 22 | - option: verbose-debug 23 | value_type: bool 24 | default_value: "false" 25 | description: Verbose debug 26 | deprecated: false 27 | hidden: true 28 | experimental: false 29 | experimentalcli: false 30 | kubernetes: false 31 | swarm: false 32 | deprecated: false 33 | experimental: false 34 | experimentalcli: true 35 | kubernetes: false 36 | swarm: false 37 | 38 | -------------------------------------------------------------------------------- /docs/docker_scout_attestation_add.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout attestation add 2 | aliases: docker scout attestation add, docker scout attest add 3 | short: Add attestation to image 4 | long: The docker scout attestation add command adds attestations to images. 5 | usage: docker scout attestation add OPTIONS IMAGE [IMAGE...] 6 | pname: docker scout attestation 7 | plink: docker_scout_attestation.yaml 8 | options: 9 | - option: file 10 | value_type: stringSlice 11 | default_value: '[]' 12 | description: File location of attestations to attach 13 | deprecated: false 14 | hidden: false 15 | experimental: false 16 | experimentalcli: false 17 | kubernetes: false 18 | swarm: false 19 | - option: org 20 | value_type: string 21 | description: Namespace of the Docker organization 22 | deprecated: false 23 | hidden: false 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | - option: predicate-type 29 | value_type: string 30 | description: Predicate-type for attestations 31 | deprecated: false 32 | hidden: false 33 | experimental: false 34 | experimentalcli: false 35 | kubernetes: false 36 | swarm: false 37 | - option: referrer 38 | value_type: bool 39 | default_value: "false" 40 | description: Use OCI referrer API for pushing attestation 41 | deprecated: false 42 | hidden: false 43 | experimental: false 44 | experimentalcli: false 45 | kubernetes: false 46 | swarm: false 47 | - option: referrer-repository 48 | value_type: string 49 | default_value: registry.scout.docker.com 50 | description: Repository to push referrer to 51 | deprecated: false 52 | hidden: false 53 | experimental: false 54 | experimentalcli: false 55 | kubernetes: false 56 | swarm: false 57 | inherited_options: 58 | - option: debug 59 | value_type: bool 60 | default_value: "false" 61 | description: Debug messages 62 | deprecated: false 63 | hidden: true 64 | experimental: false 65 | experimentalcli: false 66 | kubernetes: false 67 | swarm: false 68 | - option: verbose-debug 69 | value_type: bool 70 | default_value: "false" 71 | description: Verbose debug 72 | deprecated: false 73 | hidden: true 74 | experimental: false 75 | experimentalcli: false 76 | kubernetes: false 77 | swarm: false 78 | deprecated: false 79 | experimental: false 80 | experimentalcli: true 81 | kubernetes: false 82 | swarm: false 83 | 84 | -------------------------------------------------------------------------------- /docs/docker_scout_cache.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout cache 2 | short: Manage Docker Scout cache and temporary files 3 | long: Manage Docker Scout cache and temporary files 4 | pname: docker scout 5 | plink: docker_scout.yaml 6 | cname: 7 | - docker scout cache df 8 | - docker scout cache prune 9 | clink: 10 | - docker_scout_cache_df.yaml 11 | - docker_scout_cache_prune.yaml 12 | inherited_options: 13 | - option: debug 14 | value_type: bool 15 | default_value: "false" 16 | description: Debug messages 17 | deprecated: false 18 | hidden: true 19 | experimental: false 20 | experimentalcli: false 21 | kubernetes: false 22 | swarm: false 23 | - option: verbose-debug 24 | value_type: bool 25 | default_value: "false" 26 | description: Verbose debug 27 | deprecated: false 28 | hidden: true 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | deprecated: false 34 | experimental: false 35 | experimentalcli: false 36 | kubernetes: false 37 | swarm: false 38 | 39 | -------------------------------------------------------------------------------- /docs/docker_scout_cache_df.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout cache df 2 | short: Show Docker Scout disk usage 3 | long: |- 4 | Docker Scout uses a temporary cache storage for generating image SBOMs. 5 | The cache helps avoid regenerating or fetching resources unnecessarily. 6 | 7 | This `docker scout cache df` command shows the cached data on the host. 8 | Each cache entry is identified by the digest of the image. 9 | 10 | You can use the `docker scout cache prune` command to delete cache data at any time. 11 | usage: docker scout cache df 12 | pname: docker scout cache 13 | plink: docker_scout_cache.yaml 14 | inherited_options: 15 | - option: debug 16 | value_type: bool 17 | default_value: "false" 18 | description: Debug messages 19 | deprecated: false 20 | hidden: true 21 | experimental: false 22 | experimentalcli: false 23 | kubernetes: false 24 | swarm: false 25 | - option: verbose-debug 26 | value_type: bool 27 | default_value: "false" 28 | description: Verbose debug 29 | deprecated: false 30 | hidden: true 31 | experimental: false 32 | experimentalcli: false 33 | kubernetes: false 34 | swarm: false 35 | examples: |- 36 | ### List temporary and cache files 37 | 38 | ```console 39 | $ docker scout cache df 40 | Docker Scout temporary directory to generate SBOMs is located at: 41 | /var/folders/dw/d6h9w2sx6rv3lzwwgrnx7t5h0000gp/T/docker-scout 42 | this path can be configured using the DOCKER_SCOUT_CACHE_DIR environment variable 43 | 44 | Image Digest │ Size 45 | ──────────────────────────────────────────────────────────────────────────┼──────── 46 | sha256:c41ab5c992deb4fe7e5da09f67a8804a46bd0592bfdf0b1847dde0e0889d2bff │ 21 kB 47 | 48 | Total: 21 kB 49 | 50 | 51 | Docker Scout cached SBOMs are located at: 52 | /Users/user/.docker/scout/sbom 53 | 54 | Image Digest │ Size of SBOM 55 | ──────────────────────────────────────────────────────────────────────────┼─────────────── 56 | sha256:02bb6f428431fbc2809c5d1b41eab5a68350194fb508869a33cb1af4444c9b11 │ 42 kB 57 | sha256:03fc002fe4f370463a8f04d3a288cdffa861e462fc8b5be44ab62b296ad95183 │ 100 kB 58 | sha256:088134dd33e4a2997480a1488a41c11abebda465da5cf7f305a0ecf8ed494329 │ 194 kB 59 | sha256:0b80b2f17aff7ee5bfb135c69d0d6fe34070e89042b7aac73d1abcc79cfe6759 │ 852 kB 60 | sha256:0c9e8abe31a5f17d84d5c85d3853d2f948a4f126421e89e68753591f1b6fedc5 │ 930 kB 61 | sha256:0d49cae0723c8d310e413736b5e91e0c59b605ade2546f6e6ef8f1f3ddc76066 │ 510 kB 62 | sha256:0ef04748d071c2e631bb3edce8f805cb5512e746b682c83fdae6d8c0b243280b │ 1.0 MB 63 | sha256:13fd22925b638bb7d2131914bb8f8b0f5f582bee364aec682d9e7fe722bb486a │ 42 kB 64 | sha256:174c41d4fbc7f63e1f2bb7d2f7837318050406f2f27e5073a84a84f18b48b883 │ 115 kB 65 | 66 | Total: 4 MB 67 | ``` 68 | deprecated: false 69 | experimental: false 70 | experimentalcli: false 71 | kubernetes: false 72 | swarm: false 73 | 74 | -------------------------------------------------------------------------------- /docs/docker_scout_cache_prune.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout cache prune 2 | short: Remove temporary or cached data 3 | long: |- 4 | The `docker scout cache prune` command removes temporary data and SBOM cache. 5 | 6 | By default, `docker scout cache prune` only deletes temporary data. 7 | To delete temporary data and clear the SBOM cache, use the `--sboms` flag. 8 | usage: docker scout cache prune 9 | pname: docker scout cache 10 | plink: docker_scout_cache.yaml 11 | options: 12 | - option: force 13 | shorthand: f 14 | value_type: bool 15 | default_value: "false" 16 | description: Do not prompt for confirmation 17 | deprecated: false 18 | hidden: false 19 | experimental: false 20 | experimentalcli: false 21 | kubernetes: false 22 | swarm: false 23 | - option: sboms 24 | value_type: bool 25 | default_value: "false" 26 | description: Prune cached SBOMs 27 | deprecated: false 28 | hidden: false 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | inherited_options: 34 | - option: debug 35 | value_type: bool 36 | default_value: "false" 37 | description: Debug messages 38 | deprecated: false 39 | hidden: true 40 | experimental: false 41 | experimentalcli: false 42 | kubernetes: false 43 | swarm: false 44 | - option: verbose-debug 45 | value_type: bool 46 | default_value: "false" 47 | description: Verbose debug 48 | deprecated: false 49 | hidden: true 50 | experimental: false 51 | experimentalcli: false 52 | kubernetes: false 53 | swarm: false 54 | examples: |- 55 | ### Delete temporary data 56 | 57 | ```console 58 | $ docker scout cache prune 59 | ? Are you sure to delete all temporary data? Yes 60 | ✓ temporary data deleted 61 | ``` 62 | 63 | ### Delete temporary _and_ cache data 64 | 65 | ```console 66 | $ docker scout cache prune --sboms 67 | ? Are you sure to delete all temporary data and all cached SBOMs? Yes 68 | ✓ temporary data deleted 69 | ✓ cached SBOMs deleted 70 | ``` 71 | deprecated: false 72 | experimental: false 73 | experimentalcli: false 74 | kubernetes: false 75 | swarm: false 76 | 77 | -------------------------------------------------------------------------------- /docs/docker_scout_compare.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout compare 2 | aliases: docker scout compare, docker scout diff 3 | short: Compare two images and display differences (experimental) 4 | long: |- 5 | The `docker scout compare` command analyzes two images and displays a comparison. 6 | 7 | > This command is **experimental** and its behaviour might change in the future 8 | 9 | The intended use of this command is to compare two versions of the same image. 10 | For instance, when a new image is built and compared to the version running in production. 11 | 12 | If no image is specified, the most recently built image is used 13 | as a comparison target. 14 | 15 | The following artifact types are supported: 16 | 17 | - Images 18 | - OCI layout directories 19 | - Tarball archives, as created by `docker save` 20 | - Local directory or file 21 | 22 | By default, the tool expects an image reference, such as: 23 | 24 | - `redis` 25 | - `curlimages/curl:7.87.0` 26 | - `mcr.microsoft.com/dotnet/runtime:7.0` 27 | 28 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 29 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 30 | 31 | - `image://` (default) use a local image, or fall back to a registry lookup 32 | - `local://` use an image from the local image store (don't do a registry lookup) 33 | - `registry://` use an image from a registry (don't use a local image) 34 | - `oci-dir://` use an OCI layout directory 35 | - `archive://` use a tarball archive, as created by `docker save` 36 | - `fs://` use a local directory or file 37 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 38 | usage: docker scout compare --to IMAGE|DIRECTORY|ARCHIVE [IMAGE|DIRECTORY|ARCHIVE] 39 | pname: docker scout 40 | plink: docker_scout.yaml 41 | options: 42 | - option: exit-code 43 | shorthand: e 44 | value_type: bool 45 | default_value: "false" 46 | description: Return exit code '2' if vulnerability changes are detected 47 | deprecated: true 48 | hidden: true 49 | experimental: false 50 | experimentalcli: false 51 | kubernetes: false 52 | swarm: false 53 | - option: exit-on 54 | shorthand: x 55 | value_type: stringSlice 56 | default_value: '[]' 57 | description: | 58 | Comma separated list of conditions to fail the action step if worse or changed, options are: vulnerability, policy, package 59 | deprecated: false 60 | hidden: false 61 | experimental: false 62 | experimentalcli: false 63 | kubernetes: false 64 | swarm: false 65 | - option: format 66 | value_type: string 67 | default_value: text 68 | description: |- 69 | Output format of the generated vulnerability report: 70 | - text: default output, plain text with or without colors depending on the terminal 71 | - markdown: Markdown output 72 | deprecated: false 73 | hidden: false 74 | experimental: false 75 | experimentalcli: false 76 | kubernetes: false 77 | swarm: false 78 | - option: hide-policies 79 | value_type: bool 80 | default_value: "false" 81 | description: Hide policy status from the output 82 | deprecated: false 83 | hidden: false 84 | experimental: false 85 | experimentalcli: false 86 | kubernetes: false 87 | swarm: false 88 | - option: ignore-base 89 | value_type: bool 90 | default_value: "false" 91 | description: Filter out CVEs introduced from base image 92 | deprecated: false 93 | hidden: false 94 | experimental: false 95 | experimentalcli: false 96 | kubernetes: false 97 | swarm: false 98 | - option: ignore-unchanged 99 | value_type: bool 100 | default_value: "false" 101 | description: Filter out unchanged packages 102 | deprecated: false 103 | hidden: false 104 | experimental: false 105 | experimentalcli: false 106 | kubernetes: false 107 | swarm: false 108 | - option: multi-stage 109 | value_type: bool 110 | default_value: "false" 111 | description: Show packages from multi-stage Docker builds 112 | deprecated: false 113 | hidden: false 114 | experimental: false 115 | experimentalcli: false 116 | kubernetes: false 117 | swarm: false 118 | - option: only-fixed 119 | value_type: bool 120 | default_value: "false" 121 | description: Filter to fixable CVEs 122 | deprecated: false 123 | hidden: false 124 | experimental: false 125 | experimentalcli: false 126 | kubernetes: false 127 | swarm: false 128 | - option: only-package-type 129 | value_type: stringSlice 130 | default_value: '[]' 131 | description: | 132 | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) 133 | deprecated: false 134 | hidden: false 135 | experimental: false 136 | experimentalcli: false 137 | kubernetes: false 138 | swarm: false 139 | - option: only-policy 140 | value_type: stringSlice 141 | default_value: '[]' 142 | description: Comma separated list of policies to evaluate 143 | deprecated: false 144 | hidden: false 145 | experimental: false 146 | experimentalcli: false 147 | kubernetes: false 148 | swarm: false 149 | - option: only-severity 150 | value_type: stringSlice 151 | default_value: '[]' 152 | description: | 153 | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by 154 | deprecated: false 155 | hidden: false 156 | experimental: false 157 | experimentalcli: false 158 | kubernetes: false 159 | swarm: false 160 | - option: only-stage 161 | value_type: stringSlice 162 | default_value: '[]' 163 | description: Comma separated list of multi-stage Docker build stage names 164 | deprecated: false 165 | hidden: false 166 | experimental: false 167 | experimentalcli: false 168 | kubernetes: false 169 | swarm: false 170 | - option: only-unfixed 171 | value_type: bool 172 | default_value: "false" 173 | description: Filter to unfixed CVEs 174 | deprecated: false 175 | hidden: false 176 | experimental: false 177 | experimentalcli: false 178 | kubernetes: false 179 | swarm: false 180 | - option: org 181 | value_type: string 182 | description: Namespace of the Docker organization 183 | deprecated: false 184 | hidden: false 185 | experimental: false 186 | experimentalcli: false 187 | kubernetes: false 188 | swarm: false 189 | - option: output 190 | shorthand: o 191 | value_type: string 192 | description: Write the report to a file 193 | deprecated: false 194 | hidden: false 195 | experimental: false 196 | experimentalcli: false 197 | kubernetes: false 198 | swarm: false 199 | - option: platform 200 | value_type: string 201 | description: Platform of image to analyze 202 | deprecated: false 203 | hidden: false 204 | experimental: false 205 | experimentalcli: false 206 | kubernetes: false 207 | swarm: false 208 | - option: ref 209 | value_type: string 210 | description: |- 211 | Reference to use if the provided tarball contains multiple references. 212 | Can only be used with archive 213 | deprecated: false 214 | hidden: false 215 | experimental: false 216 | experimentalcli: false 217 | kubernetes: false 218 | swarm: false 219 | - option: to 220 | value_type: string 221 | description: Image, directory, or archive to compare to 222 | deprecated: false 223 | hidden: false 224 | experimental: false 225 | experimentalcli: false 226 | kubernetes: false 227 | swarm: false 228 | - option: to-env 229 | value_type: string 230 | description: Name of environment to compare to 231 | deprecated: false 232 | hidden: false 233 | experimental: false 234 | experimentalcli: false 235 | kubernetes: false 236 | swarm: false 237 | - option: to-latest 238 | value_type: bool 239 | default_value: "false" 240 | description: Latest image processed to compare to 241 | deprecated: false 242 | hidden: false 243 | experimental: false 244 | experimentalcli: false 245 | kubernetes: false 246 | swarm: false 247 | - option: to-ref 248 | value_type: string 249 | description: |- 250 | Reference to use if the provided tarball contains multiple references. 251 | Can only be used with archive. 252 | deprecated: false 253 | hidden: false 254 | experimental: false 255 | experimentalcli: false 256 | kubernetes: false 257 | swarm: false 258 | - option: to-stream 259 | value_type: string 260 | description: Name of stream to compare to 261 | deprecated: true 262 | hidden: true 263 | experimental: false 264 | experimentalcli: false 265 | kubernetes: false 266 | swarm: false 267 | inherited_options: 268 | - option: debug 269 | value_type: bool 270 | default_value: "false" 271 | description: Debug messages 272 | deprecated: false 273 | hidden: true 274 | experimental: false 275 | experimentalcli: false 276 | kubernetes: false 277 | swarm: false 278 | - option: verbose-debug 279 | value_type: bool 280 | default_value: "false" 281 | description: Verbose debug 282 | deprecated: false 283 | hidden: true 284 | experimental: false 285 | experimentalcli: false 286 | kubernetes: false 287 | swarm: false 288 | examples: |- 289 | ### Compare the most recently built image to the latest tag 290 | 291 | ```console 292 | $ docker scout compare --to namespace/repo:latest 293 | ``` 294 | 295 | ### Compare local build to the same tag from the registry 296 | 297 | ```console 298 | $ docker scout compare local://namespace/repo:latest --to registry://namespace/repo:latest 299 | ``` 300 | 301 | ### Ignore base images 302 | 303 | ```console 304 | $ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre 305 | ``` 306 | 307 | ### Generate a markdown output 308 | 309 | ```console 310 | $ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre 311 | ``` 312 | 313 | ### Only compare maven packages and only display critical vulnerabilities for maven packages 314 | 315 | ```console 316 | $ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre 317 | ``` 318 | 319 | ### Show all policy results for both images 320 | 321 | ```console 322 | docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre 323 | ``` 324 | deprecated: false 325 | experimental: false 326 | experimentalcli: true 327 | kubernetes: false 328 | swarm: false 329 | 330 | -------------------------------------------------------------------------------- /docs/docker_scout_config.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout config 2 | short: Manage Docker Scout configuration 3 | long: |- 4 | `docker scout config` allows you to list, get and set Docker Scout configuration. 5 | 6 | Available configuration key: 7 | 8 | - `organization`: Namespace of the Docker organization to be used by default. 9 | usage: docker scout config [KEY] [VALUE] 10 | pname: docker scout 11 | plink: docker_scout.yaml 12 | inherited_options: 13 | - option: debug 14 | value_type: bool 15 | default_value: "false" 16 | description: Debug messages 17 | deprecated: false 18 | hidden: true 19 | experimental: false 20 | experimentalcli: false 21 | kubernetes: false 22 | swarm: false 23 | - option: verbose-debug 24 | value_type: bool 25 | default_value: "false" 26 | description: Verbose debug 27 | deprecated: false 28 | hidden: true 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | examples: |- 34 | ### List existing configuration 35 | 36 | ```console 37 | $ docker scout config 38 | organization=my-org-namespace 39 | ``` 40 | 41 | ### Print configuration value 42 | 43 | ```console 44 | $ docker scout config organization 45 | my-org-namespace 46 | ``` 47 | 48 | ### Set configuration value 49 | 50 | ```console 51 | $ docker scout config organization my-org-namespace 52 | ✓ Successfully set organization to my-org-namespace 53 | ``` 54 | deprecated: false 55 | experimental: false 56 | experimentalcli: false 57 | kubernetes: false 58 | swarm: false 59 | 60 | -------------------------------------------------------------------------------- /docs/docker_scout_cves.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout cves 2 | short: Display CVEs identified in a software artifact 3 | long: |- 4 | The `docker scout cves` command analyzes a software artifact for vulnerabilities. 5 | 6 | If no image is specified, the most recently built image is used. 7 | 8 | The following artifact types are supported: 9 | 10 | - Images 11 | - OCI layout directories 12 | - Tarball archives, as created by `docker save` 13 | - Local directory or file 14 | 15 | By default, the tool expects an image reference, such as: 16 | 17 | - `redis` 18 | - `curlimages/curl:7.87.0` 19 | - `mcr.microsoft.com/dotnet/runtime:7.0` 20 | 21 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 22 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 23 | 24 | - `image://` (default) use a local image, or fall back to a registry lookup 25 | - `local://` use an image from the local image store (don't do a registry lookup) 26 | - `registry://` use an image from a registry (don't use a local image) 27 | - `oci-dir://` use an OCI layout directory 28 | - `archive://` use a tarball archive, as created by `docker save` 29 | - `fs://` use a local directory or file 30 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 31 | In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. 32 | usage: docker scout cves [OPTIONS] [IMAGE|DIRECTORY|ARCHIVE] 33 | pname: docker scout 34 | plink: docker_scout.yaml 35 | options: 36 | - option: details 37 | value_type: bool 38 | default_value: "false" 39 | description: Print details on default text output 40 | deprecated: false 41 | hidden: false 42 | experimental: false 43 | experimentalcli: false 44 | kubernetes: false 45 | swarm: false 46 | - option: env 47 | value_type: string 48 | description: Name of environment 49 | deprecated: false 50 | hidden: false 51 | experimental: false 52 | experimentalcli: false 53 | kubernetes: false 54 | swarm: false 55 | - option: epss 56 | value_type: bool 57 | default_value: "false" 58 | description: | 59 | Display the EPSS scores and organize the package's CVEs according to their EPSS score 60 | details_url: '#epss' 61 | deprecated: false 62 | hidden: false 63 | experimental: false 64 | experimentalcli: false 65 | kubernetes: false 66 | swarm: false 67 | - option: epss-percentile 68 | value_type: float32 69 | default_value: "0" 70 | description: | 71 | Exclude CVEs with EPSS scores less than the specified percentile (0 to 1) 72 | deprecated: false 73 | hidden: false 74 | experimental: false 75 | experimentalcli: false 76 | kubernetes: false 77 | swarm: false 78 | - option: epss-score 79 | value_type: float32 80 | default_value: "0" 81 | description: | 82 | Exclude CVEs with EPSS scores less than the specified value (0 to 1) 83 | deprecated: false 84 | hidden: false 85 | experimental: false 86 | experimentalcli: false 87 | kubernetes: false 88 | swarm: false 89 | - option: exit-code 90 | shorthand: e 91 | value_type: bool 92 | default_value: "false" 93 | description: Return exit code '2' if vulnerabilities are detected 94 | deprecated: false 95 | hidden: false 96 | experimental: false 97 | experimentalcli: false 98 | kubernetes: false 99 | swarm: false 100 | - option: format 101 | value_type: string 102 | default_value: packages 103 | description: |- 104 | Output format of the generated vulnerability report: 105 | - packages: default output, plain text with vulnerabilities grouped by packages 106 | - sarif: json Sarif output 107 | - spdx: json SPDX output 108 | - gitlab: json GitLab output 109 | - markdown: markdown output (including some html tags like collapsible sections) 110 | - sbom: json SBOM output 111 | deprecated: false 112 | hidden: false 113 | experimental: false 114 | experimentalcli: false 115 | kubernetes: false 116 | swarm: false 117 | - option: ignore-base 118 | value_type: bool 119 | default_value: "false" 120 | description: Filter out CVEs introduced from base image 121 | deprecated: false 122 | hidden: false 123 | experimental: false 124 | experimentalcli: false 125 | kubernetes: false 126 | swarm: false 127 | - option: ignore-suppressed 128 | value_type: bool 129 | default_value: "false" 130 | description: | 131 | Filter CVEs found in Scout exceptions based on the specified exception scope 132 | deprecated: false 133 | hidden: false 134 | experimental: false 135 | experimentalcli: false 136 | kubernetes: false 137 | swarm: false 138 | - option: local 139 | value_type: bool 140 | default_value: "false" 141 | description: Local mode 142 | deprecated: false 143 | hidden: true 144 | experimental: false 145 | experimentalcli: false 146 | kubernetes: false 147 | swarm: false 148 | - option: local-vulndb 149 | value_type: string 150 | description: Local vulnerability database 151 | deprecated: false 152 | hidden: true 153 | experimental: false 154 | experimentalcli: false 155 | kubernetes: false 156 | swarm: false 157 | - option: locations 158 | value_type: bool 159 | default_value: "false" 160 | description: Print package locations including file paths and layer diff_id 161 | deprecated: false 162 | hidden: false 163 | experimental: false 164 | experimentalcli: false 165 | kubernetes: false 166 | swarm: false 167 | - option: multi-stage 168 | value_type: bool 169 | default_value: "false" 170 | description: Show packages from multi-stage Docker builds 171 | deprecated: false 172 | hidden: false 173 | experimental: false 174 | experimentalcli: false 175 | kubernetes: false 176 | swarm: false 177 | - option: only-base 178 | value_type: bool 179 | default_value: "false" 180 | description: Only show CVEs introduced by the base image 181 | deprecated: false 182 | hidden: false 183 | experimental: false 184 | experimentalcli: false 185 | kubernetes: false 186 | swarm: false 187 | - option: only-cisa-kev 188 | value_type: bool 189 | default_value: "false" 190 | description: Filter to CVEs listed in the CISA KEV catalog 191 | deprecated: false 192 | hidden: false 193 | experimental: false 194 | experimentalcli: false 195 | kubernetes: false 196 | swarm: false 197 | - option: only-cve-id 198 | value_type: stringSlice 199 | default_value: '[]' 200 | description: | 201 | Comma separated list of CVE ids (like CVE-2021-45105) to search for 202 | deprecated: false 203 | hidden: false 204 | experimental: false 205 | experimentalcli: false 206 | kubernetes: false 207 | swarm: false 208 | - option: only-fixed 209 | value_type: bool 210 | default_value: "false" 211 | description: Filter to fixable CVEs 212 | deprecated: false 213 | hidden: false 214 | experimental: false 215 | experimentalcli: false 216 | kubernetes: false 217 | swarm: false 218 | - option: only-metric 219 | value_type: stringSlice 220 | default_value: '[]' 221 | description: | 222 | Comma separated list of CVSS metrics (like AV:N or PR:L) to filter CVEs by 223 | deprecated: false 224 | hidden: false 225 | experimental: false 226 | experimentalcli: false 227 | kubernetes: false 228 | swarm: false 229 | - option: only-package 230 | value_type: stringSlice 231 | default_value: '[]' 232 | description: Comma separated regular expressions to filter packages by 233 | deprecated: false 234 | hidden: false 235 | experimental: false 236 | experimentalcli: false 237 | kubernetes: false 238 | swarm: false 239 | - option: only-package-type 240 | value_type: stringSlice 241 | default_value: '[]' 242 | description: | 243 | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) 244 | deprecated: false 245 | hidden: false 246 | experimental: false 247 | experimentalcli: false 248 | kubernetes: false 249 | swarm: false 250 | - option: only-severity 251 | value_type: stringSlice 252 | default_value: '[]' 253 | description: | 254 | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by 255 | deprecated: false 256 | hidden: false 257 | experimental: false 258 | experimentalcli: false 259 | kubernetes: false 260 | swarm: false 261 | - option: only-stage 262 | value_type: stringSlice 263 | default_value: '[]' 264 | description: Comma separated list of multi-stage Docker build stage names 265 | deprecated: false 266 | hidden: false 267 | experimental: false 268 | experimentalcli: false 269 | kubernetes: false 270 | swarm: false 271 | - option: only-unfixed 272 | value_type: bool 273 | default_value: "false" 274 | description: Filter to unfixed CVEs 275 | deprecated: false 276 | hidden: false 277 | experimental: false 278 | experimentalcli: false 279 | kubernetes: false 280 | swarm: false 281 | - option: only-vex-affected 282 | value_type: bool 283 | default_value: "false" 284 | description: Filter CVEs by VEX statements with status not affected 285 | deprecated: false 286 | hidden: false 287 | experimental: false 288 | experimentalcli: false 289 | kubernetes: false 290 | swarm: false 291 | - option: only-vuln-packages 292 | value_type: bool 293 | default_value: "false" 294 | description: | 295 | When used with --format=only-packages ignore packages with no vulnerabilities 296 | deprecated: false 297 | hidden: false 298 | experimental: false 299 | experimentalcli: false 300 | kubernetes: false 301 | swarm: false 302 | - option: org 303 | value_type: string 304 | description: Namespace of the Docker organization 305 | deprecated: false 306 | hidden: false 307 | experimental: false 308 | experimentalcli: false 309 | kubernetes: false 310 | swarm: false 311 | - option: output 312 | shorthand: o 313 | value_type: string 314 | description: Write the report to a file 315 | deprecated: false 316 | hidden: false 317 | experimental: false 318 | experimentalcli: false 319 | kubernetes: false 320 | swarm: false 321 | - option: platform 322 | value_type: string 323 | description: Platform of image to analyze 324 | deprecated: false 325 | hidden: false 326 | experimental: false 327 | experimentalcli: false 328 | kubernetes: false 329 | swarm: false 330 | - option: ref 331 | value_type: string 332 | description: |- 333 | Reference to use if the provided tarball contains multiple references. 334 | Can only be used with archive 335 | deprecated: false 336 | hidden: false 337 | experimental: false 338 | experimentalcli: false 339 | kubernetes: false 340 | swarm: false 341 | - option: stream 342 | value_type: string 343 | description: Name of stream 344 | deprecated: true 345 | hidden: true 346 | experimental: false 347 | experimentalcli: false 348 | kubernetes: false 349 | swarm: false 350 | - option: vex 351 | value_type: bool 352 | default_value: "false" 353 | description: Apply VEX statements to filter CVEs 354 | deprecated: true 355 | hidden: true 356 | experimental: false 357 | experimentalcli: false 358 | kubernetes: false 359 | swarm: false 360 | - option: vex-author 361 | value_type: stringSlice 362 | default_value: '[]' 363 | description: List of VEX statement authors to accept 364 | deprecated: false 365 | hidden: false 366 | experimental: false 367 | experimentalcli: false 368 | kubernetes: false 369 | swarm: false 370 | - option: vex-location 371 | value_type: stringSlice 372 | default_value: '[]' 373 | description: File location of directory or file containing VEX statements 374 | deprecated: false 375 | hidden: false 376 | experimental: false 377 | experimentalcli: false 378 | kubernetes: false 379 | swarm: false 380 | inherited_options: 381 | - option: debug 382 | value_type: bool 383 | default_value: "false" 384 | description: Debug messages 385 | deprecated: false 386 | hidden: true 387 | experimental: false 388 | experimentalcli: false 389 | kubernetes: false 390 | swarm: false 391 | - option: verbose-debug 392 | value_type: bool 393 | default_value: "false" 394 | description: Verbose debug 395 | deprecated: false 396 | hidden: true 397 | experimental: false 398 | experimentalcli: false 399 | kubernetes: false 400 | swarm: false 401 | examples: |- 402 | ### Display vulnerabilities grouped by package 403 | 404 | ```console 405 | $ docker scout cves alpine 406 | Analyzing image alpine 407 | ✓ Image stored for indexing 408 | ✓ Indexed 18 packages 409 | ✓ No vulnerable package detected 410 | ``` 411 | 412 | ### Display vulnerabilities from a `docker save` tarball 413 | 414 | ```console 415 | $ docker save alpine > alpine.tar 416 | 417 | $ docker scout cves archive://alpine.tar 418 | Analyzing archive alpine.tar 419 | ✓ Archive read 420 | ✓ SBOM of image already cached, 18 packages indexed 421 | ✓ No vulnerable package detected 422 | ``` 423 | 424 | ### Display vulnerabilities from an OCI directory 425 | 426 | ```console 427 | $ skopeo copy --override-os linux docker://alpine oci:alpine 428 | 429 | $ docker scout cves oci-dir://alpine 430 | Analyzing OCI directory alpine 431 | ✓ OCI directory read 432 | ✓ Image stored for indexing 433 | ✓ Indexed 19 packages 434 | ✓ No vulnerable package detected 435 | ``` 436 | 437 | ### Display vulnerabilities from the current directory 438 | 439 | ```console 440 | $ docker scout cves fs://. 441 | ``` 442 | 443 | ### Export vulnerabilities to a SARIF JSON file 444 | 445 | ```console 446 | $ docker scout cves --format sarif --output alpine.sarif.json alpine 447 | Analyzing image alpine 448 | ✓ SBOM of image already cached, 18 packages indexed 449 | ✓ No vulnerable package detected 450 | ✓ Report written to alpine.sarif.json 451 | ``` 452 | 453 | ### Display markdown output 454 | 455 | The following example shows how to generate the vulnerability report as markdown. 456 | 457 | ```console 458 | $ docker scout cves --format markdown alpine 459 | ✓ Pulled 460 | ✓ SBOM of image already cached, 19 packages indexed 461 | ✗ Detected 1 vulnerable package with 3 vulnerabilities 462 |

:mag: Vulnerabilities of alpine

463 | 464 |
:package: Image Reference alpine 465 | 466 | 467 | 468 | 469 | 470 |
digestsha256:e3bd82196e98898cae9fe7fbfd6e2436530485974dc4fb3b7ddb69134eda2407
vulnerabilitiescritical: 0 high: 0 medium: 2 low: 0 unspecified: 1
platformlinux/arm64
size3.3 MB
packages19
471 |
472 | 473 | ... 474 | ``` 475 | 476 | ### List all vulnerable packages of a certain type 477 | 478 | The following example shows how to generate a list of packages, only including 479 | packages of the specified type, and only showing packages that are vulnerable. 480 | 481 | ```console 482 | $ docker scout cves --format only-packages --only-package-type golang --only-vuln-packages golang:1.18.0 483 | ✓ Pulled 484 | ✓ SBOM of image already cached, 296 packages indexed 485 | ✗ Detected 1 vulnerable package with 40 vulnerabilities 486 | 487 | Name Version Type Vulnerabilities 488 | ─────────────────────────────────────────────────────────── 489 | stdlib 1.18 golang 2C 29H 8M 1L 490 | ``` 491 | 492 | ### Display EPSS score (--epss) {#epss} 493 | 494 | The `--epss` flag adds [Exploit Prediction Scoring System (EPSS)](https://www.first.org/epss/) 495 | scores to the `docker scout cves` output. EPSS scores are estimates of the likelihood (probability) 496 | that a software vulnerability will be exploited in the wild in the next 30 days. 497 | The higher the score, the greater the probability that a vulnerability will be exploited. 498 | 499 | ```console {hl_lines="13,14"} 500 | $ docker scout cves --epss nginx 501 | ✓ Provenance obtained from attestation 502 | ✓ SBOM obtained from attestation, 232 packages indexed 503 | ✓ Pulled 504 | ✗ Detected 23 vulnerable packages with a total of 39 vulnerabilities 505 | 506 | ... 507 | 508 | ✗ HIGH CVE-2023-52425 509 | https://scout.docker.com/v/CVE-2023-52425 510 | Affected range : >=2.5.0-1 511 | Fixed version : not fixed 512 | EPSS Score : 0.000510 513 | EPSS Percentile : 0.173680 514 | ``` 515 | 516 | - `EPSS Score` is a floating point number between 0 and 1 representing the probability of exploitation in the wild in the next 30 days (following score publication). 517 | - `EPSS Percentile` is the percentile of the current score, the proportion of all scored vulnerabilities with the same or a lower EPSS score. 518 | 519 | You can use the `--epss-score` and `--epss-percentile` flags to filter the output 520 | of `docker scout cves` based on these scores. For example, 521 | to only show vulnerabilities with an EPSS score higher than 0.5: 522 | 523 | ```console 524 | $ docker scout cves --epss --epss-score 0.5 nginx 525 | ✓ SBOM of image already cached, 232 packages indexed 526 | ✓ EPSS scores for 2024-03-01 already cached 527 | ✗ Detected 1 vulnerable package with 1 vulnerability 528 | 529 | ... 530 | 531 | ✗ LOW CVE-2023-44487 532 | https://scout.docker.com/v/CVE-2023-44487 533 | Affected range : >=1.22.1-9 534 | Fixed version : not fixed 535 | EPSS Score : 0.705850 536 | EPSS Percentile : 0.979410 537 | ``` 538 | 539 | EPSS scores are updated on a daily basis. 540 | By default, the latest available score is displayed. 541 | You can use the `--epss-date` flag to manually specify a date 542 | in the format `yyyy-mm-dd` for fetching EPSS scores. 543 | 544 | ```console 545 | $ docker scout cves --epss --epss-date 2024-01-02 nginx 546 | ``` 547 | 548 | ### List vulnerabilities from an SPDX file 549 | 550 | The following example shows how to generate a list of vulnerabilities from an SPDX file using `syft`. 551 | 552 | ```console 553 | $ syft -o spdx-json alpine:3.16.1 | docker scout cves sbom:// 554 | ✔ Pulled image 555 | ✔ Loaded image alpine:3.16.1 556 | ✔ Parsed image sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d 557 | ✔ Cataloged contents 274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f 558 | ├── ✔ Packages [14 packages] 559 | ├── ✔ File digests [75 files] 560 | ├── ✔ File metadata [75 locations] 561 | └── ✔ Executables [16 executables] 562 | ✗ Detected 2 vulnerable packages with a total of 11 vulnerabilities 563 | deprecated: false 564 | experimental: false 565 | experimentalcli: false 566 | kubernetes: false 567 | swarm: false 568 | 569 | -------------------------------------------------------------------------------- /docs/docker_scout_docker-cli-plugin-hooks.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout docker-cli-plugin-hooks 2 | short: runs the plugins hooks 3 | long: runs the plugins hooks 4 | usage: docker scout docker-cli-plugin-hooks 5 | pname: docker scout 6 | plink: docker_scout.yaml 7 | inherited_options: 8 | - option: debug 9 | value_type: bool 10 | default_value: "false" 11 | description: Debug messages 12 | deprecated: false 13 | hidden: true 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: verbose-debug 19 | value_type: bool 20 | default_value: "false" 21 | description: Verbose debug 22 | deprecated: false 23 | hidden: true 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | deprecated: false 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | 34 | -------------------------------------------------------------------------------- /docs/docker_scout_enroll.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout enroll 2 | short: Enroll an organization with Docker Scout 3 | long: | 4 | The `docker scout enroll` command enrolls an organization with Docker Scout. 5 | usage: docker scout enroll ORG 6 | pname: docker scout 7 | plink: docker_scout.yaml 8 | inherited_options: 9 | - option: debug 10 | value_type: bool 11 | default_value: "false" 12 | description: Debug messages 13 | deprecated: false 14 | hidden: true 15 | experimental: false 16 | experimentalcli: false 17 | kubernetes: false 18 | swarm: false 19 | - option: verbose-debug 20 | value_type: bool 21 | default_value: "false" 22 | description: Verbose debug 23 | deprecated: false 24 | hidden: true 25 | experimental: false 26 | experimentalcli: false 27 | kubernetes: false 28 | swarm: false 29 | deprecated: false 30 | experimental: false 31 | experimentalcli: false 32 | kubernetes: false 33 | swarm: false 34 | 35 | -------------------------------------------------------------------------------- /docs/docker_scout_environment.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout environment 2 | aliases: docker scout environment, docker scout env 3 | short: Manage environments (experimental) 4 | long: |- 5 | The `docker scout environment` command lists the environments. 6 | If you pass an image reference, the image is recorded to the specified environment. 7 | 8 | Once recorded, environments can be referred to by their name. For example, 9 | you can refer to the `production` environment with the `docker scout compare` 10 | command as follows: 11 | 12 | ```console 13 | $ docker scout compare --to-env production 14 | ``` 15 | usage: docker scout environment [ENVIRONMENT] [IMAGE] 16 | pname: docker scout 17 | plink: docker_scout.yaml 18 | options: 19 | - option: org 20 | value_type: string 21 | description: Namespace of the Docker organization 22 | deprecated: false 23 | hidden: false 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | - option: output 29 | shorthand: o 30 | value_type: string 31 | description: Write the report to a file 32 | deprecated: false 33 | hidden: false 34 | experimental: false 35 | experimentalcli: false 36 | kubernetes: false 37 | swarm: false 38 | - option: platform 39 | value_type: string 40 | description: Platform of image to record 41 | deprecated: false 42 | hidden: false 43 | experimental: false 44 | experimentalcli: false 45 | kubernetes: false 46 | swarm: false 47 | inherited_options: 48 | - option: debug 49 | value_type: bool 50 | default_value: "false" 51 | description: Debug messages 52 | deprecated: false 53 | hidden: true 54 | experimental: false 55 | experimentalcli: false 56 | kubernetes: false 57 | swarm: false 58 | - option: verbose-debug 59 | value_type: bool 60 | default_value: "false" 61 | description: Verbose debug 62 | deprecated: false 63 | hidden: true 64 | experimental: false 65 | experimentalcli: false 66 | kubernetes: false 67 | swarm: false 68 | examples: |- 69 | ### List existing environments 70 | 71 | ```console 72 | $ docker scout environment 73 | prod 74 | staging 75 | ``` 76 | 77 | ### List images of an environment 78 | 79 | ```console 80 | $ docker scout environment staging 81 | namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b 82 | namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f 83 | ``` 84 | 85 | ### Record an image to an environment, for a specific platform 86 | 87 | ```console 88 | $ docker scout environment staging namespace/repo:stage-latest --platform linux/amd64 89 | ✓ Pulled 90 | ✓ Successfully recorded namespace/repo:stage-latest in environment staging 91 | ``` 92 | deprecated: false 93 | experimental: false 94 | experimentalcli: true 95 | kubernetes: false 96 | swarm: false 97 | 98 | -------------------------------------------------------------------------------- /docs/docker_scout_help.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout help 2 | short: Display information about the available commands 3 | long: Display information about the available commands 4 | usage: docker scout help 5 | pname: docker scout 6 | plink: docker_scout.yaml 7 | inherited_options: 8 | - option: debug 9 | value_type: bool 10 | default_value: "false" 11 | description: Debug messages 12 | deprecated: false 13 | hidden: true 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: verbose-debug 19 | value_type: bool 20 | default_value: "false" 21 | description: Verbose debug 22 | deprecated: false 23 | hidden: true 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | deprecated: false 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | 34 | -------------------------------------------------------------------------------- /docs/docker_scout_integration.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout integration 2 | short: Commands to list, configure, and delete Docker Scout integrations 3 | long: Commands to list, configure, and delete Docker Scout integrations 4 | pname: docker scout 5 | plink: docker_scout.yaml 6 | cname: 7 | - docker scout integration configure 8 | - docker scout integration delete 9 | - docker scout integration list 10 | clink: 11 | - docker_scout_integration_configure.yaml 12 | - docker_scout_integration_delete.yaml 13 | - docker_scout_integration_list.yaml 14 | inherited_options: 15 | - option: debug 16 | value_type: bool 17 | default_value: "false" 18 | description: Debug messages 19 | deprecated: false 20 | hidden: true 21 | experimental: false 22 | experimentalcli: false 23 | kubernetes: false 24 | swarm: false 25 | - option: verbose-debug 26 | value_type: bool 27 | default_value: "false" 28 | description: Verbose debug 29 | deprecated: false 30 | hidden: true 31 | experimental: false 32 | experimentalcli: false 33 | kubernetes: false 34 | swarm: false 35 | deprecated: false 36 | experimental: false 37 | experimentalcli: false 38 | kubernetes: false 39 | swarm: false 40 | 41 | -------------------------------------------------------------------------------- /docs/docker_scout_integration_configure.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout integration configure 2 | short: Configure or update a new integration configuration 3 | long: | 4 | The docker scout integration configure command creates or updates a new integration configuration for an organization. 5 | usage: docker scout integration configure INTEGRATION 6 | pname: docker scout integration 7 | plink: docker_scout_integration.yaml 8 | options: 9 | - option: name 10 | value_type: string 11 | description: Name of integration configuration to create 12 | deprecated: false 13 | hidden: false 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: org 19 | value_type: string 20 | description: Namespace of the Docker organization 21 | deprecated: false 22 | hidden: false 23 | experimental: false 24 | experimentalcli: false 25 | kubernetes: false 26 | swarm: false 27 | - option: parameter 28 | value_type: stringSlice 29 | default_value: '[]' 30 | description: Integration parameters in the form of --parameter NAME=VALUE 31 | deprecated: false 32 | hidden: false 33 | experimental: false 34 | experimentalcli: false 35 | kubernetes: false 36 | swarm: false 37 | inherited_options: 38 | - option: debug 39 | value_type: bool 40 | default_value: "false" 41 | description: Debug messages 42 | deprecated: false 43 | hidden: true 44 | experimental: false 45 | experimentalcli: false 46 | kubernetes: false 47 | swarm: false 48 | - option: verbose-debug 49 | value_type: bool 50 | default_value: "false" 51 | description: Verbose debug 52 | deprecated: false 53 | hidden: true 54 | experimental: false 55 | experimentalcli: false 56 | kubernetes: false 57 | swarm: false 58 | deprecated: false 59 | experimental: false 60 | experimentalcli: false 61 | kubernetes: false 62 | swarm: false 63 | 64 | -------------------------------------------------------------------------------- /docs/docker_scout_integration_delete.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout integration delete 2 | short: Delete a new integration configuration 3 | long: | 4 | The docker scout integration delete command deletes a new integration configuration for an organization. 5 | usage: docker scout integration delete INTEGRATION 6 | pname: docker scout integration 7 | plink: docker_scout_integration.yaml 8 | options: 9 | - option: name 10 | value_type: string 11 | description: Name of integration configuration to delete 12 | deprecated: false 13 | hidden: false 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: org 19 | value_type: string 20 | description: Namespace of the Docker organization 21 | deprecated: false 22 | hidden: false 23 | experimental: false 24 | experimentalcli: false 25 | kubernetes: false 26 | swarm: false 27 | inherited_options: 28 | - option: debug 29 | value_type: bool 30 | default_value: "false" 31 | description: Debug messages 32 | deprecated: false 33 | hidden: true 34 | experimental: false 35 | experimentalcli: false 36 | kubernetes: false 37 | swarm: false 38 | - option: verbose-debug 39 | value_type: bool 40 | default_value: "false" 41 | description: Verbose debug 42 | deprecated: false 43 | hidden: true 44 | experimental: false 45 | experimentalcli: false 46 | kubernetes: false 47 | swarm: false 48 | deprecated: false 49 | experimental: false 50 | experimentalcli: false 51 | kubernetes: false 52 | swarm: false 53 | 54 | -------------------------------------------------------------------------------- /docs/docker_scout_integration_list.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout integration list 2 | short: List integrations which can be installed 3 | long: | 4 | The docker scout integration list configured integrations for an organization. 5 | usage: docker scout integration list [INTEGRATION] 6 | pname: docker scout integration 7 | plink: docker_scout_integration.yaml 8 | options: 9 | - option: name 10 | value_type: string 11 | description: Name of integration configuration to list 12 | deprecated: false 13 | hidden: false 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: org 19 | value_type: string 20 | description: Namespace of the Docker organization 21 | deprecated: false 22 | hidden: false 23 | experimental: false 24 | experimentalcli: false 25 | kubernetes: false 26 | swarm: false 27 | inherited_options: 28 | - option: debug 29 | value_type: bool 30 | default_value: "false" 31 | description: Debug messages 32 | deprecated: false 33 | hidden: true 34 | experimental: false 35 | experimentalcli: false 36 | kubernetes: false 37 | swarm: false 38 | - option: verbose-debug 39 | value_type: bool 40 | default_value: "false" 41 | description: Verbose debug 42 | deprecated: false 43 | hidden: true 44 | experimental: false 45 | experimentalcli: false 46 | kubernetes: false 47 | swarm: false 48 | deprecated: false 49 | experimental: false 50 | experimentalcli: false 51 | kubernetes: false 52 | swarm: false 53 | 54 | -------------------------------------------------------------------------------- /docs/docker_scout_policy.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout policy 2 | short: | 3 | Evaluate policies against an image and display the policy evaluation results (experimental) 4 | long: |- 5 | The `docker scout policy` command evaluates policies against an image. 6 | The image analysis is uploaded to Docker Scout where policies get evaluated. 7 | 8 | The policy evaluation results may take a few minutes to become available. 9 | usage: docker scout policy [IMAGE | REPO] 10 | pname: docker scout 11 | plink: docker_scout.yaml 12 | options: 13 | - option: env 14 | value_type: string 15 | description: Name of the environment to compare to 16 | deprecated: true 17 | hidden: true 18 | experimental: false 19 | experimentalcli: false 20 | kubernetes: false 21 | swarm: false 22 | - option: exit-code 23 | shorthand: e 24 | value_type: bool 25 | default_value: "false" 26 | description: Return exit code '2' if policies are not met, '0' otherwise 27 | deprecated: false 28 | hidden: false 29 | experimental: false 30 | experimentalcli: false 31 | kubernetes: false 32 | swarm: false 33 | - option: only-policy 34 | value_type: stringSlice 35 | default_value: '[]' 36 | description: Comma separated list of policies to evaluate 37 | deprecated: false 38 | hidden: false 39 | experimental: false 40 | experimentalcli: false 41 | kubernetes: false 42 | swarm: false 43 | - option: org 44 | value_type: string 45 | description: Namespace of the Docker organization 46 | deprecated: false 47 | hidden: false 48 | experimental: false 49 | experimentalcli: false 50 | kubernetes: false 51 | swarm: false 52 | - option: output 53 | shorthand: o 54 | value_type: string 55 | description: Write the report to a file 56 | deprecated: false 57 | hidden: false 58 | experimental: false 59 | experimentalcli: false 60 | kubernetes: false 61 | swarm: false 62 | - option: platform 63 | value_type: string 64 | description: Platform of image to pull policy results from 65 | deprecated: false 66 | hidden: false 67 | experimental: false 68 | experimentalcli: false 69 | kubernetes: false 70 | swarm: false 71 | - option: to-env 72 | value_type: string 73 | description: Name of the environment to compare to 74 | deprecated: false 75 | hidden: false 76 | experimental: false 77 | experimentalcli: false 78 | kubernetes: false 79 | swarm: false 80 | - option: to-latest 81 | value_type: bool 82 | default_value: "false" 83 | description: Latest image processed to compare to 84 | deprecated: false 85 | hidden: false 86 | experimental: false 87 | experimentalcli: false 88 | kubernetes: false 89 | swarm: false 90 | inherited_options: 91 | - option: debug 92 | value_type: bool 93 | default_value: "false" 94 | description: Debug messages 95 | deprecated: false 96 | hidden: true 97 | experimental: false 98 | experimentalcli: false 99 | kubernetes: false 100 | swarm: false 101 | - option: verbose-debug 102 | value_type: bool 103 | default_value: "false" 104 | description: Verbose debug 105 | deprecated: false 106 | hidden: true 107 | experimental: false 108 | experimentalcli: false 109 | kubernetes: false 110 | swarm: false 111 | examples: |- 112 | ### Evaluate policies against an image and display the results 113 | 114 | ```console 115 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 116 | ``` 117 | 118 | ### Evaluate policies against an image for a specific organization 119 | 120 | ```console 121 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --org dockerscoutpolicy 122 | ``` 123 | 124 | ### Evaluate policies against an image with a specific platform 125 | 126 | ```console 127 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --platform linux/amd64 128 | ``` 129 | 130 | ### Compare policy results for a repository in a specific environment 131 | 132 | ```console 133 | $ docker scout policy dockerscoutpolicy/customers-api-service --to-env production 134 | ``` 135 | deprecated: false 136 | experimental: false 137 | experimentalcli: true 138 | kubernetes: false 139 | swarm: false 140 | 141 | -------------------------------------------------------------------------------- /docs/docker_scout_push.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout push 2 | short: Push an image or image index to Docker Scout 3 | long: | 4 | The `docker scout push` command lets you push an image or analysis result to Docker Scout. 5 | usage: docker scout push IMAGE 6 | pname: docker scout 7 | plink: docker_scout.yaml 8 | options: 9 | - option: author 10 | value_type: string 11 | description: Name of the author of the image 12 | deprecated: false 13 | hidden: false 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: dry-run 19 | value_type: bool 20 | default_value: "false" 21 | description: Do not push the image but process it 22 | deprecated: false 23 | hidden: false 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | - option: org 29 | value_type: string 30 | description: Namespace of the Docker organization to which image will be pushed 31 | deprecated: false 32 | hidden: false 33 | experimental: false 34 | experimentalcli: false 35 | kubernetes: false 36 | swarm: false 37 | - option: output 38 | shorthand: o 39 | value_type: string 40 | description: Write the report to a file 41 | deprecated: false 42 | hidden: false 43 | experimental: false 44 | experimentalcli: false 45 | kubernetes: false 46 | swarm: false 47 | - option: platform 48 | value_type: string 49 | description: Platform of image to be pushed 50 | deprecated: false 51 | hidden: false 52 | experimental: false 53 | experimentalcli: false 54 | kubernetes: false 55 | swarm: false 56 | - option: sbom 57 | value_type: bool 58 | default_value: "false" 59 | description: Create and upload SBOMs 60 | deprecated: false 61 | hidden: false 62 | experimental: false 63 | experimentalcli: false 64 | kubernetes: false 65 | swarm: false 66 | - option: secrets 67 | value_type: bool 68 | default_value: "false" 69 | description: Scan for secrets in the image 70 | deprecated: false 71 | hidden: false 72 | experimental: false 73 | experimentalcli: false 74 | kubernetes: false 75 | swarm: false 76 | - option: timestamp 77 | value_type: string 78 | description: Timestamp of image or tag creation 79 | deprecated: false 80 | hidden: false 81 | experimental: false 82 | experimentalcli: false 83 | kubernetes: false 84 | swarm: false 85 | inherited_options: 86 | - option: debug 87 | value_type: bool 88 | default_value: "false" 89 | description: Debug messages 90 | deprecated: false 91 | hidden: true 92 | experimental: false 93 | experimentalcli: false 94 | kubernetes: false 95 | swarm: false 96 | - option: verbose-debug 97 | value_type: bool 98 | default_value: "false" 99 | description: Verbose debug 100 | deprecated: false 101 | hidden: true 102 | experimental: false 103 | experimentalcli: false 104 | kubernetes: false 105 | swarm: false 106 | examples: |- 107 | ### Push an image to Docker Scout 108 | 109 | ```console 110 | $ docker scout push --org my-org registry.example.com/repo:tag 111 | ``` 112 | deprecated: false 113 | experimental: false 114 | experimentalcli: false 115 | kubernetes: false 116 | swarm: false 117 | 118 | -------------------------------------------------------------------------------- /docs/docker_scout_quickview.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout quickview 2 | aliases: docker scout quickview, docker scout qv 3 | short: Quick overview of an image 4 | long: |- 5 | The `docker scout quickview` command displays a quick overview of an image. 6 | It displays a summary of the vulnerabilities in the specified image 7 | and vulnerabilities from the base image. 8 | If available, it also displays base image refresh and update recommendations. 9 | 10 | If no image is specified, the most recently built image is used. 11 | 12 | The following artifact types are supported: 13 | 14 | - Images 15 | - OCI layout directories 16 | - Tarball archives, as created by `docker save` 17 | - Local directory or file 18 | 19 | By default, the tool expects an image reference, such as: 20 | 21 | - `redis` 22 | - `curlimages/curl:7.87.0` 23 | - `mcr.microsoft.com/dotnet/runtime:7.0` 24 | 25 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 26 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 27 | 28 | - `image://` (default) use a local image, or fall back to a registry lookup 29 | - `local://` use an image from the local image store (don't do a registry lookup) 30 | - `registry://` use an image from a registry (don't use a local image) 31 | - `oci-dir://` use an OCI layout directory 32 | - `archive://` use a tarball archive, as created by `docker save` 33 | - `fs://` use a local directory or file 34 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 35 | In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. 36 | usage: docker scout quickview [IMAGE|DIRECTORY|ARCHIVE] 37 | pname: docker scout 38 | plink: docker_scout.yaml 39 | options: 40 | - option: env 41 | value_type: string 42 | description: Name of the environment 43 | deprecated: false 44 | hidden: false 45 | experimental: false 46 | experimentalcli: false 47 | kubernetes: false 48 | swarm: false 49 | - option: ignore-suppressed 50 | value_type: bool 51 | default_value: "false" 52 | description: | 53 | Filter CVEs found in Scout exceptions based on the specified exception scope 54 | deprecated: false 55 | hidden: false 56 | experimental: false 57 | experimentalcli: false 58 | kubernetes: false 59 | swarm: false 60 | - option: latest 61 | value_type: bool 62 | default_value: "false" 63 | description: Latest indexed image 64 | deprecated: false 65 | hidden: false 66 | experimental: false 67 | experimentalcli: false 68 | kubernetes: false 69 | swarm: false 70 | - option: only-policy 71 | value_type: stringSlice 72 | default_value: '[]' 73 | description: Comma separated list of policies to evaluate 74 | deprecated: false 75 | hidden: false 76 | experimental: false 77 | experimentalcli: false 78 | kubernetes: false 79 | swarm: false 80 | - option: only-vex-affected 81 | value_type: bool 82 | default_value: "false" 83 | description: Filter CVEs by VEX statements with status not affected 84 | deprecated: false 85 | hidden: false 86 | experimental: false 87 | experimentalcli: false 88 | kubernetes: false 89 | swarm: false 90 | - option: org 91 | value_type: string 92 | description: Namespace of the Docker organization 93 | deprecated: false 94 | hidden: false 95 | experimental: false 96 | experimentalcli: false 97 | kubernetes: false 98 | swarm: false 99 | - option: output 100 | shorthand: o 101 | value_type: string 102 | description: Write the report to a file 103 | deprecated: false 104 | hidden: false 105 | experimental: false 106 | experimentalcli: false 107 | kubernetes: false 108 | swarm: false 109 | - option: platform 110 | value_type: string 111 | description: Platform of image to analyze 112 | deprecated: false 113 | hidden: false 114 | experimental: false 115 | experimentalcli: false 116 | kubernetes: false 117 | swarm: false 118 | - option: ref 119 | value_type: string 120 | description: |- 121 | Reference to use if the provided tarball contains multiple references. 122 | Can only be used with archive 123 | deprecated: false 124 | hidden: false 125 | experimental: false 126 | experimentalcli: false 127 | kubernetes: false 128 | swarm: false 129 | - option: stream 130 | value_type: string 131 | description: Name of stream 132 | deprecated: true 133 | hidden: true 134 | experimental: false 135 | experimentalcli: false 136 | kubernetes: false 137 | swarm: false 138 | - option: vex 139 | value_type: bool 140 | default_value: "false" 141 | description: Apply VEX statements to filter CVEs 142 | deprecated: true 143 | hidden: true 144 | experimental: false 145 | experimentalcli: false 146 | kubernetes: false 147 | swarm: false 148 | - option: vex-author 149 | value_type: stringSlice 150 | default_value: '[]' 151 | description: List of VEX statement authors to accept 152 | deprecated: false 153 | hidden: false 154 | experimental: false 155 | experimentalcli: false 156 | kubernetes: false 157 | swarm: false 158 | - option: vex-location 159 | value_type: stringSlice 160 | default_value: '[]' 161 | description: File location of directory or file containing VEX statements 162 | deprecated: false 163 | hidden: false 164 | experimental: false 165 | experimentalcli: false 166 | kubernetes: false 167 | swarm: false 168 | inherited_options: 169 | - option: debug 170 | value_type: bool 171 | default_value: "false" 172 | description: Debug messages 173 | deprecated: false 174 | hidden: true 175 | experimental: false 176 | experimentalcli: false 177 | kubernetes: false 178 | swarm: false 179 | - option: verbose-debug 180 | value_type: bool 181 | default_value: "false" 182 | description: Verbose debug 183 | deprecated: false 184 | hidden: true 185 | experimental: false 186 | experimentalcli: false 187 | kubernetes: false 188 | swarm: false 189 | examples: |- 190 | ### Quick overview of an image 191 | 192 | ```console 193 | $ docker scout quickview golang:1.19.4 194 | ...Pulling 195 | ✓ Pulled 196 | ✓ SBOM of image already cached, 278 packages indexed 197 | 198 | Your image golang:1.19.4 │ 5C 3H 6M 63L 199 | Base image buildpack-deps:bullseye-scm │ 5C 1H 3M 48L 6? 200 | Refreshed base image buildpack-deps:bullseye-scm │ 0C 0H 0M 42L 201 | │ -5 -1 -3 -6 -6 202 | Updated base image buildpack-deps:sid-scm │ 0C 0H 1M 29L 203 | │ -5 -1 -2 -19 -6 204 | ``` 205 | 206 | ### Quick overview of the most recently built image 207 | 208 | ```console 209 | $ docker scout qv 210 | ``` 211 | 212 | ### Quick overview from an SPDX file 213 | 214 | ```console 215 | $ syft -o spdx-json alpine:3.16.1 | docker scout quickview sbom:// 216 | ✔ Loaded image alpine:3.16.1 217 | ✔ Parsed image sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d 218 | ✔ Cataloged contents 274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f 219 | ├── ✔ Packages [14 packages] 220 | ├── ✔ File digests [75 files] 221 | ├── ✔ File metadata [75 locations] 222 | └── ✔ Executables [16 executables] 223 | 224 | Target │ │ 1C 2H 8M 0L 225 | digest │ 274a317d88b5 │ 226 | ``` 227 | deprecated: false 228 | experimental: false 229 | experimentalcli: false 230 | kubernetes: false 231 | swarm: false 232 | 233 | -------------------------------------------------------------------------------- /docs/docker_scout_recommendations.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout recommendations 2 | short: Display available base image updates and remediation recommendations 3 | long: |- 4 | The `docker scout recommendations` command display recommendations for base images updates. 5 | It analyzes the image and display recommendations to refresh or update the base image. 6 | For each recommendation it shows a list of benefits, such as 7 | fewer vulnerabilities or smaller image size. 8 | 9 | If no image is specified, the most recently built image is used. 10 | 11 | The following artifact types are supported: 12 | 13 | - Images 14 | - OCI layout directories 15 | - Tarball archives, as created by `docker save` 16 | - Local directory or file 17 | 18 | By default, the tool expects an image reference, such as: 19 | 20 | - `redis` 21 | - `curlimages/curl:7.87.0` 22 | - `mcr.microsoft.com/dotnet/runtime:7.0` 23 | 24 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 25 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 26 | 27 | - `image://` (default) use a local image, or fall back to a registry lookup 28 | - `local://` use an image from the local image store (don't do a registry lookup) 29 | - `registry://` use an image from a registry (don't use a local image) 30 | - `oci-dir://` use an OCI layout directory 31 | - `archive://` use a tarball archive, as created by `docker save` 32 | - `fs://` use a local directory or file 33 | usage: docker scout recommendations [IMAGE|DIRECTORY|ARCHIVE] 34 | pname: docker scout 35 | plink: docker_scout.yaml 36 | options: 37 | - option: only-refresh 38 | value_type: bool 39 | default_value: "false" 40 | description: Only display base image refresh recommendations 41 | deprecated: false 42 | hidden: false 43 | experimental: false 44 | experimentalcli: false 45 | kubernetes: false 46 | swarm: false 47 | - option: only-update 48 | value_type: bool 49 | default_value: "false" 50 | description: Only display base image update recommendations 51 | deprecated: false 52 | hidden: false 53 | experimental: false 54 | experimentalcli: false 55 | kubernetes: false 56 | swarm: false 57 | - option: org 58 | value_type: string 59 | description: Namespace of the Docker organization 60 | deprecated: false 61 | hidden: false 62 | experimental: false 63 | experimentalcli: false 64 | kubernetes: false 65 | swarm: false 66 | - option: output 67 | shorthand: o 68 | value_type: string 69 | description: Write the report to a file 70 | deprecated: false 71 | hidden: false 72 | experimental: false 73 | experimentalcli: false 74 | kubernetes: false 75 | swarm: false 76 | - option: platform 77 | value_type: string 78 | description: Platform of image to analyze 79 | deprecated: false 80 | hidden: false 81 | experimental: false 82 | experimentalcli: false 83 | kubernetes: false 84 | swarm: false 85 | - option: ref 86 | value_type: string 87 | description: |- 88 | Reference to use if the provided tarball contains multiple references. 89 | Can only be used with archive 90 | deprecated: false 91 | hidden: false 92 | experimental: false 93 | experimentalcli: false 94 | kubernetes: false 95 | swarm: false 96 | - option: tag 97 | value_type: string 98 | description: Specify tag 99 | deprecated: false 100 | hidden: false 101 | experimental: false 102 | experimentalcli: false 103 | kubernetes: false 104 | swarm: false 105 | inherited_options: 106 | - option: debug 107 | value_type: bool 108 | default_value: "false" 109 | description: Debug messages 110 | deprecated: false 111 | hidden: true 112 | experimental: false 113 | experimentalcli: false 114 | kubernetes: false 115 | swarm: false 116 | - option: verbose-debug 117 | value_type: bool 118 | default_value: "false" 119 | description: Verbose debug 120 | deprecated: false 121 | hidden: true 122 | experimental: false 123 | experimentalcli: false 124 | kubernetes: false 125 | swarm: false 126 | examples: |- 127 | ### Display base image update recommendations 128 | 129 | ```console 130 | $ docker scout recommendations golang:1.19.4 131 | ``` 132 | 133 | ### Display base image refresh only recommendations 134 | 135 | ```console 136 | $ docker scout recommendations --only-refresh golang:1.19.4 137 | ``` 138 | 139 | ### Display base image update only recommendations 140 | 141 | ```console 142 | $ docker scout recommendations --only-update golang:1.19.4 143 | ``` 144 | deprecated: false 145 | experimental: false 146 | experimentalcli: false 147 | kubernetes: false 148 | swarm: false 149 | 150 | -------------------------------------------------------------------------------- /docs/docker_scout_repo.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout repo 2 | short: Commands to list, enable, and disable Docker Scout on repositories 3 | long: Commands to list, enable, and disable Docker Scout on repositories 4 | pname: docker scout 5 | plink: docker_scout.yaml 6 | cname: 7 | - docker scout repo disable 8 | - docker scout repo enable 9 | - docker scout repo list 10 | clink: 11 | - docker_scout_repo_disable.yaml 12 | - docker_scout_repo_enable.yaml 13 | - docker_scout_repo_list.yaml 14 | inherited_options: 15 | - option: debug 16 | value_type: bool 17 | default_value: "false" 18 | description: Debug messages 19 | deprecated: false 20 | hidden: true 21 | experimental: false 22 | experimentalcli: false 23 | kubernetes: false 24 | swarm: false 25 | - option: verbose-debug 26 | value_type: bool 27 | default_value: "false" 28 | description: Verbose debug 29 | deprecated: false 30 | hidden: true 31 | experimental: false 32 | experimentalcli: false 33 | kubernetes: false 34 | swarm: false 35 | deprecated: false 36 | experimental: false 37 | experimentalcli: false 38 | kubernetes: false 39 | swarm: false 40 | 41 | -------------------------------------------------------------------------------- /docs/docker_scout_repo_disable.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout repo disable 2 | short: Disable Docker Scout 3 | long: | 4 | The docker scout repo disable command disables Docker Scout on repositories. 5 | usage: docker scout repo disable [REPOSITORY] 6 | pname: docker scout repo 7 | plink: docker_scout_repo.yaml 8 | options: 9 | - option: all 10 | value_type: bool 11 | default_value: "false" 12 | description: | 13 | Disable all repositories of the organization. Can not be used with --filter. 14 | deprecated: false 15 | hidden: false 16 | experimental: false 17 | experimentalcli: false 18 | kubernetes: false 19 | swarm: false 20 | - option: filter 21 | value_type: string 22 | description: Regular expression to filter repositories by name 23 | deprecated: false 24 | hidden: false 25 | experimental: false 26 | experimentalcli: false 27 | kubernetes: false 28 | swarm: false 29 | - option: integration 30 | value_type: string 31 | description: Name of the integration to use for enabling an image 32 | deprecated: false 33 | hidden: false 34 | experimental: false 35 | experimentalcli: false 36 | kubernetes: false 37 | swarm: false 38 | - option: org 39 | value_type: string 40 | description: Namespace of the Docker organization 41 | deprecated: false 42 | hidden: false 43 | experimental: false 44 | experimentalcli: false 45 | kubernetes: false 46 | swarm: false 47 | - option: registry 48 | value_type: string 49 | description: Container Registry 50 | deprecated: false 51 | hidden: false 52 | experimental: false 53 | experimentalcli: false 54 | kubernetes: false 55 | swarm: false 56 | inherited_options: 57 | - option: debug 58 | value_type: bool 59 | default_value: "false" 60 | description: Debug messages 61 | deprecated: false 62 | hidden: true 63 | experimental: false 64 | experimentalcli: false 65 | kubernetes: false 66 | swarm: false 67 | - option: verbose-debug 68 | value_type: bool 69 | default_value: "false" 70 | description: Verbose debug 71 | deprecated: false 72 | hidden: true 73 | experimental: false 74 | experimentalcli: false 75 | kubernetes: false 76 | swarm: false 77 | examples: |- 78 | ### Disable a specific repository 79 | 80 | ```console 81 | $ docker scout repo disable my/repository 82 | ``` 83 | 84 | ### Disable all repositories of the organization 85 | 86 | ```console 87 | $ docker scout repo disable --all 88 | ``` 89 | 90 | ### Disable some repositories based on a filter 91 | 92 | ```console 93 | $ docker scout repo disable --filter namespace/backend 94 | ``` 95 | 96 | ### Disable a repository from a specific registry 97 | 98 | ```console 99 | $ docker scout repo disable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com 100 | ``` 101 | deprecated: false 102 | experimental: false 103 | experimentalcli: false 104 | kubernetes: false 105 | swarm: false 106 | 107 | -------------------------------------------------------------------------------- /docs/docker_scout_repo_enable.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout repo enable 2 | short: Enable Docker Scout 3 | long: The docker scout repo enable command enables Docker Scout on repositories. 4 | usage: docker scout repo enable [REPOSITORY] 5 | pname: docker scout repo 6 | plink: docker_scout_repo.yaml 7 | options: 8 | - option: all 9 | value_type: bool 10 | default_value: "false" 11 | description: | 12 | Enable all repositories of the organization. Can not be used with --filter. 13 | deprecated: false 14 | hidden: false 15 | experimental: false 16 | experimentalcli: false 17 | kubernetes: false 18 | swarm: false 19 | - option: filter 20 | value_type: string 21 | description: Regular expression to filter repositories by name 22 | deprecated: false 23 | hidden: false 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | - option: integration 29 | value_type: string 30 | description: Name of the integration to use for enabling an image 31 | deprecated: false 32 | hidden: false 33 | experimental: false 34 | experimentalcli: false 35 | kubernetes: false 36 | swarm: false 37 | - option: org 38 | value_type: string 39 | description: Namespace of the Docker organization 40 | deprecated: false 41 | hidden: false 42 | experimental: false 43 | experimentalcli: false 44 | kubernetes: false 45 | swarm: false 46 | - option: registry 47 | value_type: string 48 | description: Container Registry 49 | deprecated: false 50 | hidden: false 51 | experimental: false 52 | experimentalcli: false 53 | kubernetes: false 54 | swarm: false 55 | inherited_options: 56 | - option: debug 57 | value_type: bool 58 | default_value: "false" 59 | description: Debug messages 60 | deprecated: false 61 | hidden: true 62 | experimental: false 63 | experimentalcli: false 64 | kubernetes: false 65 | swarm: false 66 | - option: verbose-debug 67 | value_type: bool 68 | default_value: "false" 69 | description: Verbose debug 70 | deprecated: false 71 | hidden: true 72 | experimental: false 73 | experimentalcli: false 74 | kubernetes: false 75 | swarm: false 76 | examples: |- 77 | ### Enable a specific repository 78 | 79 | ```console 80 | $ docker scout repo enable my/repository 81 | ``` 82 | 83 | ### Enable all repositories of the organization 84 | 85 | ```console 86 | $ docker scout repo enable --all 87 | ``` 88 | 89 | ### Enable some repositories based on a filter 90 | 91 | ```console 92 | $ docker scout repo enable --filter namespace/backend 93 | ``` 94 | 95 | ### Enable a repository from a specific registry 96 | 97 | ```console 98 | $ docker scout repo enable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com 99 | ``` 100 | deprecated: false 101 | experimental: false 102 | experimentalcli: false 103 | kubernetes: false 104 | swarm: false 105 | 106 | -------------------------------------------------------------------------------- /docs/docker_scout_repo_list.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout repo list 2 | short: List Docker Scout repositories 3 | long: |- 4 | The docker scout repo list command shows all repositories in an organization. 5 | 6 | If ORG is not provided the default configured organization will be used. 7 | usage: docker scout repo list 8 | pname: docker scout repo 9 | plink: docker_scout_repo.yaml 10 | options: 11 | - option: filter 12 | value_type: string 13 | description: Regular expression to filter repositories by name 14 | deprecated: false 15 | hidden: false 16 | experimental: false 17 | experimentalcli: false 18 | kubernetes: false 19 | swarm: false 20 | - option: only-disabled 21 | value_type: bool 22 | default_value: "false" 23 | description: Filter to disabled repositories only 24 | deprecated: false 25 | hidden: false 26 | experimental: false 27 | experimentalcli: false 28 | kubernetes: false 29 | swarm: false 30 | - option: only-enabled 31 | value_type: bool 32 | default_value: "false" 33 | description: Filter to enabled repositories only 34 | deprecated: false 35 | hidden: false 36 | experimental: false 37 | experimentalcli: false 38 | kubernetes: false 39 | swarm: false 40 | - option: only-registry 41 | value_type: string 42 | description: |- 43 | Filter to a specific registry only: 44 | - hub.docker.com 45 | - ecr (AWS ECR) 46 | deprecated: false 47 | hidden: false 48 | experimental: false 49 | experimentalcli: false 50 | kubernetes: false 51 | swarm: false 52 | - option: org 53 | value_type: string 54 | description: Namespace of the Docker organization 55 | deprecated: false 56 | hidden: false 57 | experimental: false 58 | experimentalcli: false 59 | kubernetes: false 60 | swarm: false 61 | inherited_options: 62 | - option: debug 63 | value_type: bool 64 | default_value: "false" 65 | description: Debug messages 66 | deprecated: false 67 | hidden: true 68 | experimental: false 69 | experimentalcli: false 70 | kubernetes: false 71 | swarm: false 72 | - option: verbose-debug 73 | value_type: bool 74 | default_value: "false" 75 | description: Verbose debug 76 | deprecated: false 77 | hidden: true 78 | experimental: false 79 | experimentalcli: false 80 | kubernetes: false 81 | swarm: false 82 | deprecated: false 83 | experimental: false 84 | experimentalcli: false 85 | kubernetes: false 86 | swarm: false 87 | 88 | -------------------------------------------------------------------------------- /docs/docker_scout_sbom.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout sbom 2 | short: Generate or display SBOM of an image 3 | long: |- 4 | The `docker scout sbom` command analyzes a software artifact to generate a 5 | Software Bill Of Materials (SBOM). 6 | 7 | The SBOM contains a list of all packages in the image. 8 | You can use the `--format` flag to filter the output of the command 9 | to display only packages of a specific type. 10 | 11 | If no image is specified, the most recently built image is used. 12 | 13 | The following artifact types are supported: 14 | 15 | - Images 16 | - OCI layout directories 17 | - Tarball archives, as created by `docker save` 18 | - Local directory or file 19 | 20 | By default, the tool expects an image reference, such as: 21 | 22 | - `redis` 23 | - `curlimages/curl:7.87.0` 24 | - `mcr.microsoft.com/dotnet/runtime:7.0` 25 | 26 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 27 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 28 | 29 | - `image://` (default) use a local image, or fall back to a registry lookup 30 | - `local://` use an image from the local image store (don't do a registry lookup) 31 | - `registry://` use an image from a registry (don't use a local image) 32 | - `oci-dir://` use an OCI layout directory 33 | - `archive://` use a tarball archive, as created by `docker save` 34 | - `fs://` use a local directory or file 35 | usage: docker scout sbom [IMAGE|DIRECTORY|ARCHIVE] 36 | pname: docker scout 37 | plink: docker_scout.yaml 38 | options: 39 | - option: format 40 | value_type: string 41 | default_value: json 42 | description: |- 43 | Output format: 44 | - list: list of packages of the image 45 | - json: json representation of the SBOM 46 | - spdx: spdx representation of the SBOM 47 | - cyclonedx: cyclone dx representation of the SBOM 48 | deprecated: false 49 | hidden: false 50 | experimental: false 51 | experimentalcli: false 52 | kubernetes: false 53 | swarm: false 54 | - option: only-package-type 55 | value_type: stringSlice 56 | default_value: '[]' 57 | description: |- 58 | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) 59 | Can only be used with --format list 60 | deprecated: false 61 | hidden: false 62 | experimental: false 63 | experimentalcli: false 64 | kubernetes: false 65 | swarm: false 66 | - option: output 67 | shorthand: o 68 | value_type: string 69 | description: Write the report to a file 70 | deprecated: false 71 | hidden: false 72 | experimental: false 73 | experimentalcli: false 74 | kubernetes: false 75 | swarm: false 76 | - option: platform 77 | value_type: string 78 | description: Platform of image to analyze 79 | deprecated: false 80 | hidden: false 81 | experimental: false 82 | experimentalcli: false 83 | kubernetes: false 84 | swarm: false 85 | - option: ref 86 | value_type: string 87 | description: |- 88 | Reference to use if the provided tarball contains multiple references. 89 | Can only be used with archive 90 | deprecated: false 91 | hidden: false 92 | experimental: false 93 | experimentalcli: false 94 | kubernetes: false 95 | swarm: false 96 | - option: secrets 97 | value_type: bool 98 | default_value: "false" 99 | description: Scan for secrets in the image 100 | deprecated: false 101 | hidden: true 102 | experimental: false 103 | experimentalcli: false 104 | kubernetes: false 105 | swarm: false 106 | inherited_options: 107 | - option: debug 108 | value_type: bool 109 | default_value: "false" 110 | description: Debug messages 111 | deprecated: false 112 | hidden: true 113 | experimental: false 114 | experimentalcli: false 115 | kubernetes: false 116 | swarm: false 117 | - option: verbose-debug 118 | value_type: bool 119 | default_value: "false" 120 | description: Verbose debug 121 | deprecated: false 122 | hidden: true 123 | experimental: false 124 | experimentalcli: false 125 | kubernetes: false 126 | swarm: false 127 | examples: |- 128 | ### Display the list of packages 129 | 130 | ```console 131 | $ docker scout sbom --format list alpine 132 | ``` 133 | 134 | ### Only display packages of a specific type 135 | 136 | ```console 137 | $ docker scout sbom --format list --only-package-type apk alpine 138 | ``` 139 | 140 | ### Display the full SBOM in JSON format 141 | 142 | ```console 143 | $ docker scout sbom alpine 144 | ``` 145 | 146 | ### Display the full SBOM of the most recently built image 147 | 148 | ```console 149 | $ docker scout sbom 150 | ``` 151 | 152 | ### Write SBOM to a file 153 | 154 | ```console 155 | $ docker scout sbom --output alpine.sbom alpine 156 | ``` 157 | deprecated: false 158 | experimental: false 159 | experimentalcli: false 160 | kubernetes: false 161 | swarm: false 162 | 163 | -------------------------------------------------------------------------------- /docs/docker_scout_stream.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout stream 2 | short: Manage streams (experimental) 3 | long: |- 4 | The `docker scout stream` command lists the deployment streams and records an image to it. 5 | 6 | Once recorded, streams can be referred to by their name, eg. in the `docker scout compare` command using `--to-stream`. 7 | usage: docker scout stream [STREAM] [IMAGE] 8 | pname: docker scout 9 | plink: docker_scout.yaml 10 | options: 11 | - option: org 12 | value_type: string 13 | description: Namespace of the Docker organization 14 | deprecated: false 15 | hidden: false 16 | experimental: false 17 | experimentalcli: false 18 | kubernetes: false 19 | swarm: false 20 | - option: output 21 | shorthand: o 22 | value_type: string 23 | description: Write the report to a file 24 | deprecated: false 25 | hidden: false 26 | experimental: false 27 | experimentalcli: false 28 | kubernetes: false 29 | swarm: false 30 | - option: platform 31 | value_type: string 32 | description: Platform of image to record 33 | deprecated: false 34 | hidden: false 35 | experimental: false 36 | experimentalcli: false 37 | kubernetes: false 38 | swarm: false 39 | inherited_options: 40 | - option: debug 41 | value_type: bool 42 | default_value: "false" 43 | description: Debug messages 44 | deprecated: false 45 | hidden: true 46 | experimental: false 47 | experimentalcli: false 48 | kubernetes: false 49 | swarm: false 50 | - option: verbose-debug 51 | value_type: bool 52 | default_value: "false" 53 | description: Verbose debug 54 | deprecated: false 55 | hidden: true 56 | experimental: false 57 | experimentalcli: false 58 | kubernetes: false 59 | swarm: false 60 | examples: |- 61 | ### List existing streams 62 | 63 | ```console 64 | $ %[1]s %[2]s 65 | prod-cluster-123 66 | stage-cluster-234 67 | ``` 68 | 69 | ### List images of a stream 70 | 71 | ```console 72 | $ %[1]s %[2]s prod-cluster-123 73 | namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b 74 | namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f 75 | ``` 76 | 77 | ### Record an image to a stream, for a specific platform 78 | 79 | ```console 80 | $ %[1]s %[2]s stage-cluster-234 namespace/repo:stage-latest --platform linux/amd64 81 | ✓ Pulled 82 | ✓ Successfully recorded namespace/repo:stage-latest in stream stage-cluster-234 83 | ``` 84 | deprecated: true 85 | experimental: false 86 | experimentalcli: true 87 | kubernetes: false 88 | swarm: false 89 | 90 | -------------------------------------------------------------------------------- /docs/docker_scout_version.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout version 2 | short: Show Docker Scout version information 3 | long: Show Docker Scout version information 4 | usage: docker scout version 5 | pname: docker scout 6 | plink: docker_scout.yaml 7 | inherited_options: 8 | - option: debug 9 | value_type: bool 10 | default_value: "false" 11 | description: Debug messages 12 | deprecated: false 13 | hidden: true 14 | experimental: false 15 | experimentalcli: false 16 | kubernetes: false 17 | swarm: false 18 | - option: verbose-debug 19 | value_type: bool 20 | default_value: "false" 21 | description: Verbose debug 22 | deprecated: false 23 | hidden: true 24 | experimental: false 25 | experimentalcli: false 26 | kubernetes: false 27 | swarm: false 28 | examples: |- 29 | ```console 30 | $ docker scout version 31 | 32 | ⢀⢀⢀ ⣀⣀⡤⣔⢖⣖⢽⢝ 33 | ⡠⡢⡣⡣⡣⡣⡣⡣⡢⡀ ⢀⣠⢴⡲⣫⡺⣜⢞⢮⡳⡵⡹⡅ 34 | ⡜⡜⡜⡜⡜⡜⠜⠈⠈ ⠁⠙⠮⣺⡪⡯⣺⡪⡯⣺ 35 | ⢘⢜⢜⢜⢜⠜ ⠈⠪⡳⡵⣹⡪⠇ 36 | ⠨⡪⡪⡪⠂ ⢀⡤⣖⢽⡹⣝⡝⣖⢤⡀ ⠘⢝⢮⡚ _____ _ 37 | ⠱⡱⠁ ⡴⡫⣞⢮⡳⣝⢮⡺⣪⡳⣝⢦ ⠘⡵⠁ / ____| Docker | | 38 | ⠁ ⣸⢝⣕⢗⡵⣝⢮⡳⣝⢮⡺⣪⡳⣣ ⠁ | (___ ___ ___ _ _| |_ 39 | ⣗⣝⢮⡳⣝⢮⡳⣝⢮⡳⣝⢮⢮⡳ \___ \ / __/ _ \| | | | __| 40 | ⢀ ⢱⡳⡵⣹⡪⡳⣝⢮⡳⣝⢮⡳⡣⡏ ⡀ ____) | (_| (_) | |_| | |_ 41 | ⢀⢾⠄ ⠫⣞⢮⡺⣝⢮⡳⣝⢮⡳⣝⠝ ⢠⢣⢂ |_____/ \___\___/ \__,_|\__| 42 | ⡼⣕⢗⡄ ⠈⠓⠝⢮⡳⣝⠮⠳⠙ ⢠⢢⢣⢣ 43 | ⢰⡫⡮⡳⣝⢦⡀ ⢀⢔⢕⢕⢕⢕⠅ 44 | ⡯⣎⢯⡺⣪⡳⣝⢖⣄⣀ ⡀⡠⡢⡣⡣⡣⡣⡣⡃ 45 | ⢸⢝⢮⡳⣝⢮⡺⣪⡳⠕⠗⠉⠁ ⠘⠜⡜⡜⡜⡜⡜⡜⠜⠈ 46 | ⡯⡳⠳⠝⠊⠓⠉ ⠈⠈⠈⠈ 47 | 48 | 49 | 50 | version: v1.0.9 (go1.21.3 - darwin/arm64) 51 | git commit: 8bf95bf60d084af341f70e8263342f71b0a3cd16 52 | ``` 53 | deprecated: false 54 | experimental: false 55 | experimentalcli: false 56 | kubernetes: false 57 | swarm: false 58 | 59 | -------------------------------------------------------------------------------- /docs/docker_scout_watch.yaml: -------------------------------------------------------------------------------- 1 | command: docker scout watch 2 | short: | 3 | Watch repositories in a registry and push images and indexes to Docker Scout (experimental) 4 | long: |- 5 | The `docker scout watch` command watches repositories in a registry 6 | and pushes images or analysis results to Docker Scout. 7 | usage: docker scout watch 8 | pname: docker scout 9 | plink: docker_scout.yaml 10 | options: 11 | - option: all-images 12 | value_type: bool 13 | default_value: "false" 14 | description: | 15 | Push all images instead of only the ones pushed during the watch command is running 16 | deprecated: false 17 | hidden: false 18 | experimental: false 19 | experimentalcli: false 20 | kubernetes: false 21 | swarm: false 22 | - option: dry-run 23 | value_type: bool 24 | default_value: "false" 25 | description: Watch images and prepare them, but do not push them 26 | deprecated: false 27 | hidden: false 28 | experimental: false 29 | experimentalcli: false 30 | kubernetes: false 31 | swarm: false 32 | - option: interval 33 | value_type: int64 34 | default_value: "60" 35 | description: Interval in seconds between checks 36 | deprecated: false 37 | hidden: false 38 | experimental: false 39 | experimentalcli: false 40 | kubernetes: false 41 | swarm: false 42 | - option: org 43 | value_type: string 44 | description: Namespace of the Docker organization to which image will be pushed 45 | deprecated: false 46 | hidden: false 47 | experimental: false 48 | experimentalcli: false 49 | kubernetes: false 50 | swarm: false 51 | - option: refresh-registry 52 | value_type: bool 53 | default_value: "false" 54 | description: | 55 | Refresh the list of repositories of a registry at every run. Only with --registry. 56 | deprecated: false 57 | hidden: false 58 | experimental: false 59 | experimentalcli: false 60 | kubernetes: false 61 | swarm: false 62 | - option: registry 63 | value_type: string 64 | description: Registry to watch 65 | deprecated: false 66 | hidden: false 67 | experimental: false 68 | experimentalcli: false 69 | kubernetes: false 70 | swarm: false 71 | - option: repository 72 | value_type: stringSlice 73 | default_value: '[]' 74 | description: Repository to watch 75 | deprecated: false 76 | hidden: false 77 | experimental: false 78 | experimentalcli: false 79 | kubernetes: false 80 | swarm: false 81 | - option: sbom 82 | value_type: bool 83 | default_value: "true" 84 | description: Create and upload SBOMs 85 | deprecated: false 86 | hidden: false 87 | experimental: false 88 | experimentalcli: false 89 | kubernetes: false 90 | swarm: false 91 | - option: tag 92 | value_type: stringSlice 93 | default_value: '[]' 94 | description: Regular expression to match tags to watch 95 | deprecated: false 96 | hidden: false 97 | experimental: false 98 | experimentalcli: false 99 | kubernetes: false 100 | swarm: false 101 | - option: workers 102 | value_type: int 103 | default_value: "3" 104 | description: Number of concurrent workers 105 | deprecated: false 106 | hidden: false 107 | experimental: false 108 | experimentalcli: false 109 | kubernetes: false 110 | swarm: false 111 | inherited_options: 112 | - option: debug 113 | value_type: bool 114 | default_value: "false" 115 | description: Debug messages 116 | deprecated: false 117 | hidden: true 118 | experimental: false 119 | experimentalcli: false 120 | kubernetes: false 121 | swarm: false 122 | - option: verbose-debug 123 | value_type: bool 124 | default_value: "false" 125 | description: Verbose debug 126 | deprecated: false 127 | hidden: true 128 | experimental: false 129 | experimentalcli: false 130 | kubernetes: false 131 | swarm: false 132 | examples: |- 133 | ### Watch for new images from two repositories and push them 134 | 135 | ```console 136 | $ docker scout watch --org my-org --repository registry-1.example.com/repo-1 --repository registry-2.example.com/repo-2 137 | ``` 138 | 139 | ### Only push images with a specific tag 140 | 141 | ```console 142 | $ docker scout watch --org my-org --repository registry.example.com/my-service --tag latest 143 | ``` 144 | 145 | ### Watch all repositories of a registry 146 | 147 | ```console 148 | $ docker scout watch --org my-org --registry registry.example.com 149 | ``` 150 | 151 | ### Push all images and not just the new ones 152 | 153 | ```console 154 | $ docker scout watch--org my-org --repository registry.example.com/my-service --all-images 155 | ``` 156 | deprecated: false 157 | experimental: false 158 | experimentalcli: true 159 | kubernetes: false 160 | swarm: false 161 | 162 | -------------------------------------------------------------------------------- /docs/scout.md: -------------------------------------------------------------------------------- 1 | # docker scout 2 | 3 | ``` 4 | docker scout COMMAND 5 | ``` 6 | 7 | 8 | Command line tool for Docker Scout 9 | 10 | ### Subcommands 11 | 12 | | Name | Description | 13 | |:--------------------------------------------------------------|:--------------------------------------------------------------------------------------------| 14 | | [`attestation`](scout_attestation.md) | Manage attestations on image indexes | 15 | | [`cache`](scout_cache.md) | Manage Docker Scout cache and temporary files | 16 | | [`compare`](scout_compare.md) | Compare two images and display differences (experimental) | 17 | | [`config`](scout_config.md) | Manage Docker Scout configuration | 18 | | [`cves`](scout_cves.md) | Display CVEs identified in a software artifact | 19 | | [`docker-cli-plugin-hooks`](scout_docker-cli-plugin-hooks.md) | runs the plugins hooks | 20 | | [`enroll`](scout_enroll.md) | Enroll an organization with Docker Scout | 21 | | [`environment`](scout_environment.md) | Manage environments (experimental) | 22 | | [`help`](scout_help.md) | Display information about the available commands | 23 | | [`integration`](scout_integration.md) | Commands to list, configure, and delete Docker Scout integrations | 24 | | [`policy`](scout_policy.md) | Evaluate policies against an image and display the policy evaluation results (experimental) | 25 | | [`push`](scout_push.md) | Push an image or image index to Docker Scout | 26 | | [`quickview`](scout_quickview.md) | Quick overview of an image | 27 | | [`recommendations`](scout_recommendations.md) | Display available base image updates and remediation recommendations | 28 | | [`repo`](scout_repo.md) | Commands to list, enable, and disable Docker Scout on repositories | 29 | | [`sbom`](scout_sbom.md) | Generate or display SBOM of an image | 30 | | [`stream`](scout_stream.md) | Manage streams (experimental) | 31 | | [`version`](scout_version.md) | Show Docker Scout version information | 32 | | [`watch`](scout_watch.md) | Watch repositories in a registry and push images and indexes to Docker Scout (experimental) | 33 | 34 | 35 | 36 | 37 | 38 | -------------------------------------------------------------------------------- /docs/scout_attestation.md: -------------------------------------------------------------------------------- 1 | # docker scout attestation 2 | 3 | 4 | Manage attestations on image indexes 5 | 6 | ### Aliases 7 | 8 | `docker scout attestation`, `docker scout attest` 9 | 10 | ### Subcommands 11 | 12 | | Name | Description | 13 | |:----------------------------------|:-------------------------| 14 | | [`add`](scout_attestation_add.md) | Add attestation to image | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /docs/scout_attestation_add.md: -------------------------------------------------------------------------------- 1 | # docker scout attestation add 2 | 3 | 4 | Add attestation to image 5 | 6 | ### Aliases 7 | 8 | `docker scout attestation add`, `docker scout attest add` 9 | 10 | ### Options 11 | 12 | | Name | Type | Default | Description | 13 | |:------------------------|:--------------|:----------------------------|:---------------------------------------------| 14 | | `--file` | `stringSlice` | | File location of attestations to attach | 15 | | `--org` | `string` | | Namespace of the Docker organization | 16 | | `--predicate-type` | `string` | | Predicate-type for attestations | 17 | | `--referrer` | | | Use OCI referrer API for pushing attestation | 18 | | `--referrer-repository` | `string` | `registry.scout.docker.com` | Repository to push referrer to | 19 | 20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /docs/scout_cache.md: -------------------------------------------------------------------------------- 1 | # docker scout cache 2 | 3 | 4 | Manage Docker Scout cache and temporary files 5 | 6 | ### Subcommands 7 | 8 | | Name | Description | 9 | |:--------------------------------|:--------------------------------| 10 | | [`df`](scout_cache_df.md) | Show Docker Scout disk usage | 11 | | [`prune`](scout_cache_prune.md) | Remove temporary or cached data | 12 | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /docs/scout_cache_df.md: -------------------------------------------------------------------------------- 1 | # docker scout cache df 2 | 3 | 4 | Show Docker Scout disk usage 5 | 6 | 7 | 8 | 9 | ## Description 10 | 11 | Docker Scout uses a temporary cache storage for generating image SBOMs. 12 | The cache helps avoid regenerating or fetching resources unnecessarily. 13 | 14 | This `docker scout cache df` command shows the cached data on the host. 15 | Each cache entry is identified by the digest of the image. 16 | 17 | You can use the `docker scout cache prune` command to delete cache data at any time. 18 | 19 | ## Examples 20 | 21 | ### List temporary and cache files 22 | 23 | ```console 24 | $ docker scout cache df 25 | Docker Scout temporary directory to generate SBOMs is located at: 26 | /var/folders/dw/d6h9w2sx6rv3lzwwgrnx7t5h0000gp/T/docker-scout 27 | this path can be configured using the DOCKER_SCOUT_CACHE_DIR environment variable 28 | 29 | Image Digest │ Size 30 | ──────────────────────────────────────────────────────────────────────────┼──────── 31 | sha256:c41ab5c992deb4fe7e5da09f67a8804a46bd0592bfdf0b1847dde0e0889d2bff │ 21 kB 32 | 33 | Total: 21 kB 34 | 35 | 36 | Docker Scout cached SBOMs are located at: 37 | /Users/user/.docker/scout/sbom 38 | 39 | Image Digest │ Size of SBOM 40 | ──────────────────────────────────────────────────────────────────────────┼─────────────── 41 | sha256:02bb6f428431fbc2809c5d1b41eab5a68350194fb508869a33cb1af4444c9b11 │ 42 kB 42 | sha256:03fc002fe4f370463a8f04d3a288cdffa861e462fc8b5be44ab62b296ad95183 │ 100 kB 43 | sha256:088134dd33e4a2997480a1488a41c11abebda465da5cf7f305a0ecf8ed494329 │ 194 kB 44 | sha256:0b80b2f17aff7ee5bfb135c69d0d6fe34070e89042b7aac73d1abcc79cfe6759 │ 852 kB 45 | sha256:0c9e8abe31a5f17d84d5c85d3853d2f948a4f126421e89e68753591f1b6fedc5 │ 930 kB 46 | sha256:0d49cae0723c8d310e413736b5e91e0c59b605ade2546f6e6ef8f1f3ddc76066 │ 510 kB 47 | sha256:0ef04748d071c2e631bb3edce8f805cb5512e746b682c83fdae6d8c0b243280b │ 1.0 MB 48 | sha256:13fd22925b638bb7d2131914bb8f8b0f5f582bee364aec682d9e7fe722bb486a │ 42 kB 49 | sha256:174c41d4fbc7f63e1f2bb7d2f7837318050406f2f27e5073a84a84f18b48b883 │ 115 kB 50 | 51 | Total: 4 MB 52 | ``` 53 | -------------------------------------------------------------------------------- /docs/scout_cache_prune.md: -------------------------------------------------------------------------------- 1 | # docker scout cache prune 2 | 3 | 4 | Remove temporary or cached data 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:----------------|:-----|:--------|:-------------------------------| 10 | | `-f`, `--force` | | | Do not prompt for confirmation | 11 | | `--sboms` | | | Prune cached SBOMs | 12 | 13 | 14 | 15 | 16 | ## Description 17 | 18 | The `docker scout cache prune` command removes temporary data and SBOM cache. 19 | 20 | By default, `docker scout cache prune` only deletes temporary data. 21 | To delete temporary data and clear the SBOM cache, use the `--sboms` flag. 22 | 23 | ## Examples 24 | 25 | ### Delete temporary data 26 | 27 | ```console 28 | $ docker scout cache prune 29 | ? Are you sure to delete all temporary data? Yes 30 | ✓ temporary data deleted 31 | ``` 32 | 33 | ### Delete temporary _and_ cache data 34 | 35 | ```console 36 | $ docker scout cache prune --sboms 37 | ? Are you sure to delete all temporary data and all cached SBOMs? Yes 38 | ✓ temporary data deleted 39 | ✓ cached SBOMs deleted 40 | ``` 41 | -------------------------------------------------------------------------------- /docs/scout_compare.md: -------------------------------------------------------------------------------- 1 | # docker scout compare 2 | 3 | 4 | Compare two images and display differences (experimental) 5 | 6 | ### Aliases 7 | 8 | `docker scout compare`, `docker scout diff` 9 | 10 | ### Options 11 | 12 | | Name | Type | Default | Description | 13 | |:----------------------|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 14 | | `-x`, `--exit-on` | `stringSlice` | | Comma separated list of conditions to fail the action step if worse or changed, options are: vulnerability, policy, package | 15 | | `--format` | `string` | `text` | Output format of the generated vulnerability report:
- text: default output, plain text with or without colors depending on the terminal
- markdown: Markdown output
| 16 | | `--hide-policies` | | | Hide policy status from the output | 17 | | `--ignore-base` | | | Filter out CVEs introduced from base image | 18 | | `--ignore-unchanged` | | | Filter out unchanged packages | 19 | | `--multi-stage` | | | Show packages from multi-stage Docker builds | 20 | | `--only-fixed` | | | Filter to fixable CVEs | 21 | | `--only-package-type` | `stringSlice` | | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) | 22 | | `--only-policy` | `stringSlice` | | Comma separated list of policies to evaluate | 23 | | `--only-severity` | `stringSlice` | | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by | 24 | | `--only-stage` | `stringSlice` | | Comma separated list of multi-stage Docker build stage names | 25 | | `--only-unfixed` | | | Filter to unfixed CVEs | 26 | | `--org` | `string` | | Namespace of the Docker organization | 27 | | `-o`, `--output` | `string` | | Write the report to a file | 28 | | `--platform` | `string` | | Platform of image to analyze | 29 | | `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | 30 | | `--to` | `string` | | Image, directory, or archive to compare to | 31 | | `--to-env` | `string` | | Name of environment to compare to | 32 | | `--to-latest` | | | Latest image processed to compare to | 33 | | `--to-ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive. | 34 | 35 | 36 | 37 | 38 | ## Description 39 | 40 | The `docker scout compare` command analyzes two images and displays a comparison. 41 | 42 | > This command is **experimental** and its behaviour might change in the future 43 | 44 | The intended use of this command is to compare two versions of the same image. 45 | For instance, when a new image is built and compared to the version running in production. 46 | 47 | If no image is specified, the most recently built image is used 48 | as a comparison target. 49 | 50 | The following artifact types are supported: 51 | 52 | - Images 53 | - OCI layout directories 54 | - Tarball archives, as created by `docker save` 55 | - Local directory or file 56 | 57 | By default, the tool expects an image reference, such as: 58 | 59 | - `redis` 60 | - `curlimages/curl:7.87.0` 61 | - `mcr.microsoft.com/dotnet/runtime:7.0` 62 | 63 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 64 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 65 | 66 | - `image://` (default) use a local image, or fall back to a registry lookup 67 | - `local://` use an image from the local image store (don't do a registry lookup) 68 | - `registry://` use an image from a registry (don't use a local image) 69 | - `oci-dir://` use an OCI layout directory 70 | - `archive://` use a tarball archive, as created by `docker save` 71 | - `fs://` use a local directory or file 72 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 73 | 74 | ## Examples 75 | 76 | ### Compare the most recently built image to the latest tag 77 | 78 | ```console 79 | $ docker scout compare --to namespace/repo:latest 80 | ``` 81 | 82 | ### Compare local build to the same tag from the registry 83 | 84 | ```console 85 | $ docker scout compare local://namespace/repo:latest --to registry://namespace/repo:latest 86 | ``` 87 | 88 | ### Ignore base images 89 | 90 | ```console 91 | $ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre 92 | ``` 93 | 94 | ### Generate a markdown output 95 | 96 | ```console 97 | $ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre 98 | ``` 99 | 100 | ### Only compare maven packages and only display critical vulnerabilities for maven packages 101 | 102 | ```console 103 | $ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre 104 | ``` 105 | 106 | ### Show all policy results for both images 107 | 108 | ```console 109 | docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre 110 | ``` 111 | -------------------------------------------------------------------------------- /docs/scout_config.md: -------------------------------------------------------------------------------- 1 | # docker scout config 2 | 3 | 4 | Manage Docker Scout configuration 5 | 6 | 7 | 8 | 9 | ## Description 10 | 11 | `docker scout config` allows you to list, get and set Docker Scout configuration. 12 | 13 | Available configuration key: 14 | 15 | - `organization`: Namespace of the Docker organization to be used by default. 16 | 17 | ## Examples 18 | 19 | ### List existing configuration 20 | 21 | ```console 22 | $ docker scout config 23 | organization=my-org-namespace 24 | ``` 25 | 26 | ### Print configuration value 27 | 28 | ```console 29 | $ docker scout config organization 30 | my-org-namespace 31 | ``` 32 | 33 | ### Set configuration value 34 | 35 | ```console 36 | $ docker scout config organization my-org-namespace 37 | ✓ Successfully set organization to my-org-namespace 38 | ``` 39 | -------------------------------------------------------------------------------- /docs/scout_cves.md: -------------------------------------------------------------------------------- 1 | # docker scout cves 2 | 3 | ``` 4 | docker scout cves [OPTIONS] [IMAGE|DIRECTORY|ARCHIVE] 5 | ``` 6 | 7 | 8 | Display CVEs identified in a software artifact 9 | 10 | ### Options 11 | 12 | | Name | Type | Default | Description | 13 | |:-----------------------|:--------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 14 | | `--details` | | | Print details on default text output | 15 | | `--env` | `string` | | Name of environment | 16 | | [`--epss`](#epss) | | | Display the EPSS scores and organize the package's CVEs according to their EPSS score | 17 | | `--epss-percentile` | `float32` | `0` | Exclude CVEs with EPSS scores less than the specified percentile (0 to 1) | 18 | | `--epss-score` | `float32` | `0` | Exclude CVEs with EPSS scores less than the specified value (0 to 1) | 19 | | `-e`, `--exit-code` | | | Return exit code '2' if vulnerabilities are detected | 20 | | `--format` | `string` | `packages` | Output format of the generated vulnerability report:
- packages: default output, plain text with vulnerabilities grouped by packages
- sarif: json Sarif output
- spdx: json SPDX output
- gitlab: json GitLab output
- markdown: markdown output (including some html tags like collapsible sections)
- sbom: json SBOM output
| 21 | | `--ignore-base` | | | Filter out CVEs introduced from base image | 22 | | `--ignore-suppressed` | | | Filter CVEs found in Scout exceptions based on the specified exception scope | 23 | | `--locations` | | | Print package locations including file paths and layer diff_id | 24 | | `--multi-stage` | | | Show packages from multi-stage Docker builds | 25 | | `--only-base` | | | Only show CVEs introduced by the base image | 26 | | `--only-cisa-kev` | | | Filter to CVEs listed in the CISA KEV catalog | 27 | | `--only-cve-id` | `stringSlice` | | Comma separated list of CVE ids (like CVE-2021-45105) to search for | 28 | | `--only-fixed` | | | Filter to fixable CVEs | 29 | | `--only-metric` | `stringSlice` | | Comma separated list of CVSS metrics (like AV:N or PR:L) to filter CVEs by | 30 | | `--only-package` | `stringSlice` | | Comma separated regular expressions to filter packages by | 31 | | `--only-package-type` | `stringSlice` | | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) | 32 | | `--only-severity` | `stringSlice` | | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by | 33 | | `--only-stage` | `stringSlice` | | Comma separated list of multi-stage Docker build stage names | 34 | | `--only-unfixed` | | | Filter to unfixed CVEs | 35 | | `--only-vex-affected` | | | Filter CVEs by VEX statements with status not affected | 36 | | `--only-vuln-packages` | | | When used with --format=only-packages ignore packages with no vulnerabilities | 37 | | `--org` | `string` | | Namespace of the Docker organization | 38 | | `-o`, `--output` | `string` | | Write the report to a file | 39 | | `--platform` | `string` | | Platform of image to analyze | 40 | | `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | 41 | | `--vex-author` | `stringSlice` | | List of VEX statement authors to accept | 42 | | `--vex-location` | `stringSlice` | | File location of directory or file containing VEX statements | 43 | 44 | 45 | 46 | 47 | ## Description 48 | 49 | The `docker scout cves` command analyzes a software artifact for vulnerabilities. 50 | 51 | If no image is specified, the most recently built image is used. 52 | 53 | The following artifact types are supported: 54 | 55 | - Images 56 | - OCI layout directories 57 | - Tarball archives, as created by `docker save` 58 | - Local directory or file 59 | 60 | By default, the tool expects an image reference, such as: 61 | 62 | - `redis` 63 | - `curlimages/curl:7.87.0` 64 | - `mcr.microsoft.com/dotnet/runtime:7.0` 65 | 66 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 67 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 68 | 69 | - `image://` (default) use a local image, or fall back to a registry lookup 70 | - `local://` use an image from the local image store (don't do a registry lookup) 71 | - `registry://` use an image from a registry (don't use a local image) 72 | - `oci-dir://` use an OCI layout directory 73 | - `archive://` use a tarball archive, as created by `docker save` 74 | - `fs://` use a local directory or file 75 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 76 | In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. 77 | 78 | ## Examples 79 | 80 | ### Display vulnerabilities grouped by package 81 | 82 | ```console 83 | $ docker scout cves alpine 84 | Analyzing image alpine 85 | ✓ Image stored for indexing 86 | ✓ Indexed 18 packages 87 | ✓ No vulnerable package detected 88 | ``` 89 | 90 | ### Display vulnerabilities from a `docker save` tarball 91 | 92 | ```console 93 | $ docker save alpine > alpine.tar 94 | 95 | $ docker scout cves archive://alpine.tar 96 | Analyzing archive alpine.tar 97 | ✓ Archive read 98 | ✓ SBOM of image already cached, 18 packages indexed 99 | ✓ No vulnerable package detected 100 | ``` 101 | 102 | ### Display vulnerabilities from an OCI directory 103 | 104 | ```console 105 | $ skopeo copy --override-os linux docker://alpine oci:alpine 106 | 107 | $ docker scout cves oci-dir://alpine 108 | Analyzing OCI directory alpine 109 | ✓ OCI directory read 110 | ✓ Image stored for indexing 111 | ✓ Indexed 19 packages 112 | ✓ No vulnerable package detected 113 | ``` 114 | 115 | ### Display vulnerabilities from the current directory 116 | 117 | ```console 118 | $ docker scout cves fs://. 119 | ``` 120 | 121 | ### Export vulnerabilities to a SARIF JSON file 122 | 123 | ```console 124 | $ docker scout cves --format sarif --output alpine.sarif.json alpine 125 | Analyzing image alpine 126 | ✓ SBOM of image already cached, 18 packages indexed 127 | ✓ No vulnerable package detected 128 | ✓ Report written to alpine.sarif.json 129 | ``` 130 | 131 | ### Display markdown output 132 | 133 | The following example shows how to generate the vulnerability report as markdown. 134 | 135 | ```console 136 | $ docker scout cves --format markdown alpine 137 | ✓ Pulled 138 | ✓ SBOM of image already cached, 19 packages indexed 139 | ✗ Detected 1 vulnerable package with 3 vulnerabilities 140 |

:mag: Vulnerabilities of alpine

141 | 142 |
:package: Image Reference alpine 143 | 144 | 145 | 146 | 147 | 148 |
digestsha256:e3bd82196e98898cae9fe7fbfd6e2436530485974dc4fb3b7ddb69134eda2407
vulnerabilitiescritical: 0 high: 0 medium: 2 low: 0 unspecified: 1
platformlinux/arm64
size3.3 MB
packages19
149 |
150 | 151 | ... 152 | ``` 153 | 154 | ### List all vulnerable packages of a certain type 155 | 156 | The following example shows how to generate a list of packages, only including 157 | packages of the specified type, and only showing packages that are vulnerable. 158 | 159 | ```console 160 | $ docker scout cves --format only-packages --only-package-type golang --only-vuln-packages golang:1.18.0 161 | ✓ Pulled 162 | ✓ SBOM of image already cached, 296 packages indexed 163 | ✗ Detected 1 vulnerable package with 40 vulnerabilities 164 | 165 | Name Version Type Vulnerabilities 166 | ─────────────────────────────────────────────────────────── 167 | stdlib 1.18 golang 2C 29H 8M 1L 168 | ``` 169 | 170 | ### Display EPSS score (--epss) 171 | 172 | The `--epss` flag adds [Exploit Prediction Scoring System (EPSS)](https://www.first.org/epss/) 173 | scores to the `docker scout cves` output. EPSS scores are estimates of the likelihood (probability) 174 | that a software vulnerability will be exploited in the wild in the next 30 days. 175 | The higher the score, the greater the probability that a vulnerability will be exploited. 176 | 177 | ```console {hl_lines="13,14"} 178 | $ docker scout cves --epss nginx 179 | ✓ Provenance obtained from attestation 180 | ✓ SBOM obtained from attestation, 232 packages indexed 181 | ✓ Pulled 182 | ✗ Detected 23 vulnerable packages with a total of 39 vulnerabilities 183 | 184 | ... 185 | 186 | ✗ HIGH CVE-2023-52425 187 | https://scout.docker.com/v/CVE-2023-52425 188 | Affected range : >=2.5.0-1 189 | Fixed version : not fixed 190 | EPSS Score : 0.000510 191 | EPSS Percentile : 0.173680 192 | ``` 193 | 194 | - `EPSS Score` is a floating point number between 0 and 1 representing the probability of exploitation in the wild in the next 30 days (following score publication). 195 | - `EPSS Percentile` is the percentile of the current score, the proportion of all scored vulnerabilities with the same or a lower EPSS score. 196 | 197 | You can use the `--epss-score` and `--epss-percentile` flags to filter the output 198 | of `docker scout cves` based on these scores. For example, 199 | to only show vulnerabilities with an EPSS score higher than 0.5: 200 | 201 | ```console 202 | $ docker scout cves --epss --epss-score 0.5 nginx 203 | ✓ SBOM of image already cached, 232 packages indexed 204 | ✓ EPSS scores for 2024-03-01 already cached 205 | ✗ Detected 1 vulnerable package with 1 vulnerability 206 | 207 | ... 208 | 209 | ✗ LOW CVE-2023-44487 210 | https://scout.docker.com/v/CVE-2023-44487 211 | Affected range : >=1.22.1-9 212 | Fixed version : not fixed 213 | EPSS Score : 0.705850 214 | EPSS Percentile : 0.979410 215 | ``` 216 | 217 | EPSS scores are updated on a daily basis. 218 | By default, the latest available score is displayed. 219 | You can use the `--epss-date` flag to manually specify a date 220 | in the format `yyyy-mm-dd` for fetching EPSS scores. 221 | 222 | ```console 223 | $ docker scout cves --epss --epss-date 2024-01-02 nginx 224 | ``` 225 | 226 | ### List vulnerabilities from an SPDX file 227 | 228 | The following example shows how to generate a list of vulnerabilities from an SPDX file using `syft`. 229 | 230 | ```console 231 | $ syft -o spdx-json alpine:3.16.1 | docker scout cves sbom:// 232 | ✔ Pulled image 233 | ✔ Loaded image alpine:3.16.1 234 | ✔ Parsed image sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d 235 | ✔ Cataloged contents 274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f 236 | ├── ✔ Packages [14 packages] 237 | ├── ✔ File digests [75 files] 238 | ├── ✔ File metadata [75 locations] 239 | └── ✔ Executables [16 executables] 240 | ✗ Detected 2 vulnerable packages with a total of 11 vulnerabilities 241 | 242 | 243 | ## Overview 244 | 245 | │ Analyzed SBOM 246 | ────────────────────┼────────────────────────────── 247 | Target │ 248 | digest │ 274a317d88b5 249 | platform │ linux/arm64 250 | vulnerabilities │ 1C 2H 8M 0L 251 | packages │ 15 252 | 253 | 254 | ## Packages and Vulnerabilities 255 | 256 | 1C 0H 0M 0L zlib 1.2.12-r1 257 | pkg:apk/alpine/zlib@1.2.12-r1?arch=aarch64&distro=alpine-3.16.1 258 | 259 | ✗ CRITICAL CVE-2022-37434 260 | https://scout.docker.com/v/CVE-2022-37434 261 | Affected range : <1.2.12-r2 262 | Fixed version : 1.2.12-r2 263 | 264 | ... 265 | 266 | 11 vulnerabilities found in 2 packages 267 | CRITICAL 1 268 | HIGH 2 269 | MEDIUM 8 270 | LOW 0 271 | ``` 272 | -------------------------------------------------------------------------------- /docs/scout_docker-cli-plugin-hooks.md: -------------------------------------------------------------------------------- 1 | # docker scout docker-cli-plugin-hooks 2 | 3 | 4 | runs the plugins hooks 5 | 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /docs/scout_enroll.md: -------------------------------------------------------------------------------- 1 | # docker scout enroll 2 | 3 | 4 | Enroll an organization with Docker Scout 5 | 6 | 7 | 8 | 9 | ## Description 10 | 11 | The `docker scout enroll` command enrolls an organization with Docker Scout. 12 | -------------------------------------------------------------------------------- /docs/scout_environment.md: -------------------------------------------------------------------------------- 1 | # docker scout environment 2 | 3 | 4 | Manage environments (experimental) 5 | 6 | ### Aliases 7 | 8 | `docker scout environment`, `docker scout env` 9 | 10 | ### Options 11 | 12 | | Name | Type | Default | Description | 13 | |:-----------------|:---------|:--------|:-------------------------------------| 14 | | `--org` | `string` | | Namespace of the Docker organization | 15 | | `-o`, `--output` | `string` | | Write the report to a file | 16 | | `--platform` | `string` | | Platform of image to record | 17 | 18 | 19 | 20 | 21 | ## Description 22 | 23 | The `docker scout environment` command lists the environments. 24 | If you pass an image reference, the image is recorded to the specified environment. 25 | 26 | Once recorded, environments can be referred to by their name. For example, 27 | you can refer to the `production` environment with the `docker scout compare` 28 | command as follows: 29 | 30 | ```console 31 | $ docker scout compare --to-env production 32 | ``` 33 | 34 | ## Examples 35 | 36 | ### List existing environments 37 | 38 | ```console 39 | $ docker scout environment 40 | prod 41 | staging 42 | ``` 43 | 44 | ### List images of an environment 45 | 46 | ```console 47 | $ docker scout environment staging 48 | namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b 49 | namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f 50 | ``` 51 | 52 | ### Record an image to an environment, for a specific platform 53 | 54 | ```console 55 | $ docker scout environment staging namespace/repo:stage-latest --platform linux/amd64 56 | ✓ Pulled 57 | ✓ Successfully recorded namespace/repo:stage-latest in environment staging 58 | ``` 59 | -------------------------------------------------------------------------------- /docs/scout_help.md: -------------------------------------------------------------------------------- 1 | # docker scout help 2 | 3 | 4 | Display information about the available commands 5 | 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /docs/scout_integration.md: -------------------------------------------------------------------------------- 1 | # docker scout integration 2 | 3 | 4 | Commands to list, configure, and delete Docker Scout integrations 5 | 6 | ### Subcommands 7 | 8 | | Name | Description | 9 | |:----------------------------------------------|:----------------------------------------------------| 10 | | [`configure`](scout_integration_configure.md) | Configure or update a new integration configuration | 11 | | [`delete`](scout_integration_delete.md) | Delete a new integration configuration | 12 | | [`list`](scout_integration_list.md) | List integrations which can be installed | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /docs/scout_integration_configure.md: -------------------------------------------------------------------------------- 1 | # docker scout integration configure 2 | 3 | 4 | Configure or update a new integration configuration 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:--------------|:--------------|:--------|:-------------------------------------------------------------| 10 | | `--name` | `string` | | Name of integration configuration to create | 11 | | `--org` | `string` | | Namespace of the Docker organization | 12 | | `--parameter` | `stringSlice` | | Integration parameters in the form of --parameter NAME=VALUE | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /docs/scout_integration_delete.md: -------------------------------------------------------------------------------- 1 | # docker scout integration delete 2 | 3 | 4 | Delete a new integration configuration 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:---------|:---------|:--------|:--------------------------------------------| 10 | | `--name` | `string` | | Name of integration configuration to delete | 11 | | `--org` | `string` | | Namespace of the Docker organization | 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /docs/scout_integration_list.md: -------------------------------------------------------------------------------- 1 | # docker scout integration list 2 | 3 | 4 | List integrations which can be installed 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:---------|:---------|:--------|:------------------------------------------| 10 | | `--name` | `string` | | Name of integration configuration to list | 11 | | `--org` | `string` | | Namespace of the Docker organization | 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /docs/scout_policy.md: -------------------------------------------------------------------------------- 1 | # docker scout policy 2 | 3 | 4 | Evaluate policies against an image and display the policy evaluation results (experimental) 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:--------------------|:--------------|:--------|:------------------------------------------------------------| 10 | | `-e`, `--exit-code` | | | Return exit code '2' if policies are not met, '0' otherwise | 11 | | `--only-policy` | `stringSlice` | | Comma separated list of policies to evaluate | 12 | | `--org` | `string` | | Namespace of the Docker organization | 13 | | `-o`, `--output` | `string` | | Write the report to a file | 14 | | `--platform` | `string` | | Platform of image to pull policy results from | 15 | | `--to-env` | `string` | | Name of the environment to compare to | 16 | | `--to-latest` | | | Latest image processed to compare to | 17 | 18 | 19 | 20 | 21 | ## Description 22 | 23 | The `docker scout policy` command evaluates policies against an image. 24 | The image analysis is uploaded to Docker Scout where policies get evaluated. 25 | 26 | The policy evaluation results may take a few minutes to become available. 27 | 28 | ## Examples 29 | 30 | ### Evaluate policies against an image and display the results 31 | 32 | ```console 33 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 34 | ``` 35 | 36 | ### Evaluate policies against an image for a specific organization 37 | 38 | ```console 39 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --org dockerscoutpolicy 40 | ``` 41 | 42 | ### Evaluate policies against an image with a specific platform 43 | 44 | ```console 45 | $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --platform linux/amd64 46 | ``` 47 | 48 | ### Compare policy results for a repository in a specific environment 49 | 50 | ```console 51 | $ docker scout policy dockerscoutpolicy/customers-api-service --to-env production 52 | ``` 53 | -------------------------------------------------------------------------------- /docs/scout_push.md: -------------------------------------------------------------------------------- 1 | # docker scout push 2 | 3 | 4 | Push an image or image index to Docker Scout 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:-----------------|:---------|:--------|:-------------------------------------------------------------------| 10 | | `--author` | `string` | | Name of the author of the image | 11 | | `--dry-run` | | | Do not push the image but process it | 12 | | `--org` | `string` | | Namespace of the Docker organization to which image will be pushed | 13 | | `-o`, `--output` | `string` | | Write the report to a file | 14 | | `--platform` | `string` | | Platform of image to be pushed | 15 | | `--sbom` | | | Create and upload SBOMs | 16 | | `--secrets` | | | Scan for secrets in the image | 17 | | `--timestamp` | `string` | | Timestamp of image or tag creation | 18 | 19 | 20 | 21 | 22 | ## Description 23 | 24 | The `docker scout push` command lets you push an image or analysis result to Docker Scout. 25 | 26 | ## Examples 27 | 28 | ### Push an image to Docker Scout 29 | 30 | ```console 31 | $ docker scout push --org my-org registry.example.com/repo:tag 32 | ``` 33 | -------------------------------------------------------------------------------- /docs/scout_quickview.md: -------------------------------------------------------------------------------- 1 | # docker scout quickview 2 | 3 | 4 | Quick overview of an image 5 | 6 | ### Aliases 7 | 8 | `docker scout quickview`, `docker scout qv` 9 | 10 | ### Options 11 | 12 | | Name | Type | Default | Description | 13 | |:----------------------|:--------------|:--------|:--------------------------------------------------------------------------------------------------------| 14 | | `--env` | `string` | | Name of the environment | 15 | | `--ignore-suppressed` | | | Filter CVEs found in Scout exceptions based on the specified exception scope | 16 | | `--latest` | | | Latest indexed image | 17 | | `--only-policy` | `stringSlice` | | Comma separated list of policies to evaluate | 18 | | `--only-vex-affected` | | | Filter CVEs by VEX statements with status not affected | 19 | | `--org` | `string` | | Namespace of the Docker organization | 20 | | `-o`, `--output` | `string` | | Write the report to a file | 21 | | `--platform` | `string` | | Platform of image to analyze | 22 | | `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | 23 | | `--vex-author` | `stringSlice` | | List of VEX statement authors to accept | 24 | | `--vex-location` | `stringSlice` | | File location of directory or file containing VEX statements | 25 | 26 | 27 | 28 | 29 | ## Description 30 | 31 | The `docker scout quickview` command displays a quick overview of an image. 32 | It displays a summary of the vulnerabilities in the specified image 33 | and vulnerabilities from the base image. 34 | If available, it also displays base image refresh and update recommendations. 35 | 36 | If no image is specified, the most recently built image is used. 37 | 38 | The following artifact types are supported: 39 | 40 | - Images 41 | - OCI layout directories 42 | - Tarball archives, as created by `docker save` 43 | - Local directory or file 44 | 45 | By default, the tool expects an image reference, such as: 46 | 47 | - `redis` 48 | - `curlimages/curl:7.87.0` 49 | - `mcr.microsoft.com/dotnet/runtime:7.0` 50 | 51 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 52 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 53 | 54 | - `image://` (default) use a local image, or fall back to a registry lookup 55 | - `local://` use an image from the local image store (don't do a registry lookup) 56 | - `registry://` use an image from a registry (don't use a local image) 57 | - `oci-dir://` use an OCI layout directory 58 | - `archive://` use a tarball archive, as created by `docker save` 59 | - `fs://` use a local directory or file 60 | - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file 61 | In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. 62 | 63 | ## Examples 64 | 65 | ### Quick overview of an image 66 | 67 | ```console 68 | $ docker scout quickview golang:1.19.4 69 | ...Pulling 70 | ✓ Pulled 71 | ✓ SBOM of image already cached, 278 packages indexed 72 | 73 | Your image golang:1.19.4 │ 5C 3H 6M 63L 74 | Base image buildpack-deps:bullseye-scm │ 5C 1H 3M 48L 6? 75 | Refreshed base image buildpack-deps:bullseye-scm │ 0C 0H 0M 42L 76 | │ -5 -1 -3 -6 -6 77 | Updated base image buildpack-deps:sid-scm │ 0C 0H 1M 29L 78 | │ -5 -1 -2 -19 -6 79 | ``` 80 | 81 | ### Quick overview of the most recently built image 82 | 83 | ```console 84 | $ docker scout qv 85 | ``` 86 | 87 | ### Quick overview from an SPDX file 88 | 89 | ```console 90 | $ syft -o spdx-json alpine:3.16.1 | docker scout quickview sbom:// 91 | ✔ Loaded image alpine:3.16.1 92 | ✔ Parsed image sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d 93 | ✔ Cataloged contents 274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f 94 | ├── ✔ Packages [14 packages] 95 | ├── ✔ File digests [75 files] 96 | ├── ✔ File metadata [75 locations] 97 | └── ✔ Executables [16 executables] 98 | 99 | Target │ │ 1C 2H 8M 0L 100 | digest │ 274a317d88b5 │ 101 | ``` 102 | -------------------------------------------------------------------------------- /docs/scout_recommendations.md: -------------------------------------------------------------------------------- 1 | # docker scout recommendations 2 | 3 | 4 | Display available base image updates and remediation recommendations 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:-----------------|:---------|:--------|:--------------------------------------------------------------------------------------------------------| 10 | | `--only-refresh` | | | Only display base image refresh recommendations | 11 | | `--only-update` | | | Only display base image update recommendations | 12 | | `--org` | `string` | | Namespace of the Docker organization | 13 | | `-o`, `--output` | `string` | | Write the report to a file | 14 | | `--platform` | `string` | | Platform of image to analyze | 15 | | `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | 16 | | `--tag` | `string` | | Specify tag | 17 | 18 | 19 | 20 | 21 | ## Description 22 | 23 | The `docker scout recommendations` command display recommendations for base images updates. 24 | It analyzes the image and display recommendations to refresh or update the base image. 25 | For each recommendation it shows a list of benefits, such as 26 | fewer vulnerabilities or smaller image size. 27 | 28 | If no image is specified, the most recently built image is used. 29 | 30 | The following artifact types are supported: 31 | 32 | - Images 33 | - OCI layout directories 34 | - Tarball archives, as created by `docker save` 35 | - Local directory or file 36 | 37 | By default, the tool expects an image reference, such as: 38 | 39 | - `redis` 40 | - `curlimages/curl:7.87.0` 41 | - `mcr.microsoft.com/dotnet/runtime:7.0` 42 | 43 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 44 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 45 | 46 | - `image://` (default) use a local image, or fall back to a registry lookup 47 | - `local://` use an image from the local image store (don't do a registry lookup) 48 | - `registry://` use an image from a registry (don't use a local image) 49 | - `oci-dir://` use an OCI layout directory 50 | - `archive://` use a tarball archive, as created by `docker save` 51 | - `fs://` use a local directory or file 52 | 53 | ## Examples 54 | 55 | ### Display base image update recommendations 56 | 57 | ```console 58 | $ docker scout recommendations golang:1.19.4 59 | ``` 60 | 61 | ### Display base image refresh only recommendations 62 | 63 | ```console 64 | $ docker scout recommendations --only-refresh golang:1.19.4 65 | ``` 66 | 67 | ### Display base image update only recommendations 68 | 69 | ```console 70 | $ docker scout recommendations --only-update golang:1.19.4 71 | ``` 72 | -------------------------------------------------------------------------------- /docs/scout_repo.md: -------------------------------------------------------------------------------- 1 | # docker scout repo 2 | 3 | 4 | Commands to list, enable, and disable Docker Scout on repositories 5 | 6 | ### Subcommands 7 | 8 | | Name | Description | 9 | |:-----------------------------------|:-------------------------------| 10 | | [`disable`](scout_repo_disable.md) | Disable Docker Scout | 11 | | [`enable`](scout_repo_enable.md) | Enable Docker Scout | 12 | | [`list`](scout_repo_list.md) | List Docker Scout repositories | 13 | 14 | 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /docs/scout_repo_disable.md: -------------------------------------------------------------------------------- 1 | # docker scout repo disable 2 | 3 | 4 | Disable Docker Scout 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:----------------|:---------|:--------|:-----------------------------------------------------------------------------| 10 | | `--all` | | | Disable all repositories of the organization. Can not be used with --filter. | 11 | | `--filter` | `string` | | Regular expression to filter repositories by name | 12 | | `--integration` | `string` | | Name of the integration to use for enabling an image | 13 | | `--org` | `string` | | Namespace of the Docker organization | 14 | | `--registry` | `string` | | Container Registry | 15 | 16 | 17 | 18 | 19 | ## Examples 20 | 21 | ### Disable a specific repository 22 | 23 | ```console 24 | $ docker scout repo disable my/repository 25 | ``` 26 | 27 | ### Disable all repositories of the organization 28 | 29 | ```console 30 | $ docker scout repo disable --all 31 | ``` 32 | 33 | ### Disable some repositories based on a filter 34 | 35 | ```console 36 | $ docker scout repo disable --filter namespace/backend 37 | ``` 38 | 39 | ### Disable a repository from a specific registry 40 | 41 | ```console 42 | $ docker scout repo disable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com 43 | ``` 44 | -------------------------------------------------------------------------------- /docs/scout_repo_enable.md: -------------------------------------------------------------------------------- 1 | # docker scout repo enable 2 | 3 | 4 | Enable Docker Scout 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:----------------|:---------|:--------|:----------------------------------------------------------------------------| 10 | | `--all` | | | Enable all repositories of the organization. Can not be used with --filter. | 11 | | `--filter` | `string` | | Regular expression to filter repositories by name | 12 | | `--integration` | `string` | | Name of the integration to use for enabling an image | 13 | | `--org` | `string` | | Namespace of the Docker organization | 14 | | `--registry` | `string` | | Container Registry | 15 | 16 | 17 | 18 | 19 | ## Examples 20 | 21 | ### Enable a specific repository 22 | 23 | ```console 24 | $ docker scout repo enable my/repository 25 | ``` 26 | 27 | ### Enable all repositories of the organization 28 | 29 | ```console 30 | $ docker scout repo enable --all 31 | ``` 32 | 33 | ### Enable some repositories based on a filter 34 | 35 | ```console 36 | $ docker scout repo enable --filter namespace/backend 37 | ``` 38 | 39 | ### Enable a repository from a specific registry 40 | 41 | ```console 42 | $ docker scout repo enable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com 43 | ``` 44 | -------------------------------------------------------------------------------- /docs/scout_repo_list.md: -------------------------------------------------------------------------------- 1 | # docker scout repo list 2 | 3 | 4 | List Docker Scout repositories 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:------------------|:---------|:--------|:---------------------------------------------------------------------------| 10 | | `--filter` | `string` | | Regular expression to filter repositories by name | 11 | | `--only-disabled` | | | Filter to disabled repositories only | 12 | | `--only-enabled` | | | Filter to enabled repositories only | 13 | | `--only-registry` | `string` | | Filter to a specific registry only:
- hub.docker.com
- ecr (AWS ECR) | 14 | | `--org` | `string` | | Namespace of the Docker organization | 15 | 16 | 17 | 18 | 19 | -------------------------------------------------------------------------------- /docs/scout_sbom.md: -------------------------------------------------------------------------------- 1 | # docker scout sbom 2 | 3 | 4 | Generate or display SBOM of an image 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 10 | | `--format` | `string` | `json` | Output format:
- list: list of packages of the image
- json: json representation of the SBOM
- spdx: spdx representation of the SBOM
- cyclonedx: cyclone dx representation of the SBOM | 11 | | `--only-package-type` | `stringSlice` | | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
Can only be used with --format list | 12 | | `-o`, `--output` | `string` | | Write the report to a file | 13 | | `--platform` | `string` | | Platform of image to analyze | 14 | | `--ref` | `string` | | Reference to use if the provided tarball contains multiple references.
Can only be used with archive | 15 | 16 | 17 | 18 | 19 | ## Description 20 | 21 | The `docker scout sbom` command analyzes a software artifact to generate a 22 | Software Bill Of Materials (SBOM). 23 | 24 | The SBOM contains a list of all packages in the image. 25 | You can use the `--format` flag to filter the output of the command 26 | to display only packages of a specific type. 27 | 28 | If no image is specified, the most recently built image is used. 29 | 30 | The following artifact types are supported: 31 | 32 | - Images 33 | - OCI layout directories 34 | - Tarball archives, as created by `docker save` 35 | - Local directory or file 36 | 37 | By default, the tool expects an image reference, such as: 38 | 39 | - `redis` 40 | - `curlimages/curl:7.87.0` 41 | - `mcr.microsoft.com/dotnet/runtime:7.0` 42 | 43 | If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, 44 | or if you want to control from where the image will be resolved, you must prefix the reference with one of the following: 45 | 46 | - `image://` (default) use a local image, or fall back to a registry lookup 47 | - `local://` use an image from the local image store (don't do a registry lookup) 48 | - `registry://` use an image from a registry (don't use a local image) 49 | - `oci-dir://` use an OCI layout directory 50 | - `archive://` use a tarball archive, as created by `docker save` 51 | - `fs://` use a local directory or file 52 | 53 | ## Examples 54 | 55 | ### Display the list of packages 56 | 57 | ```console 58 | $ docker scout sbom --format list alpine 59 | ``` 60 | 61 | ### Only display packages of a specific type 62 | 63 | ```console 64 | $ docker scout sbom --format list --only-package-type apk alpine 65 | ``` 66 | 67 | ### Display the full SBOM in JSON format 68 | 69 | ```console 70 | $ docker scout sbom alpine 71 | ``` 72 | 73 | ### Display the full SBOM of the most recently built image 74 | 75 | ```console 76 | $ docker scout sbom 77 | ``` 78 | 79 | ### Write SBOM to a file 80 | 81 | ```console 82 | $ docker scout sbom --output alpine.sbom alpine 83 | ``` 84 | -------------------------------------------------------------------------------- /docs/scout_stream.md: -------------------------------------------------------------------------------- 1 | # docker scout stream 2 | 3 | 4 | Manage streams (experimental) 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:-----------------|:---------|:--------|:-------------------------------------| 10 | | `--org` | `string` | | Namespace of the Docker organization | 11 | | `-o`, `--output` | `string` | | Write the report to a file | 12 | | `--platform` | `string` | | Platform of image to record | 13 | 14 | 15 | 16 | 17 | ## Description 18 | 19 | The `docker scout stream` command lists the deployment streams and records an image to it. 20 | 21 | Once recorded, streams can be referred to by their name, eg. in the `docker scout compare` command using `--to-stream`. 22 | 23 | ## Examples 24 | 25 | ### List existing streams 26 | 27 | ```console 28 | $ %[1]s %[2]s 29 | prod-cluster-123 30 | stage-cluster-234 31 | ``` 32 | 33 | ### List images of a stream 34 | 35 | ```console 36 | $ %[1]s %[2]s prod-cluster-123 37 | namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b 38 | namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f 39 | ``` 40 | 41 | ### Record an image to a stream, for a specific platform 42 | 43 | ```console 44 | $ %[1]s %[2]s stage-cluster-234 namespace/repo:stage-latest --platform linux/amd64 45 | ✓ Pulled 46 | ✓ Successfully recorded namespace/repo:stage-latest in stream stage-cluster-234 47 | ``` 48 | -------------------------------------------------------------------------------- /docs/scout_version.md: -------------------------------------------------------------------------------- 1 | # docker scout version 2 | 3 | ``` 4 | docker scout version 5 | ``` 6 | 7 | 8 | Show Docker Scout version information 9 | 10 | 11 | 12 | 13 | ## Examples 14 | 15 | ```console 16 | $ docker scout version 17 | 18 | ⢀⢀⢀ ⣀⣀⡤⣔⢖⣖⢽⢝ 19 | ⡠⡢⡣⡣⡣⡣⡣⡣⡢⡀ ⢀⣠⢴⡲⣫⡺⣜⢞⢮⡳⡵⡹⡅ 20 | ⡜⡜⡜⡜⡜⡜⠜⠈⠈ ⠁⠙⠮⣺⡪⡯⣺⡪⡯⣺ 21 | ⢘⢜⢜⢜⢜⠜ ⠈⠪⡳⡵⣹⡪⠇ 22 | ⠨⡪⡪⡪⠂ ⢀⡤⣖⢽⡹⣝⡝⣖⢤⡀ ⠘⢝⢮⡚ _____ _ 23 | ⠱⡱⠁ ⡴⡫⣞⢮⡳⣝⢮⡺⣪⡳⣝⢦ ⠘⡵⠁ / ____| Docker | | 24 | ⠁ ⣸⢝⣕⢗⡵⣝⢮⡳⣝⢮⡺⣪⡳⣣ ⠁ | (___ ___ ___ _ _| |_ 25 | ⣗⣝⢮⡳⣝⢮⡳⣝⢮⡳⣝⢮⢮⡳ \___ \ / __/ _ \| | | | __| 26 | ⢀ ⢱⡳⡵⣹⡪⡳⣝⢮⡳⣝⢮⡳⡣⡏ ⡀ ____) | (_| (_) | |_| | |_ 27 | ⢀⢾⠄ ⠫⣞⢮⡺⣝⢮⡳⣝⢮⡳⣝⠝ ⢠⢣⢂ |_____/ \___\___/ \__,_|\__| 28 | ⡼⣕⢗⡄ ⠈⠓⠝⢮⡳⣝⠮⠳⠙ ⢠⢢⢣⢣ 29 | ⢰⡫⡮⡳⣝⢦⡀ ⢀⢔⢕⢕⢕⢕⠅ 30 | ⡯⣎⢯⡺⣪⡳⣝⢖⣄⣀ ⡀⡠⡢⡣⡣⡣⡣⡣⡃ 31 | ⢸⢝⢮⡳⣝⢮⡺⣪⡳⠕⠗⠉⠁ ⠘⠜⡜⡜⡜⡜⡜⡜⠜⠈ 32 | ⡯⡳⠳⠝⠊⠓⠉ ⠈⠈⠈⠈ 33 | 34 | 35 | 36 | version: v1.0.9 (go1.21.3 - darwin/arm64) 37 | git commit: 8bf95bf60d084af341f70e8263342f71b0a3cd16 38 | ``` 39 | -------------------------------------------------------------------------------- /docs/scout_watch.md: -------------------------------------------------------------------------------- 1 | # docker scout watch 2 | 3 | 4 | Watch repositories in a registry and push images and indexes to Docker Scout (experimental) 5 | 6 | ### Options 7 | 8 | | Name | Type | Default | Description | 9 | |:---------------------|:--------------|:--------|:------------------------------------------------------------------------------------| 10 | | `--all-images` | | | Push all images instead of only the ones pushed during the watch command is running | 11 | | `--dry-run` | | | Watch images and prepare them, but do not push them | 12 | | `--interval` | `int64` | `60` | Interval in seconds between checks | 13 | | `--org` | `string` | | Namespace of the Docker organization to which image will be pushed | 14 | | `--refresh-registry` | | | Refresh the list of repositories of a registry at every run. Only with --registry. | 15 | | `--registry` | `string` | | Registry to watch | 16 | | `--repository` | `stringSlice` | | Repository to watch | 17 | | `--sbom` | | | Create and upload SBOMs | 18 | | `--tag` | `stringSlice` | | Regular expression to match tags to watch | 19 | | `--workers` | `int` | `3` | Number of concurrent workers | 20 | 21 | 22 | 23 | 24 | ## Description 25 | 26 | The `docker scout watch` command watches repositories in a registry 27 | and pushes images or analysis results to Docker Scout. 28 | 29 | ## Examples 30 | 31 | ### Watch for new images from two repositories and push them 32 | 33 | ```console 34 | $ docker scout watch --org my-org --repository registry-1.example.com/repo-1 --repository registry-2.example.com/repo-2 35 | ``` 36 | 37 | ### Only push images with a specific tag 38 | 39 | ```console 40 | $ docker scout watch --org my-org --repository registry.example.com/my-service --tag latest 41 | ``` 42 | 43 | ### Watch all repositories of a registry 44 | 45 | ```console 46 | $ docker scout watch --org my-org --registry registry.example.com 47 | ``` 48 | 49 | ### Push all images and not just the new ones 50 | 51 | ```console 52 | $ docker scout watch--org my-org --repository registry.example.com/my-service --all-images 53 | ``` 54 | -------------------------------------------------------------------------------- /install.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # note: we require errors to propagate (don't set -e) 4 | 5 | # Copyright © 2023 Docker, Inc. 6 | 7 | set -u 8 | 9 | PROJECT_NAME="docker-scout" 10 | OWNER=docker 11 | REPO="scout-cli" 12 | GITHUB_DOWNLOAD_PREFIX=https://github.com/${OWNER}/${REPO}/releases/download 13 | INSTALL_SH_BASE_URL=https://raw.githubusercontent.com/${OWNER}/${REPO} 14 | BINARY="docker-scout" 15 | DOCKER_HOME=${DOCKER_HOME:-~/.docker} 16 | DEFAULT_INSTALL_DIR=${DOCKER_HOME}/cli-plugins 17 | PROGRAM_ARGS=$@ 18 | 19 | # do not change the name of this parameter (this must always be backwards compatible) 20 | DOWNLOAD_TAG_INSTALL_SCRIPT=${DOWNLOAD_TAG_INSTALL_SCRIPT:-true} 21 | 22 | # 23 | # usage [script-name] 24 | # 25 | usage() ( 26 | this="$1" 27 | cat </dev/null 49 | ) 50 | 51 | echo_stderr() ( 52 | echo "$@" 1>&2 53 | ) 54 | 55 | _logp=2 56 | log_set_priority() { 57 | _logp="$1" 58 | } 59 | 60 | log_priority() ( 61 | if test -z "$1"; then 62 | echo "$_logp" 63 | return 64 | fi 65 | [ "$1" -le "$_logp" ] 66 | ) 67 | 68 | init_colors() { 69 | RED='' 70 | BLUE='' 71 | PURPLE='' 72 | BOLD='' 73 | RESET='' 74 | # check if stdout is a terminal 75 | if test -t 1 && is_command tput; then 76 | # see if it supports colors 77 | ncolors=$(tput colors) 78 | if test -n "$ncolors" && test "$ncolors" -ge 8; then 79 | RED='\033[0;31m' 80 | BLUE='\033[0;34m' 81 | PURPLE='\033[0;35m' 82 | BOLD='\033[1m' 83 | RESET='\033[0m' 84 | fi 85 | fi 86 | } 87 | 88 | init_colors 89 | 90 | log_tag() ( 91 | case "$1" in 92 | 0) echo "${RED}${BOLD}[error]${RESET}" ;; 93 | 1) echo "${RED}[warn]${RESET}" ;; 94 | 2) echo "[info]${RESET}" ;; 95 | 3) echo "${BLUE}[debug]${RESET}" ;; 96 | 4) echo "${PURPLE}[trace]${RESET}" ;; 97 | *) echo "[$1]" ;; 98 | esac 99 | ) 100 | 101 | 102 | log_trace_priority=4 103 | log_trace() ( 104 | priority=$log_trace_priority 105 | log_priority "$priority" || return 0 106 | echo_stderr "$(log_tag $priority)" "${@}" "$RESET" 107 | ) 108 | 109 | log_debug_priority=3 110 | log_debug() ( 111 | priority=$log_debug_priority 112 | log_priority "$priority" || return 0 113 | echo_stderr "$(log_tag $priority)" "${@}" "$RESET" 114 | ) 115 | 116 | log_info_priority=2 117 | log_info() ( 118 | priority=$log_info_priority 119 | log_priority "$priority" || return 0 120 | echo_stderr "$(log_tag $priority)" "${@}" "$RESET" 121 | ) 122 | 123 | log_warn_priority=1 124 | log_warn() ( 125 | priority=$log_warn_priority 126 | log_priority "$priority" || return 0 127 | echo_stderr "$(log_tag $priority)" "${@}" "$RESET" 128 | ) 129 | 130 | log_err_priority=0 131 | log_err() ( 132 | priority=$log_err_priority 133 | log_priority "$priority" || return 0 134 | echo_stderr "$(log_tag $priority)" "${@}" "$RESET" 135 | ) 136 | 137 | uname_os_check() ( 138 | os="$1" 139 | case "$os" in 140 | darwin) return 0 ;; 141 | dragonfly) return 0 ;; 142 | freebsd) return 0 ;; 143 | linux) return 0 ;; 144 | android) return 0 ;; 145 | nacl) return 0 ;; 146 | netbsd) return 0 ;; 147 | openbsd) return 0 ;; 148 | plan9) return 0 ;; 149 | solaris) return 0 ;; 150 | windows) return 0 ;; 151 | esac 152 | log_err "uname_os_check '$(uname -s)' got converted to '$os' which is not a GOOS value. Please file bug at https://github.com/client9/shlib" 153 | return 1 154 | ) 155 | 156 | uname_arch_check() ( 157 | arch="$1" 158 | case "$arch" in 159 | 386) return 0 ;; 160 | amd64) return 0 ;; 161 | arm64) return 0 ;; 162 | armv5) return 0 ;; 163 | armv6) return 0 ;; 164 | armv7) return 0 ;; 165 | ppc64) return 0 ;; 166 | ppc64le) return 0 ;; 167 | mips) return 0 ;; 168 | mipsle) return 0 ;; 169 | mips64) return 0 ;; 170 | mips64le) return 0 ;; 171 | s390x) return 0 ;; 172 | amd64p32) return 0 ;; 173 | esac 174 | log_err "uname_arch_check '$(uname -m)' got converted to '$arch' which is not a GOARCH value. Please file bug report at https://github.com/client9/shlib" 175 | return 1 176 | ) 177 | 178 | unpack() ( 179 | archive="$1" 180 | 181 | log_trace "unpack(archive=${archive})" 182 | 183 | case "$archive" in 184 | *.tar.gz | *.tgz) tar --no-same-owner -xzf "$archive" ;; 185 | *.tar) tar --no-same-owner -xf "$archive" ;; 186 | *.zip) unzip -q "$archive" ;; 187 | *.dmg) extract_from_dmg "$archive" ;; 188 | *) 189 | log_err "unpack unknown archive format for ${archive}" 190 | return 1 191 | ;; 192 | esac 193 | ) 194 | 195 | extract_from_dmg() ( 196 | dmg_file="$1" 197 | 198 | mount_point="/Volumes/tmp-dmg" 199 | hdiutil attach -quiet -nobrowse -mountpoint "$mount_point" "$dmg_file" 200 | cp -fR "${mount_point}/." ./ 201 | hdiutil detach -quiet -force "$mount_point" 202 | ) 203 | 204 | http_download_curl() ( 205 | local_file="$1" 206 | source_url="$2" 207 | header="$3" 208 | 209 | log_trace "http_download_curl(local_file=$local_file, source_url=$source_url, header=$header)" 210 | 211 | if [ -z "$header" ]; then 212 | code=$(curl -w '%{http_code}' -sL -o "$local_file" "$source_url") 213 | else 214 | code=$(curl -w '%{http_code}' -sL -H "$header" -o "$local_file" "$source_url") 215 | fi 216 | 217 | if [ "$code" != "200" ]; then 218 | log_err "received HTTP status=$code for url='$source_url'" 219 | return 1 220 | fi 221 | return 0 222 | ) 223 | 224 | http_download_wget() ( 225 | local_file="$1" 226 | source_url="$2" 227 | header="$3" 228 | 229 | log_trace "http_download_wget(local_file=$local_file, source_url=$source_url, header=$header)" 230 | 231 | if [ -z "$header" ]; then 232 | wget -q -O "$local_file" "$source_url" 233 | else 234 | wget -q --header "$header" -O "$local_file" "$source_url" 235 | fi 236 | ) 237 | 238 | http_download() ( 239 | log_debug "http_download(url=$2)" 240 | if is_command curl; then 241 | http_download_curl "$@" 242 | return 243 | elif is_command wget; then 244 | http_download_wget "$@" 245 | return 246 | fi 247 | log_err "http_download unable to find wget or curl" 248 | return 1 249 | ) 250 | 251 | http_copy() ( 252 | tmp=$(mktemp) 253 | http_download "$tmp" "$1" "$2" || return 1 254 | body=$(cat "$tmp") 255 | rm -f "$tmp" 256 | echo "$body" 257 | ) 258 | 259 | hash_sha256() ( 260 | TARGET=${1:-/dev/stdin} 261 | if is_command gsha256sum; then 262 | hash=$(gsha256sum "$TARGET") || return 1 263 | echo "$hash" | cut -d ' ' -f 1 264 | elif is_command sha256sum; then 265 | hash=$(sha256sum "$TARGET") || return 1 266 | echo "$hash" | cut -d ' ' -f 1 267 | elif is_command shasum; then 268 | hash=$(shasum -a 256 "$TARGET" 2>/dev/null) || return 1 269 | echo "$hash" | cut -d ' ' -f 1 270 | elif is_command openssl; then 271 | hash=$(openssl -dst openssl dgst -sha256 "$TARGET") || return 1 272 | echo "$hash" | cut -d ' ' -f a 273 | else 274 | log_err "hash_sha256 unable to find command to compute sha-256 hash" 275 | return 1 276 | fi 277 | ) 278 | 279 | hash_sha256_verify() ( 280 | TARGET="$1" 281 | checksums="$2" 282 | if [ -z "$checksums" ]; then 283 | log_err "hash_sha256_verify checksum file not specified in arg2" 284 | return 1 285 | fi 286 | BASENAME=${TARGET##*/} 287 | want=$(grep "$BASENAME" "$checksums" 2>/dev/null | tr '\t' ' ' | cut -d ' ' -f 1) 288 | if [ -z "$want" ]; then 289 | log_err "hash_sha256_verify unable to find checksum for '${TARGET}' in '${checksums}'" 290 | return 1 291 | fi 292 | got=$(hash_sha256 "$TARGET") 293 | if [ "$want" != "$got" ]; then 294 | log_err "hash_sha256_verify checksum for '$TARGET' did not verify ${want} vs $got" 295 | return 1 296 | fi 297 | ) 298 | 299 | # ------------------------------------------------------------------------ 300 | # End of functions from https://github.com/client9/shlib 301 | # ------------------------------------------------------------------------ 302 | 303 | # asset_file_exists [path] 304 | # 305 | # returns 1 if the given file does not exist 306 | # 307 | asset_file_exists() ( 308 | path="$1" 309 | if [ ! -f "$path" ]; then 310 | return 1 311 | fi 312 | ) 313 | 314 | 315 | # github_release_json [owner] [repo] [version] 316 | # 317 | # outputs release json string 318 | # 319 | github_release_json() ( 320 | owner="$1" 321 | repo="$2" 322 | version="$3" 323 | test -z "$version" && version="latest" 324 | giturl="https://github.com/${owner}/${repo}/releases/${version}" 325 | json=$(http_copy "$giturl" "Accept:application/json") 326 | 327 | log_trace "github_release_json(owner=${owner}, repo=${repo}, version=${version}) returned '${json}'" 328 | 329 | test -z "$json" && return 1 330 | echo "$json" 331 | ) 332 | 333 | # extract_value [key-value-pair] 334 | # 335 | # outputs value from a colon delimited key-value pair 336 | # 337 | extract_value() ( 338 | key_value="$1" 339 | IFS=':' read -r _ value << EOF 340 | ${key_value} 341 | EOF 342 | echo "$value" 343 | ) 344 | 345 | # extract_json_value [json] [key] 346 | # 347 | # outputs value of the key from the given json string 348 | # 349 | extract_json_value() ( 350 | json="$1" 351 | key="$2" 352 | key_value=$(echo "$json" | grep -o "\"$key\":[^,]*[,}]" | tr -d '",}') 353 | 354 | extract_value "$key_value" 355 | ) 356 | 357 | # github_release_tag [release-json] 358 | # 359 | # outputs release tag string 360 | # 361 | github_release_tag() ( 362 | json="$1" 363 | tag=$(extract_json_value "$json" "tag_name") 364 | test -z "$tag" && return 1 365 | echo "$tag" 366 | ) 367 | 368 | # download_github_release_checksums [release-url-prefix] [name] [version] [output-dir] 369 | # 370 | # outputs path to the downloaded checksums file 371 | # 372 | download_github_release_checksums() ( 373 | download_url="$1" 374 | name="$2" 375 | version="$3" 376 | output_dir="$4" 377 | 378 | log_trace "download_github_release_checksums(url=${download_url}, name=${name}, version=${version}, output_dir=${output_dir})" 379 | 380 | checksum_filename=${name}_${version}_checksums.txt 381 | checksum_url=${download_url}/${checksum_filename} 382 | output_path="${output_dir}/${checksum_filename}" 383 | 384 | http_download "$output_path" "$checksum_url" "" 385 | asset_file_exists "$output_path" 386 | 387 | log_trace "download_github_release_checksums() returned '${output_path}'" 388 | 389 | echo "$output_path" 390 | ) 391 | 392 | # search_for_asset [checksums-file-path] [name] [os] [arch] [format] 393 | # 394 | # outputs name of the asset to download 395 | # 396 | search_for_asset() ( 397 | checksum_path="$1" 398 | name="$2" 399 | os="$3" 400 | arch="$4" 401 | format="$5" 402 | 403 | log_trace "search_for_asset(checksum-path=${checksum_path}, name=${name}, os=${os}, arch=${arch}, format=${format})" 404 | 405 | asset_glob="${name}_.*_${os}_${arch}.${format}" 406 | output_path=$(grep -o "$asset_glob" "$checksum_path" || true) 407 | 408 | log_trace "search_for_asset() returned '${output_path}'" 409 | 410 | echo "$output_path" 411 | ) 412 | 413 | # uname_os 414 | # 415 | # outputs an adjusted os value 416 | # 417 | uname_os() ( 418 | os=$(uname -s | tr '[:upper:]' '[:lower:]') 419 | case "$os" in 420 | cygwin_nt*) os="windows" ;; 421 | mingw*) os="windows" ;; 422 | msys_nt*) os="windows" ;; 423 | esac 424 | 425 | uname_os_check "$os" 426 | 427 | log_trace "uname_os() returned '${os}'" 428 | 429 | echo "$os" 430 | ) 431 | 432 | # uname_arch 433 | # 434 | # outputs an adjusted architecture value 435 | # 436 | uname_arch() ( 437 | arch=$(uname -m) 438 | case "$arch" in 439 | x86_64) arch="amd64" ;; 440 | x86) arch="386" ;; 441 | i686) arch="386" ;; 442 | i386) arch="386" ;; 443 | aarch64) arch="arm64" ;; 444 | armv5*) arch="armv5" ;; 445 | armv6*) arch="armv6" ;; 446 | armv7*) arch="armv7" ;; 447 | esac 448 | 449 | uname_arch_check "$arch" 450 | 451 | log_trace "uname_arch() returned '${arch}'" 452 | 453 | echo "$arch" 454 | ) 455 | 456 | # get_release_tag [owner] [repo] [tag] 457 | # 458 | # outputs tag string 459 | # 460 | get_release_tag() ( 461 | owner="$1" 462 | repo="$2" 463 | tag="$3" 464 | 465 | log_trace "get_release_tag(owner=${owner}, repo=${repo}, tag=${tag})" 466 | 467 | json=$(github_release_json "$owner" "$repo" "$tag") 468 | real_tag=$(github_release_tag "$json") 469 | if test -z "$real_tag"; then 470 | return 1 471 | fi 472 | 473 | log_trace "get_release_tag() returned '${real_tag}'" 474 | 475 | echo "$real_tag" 476 | ) 477 | 478 | # tag_to_version [tag] 479 | # 480 | # outputs version string 481 | # 482 | tag_to_version() ( 483 | tag="$1" 484 | value="${tag#v}" 485 | 486 | log_trace "tag_to_version(tag=${tag}) returned '${value}'" 487 | 488 | echo "$value" 489 | ) 490 | 491 | # get_binary_name [os] [arch] [default-name] 492 | # 493 | # outputs a the binary string name 494 | # 495 | get_binary_name() ( 496 | os="$1" 497 | arch="$2" 498 | binary="$3" 499 | original_binary="$binary" 500 | 501 | case "$os" in 502 | windows) binary="${binary}.exe" ;; 503 | esac 504 | 505 | log_trace "get_binary_name(os=${os}, arch=${arch}, binary=${original_binary}) returned '${binary}'" 506 | 507 | echo "$binary" 508 | ) 509 | 510 | 511 | # get_format_name [os] [arch] [default-format] 512 | # 513 | # outputs an adjusted file format 514 | # 515 | get_format_name() ( 516 | os="$1" 517 | arch="$2" 518 | format="$3" 519 | original_format="$format" 520 | 521 | case "$os" in 522 | windows) format=zip ;; 523 | esac 524 | 525 | log_trace "get_format_name(os=${os}, arch=${arch}, format=${original_format}) returned '${format}'" 526 | 527 | echo "$format" 528 | ) 529 | 530 | # download_and_install_asset [release-url-prefix] [download-path] [install-path] [name] [os] [arch] [version] [format] [binary] 531 | # 532 | # attempts to download the archive and install it to the given path. 533 | # 534 | download_and_install_asset() ( 535 | download_url="$1" 536 | download_path="$2" 537 | install_path="$3" 538 | name="$4" 539 | os="$5" 540 | arch="$6" 541 | version="$7" 542 | format="$8" 543 | binary="$9" 544 | 545 | asset_filepath=$(download_asset "$download_url" "$download_path" "$name" "$os" "$arch" "$version" "$format") 546 | 547 | # don't continue if we couldn't download an asset 548 | if [ -z "$asset_filepath" ]; then 549 | log_err "could not find release asset for os='${os}' arch='${arch}' format='${format}' " 550 | return 1 551 | fi 552 | 553 | install_asset "$asset_filepath" "$install_path" "$binary" 554 | ) 555 | 556 | # download_asset [release-url-prefix] [download-path] [name] [os] [arch] [version] [format] [binary] 557 | # 558 | # outputs the path to the downloaded asset asset_filepath 559 | # 560 | download_asset() ( 561 | download_url="$1" 562 | destination="$2" 563 | name="$3" 564 | os="$4" 565 | arch="$5" 566 | version="$6" 567 | format="$7" 568 | 569 | log_trace "download_asset(url=${download_url}, destination=${destination}, name=${name}, os=${os}, arch=${arch}, version=${version}, format=${format})" 570 | 571 | checksums_filepath=$(download_github_release_checksums "$download_url" "$name" "$version" "$destination") 572 | 573 | log_trace "checksums content:\n$(cat ${checksums_filepath})" 574 | 575 | asset_filename=$(search_for_asset "$checksums_filepath" "$name" "$os" "$arch" "$format") 576 | 577 | # don't continue if we couldn't find a matching asset from the checksums file 578 | if [ -z "$asset_filename" ]; then 579 | return 1 580 | fi 581 | 582 | asset_url="${download_url}/${asset_filename}" 583 | asset_filepath="${destination}/${asset_filename}" 584 | http_download "$asset_filepath" "$asset_url" "" 585 | 586 | hash_sha256_verify "$asset_filepath" "$checksums_filepath" 587 | 588 | log_trace "download_asset_by_checksums_file() returned '${asset_filepath}'" 589 | 590 | echo "$asset_filepath" 591 | ) 592 | 593 | # install_asset [asset-path] [destination-path] [binary] 594 | # 595 | install_asset() ( 596 | asset_filepath="$1" 597 | destination="$2" 598 | binary="$3" 599 | 600 | log_trace "install_asset(asset=${asset_filepath}, destination=${destination}, binary=${binary})" 601 | 602 | # don't continue if we don't have anything to install 603 | if [ -z "$asset_filepath" ]; then 604 | return 605 | fi 606 | 607 | archive_dir=$(dirname "$asset_filepath") 608 | 609 | # unarchive the downloaded archive to the temp dir 610 | (cd "$archive_dir" && unpack "$asset_filepath") 611 | 612 | # create the destination dir 613 | test ! -d "$destination" && install -d "$destination" 614 | 615 | # install the binary to the destination dir 616 | install "${archive_dir}/${binary}" "${destination}/" 617 | ) 618 | 619 | main() ( 620 | # parse arguments 621 | 622 | # note: never change default install directory (this must always be backwards compatible) 623 | install_dir=${install_dir:-${DEFAULT_INSTALL_DIR}} 624 | 625 | # note: never change the program flags or arguments (this must always be backwards compatible) 626 | while getopts "b:dh?x" arg; do 627 | case "$arg" in 628 | b) install_dir="$OPTARG" ;; 629 | d) 630 | if [ "$_logp" = "$log_info_priority" ]; then 631 | # -d == debug 632 | log_set_priority $log_debug_priority 633 | else 634 | # -dd (or -ddd...) == trace 635 | log_set_priority $log_trace_priority 636 | fi 637 | ;; 638 | h | \?) usage "$0" ;; 639 | x) set -x ;; 640 | esac 641 | done 642 | shift $((OPTIND - 1)) 643 | set +u 644 | tag="$1" 645 | 646 | if [ "$install_dir" = "$DEFAULT_INSTALL_DIR" ]; then 647 | if [ ! -d "$DOCKER_HOME" ]; then 648 | log_err "docker is not installed; refusing to install to '${install_dir}'" 649 | exit 1 650 | fi 651 | fi 652 | 653 | if [ -z "$tag" ]; then 654 | log_debug "checking github for the current release tag" 655 | tag="" 656 | else 657 | log_debug "checking github for release tag='${tag}'" 658 | fi 659 | set -u 660 | 661 | tag=$(get_release_tag "$OWNER" "$REPO" "$tag") 662 | 663 | if [ "$?" != "0" ]; then 664 | log_err "unable to find tag='${tag}'" 665 | log_err "do not specify a version or select a valid version from https://github.com/${OWNER}/${REPO}/releases" 666 | return 1 667 | fi 668 | 669 | # run the application 670 | 671 | version=$(tag_to_version "$tag") 672 | os=$(uname_os) 673 | arch=$(uname_arch) 674 | format=$(get_format_name "$os" "$arch" "tar.gz") 675 | binary=$(get_binary_name "$os" "$arch" "$BINARY") 676 | download_url="${GITHUB_DOWNLOAD_PREFIX}/${tag}" 677 | 678 | # we always use the install.sh script that is associated with the tagged release. Why? the latest install.sh is not 679 | # guaranteed to be able to install every version of the application. We use the DOWNLOAD_TAG_INSTALL_SCRIPT env var 680 | # to indicate if we should continue processing with the existing script or to download the script from the given tag. 681 | if [ "$DOWNLOAD_TAG_INSTALL_SCRIPT" = "true" ]; then 682 | export DOWNLOAD_TAG_INSTALL_SCRIPT=false 683 | log_info "fetching release script for tag='${tag}'" 684 | http_copy "${INSTALL_SH_BASE_URL}/${tag}/install.sh" "" | sh -s -- ${PROGRAM_ARGS} 685 | exit "$?" 686 | fi 687 | 688 | log_info "using release tag='${tag}' version='${version}' os='${os}' arch='${arch}'" 689 | 690 | download_dir=$(mktemp -d) 691 | trap 'rm -rf -- "$download_dir"' EXIT 692 | 693 | log_debug "downloading files into ${download_dir}" 694 | 695 | download_and_install_asset "$download_url" "$download_dir" "$install_dir" "$PROJECT_NAME" "$os" "$arch" "$version" "$format" "$binary" 696 | 697 | # don't continue if we couldn't install the asset 698 | if [ "$?" != "0" ]; then 699 | log_err "failed to install ${BINARY}" 700 | return 1 701 | fi 702 | 703 | log_info "installed ${install_dir}/${binary}" 704 | ) 705 | 706 | # entrypoint 707 | 708 | set +u 709 | if [ -z "$TEST_INSTALL_SH" ]; then 710 | set -u 711 | main "$@" 712 | fi 713 | set -u 714 | --------------------------------------------------------------------------------