qids 1.3.0__py3-none-any.whl

qids/__init__.py

@@ -0,0 +1,38 @@
+"""QIDS -- Quantum-Inspired Detection for Signatures.
+
+A threat-detection framework for teleportation-based Quantum Digital
+Signature protocols.  Simulates Bell-state entanglement distribution and
+quantum teleportation exactly, applies Pauli corrections and projective
+measurements for verification, and detects forgery, impersonation, replay,
+unauthorised verification and channel manipulation through statistical
+threshold rules alone -- no machine learning anywhere in the decision path.
+"""
+
+__version__ = "1.3.0"
+
+import logging as _logging
+
+# Library convention: attach a NullHandler so importing qids never configures
+# logging for the host application.  Operators opt in with
+# ``logging.getLogger("qids").setLevel(logging.INFO)``.
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())
+
+from .errors import (  # noqa: F401
+    AuthenticationError,
+    ConfigurationError,
+    InsecureConfiguration,
+    KeyExhaustedError,
+    KeyMaterialError,
+    ProtocolError,
+    QidsError,
+    UnknownScenario,
+)
+from .protocol.params import ProtocolParams  # noqa: F401
+from .session import QdsSession, SessionResult  # noqa: F401
+
+__all__ = [
+    "ProtocolParams", "QdsSession", "SessionResult", "__version__",
+    "QidsError", "ConfigurationError", "InsecureConfiguration",
+    "ProtocolError", "KeyExhaustedError", "KeyMaterialError",
+    "AuthenticationError", "UnknownScenario",
+]

qids/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

qids/analysis/__init__.py

@@ -0,0 +1,50 @@
+"""Security analysis, metrics and benchmarking."""
+
+from .evasion import (  # noqa: F401
+    EvasionPoint,
+    Frontier,
+    acceptance_curve,
+    evaluate_strength,
+    find_frontier,
+    is_monotone,
+    threshold_only_frontier,
+)
+from .metrics import EvaluationReport, ScenarioStats, evaluate  # noqa: F401
+from .sizing import (  # noqa: F401
+    LinkSizingParameters,
+    LinkSizingResult,
+    calculate_optical_link_budget,
+    format_sizing_report,
+)
+from .sweeps import (  # noqa: F401
+    detection_power_curve,
+    forgery_probability_curve,
+    leakage_tolerance,
+    repudiation_probability_curve,
+    validate_forger_model,
+)
+
+#: Public surface of this subpackage.  Declared explicitly because a
+#: re-export is only 'used' from the outside, and ``# noqa`` does not
+#: reach pyflakes -- ``__all__`` does.
+__all__ = [
+    "EvaluationReport",
+    "EvasionPoint",
+    "Frontier",
+    "LinkSizingParameters",
+    "LinkSizingResult",
+    "ScenarioStats",
+    "acceptance_curve",
+    "calculate_optical_link_budget",
+    "detection_power_curve",
+    "evaluate",
+    "evaluate_strength",
+    "find_frontier",
+    "format_sizing_report",
+    "forgery_probability_curve",
+    "is_monotone",
+    "leakage_tolerance",
+    "repudiation_probability_curve",
+    "threshold_only_frontier",
+    "validate_forger_model",
+]

qids/analysis/evasion.py

