Welcome to Aldeci

Relevant source files

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

• README.md
• artifacts/upstream_symbol_index.json
• artifacts/upstream_doc_index.json
• tools/docgen/api_cli_map.py
• core/cli.py
• readme_updated.md

Aldeci is a contextual risk and evidence platform designed to transform raw security artifacts into actionable insights. It unifies Software Bill of Materials (SBOM) intelligence, exploit scoring, and provenance evidence into a cohesive DevSecOps workflow. The system provides both a FastAPI service for push-style data ingestion and a command-line interface (CLI) with feature parity, allowing for flexible integration into local development and CI/CD pipelines.

The core of Aldeci is an overlay-driven pipeline that processes security data (such as SBOMs, SARIF reports, and CVE feeds) to produce guardrail verdicts, contextual summaries, and auditable evidence bundles. It aims to reduce audit preparation time, prioritize remediation efforts using real-world exploit data (EPSS/KEV), and provide verifiable supply-chain provenance through SLSA attestations and reproducible build checks.

Sources: README.md:3-6, readme_updated.md:65-71

Architecture Overview

Aldeci is built around a modular architecture that separates data ingestion, processing, and output generation. Users can interact with the system via a FastAPI application or a Python CLI. Both interfaces feed security artifacts into a central pipeline orchestrator, which processes the data through a series of configurable modules.

The system's behavior is governed by YAML overlay files, which define guardrails, automation destinations, and evidence retention policies. This allows the platform to switch between different operational modes (e.g., demo vs. enterprise) without code changes. Outputs include JSON reports, signed evidence bundles, and observability data.

Sources: README.md:124-127, readme_updated.md:65-71

High-Level Data Flow

The following diagram illustrates the general data flow from input artifacts to final outputs.

This diagram shows how various security artifacts are ingested via the API or CLI, processed by the core engine, and transformed into actionable outputs.

Sources: README.md:86-106, readme_updated.md:151-170

Core Features

Aldeci's functionality is organized into several key features that address different aspects of the software supply chain security lifecycle.

Sources: artifacts/upstream_doc_index.json

SBOM Normalization & Quality Scoring

This feature standardizes SBOMs from various generators (like CycloneDX and SPDX) into a deterministic format. This ensures that downstream services for risk, evidence, and compliance consume consistent data. The system also generates quality reports, including metrics on component coverage and license information, which can be output as HTML for review.

• Key Modules: lib4sbom/normalizer.py, cli/fixops_sbom.py
• Functionality: Merges SBOMs, deduplicates components, computes quality metrics.
• Output: Normalized JSON SBOM (artifacts/sbom/normalized.json) and an HTML quality report.

Sources: readme_updated.md:293-299, tests/test_sbom_quality.py

Risk Scoring (FixOpsRisk)

The risk scoring engine prioritizes vulnerabilities by blending multiple data points:

• Exploit Probability: Uses the Exploit Prediction Scoring System (EPSS).
• Known Exploitation: Incorporates CISA's Known Exploited Vulnerabilities (KEV) catalog.
• Version Lag: Calculates the age of a component relative to its latest version.
• Exposure: Considers contextual flags indicating how a component is used.

The engine produces a composite risk score for each component and CVE, which is used for pipeline gating and prioritization.

• Key Modules: risk/scoring.py, risk/feeds/
• Functionality: Ingests EPSS/KEV feeds, joins them with a normalized SBOM, and calculates a weighted risk score.

Sources: readme_updated.md:356-360, artifacts/upstream_doc_index.json

Provenance & Signing

Aldeci provides verifiable build traceability using SLSA v1 attestations and cosign signatures. This feature ensures that every release artifact is anchored to verifiable supply-chain evidence.

• Key Modules: services/provenance/attestation.py, scripts/signing/
• Functionality: Generates and verifies SLSA provenance statements, and signs artifacts and evidence bundles.
• Output: SLSA JSON attestations and .sig signature files.

Sources: readme_updated.md:449-452, artifacts/upstream_doc_index.json

Provenance Graph Service

This service provides a queryable knowledge graph that links commits, CI jobs, artifacts, SBOM components, and CVEs. It is designed to accelerate investigations by allowing users to trace lineage, identify KEV regressions, and detect version downgrades across releases. The graph is stored in a SQLite database and can be queried via the API.

• Key Modules: services/graph/graph.py, backend/api/graph/router.py
• Functionality: Builds a graph from git metadata, attestations, and SBOMs. Exposes queries for lineage, KEV exposure, and anomalies.

Sources: readme_updated.md:476-481, artifacts/upstream_symbol_index.json

Evidence Bundles & CI Agent

This feature collapses compliance evidence collection into a single command. The CI agent (fixops-ci) aggregates outputs from other stages (SBOM, risk, provenance) and packages them into a signed ZIP bundle. The bundle includes a MANIFEST.yaml file that is signed to ensure integrity. These bundles are designed to be handed off to auditors.

