compliance-atlas — a condensed, cross-walked map of the frameworks that matter

Part of the Cognis Neural Suite · COCL v1.0 · domain: compliance

A research-grade, condensed reference for the security & privacy frameworks teams actually get asked about — each summarized to its essentials, with crosswalks showing how they overlap so you implement once and satisfy many. Built from primary sources (linked in SOURCES.md).

Not legal advice. Frameworks change — verify against the authoritative source before relying on this.

Watch the walkthrough

A full narrated tour — setup, the tool in action, and every demo scenario:

▶ Watch the walkthrough (MP4)

🔎 Example output

Sample result format (illustrative values — run on your own data for real findings):

{
  "compliances": [
    {
      "id": "001",
      "name": "GDPR",
      "description": "General Data Protection Regulation",
      "status": "active",
      "effective_date": "2018-05-25T00:00:00Z",
      "expiration_date": null,
      "compliance_items": [
        {
          "id": "001-001",
          "name": "Data Subject Rights",
          "description": "Allow users to access and delete their data"
        },
        {
          "id": "001-002",
          "name": "Breach Notification",
          "description": "Notify users within 72 hours of a breach"
        }
      ]
    },
    {
      "id": "002",
      "name": "HIPAA",
      "description": "Health Insurance Portability and Accountability Act",
      "status": "active",
      "effective_date": "1996-08-21T00:00:00Z",
      "expiration_date": null,
      "compliance_items": [
        {
          "id": "002-001",
          "name": "Protected Health Information",
          "description": "Define and protect PHI"
        },
        {
          "id": "002-002",
          "name": "Security Measures",
          "description": "Implement security measures to prevent breaches"
        }
      ]
    }
  ]
}

Usage — step by step

1. Get the atlas — clone it, or install via the suite installer:

   git clone https://github.com/cognis-digital/compliance-atlas.git && cd compliance-atlas
   ./install.sh          # or: ./scripts/setup-linux.sh

2. Read a framework summary and its crosswalks (plain Markdown, no build step):

   less frameworks/soc2.md
   less crosswalks/soc2-iso27001.md

3. Implement once, satisfy many — start from the master matrix to find overlapping controls:

   less crosswalks/master-matrix.md

   …or run it: describe your control posture in a small JSON file and cross-walk it against every framework at once with the atlas assessor (below).
4. Expose the atlas to agents over the JSON/MCP integration (see integrations/):

   python integrations/webhook.py

5. In CI, treat the atlas as a versioned reference and lint it against SOURCES.md:

   ./scripts/lint.sh

Frameworks covered

File	Framework	TL;DR
frameworks/soc2.md	SOC 2 (TSC)	5 Trust Services Criteria; attestation, not certification
frameworks/iso-27001.md	ISO/IEC 27001:2022	ISMS + 93 Annex A controls; certifiable
frameworks/nist-csf-2.0.md	NIST CSF 2.0	6 functions (Govern/Identify/Protect/Detect/Respond/Recover), 22 categories
frameworks/nist-800-53.md	NIST 800-53 r5	1,196 controls / 20 families (federal)
frameworks/nist-800-171.md	NIST 800-171	110 controls / 14 families (CUI)
frameworks/cmmc-2.0.md	CMMC 2.0	3 levels; L2 = the 110 of 800-171 r2
frameworks/gdpr.md	GDPR	EU personal-data law; privacy by design
frameworks/ccpa-cpra.md	CCPA/CPRA	California; thresholds + SPI class
frameworks/hipaa.md	HIPAA	US PHI; Privacy + Security Rules
frameworks/pci-dss-4.0.md	PCI DSS 4.0	cardholder data; phishing-resistant MFA
frameworks/eu-ai-act.md	EU AI Act	4 risk tiers; staged 2025–2028 timeline

Crosswalks

• crosswalks/soc2-iso27001.md — ~60–80% control overlap; reduces dual-audit effort up to ~40%.
• crosswalks/nistcsf-80053.md — CSF subcategory → 800-53 control mappings.
• crosswalks/cmmc-800171.md — CMMC L2 ≡ 800-171 r2 (110 controls).
• crosswalks/master-matrix.md — one table, all frameworks by theme.

