Skip to content

CLAUDE.md

Latest commit

 

History

History
101 lines (77 loc) · 3.58 KB

CLAUDE.md

File metadata and controls

101 lines (77 loc) · 3.58 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a web application for viewing and managing security control overlays based on NIST SP 800-53 controls. It's designed for security professionals working with frontier AI development, displaying NIST controls with various security overlays including SL5 (Security Level 5), FedRAMP, CNSSI 1253, and others.

Architecture

  • Frontend: Single-page application using vanilla JavaScript embedded in index.html (no build process)
  • Data Pipeline: Python scripts extract data from PDF overlays → JSON files → JavaScript web app
  • Hosting: GitLab Pages (https://gitlab.com/sl5tf/control-overlays-selector)

Common Development Commands

Python Data Extraction

# Extract overlay data from PDFs (requires PyMuPDF/fitz)
python sl5_overlay/extract_sl5_overlay.py sl5_overlay/sl5_overlay.pdf
python cnssi_1253/extract_cnssi_1253.py cnssi_1253/cnssi_1253_overlay.pdf
python classified_information/extract_classified_information_overlay.py classified_information/classified_information_overlay.pdf

# Debug specific pages
python sl5_overlay/extract_sl5_overlay.py sl5_overlay/sl5_overlay.pdf --debug-page 10

# Merge CNSSI data
python cnssi_1253/cnssi_merger.py

# Sort NIST controls naturally
python nist_catalog/nist_sorter.py input.json output.json

Development

  • No build process - edit index.html directly
  • No package manager - pure vanilla JavaScript
  • Deploy by pushing to GitLab (configured in .gitlab-ci.yml)

Code Structure

Frontend (index.html)

  • Data Loading: loadData() fetches all JSON files
  • Rendering: renderControls() displays filtered controls
  • State: Global variables store control data and overlay states
  • Events: Toggle overlays, search, filter by family, expand/collapse controls

Data Pipeline

Each overlay directory contains:

  • PDF source document
  • Python extractor script (extract_*.py)
  • Generated JSON data file
  • Common pattern: PDF → Python extractor → JSON → Web app

Key Data Structures

// Control format
{
  "id": "AC-1",
  "text": "Control description...",
  "family": "Access Control",
  "enhancements": [...],
  "discussion": "..."
}

// Overlay format varies by type
// SL5: {"selected": true/false, "attributes": {...}}
// CNSSI: {"control_text": "", "defined_value": "", "selected": true/false}

Important Patterns

  1. Control ID Format: [A-Z]{2}-\d{1,2} (base) or [A-Z]{2}-\d{1,2}\(\d+\) (enhancement)
  2. Overlay Toggle Logic: Each overlay can be enabled/disabled, affecting control visibility
  3. Enhancement Display: Controls with enhancements have expandable sections
  4. Modal System: Click control IDs to preview in modal
  5. Natural Sorting: Controls sorted as AC-1, AC-2, ..., AC-10 (not lexically)

Adding New Overlays

  1. Create directory for new overlay
  2. Add PDF source document
  3. Create Python extractor following existing patterns (see sl5_overlay/extract_sl5_overlay.py as template)
  4. Generate JSON data
  5. Add overlay loading in loadData() function
  6. Add toggle UI in overlay panel
  7. Update getOverlayInfo() to handle new overlay format

Testing

No automated tests exist. Manual testing process:

  1. Run Python extractors on PDFs
  2. Verify JSON output structure
  3. Load in browser and test filtering/toggling
  4. Check control display and enhancements
  5. Test search functionality

Dependencies

  • Python: PyMuPDF (fitz) for PDF extraction
  • JavaScript: None (vanilla JS only)
  • Deployment: GitLab Pages via CI/CD