Add NIST 800-53 Control Viewer with gap analysis and dashboard

ggbecker · ggbecker · commit 03780a7046fa · 2026-04-29T14:57:03.000+02:00
Add interactive web-based viewer for NIST 800-53 control files with comprehensive gap analysis, statistics dashboard, and backlog management. Features: - Dashboard view with coverage statistics and product comparison - Gap analysis showing controls without rules - Interactive filtering by family, baseline level, status, and gaps - Select All/Deselect All checkboxes for all filter categories - Full OSCAL metadata integration (description, guidance, parameters) - TODO/backlog management per control with localStorage persistence - Self-contained HTML with embedded data (works with file:// protocol) Components: - utils/nist_sync/generate_nist_viewer.py: Data generator script - utils/nist_sync/nist_viewer_template.html: Interactive HTML template - utils/nist_sync/VIEWER_README.md: Comprehensive documentation - cmake/SSGCommon.cmake: CMake macro for building viewer - .github/workflows/gh-pages.yaml: GitHub Pages integration Build with: ninja nist-viewer Published at: https://complianceascode.github.io/content-pages/nist-viewer/
diff --git a/.github/workflows/gh-pages.yaml b/.github/workflows/gh-pages.yaml
@@ -1,11 +1,11 @@
 name: Github Pages
 on:
   push:
-    branches: [ 'master' ]
+    branches: ['master']
   pull_request:
-    branches: [ 'master',  'oscal-update-*' ]
+    branches: ['master', 'oscal-update-*']
   merge_group:
-    branches: [ 'master' ]
+    branches: ['master']
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.number || github.run_id }}
   cancel-in-progress: true
@@ -19,13 +19,17 @@ jobs:
       PAGES_DIR: __pages
     steps:
       - name: Install Deps
-        run: dnf install -y cmake git ninja-build openscap-utils python3-pyyaml python3-jinja2 python3-pytest ansible-lint libxslt python3-pip rsync python3-lxml python3-setuptools
+        run: |
+          dnf install -y \
+            cmake git ninja-build openscap-utils python3-pyyaml \
+            python3-jinja2 python3-pytest ansible-lint libxslt \
+            python3-pip rsync python3-lxml python3-setuptools
       - name: Install deps python
         run: pip3 install json2html prometheus_client
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-            persist-credentials: false
+          persist-credentials: false
       - name: Build
         run: cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug
         working-directory: ./build
@@ -38,8 +42,14 @@ jobs:
       - name: Render Policies (Using control files)
         run: ninja render-policies -j$(nproc)
         working-directory: ./build
+      - name: Generate NIST 800-53 Control Viewer
+        run: ninja nist-viewer
+        working-directory: ./build
       - name: Generate Prometheus Metrics
-        run: utils/controleval_metrics.py prometheus -p fedora ocp4 rhcos4 rhel10 rhel9 rhel8 sle12 sle15 -f ./build/policies_metrics
+        run: |
+          utils/controleval_metrics.py prometheus \
+            -p fedora ocp4 rhcos4 rhel10 rhel9 rhel8 sle12 sle15 \
+            -f ./build/policies_metrics
         env:
           PYTHONPATH: ${{ github.workspace }}
       - name: Generate HTML pages
@@ -51,8 +61,11 @@ jobs:
         run:
           git config --global --add safe.directory "$GITHUB_WORKSPACE"
       - name: Deploy
-        if: ${{ github.event_name == 'push' && github.repository == 'ComplianceAsCode/content' && github.ref == 'refs/heads/master'  }}
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        if: >-
+          ${{ github.event_name == 'push' &&
+          github.repository == 'ComplianceAsCode/content' &&
+          github.ref == 'refs/heads/master' }}
+        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f
         with:
           branch: main # The branch the action should deploy to.
           folder: ${{ env.PAGES_DIR }} # The folder the action should deploy.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -379,6 +379,9 @@ add_custom_target(html-profile-stats)
 
 add_custom_target(render-policies)
 
+# NIST 800-53 Control Viewer with Gap Analysis
+ssg_generate_nist_viewer()
+
 ssg_build_man_page()
 
 if(SSG_PRODUCT_AL2023)
diff --git a/cmake/SSGCommon.cmake b/cmake/SSGCommon.cmake
@@ -654,6 +654,26 @@ macro(ssg_render_policies_for_product PRODUCT)
     )
 endmacro()
 