See SOURCES.md for primary references.

atlas — run the crosswalks as a gap report

The master matrix isn't just a table to read — atlas.py turns it into an actionable, CI-gateable gap report. You describe your control posture per theme in a small JSON file; atlas cross-walks it against the six frameworks (SOC 2 · ISO 27001 · NIST CSF 2.0 · 800-53 r5 · 800-171 · PCI DSS 4.0) and tells you, per framework, which control groups are covered, partial, or missing — so you "implement once, satisfy many". Pure standard library, no dependencies.

Every framework reference it prints is transcribed verbatim from crosswalks/master-matrix.md. It's a planning aid, not an audit, and not legal advice.

# assess a posture against one framework
python -m atlas assess demos/01-saas-soc2/posture.json --framework soc2

# all six frameworks at once (implement-once-satisfy-many view)
python -m atlas assess demos/08-msp-multiframework/posture.json

# machine-readable exports: json · csv · markdown · sarif
python -m atlas assess demos/08-msp-multiframework/posture.json --format sarif > atlas.sarif

# CI gate: non-zero exit if any theme is partial/missing
python -m atlas assess posture.json --fail-on-gap

# explore the inputs
python -m atlas matrix        # the embedded theme matrix
python -m atlas frameworks    # known framework keys

A posture file (omitted themes are assessed as missing — silence is a gap):

{
  "org": "Acme, Inc.",
  "scope": ["soc2"],
  "controls": {
    "Access control": "implemented",
    "Crypto / data protection": "partial",
    "Logging & monitoring": "missing"
  }
}

Status values: implemented | partial | missing | n/a.

Export formats

--format	Use it for
table (default)	a quick human read in the terminal
json	feeding a GRC pipeline / opening tickets per finding
csv	an evidence-binder snapshot / spreadsheet
markdown	pasting into a readiness deck or PR
sarif	uploading gaps to a code-scanning / SARIF 2.1.0 dashboard

Live data feeds — real NIST 800-53 + ATT&CK, edge / air-gap deployable

The master matrix only stores a 800-53 family code per theme (AC, SC, AU, …). atlas feeds pulls two real, authoritative public feeds to turn those codes into something actionable — and it works fully offline for disconnected / classified / edge deployments.

Feed id	What it is	Source (keyless HTTPS)
oscal-800-53-rev5-catalog	NIST SP 800-53 rev5 control catalog, native OSCAL JSON	raw.githubusercontent.com/usnistgov/oscal-content/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json
attack-nist-mappings	Center for Threat-Informed Defense ATT&CK ↔ 800-53 crosswalk	raw.githubusercontent.com/center-for-threat-informed-defense/mappings-explorer/main/mappings/nist_800_53/attack-16.1/nist_800_53-rev5/enterprise/nist_800_53-rev5_attack-16.1-enterprise.json

The ingestion layer (datafeeds.py + data_feeds_2026.json, bundled) is pure standard library: keyless fetch → on-disk cache → offline re-serve → air-gap snapshot. atlas feeds only ever exposes these two compliance feeds.

# list this repo's feeds and their cache freshness
python -m atlas feeds list

# fetch + cache both feeds (online, one time)
python -m atlas feeds update

# enrich the matrix: official 800-53 family titles + how many ATT&CK
# techniques each family is documented to MITIGATE (real threat coverage)
python -m atlas feeds enrich

THEME                     800-53   FAMILY TITLE                          CTRLS   ATT&CK TECHNIQUES MITIGATED
Access control            AC       Access Control                           25                          382
Crypto / data protection  SC       System and Communications Protection     51                          244
Vendor / supply chain     SR       Supply Chain Risk Management             12                           22

Fold the enrichment into a gap report — every 800-53 finding gains the real NIST family title and its ATT&CK technique-coverage count:

python -m atlas assess posture.json --framework 800-53 --format json --enrich

