attestral 0.1.0__py3-none-any.whl

attestral/__init__.py

@@ -0,0 +1,6 @@
+"""Attestral: continuous, audit-ready security design review."""
+__version__ = "0.1.0"
+
+from attestral.model import Component, Edge, Finding, SystemModel, TrustBoundary
+
+__all__ = ["SystemModel", "Component", "Edge", "TrustBoundary", "Finding"]

attestral/cli.py

@@ -0,0 +1,109 @@
+"""Attestral CLI: scan a project, emit an audit-ready design review."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from attestral import __version__
+from attestral.evidence import audit_chain, render_markdown, verify_chain
+from attestral.ingest import build_model
+from attestral.rules import RuleEngine
+
+
+@click.group()
+@click.version_option(__version__)
+def main() -> None:
+    """Attestral - continuous, audit-ready security design review."""
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("-o", "--output", default="attestral-report", help="Output file stem.")
+@click.option("--format", "fmt", type=click.Choice(["md", "json", "both"]), default="both")
+@click.option("--llm", is_flag=True, help="Add LLM threat elicitation (needs ANTHROPIC_API_KEY).")
+@click.option("--fail-on", type=click.Choice(["critical", "high", "medium", "low"]), default=None,
+              help="Exit non-zero if findings at/above this severity exist (CI gate).")
+def scan(path: str, output: str, fmt: str, llm: bool, fail_on: str | None) -> None:
+    """Scan PATH (Terraform, MCP configs) and generate a design review."""
+    model = build_model(path)
+    findings = RuleEngine().evaluate(model)
+    if llm:
+        from attestral.llm import elicit
+        findings += elicit(model)
+
+    if fmt in ("md", "both"):
+        Path(f"{output}.md").write_text(render_markdown(model, findings, path))
+        click.echo(f"wrote {output}.md")
+    if fmt in ("json", "both"):
+        Path(f"{output}.json").write_text(
+            json.dumps({"target": path, "chain": audit_chain(findings)}, indent=2)
+        )
+        click.echo(f"wrote {output}.json")
+
+    for f in findings:
+        click.echo(f"  [{f.severity.value.upper():8}] {f.rule_id}  {f.title}  ({f.component_id})")
+    click.echo(f"{len(model.components)} components · {len(findings)} findings")
+
+    if fail_on:
+        from attestral.model import Severity
+        threshold = Severity(fail_on).rank
+        if any(f.severity.rank >= threshold for f in findings):
+            click.echo(f"FAIL-CLOSED: findings at or above '{fail_on}'", err=True)
+            sys.exit(1)
+
+
+@main.command()
+@click.argument("report", type=click.Path(exists=True))
+def verify(report: str) -> None:
+    """Verify the tamper-evident audit chain in a JSON report."""
+    data = json.loads(Path(report).read_text())
+    ok = verify_chain(data.get("chain", []))
+    click.echo("chain VALID ✅" if ok else "chain INVALID - report has been altered ❌")
+    sys.exit(0 if ok else 1)
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("-o", "--output", default="mcp-guard-policy.yaml", help="Policy output file.")
+def compile(path: str, output: str) -> None:
+    """Compile PATH's attested design into an mcp-guard runtime policy."""
+    from attestral.compile import compile_policy, render_policy_yaml
+    model = build_model(path)
+    findings = RuleEngine().evaluate(model)
+    chain = audit_chain(findings)
+    head = chain[-1]["hash"] if chain else ""
+    policy = compile_policy(model, findings, chain_head=head)
+    Path(output).write_text(render_policy_yaml(policy))
+    allowed = sum(1 for s in policy["servers"].values() if s["allow"])
+    denied = len(policy["servers"]) - allowed
+    click.echo(f"wrote {output}  ·  default deny  ·  {allowed} allowed, {denied} denied")
+    for name, s in policy["servers"].items():
+        mark = "ALLOW" if s["allow"] else "DENY "
+        why = "" if s["allow"] else f"  ({s.get('reason','')})"
+        click.echo(f"  [{mark}] {name}{why}")
+
+
+@main.command()
+@click.argument("policy_file", type=click.Path(exists=True))
+@click.argument("events_file", type=click.Path(exists=True))
+@click.option("--fail-on-drift", is_flag=True, help="Exit non-zero on any drift (CI/cron gate).")
+def drift(policy_file: str, events_file: str, fail_on_drift: bool) -> None:
+    """Diff runtime EVENTS_FILE (JSONL) against a compiled POLICY_FILE."""
+    import yaml as _yaml
+    from attestral.drift import detect_drift, load_events
+    policy = _yaml.safe_load(Path(policy_file).read_text())
+    events = load_events(events_file)
+    findings = detect_drift(policy, events)
+    for f in findings:
+        click.echo(f"  [{f.severity.value.upper():8}] {f.rule_id}  {f.title}  ({f.component_id})")
+    click.echo(f"{len(events)} events · {len(findings)} drift findings")
+    if findings and fail_on_drift:
+        click.echo("DRIFT: deployment no longer matches the attested design", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

attestral/compile.py

@@ -0,0 +1,100 @@
+"""Compile an attested design into a runtime policy.
+
+This is the loop-closer: the reviewed system model (plus its findings)
+becomes an mcp-guard-compatible policy document. The threat model is not a
+PDF - it is the runtime configuration.
+
+Compilation rules (fail-closed):
+- default: deny - servers absent from the attested model are never allowed
+- critical findings against a server deny it outright (with the rule id as reason)
+- filesystem scopes are narrowed to the attested roots; broad roots (ATL-102)
+  compile to `allow: false` until re-scoped in the design
+- non-TLS transports (ATL-101) compile to a tls_only constraint violation → deny
+- env-secret findings (ATL-104) compile to a `forbid_env_secrets` constraint
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+
+import yaml
+
+from attestral.model import Finding, SystemModel
+
+POLICY_VERSION = 1
+_BROAD_ROOTS = {"/", "~", "/home", "/Users"}
+
+
+def _model_hash(model: SystemModel) -> str:
+    return hashlib.sha256(model.to_json().encode()).hexdigest()
+
+
+def compile_policy(
+    model: SystemModel,
+    findings: list[Finding],
+    chain_head: str = "",
+) -> dict:
+    """Return an mcp-guard v0 policy dict derived from the attested design."""
+    by_component: dict[str, list[Finding]] = {}
+    for f in findings:
+        by_component.setdefault(f.component_id, []).append(f)
+
+    servers: dict[str, dict] = {}
+    for c in model.by_type("mcp_server"):
+        entry: dict = {"allow": True, "constraints": {}, "attested_source": c.source}
+        server_findings = by_component.get(c.id, [])
+        deny_reasons = [
+            f.rule_id for f in server_findings if f.severity.value == "critical"
+        ]
+
+        # Transport: attested design must be TLS; http:// compiles to deny.
+        url = str(c.attr("url", ""))
+        if url:
+            entry["constraints"]["transport"] = "tls_only"
+            if url.startswith("http://"):
+                deny_reasons.append("ATL-101")
+
+        # Filesystem scope: allow only attested, non-broad roots.
+        args = [str(a) for a in (c.attr("args") or [])]
+        roots = [a for a in args if a.startswith(("/", "~"))]
+        if roots:
+            narrow = [r for r in roots if r not in _BROAD_ROOTS]
+            if narrow:
+                entry["constraints"]["root_paths"] = sorted(narrow)
+            else:
+                deny_reasons.append("ATL-102")
+
+        # Secrets in env: enforce at the proxy.
+        if c.attr("_env_has_secrets"):
+            entry["constraints"]["forbid_env_secrets"] = True
+
+        if deny_reasons:
+            entry["allow"] = False
+            entry["reason"] = (
+                "denied by attested design review: " + ", ".join(sorted(set(deny_reasons)))
+            )
+            entry.pop("constraints", None)
+
+        servers[c.name] = entry
+
+    return {
+        "version": POLICY_VERSION,
+        "metadata": {
+            "generated_by": "attestral",
+            "generated_at": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+            "model_hash": _model_hash(model),
+            "review_chain_head": chain_head,
+        },
+        "default": "deny",
+        "servers": servers,
+    }
+
+
+def render_policy_yaml(policy: dict) -> str:
+    header = (
+        "# mcp-guard policy - COMPILED FROM AN ATTESTED DESIGN REVIEW.\n"
+        "# Do not hand-edit: change the design, re-review, re-compile.\n"
+        f"# model_hash: {policy['metadata']['model_hash'][:16]}…  "
+        f"chain_head: {(policy['metadata']['review_chain_head'] or '-')[:16]}\n"
+    )
+    return header + yaml.safe_dump(policy, sort_keys=False)

attestral/drift.py

@@ -0,0 +1,84 @@
+"""Design-runtime drift detection.
+
+Reads a JSONL stream of tool-call events (mcp-guard telemetry format:
+one object per line with at least `server`, `tool`, and optionally
+`args`, `url`, `ts`) and diffs each event against the compiled policy
+derived from the attested design.
+
+Fail-closed philosophy carries through: an event that references a server
+absent from the attested model is CRITICAL drift - the deployed system has
+grown beyond what was reviewed.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from attestral.model import Finding, Severity
+
+DRIFT_RULES = {
+    "DRF-001": ("Unattested server observed at runtime", Severity.CRITICAL),
+    "DRF-002": ("Denied server invoked at runtime", Severity.CRITICAL),
+    "DRF-003": ("Filesystem access outside attested roots", Severity.HIGH),
+    "DRF-004": ("Non-TLS transport observed for TLS-constrained server", Severity.HIGH),
+}
+
+
+def _mk(rule: str, server: str, detail: str, event_no: int) -> Finding:
+    title, sev = DRIFT_RULES[rule]
+    return Finding(
+        rule_id=rule,
+        title=title,
+        severity=sev,
+        component_id=f"mcp_server.{server}",
+        description=f"Event #{event_no}: {detail}",
+        recommendation=(
+            "Either revert the runtime change, or update the design, re-run the "
+            "review, and re-compile the policy so deployment and review match."
+        ),
+        source="runtime-telemetry",
+        origin="deterministic",
+    )
+
+
+def _path_in_roots(path: str, roots: list[str]) -> bool:
+    return any(path == r or path.startswith(r.rstrip("/") + "/") for r in roots)
+
+
+def detect_drift(policy: dict, events: list[dict]) -> list[Finding]:
+    servers: dict[str, dict] = policy.get("servers", {})
+    findings: list[Finding] = []
+    for i, ev in enumerate(events, 1):
+        name = str(ev.get("server", ""))
+        entry = servers.get(name)
+
+        if entry is None:
+            findings.append(_mk("DRF-001", name, f"server '{name}' is not in the attested design", i))
+            continue
+        if not entry.get("allow", False):
+            findings.append(_mk("DRF-002", name, entry.get("reason", "denied by policy"), i))
+            continue
+
+        constraints = entry.get("constraints", {})
+        roots = constraints.get("root_paths")
+        if roots:
+            for arg in [str(a) for a in ev.get("args", []) if str(a).startswith(("/", "~"))]:
+                if not _path_in_roots(arg, roots):
+                    findings.append(_mk("DRF-003", name, f"path '{arg}' outside attested roots {roots}", i))
+        if constraints.get("transport") == "tls_only" and str(ev.get("url", "")).startswith("http://"):
+            findings.append(_mk("DRF-004", name, f"plaintext url '{ev.get('url')}'", i))
+    findings.sort(key=lambda f: f.severity.rank, reverse=True)
+    return findings
+
+
+def load_events(path: str | Path) -> list[dict]:
+    events = []
+    for line in Path(path).read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events

attestral/evidence.py

@@ -0,0 +1,91 @@
+"""Evidence layer: tamper-evident audit chain + report export."""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+
+from attestral.model import Finding, SystemModel
+
+GENESIS = "0" * 64
+
+
+def audit_chain(findings: list[Finding]) -> list[dict]:
+    """SHA-256 hash chain over findings: entry N commits to entry N-1.
+
+    Any modification, insertion, or deletion of a past entry changes every
+    subsequent hash - the chain head is the integrity commitment for the run.
+    """
+    prev = GENESIS
+    chain = []
+    for f in findings:
+        payload = json.dumps(f.to_dict(), sort_keys=True)
+        digest = hashlib.sha256((prev + payload).encode()).hexdigest()
+        chain.append({"hash": digest, "prev": prev, "finding": f.to_dict()})
+        prev = digest
+    return chain
+
+
+def verify_chain(chain: list[dict]) -> bool:
+    prev = GENESIS
+    for entry in chain:
+        payload = json.dumps(entry["finding"], sort_keys=True)
+        if entry["prev"] != prev:
+            return False
+        if hashlib.sha256((prev + payload).encode()).hexdigest() != entry["hash"]:
+            return False
+        prev = entry["hash"]
+    return True
+
+
+def render_markdown(model: SystemModel, findings: list[Finding], target: str) -> str:
+    chain = audit_chain(findings)
+    head = chain[-1]["hash"] if chain else GENESIS
+    now = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    counts: dict[str, int] = {}
+    for f in findings:
+        counts[f.severity.value] = counts.get(f.severity.value, 0) + 1
+    lines = [
+        "# Attestral - Security Design Review",
+        "",
+        f"- **Target:** `{target}`",
+        f"- **Generated:** {now}",
+        f"- **Components modeled:** {len(model.components)}",
+        f"- **Findings:** {len(findings)} "
+        f"({', '.join(f'{v} {k}' for k, v in counts.items()) or 'none'})",
+        f"- **Evidence chain head:** `{head}`",
+        "",
+        "## Findings",
+        "",
+    ]
+    if not findings:
+        lines.append("No findings from the deterministic rule pack. ✅")
+    for i, f in enumerate(findings, 1):
+        lines += [
+            f"### {i}. [{f.severity.value.upper()}] {f.title}  `{f.rule_id}`",
+            "",
+            f"- **Component:** `{f.component_id}`  ·  **Source:** `{f.source}`",
+            f"- **Frameworks:** {', '.join(f.framework_refs) or '-'}",
+            "",
+            f.description,
+            "",
+            f"**Recommendation:** {f.recommendation}",
+            "",
+        ]
+    lines += [
+        "## Evidence chain",
+        "",
+        "| # | Rule | Hash (first 16) | Prev (first 16) |",
+        "|---|------|-----------------|-----------------|",
+    ]
+    for i, e in enumerate(chain, 1):
+        lines.append(
+            f"| {i} | {e['finding']['rule_id']} | `{e['hash'][:16]}` | `{e['prev'][:16]}` |"
+        )
+    lines += [
+        "",
+        "_Verify with `attestral verify report.json`. Any tampering with a past",
+        "entry invalidates every later hash and the chain head above._",
+        "",
+    ]
+    return "\n".join(lines)

attestral/ingest/__init__.py

@@ -0,0 +1,5 @@
+from attestral.ingest.terraform import ingest_terraform
+from attestral.ingest.mcp import ingest_mcp
+from attestral.ingest.scan import build_model
+
+__all__ = ["ingest_terraform", "ingest_mcp", "build_model"]

attestral/ingest/mcp.py

@@ -0,0 +1,44 @@
+"""MCP server configuration ingestion (claude_desktop_config.json / .mcp.json style)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from attestral.model import Component, SystemModel
+
+_SECRET_HINTS = ("KEY", "SECRET", "TOKEN", "PASSWORD", "CREDENTIAL")
+
+
+def ingest_mcp(path: str | Path, model: SystemModel) -> SystemModel:
+    p = Path(path)
+    files = [p] if p.is_file() else sorted(
+        list(p.rglob("*.mcp.json")) + list(p.rglob("mcp*.json")) + list(p.rglob("claude_desktop_config.json"))
+    )
+    for f in files:
+        try:
+            data = json.loads(f.read_text(errors="ignore"))
+        except json.JSONDecodeError:
+            continue
+        servers = data.get("mcpServers") or data.get("servers") or {}
+        for name, cfg in servers.items():
+            attrs: dict = {}
+            if isinstance(cfg, dict):
+                attrs["command"] = cfg.get("command", "")
+                attrs["args"] = cfg.get("args", [])
+                attrs["url"] = cfg.get("url", "")
+                env = cfg.get("env", {}) or {}
+                attrs["env_keys"] = list(env.keys())
+                attrs["_env_has_secrets"] = any(
+                    any(h in k.upper() for h in _SECRET_HINTS) for k in env
+                )
+            model.add(
+                Component(
+                    id=f"mcp_server.{name}",
+                    type="mcp_server",
+                    name=name,
+                    source=str(f),
+                    attributes=attrs,
+                    trust_boundary="agent_runtime",
+                )
+            )
+    return model

attestral/ingest/scan.py

@@ -0,0 +1,20 @@
+"""Directory scanner: routes files to the right ingesters and returns one model."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from attestral.ingest.mcp import ingest_mcp
+from attestral.ingest.terraform import ingest_terraform
+from attestral.model import SystemModel, TrustBoundary
+
+
+def build_model(path: str | Path) -> SystemModel:
+    model = SystemModel(
+        boundaries=[
+            TrustBoundary("cloud", "Cloud infrastructure"),
+            TrustBoundary("agent_runtime", "Agent / MCP runtime"),
+        ]
+    )
+    ingest_terraform(path, model)
+    ingest_mcp(path, model)
+    return model

attestral/ingest/terraform.py

@@ -0,0 +1,130 @@
+"""Lightweight Terraform (HCL) ingestion.
+
+Deliberately dependency-free: a pragmatic block/attribute scanner, not a full
+HCL parser. Good enough to build a design-level model; swap in python-hcl2
+later for full fidelity.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from attestral.model import Component, SystemModel
+
+_RESOURCE_RE = re.compile(r'resource\s+"([\w-]+)"\s+"([\w-]+)"\s*\{', re.MULTILINE)
+_ATTR_RE = re.compile(r'^\s*([\w]+)\s*=\s*(.+?)\s*$', re.MULTILINE)
+
+
+def _block_body(text: str, start: int) -> str:
+    """Return the text of the brace-balanced block starting at `start` ('{')."""
+    depth, i = 0, start
+    while i < len(text):
+        if text[i] == "{":
+            depth += 1
+        elif text[i] == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start + 1 : i]
+        i += 1
+    return text[start + 1 :]
+
+
+def _clean(value: str):
+    v = value.strip().rstrip(",")
+    if v.startswith('"') and v.endswith('"'):
+        return v[1:-1].replace('\\"', '"')
+    if v in ("true", "false"):
+        return v == "true"
+    return v
+
+
+def ingest_terraform(path: str | Path, model: SystemModel) -> SystemModel:
+    p = Path(path)
+    files = [p] if p.is_file() else sorted(p.rglob("*.tf"))
+    for f in files:
+        if _ingest_with_hcl2(f, model):
+            continue
+        _ingest_with_scanner(f, model)
+    return model
+
+
+# --- full parser (optional extra: pip install "attestral[terraform]") -------
+
+def _unq(v):
+    """Normalize python-hcl2 output: strip HCL string quoting, recurse containers."""
+    if isinstance(v, str):
+        if v.startswith('"') and v.endswith('"'):
+            v = v[1:-1]
+        return v.replace('\\"', '"')
+    if isinstance(v, list):
+        return [_unq(x) for x in v]
+    if isinstance(v, dict):
+        return {_unq(k): _unq(x) for k, x in v.items() if k != "__is_block__"}
+    return v
+
+
+def _flatten(attrs: dict, out: dict, cidrs: list) -> None:
+    for k, v in attrs.items():
+        if isinstance(v, dict):
+            _flatten(v, out, cidrs)
+        elif isinstance(v, list) and v and isinstance(v[0], dict):
+            for block in v:
+                _flatten(block, out, cidrs)
+        else:
+            out[k] = v
+            if k == "cidr_blocks" and isinstance(v, list):
+                cidrs.extend(str(x) for x in v)
+
+
+def _ingest_with_hcl2(f: Path, model: SystemModel) -> bool:
+    try:
+        import hcl2
+    except ImportError:
+        return False
+    try:
+        with f.open() as fh:
+            data = hcl2.load(fh)
+    except Exception:
+        return False  # malformed file: let the lenient scanner have a try
+    for block in _unq(data).get("resource", []):
+        for rtype, instances in block.items():
+            for rname, raw in instances.items():
+                attrs: dict = {}
+                cidrs: list[str] = []
+                _flatten(raw if isinstance(raw, dict) else {}, attrs, cidrs)
+                if cidrs:
+                    attrs["_cidr_blocks"] = cidrs
+                model.add(
+                    Component(
+                        id=f"{rtype}.{rname}",
+                        type=rtype,
+                        name=rname,
+                        source=str(f),
+                        attributes=attrs,
+                        trust_boundary="cloud",
+                    )
+                )
+    return True
+
+
+# --- dependency-free fallback scanner ---------------------------------------
+
+def _ingest_with_scanner(f: Path, model: SystemModel) -> None:
+    text = f.read_text(errors="ignore")
+    for m in _RESOURCE_RE.finditer(text):
+        rtype, rname = m.group(1), m.group(2)
+        body = _block_body(text, text.index("{", m.end() - 1))
+        attrs = {k: _clean(v) for k, v in _ATTR_RE.findall(body)}
+        cidrs = re.findall(r'cidr_blocks\s*=\s*\[([^\]]*)\]', body)
+        if cidrs:
+            attrs["_cidr_blocks"] = re.findall(r'"([^"]+)"', ",".join(cidrs))
+        model.add(
+            Component(
+                id=f"{rtype}.{rname}",
+                type=rtype,
+                name=rname,
+                source=str(f),
+                attributes=attrs,
+                trust_boundary="cloud",
+            )
+        )

attestral/llm.py

@@ -0,0 +1,62 @@
+"""Optional LLM threat elicitation layer.
+
+Runs only when --llm is passed and ANTHROPIC_API_KEY is set. Findings from
+this layer are tagged origin="llm" and never mixed silently with the
+deterministic layer - regulated buyers need to know which is which.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from attestral.model import Finding, Severity, SystemModel
+
+_SYSTEM = (
+    "You are a principal security engineer performing a design review. "
+    "Given a JSON system model (components, edges, trust boundaries), identify "
+    "design-level threats the deterministic rules would miss: authn/authz gaps, "
+    "trust-boundary violations, agentic risks (prompt-injection paths, tool "
+    "permission escalation, handoff confusion). Respond ONLY with a JSON array; "
+    "each item: {\"title\", \"severity\" (critical|high|medium|low|info), "
+    "\"component_id\", \"description\", \"recommendation\"}. No markdown, no preamble."
+)
+
+
+def elicit(model: SystemModel, max_findings: int = 10) -> list[Finding]:
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        return []
+    try:
+        import anthropic
+    except ImportError:
+        return []
+    client = anthropic.Anthropic()
+    msg = client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=2000,
+        system=_SYSTEM,
+        messages=[{"role": "user", "content": model.to_json()[:100_000]}],
+    )
+    text = "".join(b.text for b in msg.content if getattr(b, "type", "") == "text")
+    text = text.replace("```json", "").replace("```", "").strip()
+    try:
+        items = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+    findings = []
+    for i, item in enumerate(items[:max_findings]):
+        try:
+            findings.append(
+                Finding(
+                    rule_id=f"ATL-LLM-{i+1:03d}",
+                    title=str(item.get("title", "LLM finding")),
+                    severity=Severity(str(item.get("severity", "info")).lower()),
+                    component_id=str(item.get("component_id", "model")),
+                    description=str(item.get("description", "")),
+                    recommendation=str(item.get("recommendation", "")),
+                    source="llm-elicitation",
+                    origin="llm",
+                )
+            )
+        except (ValueError, TypeError):
+            continue
+    return findings

