From 1a788ffa508940db6e8c801752077249a331286c Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 2 Aug 2023 21:04:30 +0200
Subject: [PATCH] scout: added data handling documentation

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 _data/toc.yaml         |  2 ++
 scout/data-handling.md | 57 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 scout/data-handling.md

diff --git a/_data/toc.yaml b/_data/toc.yaml
index ae49bd330c..468c3ad232 100644
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@@ -1950,6 +1950,8 @@ manuals:
       title: Artifactory integration
     - path: /scout/advisory-db-sources/
       title: Advisory Database
+    - path: /scout/data-handling/
+      title: Data handling
 
 - sectiontitle: Docker Admin (Early Access)
   section:
diff --git a/scout/data-handling.md b/scout/data-handling.md
new file mode 100644
index 0000000000..2d80894969
--- /dev/null
+++ b/scout/data-handling.md
@@ -0,0 +1,57 @@
+---
+description: How Docker Scout handles image metadata
+keywords: scanning, supply chain, security, data, metadata
+title: Data collection and storage in Docker Scout
+---
+
+{% include scout-early-access.md %}
+
+Docker Scout image analysis works by collecting metadata from the container
+images that you analyze. This metadata is stored on the Docker Scout platform.
+
+## Data transmission
+
+Docker Scout collects and sends the following image metadata to the platform.
+
+Docker and OCI image metadata:
+
+- Image creation timestamp
+- Image digest
+- Ports exposed by the image
+- Environment variable names and values
+- Name and value of image labels
+- Order of image layers
+- Hardware architecture
+- Operating system type and version
+- Registry URL and type
+
+Software Bill of Materials (SBOM) metadata:
+
+- Advisory prefix URL (PURL)
+- Package author and description
+- License IDs
+- Package name and namespace
+- Package scheme and size
+- Package type and version
+- Filepath within the image
+- The type of direct dependency
+- Total package count
+
+SBOM metadata is used to match package types and versions with public
+vulnerability data to infer whether a package is considered vulnerable.
+When the Docker Scout platform receives information from its advisory database
+about new CVEs (and other risks, such as leaked secrets), it "overlays" this
+information on the SBOM. If there's a match, the results of the match are
+displayed in the user interfaces where Docker Scout data is surfaced, such as
+the Docker Scout Dashboard and in Docker Desktop.
+
+## Data storage
+
+For the purposes of providing the Docker Scout service, data is stored using:
+
+- Amazon Web Services (AWS) on servers located in US-EAST, USA
+- Google Cloud Platform (GCP) on servers located in US-EAST, USA
+
+Data is used according to the processes described at
+[docker.com/legal](https://www.docker.com/legal/) to provide the key
+capabilities of Docker Scout.