Using the Python SDK

Relevant source files

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

• core/cli.py
• apps/fixops_cli/main.py
• README.md
• scripts/run_demo_steps.py
• tests/test_cli.py
• config/policy.yml
• cli/fixops_ci.py

The primary Python SDK for interacting with the Aldeci (FixOps) platform is its Command-Line Interface (CLI). The CLI is designed for both interactive user sessions and integration into automated CI/CD pipelines. It provides a comprehensive set of commands to manage the entire security analysis lifecycle, from ingesting security artifacts to making decisions and generating evidence bundles.

This document covers the architecture of the CLI, its main commands, and common usage patterns. The CLI acts as a local, scriptable interface with feature parity to the FastAPI web service, allowing for flexible deployment in various environments, including air-gapped systems.

Architecture

The CLI is a Python application built using the argparse module for command-line parsing. Its functionality is split across several key files that work together to process user commands.

The main entry point for the general-purpose CLI is apps/fixops_cli/__main__.py, which acts as a lightweight wrapper around the core CLI logic implemented in core/cli.py. The core/cli.py script is responsible for defining the command structure, parsing arguments, and dispatching tasks to the appropriate handler functions.

Sources: apps/fixops_cli/main.py:12-15, core/cli.py

Command Processing Flow

The following diagram illustrates the typical flow of a command executed through the CLI.

This diagram shows how a user command is routed from the entry point through the core CLI logic to execution.
Sources: apps/fixops_cli/main.py:15, core/cli.py:438-441

Core Commands

The CLI provides several commands to interact with the FixOps system. These are defined in the build_parser function within core/cli.py.

Command	Description	Source File
run	Executes the full decision pipeline using provided artifacts.	core/cli.py:414-420
stage-run	Executes a single stage of the SSDLC pipeline (e.g., build, test).	core/cli.py:392-398
demo	Runs a pre-canned demonstration in either demo or enterprise mode.	core/cli.py:427-433
show-overlay	Inspects and prints the sanitized overlay configuration.	core/cli.py:421-426
train-forecast	Trains the probabilistic forecasting engine with historical data.	core/cli.py:424-426
copy-evidence	Copies an evidence bundle from a pipeline run to a target directory.	core/cli.py:389-391
health	Reports the status of the system and its components.	core/cli.py:377-379

Sources: core/cli.py:374-436, README.md:243-247

Running the Pipeline

The most common use of the CLI is to execute the full analysis pipeline using the run command. This command takes various security artifacts as input and produces a comprehensive JSON output.

run Command Arguments

The run command is configured by the _configure_pipeline_parser function and accepts the following key arguments:

Argument	Description
--overlay <path>	Path to the YAML overlay configuration file.
--design <path>	Path to the design context CSV file.
--sbom <path>	Path to the SBOM (Software Bill of Materials) JSON file.
--sarif <path>	Path to the SARIF file from a scanner.
--cve <path>	Path to a CVE JSON feed.
--output <path>	Path to write the final JSON output. If not provided, prints to stdout.
--pretty	Pretty-print the JSON output.
--evidence-dir <path>	Directory to store the generated evidence bundle.

Sources: core/cli.py:399-412, README.md:345-348

Execution Flow

The _handle_run function orchestrates the pipeline execution. It loads inputs, prepares the configuration overlay, runs the pipeline, and writes the output.

The following sequence diagram shows the interaction when the run command is executed.

Running Individual Stages (stage-run)

For more granular control, the stage-run command allows executing a single stage of the Secure Software Development Lifecycle (SSDLC). This is particularly useful in CI/CD pipelines where different stages run at different times.

The _handle_stage_run function processes this command, taking a --stage name and an --input file.

Sources: core/cli.py:380-388, apps/fixops_cli/main.py:14-19

SSDLC Stages

The following table, derived from the project's documentation, outlines the available stages and their expected inputs.

Stage	Input Artifact	Description
requirements	Requirements CSV/JSON	Parses requirements and applies SSVC anchoring.
design	Design context CSV	Ingests design context for the application.
build	SBOM JSON	Normalizes the SBOM and flags risky components.
test	SARIF file	Ingests scanner findings and calculates drift.
deploy	Terraform/K8s manifest	Extracts guardrail evidence from IaC plans.
operate	Telemetry data	Blends telemetry with KEV/EPSS feeds.
decision	(auto-discovered)	Synthesizes all prior stage outputs into a final verdict.

Sources: README.md:61-68

Example Usage

The scripts/run_demo_steps.py script demonstrates how to programmatically invoke stage-run for a demonstration.

# From scripts/run_demo_steps.py
def _run(
    args: List[str],
) -> None:
    # ...
    parser = build_parser()
    cli_args = parser.parse_args(args)
    # ...
    main(cli_args)

# Example invocation for the 'build' stage
_run(["stage-run", "--stage", "build", "--input", "path/to/sbom.json", "--app", "my-app"])

Sources: scripts/run_demo_steps.py:17-30

Specialized CLIs

In addition to the main apps.fixops_cli entry point, the platform provides several specialized CLIs for specific, high-frequency tasks. These scripts offer a more direct interface for common CI/CD operations.

CLI Script	Purpose
cli/fixops_ci.py	A CI agent that aggregates tasks like bundling evidence, applying policies, and running attestations.
cli/fixops_sbom.py	Provides commands for SBOM normalization and quality scoring.
cli/fixops_risk.py	Scores risk based on a normalized SBOM and threat intelligence feeds.
cli/fixops_provenance.py	Generates and verifies SLSA v1 provenance attestations.
cli/fixops_repro.py	Verifies that a build is reproducible.

These specialized tools are designed to be used in automated scripts and CI pipelines, providing focused functionality for each step of a DevSecOps workflow.

Sources: README.md:90, cli/fixops_ci.py, cli/fixops_sbom.py, cli/fixops_risk.py, cli/fixops_provenance.py, cli/fixops_repro.py

Conclusion

The Aldeci/FixOps Python CLI is a powerful and flexible tool that serves as the primary SDK for interacting with the platform. It supports both high-level pipeline runs and granular, stage-by-stage execution suitable for CI/CD integration. With its overlay-based configuration and specialized entry points, the CLI provides a robust foundation for automating security analysis and evidence collection throughout the software development lifecycle.