From 3e20edee554cf7d7f8c2d8972e5c9a6859be55b5 Mon Sep 17 00:00:00 2001
From: Christopher Angelo Phillips <32073428+spiffcs@users.noreply.github.com>
Date: Tue, 2 Nov 2021 15:00:56 -0400
Subject: [PATCH] update readme with private registry section (#610)
---
README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 84 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index d8dee3481..4507fda7a 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
- 
+
[](https://github.com/anchore/syft/actions/workflows/validations.yaml)
@@ -94,7 +94,7 @@ The output format for Syft is configurable as well:
syft packages -o
```
-Where the `format`s available are:
+Where the `formats` available are:
- `json`: Use this to get as much information out of Syft as possible!
- `text`: A row-oriented, human-and-machine-friendly output.
- `cyclonedx`: A XML report conforming to the [CycloneDX 1.2 specification](https://cyclonedx.org/specification/overview/).
@@ -102,6 +102,88 @@ Where the `format`s available are:
- `spdx-json`: A JSON report conforming to the [SPDX 2.2 JSON Schema](https://github.com/spdx/spdx-spec/blob/v2.2/schemas/spdx-schema.json).
- `table`: A columnar summary (default).
+## Private Registry Authentication
+
+### Local Docker Credentials
+When a container runtime is not present, Syft can still utilize credentials configured in common credential sources (such as `~/.docker/config.json`).
+It will pull images from private registries using these credentials. The config file is where your credentials are stored when authenticating with private registries via some command like `docker login`.
+For more information see the `go-containerregistry` [documentation](https://github.com/google/go-containerregistry/tree/main/pkg/authn).
+
+
+An example `config.json` looks something like this:
+```
+// config.json
+{
+ "auths": {
+ "registry.example.com": {
+ "username": "AzureDiamond",
+ "password": "hunter2"
+ }
+ }
+}
+```
+
+You can run the following command as an example. It details the mount/environment configuration a container needs to access a private registry:
+
+`docker run -v ./config.json:/config/config.json -e "DOCKER_CONFIG=/config" anchore/syft:latest `
+
+
+### Docker Credentials in Kubernetes
+The below section shows a simple workflow on how to mount this config file as a secret into a container on kubernetes.
+1. Create a secret. The value of `config.json` is important. It refers to the specification detailed [here](https://github.com/google/go-containerregistry/tree/main/pkg/authn#the-config-file).
+Below this section is the `secret.yaml` file that the pod configuration will consume as a volume.
+The key `config.json` is important. It will end up being the name of the file when mounted into the pod.
+ ```
+ # secret.yaml
+
+ apiVersion: v1
+ kind: Secret
+ metadata:
+ name: registry-config
+ namespace: syft
+ data:
+ config.json:
+ ```
+
+ `kubectl apply -f secret.yaml`
+
+
+2. Create your pod running syft. The env `DOCKER_CONFIG` is important because it advertises where to look for the credential file.
+In the below example, setting `DOCKER_CONFIG=/config` informs syft that credentials can be found at `/config/config.json`.
+This is why we used `config.json` as the key for our secret. When mounted into containers the secrets' key is used as the filename.
+The `volumeMounts` section mounts our secret to `/config`. The `volumes` section names our volume and leverages the secret we created in step one.
+ ```
+ # pod.yaml
+
+ apiVersion: v1
+ kind: Pod
+ spec:
+ containers:
+ - image: anchore/syft:latest
+ name: syft-private-registry-demo
+ env:
+ - name: DOCKER_CONFIG
+ value: /config
+ volumeMounts:
+ - mountPath: /config
+ name: registry-config
+ readOnly: true
+ args:
+ -
+ volumes:
+ - name: registry-config
+ secret:
+ secretName: registry-config
+ ```
+
+ `kubectl apply -f pod.yaml`
+
+
+3. The user can now run `kubectl logs syft-private-registry-demo`. The logs should show the syft analysis for the `` provided in the pod configuration.
+
+Using the above information, users should be able to configure private registry access without having to do so in the `grype` or `syft` configuration files.
+They will also not be dependent on a docker daemon, (or some other runtime software) for registry configuration and access.
+
## Configuration
Configuration search paths: