heptagon7 1.0.0__tar.gz

heptagon7-1.0.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Ali
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heptagon7-1.0.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: heptagon7
+Version: 1.0.0
+Summary: Seven coordinates. Every incident. Verified.
+Author: Muhammad Ali
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/claythe3ed/heptagon
+Project-URL: Repository, https://github.com/claythe3ed/heptagon
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: PyNaCl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Dynamic: license-file
+
+# Heptagon
+
+**Seven coordinates. Every incident. Verified.**
+
+A symbolic, formal, and executable framework for cybersecurity
+incident response planning and management.
+
+## What it does
+
+Heptagon treats every incident record as a seven-coordinate object.
+An incident without a timestamp, rationale, effect, or lineage is
+not a complete record — and an incomplete record cannot be certified
+as truthful.
+
+The framework:
+
+1. **Declares** a Cyber Incident Response Plan in code
+2. **Verifies** plan completeness against six compliance gates
+3. **Simulates** scenario escalations through the reporting DAG
+4. **Logs** incidents with tamper-evident evidence and decisions
+5. **Audits** every record for 7D coordinate coverage
+6. **Rejects** incomplete records with specific, actionable reasons
+
+## The seven coordinates
+
+| Coordinate | Name | Meaning |
+|---|---|---|
+| **B**  | Spacetime  | Timestamp + origin |
+| **F5** | Intention  | Why the actor acted |
+| **F6** | Effect     | What changed downstream |
+| **F7** | Lineage    | Position in the reporting chain |
+
+A complete record populates all seven. The `check_7d_completeness()`
+gate enforces this on every logged evidence and decision.
+
+## Install
+
+    pip install heptagon7
+
+The PyPI project is named **heptagon7** — the name `heptagon` was
+already taken on PyPI. After installing, the Python import and the
+CLI command are both `heptagon`:
+
+    import heptagon          # library
+    heptagon --help          # CLI
+
+For local development:
+
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install -e .
+
+## Quick start
+
+    python -m heptagon.cirp.model          # reference CIRP demo
+    python -m heptagon.core.symbolic       # symbolic layer demo
+    python -m heptagon.simulation.stuxnet_test  # historical validation
+    python -m pytest tests/ -v             # full test suite
+
+## The six compliance gates
+
+`CIRPModel.verify_all()` runs:
+
+1. `check_teams_complete`       — all 5 R-C-C-P-T roles present and complete
+2. `check_reporting_chain`      — every reporter can reach an executive
+3. `check_evidence_completeness`— unique hashes, no dangling refs, chronology valid
+4. `check_no_hidden_thing`      — every source's slice reconciles with the global log
+5. `check_break_glass_logged`   — every emergency override is marked AND evidenced
+6. `check_7d_completeness`      — every record populates all seven coordinates
+
+## Architecture
+
+    heptagon/
+      core/            Symbolic layer (bundle, sheaf, lineage, operators)
+      cirp/            CIRP primitives + compliance checks + tabletop
+      simulation/      Deterministic agent-based simulator
+      audit/           (future) signature verification, reporting
+
+## Honest limits
+
+- **Assumes honest actors.** This tool catches accidental omission,
+  not adversarial falsification. Signatures are content hashes, not
+  PKI signatures. A v1 threat model will address the malicious case.
+- **Does not replace human judgment.** It verifies that decisions are
+  logged, not that they are wise.
+- **Does not certify compliance.** It reports whether a plan is
+  internally consistent, not whether it meets any specific regulation.
+- **Not production-ready before v1.0.** The API may change.
+
+## History
+
+The framework's design traces to a symbolic model of comprehensive
+presentation (al-'ard fi fada' al-shumul). The mathematics is a
+language for meaning, not a claim about physics. See `docs/PHILOSOPHY.md`
+(future) for the full derivation.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Status
+
+**v0.1.0** — Audit-closed. All twelve originally identified issues
+resolved or retracted. 58 tests passing.

heptagon7-1.0.0/README.md

