###### tags: `notary`

# Notary v2 Alpha 2 Goals

[Notary v2, Alpha 1 enabled](https://notaryproject.dev/blog/2021/announcing-notation-alpha1/#notation-alpha-1-features):

- [x] Offline signature creation
- [x] Signatures attesting to authenticity and/or certification
- [x] Maintain the original artifact digest and collection of associated tags, supporting existing dev through deployment workflows
- [x] Multiple signatures per artifact, enabling the originating vendor signature, public registry certification and user/environment signatures
- [x] Signature persistance within an OCI distribution-spec based registry, with oras artifacts spec enhancements
- [x] Air-gapped environments, where the originating registry of content is not accessible
- [x] Artifact and signature copying within and across OCI distribution-spec based registries, with oras artifacts spec enhancements
- [x] Verification of signatures, through a configuration based policy

In Alpha 2, we'll start enabling more of the end to end experiences, including

- [ ] Key Management Services for CA issued certificates
- [ ] notation sign, files and/or directories (`notation sign --file sbom.json:application/json --subject $IMAGE --artifact-type sbom/example`)

To enable the end to end experiences, additional CLIs updates will be explored

- [ ] `oras copy $SOURCE $TARGET`, including support for source and target authentication
- [ ] `oras tag-update $IMAGE_DIGEST $BUILD_ID` to support updating a tag to a new digest, after the supply chain graph of artifacts are established
- [ ] `docker`, `buildkit` or `containderd` for push by digest

## Alpha 2 Experience

In Alpha.2, the Notary v2 experiences will start to enable end to end experiences, identifying opportunities to improve the UX, or gaps in the experience when applied to real-world examples.

The experience will cover:

- [ ] Signing and validating within a VNet
- [ ] Validations during build, including the base image validation
- [ ] Signing in the build environment, within a VNet
- [ ] Policy Management

Not covered in Alpha 2
- [ ] Key revocation
- [ ] TSA validations

### Build Stage

Wabbit networks builds their `net-monitor` container image on an ephemeral VM, within a private network. Each build resets the build environment to a clean state.

The private network has access to their private registry where the base images are secured, the private package feeds required for build and a cloud provider key vault management service for verification and signing.

#### Locally build the artifacts to be scanned

1. The build is initiated, where `notation` validates the base image, referenced in the docker file, is signed by the wabbit-networks key.
1. An SBOM is created, based on the content that went into the build.
- For the purposes of notary validation, a simple SBOM is created:
- `echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json`
1. The image is scanned for vulnerabilities with a local scanning solution like `docker scan`, using snyk.

#### Sign the artifacts

With a successful build, SBOM creation and scan results that pass, the artifacts are ready to be signed and pushed to the private registry. All artifacts are signed with the wabbit-networks private key, stored in a key management solution.

1. Push the container image as a digest reference. A *tag update* is deferred.
- The `docker` cli doesn't support digest only push today, but we may look at buildkit or containerd.
- While the push digest only scenario isn't a notation client responsibility, it is core to the e2e scenario that needs tracking.
2. Sign the image, which can be done directly within the registry as the digest is new, without an assigned tag _yet_.
3. Push and sign the SBOM.
- Alpha.1 enables the flow with the following steps:

      # push the sbom
      oras push $REPO \
        --artifact-type 'sbom/example' \
        --subject $IMAGE \
        -u $NOTATION_USERNAME -p $NOTATION_PASSWORD \
        ./sbom.json:application/json
      # Capture the digest
      SBOM_DIGEST=$(oras discover -o json \
                      --artifact-type sbom/example \
                      -u $NOTATION_USERNAME -p $NOTATION_PASSWORD \
                      $IMAGE | jq -r ".references[0].digest")
      # sign the new digest
      notation sign $REPO@$SBOM_DIGEST

- In Alpha.2, this could be done with a cli similar to: `notation sign --file sbom.json:application/json --subject $IMAGE --artifact-type sbom/example`
4. Push and sign the scan results. (same as above)
- This could be done with a cli similar to: `notation sign --file scan-results.json --subject $IMAGE`
5. Apply a tag to the image digest, enabling registry notifications to clients monitoring for a deployment.
- This may be done with the `oras` client: `oras tag-update $IMAGE_DIGEST $BUILD_ID`

### Deploy Stage

Deployment is gated upon a few standard criteria:

- The artifacts are signed with a valid key
- The SBOM contains required packages, and doesn't contain blocked packages
- A scan was done within _ days, and has no critical vulnerabilities that are blocked from deployment

There may be others, however these represent enough complexity to validate notation is meeting the artifact promotion goals.

Upon successful validation, the image and related artifacts are signed and promoted to the production registry.

1. Validate the image(s) being deployed are signed with keys that are permitted to be deployed.
1. The SBOM contains required packages, and doesn't contain blocked packages
- The notation requirement is related to integration with an SBOM tool to validate which SBOM should be used to validate the image being deployed, or limit the SBOM evaluation to those signed by trusted entities.
1. A scan was done within _ days, by a trusted entity, and has no critical vulnerabilities that are blocked from deployment
- A lack of a valid scan result can simply trigger a new scan, with a new signature.

With the above graph validated, the artifacts are signed with the production key and copied to the production registry.

1. Sign the image with the production key
1. Sign the SBOM with the production key
1. Sign the scan results with a production key
1. Copy the artifacts to the production registry
- Copy can be done with `oras copy $SOURCE $TARGET`
- **Issue:** [ORAS Copy to support source and destination authentication]()

### k8s Admission Controller

The above deploy step validates the SBOM and signature are current. Security is always about multiple lines of defense.

In a kubernetes environment, admission controllers gate what may be deployed.

The admission controller may not validate SBOMs, but it should validate images are only deployed if they are signed by a trusted entity.

1. ...

## TODO
- [ ] ! TODO: define VNet