sectum-ai 0.1.1__tar.gz

sectum_ai-0.1.1/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+
+# Builds / distributions
+build/
+dist/
+*.whl
+
+# mkdocs build output
+site/
+
+# uv / virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Example run artifacts (generated by examples/*/run.sh, incl. the
+# out-residual/ workdir from the docs/samples regeneration recipe)
+examples/*/out/
+examples/*/out-residual/
+
+# Sectum CLI default workdir (generated by seed/probe/report; not source)
+.sectum-ai/
+examples/*/.sectum-ai/
+
+# Project-local engineering spec (not shared)
+CLAUDE.md

sectum_ai-0.1.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: sectum-ai
+Version: 0.1.1
+Summary: Sectum AI - multi-tenant AI verification: core substrate runner and the sectum-ai CLI.
+Project-URL: Homepage, https://sectum.ai
+Project-URL: Documentation, https://docs.sectum.ai
+Project-URL: Repository, https://github.com/sectum-ai/sectum-ai
+Project-URL: Changelog, https://github.com/sectum-ai/sectum-ai/blob/main/CHANGELOG.md
+Author: Sectum AI
+License-Expression: Apache-2.0
+Keywords: ai-security,llm,multi-tenant,rag,verification
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6
+Requires-Dist: sectum-ai-adapters
+Requires-Dist: sectum-ai-evidence
+Requires-Dist: sectum-ai-probes
+Requires-Dist: sectum-ai-spec
+Requires-Dist: typer>=0.12
+Provides-Extra: encryption
+Requires-Dist: cryptography>=43; extra == 'encryption'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=3; extra == 'sentence-transformers'
+Provides-Extra: weasyprint
+Requires-Dist: sectum-ai-evidence[weasyprint]; extra == 'weasyprint'
+Description-Content-Type: text/markdown
+
+# sectum-ai
+
+**Multi-tenant AI verification.** This is the core distribution of [Sectum AI](https://github.com/sectum-ai/sectum-ai):
+the marker-substrate runner and the `sectum-ai` command-line interface.
+
+Sectum AI provisions synthetic tenants on an AI stack, seeds them with
+cryptographic canary markers, runs benign and adversarial probes from each
+tenant's session, and detects cross-tenant data leakage across every surface —
+producing tamper-evident, control-mapped evidence that an auditor accepts.
+
+## Install
+
+```sh
+pip install sectum-ai
+```
+
+This pulls the full family: `sectum-ai-spec` (data models), `sectum-ai-probes`
+(the Class 1–11 attack catalog + leak-detection pipeline), `sectum-ai-adapters`
+(connectors for vector stores, caches, observability, RAG, agents, and MCP), and
+`sectum-ai-evidence` (the tamper-evident evidence chain + `sectum-ai verify`).
+
+## Quickstart
+
+```sh
+sectum-ai seed      # provision synthetic tenants + plant canary markers
+sectum-ai probe     # run the attack catalog from each tenant's session
+sectum-ai report    # assemble a signed, control-mapped evidence pack (JSON + PDF)
+sectum-ai verify .sectum-ai/evidence.json   # independently re-verify the pack
+```
+
+## Links
+
+- Documentation: <https://docs.sectum.ai>
+- Source, full README, and attack catalog: <https://github.com/sectum-ai/sectum-ai>
+
+Apache-2.0. The marker substrate, attack catalog, adapters, evidence chain, and
+the independent `sectum-ai verify` are fully open source.

sectum_ai-0.1.1/README.md

@@ -0,0 +1,37 @@
+# sectum-ai
+
+**Multi-tenant AI verification.** This is the core distribution of [Sectum AI](https://github.com/sectum-ai/sectum-ai):
+the marker-substrate runner and the `sectum-ai` command-line interface.
+
+Sectum AI provisions synthetic tenants on an AI stack, seeds them with
+cryptographic canary markers, runs benign and adversarial probes from each
+tenant's session, and detects cross-tenant data leakage across every surface —
+producing tamper-evident, control-mapped evidence that an auditor accepts.
+
+## Install
+
+```sh
+pip install sectum-ai
+```
+
+This pulls the full family: `sectum-ai-spec` (data models), `sectum-ai-probes`
+(the Class 1–11 attack catalog + leak-detection pipeline), `sectum-ai-adapters`
+(connectors for vector stores, caches, observability, RAG, agents, and MCP), and
+`sectum-ai-evidence` (the tamper-evident evidence chain + `sectum-ai verify`).
+
+## Quickstart
+
+```sh
+sectum-ai seed      # provision synthetic tenants + plant canary markers
+sectum-ai probe     # run the attack catalog from each tenant's session
+sectum-ai report    # assemble a signed, control-mapped evidence pack (JSON + PDF)
+sectum-ai verify .sectum-ai/evidence.json   # independently re-verify the pack
+```
+
+## Links
+
+- Documentation: <https://docs.sectum.ai>
+- Source, full README, and attack catalog: <https://github.com/sectum-ai/sectum-ai>
+
+Apache-2.0. The marker substrate, attack catalog, adapters, evidence chain, and
+the independent `sectum-ai verify` are fully open source.

sectum_ai-0.1.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sectum-ai"
+version = "0.1.1"
+description = "Sectum AI - multi-tenant AI verification: core substrate runner and the sectum-ai CLI."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "Sectum AI" }]
+keywords = ["ai-security", "multi-tenant", "rag", "llm", "verification"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "typer>=0.12",
+    "pyyaml>=6",
+    # config.py and cli/app.py import pydantic directly; declare it rather than
+    # relying on the transitive dependency via sectum-ai-spec (§13, mirrors adapters).
+    "pydantic>=2.9",
+    "sectum-ai-spec",
+    "sectum-ai-adapters",
+    "sectum-ai-probes",
+    "sectum-ai-evidence",
+]
+
+[project.optional-dependencies]
+# At-rest encryption of the seeded substrate (and its ground-truth manifest).
+# Optional: the default unencrypted path needs no third-party dependency.
+encryption = ["cryptography>=43"]
+# weasyprint audit-pack PDF engine (sectum-ai report --pdf-engine weasyprint).
+# Optional: the default reportlab renderer is pure Python with no system
+# libraries; weasyprint adds the pango/cairo system libraries.
+weasyprint = ["sectum-ai-evidence[weasyprint]"]
+# Real embedding providers for the Class 2 per-model RPR sweep (embedding_models:
+# ["st:all-mpnet-base-v2", ...]). Optional: the default hashing/recall sweep is
+# pure-Python. sentence-transformers runs locally (BYOC-safe); openai is a
+# hosted call. See packages/core/src/sectum_ai/embeddings.py.
+sentence-transformers = ["sentence-transformers>=3"]
+openai = ["openai>=1.40"]
+
+[project.scripts]
+sectum-ai = "sectum_ai.cli.app:app"
+
+[project.urls]
+Homepage = "https://sectum.ai"
+Documentation = "https://docs.sectum.ai"
+Repository = "https://github.com/sectum-ai/sectum-ai"
+Changelog = "https://github.com/sectum-ai/sectum-ai/blob/main/CHANGELOG.md"
+
+[tool.uv.sources]
+sectum-ai-spec = { workspace = true }
+sectum-ai-adapters = { workspace = true }
+sectum-ai-probes = { workspace = true }
+sectum-ai-evidence = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/sectum_ai"]
+sources = ["src"]

sectum_ai-0.1.1/src/sectum_ai/baseline.py

@@ -0,0 +1,330 @@
+"""Regression baselines: save a run's metrics and compare later runs to it.
+
+A baseline is a saved snapshot of a run's headline metrics. Comparing a later
+run to the baseline flags regressions - a metric that moved in the worse
+(higher-leakage) direction, for example a higher Retrieval-Pivot Rate or more
+confirmed findings after an embedding-model or prompt change (the engineering
+spec, sections 10 and 14).
+"""
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+
+from sectum_ai.spec import Finding, FindingStatus, RunMetrics, RunResult, Severity
+
+
+@dataclass(frozen=True)
+class MetricDelta:
+    """One headline metric compared between a baseline run and a later run."""
+
+    name: str
+    baseline: float
+    current: float
+    # An informational metric is reported for visibility but never counts as a
+    # regression: an erasure *caveat* (a backend with no per-tenant erasure API,
+    # Class 11 hiding place #8) is a coverage limitation, not an isolation
+    # failure. It is kept distinct from erasure *residue*, which is a real
+    # failure and does regress.
+    informational: bool = False
+
+    @property
+    def regressed(self) -> bool:
+        """True when the metric moved in the worse, higher-leakage direction.
+
+        Always ``False`` for an informational metric. Compared with a small
+        tolerance so floating-point round-trip noise (a metric serialized to
+        JSON and back) never reads as a regression; real leakage changes are far
+        larger than the epsilon.
+        """
+        if self.informational:
+            return False
+        return self.current > self.baseline + 1e-9
+
+
+@dataclass(frozen=True)
+class BaselineComparison:
+    """The outcome of comparing a run's metrics against a saved baseline."""
+
+    deltas: tuple[MetricDelta, ...]
+
+    @property
+    def regressed(self) -> bool:
+        """True when any compared metric regressed."""
+        return any(delta.regressed for delta in self.deltas)
+
+
+def _dict_deltas(
+    label: str,
+    baseline: Mapping[str, float],
+    current: Mapping[str, float],
+    *,
+    informational: bool = False,
+) -> list[MetricDelta]:
+    """A MetricDelta per key across both mappings; a key absent on a side is 0.0."""
+    return [
+        MetricDelta(
+            name=f"{label}[{key}]",
+            baseline=float(baseline.get(key, 0.0)),
+            current=float(current.get(key, 0.0)),
+            informational=informational,
+        )
+        for key in sorted(set(baseline) | set(current))
+    ]
+
+
+def compare_metrics(baseline: RunMetrics, current: RunMetrics) -> BaselineComparison:
+    """Compare a later run's metrics to a baseline; flag every metric that worsened.
+
+    Higher means more leakage for every metric, so an increase is a regression.
+    Confirmed findings and the Retrieval-Pivot Rate are compared directly; the
+    per-model Retrieval-Pivot Rate, the per-probe finding counts, the per-surface
+    erasure residue, and the per-pair side-channel effect sizes are compared key
+    by key. A Retrieval-Pivot Rate that was not measured, or a key absent on one
+    side, counts as ``0.0``.
+
+    The per-model RPR and per-probe counts matter because an aggregate can hide a
+    regression: swapping one embedding model can spike that model's RPR (the
+    canonical Phase-5 check, the engineering spec section 14) while the overall
+    rate is unchanged, and one probe can start leaking as another stops with no
+    change to the total confirmed count.
+
+    Per-surface erasure *caveats* are also reported, but as informational deltas
+    that never count as a regression: a caveat is a coverage limitation of the
+    backend (Class 11 hiding place #8), not an isolation failure like residue.
+    """
+    deltas: list[MetricDelta] = [
+        MetricDelta(
+            name="confirmed_findings",
+            baseline=float(baseline.confirmed_findings),
+            current=float(current.confirmed_findings),
+        ),
+        MetricDelta(
+            name="retrieval_pivot_rate",
+            baseline=baseline.retrieval_pivot_rate or 0.0,
+            current=current.retrieval_pivot_rate or 0.0,
+        ),
+        # Class 3/6/10 headline rates: higher means more cross-tenant leakage, so
+        # an increase regresses exactly like the retrieval-pivot rate above.
+        MetricDelta(
+            name="poisoning_bleed_delta",
+            baseline=baseline.poisoning_bleed_delta or 0.0,
+            current=current.poisoning_bleed_delta or 0.0,
+        ),
+        MetricDelta(
+            name="inversion_reconstruction_rate",
+            baseline=baseline.inversion_reconstruction_rate or 0.0,
+            current=current.inversion_reconstruction_rate or 0.0,
+        ),
+        MetricDelta(
+            name="extraction_efficiency",
+            baseline=baseline.extraction_efficiency or 0.0,
+            current=current.extraction_efficiency or 0.0,
+        ),
+    ]
+    deltas.extend(
+        _dict_deltas(
+            "retrieval_pivot_rate_by_model",
+            baseline.retrieval_pivot_rate_by_model,
+            current.retrieval_pivot_rate_by_model,
+        )
+    )
+    deltas.extend(
+        _dict_deltas(
+            "per_probe_findings",
+            {key: float(value) for key, value in baseline.per_probe_findings.items()},
+            {key: float(value) for key, value in current.per_probe_findings.items()},
+        )
+    )
+    deltas.extend(
+        _dict_deltas("erasure_residue", baseline.erasure_residue, current.erasure_residue)
+    )
+    deltas.extend(
+        _dict_deltas(
+            "side_channel_effect_sizes",
+            baseline.side_channel_effect_sizes,
+            current.side_channel_effect_sizes,
+        )
+    )
+    deltas.extend(
+        _dict_deltas(
+            "erasure_caveats",
+            baseline.erasure_caveats,
+            current.erasure_caveats,
+            informational=True,
+        )
+    )
+    return BaselineComparison(deltas=tuple(deltas))
+
+
+_SEVERITY_RANK: dict[Severity, int] = {
+    Severity.INFO: 0,
+    Severity.LOW: 1,
+    Severity.MEDIUM: 2,
+    Severity.HIGH: 3,
+    Severity.CRITICAL: 4,
+}
+
+
+@dataclass(frozen=True)
+class FindingChange:
+    """A finding present in both runs (same ``finding_id``) that changed in place.
+
+    ``previous`` is its earlier-run copy and ``current`` its later-run copy. A
+    change is a difference in status (e.g. unverified -> confirmed) or severity
+    (e.g. low -> critical) for what is, by id, the same leak.
+    """
+
+    previous: Finding
+    current: Finding
+
+    @property
+    def status_changed(self) -> bool:
+        """True when the finding's status differs between the runs."""
+        return self.previous.status is not self.current.status
+
+    @property
+    def severity_changed(self) -> bool:
+        """True when the finding's severity differs between the runs."""
+        return self.previous.severity is not self.current.severity
+
+    @property
+    def severity_escalated(self) -> bool:
+        """True when the severity rose (a worse posture), not fell."""
+        return _SEVERITY_RANK[self.current.severity] > _SEVERITY_RANK[self.previous.severity]
+
+
+@dataclass(frozen=True)
+class FindingDiff:
+    """Finding-level delta between two runs, keyed by stable ``finding_id``.
+
+    ``appeared`` are findings in the later run but not the earlier one (a new
+    leak); ``resolved`` are in the earlier run but gone from the later one (a
+    fixed leak); ``persisting`` are in both (the later copy). Each list follows
+    its source run's own deterministic finding order.
+    """
+
+    appeared: tuple[Finding, ...]
+    resolved: tuple[Finding, ...]
+    persisting: tuple[Finding, ...]
+    # Findings confirmed in the later run whose id was not already confirmed in
+    # the earlier run -- the regression signal. Broader than "confirmed and
+    # newly appeared by id": it also catches a finding that persisted by id but
+    # was upgraded unverified -> confirmed between the runs. An unverified
+    # candidate never appears here (the false-positive control, the engineering
+    # spec section 6.4), so it cannot flip a diff to a regression on its own.
+    newly_confirmed: tuple[Finding, ...]
+    # Findings present in both runs whose status or severity changed in place
+    # (matched by id), for visibility. The subset that gates a regression is
+    # ``severity_escalations``.
+    changed: tuple[FindingChange, ...]
+
+    @property
+    def severity_escalations(self) -> tuple[FindingChange, ...]:
+        """Persisting findings, confirmed in both runs, whose severity rose.
+
+        A leak that was already a confirmed cross-tenant finding becoming more
+        severe (e.g. low -> critical) is a worse isolation posture between the
+        runs, so it gates as a regression. Requiring confirmed-in-both keeps this
+        disjoint from ``newly_confirmed`` (which covers unverified -> confirmed)
+        and clear of the false-positive control.
+        """
+        return tuple(
+            change
+            for change in self.changed
+            if change.severity_escalated
+            and change.previous.status is FindingStatus.CONFIRMED
+            and change.current.status is FindingStatus.CONFIRMED
+        )
+
+
+@dataclass(frozen=True)
+class RunDiff:
+    """A full comparison of two runs: metric deltas plus the finding-level diff."""
+
+    metrics: BaselineComparison
+    findings: FindingDiff
+
+    @property
+    def regressed(self) -> bool:
+        """True when the later run is worse than the earlier one.
+
+        A regression is any worsened metric (the baseline rule), a newly
+        confirmed finding, *or* an in-place severity escalation of a finding
+        confirmed in both runs. The finding checks catch what the metric counts
+        miss: a confirmed leak that is new -- by a fresh id, or by an in-place
+        unverified -> confirmed upgrade -- can leave ``confirmed_findings``
+        unchanged when another confirmed leak resolves in the same run; and a
+        known leak growing more severe (low -> critical) is a worse posture the
+        counts do not see at all.
+        """
+        return (
+            self.metrics.regressed
+            or bool(self.findings.newly_confirmed)
+            or bool(self.findings.severity_escalations)
+        )
+
+
+def diff_findings(earlier: Sequence[Finding], later: Sequence[Finding]) -> FindingDiff:
+    """Diff two finding sequences by ``finding_id`` into the diff buckets.
+
+    ``appeared``/``resolved``/``persisting`` partition by ``finding_id``;
+    ``newly_confirmed`` is every finding confirmed in ``later`` whose id was not
+    already confirmed in ``earlier`` (a fresh id, or an in-place upgrade);
+    ``changed`` is every persisting finding whose status or severity differs
+    between the runs. Each side is de-duplicated by ``finding_id`` (first
+    occurrence wins) so a repeated id never lists a finding twice. Runs are
+    de-duplicated upstream; this only guards a hand-built input.
+    """
+    earlier_ids = {finding.finding_id for finding in earlier}
+    later_ids = {finding.finding_id for finding in later}
+    earlier_confirmed_ids = {
+        finding.finding_id for finding in earlier if finding.status is FindingStatus.CONFIRMED
+    }
+    earlier_by_id: dict[str, Finding] = {}
+    for finding in earlier:
+        earlier_by_id.setdefault(finding.finding_id, finding)
+
+    def _select(findings: Sequence[Finding], keep: Callable[[str], bool]) -> tuple[Finding, ...]:
+        seen: set[str] = set()
+        chosen: list[Finding] = []
+        for finding in findings:
+            if finding.finding_id in seen or not keep(finding.finding_id):
+                continue
+            seen.add(finding.finding_id)
+            chosen.append(finding)
+        return tuple(chosen)
+
+    newly_confirmed = _select(
+        [finding for finding in later if finding.status is FindingStatus.CONFIRMED],
+        lambda fid: fid not in earlier_confirmed_ids,
+    )
+    changed: list[FindingChange] = []
+    changed_seen: set[str] = set()
+    for finding in later:
+        fid = finding.finding_id
+        if fid in changed_seen or fid not in earlier_by_id:
+            continue
+        changed_seen.add(fid)
+        previous = earlier_by_id[fid]
+        if previous.status is not finding.status or previous.severity is not finding.severity:
+            changed.append(FindingChange(previous=previous, current=finding))
+    return FindingDiff(
+        appeared=_select(later, lambda fid: fid not in earlier_ids),
+        resolved=_select(earlier, lambda fid: fid not in later_ids),
+        persisting=_select(later, lambda fid: fid in earlier_ids),
+        newly_confirmed=newly_confirmed,
+        changed=tuple(changed),
+    )
+
+
+def diff_runs(earlier: RunResult, later: RunResult) -> RunDiff:
+    """Compare two runs: metric deltas (:func:`compare_metrics`) and a finding diff.
+
+    ``earlier`` is the reference (an older run or a pre-change baseline) and
+    ``later`` is the run under scrutiny, matching the argument order of
+    :func:`compare_metrics`.
+    """
+    return RunDiff(
+        metrics=compare_metrics(earlier.metrics, later.metrics),
+        findings=diff_findings(earlier.findings, later.findings),
+    )

sectum_ai-0.1.1/src/sectum_ai/cli/__init__.py

@@ -0,0 +1 @@
+"""Sectum AI command-line interface."""