diff --git a/_data/toc.yaml b/_data/toc.yaml index ab225238c2..12cc37e9c1 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -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/ diff --git a/_includes/atomist/disclaimer.md b/_includes/atomist/disclaimer.md new file mode 100644 index 0000000000..b2cd254033 --- /dev/null +++ b/_includes/atomist/disclaimer.md @@ -0,0 +1,4 @@ +> **Note** +> +> Atomist is currently in [Early Access](/release-lifecycle#early-access-ea). +> Features and APIs are subject to change. diff --git a/atomist/configure/advisories.md b/atomist/configure/advisories.md new file mode 100644 index 0000000000..db9ebcc16b --- /dev/null +++ b/atomist/configure/advisories.md @@ -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 + `/.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**. diff --git a/atomist/configure/settings.md b/atomist/configure/settings.md new file mode 100644 index 0000000000..c4618a1f02 --- /dev/null +++ b/atomist/configure/settings.md @@ -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. diff --git a/atomist/get-started.md b/atomist/get-started.md new file mode 100644 index 0000000000..104687f6aa --- /dev/null +++ b/atomist/get-started.md @@ -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. + + + + +

+
+ + +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 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. + > + > ![confirm](./images/ecr/capability.png) + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Regionecr-integration.template
us-east-1 + + Launch Stack + +
us-east-2 + + Launch Stack + +
us-west-1 + + Launch Stack + +
us-west-2 + + Launch Stack + +
eu-west-1 + + Launch Stack + +
eu-west-2 + + Launch Stack + +
eu-west-3 + + Launch Stack + +
eu-central-1 + + Launch Stack + +
ca-central-1 + + Launch Stack + +
ap-southeast-2 + + Launch Stack + +
+
+ +5. After creating the stack, copy the **Value** for the **AssumeRoleArn** key + from the **Outputs** tab in AWS. + + ![AWS stack creation output](./images/ecr/stack-output.png){: 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. + + ![integration list showing a successful ECR integration](./images/ecr/connection-successful.png){: + width="700px"} + +
+
+ + +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 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. + +
+
+ + +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 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. + + ![GCP configuration successful](./images/gcp/config-success.png){: + 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. + +
+
+ + +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. | + +
+
+
+ +## 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. diff --git a/atomist/images/ecr/capability.png b/atomist/images/ecr/capability.png new file mode 100644 index 0000000000..326aeacf18 Binary files /dev/null and b/atomist/images/ecr/capability.png differ diff --git a/atomist/images/ecr/connection-successful.png b/atomist/images/ecr/connection-successful.png new file mode 100644 index 0000000000..8d8b851248 Binary files /dev/null and b/atomist/images/ecr/connection-successful.png differ diff --git a/atomist/images/ecr/role-arn.png b/atomist/images/ecr/role-arn.png new file mode 100644 index 0000000000..bfd2138a49 Binary files /dev/null and b/atomist/images/ecr/role-arn.png differ diff --git a/atomist/images/ecr/stack-output.png b/atomist/images/ecr/stack-output.png new file mode 100644 index 0000000000..a0760bbf97 Binary files /dev/null and b/atomist/images/ecr/stack-output.png differ diff --git a/atomist/images/gcp/config-success.png b/atomist/images/gcp/config-success.png new file mode 100644 index 0000000000..f8672ff77f Binary files /dev/null and b/atomist/images/gcp/config-success.png differ diff --git a/atomist/images/images-overview.png b/atomist/images/images-overview.png new file mode 100644 index 0000000000..3becb18f9d Binary files /dev/null and b/atomist/images/images-overview.png differ diff --git a/atomist/images/tags-list.png b/atomist/images/tags-list.png new file mode 100644 index 0000000000..9c42f24066 Binary files /dev/null and b/atomist/images/tags-list.png differ diff --git a/atomist/images/vulnerabilities-overview.png b/atomist/images/vulnerabilities-overview.png new file mode 100644 index 0000000000..6470ffc34f Binary files /dev/null and b/atomist/images/vulnerabilities-overview.png differ diff --git a/atomist/index.md b/atomist/index.md new file mode 100644 index 0000000000..f960ca619c --- /dev/null +++ b/atomist/index.md @@ -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. diff --git a/atomist/integrate/deploys.md b/atomist/integrate/deploys.md new file mode 100644 index 0000000000..9db797fc05 --- /dev/null +++ b/atomist/integrate/deploys.md @@ -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 \\ + -X POST \\ + -H "Content-Type: application/json" \\ + -H "Authorization: Bearer " \\ + -d '{"image": {"url": "@"}}' +``` + +### 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. | diff --git a/atomist/integrate/github.md b/atomist/integrate/github.md new file mode 100644 index 0000000000..e3c42d9e88 --- /dev/null +++ b/atomist/integrate/github.md @@ -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 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"). + + ![install the GitHub app](images/gh-install.png){: 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. + + ![activate repositories](images/activate-repos.png){: 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. diff --git a/atomist/integrate/images/activate-repos.png b/atomist/integrate/images/activate-repos.png new file mode 100644 index 0000000000..b90c2d496f Binary files /dev/null and b/atomist/integrate/images/activate-repos.png differ diff --git a/atomist/integrate/images/gh-install.png b/atomist/integrate/images/gh-install.png new file mode 100644 index 0000000000..fb6fa3d756 Binary files /dev/null and b/atomist/integrate/images/gh-install.png differ diff --git a/atomist/try-atomist.md b/atomist/try-atomist.md new file mode 100644 index 0000000000..4895aae20b --- /dev/null +++ b/atomist/try-atomist.md @@ -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. + + ![indexed image in the image overview list](./images/images-overview.png){: + width="700px"} + +6. Select the image name. This gets you to the list of image tags. + + ![list of image tags](./images/tags-list.png){: 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. + + ![vulnerability breakdown view](./images/vulnerabilities-overview.png){: + 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.