icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-15-maintenance-audit.md

@@ -0,0 +1,192 @@
+# Phase 15 — Maintenance Audit
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 15 |
+| Title | Maintenance Audit |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 10 (Security Scanning), Phase 11 (Compliance Workflow) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Outdated dependencies are the number one attack vector in modern software systems. Government and DoD applications face strict compliance requirements under NIST 800-53 SI-2 (Flaw Remediation), SA-22 (Unsupported System Components), and CM-3 (Configuration Change Control). Without continuous dependency monitoring, projects accumulate technical debt, fall out of compliance, and become vulnerable to known CVEs with published exploits.
+
+Manual dependency auditing is error-prone and does not scale across multi-language projects. Teams often discover vulnerabilities only during periodic security reviews, by which time the exposure window has been dangerously long. CISA Secure by Design Commitment 4 mandates timely security patch application, yet many organizations lack automated enforcement of remediation SLAs.
+
+ICDEV needs an automated maintenance audit system that continuously inventories dependencies across all six supported languages, checks for known vulnerabilities against advisory databases, enforces remediation SLAs by severity, computes a maintenance health score, and auto-remediates low-risk issues while escalating critical findings for human review.
+
+---
+
+## 2. Goals
+
+1. Continuously inventory all direct and transitive dependencies across Python, Java, JavaScript/TypeScript, Go, Rust, and C# projects
+2. Check dependencies against vulnerability advisory databases (NVD, OSV, language-native advisories) and map findings to CVE IDs with CVSS scores
+3. Enforce severity-based remediation SLAs: critical (48h), high (7d), medium (30d), low (90d)
+4. Compute a deterministic maintenance health score (0-100) that feeds deployment gates
+5. Auto-remediate medium and low severity vulnerabilities with test verification and rollback capability
+6. Generate CUI-marked audit reports with trend analysis across audit runs
+7. Feed results into SbD assessment (SbD-05 patch cadence, SbD-22 vulnerability scanning) and deployment gates
+8. Support air-gapped environments via offline mode with local advisory database snapshots
+
+---
+
+## 3. Architecture
+
+```
++------------------+     +---------------------+     +--------------------+
+| Dependency       |---->| Vulnerability       |---->| Maintenance        |
+| Scanner          |     | Checker             |     | Auditor            |
+| (per-language)   |     | (CVE lookup + SLA)  |     | (score + report)   |
++------------------+     +---------------------+     +--------------------+
+                                                            |
+                                                            v
+                                                     +--------------------+
+                                                     | Remediation        |
+                                                     | Engine             |
+                                                     | (auto-fix + test)  |
+                                                     +--------------------+
+                                                            |
+                                                            v
+                                                     +--------------------+
+                                                     | Verify + Audit     |
+                                                     | (re-scan + log)    |
+                                                     +--------------------+
+```
+
+The maintenance audit workflow is a 6-step pipeline:
+
+1. **Scan** -- Inventory all dependencies across detected languages using language-native manifest files (requirements.txt, package.json, pom.xml, go.mod, Cargo.toml, .csproj)
+2. **Check** -- Run vulnerability audit tools (pip-audit, npm audit, cargo-audit, etc.) and map to SLA deadlines
+3. **Audit** -- Compute maintenance score, evaluate gate, generate CUI-marked report with trend analysis
+4. **Remediate** -- Auto-fix eligible vulnerabilities (medium/low with fix available), create remediation branches, run tests
+5. **Verify** -- Re-run security scan and test suite to confirm fixes do not introduce regressions
+6. **Log** -- Record all actions in the append-only audit trail (NIST AU compliance)
+
+---
+
+## 4. Requirements
+
+### 4.1 Dependency Scanning
+
+#### REQ-15-001: Multi-Language Dependency Inventory
+The system SHALL inventory all direct dependencies across Python, Java, JavaScript/TypeScript, Go, Rust, and C# by parsing their respective manifest files.
+
+#### REQ-15-002: Staleness Classification
+The system SHALL classify each dependency's staleness as: current (0d), minor (1-30d behind latest), moderate (31-90d), major (91-180d), or critical (>180d behind latest).
+
+#### REQ-15-003: Air-Gapped Scanning
+The system SHALL support an `--offline` flag that inventories dependencies from manifest files without querying remote registries, setting staleness to -1 (unknown).
+
+### 4.2 Vulnerability Checking
+
+#### REQ-15-004: CVE Mapping
+The system SHALL map discovered vulnerabilities to CVE IDs, CVSS scores, affected version ranges, and fix availability status (fix_available, no_fix, workaround).
+
+#### REQ-15-005: SLA Assignment
+The system SHALL assign remediation deadlines based on severity: critical (48 hours), high (7 days), medium (30 days), low (90 days).
+
+### 4.3 Scoring and Reporting
+
+#### REQ-15-006: Maintenance Score
+The system SHALL compute a deterministic maintenance score (0-100) using the formula: start at 100, deduct -20/critical SLA overdue, -10/high, -5/medium, -2/low, -3/critical staleness dep, -1/major staleness dep, floor at 0.
+
+#### REQ-15-007: Gate Evaluation
+The system SHALL evaluate a deployment gate: PASS (score >= 80), WARN (50-79, non-blocking), FAIL (< 50, blocks deployment).
+
+#### REQ-15-008: CUI-Marked Reports
+The system SHALL generate markdown audit reports with CUI // SP-CTI banners at `reports/<project>/maintenance_audit_YYYY-MM-DD.md`.
+
+### 4.4 Remediation
+
+#### REQ-15-009: Auto-Remediation Rules
+The system SHALL auto-remediate medium and low severity vulnerabilities with available fixes. Critical and high severity SHALL require manual approval.
+
+#### REQ-15-010: Dry-Run Mode
+The system SHALL support a `--dry-run` flag that previews all remediation changes without modifying any files.
+
+#### REQ-15-011: Test Verification
+The system SHALL run the project test suite after applying remediation changes. If tests fail, the system SHALL rollback changes and flag for manual review.
+
+#### REQ-15-012: EOL Detection
+The system SHALL flag dependencies with no maintainer activity exceeding 1 year as unsupported per NIST SA-22 and recommend replacements.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `project_dependencies` | Dependency inventory: name, version, latest_version, staleness_days, language, manifest_file |
+| `dependency_vulnerabilities` | CVE findings: cve_id, cvss_score, severity, affected_versions, fix_available, sla_deadline, status |
+| `maintenance_audits` | Audit history: project_id, score, sla_compliance_pct, trend_json, report_path, timestamp |
+| `remediation_actions` | Fix records: vulnerability_id, action_type, branch_name, test_result, rollback_log, timestamp |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/maintenance/dependency_scanner.py` | Multi-language dependency inventory with staleness calculation |
+| `tools/maintenance/vulnerability_checker.py` | CVE lookup, CVSS scoring, SLA deadline assignment |
+| `tools/maintenance/maintenance_auditor.py` | Orchestrates full audit: score computation, trend analysis, CUI report generation |
+| `tools/maintenance/remediation_engine.py` | Auto-fix eligible vulnerabilities, branch creation, test verification, rollback |
+| `tools/mcp/maintenance_server.py` | MCP server exposing scan_dependencies, check_vulnerabilities, run_maintenance_audit, remediate tools |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D13 | Python `ast` for Python analysis; regex-based parsing for Java/C# | Air-gap safe, zero external dependencies |
+| D6 | Audit trail is append-only/immutable | NIST 800-53 AU compliance; no UPDATE/DELETE on audit records |
+| D66 | Provider abstraction (ABC + implementations) per language audit tool | Each language gets its own scanner chain (pip-audit, npm audit, cargo-audit, etc.) |
+
+---
+
+## 8. Security Gate
+
+**Maintenance Audit Gate:**
+- Score < 50 blocks deployment (FAIL)
+- 0 overdue critical SLA vulnerabilities permitted at deploy time
+- 0 overdue high SLA vulnerabilities permitted at deploy time
+- EOL dependencies flagged per NIST SA-22 must have documented risk acceptance or replacement plan
+- SBOM must be regenerated after any remediation
+
+---
+
+## 9. Commands
+
+```bash
+# Scan all dependencies
+python tools/maintenance/dependency_scanner.py --project-id "proj-123"
+
+# Check vulnerabilities against advisory databases
+python tools/maintenance/vulnerability_checker.py --project-id "proj-123"
+
+# Run full maintenance audit (score + report)
+python tools/maintenance/maintenance_auditor.py --project-id "proj-123"
+python tools/maintenance/maintenance_auditor.py --project-id "proj-123" --human
+
+# Preview remediation changes (dry-run)
+python tools/maintenance/remediation_engine.py --project-id "proj-123" --dry-run
+
+# Auto-fix eligible vulnerabilities
+python tools/maintenance/remediation_engine.py --project-id "proj-123" --auto
+
+# Verify post-remediation
+python tools/security/dependency_auditor.py --project-dir "/path/to/project"
+
+# Log to audit trail
+python tools/audit/audit_logger.py --event-type "maintenance.audit" --actor "maintenance-agent" --action "Maintenance audit complete" --project-id "proj-123"
+```

icdev/data/docs/features/phase-16-ato-acceleration.md

@@ -0,0 +1,228 @@
+# Phase 16 — ATO Acceleration
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 16 |
+| Title | ATO Acceleration |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 11 (Compliance Workflow), Phase 14 (SbD & IV&V) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Obtaining an Authorization to Operate (ATO) is the single largest bottleneck in deploying government and DoD applications. Traditional ATO processes are manual, paper-driven, and can take 12-18 months. Programs must satisfy multiple overlapping compliance frameworks simultaneously -- FedRAMP (Moderate and High baselines), CMMC (Level 2/3), NIST 800-53, and DoD IL requirements -- yet each framework is typically assessed in isolation, creating redundant effort and inconsistent control mappings.
+
+Furthermore, the shift from static point-in-time ATO to continuous ATO (cATO) demands automated evidence collection, freshness monitoring, and real-time compliance posture tracking. Without automation, evidence goes stale, POA&M items slip past deadlines, and programs lose their authorization at the worst possible time. Systems of record like eMASS and Xacta 360 require periodic sync, but manual data entry introduces errors and delays.
+
+ICDEV needs an ATO acceleration engine that pursues multiple compliance frameworks simultaneously through a shared NIST 800-53 control backbone, generates machine-readable OSCAL artifacts, synchronizes with eMASS and Xacta, and establishes continuous monitoring infrastructure for cATO readiness.
+
+---
+
+## 2. Goals
+
+1. Pursue first ATO across FedRAMP (Moderate and High), CMMC (Level 2/3), and DoD IL requirements simultaneously from a single NIST 800-53 control backbone
+2. Run framework-specific assessments (FedRAMP, CMMC, STIG, CSSP, SbD, IV&V) and generate consolidated reports
+3. Generate machine-readable OSCAL artifacts (SSP, POA&M, Assessment Results) for automated ingestion by assessment tools
+4. Synchronize control status, POA&M items, and artifacts with eMASS in hybrid or export mode
+5. Synchronize with Xacta 360 for organizations using that system of record
+6. Establish cATO continuous monitoring with automated evidence collection, freshness checks, and scheduling
+7. Track compliance velocity per SAFe Program Increment (PI) for program management visibility
+8. Support air-gapped environments via export mode for eMASS/Xacta sync
+
+---
+
+## 3. Architecture
+
+```
++-------------------+     +-------------------+     +-------------------+
+| Framework         |     | Crosswalk Engine  |     | OSCAL Generator   |
+| Selection +       |---->| (NIST 800-53 hub) |---->| (SSP, POAM, AR)   |
+| Gap Analysis      |     | (gap analysis)    |     |                   |
++-------------------+     +-------------------+     +-------------------+
+        |                                                   |
+        v                                                   v
++-------------------+     +-------------------+     +-------------------+
+| FedRAMP Assessor  |     | CMMC Assessor     |     | eMASS Sync        |
+| + Report Gen      |     | + Report Gen      |     | (hybrid/export)   |
++-------------------+     +-------------------+     +-------------------+
+        |                         |                         |
+        +----------+--------------+                         |
+                   v                                        v
+           +-------------------+                    +-------------------+
+           | cATO Monitor      |                    | Xacta Sync        |
+           | + Scheduler       |                    | (hybrid/export)   |
+           | + Evidence Collect |                    +-------------------+
+           +-------------------+
+                   |
+                   v
+           +-------------------+
+           | PI Compliance     |
+           | Tracker           |
+           +-------------------+
+```
+
+The ATO acceleration workflow proceeds in 6 phases:
+
+1. **Framework Selection & Baseline** -- Select target frameworks, run crosswalk gap analysis, compute baseline coverage
+2. **Control Implementation** -- Map NIST 800-53 controls; each implementation satisfies multiple frameworks via the crosswalk engine
+3. **Framework-Specific Assessments** -- Run FedRAMP, CMMC, STIG, CSSP, SbD, and IV&V assessments with individual report generation
+4. **Artifact Generation** -- Produce OSCAL (machine-readable) and human-readable SSP, POA&M, and control matrices
+5. **System of Record Sync** -- Push/pull to eMASS and Xacta 360 in hybrid or export mode
+6. **Continuous Monitoring** -- Establish cATO evidence baseline, schedule automated collection, monitor freshness
+
+---
+
+## 4. Requirements
+
+### 4.1 Multi-Framework Assessment
+
+#### REQ-16-001: Simultaneous Framework Pursuit
+The system SHALL support pursuing ATO across FedRAMP (Moderate and High), CMMC (Level 2 and 3), and DoD STIG/CSSP simultaneously from a single NIST 800-53 control backbone.
+
+#### REQ-16-002: Crosswalk Gap Analysis
+The system SHALL compute gap analysis per target framework using the crosswalk engine, identifying unimplemented controls and their cascade impact across all targeted frameworks.
+
+#### REQ-16-003: FedRAMP Assessment
+The system SHALL assess project compliance against FedRAMP Moderate or High baselines using the `fedramp_moderate_baseline.json` or `fedramp_high_baseline.json` catalogs.
+
+#### REQ-16-004: CMMC Assessment
+The system SHALL assess project compliance against CMMC Level 2 or Level 3 practices using the `cmmc_practices.json` catalog.
+
+### 4.2 OSCAL Artifact Generation
+
+#### REQ-16-005: OSCAL SSP Generation
+The system SHALL generate OSCAL-compliant System Security Plans in JSON format per NIST OSCAL specification.
+
+#### REQ-16-006: OSCAL POA&M Generation
+The system SHALL generate OSCAL-compliant Plans of Action and Milestones for open findings across all assessed frameworks.
+
+#### REQ-16-007: OSCAL Assessment Results
+The system SHALL generate OSCAL Assessment Results documenting the findings of each framework assessment.
+
+### 4.3 System of Record Integration
+
+#### REQ-16-008: eMASS Sync
+The system SHALL synchronize control status, POA&M items, artifacts, and test results with eMASS in hybrid mode (API when available) or export mode (air-gapped).
+
+#### REQ-16-009: Xacta 360 Sync
+The system SHALL synchronize with Xacta 360 in hybrid or export mode, supporting OSCAL artifact push.
+
+### 4.4 Continuous Monitoring (cATO)
+
+#### REQ-16-010: Evidence Baseline
+The system SHALL establish a cATO evidence baseline by collecting evidence for all critical and high-priority controls with timestamps.
+
+#### REQ-16-011: Evidence Freshness Monitoring
+The system SHALL monitor evidence freshness and flag controls where evidence exceeds configured staleness thresholds.
+
+#### REQ-16-012: Automated Evidence Scheduling
+The system SHALL schedule automated evidence collection runs on configurable intervals and execute due collections.
+
+#### REQ-16-013: PI Compliance Velocity
+The system SHALL track compliance implementation velocity per SAFe Program Increment, reporting controls implemented per PI and overall compliance score trend.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `fedramp_assessments` | FedRAMP assessment results per control with status and evidence |
+| `cmmc_assessments` | CMMC practice assessment results with status and evidence |
+| `oscal_artifacts` | Generated OSCAL documents: type (ssp, poam, ar), content_json, version |
+| `emass_sync_log` | eMASS synchronization records: direction, items synced, status, errors |
+| `xacta_sync_log` | Xacta 360 synchronization records: direction, items synced, status |
+| `cato_evidence` | Continuous monitoring evidence: control_id, evidence_type, collected_at, expires_at |
+| `cato_schedules` | Evidence collection schedules: control_id, frequency, last_run, next_due |
+| `pi_compliance_tracking` | PI-level compliance metrics: pi_id, controls_implemented, score, velocity |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/fedramp_assessor.py` | Assess against FedRAMP Moderate or High baseline |
+| `tools/compliance/fedramp_report_generator.py` | Generate FedRAMP assessment reports |
+| `tools/compliance/cmmc_assessor.py` | Assess against CMMC Level 2 or 3 practices |
+| `tools/compliance/cmmc_report_generator.py` | Generate CMMC assessment reports |
+| `tools/compliance/oscal_generator.py` | Generate OSCAL SSP, POA&M, and Assessment Results |
+| `tools/compliance/emass/emass_sync.py` | Bidirectional eMASS synchronization (hybrid/export) |
+| `tools/compliance/emass/emass_export.py` | Export controls and artifacts for eMASS import |
+| `tools/compliance/xacta/xacta_sync.py` | Bidirectional Xacta 360 synchronization |
+| `tools/compliance/xacta/xacta_export.py` | Export artifacts in OSCAL format for Xacta |
+| `tools/compliance/cato_monitor.py` | cATO evidence freshness monitoring and readiness scoring |
+| `tools/compliance/cato_scheduler.py` | Schedule and execute automated evidence collection |
+| `tools/compliance/pi_compliance_tracker.py` | Track compliance velocity per SAFe PI |
+| `tools/compliance/crosswalk_engine.py` | Multi-framework crosswalk gap analysis and coverage |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D111 | Dual-hub crosswalk model (NIST 800-53 US hub + ISO 27001 international hub) | Implement once at either hub, cascade to all frameworks; implement AC-2 to satisfy FedRAMP, CMMC, and 800-171 simultaneously |
+| D113 | Multi-regime deduplication via crosswalk | Assessing N frameworks produces 1 unified NIST control set, not N separate assessments |
+| D56 | SSP baseline selection is dynamic | Query DB for FIPS 199 categorization first, fall back to IL mapping |
+| D6 | Audit trail is append-only/immutable | All assessment results and sync operations are permanently recorded |
+
+---
+
+## 8. Security Gate
+
+**FedRAMP Gate:**
+- 0 other_than_satisfied on high-priority controls
+- Encryption must be FIPS 140-2 validated
+
+**CMMC Gate:**
+- 0 not_met on Level 2 practices
+- Evidence current within 90 days
+
+**cATO Gate:**
+- 0 expired evidence on critical controls
+- Readiness score >= 50%
+
+---
+
+## 9. Commands
+
+```bash
+# Crosswalk gap analysis
+python tools/compliance/crosswalk_engine.py --project-id "proj-123" --target fedramp-high --gap-analysis
+python tools/compliance/crosswalk_engine.py --project-id "proj-123" --coverage
+
+# FedRAMP assessment and report
+python tools/compliance/fedramp_assessor.py --project-id "proj-123" --baseline moderate
+python tools/compliance/fedramp_report_generator.py --project-id "proj-123"
+
+# CMMC assessment and report
+python tools/compliance/cmmc_assessor.py --project-id "proj-123" --level 2
+python tools/compliance/cmmc_report_generator.py --project-id "proj-123"
+
+# OSCAL artifact generation
+python tools/compliance/oscal_generator.py --project-id "proj-123" --artifact all
+
+# eMASS sync
+python tools/compliance/emass/emass_sync.py --project-id "proj-123" --mode hybrid
+python tools/compliance/emass/emass_export.py --project-id "proj-123" --type controls
+
+# Xacta sync
+python tools/compliance/xacta/xacta_sync.py --project-id "proj-123" --mode hybrid
+
+# cATO monitoring
+python tools/compliance/cato_monitor.py --project-id "proj-123" --readiness
+python tools/compliance/cato_monitor.py --project-id "proj-123" --check-freshness
+python tools/compliance/cato_scheduler.py --project-id "proj-123" --run-due
+
+# PI compliance tracking
+python tools/compliance/pi_compliance_tracker.py --project-id "proj-123" --velocity
+```