+macro(ssg_generate_nist_viewer)
+    # Generate NIST 800-53 control viewer with gap analysis
+    # This generates for all RHEL products at once
+    set(NIST_PRODUCTS rhel8 rhel9 rhel10)
+    add_custom_command(
+        OUTPUT "${CMAKE_BINARY_DIR}/nist-controls-viewer/nist-controls-viewer.html"
+        COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_BINARY_DIR}/nist-controls-viewer"
+        COMMAND env "PYTHONPATH=$ENV{PYTHONPATH}" "${Python_EXECUTABLE}" "${CMAKE_SOURCE_DIR}/utils/nist_sync/generate_nist_viewer.py"
+            --products ${NIST_PRODUCTS}
+            --output-dir "${CMAKE_BINARY_DIR}/nist-controls-viewer"
+            --repo-root "${CMAKE_SOURCE_DIR}"
+        COMMAND ${CMAKE_COMMAND} -E touch "${CMAKE_BINARY_DIR}/nist-controls-viewer/nist-controls-viewer.html"
+        COMMENT "[nist-viewer] generating NIST 800-53 control viewer with gap analysis"
+    )
+
+    add_custom_target(nist-viewer
+        DEPENDS "${CMAKE_BINARY_DIR}/nist-controls-viewer/nist-controls-viewer.html"
+    )
+endmacro()
+
 macro(ssg_make_all_tables PRODUCT)
     add_custom_command(
         OUTPUT "${CMAKE_BINARY_DIR}/tables/tables-${PRODUCT}-all.html"
diff --git a/utils/generate_html_pages.sh b/utils/generate_html_pages.sh
@@ -112,6 +112,14 @@ if [ $retVal -ne 0 ]; then
     exit 1
 fi
 
+# Copy NIST 800-53 Control Viewer
+NIST_VIEWER_DIR="$PAGES_DIR/nist-viewer"
+if [ -d "build/nist-controls-viewer" ]; then
+    mkdir -p "$NIST_VIEWER_DIR"
+    cp -rf build/nist-controls-viewer/* "$NIST_VIEWER_DIR/"
+    echo "NIST 800-53 Control Viewer copied to $NIST_VIEWER_DIR"
+fi
+
 # Generate Prometheus Stats
 PROMETHEUS_STATS_DIR="$PAGES_DIR/prometheus_stats"
 mkdir -p "$PROMETHEUS_STATS_DIR"
@@ -134,6 +142,7 @@ echo "<li><a href=\"guides/index.html\">Guides</a></li>" >> index.html
 echo "<li><a href=\"tables/index.html\">Mapping Tables</a></li>" >> index.html
 echo "<li><a href=\"srg_mapping/index.html\">SRG Mapping Tables</a></li>" >> index.html
 echo "<li><a href=\"rendered-policies/index.html\">Rendered Policies</a></li>" >> index.html
+echo "<li><a href=\"nist-viewer/nist-controls-viewer.html\">NIST 800-53 Control Viewer & Gap Analysis</a></li>" >> index.html
 echo "<li><a href=\"components/index.html\">Components</a></li>" >> index.html
 echo "<li><a href=\"prometheus_stats/policies_metrics\">Prometheus Policies Metrics</a></li>" >> index.html
 echo "</ul>" >> index.html
diff --git a/utils/nist_sync/VIEWER_README.md b/utils/nist_sync/VIEWER_README.md
@@ -0,0 +1,225 @@
+# NIST 800-53 Control Viewer & Gap Analysis
+
+Interactive web-based viewer for NIST 800-53 control files with comprehensive gap analysis and backlog management features.
+
+## Features
+
+### Dashboard View
+- **Overall Coverage Statistics**: Total controls, automated, manual, and pending counts with percentages
+- **Gap Analysis**: Visual representation of controls without rules
+- **Product Comparison**: Side-by-side comparison of rhel8, rhel9, and rhel10 coverage
+- **Family Coverage Chart**: Bar chart showing automation coverage by control family
+- **Baseline Level Breakdown**: Distribution across LOW, MODERATE, and HIGH baselines
+- **Top Gaps List**: Quick view of controls that need rule implementation
+
+### Controls View
+- **Advanced Filtering**:
+  - Filter by control family (AC, AU, CM, IA, SC, SI, etc.)
+  - Filter by baseline level (Low, Moderate, High)
+  - Filter by status (Automated, Manual, Pending)
+  - Filter by gap status (With Rules, Without Rules)
+  - Full-text search across control IDs, titles, and descriptions
+
+- **Control Details**:
+  - OSCAL metadata (description, guidance, parameters)
+  - Implementation status
+  - Rule listings
+  - Related controls with clickable links
+  - Baseline level applicability
+
+- **Backlog Management**:
+  - Add TODO items per control
+  - Mark items as complete
+  - Delete completed items
+  - Persistent storage in browser localStorage
+
+## Building the Viewer
+
+### Using CMake (Recommended)
+
+```bash
+# Build everything including the NIST viewer
+cd build
+cmake .. -G Ninja
+ninja nist-viewer
+
+# The viewer will be generated at:
+# build/nist-controls-viewer/nist-controls-viewer.html
+```
+
+### Manual Generation
+
+```bash
+cd utils/nist_sync
+
+# Generate the viewer for specific products
+python3 generate_nist_viewer.py \
+  --products rhel8 rhel9 rhel10 \
+  --output-dir ../../build/nist-controls-viewer \
+  --repo-root ../..
+
+# Open the viewer
+open ../../build/nist-controls-viewer/nist-controls-viewer.html
+```
+
+## Published Version
+
+The viewer is automatically published to GitHub Pages via the `gh-pages` workflow:
+
+**URL**: https://complianceascode.github.io/content-pages/nist-viewer/nist-controls-viewer.html
+
+The published version updates automatically when changes are pushed to the master branch.
+
+## Data Structure
+
+The viewer has all control data embedded directly in the HTML file (as `EMBEDDED_DATA` JavaScript constant). This allows the viewer to work when opened directly as a local file without CORS issues.
+
+A separate `nist-controls-data.json` file is also generated for reference and debugging purposes.
+
+The data structure contains:
+
+```json
+{
+  "products": {
+    "rhel9": {
+      "metadata": { /* Product metadata */ },
+      "controls": [
+        {
+          "id": "ac-1",
+          "title": "Access Control Policy and Procedures",
+          "levels": ["low", "moderate", "high"],
+          "rules": ["rule_id_1", "rule_id_2"],
+          "status": "automated",
+          "description": "OSCAL description...",
+          "guidance": "OSCAL guidance...",
+          "parameters": [ /* ODPs */ ],
+          "related_controls": ["ac-2", "pm-9"],
+          "has_rules": true,
+          "is_automated": true
+        }
+      ]
+    }
+  },
+  "statistics": {
+    "rhel9": {
+      "total": 1196,
+      "automated": 850,
+      "manual": 50,
+      "pending": 296,
+      "with_rules": 900,
+      "without_rules": 296
+    }
+  },
+  "families": [ /* 21 control families */ ]
+}
+```
+
+## Gap Analysis Features
+
+### Gap Identification
+Controls are marked as "gaps" when:
+- `status: pending` - No implementation exists
+- `has_rules: false` - No rules are mapped to the control
+
+### Gap Visualization
+- **Dashboard**: Red indicator showing total gaps with percentage
+- **Controls List**: Red dot indicator on gap controls
+- **Filter**: Dedicated "Without Rules" filter to show only gaps
+- **Gap List**: Top 20 gaps displayed on dashboard
+
+### Addressing Gaps
+1. Navigate to a gap control in the Controls view
+2. Add TODO items describing what needs to be implemented
+3. Create the necessary rules in the repository
+4. Regenerate the viewer to see updated statistics
+
+## TODO/Backlog Management
+
+### Adding TODOs
+1. Select a control
+2. Scroll to the "TODO / Backlog Items" section
+3. Type your TODO item
+4. Click "Add"
+
+### Managing TODOs
+- **Check**: Mark as complete
+- **Uncheck**: Mark as incomplete
+- **Delete**: Remove the item
+
+TODOs are stored in browser localStorage, so they persist across sessions but are local to your browser.
+
+## Customization
+
+### Modifying the Template
+Edit `utils/nist_sync/nist_viewer_template.html` to customize:
+- Styling (CSS in `<style>` section)
+- Layout (HTML structure)
+- Behavior (JavaScript functions)
+
+### Adding New Statistics
+Modify `generate_nist_viewer.py`:
+1. Update `generate_viewer_data()` to calculate new statistics
+2. Update the template to display them
+
+### Regenerate
+After making changes:
+```bash
+ninja nist-viewer
+```
+
+## Workflow Integration
+
+The viewer is automatically built and published by `.github/workflows/gh-pages.yaml`:
+
+```yaml
+- name: Generate NIST 800-53 Control Viewer
+  run: ninja nist-viewer
+  working-directory: ./build
+```
+
+The generated files are copied to the GitHub Pages site by `utils/generate_html_pages.sh`.
+
+## Browser Compatibility
+
+The viewer uses modern JavaScript features and requires:
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+No external dependencies - all functionality is self-contained in a single HTML file.
+
+## Troubleshooting
+
+### "Error loading data"
+- The data should be embedded in the HTML file - regenerate the viewer with `ninja nist-viewer`
+- If you modified the template, ensure the `/* DATA_PLACEHOLDER */` comment exists in the script section
+- Check browser console for specific error messages
+- The HTML file should be around 7MB - if it's much smaller, the data wasn't embedded properly
+
+### Controls not showing
+- Check filter settings - try resetting all filters
+- Verify the data file contains controls for the selected product
+
+### TODOs not persisting
+- localStorage must be enabled in your browser
+- Check browser privacy settings
+- TODOs are per-browser and per-domain
+
+### Dashboard not rendering
+- Check browser console for JavaScript errors
+- Ensure the JSON data loaded successfully
+- Try refreshing the page
+
+## Development
+
+To develop new features:
+
+1. Edit `nist_viewer_template.html`
+2. Test locally by opening the generated HTML file
+3. Regenerate after changes: `ninja nist-viewer`
+4. Commit both the template and updated CMake files
+
+## License
+
+Same license as the ComplianceAsCode/content project (BSD-3-Clause).
diff --git a/utils/nist_sync/generate_nist_viewer.py b/utils/nist_sync/generate_nist_viewer.py
diff --git a/utils/nist_sync/nist_viewer_template.html b/utils/nist_sync/nist_viewer_template.html