@@ -0,0 +1,104 @@
+# Heptagon
+
+**Seven coordinates. Every incident. Verified.**
+
+A symbolic, formal, and executable framework for cybersecurity
+incident response planning and management.
+
+## What it does
+
+Heptagon treats every incident record as a seven-coordinate object.
+An incident without a timestamp, rationale, effect, or lineage is
+not a complete record — and an incomplete record cannot be certified
+as truthful.
+
+The framework:
+
+1. **Declares** a Cyber Incident Response Plan in code
+2. **Verifies** plan completeness against six compliance gates
+3. **Simulates** scenario escalations through the reporting DAG
+4. **Logs** incidents with tamper-evident evidence and decisions
+5. **Audits** every record for 7D coordinate coverage
+6. **Rejects** incomplete records with specific, actionable reasons
+
+## The seven coordinates
+
+| Coordinate | Name | Meaning |
+|---|---|---|
+| **B**  | Spacetime  | Timestamp + origin |
+| **F5** | Intention  | Why the actor acted |
+| **F6** | Effect     | What changed downstream |
+| **F7** | Lineage    | Position in the reporting chain |
+
+A complete record populates all seven. The `check_7d_completeness()`
+gate enforces this on every logged evidence and decision.
+
+## Install
+
+    pip install heptagon7
+
+The PyPI project is named **heptagon7** — the name `heptagon` was
+already taken on PyPI. After installing, the Python import and the
+CLI command are both `heptagon`:
+
+    import heptagon          # library
+    heptagon --help          # CLI
+
+For local development:
+
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install -e .
+
+## Quick start
+
+    python -m heptagon.cirp.model          # reference CIRP demo
+    python -m heptagon.core.symbolic       # symbolic layer demo
+    python -m heptagon.simulation.stuxnet_test  # historical validation
+    python -m pytest tests/ -v             # full test suite
+
+## The six compliance gates
+
+`CIRPModel.verify_all()` runs:
+
+1. `check_teams_complete`       — all 5 R-C-C-P-T roles present and complete
+2. `check_reporting_chain`      — every reporter can reach an executive
+3. `check_evidence_completeness`— unique hashes, no dangling refs, chronology valid
+4. `check_no_hidden_thing`      — every source's slice reconciles with the global log
+5. `check_break_glass_logged`   — every emergency override is marked AND evidenced
+6. `check_7d_completeness`      — every record populates all seven coordinates
+
+## Architecture
+
+    heptagon/
+      core/            Symbolic layer (bundle, sheaf, lineage, operators)
+      cirp/            CIRP primitives + compliance checks + tabletop
+      simulation/      Deterministic agent-based simulator
+      audit/           (future) signature verification, reporting
+
+## Honest limits
+
+- **Assumes honest actors.** This tool catches accidental omission,
+  not adversarial falsification. Signatures are content hashes, not
+  PKI signatures. A v1 threat model will address the malicious case.
+- **Does not replace human judgment.** It verifies that decisions are
+  logged, not that they are wise.
+- **Does not certify compliance.** It reports whether a plan is
+  internally consistent, not whether it meets any specific regulation.
+- **Not production-ready before v1.0.** The API may change.
+
+## History
+
+The framework's design traces to a symbolic model of comprehensive
+presentation (al-'ard fi fada' al-shumul). The mathematics is a
+language for meaning, not a claim about physics. See `docs/PHILOSOPHY.md`
+(future) for the full derivation.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Status
+
+**v0.1.0** — Audit-closed. All twelve originally identified issues
+resolved or retracted. 58 tests passing.

heptagon7-1.0.0/heptagon/__init__.py

@@ -0,0 +1,44 @@
+"""
+Heptagon — Seven coordinates. Every incident. Verified.
+
+A symbolic, formal, and executable framework for cybersecurity
+incident response planning and management.
+"""
+__version__ = "1.0.0"
+
+from heptagon.core.symbolic import (
+    FiberBundle7D,
+    MoralSheaf,
+    Lineage,
+    PresentationOperator,
+    TestimonyOperator,
+    MoralJacobians,
+    UnifiedEvaluation,
+    IncidentResponsePipeline,
+)
+
+from heptagon.cirp.model import (
+    CIRPModel,
+    Team,
+    Stakeholder,
+    Scenario,
+    Evidence,
+    Decision,
+)
+
+__all__ = [
+    "FiberBundle7D",
+    "MoralSheaf",
+    "Lineage",
+    "PresentationOperator",
+    "TestimonyOperator",
+    "MoralJacobians",
+    "UnifiedEvaluation",
+    "IncidentResponsePipeline",
+    "CIRPModel",
+    "Team",
+    "Stakeholder",
+    "Scenario",
+    "Evidence",
+    "Decision",
+]

