Skip to content

CLAUDE.md

Latest commit

 

History

History
159 lines (115 loc) · 8.66 KB

CLAUDE.md

File metadata and controls

159 lines (115 loc) · 8.66 KB
Raw

CLAUDE.md — osa-data

Working Style

Push back when something is wrong. If a request would create technical debt, introduce side effects, or is architecturally unsound — say so clearly before implementing. The founders value honest disagreement over silent compliance. A shortcut that works today but breaks tomorrow is not acceptable. If you're not confident in an approach, flag it.

Structured JSON data for Open Security Architecture (OSA) patterns, NIST 800-53 controls, and compliance framework mappings. This is the data layer — the website reads from this repo via a symlink.

Repositories

Repo Purpose Visibility
osa-data Patterns, controls, frameworks (this repo) Public
osa-website Astro site, Cloudflare Pages Public
osa-trident TRIDENT data, schemas, scripts, design docs Private
osa-strategy Roadmap, metrics, contacts, social Private

The website repo is a sibling at ~/osa/website/ and reads data via a symlink (website/src/data -> ../../data, resolves to ~/osa/data). A push to osa-data triggers an osa-website rebuild via GitHub Actions dispatch.

Founders

Name Alias Location Focus
Tobias Christen Aurelius Zurich Enterprise security architecture, pattern design, product strategy
Chris Lethaby Vinylwasp London APT defence, CBEST, GRC, CIS Controls
Russell Wing Spinoza London Platform, NIST mappings, compliance frameworks, assessment
Claude (AI) Vitruvius — Pattern enrichment, new patterns, technical implementation

Current Data

  • 48 security patterns (SP-001 to SP-047) + SP-000 reference/style guide + SP-999 test
  • 315 NIST 800-53 Rev 5 controls across 20 families
  • 63 compliance framework coverage files (79 in website registry) with cross-references
  • data/attack/metadata.json — symlink to osa-trident (TRIDENT graph versioning, provenance, checksums, and changelog)

