Getting Started

Relevant source files

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

• artifacts/upstream_doc_index.json
• artifacts/upstream_symbol_index.json
• core/cli.py
• core/stage_runner.py
• tools/importer/mine_docs.py

The Aldeci project, also referred to as FixOps, is a contextual risk and evidence platform designed to process raw security artifacts and transform them into actionable outputs. It provides a lightweight FastAPI service and a command-line interface (CLI) with parity to accept various inputs like SBOMs, SARIF files, and CVE data. The system processes these inputs through a modular pipeline to generate guardrail verdicts, contextual summaries, and auditable evidence bundles.

The platform operates in different modes, such as demo and enterprise, which are governed by overlay configuration files. These overlays control guardrails, automation, and evidence retention settings without requiring code changes. This guide focuses on the core concepts and CLI usage to get started with the platform's capabilities.

Sources: artifacts/upstream_doc_index.json

Core Concepts

The platform is built around several key capabilities for DevSecOps workflows. These features are identified as core keywords within the project's documentation analysis.

Sources: tools/importer/mine_docs.py:11-21

Feature	Description	Relevant Modules
SBOM	Software Bill of Materials normalization and quality scoring. The system can ingest CycloneDX and SPDX formats to create a deterministic, deduplicated component list for downstream processing.	lib4sbom/normalizer.py, cli/fixops_sbom.py
Risk Scoring	Prioritizes remediation by blending exploit intelligence from EPSS and KEV feeds with SBOM data to produce a composite risk score.	risk/scoring.py, risk/feeds/*
Provenance	Generates and verifies SLSA v1 attestations for build artifacts, ensuring a verifiable supply chain.	services/provenance/attestation.py, cli/fixops_provenance.py
Evidence	Packages security artifacts (SBOM, risk reports, provenance) into signed, compressed bundles for auditors.	evidence/packager.py, cli/fixops_ci.py
Graph	Builds a queryable provenance graph linking commits, CI jobs, artifacts, components, and CVEs to facilitate security investigations.	services/graph/graph.py, backend/api/graph/router.py

Sources: artifacts/upstream_doc_index.json, artifacts/upstream_symbol_index.json

Architecture Overview

The Aldeci platform is architected around a central StageRunner that processes artifacts through a series of stages corresponding to the Secure Software Development Lifecycle (SSDLC). Both the CLI and the API act as frontends to this core processing logic.

The diagram below illustrates the high-level data flow from ingestion to the final decision and evidence bundle creation.

Sources: core/cli.py, core/stage_runner.py, artifacts/upstream_doc_index.json

CLI Usage

The primary entry point for local interaction is the command-line interface, defined in core/cli.py. It provides commands to run the pipeline, execute individual stages, and manage configurations.

Main Commands

Command	Description	Source
run	Executes the full pipeline using specified inputs and an overlay configuration.	core/cli.py:309-317
stage-run	Executes a single SSDLC stage (e.g., build, test).	core/cli.py:236-244
demo	Runs a pre-configured demonstration pipeline for either demo or enterprise mode.	core/cli.py:330-333
show-overlay	Inspects and prints sanitized overlay metadata.	core/cli.py:318-321
copy-evidence	Copies an evidence bundle from a pipeline run to a target directory.	core/cli.py:209-212

Sources: core/cli.py

SSDLC Stage Workflow

The stage-run command is central to the platform's operation. It processes one of several predefined stages, each accepting a specific input and producing a canonical JSON output.

The following diagram shows the sequence of stages in a typical SSDLC workflow.

Sources: core/stage_runner.py:53-68

Each stage has a designated input and output file, managed by the StageRunner.

Stage	Input Filename	Output Filename	Description
requirements	requirements-input.csv	requirements.json	Parses requirements and applies an SSVC anchor.
design	design-input.json	design.manifest.json	Mints application/component IDs and calculates a design risk score.
build	sbom.json	build.report.json	Normalizes an SBOM and flags risky components.
test	scanner.sarif	test.report.json	Ingests SARIF findings and calculates a test risk score.
deploy	tfplan.json	deploy.manifest.json	Analyzes infrastructure-as-code posture for risks like public S3 buckets.
operate	ops-telemetry.json	operate.snapshot.json	Blends telemetry with KEV/EPSS feeds to compute operational risk.
decision	decision-input.json	decision.json	Synthesizes all prior stage outputs into a final verdict and evidence bundle.

Sources: core/stage_runner.py:53-68

Stage Processing Deep Dive

The StageRunner class orchestrates the execution of each stage. It contains a _process_<stage_name> method for each step in the workflow.

Sources: core/stage_runner.py

StageRunner Class

The StageRunner and its summary class StageSummary are central to the CLI's operation.

Sources: core/stage_runner.py:48-71

Build Stage

The _process_build method handles the build stage. It ingests an SBOM, normalizes it using InputNormalizer, and identifies components that match a predefined set of risk rules (e.g., log4j-core). The output is a build.report.json file containing the count of indexed components, a list of risk flags, and a calculated build_risk_score.

Sources: core/stage_runner.py:240-281

Decision Stage

The _process_decision method is the final and most critical stage. Its workflow is as follows:

1. Collect Documents: It gathers all the JSON outputs from the preceding stages (requirements, build, test, etc.).
2. Determine Verdict: It analyzes the collected data, such as control failures from the deploy stage or KEV hits from the operate stage, to determine a final verdict, which is either ALLOW or DEFER.
3. Identify Top Factors: It synthesizes the most significant findings (e.g., high-severity vulnerabilities, guardrail violations) into a list of "top factors" that influenced the decision.
4. Create Evidence Bundle: It archives all the stage documents into a single evidence_bundle.zip file. A manifest.json is also created and added to the bundle, containing checksums for all included documents to ensure integrity.

Sources: core/stage_runner.py:413-455

This sequence diagram illustrates the decision stage process.

Sources: core/stage_runner.py:121-178, 413-455

Summary

Getting started with Aldeci involves understanding its core concepts and the SSDLC-based stage workflow. The core.cli provides the primary interface for executing this workflow, with the StageRunner handling the logic for each step. By processing security artifacts through stages like build, test, and deploy, the platform generates a final decision and a comprehensive evidence_bundle.zip, providing a powerful mechanism for automated risk assessment and compliance auditing.

Sources: artifacts/upstream_doc_index.json, core/cli.py, core/stage_runner.py