heptagon7-1.0.0/heptagon/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for ``python -m heptagon``."""
+import sys
+
+from heptagon.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

heptagon7-1.0.0/heptagon/audit/log.py

@@ -0,0 +1,78 @@
+"""
+log.py
+======
+
+Read and write incident logs.
+
+An incident log is a JSONL file. Each line is one JSON object of
+the form::
+
+    {"type": "evidence", "data": { ... Evidence fields ... }}
+    {"type": "decision", "data": { ... Decision fields ... }}
+
+Records are stored in insertion order. Append-only semantics are
+recommended: never rewrite a log once written, only append to it.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Union
+
+from heptagon.cirp.model import Decision, Evidence
+
+
+@dataclass
+class IncidentLog:
+    """An ordered collection of evidence and decisions."""
+    evidence: List[Evidence] = field(default_factory=list)
+    decisions: List[Decision] = field(default_factory=list)
+
+    def append_evidence(self, ev: Evidence) -> None:
+        self.evidence.append(ev)
+
+    def append_decision(self, d: Decision) -> None:
+        self.decisions.append(d)
+
+    def to_jsonl(self) -> str:
+        lines: List[str] = []
+        for ev in self.evidence:
+            lines.append(json.dumps({"type": "evidence", "data": ev.to_dict()}))
+        for d in self.decisions:
+            lines.append(json.dumps({"type": "decision", "data": d.to_dict()}))
+        return "\n".join(lines) + "\n"
+
+    @classmethod
+    def from_jsonl(cls, text: str) -> "IncidentLog":
+        log = cls()
+        for lineno, raw in enumerate(text.splitlines(), start=1):
+            stripped = raw.strip()
+            if not stripped:
+                continue
+            try:
+                record = json.loads(stripped)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"line {lineno}: invalid JSON: {e}") from e
+            rtype = record.get("type")
+            data = record.get("data", {})
+            if rtype == "evidence":
+                log.evidence.append(Evidence.from_dict(data))
+            elif rtype == "decision":
+                log.decisions.append(Decision.from_dict(data))
+            else:
+                raise ValueError(
+                    f"line {lineno}: unknown record type {rtype!r}"
+                )
+        return log
+
+
+def save_log(log: IncidentLog, path: Union[str, Path]) -> None:
+    """Write an IncidentLog to a JSONL file."""
+    Path(path).write_text(log.to_jsonl(), encoding="utf-8")
+
+
+def load_log(path: Union[str, Path]) -> IncidentLog:
+    """Read an IncidentLog from a JSONL file."""
+    return IncidentLog.from_jsonl(Path(path).read_text(encoding="utf-8"))

heptagon7-1.0.0/heptagon/audit/signing.py

@@ -0,0 +1,127 @@
+"""
+signing.py
+==========
+
+Ed25519 signing for incident-response records.
+
+Provides a ``Signer`` class that wraps a private/public keypair and
+signs canonical byte representations of Decision records.
+
+Key storage format
+------------------
+A signer is serialized as JSON:
+
+    {
+      "algorithm": "ed25519",
+      "private_key_hex": "...",
+      "public_key_hex": "...",
+      "created_utc": "2026-10-10T20:35:00+00:00"
+    }
+
+The private key should be stored with strict filesystem permissions
+(0600). The public key can be shared freely — it is the identifier
+used to verify signed records.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Union
+
+from nacl import signing as ed25519
+from nacl.exceptions import BadSignatureError
+
+
+ALGORITHM_NAME = "ed25519"
+
+
+@dataclass
+class Signer:
+    """An Ed25519 keypair capable of signing and verifying records."""
+    private_key_bytes: bytes
+    public_key_bytes: bytes
+    created_utc: str = ""
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def generate(cls) -> "Signer":
+        """Generate a fresh random keypair."""
+        vk = ed25519.SigningKey.generate()
+        sk_bytes = bytes(vk)
+        pk_bytes = bytes(vk.verify_key)
+        return cls(
+            private_key_bytes=sk_bytes,
+            public_key_bytes=pk_bytes,
+            created_utc=datetime.now(timezone.utc).isoformat(),
+        )
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self, path: Union[str, Path]) -> None:
+        """Write the keypair to a JSON file with 0600 permissions."""
+        p = Path(path)
+        payload = {
+            "algorithm": ALGORITHM_NAME,
+            "private_key_hex": self.private_key_bytes.hex(),
+            "public_key_hex": self.public_key_bytes.hex(),
+            "created_utc": self.created_utc,
+        }
+        p.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        # Lock permissions down
+        try:
+            os.chmod(p, 0o600)
+        except OSError:
+            pass
+
+    @classmethod
+    def load(cls, path: Union[str, Path]) -> "Signer":
+        """Load a keypair from a JSON file."""
+        p = Path(path)
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if data.get("algorithm") != ALGORITHM_NAME:
+            raise ValueError(
+                f"unsupported algorithm: {data.get('algorithm')}"
+            )
+        return cls(
+            private_key_bytes=bytes.fromhex(data["private_key_hex"]),
+            public_key_bytes=bytes.fromhex(data["public_key_hex"]),
+            created_utc=data.get("created_utc", ""),
+        )
+
+    # ------------------------------------------------------------------
+    # Sign / verify
+    # ------------------------------------------------------------------
+
+    @property
+    def public_key_hex(self) -> str:
+        return self.public_key_bytes.hex()
+
+    def sign(self, payload: bytes) -> bytes:
+        """Sign raw bytes. Returns the 64-byte signature."""
+        vk = ed25519.SigningKey(self.private_key_bytes)
+        # PyNaCl's SigningKey.sign() returns a SignedMessage container
+        # (signature + original message). Extract only the signature.
+        return vk.sign(payload).signature
+
+    @staticmethod
+    def verify(
+        public_key_bytes: bytes,
+        payload: bytes,
+        signature_bytes: bytes,
+    ) -> bool:
+        """Verify a signature against a payload and public key."""
+        try:
+            vk = ed25519.VerifyKey(public_key_bytes)
+            vk.verify(payload, signature_bytes)
+            return True
+        except (BadSignatureError, Exception):
+            return False