From 57d572eaaa68ee002d373709a24a274192bb968b Mon Sep 17 00:00:00 2001 From: Luis Cosio Date: Sun, 13 Sep 2026 09:44:11 -0600 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20make=20AGENTS.md=20canon?= =?UTF-8?q?ical,=20CLAUDE.md=20a=20shim?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md is read by every agent tool; CLAUDE.md now imports it so the guidance lives in one file instead of two that drift. Claude-Session: https://claude.ai/code/session_0165h5hvmWJfxaEN4y9t5m1U --- AGENTS.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 111 +----------------------------------------------------- README.md | 2 +- 3 files changed, 112 insertions(+), 111 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61ea861 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,110 @@ +# AGENTS.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 that constitute IL6 (Information Level 6) — the DoD standard for cloud service providers working with classified secret information. It displays NIST SP 800-53 controls with security overlays including FedRAMP High, CNSSI 1253, Classified Information Overlay, and FedRAMP+. + +## 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**: https://il6.sl5taskforce.org/ (GitHub: https://github.com/securitylevel5/il6-control-catalog) + +## Common Development Commands + +### Python Data Extraction + +Python 3.13 (pinned in `.python-version`), managed with `uv`. Never use bare `pip` or conda. + +```bash +# One-time environment setup +uv venv --python 3.13 +uv pip install -r requirements.txt + +# Extract overlay data from PDFs (requires PyMuPDF/fitz) +uv run python cnssi_1253/extract_cnssi_1253.py cnssi_1253/CNSSI_1253_2022.pdf +uv run python classified_information/extract_classified_information.py classified_information/classified_information_overlay_2022.pdf + +# Debug specific pages +uv run python cnssi_1253/extract_cnssi_1253.py cnssi_1253/CNSSI_1253_2022.pdf --debug-page 10 + +# Sort NIST controls naturally +uv run python nist_catalog/nist_sorter.py input.json output.json +``` + +**Extractor output paths:** `extract_*.py` write their JSON to the *current working directory* using hardcoded +filenames, so run them from the repo root to land on the committed files. `nist_sorter.py` overwrites its input +file when no output path is given. When regenerating output just to verify a change, run from a scratch +directory so the committed JSON is never clobbered, then `diff` the result. + +### Development +- No build process - edit `index.html` directly +- No package manager - pure vanilla JavaScript +- Deploy by pushing to GitHub + +## 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 +```javascript +// Control format +{ + "id": "AC-1", + "text": "Control description...", + "family": "Access Control", + "enhancements": [...], + "discussion": "..." +} + +// Overlay format varies by type +// FedRAMP: {"assessment_procedures": [...]} +// CNSSI: {"selections": {...}, "parameter_value": "...", "justification": "..."} +// Classified: {"justification": "...", "parameter_value": "...", "guidance": "..."} +``` + +## 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 `cnssi_1253/extract_cnssi_1253.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**: 3.13, PyMuPDF (fitz) for PDF extraction (see `requirements.txt`) +- **JavaScript**: None (vanilla JS only) +- **Deployment**: GitHub Pages \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index a1ceaa2..10ddb19 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,110 +1 @@ -# 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 that constitute IL6 (Information Level 6) — the DoD standard for cloud service providers working with classified secret information. It displays NIST SP 800-53 controls with security overlays including FedRAMP High, CNSSI 1253, Classified Information Overlay, and FedRAMP+. - -## 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**: https://il6.sl5taskforce.org/ (GitHub: https://github.com/securitylevel5/il6-control-catalog) - -## Common Development Commands - -### Python Data Extraction - -Python 3.13 (pinned in `.python-version`), managed with `uv`. Never use bare `pip` or conda. - -```bash -# One-time environment setup -uv venv --python 3.13 -uv pip install -r requirements.txt - -# Extract overlay data from PDFs (requires PyMuPDF/fitz) -uv run python cnssi_1253/extract_cnssi_1253.py cnssi_1253/CNSSI_1253_2022.pdf -uv run python classified_information/extract_classified_information.py classified_information/classified_information_overlay_2022.pdf - -# Debug specific pages -uv run python cnssi_1253/extract_cnssi_1253.py cnssi_1253/CNSSI_1253_2022.pdf --debug-page 10 - -# Sort NIST controls naturally -uv run python nist_catalog/nist_sorter.py input.json output.json -``` - -**Extractor output paths:** `extract_*.py` write their JSON to the *current working directory* using hardcoded -filenames, so run them from the repo root to land on the committed files. `nist_sorter.py` overwrites its input -file when no output path is given. When regenerating output just to verify a change, run from a scratch -directory so the committed JSON is never clobbered, then `diff` the result. - -### Development -- No build process - edit `index.html` directly -- No package manager - pure vanilla JavaScript -- Deploy by pushing to GitHub - -## 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 -```javascript -// Control format -{ - "id": "AC-1", - "text": "Control description...", - "family": "Access Control", - "enhancements": [...], - "discussion": "..." -} - -// Overlay format varies by type -// FedRAMP: {"assessment_procedures": [...]} -// CNSSI: {"selections": {...}, "parameter_value": "...", "justification": "..."} -// Classified: {"justification": "...", "parameter_value": "...", "guidance": "..."} -``` - -## 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 `cnssi_1253/extract_cnssi_1253.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**: 3.13, PyMuPDF (fitz) for PDF extraction (see `requirements.txt`) -- **JavaScript**: None (vanilla JS only) -- **Deployment**: GitHub Pages \ No newline at end of file +See @AGENTS.md diff --git a/README.md b/README.md index 082ab14..9d882d0 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ python -m http.server 8000 ``` control-overlays-selector/ ├── index.html # Main web application (vanilla JS) -├── CLAUDE.md # AI assistant guidance +├── AGENTS.md # AI assistant guidance ├── README.md # This file │ ├── nist_catalog/ # NIST SP 800-53 source data