scout: add docs for docker scout hub and cli

- add: new docker scout section - add: advanced image analysis - add: scout artifactory integration - add: image details view - add: docker scout cli reference - change: hub vulnerability scanning - change: security best practices (previously /develop/scan-images) - change: prune references to docker scan - deprecate: docker scan - remove: atomist section
benz0li · Feb 24, 2023 · c040293 · c040293
1 parent 618b9c0
commit c040293
Show file tree

Hide file tree

Showing 53 changed files with 1,188 additions and 1,289 deletions.
diff --git a/.github/vale/Vocab/Technology/accept.txt b/.github/vale/Vocab/Technology/accept.txt
@@ -1,4 +1,5 @@
 APIs?
+CVEs?
 DHCP
 DNS
 Ethernet
@@ -11,6 +12,7 @@ IPv[46]
 IPvlan
 MAC
 RPM
+SARIF
 SDKs?
 SSO
 TCP

diff --git a/_data/scout-cli/docker_scout.yaml b/_data/scout-cli/docker_scout.yaml
@@ -0,0 +1,18 @@
+command: docker scout
+short: Command line tool for Docker Scout
+long: Command line tool for Docker Scout
+usage: docker scout [command]
+pname: docker
+plink: docker.yaml
+cname:
+    - docker scout cves
+    - docker scout version
+clink:
+    - docker_scout_cves.yaml
+    - docker_scout_version.yaml
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+
diff --git a/_data/scout-cli/docker_scout_cves.yaml b/_data/scout-cli/docker_scout_cves.yaml
@@ -0,0 +1,225 @@
+command: docker scout cves
+short: Display CVEs identified in a software artifact
+long: |-
+    The `docker scout cves` command analyzes a software artifact for vulnerabilities.
+    The following artifact types are supported:
+
+    - Images
+    - OCI layout directories
+    - Tarball archives, as created by `docker save`
+
+    The tool analyzes the provided software artifact, and generates a vulnerability report.
+
+    By default, the tool expects an image reference, such as:
+
+    - `redis`
+    - `curlimages/curl:7.87.0`
+    - `mcr.microsoft.com/dotnet/runtime:7.0`
+
+    If the artifact you want to analyze is an OCI directory or a tarball archive, you must use the `--type` flag.
+usage: docker scout cves [OPTIONS] IMAGE|DIRECTORY|ARCHIVE
+pname: docker scout
+plink: docker_scout.yaml
+options:
+    - option: debug
+      value_type: bool
+      default_value: "false"
+      description: Debug messages
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: details
+      value_type: bool
+      default_value: "false"
+      description: Print details on default text output
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: exit-code
+      shorthand: e
+      value_type: bool
+      default_value: "false"
+      description: Return exit code '2' if vulnerabilities are detected
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: format
+      value_type: string
+      default_value: txt-by-packages
+      description: |-
+        Output format of the generated vulnerability report:
+        - packages: default output, plain text with vulnerabilities grouped by packages
+        - sarif: json Sarif output
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: ignore-base
+      value_type: bool
+      default_value: "false"
+      description: Filter out CVEs introduced from base image
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-cve-id
+      value_type: stringSlice
+      default_value: '[]'
+      description: |
+        Comma separated list of CVE ids (like CVE-2021-45105) to search for
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-fixed
+      value_type: bool
+      default_value: "false"
+      description: Filter to fixable CVEs
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-package-type
+      value_type: stringSlice
+      default_value: '[]'
+      description: |
+        Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-severity
+      value_type: stringSlice
+      default_value: '[]'
+      description: |
+        Comma separated list of severities (critical, high, medium, low) to filter CVEs by
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-unfixed
+      value_type: bool
+      default_value: "false"
+      description: Filter to unfixed CVEs
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: output
+      shorthand: o
+      value_type: string
+      description: Write the report to a file.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: platform
+      value_type: string
+      description: Platform of image for which to list CVEs for
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: ref
+      value_type: string
+      description: |-
+        Reference to use if the provided tarball contains multiple references.
+        Can only be used with --type archive.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+examples: |-
+    ### Display vulnerabilities grouped by package
+
+    ```console
+    $ docker scout cves alpine
+    Analyzing image alpine
+        ✓ Image stored for indexing
+        ✓ Indexed 18 packages
+        ✓ No vulnerable package detected
+    ```
+
+    ### Display vulnerabilities from a `docker save` tarball
+
+    ```console
+    $ docker save alpine > alpine.tar
+
+    $ docker scout cves --type archive alpine.tar
+    Analyzing archive alpine.tar
+        ✓ Archive read
+        ✓ SBOM of image already cached, 18 packages indexed
+        ✓ No vulnerable package detected
+    ```
+
+    ### Display vulnerabilities from an OCI directory
+
+    ```console
+    $ skopeo copy --override-os linux docker://alpine oci:alpine
+
+    $ docker scout cves --type oci-dir alpine
+    Analyzing OCI directory alpine
+        ✓ OCI directory read
+        ✓ Image stored for indexing
+        ✓ Indexed 19 packages
+        ✓ No vulnerable package detected
+    ```
+
+    ### Export vulnerabilities to a SARIF JSON file
+
+    ```console
+    $ docker scout cves --format sarif --output alpine.sarif.json alpine
+    Analyzing image alpine
+        ✓ SBOM of image already cached, 18 packages indexed
+        ✓ No vulnerable package detected
+        ✓ Report written to alpine.sarif.json
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+
diff --git a/_data/scout-cli/docker_scout_version.yaml b/_data/scout-cli/docker_scout_version.yaml
@@ -0,0 +1,18 @@
+command: docker scout version
+short: Show Docker Scout version information
+long: Show Docker Scout version information
+usage: docker scout version
+pname: docker scout
+plink: docker_scout.yaml
+examples: |-
+    ```console
+    $ docker scout version
+    version: v0.2.2 (go1.19.5 - darwin/arm64)
+    git commit: c15f374b9a39d993da2e8a1db7edc4be4f7c0c1e
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+
diff --git a/_data/toc.yaml b/_data/toc.yaml
@@ -136,13 +136,11 @@ guides:
   - path: /develop/
     title: Overview
   - path: /develop/dev-best-practices/