attestral/model.py

@@ -0,0 +1,103 @@
+"""Unified system model: components, edges, trust boundaries, findings."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Any
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+    @property
+    def rank(self) -> int:
+        return {"critical": 4, "high": 3, "medium": 2, "low": 1, "info": 0}[self.value]
+
+
+@dataclass
+class Component:
+    """A node in the system model: cloud resource, service, MCP server, agent, datastore."""
+    id: str
+    type: str                       # e.g. aws_s3_bucket, mcp_server, agent, service
+    name: str
+    source: str                     # file path the component was ingested from
+    attributes: dict[str, Any] = field(default_factory=dict)
+    trust_boundary: str | None = None
+
+    def attr(self, key: str, default: Any = None) -> Any:
+        return self.attributes.get(key, default)
+
+
+@dataclass
+class Edge:
+    """A directed relationship: data flow, invocation, tool access, network path."""
+    source_id: str
+    target_id: str
+    kind: str = "dataflow"          # dataflow | invokes | tool_access | network
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TrustBoundary:
+    id: str
+    name: str
+    description: str = ""
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    title: str
+    severity: Severity
+    component_id: str
+    description: str
+    recommendation: str
+    source: str = ""
+    framework_refs: list[str] = field(default_factory=list)   # e.g. ["ASVS V1.2", "NIST AC-3"]
+    origin: str = "deterministic"   # deterministic | llm
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["severity"] = self.severity.value
+        return d
+
+
+@dataclass
+class SystemModel:
+    components: list[Component] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+    boundaries: list[TrustBoundary] = field(default_factory=list)
+
+    def add(self, component: Component) -> None:
+        self.components.append(component)
+
+    def by_type(self, prefix: str) -> list[Component]:
+        return [c for c in self.components if c.type.startswith(prefix)]
+
+    def get(self, component_id: str) -> Component | None:
+        return next((c for c in self.components if c.id == component_id), None)
+
+    def crossing_edges(self) -> list[Edge]:
+        """Edges whose endpoints sit in different trust boundaries."""
+        out = []
+        for e in self.edges:
+            s, t = self.get(e.source_id), self.get(e.target_id)
+            if s and t and s.trust_boundary != t.trust_boundary:
+                out.append(e)
+        return out
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "components": [asdict(c) for c in self.components],
+                "edges": [asdict(e) for e in self.edges],
+                "boundaries": [asdict(b) for b in self.boundaries],
+            },
+            indent=2,
+            default=str,
+        )

attestral/rules/__init__.py

@@ -0,0 +1,3 @@
+from attestral.rules.engine import RuleEngine
+
+__all__ = ["RuleEngine"]

attestral/rules/core_rules.yaml

@@ -0,0 +1,93 @@
+# Attestral core rule pack (v0)
+# Deterministic, design-level checks. Each rule targets a component type
+# and applies structured matchers against ingested attributes.
+rules:
+  - id: ATL-001
+    title: S3 bucket allows public access
+    severity: critical
+    target: aws_s3_bucket
+    match: { attr_in: { acl: ["public-read", "public-read-write"] } }
+    description: Bucket ACL grants access to all users, exposing stored data to the internet.
+    recommendation: Remove the public ACL and enforce account-level S3 Block Public Access.
+    frameworks: ["NIST AC-3", "ASVS V4.1", "SOC2 CC6.1"]
+
+  - id: ATL-002
+    title: Security group open to the world
+    severity: high
+    target: aws_security_group
+    match: { attr_list_contains: { _cidr_blocks: "0.0.0.0/0" } }
+    description: Ingress permits traffic from any IPv4 address, expanding the attack surface to the entire internet.
+    recommendation: Restrict ingress CIDRs to known ranges or place the service behind a load balancer/VPN.
+    frameworks: ["NIST SC-7", "SOC2 CC6.6"]
+
+  - id: ATL-003
+    title: IAM policy grants wildcard actions
+    severity: critical
+    target: aws_iam_policy
+    match: { attr_contains: { policy: '"Action": "*"' } }
+    description: Wildcard IAM actions violate least privilege; a compromised principal gains full account control.
+    recommendation: Enumerate required actions explicitly; use IAM Access Analyzer to right-size.
+    frameworks: ["NIST AC-6", "ASVS V4.1", "SOC2 CC6.3"]
+
+  - id: ATL-004
+    title: Database publicly accessible
+    severity: critical
+    target: aws_db_instance
+    match: { attr_equals: { publicly_accessible: true } }
+    description: The database endpoint is reachable from the public internet.
+    recommendation: Set publicly_accessible = false and access the DB through private subnets or a bastion.
+    frameworks: ["NIST SC-7", "SOC2 CC6.1"]
+
+  - id: ATL-005
+    title: Storage encryption not declared
+    severity: medium
+    target: aws_db_instance
+    match: { attr_missing: storage_encrypted }
+    description: Encryption at rest is not declared in the design; data may be stored in plaintext.
+    recommendation: Set storage_encrypted = true (and kms_key_id for CMK control).
+    frameworks: ["NIST SC-28", "ASVS V6.1", "SOC2 CC6.7"]
+
+  - id: ATL-101
+    title: MCP server uses non-TLS transport
+    severity: high
+    target: mcp_server
+    match: { attr_starts_with: { url: "http://" } }
+    description: Tool traffic (including prompts and tool results) crosses the network unencrypted.
+    recommendation: Serve the MCP endpoint over HTTPS/WSS only.
+    frameworks: ["NIST SC-8", "OWASP-AgSec TLS-1"]
+
+  - id: ATL-102
+    title: Filesystem MCP server rooted at a broad path
+    severity: high
+    target: mcp_server
+    match: { attr_list_any_of: { args: ["/", "~", "/home", "/Users"] } }
+    description: The agent gains read/write reach over a broad filesystem root, far beyond task scope.
+    recommendation: Scope the server to the narrowest project directory that supports the workflow.
+    frameworks: ["NIST AC-6", "OWASP-AgSec TOOL-2"]
+
+  - id: ATL-103
+    title: Shell-capable MCP server configured
+    severity: critical
+    target: mcp_server
+    match: { attr_any_contains: { command: ["bash", "sh", "cmd", "powershell"], args: ["bash", "sh -c", "shell"] } }
+    description: The agent can execute arbitrary shell commands; a single prompt injection becomes code execution.
+    recommendation: Replace generic shell access with narrowly scoped, allowlisted tools; gate with human approval.
+    frameworks: ["OWASP-AgSec TOOL-1", "NIST AC-6"]
+
+  - id: ATL-104
+    title: Secrets passed to MCP server via environment
+    severity: medium
+    target: mcp_server
+    match: { attr_equals: { _env_has_secrets: true } }
+    description: Credentials in tool-server env vars are exposed to the tool process and often to model context.
+    recommendation: Use a secret manager or OS keychain; never place raw credentials where tool output can echo them.
+    frameworks: ["NIST IA-5", "ASVS V2.10", "OWASP-AgSec CRED-1"]
+
+  - id: ATL-201
+    title: Agent runtime and cloud share no declared boundary controls
+    severity: info
+    target: model
+    match: { model_has_both: ["mcp_server", "aws_"] }
+    description: The design contains both agent tooling and cloud resources but no declared control between the two trust zones.
+    recommendation: Document the authn/authz path from agent runtime to cloud APIs; deny by default.
+    frameworks: ["NIST AC-4", "OWASP-AgSec ARCH-1"]

attestral/rules/engine.py

@@ -0,0 +1,101 @@
+"""Deterministic rule engine: structured matchers over the system model.
+
+No eval(), no string execution - every matcher is a named, typed check.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from attestral.model import Component, Finding, Severity, SystemModel
+
+_CORE = Path(__file__).parent / "core_rules.yaml"
+
+
+def _matches(component: Component, match: dict[str, Any]) -> bool:
+    for kind, spec in match.items():
+        if kind == "attr_equals":
+            if not all(component.attr(k) == v for k, v in spec.items()):
+                return False
+        elif kind == "attr_in":
+            if not all(component.attr(k) in v for k, v in spec.items()):
+                return False
+        elif kind == "attr_missing":
+            keys = spec if isinstance(spec, list) else [spec]
+            if not all(component.attr(k) is None for k in keys):
+                return False
+        elif kind == "attr_starts_with":
+            if not all(str(component.attr(k, "")).startswith(v) for k, v in spec.items()):
+                return False
+        elif kind == "attr_contains":
+            if not all(v in str(component.attr(k, "")) for k, v in spec.items()):
+                return False
+        elif kind == "attr_list_contains":
+            if not all(v in (component.attr(k) or []) for k, v in spec.items()):
+                return False
+        elif kind == "attr_list_any_of":
+            ok = False
+            for k, values in spec.items():
+                items = [str(x) for x in (component.attr(k) or [])]
+                if any(any(v == i or i.startswith(v + "/") or v in i for i in items) for v in values):
+                    ok = True
+            if not ok:
+                return False
+        elif kind == "attr_any_contains":
+            ok = False
+            for k, values in spec.items():
+                hay = component.attr(k)
+                hay = " ".join(str(x) for x in hay) if isinstance(hay, list) else str(hay or "")
+                if any(v in hay for v in values):
+                    ok = True
+            if not ok:
+                return False
+        else:
+            return False  # unknown matcher: fail closed
+    return True
+
+
+class RuleEngine:
+    def __init__(self, rule_paths: list[str | Path] | None = None):
+        paths = [_CORE] + [Path(p) for p in (rule_paths or [])]
+        self.rules: list[dict] = []
+        for p in paths:
+            data = yaml.safe_load(Path(p).read_text()) or {}
+            self.rules.extend(data.get("rules", []))
+
+    def evaluate(self, model: SystemModel) -> list[Finding]:
+        findings: list[Finding] = []
+        for rule in self.rules:
+            target = rule.get("target", "")
+            match = rule.get("match", {})
+            if target == "model":
+                findings.extend(self._evaluate_model_rule(rule, match, model))
+                continue
+            for c in model.by_type(target):
+                if _matches(c, match):
+                    findings.append(self._finding(rule, c.id, c.source))
+        findings.sort(key=lambda f: f.severity.rank, reverse=True)
+        return findings
+
+    def _evaluate_model_rule(self, rule: dict, match: dict, model: SystemModel) -> list[Finding]:
+        if "model_has_both" in match:
+            a, b = match["model_has_both"]
+            if model.by_type(a) and model.by_type(b):
+                return [self._finding(rule, "model", "system model")]
+        return []
+
+    @staticmethod
+    def _finding(rule: dict, component_id: str, source: str) -> Finding:
+        return Finding(
+            rule_id=rule["id"],
+            title=rule["title"],
+            severity=Severity(rule["severity"]),
+            component_id=component_id,
+            description=rule.get("description", ""),
+            recommendation=rule.get("recommendation", ""),
+            source=source,
+            framework_refs=rule.get("frameworks", []),
+            origin="deterministic",
+        )