icdev/data/docs/features/phase-17-multi-framework-compliance.md

@@ -0,0 +1,223 @@
+# Phase 17 — Multi-Framework Compliance
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 17 |
+| Title | Multi-Framework Compliance |
+| Status | Implemented |
+| Priority | P0 |
+| Dependencies | Phase 11 (Compliance Workflow), Phase 16 (ATO Acceleration) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Government and defense applications must comply with multiple overlapping compliance frameworks simultaneously. A single DoD system may need to satisfy NIST 800-53, FedRAMP High, CMMC Level 2, NIST 800-171, and DoD CSSP requirements -- all of which share significant control overlap but use different taxonomies, identifiers, and assessment criteria. Without a unified compliance engine, organizations implement the same security control multiple times under different names, waste assessment resources, and produce inconsistent compliance documentation.
+
+The international dimension compounds this challenge. Organizations operating globally must also satisfy ISO/IEC 27001:2022, which uses an entirely different control structure than the NIST-based US frameworks. Manually mapping between US and international frameworks is error-prone and rarely maintained as frameworks evolve independently.
+
+ICDEV needs a dual-hub crosswalk engine that uses NIST 800-53 Rev 5 as the US hub and ISO/IEC 27001:2022 as the international hub, connected by a bidirectional bridge. Implementing a control at either hub should automatically cascade satisfaction to all mapped frameworks, eliminating redundant work and ensuring consistent compliance posture across all regimes.
+
+---
+
+## 2. Goals
+
+1. Implement a dual-hub crosswalk engine with NIST 800-53 as the US hub and ISO 27001 as the international hub, connected by a bidirectional bridge
+2. Enable single-control implementation to cascade across all mapped frameworks (e.g., implementing AC-2 satisfies FedRAMP AC-2, 800-171 3.1.1, CMMC AC.L2-3.1.1)
+3. Provide FedRAMP assessment and report generation for both Moderate and High baselines
+4. Provide CMMC assessment and report generation for Level 2 and Level 3
+5. Support classification-aware markings (CUI for IL4/IL5, SECRET for IL6) via the classification manager
+6. Generate OSCAL machine-readable artifacts for automated compliance tooling
+7. Integrate with eMASS and Xacta 360 for system of record synchronization
+8. Enable cATO continuous monitoring with evidence freshness tracking and automated scheduling
+
+---
+
+## 3. Architecture
+
+```
+                    +---------------------------+
+                    |    ISO/IEC 27001:2022     |
+                    |   (International Hub)      |
+                    +-------------+-------------+
+                                  |
+                    +-------------v-------------+
+                    | iso27001_nist_bridge.json  |
+                    | (Bidirectional Bridge)     |
+                    +-------------+-------------+
+                                  |
++------------------+  +-----------v-----------+  +------------------+
+| FedRAMP          |  |   NIST 800-53 Rev 5   |  | CMMC             |
+| (Mod/High)       |<-|     (US Hub)           |->| (Level 2/3)      |
++------------------+  +-----------+-----------+  +------------------+
+                                  |
+              +-------------------+-------------------+
+              |                   |                   |
+     +--------v------+  +--------v------+  +---------v-----+
+     | NIST 800-171  |  | DoD CSSP      |  | Other US      |
+     | (3.x.x)       |  | (DI 8530.01)  |  | Frameworks    |
+     +---------------+  +---------------+  +---------------+
+```
+
+The crosswalk engine uses a dual-hub model (ADR D111):
+
+- **US Hub**: NIST 800-53 Rev 5 -- all domestic frameworks (FedRAMP, CMMC, 800-171, CSSP, CJIS, HIPAA, etc.) map directly to NIST controls
+- **International Hub**: ISO/IEC 27001:2022 -- international frameworks map via the ISO hub
+- **Bridge**: `iso27001_nist_bridge.json` connects the two hubs bidirectionally
+
+When a NIST 800-53 control is implemented, the crosswalk engine automatically marks the corresponding FedRAMP control, CMMC practice, 800-171 requirement, and any other mapped framework requirement as satisfied. This eliminates redundant assessment work and ensures consistency.
+
+---
+
+## 4. Requirements
+
+### 4.1 Crosswalk Engine
+
+#### REQ-17-001: Dual-Hub Crosswalk
+The system SHALL implement a dual-hub crosswalk model with NIST 800-53 Rev 5 as the US hub and ISO/IEC 27001:2022 as the international hub, connected by `iso27001_nist_bridge.json`.
+
+#### REQ-17-002: Cascade Satisfaction
+When a NIST 800-53 control is marked as satisfied, the system SHALL automatically cascade that status to all mapped framework controls (FedRAMP, CMMC, 800-171, CSSP, and any additional mapped frameworks).
+
+#### REQ-17-003: Coverage Computation
+The system SHALL compute coverage percentage per framework showing satisfied, partially satisfied, and not satisfied controls.
+
+#### REQ-17-004: Gap Analysis
+The system SHALL identify gaps per target framework, showing which NIST 800-53 controls need implementation to achieve full coverage.
+
+### 4.2 Framework Assessments
+
+#### REQ-17-005: FedRAMP Assessor
+The system SHALL assess compliance against FedRAMP Moderate and High baselines using `fedramp_moderate_baseline.json` and `fedramp_high_baseline.json` catalogs with per-control status tracking.
+
+#### REQ-17-006: CMMC Assessor
+The system SHALL assess compliance against CMMC Level 2 and Level 3 practices using `cmmc_practices.json` with per-practice status and evidence tracking.
+
+#### REQ-17-007: Framework Report Generation
+The system SHALL generate human-readable markdown assessment reports for each framework with CUI markings, finding details, and remediation guidance.
+
+### 4.3 Classification and Markings
+
+#### REQ-17-008: Classification Manager
+The system SHALL apply classification markings appropriate to impact level: CUI // SP-CTI for IL4/IL5, SECRET for IL6, via `classification_manager.py`.
+
+#### REQ-17-009: Dynamic Marking Application
+Classification markings SHALL be applied at artifact generation time (inline, not post-processing) per ADR D5.
+
+### 4.4 Artifact and Integration
+
+#### REQ-17-010: OSCAL Generation
+The system SHALL generate OSCAL-compliant artifacts (SSP, POA&M, Assessment Results) in JSON format per the NIST OSCAL specification.
+
+#### REQ-17-011: eMASS Integration
+The system SHALL synchronize controls, POA&M items, and artifacts with eMASS in hybrid mode (API when available) or export mode (file-based for air-gapped).
+
+#### REQ-17-012: cATO Monitoring
+The system SHALL continuously monitor evidence freshness for all critical controls and alert when evidence exceeds configured staleness thresholds.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `fedramp_assessments` | FedRAMP assessment results per control: status, evidence, baseline |
+| `cmmc_assessments` | CMMC practice assessment results: status, evidence, level |
+| `oscal_artifacts` | OSCAL document storage: artifact_type, content_json, version, generated_at |
+| `emass_sync_log` | eMASS sync records: direction, items_synced, status, errors, timestamp |
+| `xacta_sync_log` | Xacta sync records: direction, items_synced, status, timestamp |
+| `cato_evidence` | Continuous monitoring evidence: control_id, evidence_type, collected_at, expires_at |
+| `cato_schedules` | Evidence collection schedules: control_id, frequency, last_run, next_due |
+| `pi_compliance_tracking` | PI-level compliance velocity: pi_id, controls_implemented, score |
+| `crosswalk_bridges` | Framework-to-framework control mappings for the dual-hub model |
+| `framework_catalog_versions` | Independent versioning per framework catalog |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/crosswalk_engine.py` | Dual-hub crosswalk: query, gap analysis, coverage, cascade |
+| `tools/compliance/classification_manager.py` | Impact-level-aware CUI/SECRET marking generation |
+| `tools/compliance/fedramp_assessor.py` | FedRAMP Moderate/High baseline assessment |
+| `tools/compliance/fedramp_report_generator.py` | FedRAMP human-readable report generation |
+| `tools/compliance/cmmc_assessor.py` | CMMC Level 2/3 practice assessment |
+| `tools/compliance/cmmc_report_generator.py` | CMMC human-readable report generation |
+| `tools/compliance/oscal_generator.py` | OSCAL SSP, POA&M, and Assessment Results generation |
+| `tools/compliance/emass/emass_sync.py` | Bidirectional eMASS synchronization |
+| `tools/compliance/emass/emass_export.py` | File-based eMASS export for air-gapped environments |
+| `tools/compliance/xacta/xacta_sync.py` | Bidirectional Xacta 360 synchronization |
+| `tools/compliance/cato_monitor.py` | cATO evidence freshness and readiness monitoring |
+| `tools/compliance/cato_scheduler.py` | Automated evidence collection scheduling |
+| `tools/compliance/pi_compliance_tracker.py` | PI-level compliance velocity tracking |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D111 | Dual-hub crosswalk: NIST 800-53 (US) + ISO 27001 (international) + bridge | Implement once at either hub, cascade everywhere; eliminates redundant assessment work |
+| D112 | Framework catalogs versioned independently | Update one framework JSON catalog without touching others |
+| D113 | Multi-regime deduplication via crosswalk | N frameworks produce 1 unified NIST control set, not N separate assessments |
+| D5 | CUI markings applied at generation time (inline) | Markings are never post-processed; classification is part of artifact creation |
+| D56 | SSP baseline selection is dynamic | Query DB for FIPS 199 categorization, fall back to IL mapping |
+
+---
+
+## 8. Security Gate
+
+**FedRAMP Gate:**
+- 0 other_than_satisfied on high-priority controls
+- Encryption FIPS 140-2 required
+
+**CMMC Gate:**
+- 0 not_met Level 2 practices
+- Evidence current within 90 days
+
+**cATO Gate:**
+- 0 expired evidence on critical controls
+- Readiness >= 50%
+
+---
+
+## 9. Commands
+
+```bash
+# Crosswalk queries
+python tools/compliance/crosswalk_engine.py --control AC-2
+python tools/compliance/crosswalk_engine.py --project-id "proj-123" --coverage
+python tools/compliance/crosswalk_engine.py --project-id "proj-123" --target fedramp-moderate --gap-analysis
+
+# Classification markings
+python tools/compliance/classification_manager.py --impact-level IL5
+
+# FedRAMP
+python tools/compliance/fedramp_assessor.py --project-id "proj-123" --baseline moderate
+python tools/compliance/fedramp_report_generator.py --project-id "proj-123"
+
+# CMMC
+python tools/compliance/cmmc_assessor.py --project-id "proj-123" --level 2
+python tools/compliance/cmmc_report_generator.py --project-id "proj-123"
+
+# OSCAL generation
+python tools/compliance/oscal_generator.py --project-id "proj-123" --artifact ssp
+
+# eMASS integration
+python tools/compliance/emass/emass_sync.py --project-id "proj-123" --mode hybrid
+python tools/compliance/emass/emass_export.py --project-id "proj-123" --type controls
+
+# cATO monitoring
+python tools/compliance/cato_monitor.py --project-id "proj-123" --check-freshness
+python tools/compliance/cato_scheduler.py --project-id "proj-123" --run-due
+
+# PI tracking
+python tools/compliance/pi_compliance_tracker.py --project-id "proj-123" --velocity
+```