Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

ComplyRoll: FedRAMP 20x VDR evidence compiler

PyPI Python License CI

A local-first evidence compiler for FedRAMP® 20x Vulnerability Detection and Response (VDR).

ComplyRoll turns scanner observations, validation runs, and operational evidence into traceable vulnerability cases, class-aware response clocks, and official-format FedRAMP reports that a provider can publish and an independent assessor can recompute.

ComplyRoll is pre-alpha. It does not produce a FedRAMP submission package and must not be represented as FedRAMP approved.

Quick start

Install the latest pre-release with pip install --pre complyroll. The walkthrough below uses the synthetic sample files in this repository, so run it from a source checkout, with Python 3.11 or newer:

git clone https://github.com/ComplyRoll/ComplyRoll.git && cd ComplyRoll
python3 -m venv .venv && . .venv/bin/activate && python3 -m pip install -e .

complyroll report vdt tests/fixtures/ubuntu-host.cklb tests/fixtures/windows-host.ckl \
  tests/fixtures/openscap-results.xml --class C --package-uri https://example.test/cpo \
  --from 2026-08-01T00:00:00Z --to 2026-08-31T23:59:59Z --as-of 2026-08-21T12:00:00Z \
  --detected-at 2026-08-01T00:00:00Z --evaluations examples/evaluations.json \
  -o report.json --markdown report.md
complyroll validate report.json --schema vulnerability-detail

The fixtures declare no scan time, so report vdt warns source_timestamp_missing three times and --detected-at attests one. Next, record the same work as append-only history and rebuild the report from it (ADR 0008). The two reports are byte-identical, so cmp prints nothing:

complyroll ingest tests/fixtures/ubuntu-host.cklb tests/fixtures/windows-host.ckl \
  tests/fixtures/openscap-results.xml --db complyroll.db --as-of 2026-08-21T12:00:00Z
complyroll cases correlate --db complyroll.db
complyroll cases attest-detection --db complyroll.db --all-missing \
  --detected-at 2026-08-01T00:00:00Z --rationale "The fixtures declare no assessment timestamp."
complyroll cases evaluate --db complyroll.db --evaluations examples/evaluations.json
complyroll report vdt --db complyroll.db --class C --package-uri https://example.test/cpo \
  --from 2026-08-01T00:00:00Z --to 2026-08-31T23:59:59Z --as-of 2026-08-21T12:00:00Z \
  -o report-from-history.json --markdown report-from-history.md
cmp report.json report-from-history.json && cmp report.md report-from-history.md

The report includes internal resource identifiers and provider rationale, so redact it before sharing with an agency. examples/README.md continues from here with the other two reports, SARIF, KEV, coverage and coverage gaps, HDF, failed imports, and the Python API.

What it does

Surface What it does
CKLB, CKL, XCCDF, ARF, SARIF, HDF, and CycloneDX files Become immutable observations with the artifact digest, parser identity, and timestamps
complyroll report vdt|avi|historical Compiles the Vulnerability Detail, Accepted Vulnerability Information, or Historical VER Activity report, with a Markdown twin rendered from the same records
complyroll validate REPORT --schema KIND Validates a report offline against the pinned official schema, with a JSON Pointer for each failure
--kev FILE Matches each record's CVE identifiers to a CISA KEV catalog the operator supplies and carries its due date as the VDR-TFR-KEV clock, without fetching anything
--inventory FILE Shows when detection last reached each resource the operator declares
--changes FILE, complyroll changes pending Shows whether detection reached each resource a declared change touched, and writes the resources still waiting as a document for the pipeline that owns the scanner
--record-failed-imports Records an artifact that cannot be parsed or holds no usable content, or a failed scanner invocation, as a vulnerability case of its own (VDR-CSO-FAV), and exits 3
--record-coverage-gaps, complyroll cases coverage Record coverage windows that closed with no verification as vulnerability cases (VDR-CSO-FAV), on a report run or into a store, and exit 3
--record-change-gaps, complyroll cases changes Record change windows that closed with no verification as vulnerability cases (VDR-CSO-FAV), one per change, on a report run or into a store, and exit 3
complyroll ingest, cases, and report --db Record the same work as append-only history and rebuild each report from it, byte-identical to the stateless report
complyroll changes record Records each declared change in a store as history, for report --db, changes pending --db, and cases changes to read back
complyroll store verify --db STORE Audits an event store's bytes and its domain, and exits non-zero on any fault
stigroll FILE... The predecessor STIG roll-up, rebuilt on the hardened adapters and locked to its original output
complyroll.adapters, .policy, .schemas, .store Ingest an artifact, calculate a deadline with its rule provenance, validate a report, or open the event store from Python

Every command, flag, and exit status: docs/CLI.md.

What a result does not mean:

  • A coverage gap or a change gap records that no verification reached a resource in time, not that the resource is vulnerable.
  • A SARIF log with no results ingests as a PASS observation of the scope it names. That is evidence that the tool ran, not that the scope is clean.
  • A CycloneDX SBOM with no vulnerability records, or an empty list, ingests as a NOT_REVIEWED observation of its subject. An inventory is not a detection, and a standalone VEX document is refused.
  • A scanner pass may support a Key Security Indicator (KSI). It does not prove the complete KSI.

