Sign artifacts

• Integrity of container images and build artifacts: Using a cryptographic signature ensures that container images and other build artifacts are genuine and crafted by the organization. This adds an extra layer of security to the software supply chain, making sure that only authorized and unaltered items are scheduled for execution.
• Traces across workflows: Beyond just verification, the framework offers thorough traceability. Users can trace the roots of container images and build artifacts, navigating through workflows and environments. Complete traceability ensures transparency, enabling organizations to validate the entire lifecycle of their software, from creation to deployment.
• Certificate validity: Endor Labs uses a short-lived certificate with a validity period of 5 minutes to ensure that the build artifact has been signed during this time frame. To further guarantee the signing occurred within the valid window, a timestamp is added alongside the certificate and signature, confirming the signing within the specified time frame.

​

Sign artifacts

​

Sign using GitHub Action

1. Set up authentication to Endor Labs.
   • (Recommended) If you are using GitHub Action keyless authentication, set an authorization policy in Endor Labs to allow your organization or repository to authenticate. See Keyless Authentication for more information.
   • Alternatively, authenticate with a GCP service account setup for keyless authentication from GitHub Actions or an Endor Labs API key added as a repository secret.
2. Checkout your code.
3. Install your build toolchain.
4. Build your code.
5. Sign your artifacts with Endor Labs.

name: Sign artifacts with Endor Labs
on: [push, workflow_dispatch]
jobs:
  ko-publish:
    name: Release ko artifact
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      packages: write
      contents: read
    steps:
      - uses: actions/setup-go@v4
        with:
          go-version: '1.20.x'
      - uses: actions/checkout@v3
      - uses: ko-build/setup-ko@v0.6
      - run: ko build
      - name: Login to the GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Publish
        run: KO_DOCKER_REPO=ghcr.io/endorlabs/hello-sign ko publish --bare github.com/endorlabs/hello-sign
      - name: Get Image Digest to Sign
        run: |
          IMAGE_SHA=$(docker inspect ghcr.io/endorlabs/hello-sign:latest | jq -r '.[].Id')
          SIGNING_TARGET="ghcr.io/endorlabs/hello-sign@$IMAGE_SHA"
          echo ARTIFACT="$SIGNING_TARGET" >> $GITHUB_ENV
      - name: Sign with Endor Labs
        uses: endorlabs/github-action/sign@version
        with:
          namespace: "example"
          artifact_name: ${{ env.ARTIFACT }}

​

Sign using endorctl

endorctl artifact sign --name string --source-repository-ref string --certificate-oidc-issuer string

​

Provenance information in signed artifacts

​

Understand the signing process

• Authentication: Initiates regular authentication and retrieves a token from the OIDC or workflow provider while using an authentication option such as --enable-github-action-token or API keys.
• Key Generation: Generates a public and private key using ECDSA-256.
• Certificate Request: Sends a certificate request to the private Certificate Authority to obtain a short-lived certificate.
• Provenance Inclusion: Incorporates provenance information from the token (if available) or provided with the CLI, adding it as a set of extensions to the certificate using ASN.1 encoding.
• Image Signing: Uses the private key to actively sign the image.
• Certificate Storage: Stores the certificate containing provenance information along with the signature in the database.
• Timestamp: Adds a timestamp of the signing event.

​

View the signed artifacts

1. Sign in to Endor Labs and select Inventory from the left sidebar.
2. Select Artifacts. The list shows signed artifacts with Name, Created, and Last Updated details.
3. Use the search bar to find artifacts by name, description, or tags. You can use the following filters:
   • Artifact Types: Filter by artifact type, for example container image.
   • Created: Filter by when the artifact was created.
4. Select an artifact to see its signed artifact digests in the list and provenance information. The list shows Artifact Digest, Reference, Created, and Last Updated for each digest.
5. Select an artifact digest to open Artifact Digest Details and view the metadata, signature and certificate details, build configuration, and source repository information.

​

Verify artifacts

​

Verify using GitHub Action

name: Verify artifacts with Endor Labs
on: [push, workflow_dispatch]
jobs:
  verify-artifact:
    name: Verify signed artifact
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      packages: read
      contents: read
    steps:
      - uses: actions/checkout@v3
      - name: Verify with Endor Labs
        uses: endorlabs/github-action/verify@version
        with:
          namespace: "example"
          artifact_name: "ghcr.io/endorlabs/hello-sign@sha256:digest"
          certificate_oidc_issuer: "https://token.actions.githubusercontent.com"

​

Verify using endorctl

endorctl artifact verify --name <artifact> --certificate-oidc-issuer <issuer>

​

Understand the verification process

• Authentication: Initiates regular authentication and retrieves a token from the OIDC or workflow provider while using an authentication option such as --enable-github-action-token or API keys.
• Signature Retrieval: Retrieves a signature entry from the database using the artifact name.
  • If the entry is not found, the verification process fails.
• Certificate Authority Check: Checks for a trusted Certificate Authority.
• Image Signature Validation: Validates the image signature using the public key from the certificate.
• Timestamp Validation: Validates that the timestamp in the signature entry is within the certificate’s validity.
• OIDC Issuer Verification: Checks whether the issuer provided matches the contents of the certificate.
• Provenance Verification: Ensures that any provenance information from the CLI matches the ones in the certificate.

​

Revoke the artifact signature

endorctl artifact revoke-signature --name <image> --source-repository-ref "ref"

​

Best practices

• While specifying the artifact name during the signing process, for the container images, adhere to the structure registry.example.com/repository/image@sha256:digest.
• The signing process does not support tags. Ensure that you specify a SHA256 digest with the artifact you are signing to represent a cryptographic hash of the image’s content. This ensures a unique digest is created for every minor alteration in the image.