Feature: Artifact Signing and Verification
Relevant source files
The following files were used as context for generating this wiki page:
The Aldeci project implements a robust artifact signing and verification mechanism to ensure the integrity and authenticity of release artifacts. This feature is a cornerstone of the project's supply chain security strategy, leveraging tools like cosign to create and verify detached signatures. The process is deeply integrated into the CI/CD pipeline, particularly during release events, to automatically sign artifacts and evidence bundles.
This system provides verifiable proof of an artifact's origin and guarantees that it has not been tampered with. It supports SLSA v1 attestations and is a critical component for generating audit-ready evidence bundles. The entire process is configurable through the project's overlay system, allowing signing to be enabled or disabled based on the environment.
Sources: readme_updated.md:79, readme_updated.md:396, readme_updated.md:449-451
Architecture Overview
The signing and verification architecture is composed of shell scripts that wrap cosign commands, a GitHub Actions workflow that orchestrates the process, and Python modules for configuration and testing. The system is designed to be straightforward, relying on standard tools and environment variables for key management.
The general flow involves generating a detached signature for an artifact during a release and attaching it. This signature can then be used by any consumer to verify the artifact's integrity against a public key.
Sources: readme_updated.md:207, readme_updated.md:451
Signing and Verification Flow
This diagram illustrates the high-level process of signing an artifact and subsequently verifying it.
Configuration
Artifact signing is configured within the overlay YAML file (e.g., config/fixops.overlay.yml). The configuration is validated at runtime by the _validate_signing_config function.
Sources: core/configuration.py:163-166
| Key | Type | Description | Default |
|---|---|---|---|
enabled | boolean | Toggles the signing feature on or off. | false |
provider | string | Specifies the signing provider. The only supported value is rsa. | rsa |
key_uri | string | A URI pointing to the public key for verification. | N/A (Required if enabled) |
An example configuration block in the overlay file:
signing:
enabled: true
provider: rsa
key_uri: "file:///path/to/public.key"
Sources: tests/test_overlay_configuration.py:270-275, core/configuration.py:163-176
Signing Process
Artifact signing is primarily executed within the CI/CD pipeline for releases. The release-sign.yml workflow defines a dedicated job for this purpose.
Sources: .github/workflows/release-sign.yml:119
CI/CD Integration
The sign-and-verify job in the release workflow performs the following key steps:
- Setup Cosign: Installs the
cosigntool. - Export Private Key: The
COSIGN_PRIVATE_KEYis retrieved from GitHub secrets and exported as an environment variable. - Sign Artifact: The
scripts/signing/sign-artifact.shscript is called to sign the release artifact (e.g.,dist/fixops.tar.gz). - Verify Artifact: The
scripts/signing/verify-artifact.shscript is immediately called to confirm the generated signature is valid. - Upload Signature: The generated
.sigfile is uploaded as a release asset alongside the artifact.
Sources: .github/workflows/release-sign.yml:128-160
This sequence diagram shows the interaction within the GitHub Actions workflow.
sign-artifact.sh
This shell script is the core utility for creating signatures.
- It expects the path to the artifact as its first argument.
- It uses the
cosign sign-blobcommand to generate a detached signature. - It relies on the
COSIGN_PRIVATE_KEYandCOSIGN_PASSWORDenvironment variables for the signing key and its passphrase. - The output is a new file with a
.sigextension, placed in the same directory as the artifact.
Sources: scripts/signing/sign-artifact.sh
Verification Process
Verification is the process of confirming that an artifact's signature is valid, proving its integrity and authenticity.
verify-artifact.sh
This script is used to verify an artifact's signature.
- It expects three arguments: the path to the artifact, the path to the
.sigfile, and the path to the public key. - It uses the
cosign verify-blobcommand to perform the verification. - The script will exit with a non-zero status code if verification fails.
Sources: scripts/signing/verify-artifact.sh
Testing
The signing and verification functionality is thoroughly tested to ensure its reliability. The tests cover the end-to-end process as well as the underlying cryptographic operations.
Key test scenarios include:
- Round-trip success: An artifact is signed and then successfully verified.
- Tampering failure: Verification fails if the artifact content is altered after signing.
- Signing disabled: The system correctly skips signing when
signing.enabledisfalsein the configuration. - RSA key operations: The underlying RSA key generation and sign/verify round-trip are tested independently.
Sources: tests/test_signing_verify.py:17-37, tests/test_crypto_signing.py:21-31
Related Components
Evidence Bundling
The signing mechanism is also used to ensure the integrity of evidence bundles. The evidence/packager.py module is responsible for assembling signed ZIP bundles that contain a MANIFEST.yaml. This ensures that the collection of audit artifacts is also tamper-proof.
Sources: readme_updated.md:561, evidence/packager.py
Environment Variables
The signing scripts rely on a set of environment variables for their operation.
| Variable | Used By | Description |
|---|---|---|
COSIGN_PRIVATE_KEY | sign-artifact.sh | The private key used for signing artifacts. |
COSIGN_PASSWORD | sign-artifact.sh | The passphrase for the private key. |
Sources: scripts/signing/sign-artifact.sh, .github/workflows/release-sign.yml:140-141
Summary
The Artifact Signing and Verification feature is a critical security control in the Aldeci project. By integrating cosign into the CI/CD pipeline and providing simple, robust scripts for the signing and verification operations, the project ensures that all release artifacts and evidence bundles are authentic and have not been tampered with. This provides a strong foundation for supply chain security and auditability.
Sources: readme_updated.md:449, readme_updated.md:941