-    title: Best practices
-  - sectiontitle: Build images
-    section:
-    - path: /develop/develop-images/dockerfile_best-practices/
-      title: Dockerfile best practices
-  - path: /develop/scan-images/
-    title: Scan images
+    title: Development best practices
+  - path: /develop/develop-images/dockerfile_best-practices/
+    title: Dockerfile best practices
+  - path: /develop/security-best-practices/
+    title: Security best practices
 - sectiontitle: Deploy your app to the cloud
   section:
   - path: /cloud/aci-integration/
@@ -605,6 +603,14 @@ reference:
       title: docker run
     - path: /engine/reference/commandline/save/
       title: docker save
+    - sectiontitle: docker scout
+      section:
+      - path: /engine/reference/commandline/scout/
+        title: docker scout
+      - path: /engine/reference/commandline/scout_cves/
+        title: docker scout cves
+      - path: /engine/reference/commandline/scout_version/
+        title: docker scout version
     - path: /engine/reference/commandline/search/
       title: docker search
     - sectiontitle: docker secret
@@ -1796,6 +1802,17 @@ manuals:
   - path: /docker-hub/release-notes/
     title: Release notes
 
+- sectiontitle: Docker Scout (Early Access)
+  section:
+    - path: /scout/
+      title: Overview
+    - path: /scout/image-details-view/
+      title: Image details view
+    - path: /scout/advanced-image-analysis/
+      title: Advanced image analysis
+    - path: /scout/artifactory/
+      title: Artifactory integration
+
 - sectiontitle: Docker subscription
   section:
   - path: /subscription/
@@ -1865,31 +1882,9 @@ manuals:
   - path: /docker-hub/image-access-management/
     title: Image Access Management
 
-
 - title: Security announcements
   path: /security/
 
-- sectiontitle: Atomist
-  section:
-    - path: /atomist/
-      title: Introduction
-    - path: /atomist/try-atomist/
-      title: Try Atomist
-    - path: /atomist/get-started/
-      title: Get started
-    - sectiontitle: Configure
-      section:
-        - path: /atomist/configure/settings/
-          title: Settings
-        - path: /atomist/configure/advisories/
-          title: Advisories
-    - sectiontitle: Integrate
-      section:
-        - path: /atomist/integrate/github/
-          title: GitHub
-        - path: /atomist/integrate/deploys/
-          title: Track deployments
-
 - sectiontitle: Open-source projects
   section:
   - sectiontitle: Docker Registry

diff --git a/_includes/atomist/disclaimer.md b/_includes/atomist/disclaimer.md
diff --git a/_redirects.yml b/_redirects.yml
@@ -553,3 +553,9 @@
 # feedback
 "https://docs.google.com/forms/d/e/1FAIpQLSenjK8KiBiOrwCpq06u_iVEZGv4tfTEpfmY_cQDmsqJrHL9Gw/viewform":
   - /feedback/extension/
+
+# Docker Scout
+"/scout/":
+  - /go/scout/
+"/scout/artifactory":
+  - /go/scout-artifactory/
-Original file line number
+Diff line change
@@ -1,4 +1,5 @@
     APIs?
+    CVEs?
     DHCP
     DNS
     Ethernet
@@ Expand All / @@ -11,6 +12,7 @@ IPv[46] @@
     IPvlan
     MAC
     RPM
+    SARIF
     SDKs?
     SSO
     TCP
@@ Expand Down @@