@@ -0,0 +1,233 @@
+"""The strongest attack that survives: mapping the evasion frontier.
+
+Every scenario in the catalogue runs an attack at a *fixed* strength and asks
+whether it is caught.  That answers "does this attack work against the
+detector", which is the easy question.  The hard one is the adversary's:
+
+    given that this detector exists, and knowing its thresholds, what is the
+    most I can do and still be accepted?
+
+An attacker who reads the source picks their strength deliberately.  If the
+only defence were the protocol's own threshold rule, they would tune the
+attack to sit just under s_a and walk through.  So the number that actually
+characterises the framework is the *largest attack strength that still gets
+ACCEPT*, and how much that concession costs the attacker.
+
+Two frontiers are reported per family:
+
+``p50``  the strength at which acceptance falls to 50%
+``p05``  the strength at which acceptance falls to 5% -- the practical ceiling
+
+Bisection rather than a grid, because the transition is sharp and a grid
+either misses it or wastes runs far from it.  Acceptance is monotone in
+strength for every family here (more disturbance is never easier to hide),
+which is what makes bisection valid; the sweep in ``acceptance_curve`` is
+kept so that assumption stays checkable rather than assumed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from ..detect.engine import Decision
+from ..protocol.verify import Level
+from ..session import QdsSession
+
+
+@dataclass
+class EvasionPoint:
+    """Outcome of testing one attack strength."""
+
+    strength: float
+    trials: int
+    accepted: int
+    mean_mismatch: float
+    fired: dict = field(default_factory=dict)
+
+    @property
+    def acceptance(self) -> float:
+        return self.accepted / self.trials if self.trials else 0.0
+
+    def summary(self) -> dict:
+        return {
+            "strength": self.strength,
+            "acceptance": self.acceptance,
+            "mean_mismatch": self.mean_mismatch,
+            "fired": self.fired,
+        }
+
+
+@dataclass
+class Frontier:
+    """Where a family of attacks stops getting through."""
+
+    family: str
+    p50: float
+    p05: float
+    detail: list = field(default_factory=list)
+    threshold_s_a: float = 0.0
+    mismatch_at_p50: float = 0.0
+    mismatch_at_p05: float = 0.0
+    first_monitor: str = ""
+
+    def summary(self) -> dict:
+        return {
+            "family": self.family,
+            "strength_at_50pct_acceptance": self.p50,
+            "strength_at_5pct_acceptance": self.p05,
+            "mismatch_at_p50": self.mismatch_at_p50,
+            "mismatch_at_p05": self.mismatch_at_p05,
+            "s_a": self.threshold_s_a,
+            "first_monitor_to_fire": self.first_monitor,
+            "points": [p.summary() for p in self.detail],
+        }
+
+
+def evaluate_strength(
+    params,
+    adversary_factory,
+    strength: float,
+    trials: int = 10,
+    seed: int = 0,
+    holder: str = "bob",
+) -> EvasionPoint:
+    """Run the full pipeline ``trials`` times at one attack strength."""
+    accepted, mismatches = 0, []
+    fired: dict = {}
+    for t in range(trials):
+        rng = np.random.default_rng(seed * 7717 + int(strength * 1e6) * 31 + t)
+        sess = QdsSession(params, rng)
+        sess.distribute(adversary=adversary_factory(strength))
+        sess.symmetrise()
+        decoys = sess.check_decoys(0)
+        sig = sess.sign(b"EVASION", 0)
+        env = sess.transport(sig, holder)
+        ev, verdict = sess.deliver(sig, holder, Level.AUTHENTICATION,
+                                   envelope=env, decoy_evidence=decoys.get(holder))
+        mismatches.append(ev.mismatch_rate)
+        if verdict.decision == Decision.ACCEPT:
+            accepted += 1
+        for name in verdict.fired_names:
+            fired[name] = fired.get(name, 0) + 1
+    return EvasionPoint(
+        strength=strength, trials=trials, accepted=accepted,
+        mean_mismatch=float(np.mean(mismatches)),
+        fired={k: v / trials for k, v in sorted(fired.items())},
+    )
+
+
+def find_frontier(
+    params,
+    adversary_factory,
+    family: str,
+    lo: float = 0.0,
+    hi: float = 1.0,
+    trials: int = 10,
+    iterations: int = 7,
+    seed: int = 0,
+) -> Frontier:
+    """Bisect for the strengths at which acceptance crosses 50% and 5%."""
+    points: list = []
+
+    def probe(x: float) -> EvasionPoint:
+        for p in points:
+            if abs(p.strength - x) < 1e-9:
+                return p
+        p = evaluate_strength(params, adversary_factory, x, trials, seed)
+        points.append(p)
+        return p
+
+    def bisect(target: float) -> float:
+        a, b = lo, hi
+        if probe(b).acceptance >= target:      # never suppressed in range
+            return b
+        if probe(a).acceptance < target:       # already suppressed at the floor
+            return a
+        for _ in range(iterations):
+            mid = (a + b) / 2
+            if probe(mid).acceptance >= target:
+                a = mid
+            else:
+                b = mid
+        return (a + b) / 2
+
+    p50 = bisect(0.5)
+    p05 = bisect(0.05)
+    points.sort(key=lambda p: p.strength)
+
+    def mismatch_near(x: float) -> float:
+        return min(points, key=lambda p: abs(p.strength - x)).mean_mismatch
+
+    first = first_monitor(points)
+
+    return Frontier(
+        family=family, p50=p50, p05=p05, detail=points,
+        threshold_s_a=params.thresholds[0],
+        mismatch_at_p50=mismatch_near(p50),
+        mismatch_at_p05=mismatch_near(p05),
+        first_monitor=first,
+    )
+
+
+def first_monitor(points, min_rate: float = 0.25) -> str:
+    """Which monitor is the first to engage as attack strength rises?
+
+    ``min_rate`` matters more than it looks.  Taking the lowest strength where
+    *any* monitor fires at all picks up single noise firings -- one trial in
+    twelve, while the attack is still being accepted 92% of the time -- and
+    labels that the "first" monitor, which is misleading.  Requiring a monitor
+    to fire on a real fraction of trials before it counts gives a label that
+    reflects the ladder rather than the tail of the sampling distribution.
+    """
+    for p in sorted(points, key=lambda q: q.strength):
+        meaningful = {k: v for k, v in p.fired.items() if v >= min_rate}
+        if meaningful:
+            return max(meaningful, key=meaningful.get)
+    return ""
+
+
+def acceptance_curve(
+    params,
+    adversary_factory,
+    strengths,
+    trials: int = 8,
+    seed: int = 0,
+) -> list:
+    """Straight sweep, used to check that acceptance really is monotone."""
+    return [evaluate_strength(params, adversary_factory, s, trials, seed)
+            for s in strengths]
+
+
+def is_monotone(points, tolerance: float = 0.25) -> bool:
+    """Is acceptance non-increasing in strength, within sampling noise?
+
+    Bisection assumes it.  With ``trials`` runs per point the estimate has a
+    standard error around 0.5/sqrt(trials), so a small rise is noise rather
+    than a violation; anything larger means the frontier is not well defined
+    and the number should not be quoted.
+    """
+    acc = [p.acceptance for p in sorted(points, key=lambda p: p.strength)]
+    return all(b <= a + tolerance for a, b in zip(acc, acc[1:]))
+
+
+def threshold_only_frontier(params, induced_rate) -> float:
+    """Where the frontier would sit with *only* the protocol's threshold rule.
+
+    ``induced_rate(strength)`` gives the mismatch rate an attack produces.
+    Solving ``induced_rate(x) = s_a`` gives the strength a bare threshold
+    detector would tolerate -- the number the extra monitors have to beat to
+    be worth their cost.
+    """
+    s_a, _ = params.thresholds
+    lo, hi = 0.0, 1.0
+    if induced_rate(hi) <= s_a:
+        return hi
+    for _ in range(60):
+        mid = (lo + hi) / 2
+        if induced_rate(mid) <= s_a:
+            lo = mid
+        else:
+            hi = mid
+    return lo

qids/analysis/metrics.py

@@ -0,0 +1,263 @@
+"""Scoring the detector: detection power, false alarms, attribution accuracy.
+
+Three numbers matter, and they are not interchangeable:
+
+``undetected acceptance`` an attack that was ACCEPTed.  This is the only
+                          outcome that actually breaks the scheme, and the
+                          target for it is zero.
+``detection rate``        an attack that was not ACCEPTed (REJECT or
+                          QUARANTINE).  Quarantine counts, because holding a
+                          signature for arbitration is a safe outcome.
+``false alarm rate``      a benign session that was not ACCEPTed.  This is the
+                          cost of the detector, and it is what stops anyone
+                          from trivially scoring 100% by rejecting everything.
+
+Attribution accuracy is reported separately.  Detecting an attack and naming
+it correctly are different capabilities, and conflating them hides the cases
+where the framework is right for the wrong reason.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from ..detect.engine import Decision
+from ..scenarios import SCENARIOS, run_scenario
+
+#: Threats that are the same physical phenomenon seen at different strengths.
+#: Scored as a family as well as exactly, because "weak attack" and "degraded
+#: link" are genuinely indistinguishable from one session's observables.
+THREAT_FAMILY = {
+    "benign": "benign",
+    "forgery": "fabrication",
+    "impersonation": "fabrication",
+    "replay": "replay",
+    "unauthorized_verification": "access",
+    "channel_manipulation": "channel",
+    "link_degradation": "channel",
+    "repudiation": "repudiation",
+    "evasion": "fabrication",
+}
+
+
+@dataclass
+class ScenarioStats:
+    """Aggregate outcome of repeating one scenario."""
+
+    name: str
+    truth: str
+    n_runs: int = 0
+    n_detected: int = 0
+    n_accepted: int = 0
+    n_exact: int = 0
+    n_family: int = 0
+    mismatch_rates: list = field(default_factory=list)
+    latencies_ms: list = field(default_factory=list)
+    sprt_stops: list = field(default_factory=list)
+    decisions: Counter = field(default_factory=Counter)
+    attributed: Counter = field(default_factory=Counter)
+
+    @property
+    def is_benign(self) -> bool:
+        return self.truth == "benign"
+
+    @property
+    def detection_rate(self) -> float:
+        return self.n_detected / self.n_runs if self.n_runs else 0.0
+
+    @property
+    def false_alarm_rate(self) -> float:
+        return self.detection_rate if self.is_benign else 0.0
+
+    @property
+    def undetected_acceptance_rate(self) -> float:
+        return 0.0 if self.is_benign else self.n_accepted / max(1, self.n_runs)
+
+    @property
+    def exact_attribution(self) -> float:
+        return self.n_exact / self.n_runs if self.n_runs else 0.0
+
+    @property
+    def family_attribution(self) -> float:
+        return self.n_family / self.n_runs if self.n_runs else 0.0
+
+    def row(self) -> dict:
+        return {
+            "scenario": self.name,
+            "truth": self.truth,
+            "runs": self.n_runs,
+            "detection_rate": self.detection_rate,
+            "undetected_acceptance": self.undetected_acceptance_rate,
+            "exact_attribution": self.exact_attribution,
+            "family_attribution": self.family_attribution,
+            "mean_mismatch": float(np.mean(self.mismatch_rates)) if self.mismatch_rates else 0.0,
+            "mean_latency_ms": float(np.mean(self.latencies_ms)) if self.latencies_ms else 0.0,
+            "median_sprt_stop": (
+                float(np.median([s for s in self.sprt_stops if s])) if any(self.sprt_stops) else None
+            ),
+            "decisions": dict(self.decisions),
+            "attributed": dict(self.attributed),
+        }
+
+
+@dataclass
+class EvaluationReport:
+    per_scenario: dict = field(default_factory=dict)
+    confusion: dict = field(default_factory=lambda: defaultdict(Counter))
+    params_summary: dict = field(default_factory=dict)
+    wall_clock_s: float = 0.0
+
+    # -- aggregate figures -------------------------------------------------
+    def _bucket(self, benign: bool):
+        return [s for s in self.per_scenario.values() if s.is_benign == benign]
+
+    @property
+    def attack_scenarios(self) -> list:
+        return self._bucket(False)
+
+    @property
+    def benign_scenarios(self) -> list:
+        return self._bucket(True)
+
+    def _weighted(self, items, attr) -> float:
+        runs = sum(s.n_runs for s in items)
+        if not runs:
+            return 0.0
+        return sum(getattr(s, attr) * s.n_runs for s in items) / runs
+
+    @property
+    def detection_rate(self) -> float:
+        return self._weighted(self.attack_scenarios, "detection_rate")
+
+    @property
+    def false_alarm_rate(self) -> float:
+        return self._weighted(self.benign_scenarios, "detection_rate")
+
+    @property
+    def undetected_acceptance_rate(self) -> float:
+        return self._weighted(self.attack_scenarios, "undetected_acceptance_rate")
+
+    @property
+    def exact_attribution(self) -> float:
+        return self._weighted(self.attack_scenarios, "exact_attribution")
+
+    @property
+    def family_attribution(self) -> float:
+        return self._weighted(self.attack_scenarios, "family_attribution")
+
+    def summary(self) -> dict:
+        return {
+            "scenarios": len(self.per_scenario),
+            "total_runs": sum(s.n_runs for s in self.per_scenario.values()),
+            "detection_rate": self.detection_rate,
+            "false_alarm_rate": self.false_alarm_rate,
+            "undetected_acceptance_rate": self.undetected_acceptance_rate,
+            "exact_attribution": self.exact_attribution,
+            "family_attribution": self.family_attribution,
+            "wall_clock_s": self.wall_clock_s,
+        }
+
+    def confusion_matrix(self) -> dict:
+        return {t: dict(c) for t, c in self.confusion.items()}
+
+    def table(self) -> str:
+        hdr = (
+            f"{'scenario':36s} {'truth':26s} {'runs':>5s} {'detect':>7s} "
+            f"{'undet.acc':>10s} {'attrib':>7s} {'family':>7s} {'ms':>7s}"
+        )
+        lines = [hdr, "-" * len(hdr)]
+        for s in self.per_scenario.values():
+            r = s.row()
+            lines.append(
+                f"{r['scenario']:36s} {r['truth']:26s} {r['runs']:5d} "
+                f"{r['detection_rate']:7.3f} {r['undetected_acceptance']:10.3f} "
+                f"{r['exact_attribution']:7.3f} {r['family_attribution']:7.3f} "
+                f"{r['mean_latency_ms']:7.2f}"
+            )
+        return "\n".join(lines)
+
+
+def _outcome(result):
+    """Extract (decision, attributed_threat) from a scenario result.
+
+    Repudiation is arbitrated across verifiers, so for those scenarios the
+    dispute outcome -- not a single verifier's local verdict -- is the
+    framework's answer.
+    """
+    if result.dispute is not None and result.truth == "repudiation":
+        return result.dispute.decision, result.dispute.threat.value
+    v = result.target_verdict
+    if v is None:
+        return Decision.REJECT, "benign"
+    return v.decision, v.threat.value
+
+
+def _name_offset(name: str) -> int:
+    """Stable per-scenario seed offset.
+
+    This used ``abs(hash(name))``, which is not reproducible: CPython
+    randomises string hashing per process unless ``PYTHONHASHSEED`` is set, so
+    two runs of the same evaluation at the same ``seed`` drew different streams
+    and reported different numbers.  A cryptographic digest is stable across
+    processes, platforms and Python versions, which is what "seed 11" has to
+    mean for a reported figure to be checkable.
+    """
+    digest = hashlib.blake2b(name.encode("utf-8"), digest_size=8).digest()
+    return int.from_bytes(digest, "big") % 99_991
+
+
+def evaluate(
+    params,
+    seed: int = 0,
+    repeats: int = 5,
+    only: tuple = (),
+    progress: bool = False,
+) -> EvaluationReport:
+    """Run every scenario ``repeats`` times and score the detector."""
+    names = only or tuple(SCENARIOS)
+    report = EvaluationReport(params_summary=params.security_summary())
+    t0 = time.perf_counter()
+
+    for name in names:
+        sc = SCENARIOS[name]
+        stats = ScenarioStats(name=name, truth=sc.truth)
+        for r_i in range(repeats):
+            rng = np.random.default_rng(seed * 100_003 + _name_offset(name) + r_i)
+            result = run_scenario(name, params, rng)
+            decision, threat = _outcome(result)
+
+            stats.n_runs += 1
+            stats.decisions[decision] += 1
+            stats.attributed[threat] += 1
+            if decision != Decision.ACCEPT:
+                stats.n_detected += 1
+            else:
+                stats.n_accepted += 1
+            if threat == sc.truth or (sc.truth == "benign" and decision == Decision.ACCEPT):
+                stats.n_exact += 1
+            if THREAT_FAMILY.get(threat) == THREAT_FAMILY.get(sc.truth) or (
+                sc.truth == "benign" and decision == Decision.ACCEPT
+            ):
+                stats.n_family += 1
+
+            v = result.target_verdict
+            if v is not None:
+                stats.mismatch_rates.append(v.mismatch_rate)
+                stats.latencies_ms.append(v.elapsed_s * 1000.0)
+                sprt = next((s for s in v.signals if s.name == "sprt"), None)
+                stats.sprt_stops.append(
+                    (sprt.detail or {}).get("stopped_at") if sprt else None
+                )
+            report.confusion[sc.truth][threat] += 1
+        report.per_scenario[name] = stats
+        if progress:
+            print(f"  {name:36s} detect={stats.detection_rate:.2f} "
+                  f"attrib={stats.exact_attribution:.2f}", flush=True)
+
+    report.wall_clock_s = time.perf_counter() - t0
+    return report