Skip to content

CLAUDE.md

Latest commit

 

History

History
173 lines (145 loc) · 8.18 KB

CLAUDE.md

File metadata and controls

173 lines (145 loc) · 8.18 KB

CLAUDE.md — AI Assistant Guide for cps-assurance

Project Overview

This repository contains governance-as-code for cyber-physical systems under EU product regulation. It bridges three domains that are inseparable in CPS: functional safety, OT/ICS security, and EU product conformity — plus their interaction.

Owner: Roman Mednitzer License: MIT Regulatory scope: Machinery Regulation (EU 2023/1230), CRA (EU 2024/2847), RED, LVD, EMC, EU AI Act, IEC 61508, IEC 62443, IEC 63069

Repository Structure

cps-assurance/
├── docs/                              # Documentation
│   ├── architecture/
│   │   └── standards-applicability.md # Standards and directive applicability
│   ├── safety/                        # Functional safety methodology
│   ├── security/                      # OT/ICS security methodology
│   ├── regulatory/                    # EU product regulation mapping
│   ├── assurance/                     # Assurance cases, data model, traceability
│   ├── evidence/                      # CPS evidence types and metadata
│   └── conformity/                    # Conformity assessment guidance
├── policies/                          # CPS-specific ISMS extensions
│   ├── POL-CPS-01-functional-safety.md
│   ├── POL-CPS-02-ot-security.md
│   └── POL-CPS-03-product-conformity.md
├── registers/                         # Operational registers
│   ├── hazard-register.md
│   ├── safety-constraint-register.md
│   ├── threat-register.md
│   ├── zone-conduit-register.md
│   ├── ssi-register.md               # Safety-security interactions
│   ├── product-register.md
│   └── traceability-manifest.md
├── templates/                         # Structured entry templates
│   ├── hazard-analysis/
│   ├── safety-constraints/
│   ├── threat-model/
│   ├── zone-conduit/
│   ├── safety-security-interaction/
│   ├── assurance-case/
│   ├── traceability/
│   ├── product-gap-assessment/
│   └── change-review/
├── checklists/                        # Pre-commissioning and review checklists
│   ├── pre-commissioning-safety/
│   ├── pre-commissioning-security/
│   └── annual-review/
├── schemas/                           # JSON/YAML schemas for register entries
├── scripts/                           # Python validation and utility scripts
├── artifact-index.yaml                # AI-facing artifact classification index
├── Makefile                           # validate target
├── CONTRIBUTING.md
├── LICENSE
└── README.md

Key Concepts

Design Principles

  1. Correctness > Safety > Auditability > Completeness > Speed — priority ordering for all decisions.
  2. Enforce at boundaries, not internals. Boundary contracts must hold.
  3. Measure, don't trust. Every assurance claim needs observable, measurable evidence.
  4. Degrade, don't fail. Every component has a defined degraded mode.
  5. Safety and security are jointly governed.

Safety-Security Interaction Types

Seven interaction types (SS-1 through SS-7) covering both directions:

  • Security failures causing safety hazards
  • Safety mechanisms creating security vulnerabilities

Evidence Tagging

  • [F] — Verified fact
  • [I] — Inference
  • [S] — Heuristic
  • Confidence levels: {50, 70, 75, 80, 85, 90}

Methodologies

  • STPA — System-Theoretic Process Analysis for hazard identification (CPS-adapted with security overlay)
  • STRIDE — OT threat modelling with physical consequence tracing
  • IEC 62443-3-2 — Zone/conduit modelling and SL-T allocation
  • Joint STPA-STRIDE — Safety-security interaction analysis
  • GSN/CAE — Structured assurance cases arguing both safety and security

ID Schemes

  • H-nnn — Hazards
  • SC-nnn — Safety constraints
  • SF-nnn — Safety functions
  • T-nnn — Threats
  • Z-nn — Zones
  • CO-nn — Conduits
  • SSI-nnn — Safety-security interactions
  • CTL-nnnn — Cross-references to platform-assurance controls

Commit Conventions

Use conventional commits with these prefixes:

  • feat: — New governance artifact or capability
  • fix: — Corrections to existing artifacts
  • docs: — Documentation changes
  • policy: — Policy changes
  • register: — Register updates
  • safety: — Safety-critical changes
  • security: — Security-related changes

All commits should be signed (GPG or SSH): git commit -S

Branch Model

  • main — Approved, current state of CPS governance
  • draft/* — Work in progress
  • No direct pushes to main — merge requests only

Review Requirements by Path

Path Review required Approver
policies/ Legal review + safety manager + CISO Safety manager signs tag
registers/hazard-register.md Safety engineer + safety manager Merge request review
registers/safety-constraint-register.md Safety engineer + safety manager Merge request review
registers/threat-register.md OT security lead + CISO Merge request review
registers/zone-conduit-register.md OT security lead + CISO Merge request review
registers/ssi-register.md Safety engineer + OT security lead (joint) Merge request review
registers/traceability-manifest.md Safety manager + compliance lead Merge request review
registers/product-register.md Product owner + compliance lead Merge request review
docs/ Peer review (1 reviewer minimum) Any team member
templates/, checklists/ Safety manager or CISO Merge request review

Relationship to platform-assurance

This repo governs the CPS-specific layer (physical safety, OT networks, product certification). The platform-assurance repo governs the IT platform layer (ISMS, NIS2, GDPR, evidence pipeline, observability, IAM).

Connections:

  • CPS evidence flows into the platform-assurance evidence pipeline (MinIO WORM, cosign, OpenSearch)
  • Platform-assurance POL-10 applies to all changes; CPS policies add OT-specific review gates
  • OT security alerts escalate to the platform-assurance incident response workflow (POL-04)
  • CPS schemas accept platform_controls references (CTL-nnnn) for IT-layer control dependencies

Guidelines for AI Assistants

Content Standards

  • All documents follow British English spelling conventions (organisation, authorised, etc.)
  • Registers use structured entry templates — match existing formats exactly
  • Do not create duplicate IDs; check existing entries first

When Editing Policies

  • Policies are legally significant — do not change wording casually
  • CPS policies extend the platform-assurance ISMS; they complement, not replace, IT-layer policies
  • Preserve DRAFT status markers; do not mark as approved

When Editing Registers

  • Preserve column schemas and entry structures exactly — auditors and safety assessors rely on them
  • Use the structured ID schemes consistently
  • Cross-references to platform-assurance controls use CTL-nnnn format
  • Always consider cross-domain impact (safety changes may affect security, and vice versa)

When Editing Schemas

  • Schemas define the machine-readable contract for register entries
  • Changes to schemas affect validation; run make validate after changes
  • Maintain backwards compatibility unless explicitly instructed otherwise

Safety-Critical Changes

  • Any change to H-n, SF-n, SC-n, T-n, SIL/PL allocations, Z-n, or CO-n is safety-critical
  • Safety-critical changes require joint safety + security review
  • Always assess impact on the SSI register when modifying safety or security items
  • Never alter SIL/PL allocations, safety function specifications, or zone boundaries without explicit instruction

General

  • CPS governance requires domain-specific rigour — accuracy and traceability matter more than brevity
  • Safety and security are not independent in CPS — always consider interaction effects
  • Run make validate before any merge request
  • The canonical source for AI continuation context is artifact-index.yaml