agentic-transfer-verifier 0.2.1__py3-none-any.whl

agentic_transfer_verifier/__init__.py

@@ -0,0 +1,85 @@
+"""Agentic transfer verification primitives."""
+
+from agentic_transfer_verifier.adversarial import (
+    AttackChainCase,
+    AttackStep,
+    ChainAssessment,
+    DetectionSignal,
+    assess_attack_chain,
+    attack_chain_corpus,
+    detection_signal_catalog,
+)
+from agentic_transfer_verifier.asset_leakage import (
+    ProtectedAsset,
+    SinkAssessment,
+    SinkAttempt,
+    assess_sink_attempt,
+    leakage_scenario_corpus,
+    trading_signal_canary,
+)
+from agentic_transfer_verifier.models import (
+    CapabilityGrant,
+    Finding,
+    IdentityClaim,
+    ProvenanceStep,
+    TransferEdge,
+    TransferEnvelope,
+    TransferRisk,
+    TransferRiskProfile,
+    VerificationReport,
+)
+from agentic_transfer_verifier.portfolio_adapter import (
+    AdapterAuditV1,
+    AdapterFieldMappingV1,
+    CanonicalObservationV1,
+    SafeEvidencePointerV1,
+    TransferAdapterContext,
+    TransferEnvelopeContractError,
+    TransferProjectionResult,
+    load_transfer_envelope,
+    project_transfer_envelope,
+)
+from agentic_transfer_verifier.risk_model import assess_transfer_profile
+from agentic_transfer_verifier.scenarios import ScenarioCase, scenario_corpus
+from agentic_transfer_verifier.verifier import assess_transfer_risk, verify_envelope
+
+__all__ = [
+    "AttackChainCase",
+    "AttackStep",
+    "AdapterAuditV1",
+    "AdapterFieldMappingV1",
+    "CapabilityGrant",
+    "ChainAssessment",
+    "CanonicalObservationV1",
+    "DetectionSignal",
+    "Finding",
+    "IdentityClaim",
+    "ProvenanceStep",
+    "ProtectedAsset",
+    "ScenarioCase",
+    "SafeEvidencePointerV1",
+    "SinkAssessment",
+    "SinkAttempt",
+    "TransferEnvelope",
+    "TransferAdapterContext",
+    "TransferEnvelopeContractError",
+    "TransferEdge",
+    "TransferRisk",
+    "TransferRiskProfile",
+    "TransferProjectionResult",
+    "VerificationReport",
+    "assess_attack_chain",
+    "assess_sink_attempt",
+    "assess_transfer_profile",
+    "assess_transfer_risk",
+    "attack_chain_corpus",
+    "detection_signal_catalog",
+    "leakage_scenario_corpus",
+    "load_transfer_envelope",
+    "project_transfer_envelope",
+    "scenario_corpus",
+    "trading_signal_canary",
+    "verify_envelope",
+]
+
+__version__ = "0.2.1"

agentic_transfer_verifier/adversarial.py

