mirror of https://github.com/docker/docs.git
Documentation for dso.docker.com (#15540)
* initial commit with atomist content * updated domain name for dso * updated tutorial * fixed broken link * updated image policies * rm excess pages * update toc and remove broken links * first pass on k8s integration pageg * updated dockerfile label * reworked policies, restructuring * update links, rm dockerhub integration * added reference to seamless docker hub integration * added back hub tab in get started * fix platform statement for connect registry * update get-started * update try instruction * edited deploy tracking * rm policies from toc, update advisories page * moved advisories page to new reference section * removed unsupported settings * removed gitops and k8s adm ctrl * shift emphasis from scanning to sboms * fix typo in oci label Co-authored-by: CrazyMax <github@crazymax.dev> * address review comments * added buildx and other edits * updated try tutorial * update google instructions * removed unsupported content * add disclaimer to settings page * editorial, cleanup * minor updates * fix toc * address review comments * fix broken link Signed-off-by: David Karlsson <david.karlsson@docker.com> Signed-off-by: David Karlsson <david.karlsson@docker.com> Co-authored-by: CrazyMax <github@crazymax.dev>
This commit is contained in:
David Karlsson
GitHub
parent
f3cfa1532e
commit
f7c9499e7d
|
|
@ -1531,6 +1531,27 @@ manuals:
|
|||
- path: /docker-hub/release-notes/
|
||||
title: Release notes
|
||||
|
||||
- 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: Docker subscription
|
||||
section:
|
||||
- path: /subscription/
|
||||
|
|
@ -1646,6 +1667,7 @@ manuals:
|
|||
title: Compatibility
|
||||
- path: /registry/help/
|
||||
title: Getting help
|
||||
|
||||
- path: /release-notes/
|
||||
title: Release notes
|
||||
- path: /support/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
> **Note**
|
||||
>
|
||||
> Atomist is currently in [Early Access](/release-lifecycle#early-access-ea).
|
||||
> Features and APIs are subject to change.
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: Advisory sources
|
||||
description: Add and remove vulnerability advisories
|
||||
keywords: >
|
||||
advisories, vulnerabilities, databases, open source, configure, security,
|
||||
atomist
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
With no configuration required, Atomist already draws vulnerability data from
|
||||
several public advisories. You can extend this by adding your own, custom
|
||||
advisories if you wish.
|
||||
|
||||
## Adding and updating advisories
|
||||
|
||||
To add your own advisories:
|
||||
|
||||
1. Create a repository called `atomist-advisories` in the GitHub account where
|
||||
you've installed the Atomist GitHub app.
|
||||
|
||||
2. In the default branch of the repository, add a new JSON file called
|
||||
`<source>/<source id>.json`, where:
|
||||
|
||||
- `source` should be the name of your company
|
||||
- `source-id` has to be a unique id for the advisory within `source`.
|
||||
|
||||
3. The JSON file must follow the schema defined in
|
||||
[Open Source Vulnerability format](https://ossf.github.io/osv-schema/).
|
||||
|
||||
Refer to the
|
||||
[GitHub Advisory Database](https://github.com/github/advisory-database/tree/main/advisories/github-reviewed)
|
||||
for examples of advisories.
|
||||
|
||||
## Deleting advisories
|
||||
|
||||
Delete an advisory from the database by removing the corresponding JSON advisory
|
||||
file from the `atomist-advisories` repository.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Atomist only considers additions, changes and removals of JSON advisory files
|
||||
> in the repository's **default branch**.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: Settings
|
||||
description:
|
||||
keywords: settings, configure, vulnerabilities, base images, atomist
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
This page describes the configurable settings for Atomist. Enabling any of these
|
||||
settings instructs Atomist to carry out an action whenever a specific Git event
|
||||
occurs. These features require that you
|
||||
[install the Atomist GitHub app](/atomist/integrate/github/#connect-to-github){:
|
||||
target="blank" rel="noopener" class=""} in your GitHub organization.
|
||||
|
||||
To view and manage these settings, go to the
|
||||
[settings page](https://dso.docker.com/r/auth/policies){: target="blank"
|
||||
rel="noopener" class=""} on the Atomist website.
|
||||
|
||||
## New image vulnerabilities
|
||||
|
||||
Extract software bill of material from container images, and match packages with
|
||||
data from vulnerability advisories. Identify when new vulnerabilities get
|
||||
introduced, and display them as GitHub status check on the pull request that
|
||||
introduces them.
|
||||
|
||||
## Base image tags
|
||||
|
||||
Pin base image tags to digests in Dockerfiles, and check for supported tags on
|
||||
Docker official images. Automatically creates a pull request pinning the
|
||||
Dockerfile to the latest digest for the base image tag used.
|
||||
|
|
@ -0,0 +1,436 @@
|
|||
---
|
||||
title: Get started
|
||||
description: Getting started with Atomist
|
||||
keywords: atomist, software supply chain, vulnerability scanning, tutorial
|
||||
toc_max: 2
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
To get started with Atomist, you'll need to:
|
||||
|
||||
- Connect Atomist with your container registry
|
||||
- Link your container images with their Git source
|
||||
|
||||
Before you can begin the setup, you need a Docker ID. If you don't already have
|
||||
one, you can [register here](https://hub.docker.com/signup){: target="blank"
|
||||
rel="noopener" class=""}.
|
||||
|
||||
## Connect container registry
|
||||
|
||||
This section describes how to integrate Atomist with your container registry.
|
||||
Follow the applicable instructions depending on the type of container registry
|
||||
you use. After completing this setup, Atomist will have read-only access to your
|
||||
registry, and gets notified about pushed or deleted images.
|
||||
|
||||
> Using Docker Hub? 🐳
|
||||
>
|
||||
> If you are using Docker Hub as your container registry, you can skip this step
|
||||
> and go straight to
|
||||
> [linking images to Git source](#link-images-to-git-repository). Atomist
|
||||
> integrates seamlessly with your Docker Hub organizations.
|
||||
|
||||
<!-- vale off -->
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab-ecr" aria-expanded="true">Amazon</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab-ghcr">GitHub</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab-google">Google</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab-jfrog">JFrog</a></li>
|
||||
</ul>
|
||||
<!-- vale on -->
|
||||
<div class="tab-content"><br>
|
||||
<div id="tab-ecr" class="tab-pane fade in active" markdown="1">
|
||||
<!-- ECR -->
|
||||
|
||||
When setting up an Amazon Elastic Container Registry (ECR) integration with
|
||||
Atomist, the following AWS resources are required:
|
||||
|
||||
- Read-only Identity Access Management (IAM) role, for Atomist to be able to
|
||||
access the container registry
|
||||
- Amazon EventBridge, to notify Atomist of pushed and deleted images
|
||||
|
||||
This procedure uses pre-defined CloudFormation templates to create the necessary
|
||||
IAM role and Amazon EventBridge. This template protects you from
|
||||
[confused deputy attacks](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html){:
|
||||
target="blank" rel="noopener" class=""} by ensuring a unique `ExternalId`, along
|
||||
with the appropriate condition on the IAM role statement.
|
||||
|
||||
1. Go to <https://dso.docker.com> and sign in using your Docker ID credentials.
|
||||
2. Navigate to the **Integrations** tab and select **Configure** next to the
|
||||
**Elastic Container Registry** integration.
|
||||
3. Fill out all the fields, except **Trusted Role ARN**. The trusted role
|
||||
identity is known only after applying the CloudFormation template.
|
||||
|
||||
Choose basic auth credentials to protect the endpoint that AWS uses to notify
|
||||
Atomist. The URL and the basic auth credentials are parameters to the
|
||||
CloudFormation template.
|
||||
|
||||
4. Now create the CloudFormation stack. Before creating the stack, AWS asks you
|
||||
to enter three parameters.
|
||||
|
||||
- `Url`: the API endpoint copied from Atomist
|
||||
- `Username`, `Password`: basic authentication credentials for the endpoint.
|
||||
Must match what you entered in the Atomist workspace.
|
||||
|
||||
Use the following **Launch Stack** buttons to start reviewing the details in
|
||||
your AWS account.
|
||||
|
||||
> Note
|
||||
>
|
||||
> Before creating the stack, AWS will ask for acknowledgement that creating
|
||||
> this stack requires a capability. This stack creates a role that will grant
|
||||
> Atomist read-only access to ECR resources.
|
||||
>
|
||||
> 
|
||||
|
||||
<div style="text-align: center">
|
||||
<table>
|
||||
<tr>
|
||||
<th>Region</th>
|
||||
<th>ecr-integration.template</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>us-east-1</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-us-east-1/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>us-east-2</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-us-east-2/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>us-west-1</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=us-west-1#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-us-west-1/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>us-west-2</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-us-west-2/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>eu-west-1</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=eu-west-1#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-eu-west-1/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>eu-west-2</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=eu-west-2#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-eu-west-2/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>eu-west-3</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=eu-west-3#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-eu-west-3/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>eu-central-1</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=eu-central-1#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-eu-central-1/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>ca-central-1</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=ca-central-1#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-ca-central-1/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>ap-southeast-2</th>
|
||||
<td>
|
||||
<a href="https://console.aws.amazon.com/cloudformation/home?region=ap-southeast-2#/stacks/new?stackName=atomist-public-templates-ecr-integration&templateURL=https://s3.amazonaws.com/atomist-ap-southeast-2/atomist-public-templates/latest/ecr-integration.template">
|
||||
<img alt="Launch Stack" src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" />
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
5. After creating the stack, copy the **Value** for the **AssumeRoleArn** key
|
||||
from the **Outputs** tab in AWS.
|
||||
|
||||
{: width="700px"}
|
||||
|
||||
6. Paste the copied **AssumeRoleArn** value into the **Trusted Role ARN** field
|
||||
on the Atomist configuration page.
|
||||
|
||||
7. Select **Save Configuration**.
|
||||
|
||||
Atomist tests the connection with your ECR registry. A green check mark
|
||||
displays beside the integration if a successful connection is made.
|
||||
|
||||
{:
|
||||
width="700px"}
|
||||
|
||||
</div>
|
||||
<div id="tab-ghcr" class="tab-pane fade" markdown="1">
|
||||
<!-- GitHub Container Registry -->
|
||||
|
||||
To integrate Atomist with GitHub Container Registry, connect your GitHub
|
||||
account, and enter a personal access token for Atomist to use when pulling
|
||||
container images.
|
||||
|
||||
1. Go to <https://dso.docker.com> and sign in using your Docker ID credentials.
|
||||
2. Connect your GitHub account as instructed in the
|
||||
[GitHub app page](./integrate/github.md#connect-to-github).
|
||||
3. Open the **Integrations** tab, and select **Configure** next to the **GitHub
|
||||
Container Registry** in the list.
|
||||
4. Fill out the fields and select **Save Configuration**.
|
||||
|
||||
Atomist requires the **Personal access token** for connecting images to
|
||||
private repositories. The token must have the
|
||||
[`read:packages` scope](https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages).
|
||||
|
||||
Leave the **Personal access token** field blank if you only want to index
|
||||
images in public repositories.
|
||||
|
||||
</div>
|
||||
<div id="tab-google" class="tab-pane fade" markdown="1">
|
||||
<!-- Google -->
|
||||
|
||||
Setting up an Atomist integration with Google Container Registry and Google
|
||||
Artifact Registry involves:
|
||||
|
||||
- Creating a service account and grant it a read-only access role.
|
||||
- Creating a PubSub subscription on the `gcr` topic to watch for activity in the
|
||||
registry.
|
||||
|
||||
To complete the following procedure requires administrator's permissions in the
|
||||
project.
|
||||
|
||||
1. Set the following environment variables. You will use them in the next steps
|
||||
when configuring the Google Cloud resources, using the `gcloud` CLI.
|
||||
|
||||
```bash
|
||||
export SERVICE_ACCOUNT_ID="atomist-integration" # can be anything you like
|
||||
export PROJECT_ID="YOUR_GCP_PROJECT_ID"
|
||||
```
|
||||
|
||||
2. Create the service account.
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts create ${SERVICE_ACCOUNT_ID} \
|
||||
--project ${PROJECT_ID} \
|
||||
--description="Atomist Integration Service Account" \
|
||||
--display-name="Atomist Integration"
|
||||
```
|
||||
|
||||
3. Grant the service account read-only access to the artifact registry.
|
||||
|
||||
The role name differs depending on whether you use Artifact Registry or
|
||||
Container Registry:
|
||||
|
||||
- `roles/artifactregistry.reader` for Google Artifact Registry
|
||||
- `roles/object.storageViewer` for Google Container Registry
|
||||
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
|
||||
--project ${PROJECT_ID} \
|
||||
--member="serviceAccount:${SERVICE_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com" \
|
||||
--role="roles/artifactregistry.reader" # change this if you use GCR
|
||||
```
|
||||
|
||||
4. Grant service account access to Atomist.
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts add-iam-policy-binding "${SERVICE_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com" \
|
||||
--project ${PROJECT_ID} \
|
||||
--member="serviceAccount:atomist-bot@atomist.iam.gserviceaccount.com" \
|
||||
--role="roles/iam.serviceAccountTokenCreator"
|
||||
```
|
||||
|
||||
5. Go to <https://dso.docker.com> and sign in with your Docker ID credentials.
|
||||
6. Navigate to the **Integrations** tab and select **Configure** next to the
|
||||
**Google Artifact Registry** integration.
|
||||
7. Fill out the following fields:
|
||||
|
||||
- **Project ID** is the `PROJECT_ID` used in earlier steps.
|
||||
- **Service Account**: The email address of the service account created
|
||||
step 2.
|
||||
|
||||
8. Select **Save Configuration**. Atomist will test the connection. Green check
|
||||
marks indicate a successful connection.
|
||||
|
||||
{:
|
||||
width="700px"}
|
||||
|
||||
Next, create a new PubSub subscription on the `gcr` topic in registry. This
|
||||
subscription notifies Atomist about new or deleted images in the registry.
|
||||
|
||||
9. Copy the URL in the **Events Webhook** field to your clipboard. This will be
|
||||
the `PUSH_ENDPOINT_URI` for the PubSub subscription.
|
||||
|
||||
10. Define the following three variable values, in addition to the `PROJECT_ID`
|
||||
and `SERVICE_ACCOUNT_ID` from earlier:
|
||||
|
||||
- `PUSH_ENDPOINT_URL`: the webhook URL copied from the Atomist workspace.
|
||||
- `SERVICE_ACCOUNT_EMAIL`: the service account address; a combination of the
|
||||
service account ID and project ID.
|
||||
- `SUBSCRIPTION`: the name of the PubSub (can be anything).
|
||||
|
||||
```bash
|
||||
PUSH_ENDPOINT_URI={COPY_THIS_FROM_ATOMIST}
|
||||
SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com"
|
||||
SUBSCRIPTION="atomist-integration-subscription"
|
||||
```
|
||||
|
||||
11. Create the PubSub for the `gcr` topic.
|
||||
|
||||
```bash
|
||||
gcloud pubsub subscriptions create ${SUBSCRIPTION} \
|
||||
--topic='gcr' \
|
||||
--push-auth-token-audience='atomist' \
|
||||
--push-auth-service-account="${SERVICE_ACCOUNT_EMAIL}" \
|
||||
--push-endpoint="${PUSH_ENDPOINT_URI}"
|
||||
```
|
||||
|
||||
When the first image push is successfully detected, a green check mark on the
|
||||
integration page will indicate that the integration works.
|
||||
|
||||
</div>
|
||||
<div id="tab-jfrog" class="tab-pane fade" markdown="1">
|
||||
<!-- JFrog Artifactory -->
|
||||
|
||||
Atomist can index images in a JFrog Artifactory repository by means of a
|
||||
monitoring agent.
|
||||
|
||||
The agent scans configured repositories at regular intervals, and send newly
|
||||
discovered images' metadata to the Atomist data plane.
|
||||
|
||||
In the following example, `https://hal9000.atomist.com` is a private registry
|
||||
only visible on an internal network.
|
||||
|
||||
```
|
||||
docker run -ti atomist/docker-registry-broker:latest\
|
||||
index-image remote \
|
||||
--workspace AQ1K5FIKA \
|
||||
--api-key team::6016307E4DF885EAE0579AACC71D3507BB38E1855903850CF5D0D91C5C8C6DC0 \
|
||||
--artifactory-url https://hal9000.docker.com \
|
||||
--artifactory-repository atomist-docker-local \
|
||||
--container-registry-host atomist-docker-local.hal9000.docker.com
|
||||
--username admin \
|
||||
--password password
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| `workspace` | ID of your Atomist workspace. |
|
||||
| `api-key` | Atomist API key. |
|
||||
| `artifactory-url` | Base URL of the Artifactory instance. Must not contain trailing slashes. |
|
||||
| `artifactory-repository` | The name of the container registry to watch. |
|
||||
| `container-registry-host` | The hostname associated with the Artifactory repository containing images, if different from `artifactory-url`. |
|
||||
| `username` | Username for HTTP basic authentication with Artifactory. |
|
||||
| `password` | Password for HTTP basic authentication with Artifactory. |
|
||||
|
||||
</div>
|
||||
<hr>
|
||||
</div>
|
||||
|
||||
## Link images to Git repository
|
||||
|
||||
Knowing the source repository of an image is a prerequisite for Atomist to
|
||||
interact with the Git repository. For Atomist to be able to link scanned images
|
||||
back to a Git repository repository, you must annotate the image at build time.
|
||||
|
||||
The image labels that Atomist requires are:
|
||||
|
||||
| Label | Value |
|
||||
| ------------------------------------ | ------------------------------------------------- |
|
||||
| `org.opencontainers.image.revision` | The commit revision that the image is built for. |
|
||||
| `com.docker.image.source.entrypoint` | Path to the Dockerfile, relative to project root. |
|
||||
|
||||
For more information about pre-defined OCI annotations, see the
|
||||
[specification document on GitHub](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys).
|
||||
|
||||
You can add these labels to images using the built-in Git provenance feature of
|
||||
Buildx, or set using the `--label` CLI argument.
|
||||
|
||||
### Add labels using Docker Buildx
|
||||
|
||||
> Beta
|
||||
>
|
||||
> Git provenance labels in Buildx is a [Beta](/release-lifecycle#beta)
|
||||
> feature.
|
||||
|
||||
To add the image labels using Docker Buildx, set the environment variable
|
||||
`BUILDX_GIT_LABELS=1`. The Buildx will create the labels automatically when
|
||||
building the image.
|
||||
|
||||
```bash
|
||||
export BUILDX_GIT_LABELS=1
|
||||
docker buildx build . -f docker/Dockerfile
|
||||
```
|
||||
|
||||
### Add labels using the label CLI argument
|
||||
|
||||
Assign image labels using the `--label` argument for `docker build`.
|
||||
|
||||
```bash
|
||||
docker build . -f docker/Dockerfile -t $IMAGE_NAME \
|
||||
--label "org.opencontainers.image.revision=10ac8f8bdaa343677f2f394f9615e521188d736a" \
|
||||
--label "com.docker.image.source.entrypoint=docker/Dockerfile"
|
||||
```
|
||||
|
||||
Images built in a CI/CD environment can leverage the built-in environment
|
||||
variables when setting the Git revision label:
|
||||
|
||||
| Build tool | Environment variable |
|
||||
| ----------------------------- | ---------------------------------------------------------------- |
|
||||
| GitHub Actions | {% raw %}`${{ github.sha }}`{% endraw %} |
|
||||
| GitHub Actions, pull requests | {% raw %}`${{ github.event.pull_request.head.sha }}`{% endraw %} |
|
||||
| GitLab CI/CD | `$CI_COMMIT_SHA` |
|
||||
| Docker Hub automated builds | `$SOURCE_COMMIT` |
|
||||
| Google Cloud Build | `$COMMIT_SHA` |
|
||||
| AWS CodeBuild | `$CODEBUILD_RESOLVED_SOURCE_VERSION` |
|
||||
| Manually | `$(git rev-parse HEAD)` |
|
||||
|
||||
Consult the documentation for your CI/CD platform to learn which variables to
|
||||
use.
|
||||
|
||||
## Where to go next
|
||||
|
||||
Atomist is now tracking bill of materials, packages, and vulnerabilities for
|
||||
your images! You can view your image scan results on the
|
||||
[images overview page](https://dso.docker.com/r/auth/overview/images).
|
||||
|
||||
Teams use Atomist to protect downstream workloads from new vulnerabilities. It's
|
||||
also used to help teams track and remediate new vulnerabilities that impact
|
||||
existing workloads. The following sections describe integrate and configure
|
||||
Atomist further. For example, to gain visibility into container workload systems
|
||||
like Kubernetes.
|
||||
|
||||
- Connect Atomist with your GitHub repositories by
|
||||
[installing the Atomist app](integrate/github.md) for your GitHub
|
||||
organization.
|
||||
- Manage which Atomist features you use in [settings](configure/settings.md).
|
||||
- Learn about [deployment tracking](integrate/deploys.md) and how Atomist can
|
||||
help watch your deployed containers.
|
||||
- Atomist watches for new advisories from public sources, but you can also
|
||||
[add your own internal advisories](configure/advisories.md) for more
|
||||
information.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 387 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 370 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 871 KiB |
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: Introduction to Atomist
|
||||
description: Introduction to Atomist
|
||||
keywords:
|
||||
atomist, software supply chain, indexing, sbom, vulnerabilities, automation
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
Atomist is a data and automation platform for managing the software supply
|
||||
chain. It extracts metadata from container images, evaluates the data, and helps
|
||||
you understand the state of the image.
|
||||
|
||||
Integrating Atomist into your systems and repositories grants you essential
|
||||
information about the images you build, and the containers running in
|
||||
production. Beyond collecting and visualizing information, Atomist can help you
|
||||
further by giving you recommendations, notifications, validation, and more.
|
||||
|
||||
Example capabilities made possible with Atomist are:
|
||||
|
||||
- Stay up to date with advisory databases without having to re-analyze your
|
||||
images.
|
||||
- Automatically open pull requests to update base images for improved product
|
||||
security.
|
||||
- Check that your applications don't contain secrets, such as a password or API
|
||||
token, before they get deployed.
|
||||
- Dissect Dockerfiles and see where vulnerabilities come from, line by line.
|
||||
|
||||
## How it works
|
||||
|
||||
Atomist monitors your container registry for new images. When it finds a new
|
||||
image, it analyzes and extracts metadata about the image contents and any base
|
||||
images used. The metadata is uploaded to an isolated partition in the Atomist
|
||||
data plane where it's securely stored.
|
||||
|
||||
The Atomist data plane is a combination of metadata and a large knowledge graph
|
||||
of public software and vulnerability data. Atomist determines the state of your
|
||||
container by overlaying the image metadata with the knowledge graph.
|
||||
|
||||
## What's next?
|
||||
|
||||
Head over to the [try atomist](./try-atomist.md) page for instructions on how to
|
||||
run Atomist, locally and with no strings attached.
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
title: Track deployments
|
||||
description: >
|
||||
Deployment tracking lets Atomist compare your image builds with what's running
|
||||
in your environments.
|
||||
keywords: deployment, kubernetes, security
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
By integrating Atomist with a runtime environment, you can track vulnerabilities
|
||||
for deployed containers. This gives you contexts for whether security debt is
|
||||
increasing or decreasing.
|
||||
|
||||
There are several options for how you could implement deployment tracking:
|
||||
|
||||
- Invoking the API directly
|
||||
- Adding it as a step in your continuous deployment pipeline
|
||||
- Creating Kubernetes admission controllers
|
||||
|
||||
## API
|
||||
|
||||
Each Atomist workspace exposes an API endpoint. Submitting a POST request to the
|
||||
endpoint updates Atomist about what image you are running in your environments.
|
||||
This lets you compare data for images you build against images of containers
|
||||
running in staging or production.
|
||||
|
||||
You can find the API endpoint URL on the **Integrations** page. Using this API
|
||||
requires an API key.
|
||||
|
||||
The most straight-forward use is to post to this endpoint using a webhook. When
|
||||
deploying a new image, submit an automated POST request (using `curl`, for
|
||||
example) as part of your deployment pipeline.
|
||||
|
||||
```bash
|
||||
$ curl <api-endpoint-url> \\
|
||||
-X POST \\
|
||||
-H "Content-Type: application/json" \\
|
||||
-H "Authorization: Bearer <api-token>" \\
|
||||
-d '{"image": {"url": "<image-url>@<sha256-digest>"}}'
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
The API supports the following parameters in the request body:
|
||||
|
||||
```json
|
||||
{
|
||||
"image": {
|
||||
"url": "string",
|
||||
"name": "string"
|
||||
},
|
||||
"environment": {
|
||||
"name": "string"
|
||||
},
|
||||
"platform": {
|
||||
"os": "string",
|
||||
"architecture": "string",
|
||||
"variant": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Mandatory | Default | Description |
|
||||
| ----------------------- | :-------: | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `image.url` | Yes | | Fully qualified reference name of the image, plus version (digest). You **must** specify the image version by digest. |
|
||||
| `image.name` | No | | Optional identifier. If you deploy many containers from the same image in any one environment, each instance must have a unique name. |
|
||||
| `environment.name` | No | `deployed` | Use custom environment names to track different image versions in environments, like `staging` and `production` |
|
||||
| `platform.os` | No | `linux` | Image operating system. |
|
||||
| `platform.architecture` | No | `amd64` | Instruction set architecture. |
|
||||
| `platform.variant` | No | | Optional variant label. |
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
---
|
||||
title: Integrate with GitHub
|
||||
description: Link images with commits and pull requests on GitHub
|
||||
keywords: github, app, link, commits, source code, atomist
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
When installed for a GitHub organization, the Atomist GitHub app links
|
||||
repository activity to images. This enables Atomist to relate image tags and
|
||||
digests directly to specific commits in the source repository. It also opens up
|
||||
the possibility to incorporate image analysis in your Git workflow. For example,
|
||||
by adding analysis checks to pull request, or automatically raising pull
|
||||
requests for updating and pinning base image versions.
|
||||
|
||||
Install the GitHub app in the organization that contains the source code
|
||||
repositories for your Docker images.
|
||||
|
||||
## Connect to GitHub
|
||||
|
||||
1. Go to <https://dso.docker.com/> and sign in using your Docker ID.
|
||||
2. Open the **Repositories** tab.
|
||||
3. Select **Connect to GitHub** and follow the authorization flow. This installs
|
||||
the
|
||||
[Atomist GitHub App](https://github.com/apps/atomist "Atomist GitHub App").
|
||||
|
||||
{: width="700px" }
|
||||
|
||||
4. Install the app.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> If your GitHub account is a member of one or more organizations, GitHub
|
||||
> prompts you to choose which account to install the app into. Select the
|
||||
> account that contains the source repositories for your images.
|
||||
|
||||
After installing the app, GitHub redirects you back to Atomist.
|
||||
|
||||
5. In the repository selection menu, select what repositories you want Atomist
|
||||
to start watching.
|
||||
|
||||
{: width="500px" }
|
||||
|
||||
If you are just looking to evaluate Atomist, start by selecting a few
|
||||
repositories during evaluation. Once you are comfortable using Atomist, you
|
||||
can switch on the integration for all repositories. Selecting **All
|
||||
repositories** also includes any repository created in the future.
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> If Atomist detects `FROM` commands in Dockerfiles in the selected
|
||||
> repositories, it begins raising automated pull requests. The pull requests
|
||||
> update the Dockerfile `FROM`-line to specify the image versions (as
|
||||
> digests).
|
||||
{: .important }
|
||||
|
||||
6. Select **Save selection**.
|
||||
|
||||
Atomist is now connected with your GitHub repositories and is be able to link
|
||||
image analyses with Git commits.
|
||||
|
||||
## Manage repository access
|
||||
|
||||
If you wish to add or remove repository access for Atomist, go to the
|
||||
**Repositories** page.
|
||||
|
||||
- Select **All repositories** if you want enable Atomist for all connected
|
||||
organizations and repositories.
|
||||
- Select **Only select repositories** if you want to provision access to only a
|
||||
subset of repositories.
|
||||
|
||||
## Disconnect from GitHub
|
||||
|
||||
You might want to disconnect from GitHub when:
|
||||
|
||||
- You want to change which GitHub organization or account connected to your
|
||||
Atomist workspace.
|
||||
|
||||
To do so, disconnect the old GitHub organization or account first. Then,
|
||||
follow the instructions for [connecting to GitHub](#connect-to-github) for the
|
||||
new GitHub organization or account.
|
||||
|
||||
- You want to remove Atomist access to a GitHub organization or account when you
|
||||
no longer use Atomist.
|
||||
|
||||
To disconnect a GitHub account:
|
||||
|
||||
1. Go to **Repositories** and select the **Disconnect** link. This removes the
|
||||
connection to your GitHub organization or account.
|
||||
2. Go to the
|
||||
[GitHub Applications settings page](https://github.com/settings/installations){:
|
||||
target="blank" rel="noopener" class=""}, then:
|
||||
|
||||
3. Find **atomist** on the Installed GitHub Apps tab.
|
||||
4. Select **Configure**
|
||||
|
||||
5. Select **Uninstall**. This removes the installation of the Atomist GitHub
|
||||
App from your GitHub organization or account.
|
||||
|
||||
6. Find **atomist** on the **Authorized GitHub Apps** tab.
|
||||
7. Select **Revoke**.
|
||||
|
||||
This removes the authorization of the Atomist GitHub App from your GitHub
|
||||
organization or account.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 227 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
|
|
@ -0,0 +1,104 @@
|
|||
---
|
||||
title: Try Atomist
|
||||
description:
|
||||
keywords: atomist, tutorial, introduction, local images
|
||||
---
|
||||
|
||||
{% include atomist/disclaimer.md %}
|
||||
|
||||
The quickest way to try Atomist is to run it on your local images, as a CLI
|
||||
tool. Trying it locally eliminates the need of having to integrate with and
|
||||
connect to a remote container registry. The CLI uses your local Docker daemon
|
||||
directly to upload the Software Bill of Materials (SBOM) to the Atomist control
|
||||
plane for analysis.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you can begin the setup, you need a Docker ID. If you don't already
|
||||
have one, you can [register here](https://hub.docker.com/signup){:
|
||||
target="blank" rel="noopener" class=""}.
|
||||
|
||||
## Steps
|
||||
|
||||
> Note
|
||||
>
|
||||
> Only use this CLI-based method of indexing images for testing or trial
|
||||
> purposes. For further evaluation or production use, integrate Atomist with
|
||||
> your container registry. See [get started](./get-started.md).
|
||||
|
||||
1. Go to the [Atomist website](https://dso.docker.com) and sign in using your
|
||||
Docker ID.
|
||||
2. Open the **Integrations** tab.
|
||||
3. Under **API Keys**, create a new API key.
|
||||
4. In your terminal of choice, invoke the Atomist CLI tool using `docker run`.
|
||||
Update the following values:
|
||||
|
||||
- `--workspace`: the workspace ID found on the **Integrations** page on the
|
||||
Atomist website.
|
||||
- `--api-key`: the API key you just created.
|
||||
- `--image`: the Docker image that you want to index.
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-ti atomist/docker-registry-broker:0.0.1 \
|
||||
index-image local \
|
||||
--workspace AQ1K5FIKA \
|
||||
--api-key team::6016307E4DF885EAE0579AACC71D3507BB38E1855903850CF5D0D91C5C8C6DC0 \
|
||||
--image docker.io/david/myimage:latest
|
||||
```
|
||||
|
||||
> Note
|
||||
>
|
||||
> The image must have a tag (for example, `myimage:latest`) so that you are
|
||||
> able to identify the image in the
|
||||
> [Atomist web UI](https://dso.docker.com/r/auth/overview/images).
|
||||
|
||||
The output should be similar to the following:
|
||||
|
||||
```bash
|
||||
[info] Starting session with correlation-id c12e08d3-3bcc-4475-ab21-7114da599eaf
|
||||
[info] Starting atomist/docker-vulnerability-scanner-skill 'index_image' (1f99caa) atomist/skill:0.12.0-main.44 (fe90e3c) nodejs:16.15.0
|
||||
[info] Indexing image python:latest
|
||||
[info] Downloading image
|
||||
[info] Download completed
|
||||
[info] Indexing completed
|
||||
[info] Mapped packages to layers
|
||||
[info] Indexing completed successfully
|
||||
[info] Transacting image manifest for docker.io/david/myimage:latest with digest sha256:a8077d2b2ff4feb1588d941f00dd26560fe3a919c16a96305ce05f7b90f388f6
|
||||
[info] Successfully transacted entities in team AQ1K5FIKA
|
||||
[info] Image URL is https://dso.atomist.com/AQ1K5FIKA/overview/images/myimage/digests/sha256:a8077d2b2ff4feb1588d941f00dd26560fe3a919c16a96305ce05f7b90f388f6
|
||||
[info] Transacting SBOM...
|
||||
[info] Successfully transacted entities in team AQ1K5FIKA
|
||||
[info] Transacting SBOM...
|
||||
```
|
||||
|
||||
5. When the command exits, open the
|
||||
[Atomist web UI](https://dso.docker.com/r/auth/overview/images), where you
|
||||
should see the image in the list.
|
||||
|
||||
{:
|
||||
width="700px"}
|
||||
|
||||
6. Select the image name. This gets you to the list of image tags.
|
||||
|
||||
{: width="700px"}
|
||||
|
||||
Since this is your first time indexing this image, the list only has one tag
|
||||
for now. When you integrate Atomist with your container registry, images and
|
||||
tags show up in this list automatically.
|
||||
|
||||
7. Select the tag name. This shows you the insights for this tag.
|
||||
|
||||
{:
|
||||
width="700px"}
|
||||
|
||||
In this view, you can see how many vulnerabilities this image has, their
|
||||
severity levels, whether there is a fix version available, and more.
|
||||
|
||||
## Where to go next
|
||||
|
||||
The tutorial ends here. Take some time to explore the different data views that
|
||||
Atomist presents about your image. When you're ready, head to the
|
||||
[get started guide](./get-started.md) to learn how to start integrating Atomist
|
||||
in your software supply chain.
|
||||
Loading…
Reference in New Issue