attestral-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: attestral
+Version: 0.1.0
+Summary: Continuous, audit-ready security design review for cloud and agentic systems
+Author: Attestral
+License: Apache-2.0
+License-File: LICENSE
+Keywords: design-review,mcp,security,terraform,threat-modeling
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Provides-Extra: terraform
+Requires-Dist: python-hcl2>=4.3; extra == 'terraform'
+Description-Content-Type: text/markdown
+
+# Attestral
+
+**Continuous, audit-ready security design review for cloud and agentic systems.**
+
+Attestral ingests your infrastructure-as-code and agent/MCP configurations, builds a unified system model, runs a deterministic rule pack (plus optional LLM threat elicitation), and produces a design review with a **tamper-evident evidence chain** you can hand to reviewers, auditors, and customers.
+
+```
+pip install attestral
+attestral scan ./my-project
+```
+
+## Why
+
+- Legacy threat modeling platforms are questionnaire-driven, consultant-heavy, and priced for the Fortune 500. In practice most teams do this work in a spreadsheet.
+- The fastest-growing attack surface (AI agents, MCP servers, tool permissions) is the one legacy tools understand least.
+- Review output is only worth what you can prove. Every Attestral run emits a SHA-256 hash chain over its findings, and altering any past entry invalidates the chain head.
+
+## What it does today (v0.1)
+
+| Layer | Status |
+|---|---|
+| Terraform ingestion (design-level) | ✅ dependency-free scanner |
+| MCP server config ingestion | ✅ `mcp.json` / `claude_desktop_config.json` |
+| Deterministic rule pack | ✅ 10 rules: cloud misconfig + agentic tool risk |
+| Framework mapping | ✅ NIST 800-53, ASVS, SOC 2, OWASP Agentic refs per finding |
+| Evidence chain + verification | ✅ `attestral verify report.json` |
+| Fail-closed CI gate | ✅ `--fail-on high` |
+| LLM threat elicitation | ✅ optional, `--llm` + `ANTHROPIC_API_KEY`, findings tagged separately |
+| Design→policy compiler (`attestral compile`) | ✅ mcp-guard default-deny policy, bound to the review chain head |
+| Design-runtime drift detection (`attestral drift`) | ✅ JSONL telemetry diffed against the attested design |
+| PR design-diff (GitHub App) | 🔜 roadmap |
+| IriusRisk/ThreatModeler import | 🔜 roadmap |
+
+## Usage
+
+```bash
+# Scan a project (Terraform + MCP configs discovered automatically)
+attestral scan ./my-project
+
+# Markdown + JSON evidence report
+attestral scan ./my-project -o review --format both
+
+# CI gate: fail the pipeline on high/critical design findings
+attestral scan . --fail-on high
+
+# Add LLM design-review reasoning on top of the deterministic layer
+export ANTHROPIC_API_KEY=...
+attestral scan ./my-project --llm
+
+# Prove a report hasn't been altered
+attestral verify review.json
+
+# Close the loop: compile the attested design into a runtime policy...
+attestral compile ./my-project -o policy.yaml
+# ...and diff runtime telemetry (mcp-guard JSONL) against it
+attestral drift policy.yaml events.jsonl --fail-on-drift
+```
+
+Try it on the included demo:
+
+```bash
+attestral scan examples/demo-project
+```
+
+## Architecture
+
+1. **Ingest** → unified `SystemModel` (components, edges, trust boundaries) from Terraform and MCP configs.
+2. **Deterministic layer** → typed matchers in YAML rules (`attestral/rules/core_rules.yaml`). No `eval`, unknown matchers fail closed.
+3. **LLM layer (optional)** → design-level threat elicitation over the model JSON; findings tagged `origin: llm`, never silently mixed with deterministic results.
+4. **Evidence layer** → hash-chained findings, markdown/JSON export, offline verification.
+
+## Writing custom rules
+
+```yaml
+rules:
+ - id: ORG-001
+ title: Internal service exposed without auth attribute
+ severity: high
+ target: aws_lb
+ match: { attr_missing: auth }
+ description: ...
+ recommendation: ...
+ frameworks: ["NIST AC-3"]
+```
+
+```bash
+attestral scan . # core pack
+python -c "from attestral.rules import RuleEngine; RuleEngine(['org_rules.yaml'])"
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff check attestral tests
+```
+
+## License
+
+Apache 2.0

