Dalec

Dalec provides a structured assurance case designed to meet OpenSSF Best Practices Silver standards. This document outlines how Dalec's release process mitigates supply-chain risks by mapping high-level security claims to specific evidence (such as CI workflows, governance policies, and architectural designs).

Key Security Mitigations

• Declarative Spec Validation: Ensures build specifications are valid.
• Sandboxed Execution: Uses BuildKit's sandboxing with clearly defined mounts to isolate build processes.
• Artifact Integrity: Official release artifacts include signatures and SBOM/provenance outputs.
• Automated Testing: Specs include tests that are executed via the Dalec test runner.
• Continuous Monitoring: Uses Dependabot, GitHub Dependency Review, and Snyk to monitor and triage dependency vulnerabilities.

Dalec is a Docker Buildkit frontend that translates a YAML specification into build instructions for creating packages (such as RPMs or DEBs) and container images. It requires only Docker to run.

Dalec builds follow a three-stage lifecycle:

1. Package Build: Checks out sources and executes defined build steps.
2. Package Test: Installs and validates the package in a clean environment.
3. Create Container (optional): Installs the resulting package(s) into a scratch image to produce a container image.

You can verify the presence and metadata of files within the container using the files key under a test case.

Available file checks include:

• Existence: Simply listing a path under files checks if it exists.
• Non-existence: Use not_exist: true to assert a file is absent.
• Directory check: Use is_dir: true to assert a path is a directory.
• Permissions: Use the permissions key (e.g., 0644) to check file mode.
• Symlinks: Use link_target to verify the destination of a symbolic link.

tests:
  - name: My Test case
    files:
      /usr/bin/foo: # Checks existence
      /some/nonexistent/path:
        not_exist: true
      /some/path:
        is_dir: true
      /etc/foo.conf:
        permissions: 0644
      /some/symlink:
        link_target: /expected/target

The image field is an object in the DALEC specification used to customize the properties of the produced container image. Most fields (except base, bases, and post) are merged with the configured or default base image settings.

Supported properties include:

• minimization_profile: Optional post-install minimization policy.
• labels: Optional key-value pairs for image labels.
• env: Optional environment variables.
• entrypoint: Optional entrypoint command.
• cmd: Optional command.
• workdir: Optional working directory.
• user: Optional user/group configuration.
• stop_signal: Optional signal for graceful container shutdown.
• volumes: Optional volume definitions.

If you need a worker image with additional tools not present in the base image, you can target the worker specifically using <target>/worker (e.g., --target=azlinux3/worker).

To provide a custom worker image, use the Docker buildx --build-context flag. For the azlinux3 target, DALEC looks for a named context called dalec-azlinux3-worker. If you provide a context for the actual base image used by azlinux3, the worker context is ignored.

Example using a custom worker context:

docker buildx build --build-context dalec-azlinux3-worker=<new ref> ...

For all source types, you can apply the following top-level configuration keys to control how the source is processed:

• path: The specific path to extract from the source type.
• includes: A list of glob patterns to include from the source.
• excludes: A list of glob patterns to exclude from the source.
• generate: Used to trigger a generator (e.g., gomod, pip).

Example of configuring a context source with path filtering:

sources:
  someSource:
    path: path/in/source
    includes:
      - "*.txt"
    excludes:
      - "secret.txt"
    context: {}

Dalec uses two distinct testing tiers:

1. Unit Tests

• Location: Distributed throughout the codebase (e.g., spec_test.go).
• Characteristics: Fast (< 1 minute), no Docker/network required, tests functions in isolation.
• Execution: Use go test --test.short ./... or make test.

2. Integration Tests

• Location: The test/ directory.
• Characteristics: Slow (30-60+ minutes), requires Docker with BuildKit, tests end-to-end scenarios (Linux/Windows packages/containers).
• Framework: Uses a custom framework in test/testenv/ to manage Docker contexts and parallel execution.

# Run all unit tests
go test --test.short ./...