Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides a technical overview of the deployment process within the Aldeci project. The system uses a structured, stage-based approach to execute deployment-related tasks, which are defined in declarative scenario files. The core of this process is the StageRunner, a component responsible for orchestrating the execution of each stage, processing inputs, and generating auditable outputs like evidence bundles.
The deployment process is not just about pushing code; it integrates security and compliance checks directly into the workflow. This includes analyzing infrastructure-as-code (IaC) manifests for security posture, running risk assessments, and bundling all relevant artifacts into a signed evidence package for auditing and verification.
Deployment Scenarios
Deployment workflows are defined as YAML-based scenarios located in the scenarios/deploy/ directory. These files specify the inputs, a sequence of commands to execute, and expected outcomes, making the deployment process testable and repeatable.
Sources: scenarios/deploy/deploy_0225.yaml, scenarios/deploy/deploy_0176.yaml, scenarios/deploy/deploy_0103.yaml, scenarios/deploy/deploy_0180.yaml
Scenario Structure
Each deployment scenario file contains the following key sections:
| Section | Description |
|---|---|
id | A unique identifier for the scenario (e.g., deploy_0225). |
stage | Specifies the lifecycle stage, which is deploy for these scenarios. |
description | A brief explanation of the scenario's purpose. |
tags | Metadata tags for categorization, such as epss score and topology. |
inputs | Defines the input artifacts required for the scenario, such as SBOM and SARIF files. |
commands | A list of commands to be executed in sequence to perform the deployment and associated tasks. |
expected | The expected result of the scenario run, typically an exit_code of 0 for success. |
invariants | A list of conditions that must hold true for the scenario to be considered valid, such as manifest_integrity and idempotence. |
Sources: scenarios/deploy/deploy_0225.yaml:1-49
Deployment Commands
The commands section orchestrates the entire deployment workflow. The following diagram illustrates the typical command flow defined in a deployment scenario.
This diagram shows the sequence of commands executed during a typical deployment scenario.
Sources: scenarios/deploy/deploy_0225.yaml:12-44
The table below details the purpose of each command.
| Command | Description |
|---|---|
ingest sbom | Normalizes and processes the input SBOM file, preparing it for subsequent analysis. |
risk score | Calculates a risk score based on the normalized SBOM, EPSS data, and KEV feeds. |
graph lineage | Traces the lineage of the deployment artifact by linking it to the SBOM and risk report within the project's knowledge graph. |
evidence bundle | Collects all relevant artifacts (SBOM, risk reports, provenance, etc.) into a single, signed ZIP file for auditing. This is a key feature mentioned in the project's documentation. |
gate | Evaluates the generated artifacts against a defined policy to make a go/no-go decision on the deployment. |
Sources: scenarios/deploy/deploy_0225.yaml:12-44, artifacts/upstream_doc_index.json
Stage Runner
The StageRunner class is the engine that drives the execution of all SSDLC stages, including deployment. It is responsible for handling I/O, processing inputs for a given stage, generating canonical outputs, and managing the creation of evidence bundles.
Sources: core/stage_runner.py:61-574
Core Components
The StageRunner interacts with several key components and data structures.
This diagram shows the StageRunner class and the StageSummary dataclass it returns.
Sources: core/stage_runner.py:61-574, artifacts/upstream_symbol_index.json
The deploy Stage
When run_stage is called with stage='deploy', the _process_deploy method is invoked. This method is specifically designed to analyze infrastructure manifests.
The process flow for the deploy stage is as follows:
- Load Manifest: The input file (e.g., a Terraform plan JSON or Kubernetes YAML) is loaded.
- Analyze Posture: The manifest is parsed to identify security-relevant configurations. The system specifically looks for public S3 buckets and TLS policies.
- Extract Digests: If a SLSA provenance file is available from a previous stage, it extracts artifact digests (e.g.,
sha256). - Generate Control Evidence: Based on the posture analysis, it generates evidence for security controls, marking them as
passorfail. - Calculate Risk Score: A
deploy_risk_scoreis calculated based on the findings from the posture analysis. - Generate Output: A
deploy.manifest.jsonfile is created containing the posture analysis, control evidence, and risk score.
Sources: core/stage_runner.py:349-386
This diagram illustrates the internal logic of the _process_deploy method.
This flowchart details the steps within the _process_deploy function in StageRunner.
Sources: core/stage_runner.py:349-386
Posture Analysis
The _analyse_posture helper function is responsible for inspecting the deployment manifest. It checks for common misconfigurations that could introduce security risks.
| Check | Description |
|---|---|
public_buckets | Identifies S3 buckets with public-read ACLs by inspecting aws_s3_bucket resources in the manifest. |
tls_policy | Checks for the presence of an SSL/TLS policy in load balancer listeners or Ingress resources. |
Sources: core/stage_runner.py:448-489
Control Evidence
The results of the posture analysis are mapped to specific compliance controls. This creates a clear, auditable record of whether the deployment meets predefined security requirements.
| Control | Condition for "pass" |
|---|---|
ISO27001:AC-2 | No public S3 buckets are found (public_buckets is empty). |
ISO27001:AC-1 | A TLS policy is defined (tls_policy is not null). |
Sources: core/stage_runner.py:491-509
Evidence Bundling
A critical output of the Aldeci workflow is the evidence bundle, which is finalized during the decision stage but aggregates artifacts from all preceding stages, including deploy. The _write_evidence_bundle method creates a ZIP archive containing all stage output JSON files.
A manifest.json is also generated and added to the bundle, containing SHA256 hashes of all included documents to ensure their integrity. This bundling process is a key part of providing auditable, tamper-proof deployment records.
Sources: core/stage_runner.py:539-552, artifacts/upstream_doc_index.json
Conclusion
The deployment system in Aldeci is a robust, automated process orchestrated by the StageRunner and defined through declarative scenarios. By integrating security posture analysis, risk scoring, and evidence bundling directly into the deployment workflow, the system ensures that every deployment is not only functional but also secure and compliant. The use of distinct stages and auditable outputs provides strong guarantees and traceability for auditors and developers alike.