@@ -0,0 +1,585 @@
+"""Adversarial transfer-chain model.
+
+This module models defensive, synthetic attack chains. It contains no payload
+recipes, no provider calls, and no live target behavior.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+from agentic_transfer_verifier.models import CapabilityGrant, Finding, RiskLevel, TransferEnvelope
+from agentic_transfer_verifier.risk_model import assess_transfer_profile
+from agentic_transfer_verifier.scenarios import _base_user_brief
+
+AdversaryRole = Literal[
+    "external_content_author",
+    "compromised_tool_or_server",
+    "memory_writer",
+    "delegated_agent",
+    "skill_or_package_publisher",
+    "internal_user_or_operator",
+    "stale_state_replayer",
+    "confused_client",
+]
+
+AttackPhase = Literal[
+    "ingress",
+    "role_confusion",
+    "trust_promotion",
+    "authority_or_capability_gain",
+    "action_or_persistence",
+    "evidence_degradation",
+]
+
+EvidenceArtifact = Literal[
+    "envelope",
+    "parent_child_edge",
+    "risk_profile",
+    "violation_code",
+    "provenance_chain",
+    "approval_binding",
+    "capability_grant",
+    "scenario_trace",
+]
+
+
+@dataclass(frozen=True)
+class DetectionSignal:
+    """A defensive signal that ties an attack phase to inspectable evidence."""
+
+    code: str
+    phase: AttackPhase
+    severity: Literal["low", "medium", "high"]
+    artifacts: tuple[EvidenceArtifact, ...]
+    description: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AttackStep:
+    """One abstract step in a synthetic adversarial transfer chain."""
+
+    phase: AttackPhase
+    tactic: str
+    expected_signals: tuple[str, ...]
+    evidence: tuple[EvidenceArtifact, ...]
+    defensive_question: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AttackChainCase:
+    """Synthetic chain for studying how transfer failures propagate."""
+
+    name: str
+    adversary: AdversaryRole
+    objective: str
+    steps: tuple[AttackStep, ...]
+    envelopes: tuple[TransferEnvelope, ...]
+    parent_map: tuple[int | None, ...]
+    expected_signals: tuple[str, ...]
+    public_safe_summary: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "adversary": self.adversary,
+            "objective": self.objective,
+            "steps": [step.to_dict() for step in self.steps],
+            "envelopes": [envelope.to_dict() for envelope in self.envelopes],
+            "parent_map": list(self.parent_map),
+            "expected_signals": list(self.expected_signals),
+            "public_safe_summary": self.public_safe_summary,
+        }
+
+
+@dataclass(frozen=True)
+class ChainAssessment:
+    """Assessment of a complete synthetic adversarial chain."""
+
+    chain_name: str
+    score: float
+    level: RiskLevel
+    observed_signals: tuple[str, ...]
+    missing_expected_signals: tuple[str, ...]
+    covered_phases: tuple[AttackPhase, ...]
+    profile_levels: tuple[RiskLevel, ...]
+    findings: tuple[Finding, ...] = field(default_factory=tuple)
+    model_version: str = "0.2-chain"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model_version": self.model_version,
+            "chain_name": self.chain_name,
+            "score": round(self.score, 3),
+            "level": self.level,
+            "observed_signals": list(self.observed_signals),
+            "missing_expected_signals": list(self.missing_expected_signals),
+            "covered_phases": list(self.covered_phases),
+            "profile_levels": list(self.profile_levels),
+            "findings": [finding.to_dict() for finding in self.findings],
+        }
+
+
+def detection_signal_catalog() -> dict[str, DetectionSignal]:
+    """Return the defensive signal vocabulary used by chain cases."""
+
+    signals = [
+        DetectionSignal(
+            code="data_consumed_as_instruction",
+            phase="role_confusion",
+            severity="high",
+            artifacts=("envelope", "risk_profile", "violation_code"),
+            description="Data-like content is consumed as instruction, policy, or capability.",
+        ),
+        DetectionSignal(
+            code="unauthorized_trust_promotion",
+            phase="trust_promotion",
+            severity="high",
+            artifacts=("parent_child_edge", "risk_profile", "provenance_chain"),
+            description="Trust increases without verifier provenance and verified identity.",
+        ),
+        DetectionSignal(
+            code="verified_without_identity",
+            phase="trust_promotion",
+            severity="high",
+            artifacts=("envelope", "provenance_chain", "violation_code"),
+            description="Verified/signed/attested trust is declared without identity evidence.",
+        ),
+        DetectionSignal(
+            code="authority_escalation",
+            phase="authority_or_capability_gain",
+            severity="high",
+            artifacts=("parent_child_edge", "risk_profile", "violation_code"),
+            description="Authority increases across a transfer boundary.",
+        ),
+        DetectionSignal(
+            code="weak_trust_authority",
+            phase="authority_or_capability_gain",
+            severity="high",
+            artifacts=("envelope", "risk_profile", "violation_code"),
+            description="Weakly trusted content carries write or stronger authority.",
+        ),
+        DetectionSignal(
+            code="capability_exceeds_authority",
+            phase="authority_or_capability_gain",
+            severity="high",
+            artifacts=("capability_grant", "risk_profile", "violation_code"),
+            description="A capability grant exceeds the envelope authority.",
+        ),
+        DetectionSignal(
+            code="unbound_capability",
+            phase="authority_or_capability_gain",
+            severity="high",
+            artifacts=("capability_grant", "approval_binding", "violation_code"),
+            description="Capability is not bound to an action, envelope, or approval.",
+        ),
+        DetectionSignal(
+            code="approval_laundering",
+            phase="authority_or_capability_gain",
+            severity="high",
+            artifacts=("approval_binding", "risk_profile", "violation_code"),
+            description="An approval is reused for a different declared action.",
+        ),
+        DetectionSignal(
+            code="self_replay",
+            phase="action_or_persistence",
+            severity="high",
+            artifacts=("envelope", "parent_child_edge", "violation_code"),
+            description="An envelope declares itself as parent, indicating replay ambiguity.",
+        ),
+        DetectionSignal(
+            code="parent_mismatch",
+            phase="action_or_persistence",
+            severity="high",
+            artifacts=("parent_child_edge", "risk_profile", "violation_code"),
+            description="Declared parent does not match the supplied parent context.",
+        ),
+        DetectionSignal(
+            code="profile_missing_provenance",
+            phase="evidence_degradation",
+            severity="high",
+            artifacts=("provenance_chain", "risk_profile", "violation_code"),
+            description="The transfer cannot show the actor/action/source chain.",
+        ),
+        DetectionSignal(
+            code="agent_card_without_identity",
+            phase="ingress",
+            severity="medium",
+            artifacts=("envelope", "provenance_chain", "violation_code"),
+            description="Agent discovery metadata is consumed without verifiable identity.",
+        ),
+    ]
+    return {signal.code: signal for signal in signals}
+
+
+def assess_attack_chain(chain: AttackChainCase) -> ChainAssessment:
+    """Assess a synthetic adversarial chain using v0.2 envelope profiles."""
+
+    if len(chain.envelopes) != len(chain.parent_map):
+        raise ValueError("parent_map must align with envelopes")
+
+    findings: list[Finding] = []
+    profile_scores: list[float] = []
+    profile_levels: list[RiskLevel] = []
+
+    for index, envelope in enumerate(chain.envelopes):
+        parent_index = chain.parent_map[index]
+        if index == 0 and parent_index is None:
+            continue
+        parent = None if parent_index is None else chain.envelopes[parent_index]
+        profile = assess_transfer_profile(envelope, parent=parent)
+        profile_scores.append(profile.score)
+        profile_levels.append(profile.level)
+        findings.extend(profile.violations)
+
+    observed = tuple(sorted({finding.code for finding in findings}))
+    missing = tuple(signal for signal in chain.expected_signals if signal not in observed)
+    covered = tuple(dict.fromkeys(step.phase for step in chain.steps))
+    expected_coverage = 1.0 - (len(missing) / len(chain.expected_signals))
+    phase_factor = min(1.0, len(covered) / 6)
+    profile_factor = max(profile_scores) if profile_scores else 0.0
+    score = min(1.0, 0.50 * expected_coverage + 0.25 * phase_factor + 0.25 * profile_factor)
+
+    return ChainAssessment(
+        chain_name=chain.name,
+        score=score,
+        level=_risk_level(score),
+        observed_signals=observed,
+        missing_expected_signals=missing,
+        covered_phases=covered,
+        profile_levels=tuple(profile_levels),
+        findings=tuple(findings),
+    )
+
+
+def attack_chain_corpus() -> list[AttackChainCase]:
+    """Return defensive synthetic adversarial chain cases."""
+
+    base = _base_user_brief()
+    return [
+        _repo_text_to_tool_write(base),
+        _tool_metadata_to_capability(base),
+        _memory_replay_to_policy(base),
+        _approval_reuse_to_action(base),
+        _delegated_agent_identity_drift(base),
+        _audit_gap_after_summary(base),
+    ]
+
+
+def _repo_text_to_tool_write(base: TransferEnvelope) -> AttackChainCase:
+    summary = TransferEnvelope(
+        envelope_id="chain-repo-summary",
+        producer="agent-a",
+        consumer="agent-b",
+        payload_kind="summary",
+        trust_level="user_confirmed",
+        authority_scope="read",
+        payload={"summary": "Repository text includes a request-like sentence."},
+        provenance=[],
+        consumed_as="instruction",
+        allowed_uses=["read"],
+        parent_envelope_id=base.envelope_id,
+    )
+    tool_action = TransferEnvelope(
+        envelope_id="chain-tool-write",
+        producer="agent-b",
+        consumer="tool-filesystem",
+        payload_kind="tool_output",
+        trust_level="tool_observed",
+        authority_scope="write",
+        payload={"action": "write requested by interpreted repository text"},
+        provenance=[],
+        consumed_as="instruction",
+        allowed_uses=["read"],
+        parent_envelope_id=summary.envelope_id,
+    )
+    return AttackChainCase(
+        name="repo_text_to_tool_write",
+        adversary="external_content_author",
+        objective="Turn repository-controlled text into a write-capable tool action.",
+        steps=(
+            _step("ingress", "Untrusted repository text enters the context.", ()),
+            _step("role_confusion", "Repository data is consumed as instruction."),
+            _step(
+                "authority_or_capability_gain",
+                "The interpreted instruction reaches write authority.",
+            ),
+            _step("evidence_degradation", "The summary loses provenance before action."),
+        ),
+        envelopes=(base, summary, tool_action),
+        parent_map=(None, 0, 1),
+        expected_signals=(
+            "profile_missing_provenance",
+            "data_consumed_as_instruction",
+            "authority_escalation",
+            "weak_trust_authority",
+        ),
+        public_safe_summary="Synthetic repository text is reinterpreted as tool authority.",
+    )
+
+
+def _tool_metadata_to_capability(base: TransferEnvelope) -> AttackChainCase:
+    tool_card = TransferEnvelope(
+        envelope_id="chain-tool-card",
+        producer="remote-tool-server",
+        consumer="local-agent",
+        payload_kind="agent_card",
+        trust_level="tool_observed",
+        authority_scope="read",
+        payload={"capabilities": ["write_files"]},
+        provenance=[],
+        consumed_as="capability_grant",
+        parent_envelope_id=base.envelope_id,
+    )
+    grant = TransferEnvelope(
+        envelope_id="chain-capability-grant",
+        producer="local-agent",
+        consumer="tool-router",
+        payload_kind="action_request",
+        trust_level="tool_observed",
+        authority_scope="read",
+        payload={"requested_capability": "write_files"},
+        provenance=[],
+        consumed_as="capability_grant",
+        capabilities=[
+            CapabilityGrant(
+                name="write_files",
+                scope="write",
+                source="agent_card",
+                bound_to="",
+            )
+        ],
+        parent_envelope_id=tool_card.envelope_id,
+    )
+    return AttackChainCase(
+        name="tool_metadata_to_capability",
+        adversary="compromised_tool_or_server",
+        objective="Convert tool discovery metadata into an unbound write capability.",
+        steps=(
+            _step("ingress", "Tool or agent metadata enters discovery."),
+            _step("role_confusion", "Metadata is consumed as capability grant."),
+            _step("authority_or_capability_gain", "Capability exceeds declared authority."),
+            _step("evidence_degradation", "No identity or provenance binds the metadata."),
+        ),
+        envelopes=(base, tool_card, grant),
+        parent_map=(None, 0, 1),
+        expected_signals=(
+            "agent_card_without_identity",
+            "profile_missing_provenance",
+            "data_consumed_as_instruction",
+            "capability_exceeds_authority",
+            "unbound_capability",
+        ),
+        public_safe_summary="Synthetic discovery metadata becomes an unbound capability grant.",
+    )
+
+
+def _memory_replay_to_policy(base: TransferEnvelope) -> AttackChainCase:
+    memory = TransferEnvelope(
+        envelope_id="chain-memory-policy",
+        producer="agent-memory",
+        consumer="agent-b",
+        payload_kind="memory",
+        trust_level="user_confirmed",
+        authority_scope="write",
+        payload={"memory": "Old decision is treated as current policy."},
+        provenance=[],
+        consumed_as="policy",
+        parent_envelope_id="chain-memory-policy",
+    )
+    return AttackChainCase(
+        name="memory_replay_to_policy",
+        adversary="stale_state_replayer",
+        objective="Replay old memory as current policy with write authority.",
+        steps=(
+            _step("ingress", "Memory enters a later run."),
+            _step("role_confusion", "Memory is consumed as policy."),
+            _step("action_or_persistence", "The stale record persists by self-parenting."),
+            _step("authority_or_capability_gain", "The memory carries write authority."),
+        ),
+        envelopes=(base, memory),
+        parent_map=(None, None),
+        expected_signals=(
+            "profile_missing_provenance",
+            "data_consumed_as_instruction",
+            "self_replay",
+            "authority_escalation",
+        ),
+        public_safe_summary="Synthetic stale memory is replayed as current write policy.",
+    )
+
+
+def _approval_reuse_to_action(base: TransferEnvelope) -> AttackChainCase:
+    action = TransferEnvelope(
+        envelope_id="chain-approval-reuse",
+        producer="agent-a",
+        consumer="agent-b",
+        payload_kind="action_request",
+        trust_level="user_confirmed",
+        authority_scope="write",
+        payload={"approved_action": "write-prod-like-config"},
+        provenance=[],
+        consumed_as="instruction",
+        allowed_uses=["execute"],
+        approval_id="approval-docs-review",
+        approval_binding="update-docs",
+        parent_envelope_id=base.envelope_id,
+    )
+    return AttackChainCase(
+        name="approval_reuse_to_action",
+        adversary="internal_user_or_operator",
+        objective="Reuse a narrow approval as broader write authority.",
+        steps=(
+            _step("ingress", "A prior approval enters the transfer."),
+            _step("trust_promotion", "User-confirmed status is treated as broader permission."),
+            _step(
+                "authority_or_capability_gain",
+                "Approval binding is laundered into another action.",
+            ),
+            _step("evidence_degradation", "The provenance chain does not explain the mismatch."),
+        ),
+        envelopes=(base, action),
+        parent_map=(None, 0),
+        expected_signals=(
+            "profile_missing_provenance",
+            "authority_escalation",
+            "approval_laundering",
+        ),
+        public_safe_summary="Synthetic approval is reused for a different action.",
+    )
+
+
+def _delegated_agent_identity_drift(base: TransferEnvelope) -> AttackChainCase:
+    delegated = TransferEnvelope(
+        envelope_id="chain-delegated-agent",
+        producer="remote-agent",
+        consumer="local-agent",
+        payload_kind="summary",
+        trust_level="verified",
+        authority_scope="execute",
+        payload={"summary": "Delegated agent claims the task is verified."},
+        provenance=[],
+        consumed_as="instruction",
+        allowed_uses=["read"],
+        parent_envelope_id=base.envelope_id,
+    )
+    return AttackChainCase(
+        name="delegated_agent_identity_drift",
+        adversary="delegated_agent",
+        objective="Promote a delegated agent summary into verified executable instruction.",
+        steps=(
+            _step("ingress", "A delegated agent handoff enters the receiver."),
+            _step("role_confusion", "Summary is consumed as instruction."),
+            _step("trust_promotion", "The child transfer claims verified trust."),
+            _step("authority_or_capability_gain", "Execute authority appears at the receiver."),
+        ),
+        envelopes=(base, delegated),
+        parent_map=(None, 0),
+        expected_signals=(
+            "verified_without_identity",
+            "unauthorized_trust_promotion",
+            "authority_escalation",
+        ),
+        public_safe_summary=(
+            "Synthetic delegated-agent summary claims verified executable authority."
+        ),
+    )
+
+
+def _audit_gap_after_summary(base: TransferEnvelope) -> AttackChainCase:
+    summary = TransferEnvelope(
+        envelope_id="chain-shadow-summary",
+        producer="agent-a",
+        consumer="agent-b",
+        payload_kind="summary",
+        trust_level="untrusted",
+        authority_scope="none",
+        payload={"summary": "A short handoff with no source path."},
+        provenance=[],
+        consumed_as="evidence",
+        parent_envelope_id="unexpected-parent",
+    )
+    return AttackChainCase(
+        name="audit_gap_after_summary",
+        adversary="confused_client",
+        objective="Create a handoff whose source chain cannot be reconstructed.",
+        steps=(
+            _step("ingress", "A summary crosses runtime boundary."),
+            _step(
+                "evidence_degradation",
+                "Source, actor, and parent relation are missing or wrong.",
+            ),
+            _step("action_or_persistence", "Receiver cannot replay the decision path."),
+        ),
+        envelopes=(base, summary),
+        parent_map=(None, 0),
+        expected_signals=("profile_missing_provenance", "parent_mismatch"),
+        public_safe_summary="Synthetic summary loses enough provenance to block review.",
+    )
+
+
+def _step(
+    phase: AttackPhase,
+    tactic: str,
+    expected_signals: tuple[str, ...] | None = None,
+) -> AttackStep:
+    catalog = detection_signal_catalog()
+    signals = expected_signals or tuple(
+        code for code, signal in catalog.items() if signal.phase == phase
+    )
+    fallback = _fallback_signal()
+    artifacts = tuple(
+        dict.fromkeys(
+            artifact
+            for code in signals
+            for artifact in catalog.get(code, fallback).artifacts
+        )
+    )
+    return AttackStep(
+        phase=phase,
+        tactic=tactic,
+        expected_signals=signals,
+        evidence=artifacts,
+        defensive_question=_defensive_question(phase),
+    )
+
+
+def _fallback_signal() -> DetectionSignal:
+    return DetectionSignal(
+        code="fallback",
+        phase="evidence_degradation",
+        severity="low",
+        artifacts=("scenario_trace",),
+        description="Fallback evidence marker.",
+    )
+
+
+def _defensive_question(phase: AttackPhase) -> str:
+    questions = {
+        "ingress": "What untrusted or weakly trusted material entered the system?",
+        "role_confusion": "Did the receiver consume data as instruction, policy, or capability?",
+        "trust_promotion": "Did trust increase without verifier and identity evidence?",
+        "authority_or_capability_gain": (
+            "Did authority or capability expand beyond the parent task?"
+        ),
+        "action_or_persistence": "Did the transfer enable action, replay, or persistence?",
+        "evidence_degradation": "Can a reviewer reconstruct the actor/action/source chain?",
+    }
+    return questions[phase]
+
+
+def _risk_level(score: float) -> RiskLevel:
+    if score >= 0.75:
+        return "high"
+    if score >= 0.45:
+        return "medium"
+    if score > 0:
+        return "low"
+    return "none"