create-gsn-diagram

# create-gsn-diagram Generate Goal Structuring Notation (GSN) assurance case diagrams from the SPARTA compliance graph stored in ArangoDB. Supports three output formats: | Format | Standard | Use Case | |--------|----------|----------| | **SVG/PNG** | Graphviz | Human-readable diagrams | | **DOT** | Graphviz | Manual rendering, CI pipelines | | **SACM XML** | OMG SACM 2.2 | Machine-readable, tool interoperability | ## Standards Alignment | Standard | Status | Integration | |----------|--------|-------------| | **GSN** | De facto | Visual notation (boxes, circles, parallelograms) | | **OMG SACM 2.2** | Approved (2024) | XML export via `export-sacm` | | **ISO/IEC 15026** | Published (2019) | Assurance case concepts | | **OSCAL** | NIST v1.1 | Evidence references in Solution nodes | | **SPARTA Taxonomy** | Internal | Mind tags → SACM Context nodes | ## Usage ### Render GSN diagram (SVG/PNG) ```bash ./run.sh render --control AC-1 ./run.sh render --framework NIST-800-171 --output ./diagrams/ ``` ### Export DOT notation ```bash ./run.sh export-dot --control AC-1 ./run.sh export-dot --control AC-1 | dot -Tsvg > diagram.svg ``` ### Export SACM XML (machine-readable) ```bash # To stdout ./run.sh export-sacm --control AC-1 --dry-run # To file ./run.sh export-sacm --control AC-1 --output ac1_assurance.xml # Full framework ./run.sh export-sacm --framework SPARTA --output sparta_assurance.xml ``` ## SACM Export Features The `export-sacm` command produces OMG SACM 2.2 compliant XML with: ### Taxonomy → Context Mapping SPARTA Mind tags (Detect, Evade, Exploit, Harden, Isolate, Model, Persist, Restore) are mapped to SACM `InformationElement` (Context) nodes: ```xml <arg:InformationElement gid="C2" name="C2: Tactical scope: Harden, Detect"> <base:implementationConstraint content="taxonomy:mind=Harden,Detect"/> </arg:InformationElement> ``` This enables: - Filtering assurance cases by tactical category - Validating tactical alignment across refinement chains - Machine queries like "show all Harden arguments" ### OSCAL Evidence References Solution nodes can reference OSCAL Assessment Result findings: ```xml <arti:ArtifactReference gid="Sn1" name="Sn1: QRA evidence"> <arti:externalReference location="oscal-ar://findings/ac1_qra" type="OSCAL-AR"/> </arti:ArtifactReference> ``` ### Lean4 Proof References Solution nodes can reference formal proofs: ```xml <arti:ArtifactReference gid="Sn2" name="Sn2: Formal proof"> <arti:externalReference location="lean4://proofs/ac1_theorem" type="Lean4-Proof"/> </arti:ArtifactReference> ``` ## Options | Flag | Description | |-----------------|-----------------------------------------------------| | `--control` | NIST/CMMC/SPARTA control ID (e.g. `AC-1`, `SA-1`) | | `--framework` | Framework name; processes all controls under it | | `--output` | Output file path (format auto-detected by command) | | `--dry-run` | Generate sample output without querying ArangoDB | ## Integration Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ /memory recall → control + QRA evidence + taxonomy │ │ ↓ │ │ GSNGraph (internal model with taxonomy metadata) │ │ ├─→ graph_to_dot() → SVG/PNG (human-readable) │ │ └─→ graph_to_sacm() → SACM XML (machine-readable) │ │ ↓ │ │ /review-assurance-case (47 checks) │ │ /export-oscal (evidence export) │ │ /lean4-prove (formal proofs) │ └─────────────────────────────────────────────────────────────────────┘ ``` ## Common Mistakes ### WRONG: Rendering without checking ArangoDB connectivity ```bash ./run.sh render --control AC-1 # fails silently if ArangoDB is down ``` ### RIGHT: Use --dry-run to test, or verify ArangoDB first ```bash ./run.sh render --control AC-1 --dry-run # works without ArangoDB # Or verify: curl -s http://127.0.0.1:8529/_api/version ``` ### WRONG: Using export-dot when you need machine-readable output ```bash ./run.sh export-dot --control AC-1 > assurance.txt # not machine-parseable ``` ### RIGHT: Use export-sacm for tool interoperability ```bash ./run.sh export-sacm --control AC-1 --output assurance.xml ``` ### WRONG: Ignoring taxonomy context in assurance arguments ```bash # Building an argument without tactical scope = weak argument ``` ### RIGHT: Include taxonomy context (automatic with DB queries) ```bash ./run.sh export-sacm --control SA-1 # Mind tags auto-included as Context nodes ```