Key Concepts

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• core/stage_runner.py
• artifacts/upstream_symbol_index.json
• artifacts/upstream_doc_index.json
• apps/api/pipeline.py
• apps/api/normalizers.py

The Aldeci project, also referred to as FixOps, is a contextual risk and evidence platform. Its primary function is to ingest various security and development artifacts, such as Software Bills of Materials (SBOMs) and Static Analysis Results Interchange Format (SARIF) files, and transform them into actionable intelligence. This includes contextual risk assessments, compliance evidence, and automation manifests. The system is designed with a dual interface, offering both a FastAPI-based web service for push-style uploads and a command-line interface (CLI) that provides functional parity for local or air-gapped workflows.

At its core, Aldeci operates on a modular, overlay-driven pipeline. This architecture allows for flexible configuration of guardrails, automation, and evidence retention policies to suit different operational modes, such as "demo" or "enterprise," without requiring code changes. Key outputs include guardrail verdicts, context summaries, auditable evidence bundles, and risk scoring enriched with external threat intelligence feeds like EPSS and CISA KEV.

Sources: README.md:3-9

Core Architecture

The Aldeci platform is composed of several key services and components that work together to process security artifacts and generate insights. The architecture is designed to be modular, with distinct services for ingestion, processing, and data management.

Sources: README.md:88-99

The diagram below illustrates the high-level architectural flow of the system.

Sources: README.md:102-108, artifacts/upstream_symbol_index.json

Key Components

Component	Description	Relevant Files
FastAPI Service	Provides RESTful endpoints for ingesting artifacts (e.g., SBOM, SARIF) and running the processing pipeline. Enforces API key authentication and content validation.	apps/api/app.py, apps/api/routes/
CLI Runner	Offers a command-line interface with parity to the API, allowing for local execution of the pipeline stages.	core/cli.py, apps/fixops_cli/__main__.py
Pipeline Orchestrator	The central component that correlates inputs, executes modular stages, evaluates guardrails, and assembles the final output.	apps/api/pipeline.py
Stage Runner	Manages the execution of individual SSDLC stages, handling canonical input/output and persistence.	core/stage_runner.py
Normalizers	A set of classes responsible for parsing and standardizing various input formats (SBOM, SARIF, VEX, etc.) into a consistent internal data model.	apps/api/normalizers.py
Risk Engine	Scores risk by combining normalized SBOMs with external threat intelligence feeds like EPSS and CISA KEV.	risk/scoring.py, risk/feeds/
Provenance & Graph Service	Generates SLSA attestations and builds a queryable knowledge graph linking commits, artifacts, components, and CVEs.	services/provenance/attestation.py, services/graph/graph.py
Evidence Hub	Packages all relevant artifacts, manifests, and attestations into a compressed, optionally signed and encrypted, evidence bundle for auditing.	core/evidence.py, evidence/packager.py

Sources: README.md:75-81, 253-254, artifacts/upstream_symbol_index.json

The SSDLC Pipeline and Stage Runner

A central concept in Aldeci is the Secure Software Development Lifecycle (SSDLC) pipeline, which is executed by the StageRunner class. This class coordinates the processing of artifacts through a series of distinct stages, each corresponding to a phase of the SDLC.

The StageRunner is responsible for:

• Resolving application and run identities.
• Managing canonical input and output file naming for each stage.
• Invoking the correct processing logic for a given stage (_process_<stage>).
• Handling the persistence of inputs, outputs, and signed manifests.
• Creating a final evidence bundle at the decision stage.

Sources: core/stage_runner.py:65-70, 110-141

Pipeline Stages

The pipeline is composed of several stages, each with defined inputs and outputs. The StageRunner class defines these mappings internally.

Sources: core/stage_runner.py:73-91

The table below details each stage's standard input and output.

