How CleanStart Builds Container Images from YAML

CleanStart's image construction pipeline turns YAML configurations into verified container images using a declarative, hermetic system. Unlike traditional Dockerfiles that are imperative and sequential, you specify what you want in the image, and the build system determines how to build it.

Key Principles

The pipeline follows three phases. Declaration & Resolution transforms YAML config into verified dependency manifest. Hermetic Compilation builds the image in isolated, network-disconnected environment for both AMD64 and ARM64 architectures in parallel. Quality Gates & Verification subjects the image to 78-test suite covering security, functionality, performance, and compliance.

1. Declarative Configuration

Rather than writing imperative build commands that execute sequentially, CleanStart allows you to declare your image's requirements in YAML format. You specify what you want the image to contain, and the build system figures out how to create it.

YAML configuration specifies name, base language (python), version (3.12), packages (fastapi, psycopg2-binary), and build flags (fips: true, hardening: maximum).

2. Hermetic Compilation

A critical distinction between traditional and CleanStart builds is the timing of dependency resolution. All dependencies are resolved and verified before the build starts. Once resolution completes, the actual build runs completely offline—in network isolation—with all dependencies pre-fetched and cached locally. This prevents the injection of malicious dependencies and ensures reproducibility.

3. Multi-Architecture by Default

Rather than forcing developers to maintain separate build configurations for different architectures, CleanStart generates both AMD64 and ARM64 images from a single configuration. Native compilation on each architecture ensures architecture-specific optimizations and eliminates cross-compilation bugs.

4. Automated Quality Gates

Seventy-eight security, functionality, and performance tests run automatically as part of the build process. If any test fails, the image is not released. This automation prevents defective or insecure images from reaching production.

5. Verification Artifacts

Every image released by CleanStart includes 11 distinct artifact types: SBOMs in multiple formats, cryptographic provenance documents, build logs, test reports, vulnerability assessments, VEX attestations, digital signatures, license inventories, and more. These artifacts collectively prove the security of the image and enable comprehensive audits for regulatory compliance.

How It Works: Three Phases

Phase 1: Declaration and Resolution

The first phase transforms your declarative YAML configuration into a complete, verified dependency manifest. You provide a YAML configuration file that specifies exactly what you want in your image. The Dependency Resolution Engine then executes a comprehensive verification process.

YAML Input specifies name, description, base language (python), version (3.12.1), packages (fastapi, uvicorn, psycopg2-binary, pydantic), build flags (fips: true, hardening: maximum, strip_binaries: true, optimization: O2), and metadata (owner, compliance, documentation).

The engine fetches Python 3.12.1 source from the official CPython repository and verifies the GPG signature. It fetches FastAPI 0.104.1 from PyPI and automatically resolves all transitive dependencies. It verifies the SHA-256 hash of every package against known good values. Finally, it pins the exact versions of all dependencies into a lockfile.

Output is a lockfile with complete dependency graph including all packages, versions, and hashes.

Phase 2: Hermetic Compilation

The second phase takes the verified dependency manifest and builds the actual container image in a completely isolated, network-disconnected environment.

AMD64 Build Process loads Python 3.12.1 source from pre-fetched cache, configures compilation with FIPS support enabled, compiles using all 8 CPU cores in parallel, installs the compiled artifacts, strips unnecessary debug symbols, verifies that security compilation flags were properly applied, installs pip, and installs FastAPI and all transitive dependencies from pre-fetched cache. The output is an OCI-compliant container image: python-fastapi-api:3.12.1-amd64.

ARM64 Build Process (runs in parallel) executes identical steps but compiles for ARM64 native architecture using the ARM64 GCC toolchain, producing the corresponding image: python-fastapi-api:3.12.1-arm64.

Because AMD64 and ARM64 builds execute on separate hardware in parallel, the total build time is not doubled—both complete simultaneously.

Build Artifacts Generated include OCI container image, complete build log transcript, compilation flags metadata, source manifest, and SHA-256 checksum.

Phase 3: Quality Gates and Verification

The third and final phase subjects the newly-built image to rigorous quality assurance before it is considered ready for distribution. A comprehensive 78-test suite executes automatically, covering security, functionality, performance, and compliance aspects. Only images that pass all tests are released.

The test matrix includes Security (25 tests) for vulnerability scanning, FIPS mode validation, cryptographic signature verification, crypto algorithm compliance, and permission/capability checks. Functionality (30 tests) for container entrypoint execution, Python package imports, networking configuration, filesystem operations, and I/O performance. Performance (15 tests) for boot time, peak memory usage, cold start latency, CPU utilization, and horizontal scalability. Compliance (8 tests) for open source license verification, SBOM completeness, SLSA Level 4 validation, and cryptographic signature validation.

Output is a test report (JSON) showing tests run (78), passed (78), failed (0), and coverage percentages for each category.

