Case File 05 / Open-Source Software

Heptagon

A Python framework for making incident-response plans and records more inspectable: validate plan structure, check escalation paths, record evidence and decisions, and audit signed records for specific integrity failures.

Cybersecurity / IRPython 3.11+MIT licensePublic repository
Problem

Make gaps explicit

Incident-response plans and logs can be difficult to inspect consistently. Heptagon represents a response plan as structured data and returns named failures for missing roles, unreachable escalation paths, incomplete records, invalid signatures and unresolved evidence references.

Workflow

Declare → verify → simulate → audit

  • declare: validate a YAML plan against a JSON Schema and summarize it.
  • verify: run six plan and record-completeness gates.
  • simulate: check whether scenario escalation paths are reachable.
  • audit: inspect JSONL evidence/decision records, signatures, required coordinates and evidence references.
Record model

Seven coordinates

Heptagon groups a record's spacetime metadata with three additional fields: intention (F5), effect (F6) and lineage (F7). The six gates check team completeness, reporting-chain reachability, evidence integrity, signed/reconciled records, emergency override logging, and seven-coordinate completeness. This is a software-defined record schema—not proof that an incident account is complete in the real world.

Implementation

Python library and CLI

The repository contains a Python package, a command-line interface, YAML/JSON Schema plan loading, JSONL incident-log serialization, Ed25519 signing via PyNaCl, a symbolic modeling layer, a deterministic scenario simulator, examples and tests. The package is published on PyPI as heptagon7; the import and CLI names are heptagon.

Verification record

Tests and packaging checks

The repository documents 109 tests and a GitHub Actions workflow configured to test Python 3.11 and 3.12, build a wheel, check that the JSON Schema is included, install the wheel into a fresh environment, and run CLI smoke tests. These repository definitions describe the intended checks; consult the live workflow for the latest run result before treating a release as verified.

Scope and limits: Heptagon is not a SIEM, EDR, real-time detection system, threat-intelligence feed, legal-admissibility guarantee or certification of organizational compliance. Its threat model excludes compromised signing keys, malicious deletion by someone with write access to the log, and attackers who control the audit machine. Private signing keys are written with restrictive file permissions but are not encrypted at rest. The code also retains a legacy non-cryptographic signature mode when a decision is created without an Ed25519 signer; callers should explicitly provide a signer when cryptographic verification is required.
Evidence / primary sources
Source repository → Documentation site → PyPI package → CI workflow →