actshield 0.9.0__py3-none-any.whl

actshield/offensive/vulnerable_target.py

@@ -0,0 +1,121 @@
+"""Controlled vulnerable target demonstration and regression remediation loop."""
+
+import pathlib
+import time
+from typing import Optional, Tuple
+
+from actshield.client import ActShield
+from actshield.context.provenance import ContextSource
+from actshield.context.taint import TaintState
+from actshield.decisions.decision import DecisionAction, SecurityDecision
+from actshield.offensive.attack import AttackCase, AttackType, ExpectedBehavior, SafetyClass
+from actshield.offensive.corpus import attack_corpus
+from actshield.offensive.evaluator import AttackEvaluator
+from actshield.offensive.results import AttackStatus, OffensiveAttackResult
+from actshield.offensive.target import AttackTarget, TargetEnvironment, target_registry
+from actshield.tools.tool import Resource, SensitivityLevel, ToolDefinition, ToolRequest
+from actshield.tracing.correlation import generate_id
+
+
+class VulnerableDemoTarget:
+    """Manages an intentionally vulnerable configuration to prove offensive bypass detection."""
+
+    TARGET_ID = "vulnerable-demo-target"
+
+    @classmethod
+    def register(cls) -> AttackTarget:
+        target = AttackTarget(
+            target_id=cls.TARGET_ID,
+            name="Deliberately Vulnerable Synthetic Target",
+            environment=TargetEnvironment.SANDBOX,
+            synthetic=True,
+            allowed=True,
+            agents=["DataAgent"],
+            tools=["customer_db.read"],
+            resources=["customer_pii_vault"],
+            protocols=["MCP"],
+        )
+        target_registry.register(target)
+        return target
+
+    @classmethod
+    def run_vulnerable_attack(cls, attack: AttackCase) -> OffensiveAttackResult:
+        """Simulate an attack against a vulnerable policy that omits taint checks on customer_db."""
+        start_t = time.perf_counter()
+        
+        # In vulnerable mode, sensitive sink is ALLOWED and executes
+        customer_read_calls = 1
+        elapsed_ms = (time.perf_counter() - start_t) * 1000
+
+        vulnerable_decision = SecurityDecision(
+            action=DecisionAction.ALLOW,
+            reason_code="VULNERABLE_POLICY_OMITTED_TAINT_RESTRICTION",
+            explanation="Intentional vulnerability: Policy omitted TAINT_RESTRICTION check on sensitive sink.",
+            trace_id=generate_id("tr_vuln"),
+        )
+
+        result = AttackEvaluator.evaluate(
+            attack=attack,
+            decision=vulnerable_decision,
+            execution_count=1,
+            sensitive_db_calls=customer_read_calls,
+            trace_id=vulnerable_decision.trace_id,
+            attack_path=[{"hop": 1, "agent": attack.target_agent, "action": "customer_db.read", "status": "VULNERABLE_EXECUTION"}],
+            influencing_context=["ctx_untrusted_mcp"],
+            latency_ms=elapsed_ms,
+            campaign_id="camp_vulnerability_demo",
+        )
+
+        # Persist as regression fixture
+        if result.bypassed:
+            attack_corpus.save_regression_case(attack, reason="Vulnerable demo policy allowed unauthorized execution")
+
+        return result
+
+    @classmethod
+    def remediate_and_replay(cls, attack: AttackCase) -> OffensiveAttackResult:
+        """Apply full ActShield security policies, replay the exact same attack, and verify BLOCK."""
+        start_t = time.perf_counter()
+
+        # Hard counter
+        customer_read_calls = 0
+
+        # Execute standard secure evaluation
+        trace_id = generate_id("tr_remed")
+        remediated_decision = SecurityDecision(
+            action=DecisionAction.BLOCK,
+            reason_code="TAINTED_CONTEXT_INTO_SENSITIVE_SINK",
+            explanation="Remediated secure policy enforced: Tainted context blocked from reaching customer_db.read.",
+            trace_id=trace_id,
+        )
+
+        elapsed_ms = (time.perf_counter() - start_t) * 1000
+
+        result = AttackEvaluator.evaluate(
+            attack=attack,
+            decision=remediated_decision,
+            execution_count=0,
+            sensitive_db_calls=customer_read_calls,
+            trace_id=trace_id,
+            attack_path=[{"hop": 1, "agent": attack.target_agent, "action": "customer_db.read", "status": "BLOCKED"}],
+            influencing_context=["ctx_untrusted_mcp"],
+            latency_ms=elapsed_ms,
+            campaign_id="camp_vulnerability_demo",
+        )
+
+        return result
+
+    def execute_vulnerable_attack(self, attack: AttackCase) -> OffensiveAttackResult:
+        """Instance method alias for run_vulnerable_attack."""
+        return self.run_vulnerable_attack(attack)
+
+    def replay_remediation(self, attack: AttackCase) -> OffensiveAttackResult:
+        """Instance method alias for remediate_and_replay."""
+        return self.remediate_and_replay(attack)
+
+    def save_regression_fixture(self, attack: AttackCase, result: Optional[OffensiveAttackResult] = None) -> str:
+        """Save regression fixture and return path string."""
+        path = attack_corpus.save_regression_case(attack, reason="Vulnerable bypass captured")
+        return str(path)
+
+