Artifacts Generated

Upon successful completion of all three phases and all 78 tests, CleanStart generates a comprehensive set of 11 verification artifacts that collectively prove the provenance, security, and compliance status of the image. These artifacts enable downstream tools to make automated security decisions and support comprehensive audits.

1-2. SBOMs (Software Bill of Materials)

The SBOM documents every component in the image. CycloneDX format (JSON/XML) is the OWASP standard for component information. SPDX format (JSON/RDF) is the Linux Foundation standard.

3. SLSA Provenance (v1.0)

SLSA provenance is a cryptographically signed document proving the build process was conducted securely and reproducibly. The document includes the source repository and commit hash, build environment configuration, exact compilation flags used, test results, and a cryptographic timestamp.

4. Build Log

The complete build log is a full transcript of every command executed, every output produced, and every error encountered.

5. Test Report

The test report documents the results of the 78-test suite, performance metrics such as boot time and peak memory usage, and security validation results.

6. Vulnerability Report

The vulnerability report includes CVE scanning results, four-layer detection analysis, and risk scoring and remediation prioritization.

7. VEX Attestation

The VEX attestation provides structured documentation of vulnerability exploitability, specifying for each CVE whether it is exploitable, non-exploitable, or unknown.

8. Cryptographic Signature

The image is digitally signed using an asymmetric signing key, producing a PEM-format signature of the SHA-256 digest.

9. Attestation Bundle

All attestations—the provenance, test results, vulnerability assessments, and VEX statements—are packaged together in a standardized format using in-toto specification.

10. Software Hash

The SHA-256 hash of the final image serves as a content-addressable identifier.

11. License Report

The license report provides a complete inventory of open source licenses present in the image.

Workflow Example

Scenario: Deploy Python FastAPI Microservice

A developer writes a YAML configuration specifying what should be in the image. The developer commits this configuration to Git. When pushed to main branch, CI/CD pipeline automatically triggers. Validation step checks YAML syntax correctness, package version resolvability, and organizational policy enforcement. Dependency Resolution step resolves all transitive dependencies and outputs a lockfile. Build step compiles the image for both AMD64 and ARM64 architectures, runs the 78-test suite, and generates all 11 verification artifacts. Verification step confirms all tests passed, CVEs have no exploitable code paths, licenses comply with policy, and SLSA provenance is valid. Distribution step pushes verified images to the primary registry and mirrors, attaches all 11 verification artifacts, and notifies the team.

At this point, the image is ready to use in production with complete confidence in its provenance and security.

Configuration Reference

Language/Version Options

Supported base languages include python (3.12, 3.11, 3.10, etc.), go (1.21, 1.20, etc.), node (20, 18, 16, etc.), java (21, 17, etc.), rust (1.74, latest), and ruby (3.2, 3.1, 3.0, etc.).

Build Flags

Build flags include fips: true (Enable FIPS compilation), hardening: maximum (apply security hardening), strip_binaries: true (remove debug symbols), optimization: O2 (optimization level), and reproducible: true (ensure determinism).

Dependencies

Packages can pin exact version or specify range. System packages are specified separately.

Integration Points

CI/CD Integration

GitHub Actions uses cleanstart/build-action to build and push images.

Cloud Build (Google Cloud) uses cloud-builders/docker with clnstrt-cli.

GitLab CI uses cleanstart/cli:latest container.

Artifact Storage

Local registry (enterprise) pushes to registry.example.com. Multiple registries (high availability) pushes to multiple registries simultaneously.

Advanced Features

Policy Enforcement

Define policies that images must comply with, specifying no untagged versions, allowed languages, FIPS requirements, max critical CVEs, and license whitelist.

Custom Build Scripts

For advanced use cases, inject custom build steps with pre_build and post_build scripts.

Parameterized Configs

Use templating for reusable configurations with parameter substitution.

Performance and Scale

Build Times

Single image takes 15-25 minutes (including tests and artifacts). Parallel multi-arch (AMD64 + ARM64) takes ~20 minutes (not 40). Batch of 10 images takes 2-3 hours (all in parallel).

Scalability

CleanStart can build 100+ images per day per organization, handle 19,200+ pre-built variants, and use distributed builder nodes for parallel builds.

Next Steps

Configure your first image: YAML Image Configuration, Understand the builder pattern: Builder Pattern Dev-Prod, Multi-architecture support: Multi-Arch Build Strategy, Deep dive into hermetic builds: Hermetic Builds and SLSA, and Start building: Quick Start.

Key Insight

The image construction pipeline removes the friction between "I want an image" and "I have a production-ready, verified, auditable image."

What used to take days (write Dockerfile, build, test, scan, fix CVEs, rebuild) now takes minutes (declare config, run build, get verified image with 11 artifacts).