Status

Phase Scope State
0 Harden stigroll ingestion and provenance Complete
1 Build VDR cases, policy clocks, and VER exports Complete
2 Add automation, coverage, and change integration Complete
3 Add response-process cases, KSI validation, and SDR evidence Not started
4 Integrate trust-center and ongoing certification workflows Not started

Phase 2 closed on its exit criteria, with three deliverables moved on as a recorded scope change. Not yet built, among others: failures in the response process as cases, a cloud, container, or CSPM adapter, HTML report output, SPDX input, and KSI and SDR evidence. docs/BUILD_PLAN.md has the full list. main can be ahead of the PyPI pre-release, and CHANGELOG.md says what is unreleased.

Design rules

FedRAMP 20x is based on measured outcomes and persistent validation. A failed STIG rule or CVE is only a source observation. VDR also covers drift, failed validation pipelines, stale security decisions, supply-chain exposures, and failures in the detection and response process itself. So:

  • Observations are immutable source facts, kept apart from stateful vulnerability cases.
  • A case's Potential Agency Impact (PAIN) rating comes from the operator's evaluation. It is never derived from scanner severity, DISA CAT, or CVSS.
  • Every deadline names its rule in the official FedRAMP rules dataset, pinned to one commit, and takes its timeframe from that rule. The KEV clock is the one exception: its rule comes from the dataset, but its due date comes from the CISA catalog the operator supplies.
  • Grouping observations must not destroy affected-resource or source-level details.
  • Human-readable and machine-readable reports must come from the same normalized records.
  • Historical evaluations and evidence must remain reproducible.

For independent assessors

ComplyRoll is meant to be run cold on provider-supplied artifacts: ingest the raw scanner exports, recompute the clocks and the report, and compare against what the provider published. Every deadline names its rule identifier, force (MUST or SHOULD), certification class, dataset commit, and digest. The same artifacts, evaluations, options, and --as-of instant produce the same bytes in any argument order (docs/ARCHITECTURE.md has the details). Assessors do not configure or operate ComplyRoll on a provider's behalf; under the 2026 recognition rules, advisory work on an offering bars assessing that offering for two years.

Documentation

Dependencies and data

ComplyRoll uses the Python standard library plus one declared runtime dependency, the major-version-bounded jsonschema package with its non-GPL format extra, because the standard library does not implement JSON Schema Draft 2020-12 (ADR 0006). The official FedRAMP rules dataset and VER schemas are bundled unmodified and pinned to immutable upstream commits with SHA-256 digests; see NOTICE and src/complyroll/data/README.md for provenance and license.

Contributing and security

CONTRIBUTING.md covers the development setup and the Developer Certificate of Origin sign-off every commit carries. Report a vulnerability privately, as SECURITY.md describes, rather than in a public issue.

License and disclaimer

ComplyRoll's code is licensed under the Apache License, Version 2.0 (see LICENSE and NOTICE). The bundled FedRAMP data files are works of the U.S. Government and are not covered by that license. The ComplyRoll name is not licensed (Apache License, Section 6).

ComplyRoll is informational tooling, not legal or compliance advice. A report that validates against an official schema satisfies that schema's minimum structure; it is not a FedRAMP determination, and the provider remains responsible for meeting the Consolidated Rules. Verify every clock against https://www.fedramp.gov/2026/ before relying on it.

FedRAMP® is a registered trademark of the U.S. General Services Administration. ComplyRoll is an independent project and is not affiliated with, endorsed by, or approved by GSA or the FedRAMP Program Management Office.

Metadata

Release files for complyroll 0.5.0a0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for complyroll 0.5.0a0
File Size Uploaded Provenance Actions
complyroll-0.5.0a0.tar.gz 1.2 MB With provenance Details for complyroll-0.5.0a0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for complyroll 0.5.0a0
File Interpreter ABI Platform Actions
complyroll-0.5.0a0-py3-none-any.whl Python 3 none any Details for complyroll-0.5.0a0-py3-none-any.whl

Total release size: 1.7 MB

Release files / complyroll-0.5.0a0.tar.gz

Download URL complyroll-0.5.0a0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
0cd47958e4fa5cce12fca6d0159a5f87a13ba78e0e6a0bb78be858c02b4ddf6b
BLAKE2b-256 checksum
How to use checksums
7193ac248344bf19424142e6f64659d2cbad8a5e194f1ef6a1222950db760818
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / complyroll-0.5.0a0-py3-none-any.whl

Download URL complyroll-0.5.0a0-py3-none-any.whl
Size 463.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b88f2de389d642c336b7fdd3d1a99f92be8558255bd84d2770974234a2af8263
BLAKE2b-256 checksum
How to use checksums
f8a551440ba36a5bcdecbd8313b0bb4a0d56b0d521d4e1aab73878df699a16b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for complyroll 0.5.0a0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for complyroll-0.5.0a0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page