API Endpoints: Graph and Provenance
Relevant source files
The following files were used as context for generating this wiki page:The Graph and Provenance services are core components of the FixOps platform, designed to provide verifiable supply-chain evidence and deep contextual insights. The Provenance service focuses on generating and verifying SLSA v1 attestations for build artifacts, ensuring their integrity and traceability. The Provenance Graph service complements this by creating a queryable knowledge graph that links software development artifacts—from commits and CI jobs to components and CVEs—enabling rapid investigation of lineage, risk exposure, and release anomalies.
Together, these services provide a robust foundation for security-as-code, automating the collection of audit-ready evidence and enabling context-aware decision-making. They are accessible via both a RESTful API for integration with UIs and external systems, and a command-line interface (CLI) for use in local development and CI/CD pipelines.
Sources: README.md:79, README.md:444, readme_updated.md:65
Provenance Attestation Service
The Provenance service is responsible for creating and verifying SLSA v1-compliant attestations. This guarantees build traceability by anchoring release artifacts to verifiable supply-chain evidence. The service can hash artifacts, embed builder and source metadata, and generate signed statements.
Sources: README.md:79, readme_updated.md:449
Core Components
| Component | Path | Description |
|---|---|---|
| Attestation Model | services/provenance/attestation.py | Defines the data structures and logic for creating and validating SLSA v1 provenance statements. It handles artifact hashing (SHA-256) and metadata embedding. |
| Provenance CLI | cli/fixops_provenance.py | Provides attest and verify subcommands, allowing users to generate and validate attestations from the command line, suitable for CI/CD integration. |
| Provenance API Router | backend/api/provenance/router.py | Exposes the provenance functionality via a RESTful API, allowing external systems and UIs to retrieve attestation data for specific artifacts. |
Sources: readme_updated.md:394-395, readme_updated.md:922, readme_updated.md:929
Attestation Generation Flow
The following diagram illustrates the process of generating a signed SLSA attestation for a build artifact.
API Endpoints
The Provenance API exposes endpoints for retrieving attestation data.
| Method | Endpoint | Description |
|---|---|---|
GET | /provenance/artifacts/{name} | Returns the stored SLSA attestation JSON for the requested artifact name. |
Sources: readme_updated.md:464, readme_updated.md:929
CLI Interface
The fixops-provenance CLI tool provides direct access to the service's core functions.
| Command | Example | Description |
|---|---|---|
attest | fixops-provenance attest --artifact dist/fixops.tar.gz | Generates a SLSA v1 provenance statement for the specified artifact. |
verify | fixops-provenance verify --artifact dist/fixops.tar.gz --attestation ... | Verifies an artifact against its corresponding attestation file. |
Sources: readme_updated.md:461-462, readme_updated.md:922
Provenance Graph Service
The Provenance Graph Service provides a queryable knowledge graph that connects commits, CI jobs, artifacts, SBOM components, and CVEs. This enables auditors and responders to quickly investigate lineage, trace risk exposure (like KEV regressions), and detect anomalies such as version downgrades across releases.
Sources: readme_updated.md:476, readme_updated.md:696
Architecture
The graph is built using a SQLite database for persistence and a NetworkX overlay for in-memory graph analysis. A dedicated worker process is responsible for orchestrating the ingestion of data from various sources.
This diagram shows the data sources that feed into the Provenance Graph.
API Endpoints
The graph's insights are exposed via a set of RESTful API endpoints for use in UIs and automated reporting.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/graph/lineage | Traces the provenance lineage for a given artifact, showing its path from source code to release. |
GET | /api/v1/graph/kev-components | Lists components across recent releases that are affected by Known Exploited Vulnerabilities (KEVs). |
GET | /api/v1/graph/anomalies | Surfaces version drift and downgrade anomalies by comparing component versions against previous releases. |
Sources: readme_updated.md:49, readme_updated.md:932-934
Key Queries & Use Cases
The service is designed to answer critical supply-chain security questions:
- Lineage Tracing: By querying the
/graph/lineageendpoint, a user can trace an artifact back to its source commit, build job, and materials, providing a clear audit trail.
Sources: readme_updated.md:49 - KEV Exposure: The
/graph/kev-componentsendpoint helps security teams quickly identify which releases contain components with actively exploited vulnerabilities, enabling focused remediation efforts.
Sources: readme_updated.md:49, readme_updated.md:698 - Downgrade Anomaly Detection: The
/graph/anomaliesendpoint detects when a component has been downgraded to an older version in a new release, which could indicate a malicious action or a misconfiguration. The query works by performing a semantic diff against previous releases.
Sources: readme_updated.md:49, readme_updated.md:519, readme_updated.md:698
Conclusion
The Provenance and Graph APIs are essential for establishing trust and visibility within the software supply chain. The Provenance service provides the foundational, immutable evidence of an artifact's origin through SLSA attestations. The Graph service builds upon this by weaving together disparate data points into an interconnected model, enabling powerful, context-aware queries that are crucial for modern security operations, compliance, and incident response. Together, they empower teams to move from reactive vulnerability management to proactive risk posture management.
Sources: README.md:79, readme_updated.md:60, readme_updated.md:62