This release is a pre-release and may not be stable for production use.
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
examples/README.md: worked runs on the synthetic fixtures, Python API includeddocs/CLI.md: every command and flag, and the exit status of eachexamples/ci/: a reference GitHub Actions workflow and gatedocs/BUILD_PLAN.md: phased implementation plan and exit criteriadocs/ARCHITECTURE.md: system boundaries and component designdocs/DATA_MODEL.md: observation, case, evaluation, and evidence modeldocs/FEDRAMP_2026_MAPPING.md: current rule and schema mapping, and the FedRAMP sources ComplyRoll pinsdocs/SECURITY.md: threat model and evidence-handling requirementsdocs/decisions/README.md: index of the architecture decision recordsCHANGELOG.md: notable changes by releaseAGENTS.md: repository rules and development commands
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.