diff --git a/content/scout/integrations/ci/_index.md b/content/scout/integrations/ci/_index.md index f20dbac3e7..11cb253d39 100644 --- a/content/scout/integrations/ci/_index.md +++ b/content/scout/integrations/ci/_index.md @@ -18,4 +18,8 @@ Available integrations: - [GitLab](gitlab.md) - [Microsoft Azure DevOps Pipelines](azure.md) - [Circle CI](circle-ci.md) -- [Jenkins](jenkins.md) \ No newline at end of file +- [Jenkins](jenkins.md) + +You can also add runtime integration as part of your CI/CD pipeline, which lets +you assign an image to an environment, such as `production` or `staging`, when +you deploy it. For more information, see [Environment monitoring](../environment/_index.md). diff --git a/content/scout/integrations/environment/_index.md b/content/scout/integrations/environment/_index.md index 4547cb397b..a3884f1448 100644 --- a/content/scout/integrations/environment/_index.md +++ b/content/scout/integrations/environment/_index.md @@ -1,9 +1,7 @@ --- -description: 'Docker Scout can integrate with runtime environments to give you realtime - +description: + Docker Scout can integrate with runtime environments to give you realtime insights about your software supply chain. - - ' keywords: supply chain, security, streams, environments, workloads, deployments title: Integrating Docker Scout with environments --- @@ -11,7 +9,7 @@ title: Integrating Docker Scout with environments {{< include "scout-early-access.md" >}} You can integrate Docker Scout with your runtime environments, and get insights -for your running workloads. This gives you a realtime view of your security +for your running workloads. This gives you a real-time view of your security status for your deployed artifacts. Docker Scout lets you define multiple environments, and assign images to @@ -32,6 +30,48 @@ assign that tag to your `production` environment. You might be running a different version of the same image in staging, in which case you can assign that version of the image to the `staging` environment. +To add environments to Docker Scout, you can: + +- Use the `docker scout env ` CLI command to record images to environments manually +- Enable a runtime integration to automatically detect images in your environments. + +Docker Scout supports the following runtime integrations: + +- [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout#record-an-image-deployed-to-a-stream-environment) +- [CLI client](./cli.md) + +> **Note** +> +> Only organization owners can create new environments and set up integrations. +> Additionally, Docker Scout only assigns an image to an environment if the +> image [has been analyzed](../../image-analysis.md), either manually or +> through a [registry integration](../_index.md#container-registries). + +## List environments + +To see all of the available environments for an organization, you can use the +`docker scout env` command. + +```console +$ docker scout env +``` + +By default, this prints all environments for your personal Docker organization. +To list environments for another organization that you're a part of, use the +`--org` flag. + +```console +$ docker scout env --org +``` + +You can use the `docker scout config` command to change the default +organization. This changes the default organization for all `docker scout` +commands, not just `env`. + +```console +$ docker scout config organization +``` + ## Comparing between environments Assigning images to environments lets you make comparisons with and between @@ -39,26 +79,14 @@ environments. This is useful for things like GitHub pull requests, for comparing the image built from the code in the PR to the corresponding image in staging or production. -You can also compare with streams using the `--to-stream` flag on the +You can also compare with streams using the `--to-env` flag on the [`docker scout compare`](../../../engine/reference/commandline/scout_compare.md) CLI command: ```console -$ docker scout compare --to-stream production myorg/webapp:latest +$ docker scout compare --to-env production myorg/webapp:latest ``` -## Assign images to environments - -To add environments to Docker Scout, you can: - -- Use the `docker scout stream` command in the Docker CLI: - - ```console - $ docker scout stream - ``` - -- Use the [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout#record-an-image-deployed-to-a-stream-environment) - ## View images for an environment To view the images for an environment: @@ -72,10 +100,17 @@ The list displays all images that have been assigned to the selected environment. If you've deployed multiple versions of the same image in an environment, all versions of the image appear in the list. +Alternatively, you can use the `docker scout env` command to view the images from the terminal. + +```console +$ docker scout env production +docker/scout-demo-service:main@sha256:ef08dca54c4f371e7ea090914f503982e890ec81d22fd29aa3b012351a44e1bc +``` + ### Mismatching image tags When you've selected an environment on the **Images** tab, tags in the list represent the tag that was used to deploy the image. Tags are mutable, meaning that you can change the image digest that a tag refers to. If Docker Scout detects that a tag refers to an outdated digest, a warning icon displays next -to the image name. \ No newline at end of file +to the image name. diff --git a/content/scout/integrations/environment/cli.md b/content/scout/integrations/environment/cli.md new file mode 100644 index 0000000000..fabed6aeae --- /dev/null +++ b/content/scout/integrations/environment/cli.md @@ -0,0 +1,130 @@ +--- +description: Integrate your runtime environments with Docker Scout using the CLI client +keywords: docker scout, integration, image analysis, runtime, workloads, cli, environments +title: Generic environment integration with CLI +--- + +{{< include "scout-early-access.md" >}} + +You can create a generic environment integration by running the Docker Scout +CLI client in your CI workflows. The CLI client is available as a binary on +GitHub and as a container image on Docker Hub. Use the client to invoke the +`docker scout environment` command to assign your images to environments. + +For more information about how to use the `docker scout environment` command, +refer to the [CLI reference](../../../engine/reference/commandline/scout_environment.md). + +## Examples + +Before you start, set the following environment variables in your CI system: + +- `DOCKER_SCOUT_HUB_USER`: your Docker Hub username +- `DOCKER_SCOUT_HUB_PASSWORD`: your Docker Hub personal access token + +Make sure the variables are accessible to your project. + +{{< tabs >}} +{{< tab name="Circle CI" >}} + +```yaml +version: 2.1 + +jobs: + record_environment: + machine: + image: ubuntu-2204:current + image: namespace/repo + steps: + - run: | + if [[ -z "$CIRCLE_TAG" ]]; then + tag="$CIRCLE_TAG" + echo "Running tag '$CIRCLE_TAG'" + else + tag="$CIRCLE_BRANCH" + echo "Running on branch '$CI_COMMIT_BRANCH'" + fi + echo "tag = $tag" + - run: docker run -it \ + -e DOCKER_SCOUT_HUB_USER=$DOCKER_SCOUT_HUB_USER \ + -e DOCKER_SCOUT_HUB_PASSWORD=$DOCKER_SCOUT_HUB_PASSWORD \ + docker/scout-cli:1.0.2 environment \ + --org "" \ + "" ${image}:${tag} +``` + +{{< /tab >}} +{{< tab name="GitLab" >}} + +The following example uses the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html). + +```yaml +variables: + image: namespace/repo + +record_environment: + image: docker/scout-cli:1.0.2 + script: + - | + if [[ -z "$CI_COMMIT_TAG" ]]; then + tag="latest" + echo "Running tag '$CI_COMMIT_TAG'" + else + tag="$CI_COMMIT_REF_SLUG" + echo "Running on branch '$CI_COMMIT_BRANCH'" + fi + echo "tag = $tag" + - environment --org "PRODUCTION" ${image}:${tag} +``` + +{{< /tab >}} +{{< tab name="Azure DevOps" >}} + +```yaml +trigger: + - main + +resources: + - repo: self + +variables: + tag: "$(Build.BuildId)" + image: "namespace/repo" + +stages: + - stage: Docker Scout + displayName: Docker Scout environment integration + jobs: + - job: Record + displayName: Record environment + pool: + vmImage: ubuntu-latest + steps: + - task: Docker@2 + - script: docker run -it \ + -e DOCKER_SCOUT_HUB_USER=$DOCKER_SCOUT_HUB_USER \ + -e DOCKER_SCOUT_HUB_PASSWORD=$DOCKER_SCOUT_HUB_PASSWORD \ + docker/scout-cli:1.0.2 environment \ + --org "" \ + "" $(image):$(tag) +``` + +{{< /tab >}} +{{< tab name="Jenkins" >}} + +```groovy +stage('Analyze image') { + steps { + // Install Docker Scout + sh 'curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /usr/local/bin' + + // Log into Docker Hub + sh 'echo $DOCKER_SCOUT_HUB_PASSWORD | docker login -u $DOCKER_SCOUT_HUB_USER --password-stdin' + + // Analyze and fail on critical or high vulnerabilities + sh 'docker-scout environment --org "" "" $IMAGE_TAG + } +} +``` + +{{< /tab >}} +{{< /tabs >}} diff --git a/data/toc.yaml b/data/toc.yaml index 2ff3531d98..076aae712f 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1994,6 +1994,8 @@ Manuals: section: - title: Overview path: /scout/integrations/environment/ + - title: Generic + path: /scout/integrations/environment/cli/ - sectiontitle: Container registries section: - title: Artifactory