API Endpoints: Gate and Risk

Relevant source files

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

• backend/api/risk/router.py
• risk/scoring.py
• cli/fixops_risk.py
• cli/fixops_ci.py
• config/policy.yml
• README.md
• evidence/packager.py

The Aldeci platform provides a robust system for quantifying security risk and enforcing policy-based gates within the CI/CD pipeline. The "Risk" component offers API endpoints for on-demand analysis of components and CVEs, powered by a scoring engine that synthesizes multiple threat intelligence feeds. The "Gate" functionality is primarily implemented as a CLI agent, fixops-ci, designed to run within CI/CD environments. This agent consumes risk scores and other artifacts to enforce quality and security thresholds defined in a policy file, ultimately producing signed evidence bundles.

These two systems work in tandem to provide both continuous risk visibility and automated enforcement. The Risk API serves interactive queries for UIs and external tools, while the CI Gate provides a non-falsifiable mechanism for ensuring releases meet organizational standards.

Sources: README.md:47-51, cli/fixops_ci.py, backend/api/risk/router.py

Risk Scoring System

The risk scoring system is centered around the FixOpsRisk engine, which provides a composite risk score by blending threat intelligence with SBOM data. It is accessible via both a REST API and a command-line interface.

Sources: risk/scoring.py, README.md:47

Core Logic (FixOpsRisk)

The core scoring logic resides in risk/scoring.py. The compute_risk_profile function is the main entry point, which takes a normalized SBOM and enriches it with data from EPSS (Exploit Prediction Scoring System) and CISA KEV (Known Exploited Vulnerabilities) feeds. The engine calculates a composite fixops_risk score for each component and CVE by weighting factors like exploit probability, version lag, and known exposure.

This diagram illustrates the data flow for computing a risk profile.

Risk API Endpoints

The risk scoring engine is exposed through a modular FastAPI router. These endpoints allow external systems and UIs to query for on-demand risk information about specific components or CVEs.

Endpoint	Method	Description	Source
/api/v1/risk/component/{id}	GET	Retrieves the risk profile for a specific software component.	README.md:47
/api/v1/risk/cve/{id}	GET	Retrieves risk information for a specific CVE identifier.	README.md:47

Note: The specific implementation details for these routes are located in backend/api/risk/router.py.

Sources: backend/api/risk/router.py, README.md:47

CLI Interface

For local analysis, air-gapped environments, or pipeline integration, the fixops-risk CLI provides direct access to the scoring engine. It serves as a parity tool to the API.

Command:

fixops-risk score --sbom <path/to/sbom.json>

This command ingests an SBOM, performs the same risk calculation as the API, and outputs the resulting risk profile.

Sources: cli/fixops_risk.py, README.md:47

CI Gating and Evidence Bundling

The "Gate" in Aldeci is not a single API endpoint but a process orchestrated by the fixops-ci CLI agent. This agent acts as a policy enforcement point in CI/CD pipelines, aggregating various security artifacts, evaluating them against defined policies, and bundling the results into signed, auditable evidence packages.

Sources: cli/fixops_ci.py, README.md:51

Policy Enforcement

The gating logic is driven by policies defined in config/policy.yml. This file specifies thresholds that must be met for a pipeline to pass, such as maximum allowable risk scores or minimum SBOM quality metrics. The fixops-ci agent reads this policy file to determine whether to pass or fail a build.

Policy Key	Description	Example Value
version	The version of the policy schema.	1
risk_scoring.fail_on.max_risk_score	Fails the gate if any component's fixops_risk exceeds this value.	8.0
sbom_quality.fail_on.min_coverage_ratio	Fails the gate if the SBOM component coverage is below this ratio.	0.85
evidence.sign_bundle	A boolean that determines if the final evidence bundle should be signed.	true

Sources: config/policy.yml:1-160, cli/fixops_ci.py:120-300

Evidence Bundling Process

A primary function of the CI gate is to create immutable evidence bundles. The fixops-ci evidence bundle command orchestrates this process, which is handled by the evidence/packager.py module.

This sequence diagram shows how the fixops-ci agent creates an evidence bundle.

Evidence API Endpoint

Once an evidence bundle is created and stored, it can be retrieved via the API. This allows auditors or other external systems to access the complete, signed record of a release's security posture.

Endpoint	Method	Description	Source
/api/v1/evidence/{release}	GET	Retrieves the signed evidence bundle for a specific release.	README.md:51, backend/api/evidence/router.py

Sources: README.md:51, backend/api/evidence/router.py:80-140

Conclusion

The Gate and Risk systems provide a comprehensive framework for managing software supply chain security. The Risk API offers flexible, on-demand threat intelligence, while the CI Gate enforces security and quality standards directly within the development pipeline. Together, they create a verifiable and auditable trail of a project's security posture from build to release, culminating in signed evidence bundles that serve as a single source of truth for compliance and audit activities.

Sources: README.md:61-62