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.

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 In progress
3 Add KSI validation and SDR evidence Not started
4 Integrate trust-center and ongoing certification workflows Not started

ComplyRoll is pre-alpha; it does not produce a FedRAMP submission package and must not be represented as FedRAMP approved. The PyPI pre-release (pip install --pre complyroll) lags main, so follow this README from a source checkout.

Why ComplyRoll

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. ComplyRoll therefore keeps immutable observations apart from stateful vulnerability cases. A case's Potential Agency Impact (PAIN) rating comes from the operator's evaluation and 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.

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
--kev FILE Matches each record's CVE identifiers to a CISA KEV catalog the operator supplies and carries the catalog's due date as the VDR-TFR-KEV clock, without fetching anything
--inventory FILE Shows when detection last reached each resource the operator declares
--record-failed-imports Records an artifact that cannot be parsed or holds no usable content, or a failed scanner invocation, as a system observation and a vulnerability of its own (VDR-CSO-FAV), and exits 3; ingest refuses with failure_read_elsewhere, appending nothing, a failure whose bytes the store already holds an outranking reading of
--record-coverage-gaps, complyroll cases coverage Record each coverage window that closed with no verification as a system observation of its own and a vulnerability case (VDR-CSO-FAV), on a report run or into a store, and exit 3; windows of one rule whose entries name the same job share a case, the windows of one sample group share a case, and every other window is a case of its own
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 store verify --db STORE Audits an event store's bytes and its domain, and exits non-zero on any fault
complyroll validate REPORT --schema KIND Validates a report offline against the pinned official schema, with a JSON Pointer for each failure
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

Not yet built, among others: failures in the response process, change integration, SPDX and cloud sources, and KSI and SDR evidence. docs/BUILD_PLAN.md has the full list. A coverage 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, which 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.

Every command and flag: docs/CLI.md.

Quick start

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.

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.

Non-negotiable rules

  • Source severity, DISA CAT, CVSS, and PAIN are separate concepts.
  • ComplyRoll must never infer PAIN solely from source severity or CVSS.
  • A scanner pass may support a Key Security Indicator (KSI); it does not prove the complete KSI.
  • Grouping observations must not destroy affected-resource or source-level details.
  • Rule calculations must identify the exact pinned FedRAMP rules version used.
  • Human-readable and machine-readable reports must come from the same normalized records.
  • Historical evaluations and evidence must remain reproducible.

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.

Disclaimer

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.

License

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). Contributions require a Developer Certificate of Origin sign-off (CONTRIBUTING.md).

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.4.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.4.0a0
File Size Uploaded Provenance Actions
complyroll-0.4.0a0.tar.gz 1.0 MB With provenance Details for complyroll-0.4.0a0.tar.gz

Built distribution (wheel)

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

Total release size: 1.5 MB

Release files / complyroll-0.4.0a0.tar.gz

Download URL complyroll-0.4.0a0.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
73c8f6e4a126f021109d43961795261f33c1dc69f3d8039dcd3df04c3929a132
BLAKE2b-256 checksum
How to use checksums
5d776696cf0b718c753c7f03c85eb841b0cb3af36b0ea5572a16f7fa19227a77
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 6, 2026.

Transparency log

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

Download URL complyroll-0.4.0a0-py3-none-any.whl
Size 421.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f74cb2b9765a88795f9d331cfa2e3b2bfa9e9622b1f5fe477e63782c8efebeb0
BLAKE2b-256 checksum
How to use checksums
3f015d896eb160e51f36986fcc3569071f983f2bd8b4135450daf686ecfe7a33
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 6, 2026.

Transparency log

Security for complyroll 0.4.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.4.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 6, 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