Stage	Input Filename	Output Filename	Description
requirements	requirements-input.csv	requirements.json	Parses requirements, assigns unique IDs, and establishes an SSVC anchor based on context like PII and internet-facing status.
design	design-input.json	design.manifest.json	Processes design context, allocates application and component IDs, and calculates a design-time risk score.
build	sbom.json	build.report.json	Normalizes an SBOM, identifies components with known risks (e.g., log4j), and calculates a build risk score.
test	scanner.sarif	test.report.json	Ingests SARIF reports, summarizes finding severities, and calculates a test risk score based on findings and code coverage.
deploy	tfplan.json	deploy.manifest.json	Analyzes infrastructure-as-code plans (e.g., Terraform) to assess posture, checking for issues like public S3 buckets.
operate	ops-telemetry.json	operate.snapshot.json	Blends operational telemetry with threat intelligence feeds (KEV, EPSS) to calculate operational risk and pressure.
decision	decision-input.json	decision.json	Synthesizes outputs from all prior stages, generates a final verdict (ALLOW/DEFER), and creates a comprehensive evidence bundle.

Sources: core/stage_runner.py:73-91, 185-442

Evidence and Provenance

A key capability of Aldeci is the generation of auditable evidence and verifiable provenance for all build and release artifacts. This is achieved through two primary mechanisms: Evidence Bundles and SLSA Provenance Attestations.

Evidence Bundles

At the conclusion of the decision stage, the StageRunner creates a evidence_bundle.zip file. This bundle is a self-contained archive that includes:

• The JSON output from each pipeline stage (requirements.json, build.report.json, etc.).
• A manifest.json file containing SHA-256 hashes of all included documents.

This bundle serves as a comprehensive, immutable record for a given run, which is critical for audits and compliance. The system also supports signing the manifest using cosign and encrypting the bundle if configured in the overlay.

Sources: core/stage_runner.py:421-442, 461-480, README.md:79, 228

The following diagram shows the process of creating an evidence bundle.

Sources: core/stage_runner.py:421-442, 461-480

Provenance Attestations (SLSA)

Aldeci integrates the principles of Supply-chain Levels for Software Artifacts (SLSA) to generate provenance. This involves:

• Creating SLSA v1-compliant attestation statements in JSON format.
• Recording metadata about the build process, source materials, and artifact digests (SHA-256).
• Using cosign to sign these attestations, creating a verifiable link between a released artifact and its origins.

This functionality is primarily managed by the services/provenance module and is orchestrated in CI/CD via GitHub Actions workflows like provenance.yml and release-sign.yml.

Sources: README.md:79, 443, artifacts/upstream_doc_index.json

Risk Scoring

Aldeci implements a "risk-first" posture by enriching security data with external threat intelligence. The risk scoring engine, located in risk/scoring.py, combines information from the normalized SBOM with data from two key feeds:

1. CISA KEV (Known Exploited Vulnerabilities) Catalog: Identifies vulnerabilities that are actively being exploited in the wild.
2. EPSS (Exploit Prediction Scoring System): Provides a probability score (from 0 to 1) indicating the likelihood of a vulnerability being exploited.

During the operate stage, the StageRunner loads these feeds and cross-references them with components from the build report to calculate an operate_risk_score and flag kev_hits. This allows the system to prioritize findings based not just on their theoretical severity but on their real-world exploitability.

Sources: README.md:80, core/stage_runner.py:382-420, artifacts/upstream_doc_index.json

Key Data Artifacts

The Aldeci pipeline is designed to ingest a variety of standard security and development artifacts. The InputNormalizer class is responsible for parsing these different formats into a consistent internal representation.

Sources: apps/api/normalizers.py:61-68

Artifact Type	Description	Relevant Modules
SBOM	Software Bill of Materials (CycloneDX, SPDX). Used to identify all software components and their dependencies.	apps.api.normalizers.NormalizedSBOM
SARIF	Static Analysis Results Interchange Format. Used to ingest findings from static analysis (SAST) tools.	apps.api.normalizers.NormalizedSARIF
VEX	Vulnerability Exploitability eXchange. Provides assertions about the status of vulnerabilities (e.g., not_affected).	apps.api.normalizers.NormalizedVEX
CVE Feeds	Lists of Common Vulnerabilities and Exposures. Used for vulnerability matching.	apps.api.normalizers.NormalizedCVEFeed
CNAPP	Cloud Native Application Protection Platform data. Provides findings related to cloud assets.	apps.api.normalizers.NormalizedCNAPP
Business Context	User-provided data (e.g., from a CSV) that describes the business impact and environment of an application.	apps.api.normalizers.NormalizedBusinessContext

Sources: apps/api/normalizers.py, README.md:75