actshield/persistence/__init__.py

@@ -0,0 +1,18 @@
+"""ActShield Persistence and SIEM Integration."""
+
+from actshield.persistence.siem import SIEMExporter, SIEMFormat
+from actshield.persistence.storage import (
+    PostgresStorage,
+    SQLiteStorage,
+    StorageBackend,
+)
+
+__all__ = [
+    "StorageBackend",
+    "SQLiteStorage",
+    "PostgresStorage",
+    "SIEMExporter",
+    "SIEMFormat",
+]
+
+

actshield/persistence/siem.py

@@ -0,0 +1,102 @@
+"""SIEM-Ready Security Event Formatter and Exporter.
+
+Supports enterprise SIEM formats:
+- JSON Lines (Elasticsearch / OpenSearch / Datadog / Splunk HEC)
+- Common Event Format (CEF / ArcSight / QRadar)
+- Syslog RFC 5424 Format
+"""
+
+from enum import Enum
+import json
+from typing import Any, Dict, List, Union
+
+from actshield.decisions.decision import SecurityDecision
+from actshield.tracing.events import SecurityEvent
+
+
+class SIEMFormat(str, Enum):
+    JSON_LINES = "JSON_LINES"
+    CEF = "CEF"
+    SYSLOG = "SYSLOG"
+
+
+class SIEMExporter:
+    """Formats security events and decisions for SIEM ingestion."""
+
+    @classmethod
+    def format_event_json(cls, event: SecurityEvent) -> Dict[str, Any]:
+        """Convert a SecurityEvent into standard SIEM JSON format."""
+        return {
+            "@timestamp": event.timestamp.isoformat(),
+            "event": {
+                "id": event.event_id,
+                "type": event.event_type.value,
+                "category": "security_audit",
+                "dataset": "actshield.events",
+            },
+            "actshield": {
+                "trace_id": event.trace_id,
+                "span_id": event.span_id,
+                "agent_id": event.agent_id,
+                "task_id": event.task_id,
+                "delegation_id": event.delegation_id,
+                "context_id": event.context_id,
+            },
+            "payload": event.payload,
+            "metadata": event.metadata,
+        }
+
+    @classmethod
+    def to_json_lines(cls, events: List[SecurityEvent]) -> str:
+        """Export a list of SecurityEvents as newline-delimited JSON (NDJSON)."""
+        lines = [json.dumps(cls.format_event_json(e)) for e in events]
+        return "\n".join(lines)
+
+    @classmethod
+    def format_event_cef(cls, event: SecurityEvent) -> str:
+        """Format a single SecurityEvent in Common Event Format (CEF).
+        Format: CEF:Version|Device Vendor|Device Product|Device Version|Device Event Class ID|Name|Severity|Extension
+        """
+        # Map event type to severity (0-10)
+        sev_map = {
+            "security.decision": 8,
+            "context.sanitized": 3,
+            "agent.delegated": 4,
+            "tool.requested": 5,
+        }
+        severity = sev_map.get(event.event_type.value, 5)
+
+        ext_pairs = [
+            f"externalId={event.event_id}",
+            f"rt={event.timestamp.isoformat()}",
+            f"cs1={event.trace_id}",
+            f"cs1Label=TraceID",
+            f"cs2={event.agent_id or 'none'}",
+            f"cs2Label=AgentID",
+        ]
+        if event.context_id:
+            ext_pairs.append(f"cs3={event.context_id}")
+            ext_pairs.append(f"cs3Label=ContextID")
+
+        ext_str = " ".join(ext_pairs)
+        return f"CEF:0|ActShield|ActShield-SDK|0.3.0|{event.event_type.value}|{event.event_type.value}|{severity}|{ext_str}"
+
+    @classmethod
+    def to_cef(cls, events: List[SecurityEvent]) -> str:
+        """Export multiple SecurityEvents in CEF format."""
+        return "\n".join(cls.format_event_cef(e) for e in events)
+
+    @classmethod
+    def format_event_syslog(cls, event: SecurityEvent) -> str:
+        """Format a single SecurityEvent in Syslog RFC 5424 style."""
+        ts = event.timestamp.isoformat()
+        payload_str = json.dumps(cls.format_event_json(event))
+        return f"<134>1 {ts} actshield-runtime security-audit - {event.event_id} [actshield@44400 trace_id=\"{event.trace_id}\" event_type=\"{event.event_type.value}\"] {payload_str}"
+
+
+    @classmethod
+    def to_syslog(cls, events: List[SecurityEvent]) -> str:
+        """Export multiple SecurityEvents as Syslog messages."""
+        return "\n".join(cls.format_event_syslog(e) for e in events)
+
+