attestral-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+attestral/__init__.py,sha256=MBZxfVWITQ1dA3-FQ7suNAkmdqkKQo8oH-PGchO5rnM,245
+attestral/cli.py,sha256=cNQS5TIHxTldqNlCZkyvm6VVZ7c9EKv4DaLToiVUzZw,4621
+attestral/compile.py,sha256=6eRijSke89rrP838gwPeHY--f86FYatj0s0APEi7IjA,3622
+attestral/drift.py,sha256=h4_0aq2E1IVP0IOj1pnoM4F0dkgAYXLCDDLNbtRG0D4,3171
+attestral/evidence.py,sha256=d4v6oClMyzdQGAtbYt70aX4lnxv5exwLbpbfFDO40Pg,3097
+attestral/llm.py,sha256=M0h9w4ZK-L3B7_YwGnPVEC0GfUVoAli_kx2UTHAid9Q,2384
+attestral/model.py,sha256=SygO3E2HXvU_FpIxEHCZlwyuwi4zLADn_f3_MdznMVo,3076
+attestral/ingest/__init__.py,sha256=2TCIdjq7q2o8xj6tn0LDmOegk3T6IS19tgp66tlMFjs,207
+attestral/ingest/mcp.py,sha256=b8nH9sCPAN8tuf1uepwr3iWsb3RjAgUMhenJpD7oA20,1607
+attestral/ingest/scan.py,sha256=X-YewzzKEYvbzVK61Q00oYfQMufgMB3YFUskPgWe4Pk,621
+attestral/ingest/terraform.py,sha256=Pqt4bW-Ch-tJCfUdaUiUVor9MAtpBLOn9hRyTu1Vfhk,4222
+attestral/rules/__init__.py,sha256=J14ai9CbgcNegaQ0xNfAZPeM76wiAXDVXsIyXSf2uns,72
+attestral/rules/core_rules.yaml,sha256=qY2aXZebj_r4WhKEStKGkP7gLdqruKGd3UGU2kA8SVg,4528
+attestral/rules/engine.py,sha256=iMjk7M-DNGnhQC6hLZOX4_a_lvHZ66RBzg-8LIX7Bko,3984
+attestral-0.1.0.dist-info/METADATA,sha256=HQBdTJx8Kph0Xpk2LOhyISvkvIiuVa4efKDqQ7COH0o,4299
+attestral-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+attestral-0.1.0.dist-info/entry_points.txt,sha256=wICz2OqyydNSxttRcr0KuZ9f-ju02TBL5BwlT_kUgqg,49
+attestral-0.1.0.dist-info/licenses/LICENSE,sha256=fJyJtKmZmQILfa_KJ-mJd_35kX8Cy7fLtP7EHVw8zDg,570
+attestral-0.1.0.dist-info/RECORD,,

attestral-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

attestral-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+attestral = attestral.cli:main

attestral-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright 2026 Attestral
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.