Execution Model: Stages and Scenarios
Relevant source files
The following files were used as context for generating this wiki page:
The Aldeci execution model is built upon two core concepts: Stages and Scenarios. This model provides a structured, repeatable, and configurable way to process security artifacts, evaluate risk, and generate compliance evidence across the software development lifecycle (SDLC). It is the backbone for the project's CLI, API, and automated testing harnesses.
Stages represent distinct phases of the SDLC, each designed to process a specific type of input artifact and produce a canonical JSON output. Scenarios are declarative YAML configurations that orchestrate the execution of these stages, defining command chains, inputs, and expected outcomes. This allows for the creation of complex, automated workflows for simulation, regression testing, and CI/CD integration.
Core Concepts
Stages
Stages are the fundamental processing units in the execution model. Each stage corresponds to a phase in the SDLC and has a defined input artifact and output report.
The following stages are defined in the system:
| Stage | Input Filename | Output Filename | Description |
|---|---|---|---|
requirements | requirements-input.csv | requirements.json | Parses CSV/JSON requirements, mints IDs, and applies SSVC anchoring. |
design | design-input.json | design.manifest.json | Processes application design context, allocates IDs, and calculates a design risk score. |
build | sbom.json | build.report.json | Normalizes an SBOM, flags risky components (e.g., log4j), and calculates a build risk score. |
test | scanner.sarif | test.report.json | Ingests SARIF reports, analyzes findings, and calculates a test risk score. |
deploy | tfplan.json | deploy.manifest.json | Analyzes infrastructure-as-code plans (Terraform/Kubernetes) for posture and guardrail violations. |
operate | ops-telemetry.json | operate.snapshot.json | Blends operational telemetry with exploit intelligence feeds (KEV/EPSS) to compute operational risk. |
decision | decision-input.json | decision.json | Synthesizes all prior stage outputs into an explainable verdict and generates a signed evidence bundle. |
Sources: core/stage_runner.py:90-104, core/stage_runner.py:240-569, tools/scenario/generate.py:27
Scenarios
Scenarios are YAML files that define a specific execution workflow. They are used extensively for testing and simulation. A scenario specifies the stage, inputs, a sequence of commands to run, and expected outcomes.
This diagram illustrates the structure of a scenario.
Sources: tools/scenario/generate.py:168-188
The StageRunner Class
The StageRunner class is the central component responsible for executing a single stage. It coordinates all I/O, processes the input artifact, generates the canonical output, and handles artifact signing and verification.
Sources: core/stage_runner.py:86, artifacts/upstream_symbol_index.json
Class Structure
This diagram shows the StageRunner class and its main run_stage method, which returns a StageSummary object.
Sources: core/stage_runner.py:68-84, core/stage_runner.py:86-118
run_stage Execution Flow
The run_stage method is the entry point for all stage executions. It handles identity resolution, context management, input/output operations, and invoking the correct processor for the given stage.
This flowchart shows the logical steps inside the run_stage method, from resolving application identity to returning a summary of the execution.
Sources: core/stage_runner.py:121-238
Stage Processing Logic
Each stage has a dedicated _process_<stage> method within StageRunner that contains its unique business logic.
_process_build
This method processes an SBOM to analyze dependencies and assess build-level risk.
The build stage normalizes an SBOM, identifies components matching a predefined risk list (like log4j), and calculates a risk score.
Sources: core/stage_runner.py:303-340
_process_decision
The decision stage is the final step, synthesizing all previous stage outputs to make a final verdict and produce an audit-ready evidence bundle.
This diagram shows how the decision stage aggregates data from other stages to produce a verdict and a comprehensive evidence bundle.
Sources: core/stage_runner.py:511-569
The evidence bundle is a key artifact, containing all stage outputs and a manifest file, which can be optionally signed.
Sources: core/stage_runner.py:557-569, artifacts/upstream_doc_index.json
Scenario Generation and Execution
Scenarios are automatically generated to create a large corpus for end-to-end testing and simulation.
Generation Process
The tools/scenario/generate.py script synthesizes scenarios based on a combination of templates, topologies, and other variables.
This process generates hundreds of scenario files and a catalog.json to index them, forming a comprehensive test matrix.
Sources: tools/scenario/generate.py:261-278
A scenario template includes:
- topology: The structure of the command chain (e.g.,
linear,diamond). - tags: Metadata for filtering and classification (e.g.,
epss:high). - inputs: Pointers to artifact files.
- command_chain: A list of commands to execute (e.g.,
ingest sbom,risk score). - invariants: Checks to perform after execution (e.g.,
kev_policy).
Sources: tools/scenario/generate.py:198-232
Handling Failures: The Fixloop
When a scenario fails, the fixloop process provides a structured workflow for triaging and fixing the underlying bug.
Triage and Fix Workflow
The tools/fixloop/triage_and_fix.py script automates the initial steps of the fixloop.
This sequence shows how a developer uses the script to create a dedicated git branch, a new regression test, a patch skeleton, and a markdown report to guide the fixing process.
Sources: tools/fixloop/triage_and_fix.py:85-96
Conclusion
The execution model, with its foundation of Stages and Scenarios, is a cornerstone of the Aldeci project. It provides a robust and highly configurable system for processing security data through a simulated SDLC. The StageRunner ensures consistent execution, while the scenario generation engine provides a vast testbed for ensuring correctness and stability. The integrated fixloop workflow further demonstrates how this model is deeply embedded in the project's development and quality assurance processes. This architecture enables reliable automation, comprehensive testing, and auditable evidence generation.