Edge / air-gap (no network)

--offline serves from the on-disk cache and never touches the network; the cache location is COGNIS_FEEDS_CACHE (default ~/.cache/cognis-feeds).

# on an air-gapped host pointed at a pre-seeded cache
COGNIS_FEEDS_CACHE=/srv/feeds python -m atlas feeds enrich --offline
COGNIS_FEEDS_CACHE=/srv/feeds python -m atlas assess posture.json --enrich --offline

Move the cache across the air gap by snapshot (sneakernet):

python -m datafeeds snapshot-export feeds.tar.gz          # connected host
# … carry feeds.tar.gz across the gap …
COGNIS_FEEDS_CACHE=/srv/feeds python -m datafeeds snapshot-import feeds.tar.gz

Tests run with zero network: a trimmed sample of each feed is committed under tests/fixtures/cache/, and the tests point COGNIS_FEEDS_CACHE at it (see demos/09-feed-enrichment/). Defensive / authorized-use intelligence only.

Demos

Two layers, both driving the real API on real data (nothing mocked). See docs/DEMOS.md for the full guide and docs/ARCHITECTURE.md for how the pieces fit.

Runnable, narrated scenarios (demos/*.py) — pick the one for your role, or run them all. Offline, exit 0, standard library only:

PYTHONUTF8=1 python demos/run_all.py            # all five, in order
PYTHONUTF8=1 python demos/01_startup_first_soc2.py

Demo	Audience	What it shows
01_startup_first_soc2.py	Founders chasing first SOC 2	Readiness gut-check → prioritized punch list (stand up vs prove) + board coverage number
02_grc_implement_once.py	GRC / compliance leads	One baseline across all six frameworks at once; each gap's cross-framework blast radius
03_auditor_ci_gate.py	Auditors / CI engineers	Clean-run proof, --fail-on-gap exit codes, real SARIF 2.1.0 for code-scanning
04_security_engineer_threat_coverage.py	Security engineers	800-53 gaps as ATT&CK technique exposure (real OSCAL + CTID feeds, offline)
05_greenfield_assess_by_default.py	Pre-seed / greenfield	Empty posture → honest 0% roadmap; portable, framework-agnostic blueprint

Worked posture pairs (demos/<NN-name>/) — each pairs a realistic posture.json with a SCENARIO.md (data provenance, expected output, exact command, how to act). The runnable scenarios above load these same files:

Demo	Situation
01-saas-soc2	Series-B SaaS heading into its first SOC 2 Type II
02-fintech-pci	Payment facilitator on the road to PCI DSS 4.0
03-defense-cmmc-800171	DIB subcontractor scoping CMMC L2 / NIST 800-171 (CUI)
04-health-startup	Digital-health startup mapping SOC 2 and NIST CSF together
05-eu-ai-vendor	High-risk AI provider hardening its ISO 27001 ISMS
06-greenfield-baseline	Pre-seed: assess-by-default when you have nothing yet
07-iso-certification-prep	Clean run — --fail-on-gap as an ISO stage-2 CI gate
08-msp-multiframework	MSP shared baseline reported across all six frameworks at once
09-feed-enrichment	Air-gapped enclave: enrich 800-53 themes with real OSCAL titles + ATT&CK coverage, fully offline

Tests live in tests/ (python -m pytest -q).

How it fits

flowchart LR
  U[You / CI / Agent] --> R[compliance-atlas]
  R --> O[Outputs & artifacts]
  R --> M[MCP / JSON]
  M --> AI[AI agents]
  R --> S[Cognis Neural Suite]

Loading

Explore the suite → 🗂️ all tools · ⭐ awesome-cognis · 🔗 cognis-sources

Interoperability

compliance-atlas composes with the 300+ tool Cognis suite — JSON in/out and a shared OpenAI-compatible /v1 backbone. See INTEROP.md for the suite map, composition patterns, and reference stacks.

Integrations

Forward compliance-atlas's findings to STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks via cognis-connect. See INTEGRATIONS.md.