Note: TRIDENT data catalogs, schemas, and enrichment scripts live in osa-trident. Only attack-metadata.schema.json is checked into this repo. metadata.json is maintained in osa-trident and generated by scripts/sync_metadata.py. Locally, all data/attack/*.json files (including metadata.json) are symlinks to the osa-trident checkout.

metadata.json (maintained in osa-trident)

This file is the public contract between osa-trident (private) and osa-website (public). It is generated by osa-trident/scripts/sync_metadata.py which computes checksums, edge counts, and entity counts from actual data files, and merges with hand-maintained sections (changelog, data_layers, jurisdiction_index, trident_paths).

The website build validates that:

  1. Every hasData: true nodeType in trident-model.json exists in graph_summary.node_types
  2. Every edge type in graph-edges.json exists in graph_summary.edge_types

When osa-trident data changes, run python3 scripts/sync_metadata.py --apply in osa-trident to regenerate metadata.json. The only manual updates needed are data_layers, changelog, and trident_paths entries for new data sources.

Directory Structure

data/
├── patterns/           # SP-NNN-descriptive-title.json
│   └── _manifest.json  # Index of all patterns
├── controls/           # NIST 800-53 Rev 5 (AC-01.json, etc.)
│   ├── _manifest.json
│   └── _catalog.json
├── attack/
│   └── metadata.json -> osa-trident     # Symlink — provenance, version info, graph summary
├── verticals/
│   └── financial-services.json          # FS vertical profile with threat profiles
└── schema/
    ├── pattern.schema.json
    ├── control.schema.json
    ├── framework-coverage.schema.json
    └── attack-metadata.schema.json      # Validates metadata.json

Naming Conventions

  • Pattern JSON: SP-NNN-descriptive-title.json (e.g., SP-029-zero-trust-architecture.json)
  • Pattern SVGs: sp-NNN-descriptive-title.svg in ../website/public/images/ (e.g., sp-029-zero-trust-architecture.svg) — website is a sibling repo at ~/osa/website/
  • Control JSON: XX-NN.json using NIST ID (e.g., AC-01.json, SC-13.json)
  • Slugs: lowercase, hyphenated, no sp-NNN- prefix (e.g., zero-trust-architecture)
  • Pattern IDs: SP-NNN format, zero-padded to 3 digits

Adding a New Pattern

  1. Create data/patterns/SP-NNN-descriptive-title.json following the schema
  2. Add entry to data/patterns/_manifest.json
  3. Create SVG diagram at ../website/public/images/sp-NNN-descriptive-title.svg
  4. That's it — the website reads the manifest and renders automatically

Pattern Schema Key Fields

  • id, title, slug, description — identity
  • metadata.status — active, draft, published, reserved, deprecated
  • metadata.type — pattern, module, reference
  • metadata.authors — use aliases (Aurelius, Vinylwasp, Spinoza, Vitruvius)
  • controls[] — NIST 800-53 control mappings with emphasis (critical/important/standard)
  • threats[] — threat catalogue with mitigatedBy control references
  • content.keyControlAreas[] — key areas with inline NIST references
  • examples{}, references[], relatedPatterns[]

SVG Diagram Conventions

Canonical reference: data/patterns/SP-000-reference-pattern.json — always check this before creating or editing SVGs.

Structure

  • ViewBox: 960 x 720 (may extend to 750 for larger diagrams)
  • Background: fill="#f8fafc" rx="8" (slate-50, rounded corners) — NOT white
  • Title bar: rect fill="#00171F" rx="6" (Midnight), title text fill="white" font-weight="700"
  • Font stack: font-family="system-ui, -apple-system, sans-serif" — NOT named fonts like GillSans

Palette

#003459 (Navy), #007EA7 (OSA Blue), #00A8E8 (Sky), #00171F (Midnight), #FFFFFF (White)

Interactive Elements

  • NIST badges: clickable <a xlink:href="/controls/xx-nn" target="_top"> — lowercase control IDs, always include target="_top"
  • Inline badges (on light backgrounds): fill at opacity="0.12", NO stroke, text fill at full colour
  • Dark-bar badges (on dark backgrounds): fill at opacity="0.35" with stroke and stroke-opacity
  • Reference taglines: clickable links at bottom — authoritative sources for the pattern topic
  • Related patterns: <a xlink:href="/patterns/sp-NNN" target="_top">

Required Sections

  • Legend/Key: colour-coded key explaining zone/component colours
  • Reference bar: clickable links to authoritative sources
  • opensecurityarchitecture.org: right-aligned at bottom

Techniques

  • White lozenge: rect fill="white" opacity="0.9" rx="3" behind arrow text
  • Icons from OSA icon library (../website/public/icons/)

GitHub Issues

When creating issues in any OSA repo, always add them to the "OSA Delivery Board" project so Chris and the other founders can see them. Use: gh issue create --project "OSA Delivery Board". When closing issues, the board updates automatically.

Commands

# Validate all JSON against schemas
python3 scripts/validate_json.py

# Website build (from workspace root ~/osa/)
npm --prefix ~/osa/website run build

# Website dev server
npm --prefix ~/osa/website run dev

CI/CD

  • osa-data: GitHub Actions validates all JSON against schemas on push
  • osa-website: Cloudflare Pages auto-deploys on push; also triggered by osa-data dispatch
  • Cross-repo dispatch: osa-data push → GitHub Actions → repository_dispatch → osa-website rebuild

Skills

OSA skills live in ~/osa/trident/.claude/skills/ (private repo). Current skills: new-pattern, pattern-audit, enrich-pattern, add-framework-mapping, generate-coverage, review-spec, review-tests.

Iterative improvement: Skills should be improved in-context as issues are found. If a skill produces output that needs manual correction, or misses an edge case, fix the SKILL.md in the same session. Do not work around skill bugs — fix them.

What Goes Where

  • Pattern data, controls, schemas → this repo (osa-data)
  • TRIDENT data, schemas, scripts, design docs → osa-trident (private)
  • Site source, SVGs, icons, JS, CSS → osa-website
  • Strategy, metrics, contacts, social plans → osa-strategy (private)
  • Personal session notes, preferences → your private .claude/ memory (never committed)