API: Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Aldeci API is a FastAPI-based service that provides a comprehensive interface for ingesting security artifacts, orchestrating analysis pipelines, and querying contextual risk and provenance information. It is designed to be the backend for both the fixops CLI and other integrations, such as UI dashboards. The API exposes endpoints for managing various security data types, including SBOMs, SARIF files, CVEs, and provenance attestations.
The core of the system is a modular pipeline that processes these inputs. The API allows clients to upload artifacts, run the pipeline, and retrieve structured outputs like guardrail verdicts, compliance evidence bundles, and risk scores. It features a robust, overlay-driven configuration system that allows runtime behavior to be switched between different profiles (e.g., demo vs. enterprise) without code changes.
Architecture
The API is built around a central FastAPI application that wires together modular routers for different functionalities like provenance, risk, and graph queries. A key architectural element is the EXECUTION_REGISTRY, which maps high-level capabilities to their corresponding API endpoints and CLI commands, ensuring parity between the two interfaces.
Sources: tools/docgen/api_cli_map.py:23-24, artifacts/upstream_doc_index.json (mentions of FastAPI and CLI parity)
High-Level Request Flow
The following diagram illustrates the general flow of a request from a user or CI/CD process to the API, and the subsequent internal service calls.
This diagram shows how a user interacts with the CLI/SDK, which in turn calls the FastAPI application. The app uses modular routers to direct requests to the appropriate backend services.
Sources: apps/api/app.py:16-36, tools/docgen/api_cli_map.py:100-117
Application Factory
The FastAPI application is instantiated by the create_app function. This factory is responsible for:
- Initializing the FastAPI instance.
- Mounting modular API routers for different functionalities like risk, provenance, and graph queries.
- Applying middleware, such as CORS.
- Setting up JWT-based authentication.
Sources: apps/api/app.py:16-36
Authentication
The API uses JSON Web Tokens (JWT) for securing endpoints. The generate_access_token and decode_access_token functions in apps/api/app.py handle the creation and validation of these tokens. An API key (X-API-Key header) is also mentioned as a method of enforcement.
Sources: apps/api/app.py:6-14, artifacts/upstream_doc_index.json (mention of X-API-Key)
Capabilities and Endpoints
The system's functionality is organized into "capabilities" which are mapped to specific API endpoints and CLI commands. This mapping is defined in the EXECUTION_REGISTRY.
Sources: tools/docgen/api_cli_map.py:24
The following table summarizes the primary capabilities and their corresponding API endpoints.
| Capability | API Route | FastAPI Handler | Description |
|---|---|---|---|
| Ingestion | |||
ingest.sbom | POST /inputs/sbom | apps.api.app.create_app | Uploads SBOM JSON files. Normalizes component tokens and retains version metadata. |
ingest.sarif | POST /inputs/sarif | apps.api.app.create_app | Uploads scanner findings in SARIF format. |
| Risk | |||
risk.score | GET /api/v1/risk/component/{id} | backend.api.risk.router | Powers portals and integrations that need on-demand risk lookups for a component. |
| Provenance | |||
provenance.attest | GET /api/v1/provenance/{artifact} | backend.api.provenance.router.get_provenance_for_artifact | Returns SLSA v1 provenance statements for a given artifact. |
provenance.verify | GET /api/v1/provenance/{artifact} | backend.api.provenance.router.get_provenance_for_artifact | Verifies a release artifact. The API endpoint retrieves the attestation for verification. |
| Graph | |||
graph.lineage | GET /api/v1/graph/lineage | backend.api.graph.router | Traces the lineage of an artifact. |
graph.kev_in_last | GET /api/v1/graph/kev | backend.api.graph.router | Finds KEV (Known Exploited Vulnerabilities) regressions. |
graph.anomalies | GET /api/v1/graph/anomalies | backend.api.graph.router | Detects downgrade anomalies across releases. |
| Evidence | |||
evidence.bundle | GET /api/v1/evidence/{release} | backend.api.evidence.router | Exposes ready-made, signed evidence bundles for auditors. |
| Enhanced Analysis | |||
enhanced.analysis | POST /enhanced/analysis | apps.api.routes.enhanced.run_enhanced_analysis | Retrieves a standardized multi-LLM schema for CI/CD gating. |
enhanced.capabilities | GET /enhanced/capabilities | apps.api.routes.enhanced.enhanced_capabilities | Exposes supported LLM models for enhanced analysis. |
Sources: tools/docgen/api_cli_map.py:144-177, artifacts/upstream_doc_index.json, backend/api/risk/router.py, backend/api/provenance/router.py, apps/api/routes/enhanced.py
Interaction Sequence Diagram
This diagram shows the sequence of calls for the risk.score capability, from the CLI to the API and internal services.
This sequence illustrates how a CLI command is translated into an SDK call, which then makes an HTTP request to the FastAPI backend. The request is handled by a specific router that invokes the core risk scoring service.
Sources: tools/docgen/api_cli_map.py:276-324, artifacts/upstream_doc_index.json, backend/api/risk/router.py
Data Schemas
The API relies on Pydantic models for request and response validation. Key data structures are used for normalizing various security artifacts.
Normalizer Schemas
The apps/api/normalizers.py module defines a set of Pydantic models to create a canonical representation of different input types like SBOM, VEX, SARIF, and CNAPP findings.
This diagram shows the InputNormalizer class and the main normalized data structures it produces.
Sources: artifacts/upstream_symbol_index.json (symbols from apps/api/normalizers.py)
Enhanced Analysis Schemas
The enhanced analysis endpoints use specific request models to handle interactions with LLMs.
EnhancedDecisionRequest: The main request body for the/enhanced/analysisendpoint.CompareLLMsRequest: The request body for the/enhanced/compare_llmsendpoint.
Sources: apps/api/routes/enhanced.py:13-20
Summary
The Aldeci API provides a structured and extensible backend for a comprehensive security analysis platform. By leveraging FastAPI, modular routers, and a central capability registry, it maintains parity with its CLI counterpart while offering a robust interface for data ingestion and retrieval. Its use of Pydantic for data normalization and JWT for security ensures reliable and secure operations, making it a solid foundation for building advanced DevSecOps workflows.