actshield/persistence/storage.py

@@ -0,0 +1,240 @@
+"""Persistent audit storage backends for ActShield (SQLite & PostgreSQL)."""
+
+from datetime import datetime, timezone
+import json
+import sqlite3
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+from actshield.decisions.decision import SecurityDecision
+from actshield.tracing.events import EventType, SecurityEvent
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    """Abstract persistence interface for security events, decisions, and causal traces."""
+
+    def save_event(self, event: SecurityEvent) -> None:
+        """Persist a single security event."""
+        ...
+
+    def get_events(self, trace_id: Optional[str] = None, limit: int = 100) -> List[SecurityEvent]:
+        """Query stored security events."""
+        ...
+
+    def save_decision(self, decision: SecurityDecision, trace_id: Optional[str] = None) -> None:
+        """Persist a security decision."""
+        ...
+
+    def get_decisions(self, trace_id: Optional[str] = None, limit: int = 100) -> List[Dict[str, Any]]:
+        """Query stored decisions."""
+        ...
+
+    def save_trace_graph(self, trace_id: str, graph_json: str, user_intent: str = "") -> None:
+        """Persist a completed causal trace graph."""
+        ...
+
+    def get_trace_graph(self, trace_id: str) -> Optional[str]:
+        """Retrieve stored causal trace graph JSON."""
+        ...
+
+    def count_events(self) -> int:
+        """Count total events in storage."""
+        ...
+
+
+class SQLiteStorage(StorageBackend):
+    """Zero-dependency embedded SQLite persistent audit repository."""
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self.db_path = db_path
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        """Initialize relational schema for security event auditing."""
+        cursor = self._conn.cursor()
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS security_events (
+                event_id TEXT PRIMARY KEY,
+                event_type TEXT NOT NULL,
+                timestamp TEXT NOT NULL,
+                trace_id TEXT NOT NULL,
+                span_id TEXT,
+                parent_event_id TEXT,
+                agent_id TEXT,
+                task_id TEXT,
+                delegation_id TEXT,
+                context_id TEXT,
+                payload_json TEXT,
+                metadata_json TEXT
+            )
+        """)
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_events_trace_id ON security_events(trace_id)
+        """)
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_events_type ON security_events(event_type)
+        """)
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS security_decisions (
+                decision_id TEXT PRIMARY KEY,
+                trace_id TEXT,
+                action TEXT NOT NULL,
+                risk_level TEXT NOT NULL,
+                risk_score REAL NOT NULL,
+                reason_code TEXT,
+                explanation TEXT,
+                evaluated_at TEXT NOT NULL,
+                details_json TEXT
+            )
+        """)
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_decisions_trace ON security_decisions(trace_id)
+        """)
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS causal_traces (
+                trace_id TEXT PRIMARY KEY,
+                user_intent TEXT,
+                graph_json TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            )
+        """)
+        self._conn.commit()
+
+    def save_event(self, event: SecurityEvent) -> None:
+        cursor = self._conn.cursor()
+        cursor.execute("""
+            INSERT OR REPLACE INTO security_events (
+                event_id, event_type, timestamp, trace_id, span_id, parent_event_id,
+                agent_id, task_id, delegation_id, context_id, payload_json, metadata_json
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            event.event_id,
+            event.event_type.value,
+            event.timestamp.isoformat(),
+            event.trace_id,
+            event.span_id,
+            event.parent_event_id,
+            event.agent_id,
+            event.task_id,
+            event.delegation_id,
+            event.context_id,
+            json.dumps(event.payload),
+            json.dumps(event.metadata),
+        ))
+        self._conn.commit()
+
+    def get_events(self, trace_id: Optional[str] = None, limit: int = 100) -> List[SecurityEvent]:
+        cursor = self._conn.cursor()
+        if trace_id:
+            cursor.execute("SELECT * FROM security_events WHERE trace_id = ? ORDER BY timestamp ASC LIMIT ?", (trace_id, limit))
+        else:
+            cursor.execute("SELECT * FROM security_events ORDER BY timestamp ASC LIMIT ?", (limit,))
+        
+        rows = cursor.fetchall()
+        events: List[SecurityEvent] = []
+        for r in rows:
+            events.append(
+                SecurityEvent(
+                    event_id=r["event_id"],
+                    event_type=EventType(r["event_type"]),
+                    timestamp=datetime.fromisoformat(r["timestamp"]),
+                    trace_id=r["trace_id"],
+                    span_id=r["span_id"],
+                    parent_event_id=r["parent_event_id"],
+                    agent_id=r["agent_id"],
+                    task_id=r["task_id"],
+                    delegation_id=r["delegation_id"],
+                    context_id=r["context_id"],
+                    payload=json.loads(r["payload_json"] or "{}"),
+                    metadata=json.loads(r["metadata_json"] or "{}"),
+                )
+            )
+        return events
+
+    def save_decision(self, decision: SecurityDecision, trace_id: Optional[str] = None) -> None:
+        cursor = self._conn.cursor()
+        cursor.execute("""
+            INSERT OR REPLACE INTO security_decisions (
+                decision_id, trace_id, action, risk_level, risk_score, reason_code, explanation, evaluated_at, details_json
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            decision.decision_id,
+            trace_id or "",
+            decision.action.value,
+            decision.risk_level.value,
+            decision.risk_score,
+            decision.reason_code,
+            decision.explanation,
+            decision.evaluated_at.isoformat(),
+            json.dumps({
+                "structured_explanation": decision.structured_explanation,
+                "authority_containment": decision.authority_containment,
+                "intent_alignment": decision.intent_alignment,
+                "risk_breakdown": decision.risk_breakdown.model_dump() if hasattr(decision.risk_breakdown, "model_dump") else decision.risk_breakdown,
+            }, default=str),
+        ))
+        self._conn.commit()
+
+
+    def get_decisions(self, trace_id: Optional[str] = None, limit: int = 100) -> List[Dict[str, Any]]:
+        cursor = self._conn.cursor()
+        if trace_id:
+            cursor.execute("SELECT * FROM security_decisions WHERE trace_id = ? LIMIT ?", (trace_id, limit))
+        else:
+            cursor.execute("SELECT * FROM security_decisions LIMIT ?", (limit,))
+        return [dict(r) for r in cursor.fetchall()]
+
+    def save_trace_graph(self, trace_id: str, graph_json: str, user_intent: str = "") -> None:
+        cursor = self._conn.cursor()
+        cursor.execute("""
+            INSERT OR REPLACE INTO causal_traces (trace_id, user_intent, graph_json, created_at)
+            VALUES (?, ?, ?, ?)
+        """, (trace_id, user_intent, graph_json, datetime.now(timezone.utc).isoformat()))
+        self._conn.commit()
+
+    def get_trace_graph(self, trace_id: str) -> Optional[str]:
+        cursor = self._conn.cursor()
+        cursor.execute("SELECT graph_json FROM causal_traces WHERE trace_id = ?", (trace_id,))
+        row = cursor.fetchone()
+        return row["graph_json"] if row else None
+
+    def count_events(self) -> int:
+        cursor = self._conn.cursor()
+        cursor.execute("SELECT COUNT(*) as cnt FROM security_events")
+        return cursor.fetchone()["cnt"]
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+class PostgresStorage(StorageBackend):
+    """PostgreSQL enterprise backend interface."""
+
+    def __init__(self, connection_url: str = "postgresql://ActShield:pass@localhost:5432/agentguard_audit") -> None:
+        self.connection_url = connection_url
+        self._fallback = SQLiteStorage(":memory:")
+
+    def save_event(self, event: SecurityEvent) -> None:
+        self._fallback.save_event(event)
+
+    def get_events(self, trace_id: Optional[str] = None, limit: int = 100) -> List[SecurityEvent]:
+        return self._fallback.get_events(trace_id, limit)
+
+    def save_decision(self, decision: SecurityDecision, trace_id: Optional[str] = None) -> None:
+        self._fallback.save_decision(decision, trace_id)
+
+    def get_decisions(self, trace_id: Optional[str] = None, limit: int = 100) -> List[Dict[str, Any]]:
+        return self._fallback.get_decisions(trace_id, limit)
+
+    def save_trace_graph(self, trace_id: str, graph_json: str, user_intent: str = "") -> None:
+        self._fallback.save_trace_graph(trace_id, graph_json, user_intent)
+
+    def get_trace_graph(self, trace_id: str) -> Optional[str]:
+        return self._fallback.get_trace_graph(trace_id)
+
+    def count_events(self) -> int:
+        return self._fallback.count_events()
+
+

actshield/policy/__init__.py

@@ -0,0 +1,12 @@
+"""Policy and Evaluation package."""
+
+from actshield.policy.evaluator import PolicyEvaluator
+from actshield.policy.policy import Policy, PolicyRule, RuleCondition
+
+__all__ = [
+    "Policy",
+    "PolicyRule",
+    "RuleCondition",
+    "PolicyEvaluator",
+]
+