• Key Modules: evidence/packager.py, cli/fixops_ci.py
• Functionality: Collects artifacts, validates them against policies, signs a manifest, and creates a compressed archive.

Sources: readme_updated.md:558-563, readme_updated.md:756-759

Capabilities: API and CLI Mapping

Aldeci exposes its core capabilities through both a FastAPI backend and a parallel CLI. The tools/docgen/api_cli_map.py script defines this mapping, ensuring feature parity between interfaces.

Sources: tools/docgen/api_cli_map.py

Interaction Flow

The following diagram shows the typical interaction flow when a user invokes a capability, either through the CLI in local mode or via the SDK targeting the remote API.

This sequence illustrates how the CLI can either execute handlers directly for local processing or use the Python SDK to communicate with the remote FastAPI server.

Sources: tools/docgen/api_cli_map.py:221-267

Capability Matrix

The table below, derived from the project's execution registry, maps high-level capabilities to their corresponding CLI commands, API endpoints, and underlying service implementations.

Capability	CLI Command	API Route	FastAPI Handler	Core Services
evidence.bundle	aldecI evidence bundle	GET /api/v1/evidence/{release}	backend.api.evidence.router.get_bundle	evidence/packager.py
gate.check	aldecI gate check	POST /api/v1/gate/check	backend.api.gate.router.check_gate	core/policy.py
graph.anomalies	aldecI graph anomalies	GET /api/v1/graph/anomalies	backend.api.graph.router.get_anomalies	services/graph/graph.py
graph.kev_in_last	aldecI graph kev-in-last	GET /api/v1/graph/kev	backend.api.graph.router.get_kev_components	services/graph/graph.py
graph.lineage	aldecI graph lineage	GET /api/v1/graph/lineage	backend.api.graph.router.get_lineage	services/graph/graph.py
ingest.sarif	aldecI ingest sarif	POST /api/v1/ingest/sarif	backend.api.ingest.router.ingest_sarif	apps/api/normalizers.py
ingest.sbom	aldecI ingest sbom	POST /api/v1/ingest/sbom	backend.api.ingest.router.ingest_sbom	lib4sbom/normalizer.py
provenance.attest	aldecI provenance attest	POST /api/v1/provenance/attest	backend.api.provenance.router.create_attestation	services/provenance/attestation.py
provenance.verify	aldecI provenance verify	POST /api/v1/provenance/verify	backend.api.provenance.router.verify_attestation	services/provenance/attestation.py
risk.score	aldecI risk score	POST /api/v1/risk/score	backend.api.risk.router.score_components	risk/scoring.py
stage.run	aldecI stage run	POST /api/v1/stage/run	backend.api.stage.router.run_stage	core/stage_runner.py

Sources: tools/docgen/api_cli_map.py:151-185, README.md:46-51

SSDLC Simulation

A key demonstration of Aldeci's capabilities is the Secure Software Development Lifecycle (SSDLC) simulation. This feature runs a series of stages that mirror a real-world development process, transforming raw inputs into deterministic JSON outputs that can be audited or consumed by dashboards.

The stage-run command in the CLI is the entry point for this process. Each stage corresponds to a phase in the SSDLC and has defined inputs and outputs.

Sources: readme_updated.md:602-604, core/cli.py:314-317

Simulation Stages

The following diagram shows the sequence of stages in the SSDLC simulation.

This flow demonstrates how artifacts from each development phase are processed sequentially, with the output of one stage potentially feeding into the next, culminating in a final decision.

Sources: readme_updated.md:615-623, readme_updated.md:641-646

Stage	Input(s)	Output	Description
requirements	controls.json	policy_plan.json	Defines the security controls and policies for the project.
design	design_context.csv, overlay.yaml	design_crosswalk.json	Maps business context to technical components.
build	sbom.json	component_index.json	Creates a component manifest from the SBOM.
test	scanner.sarif	normalized_findings.json	Normalizes scanner findings for QA sign-off.
deploy	iac.tfplan.json	iac_posture.json	Assesses Infrastructure-as-Code posture.
operate	epss.json, kev.json	exploitability.json	Fuses exploit intelligence to flag urgent priorities.
decision	(All previous outputs)	decision.json	Synthesizes all stage outputs to produce a final verdict.

Sources: readme_updated.md:641-646, README.md:62-68

Conclusion

Aldeci provides a comprehensive and automatable solution for managing software supply chain security. By integrating artifact analysis, risk scoring, and provenance tracking into a single, configurable platform, it enables organizations to enforce security policies, accelerate audits, and make data-driven decisions. Its dual API/CLI interface and modular architecture make it a versatile tool for modern DevSecOps practices.

Sources: README.md:3-6, readme_updated.md:65-71