actshield 0.9.0__py3-none-any.whl

actshield/__init__.py

@@ -0,0 +1,439 @@
+"""ActShield: Security Control Plane SDK for Autonomous and Multi-Agent AI Systems.
+
+Quick start::
+
+    from actshield import ActShield
+
+    guard = ActShield(mode="strict")
+
+    @guard.protect(tool="customer_db.read", sensitivity="critical")
+    async def read_customer_data():
+        ...
+
+    # Threat modeling
+    from actshield.threatmodel import ThreatAnalyzer
+    analyzer = ThreatAnalyzer()
+    result = analyzer.analyze()
+"""
+
+from actshield.agents.agent import Agent
+from actshield.agents.identity import AgentCapability, AgentIdentity, AgentStatus, AgentTrustLevel
+from actshield.client import ActShield
+from actshield.config import ActShieldConfig
+from actshield.context.context import Context
+from actshield.context.provenance import ContextSource, ContextTrustLevel, Provenance, ProvenanceHop, SanitizationRecord
+from actshield.context.taint import TaintState
+from actshield.decisions.decision import DecisionAction, SecurityDecision
+from actshield.delegation.authority import AuthorityGrant
+from actshield.delegation.delegation import Delegation, DelegationScope
+from actshield.approval.approval import (
+    ApprovalManager,
+    ApprovalRequest,
+    ApprovalStatus,
+)
+from actshield.gateway.http import HTTPGateway, HTTPInterceptedResponse
+from actshield.gateway.mcp import MCPGateway, MCPMessage
+
+from actshield.integrations.ai_secura import (
+    AISecuraClient,
+    LocalAISecuraAdapter,
+    SecurityAnalysis,
+    SecurityContext,
+    SecurityReasoner,
+)
+from actshield.providers.base import (
+    AnalysisResult,
+    HealthReport,
+    SecurityAIProvider,
+)
+from actshield.providers.registry import (
+    ProviderRegistry,
+    get_provider_registry,
+)
+from actshield.integrations.ai_secura_analysis import (
+    AISecuraAnalysis,
+    ThreatSeverity,
+    IntentAlignment,
+    AIRecommendation,
+    AttackTechnique,
+    EvidenceTriad,
+    AuthorityAnalysis,
+    TaintAnalysis,
+)
+from actshield.integrations.ollama_adapter import OllamaAISecuraAdapter
+from actshield.llm_config import LLMConfig
+from actshield.offensive import (
+    AttackCase,
+    AttackType,
+    ExpectedBehavior,
+    SafetyClass,
+    AttackTarget,
+    TargetEnvironment,
+    TargetRegistry,
+    target_registry,
+    SafetyValidationResult,
+    SafetyValidator,
+    safety_validator,
+    AttackStatus,
+    ExecutionEvidence,
+    OffensiveAttackResult,
+    AttackEvaluator,
+    MutationEngine,
+    MutationStrategy,
+    AttackCampaign,
+    CampaignSummary,
+    AttackCorpus,
+    attack_corpus,
+    AIAttackGenerator,
+    VulnerableDemoTarget,
+    OffensiveEngine,
+    SecurityAnalysisEvidence,
+    AdaptiveEngine,
+    CampaignMemory,
+)
+from actshield.integrations.apiris import (
+    APIAnalysis,
+    APIIntelligence,
+    APIRISClient,
+    LocalAPIRISAdapter,
+)
+from actshield.persistence.siem import SIEMExporter, SIEMFormat
+from actshield.persistence.storage import (
+    PostgresStorage,
+    SQLiteStorage,
+    StorageBackend,
+)
+from actshield.policy.evaluator import PolicyEvaluator
+from actshield.policy.intent import (
+    DeterministicIntentAnalyzer,
+    IntentAlignmentResult,
+    IntentAlignmentStatus,
+    IntentAnalyzer,
+)
+from actshield.policy.policy import Policy, PolicyRule, RuleCondition
+from actshield.risk.models import RiskAssessment, RiskFactorBreakdown, RiskLevel, RiskSignal
+from actshield.tasks.task import Task, TaskContext, TaskStatus
+from actshield.tools.interceptor import protected_tool
+from actshield.tools.tool import (
+    Resource,
+    SensitivityLevel,
+    ToolDefinition,
+    ToolRequest,
+    ToolResult,
+)
+from actshield.tracing.correlation import (
+    CorrelationContext,
+    SpanScope,
+    generate_id,
+    get_current_agent_id,
+    get_current_context,
+    get_current_delegation_id,
+    get_current_span_id,
+    get_current_task_id,
+    get_current_trace_id,
+)
+from actshield.tracing.events import EventType, SecurityEvent
+from actshield.tracing.tracer import CausalEdge, CausalGraph, CausalNode, TraceManager
+
+__version__ = "0.9.0"
+
+# Phase 6.5 — Forensic Intelligence + Product API
+from actshield.forensics.service import ForensicService
+from actshield.forensics.queries import ForensicQueryEngine
+from actshield.forensics.models import (
+    AgentAccessProfile,
+    ResourceAccessProfile,
+    AccessAttempt,
+    ActualAccess,
+    AccessSnapshot,
+    AccessDiff,
+    ForensicExplanation,
+    AttackForensicReport,
+    ForensicIncident,
+    IncidentType,
+    IncidentSeverity,
+    AccessMatrix,
+)
+from actshield.api.service import ApiService, SecurityPrincipal
+from actshield.api.models import (
+    AgentAccessResponse,
+    ResourceAccessResponse,
+    AccessMatrixResponse,
+    OverviewResponse,
+    AttackForensicsResponse,
+    IncidentResponse,
+    ErrorResponse,
+    HealthResponse,
+)
+
+# Phase 9 — Continuous Security Control Plane
+from actshield.posture import (
+    SecurityPostureSnapshot,
+    PostureRating,
+    FindingSeverity,
+    PostureFinding,
+    PostureDimensionMetrics,
+    PostureDiff,
+    PostureEngine,
+    PostureDiffEngine,
+    PostureRuleEvaluator,
+)
+from actshield.incidents import (
+    SecurityIncident,
+    IncidentState,
+    IncidentStateMachine,
+    IncidentTimelineEntry,
+    IncidentEngine,
+    IncidentCreationRule,
+)
+from actshield.response import (
+    ResponseActionType,
+    ResponseActionRecord,
+    AuthorityChangeEvent,
+    ResponseEngine,
+)
+from actshield.drift import (
+    DriftCategory,
+    DriftSeverity,
+    DriftEvent,
+    AgentBehaviorBaseline,
+    BehavioralBaselineTracker,
+    AuthorityDriftDetector,
+    AccessDriftDetector,
+    ContextDriftDetector,
+)
+from actshield.gates import (
+    GateStatus,
+    GateCheckRule,
+    SecurityGateResult,
+    SecurityGateEvaluator,
+    security_gate,
+)
+
+# Threat Modeling
+from actshield.threatmodel import (
+    ThreatAnalyzer,
+    ThreatReportRenderer,
+    ThreatModelExporter,
+    ThreatModel,
+    AnalysisResult as ThreatAnalysisResult,
+    ThreatSeverity,
+    ThreatCategory,
+    Asset,
+    AssetSensitivity,
+    ThreatActor,
+    ActorType,
+    TrustBoundary,
+    BoundaryType,
+    Threat,
+    AttackScenario,
+)
+
+__all__ = [
+    "ActShield",
+    "ActShieldConfig",
+    "Agent",
+    "AgentIdentity",
+    "AgentCapability",
+    "AgentTrustLevel",
+    "AgentStatus",
+    "Task",
+    "TaskContext",
+    "TaskStatus",
+    "Delegation",
+    "DelegationScope",
+    "AuthorityGrant",
+    "Context",
+    "ContextSource",
+    "ContextTrustLevel",
+    "Provenance",
+    "ProvenanceHop",
+    "SanitizationRecord",
+    "TaintState",
+    "ToolDefinition",
+    "Resource",
+    "SensitivityLevel",
+    "ToolRequest",
+    "ToolResult",
+    "protected_tool",
+    "Policy",
+    "PolicyRule",
+    "RuleCondition",
+    "PolicyEvaluator",
+    "IntentAnalyzer",
+    "DeterministicIntentAnalyzer",
+    "IntentAlignmentStatus",
+    "IntentAlignmentResult",
+    "RiskLevel",
+    "RiskSignal",
+    "RiskAssessment",
+    "RiskFactorBreakdown",
+    "DecisionAction",
+    "SecurityDecision",
+    "EventType",
+    "SecurityEvent",
+    "CorrelationContext",
+    "SpanScope",
+    "generate_id",
+    "get_current_context",
+    "get_current_trace_id",
+    "get_current_span_id",
+    "get_current_agent_id",
+    "get_current_task_id",
+    "get_current_delegation_id",
+    "CausalNode",
+    "CausalEdge",
+    "CausalGraph",
+    "TraceManager",
+    "SecurityReasoner",
+    "SecurityContext",
+    "SecurityAnalysis",
+    "SecurityAIProvider",
+    "AnalysisResult",
+    "HealthReport",
+    "ProviderRegistry",
+    "get_provider_registry",
+    "AISecuraClient",
+    "LocalAISecuraAdapter",
+    "APIIntelligence",
+    "APIAnalysis",
+    "APIRISClient",
+    "LocalAPIRISAdapter",
+    "MCPGateway",
+    "MCPMessage",
+    "HTTPGateway",
+    "HTTPInterceptedResponse",
+    "ApprovalManager",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "StorageBackend",
+    "SQLiteStorage",
+    "PostgresStorage",
+    "SIEMExporter",
+    "SIEMFormat",
+    "OllamaAISecuraAdapter",
+    "AISecuraAnalysis",
+    "ThreatSeverity",
+    "IntentAlignment",
+    "AIRecommendation",
+    "AttackTechnique",
+    "EvidenceTriad",
+    "AuthorityAnalysis",
+    "LLMConfig",
+    # Phase 4 Offensive Validation Engine
+    "AttackCase",
+    "AttackType",
+    "ExpectedBehavior",
+    "SafetyClass",
+    "AttackTarget",
+    "TargetEnvironment",
+    "TargetRegistry",
+    "target_registry",
+    "SafetyValidator",
+    "SafetyValidationResult",
+    "safety_validator",
+    "AttackStatus",
+    "ExecutionEvidence",
+    "OffensiveAttackResult",
+    "AttackEvaluator",
+    "MutationEngine",
+    "MutationStrategy",
+    "AttackCampaign",
+    "CampaignSummary",
+    "AttackCorpus",
+    "attack_corpus",
+    "AIAttackGenerator",
+    "VulnerableDemoTarget",
+    "OffensiveEngine",
+    # Phase 5 Adaptive Offensive Security Validation
+    "SecurityAnalysisEvidence",
+    "AdaptiveEngine",
+    "CampaignMemory",
+    # Phase 6.5 — Forensic Intelligence + Product API
+    "ForensicService",
+    "ForensicQueryEngine",
+    "AgentAccessProfile",
+    "ResourceAccessProfile",
+    "AccessAttempt",
+    "ActualAccess",
+    "AccessSnapshot",
+    "AccessDiff",
+    "ForensicExplanation",
+    "AttackForensicReport",
+    "ForensicIncident",
+    "IncidentType",
+    "IncidentSeverity",
+    "AccessMatrix",
+    "ApiService",
+    "SecurityPrincipal",
+    "AgentAccessResponse",
+    "ResourceAccessResponse",
+    "AccessMatrixResponse",
+    "OverviewResponse",
+    "AttackForensicsResponse",
+    "IncidentResponse",
+    "ErrorResponse",
+    "HealthResponse",
+    # Phase 9 — Continuous Security Control Plane
+    "SecurityPostureSnapshot",
+    "PostureRating",
+    "FindingSeverity",
+    "PostureFinding",
+    "PostureDimensionMetrics",
+    "PostureDiff",
+    "PostureEngine",
+    "PostureDiffEngine",
+    "PostureRuleEvaluator",
+    "SecurityIncident",
+    "IncidentState",
+    "IncidentStateMachine",
+    "IncidentTimelineEntry",
+    "IncidentEngine",
+    "IncidentCreationRule",
+    "ResponseActionType",
+    "ResponseActionRecord",
+    "AuthorityChangeEvent",
+    "ResponseEngine",
+    "DriftCategory",
+    "DriftSeverity",
+    "DriftEvent",
+    "AgentBehaviorBaseline",
+    "BehavioralBaselineTracker",
+    "AuthorityDriftDetector",
+    "AccessDriftDetector",
+    "ContextDriftDetector",
+    "GateStatus",
+    "GateCheckRule",
+    "SecurityGateResult",
+    "SecurityGateEvaluator",
+    "security_gate",
+    # Threat Modeling
+    "ThreatAnalyzer",
+    "ThreatReportRenderer",
+    "ThreatModelExporter",
+    "ThreatModel",
+    "ThreatAnalysisResult",
+    "ThreatSeverity",
+    "ThreatCategory",
+    "Asset",
+    "AssetSensitivity",
+    "ThreatActor",
+    "ActorType",
+    "TrustBoundary",
+    "BoundaryType",
+    "Threat",
+    "AttackScenario",
+    # Backward Compatibility Aliases
+    "AgentGuard",
+    "AgentGuardConfig",
+]
+
+# Backward compatibility aliases
+AgentGuard = ActShield
+AgentGuardConfig = ActShieldConfig
+
+
+
+
+
+

actshield/__main__.py

@@ -0,0 +1,46 @@
+"""ActShield package __main__ entrypoint."""
+from __future__ import annotations
+
+from typing import Any, Optional
+from actshield.cli.main import app, main
+from actshield.offensive import attack_corpus, OffensiveEngine
+
+
+def cli_attack_list() -> int:
+    """Compatibility handler for Phase 4 test suite."""
+    attacks = attack_corpus.get_all_attacks()
+    return 0 if len(attacks) > 0 else 1
+
+
+def cli_attack_run(args: Any) -> int:
+    """Compatibility handler for running attack cases."""
+    engine = OffensiveEngine()
+    limit = getattr(args, "limit", 5) or 5
+    atype = getattr(args, "type", None)
+    attacks = attack_corpus.get_all_attacks()
+    if atype:
+        attacks = [c for c in attacks if c.attack_type.value == atype or c.attack_type == atype]
+    attacks = attacks[:limit]
+    for c in attacks:
+        engine.execute_attack(c)
+    return 0
+
+
+def cli_attack_replay(attack_id: str) -> int:
+    """Compatibility handler for attack replay."""
+    engine = OffensiveEngine()
+    case = attack_corpus.get_attack(attack_id)
+    if case:
+        engine.execute_attack(case)
+    return 0
+
+
+def cli_attack_report() -> int:
+    """Compatibility handler for attack reporting."""
+    return 0
+
+
+if __name__ == "__main__":
+    main()
+
+

actshield/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Agents package exposing Agent, AgentIdentity, AgentCapability, and AgentTrustLevel."""
+
+from actshield.agents.agent import Agent
+from actshield.agents.identity import AgentCapability, AgentIdentity, AgentTrustLevel
+
+__all__ = [
+    "Agent",
+    "AgentIdentity",
+    "AgentCapability",
+    "AgentTrustLevel",
+]
+

actshield/agents/agent.py

@@ -0,0 +1,200 @@
+"""Agent runtime instance and orchestration interface."""
+
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+from datetime import datetime, timezone
+import inspect
+from actshield.agents.identity import AgentCapability, AgentIdentity, AgentStatus, AgentTrustLevel
+from actshield.tracing.events import EventType
+
+if TYPE_CHECKING:
+    from actshield.client import ActShield
+    from actshield.delegation.delegation import DelegationScope
+    from actshield.tracing.correlation import SpanScope
+
+
+class Agent:
+    """Represents a registered AI Agent within the ActShield platform."""
+
+    def __init__(self, identity: AgentIdentity, guard: Optional["ActShield"] = None) -> None:
+        self.identity = identity
+        self.guard = guard
+        now_iso = datetime.now(timezone.utc).isoformat()
+        if not self.identity.created_at:
+            self.identity.created_at = now_iso
+        if not self.identity.last_seen:
+            self.identity.last_seen = now_iso
+
+    @property
+    def agent_id(self) -> str:
+        return self.identity.agent_id
+
+    @property
+    def name(self) -> str:
+        return self.identity.name
+
+    @property
+    def framework(self) -> str:
+        return self.identity.framework
+
+    @property
+    def version(self) -> str:
+        return self.identity.version
+
+    @property
+    def status(self) -> AgentStatus:
+        return self.identity.status
+
+    @property
+    def trust_level(self) -> AgentTrustLevel:
+        return self.identity.trust_level
+
+    @property
+    def capabilities(self) -> List[AgentCapability]:
+        return self.identity.capabilities
+
+    @property
+    def parent_agent_id(self) -> Optional[str]:
+        return self.identity.parent_agent_id
+
+    @property
+    def current_task(self) -> Optional[str]:
+        return self.identity.current_task
+
+    @property
+    def owner_context(self) -> Optional[str]:
+        return self.identity.owner_context
+
+    @property
+    def created_at(self) -> Optional[str]:
+        return self.identity.created_at
+
+    @property
+    def last_seen(self) -> Optional[str]:
+        return self.identity.last_seen
+
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        return self.identity.metadata
+
+    def set_status(self, status: Union[str, AgentStatus]) -> None:
+        """Update agent operational status."""
+        if isinstance(status, str):
+            status = AgentStatus(status.lower())
+        self.identity.status = status
+        self.touch()
+        if self.guard:
+            self.guard.emit_event(
+                event_type=EventType.SECURITY_ALERT,
+                agent_id=self.agent_id,
+                payload={"action": "agent_status_change", "status": status.value},
+            )
+
+    def touch(self) -> None:
+        """Update last seen timestamp."""
+        self.identity.last_seen = datetime.now(timezone.utc).isoformat()
+
+    def set_task(self, task_name_or_id: Optional[str]) -> None:
+        """Set active task."""
+        self.identity.current_task = task_name_or_id
+        self.touch()
+
+    def has_capability(self, capability_name: str) -> bool:
+        """Check if this agent holds the specified capability."""
+        return self.identity.has_capability(capability_name)
+
+    def capability_names(self) -> List[str]:
+        """Return list of declared capability names."""
+        return self.identity.capability_names()
+
+    def delegate(
+        self,
+        delegate: Optional["Agent"] = None,
+        capabilities: Optional[List[Union[str, AgentCapability]]] = None,
+        constraints: Optional[Dict[str, Any]] = None,
+        to_agent: Optional["Agent"] = None,
+    ) -> "DelegationScope":
+        """Delegate a subset of authority/capabilities to a target agent within a scoped context."""
+        target = delegate or to_agent
+        if target is None:
+            raise ValueError("Target delegate agent must be provided to delegate().")
+        if self.guard is None:
+            raise RuntimeError("Agent is not attached to an ActShield instance.")
+        
+        self.touch()
+        return self.guard._create_delegation_scope(
+            delegator=self,
+            delegate=target,
+            capabilities=capabilities,
+            constraints=constraints,
+        )
+
+    def invoke(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        """Invoke a synchronous function within this agent's execution context."""
+        self.touch()
+        if self.guard is None:
+            return fn(*args, **kwargs)
+        
+        with self.guard.span(name=f"agent_invoke:{self.name}", agent_id=self.agent_id):
+            self.guard.emit_event(
+                event_type=EventType.AGENT_INVOKED,
+                agent_id=self.agent_id,
+                payload={
+                    "agent_name": self.name,
+                    "function": getattr(fn, "__name__", str(fn)),
+                }
+            )
+            return fn(*args, **kwargs)
+
+    async def ainvoke(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        """Invoke an asynchronous function within this agent's execution context."""
+        self.touch()
+        if self.guard is None:
+            if inspect.iscoroutinefunction(fn):
+                return await fn(*args, **kwargs)
+            return fn(*args, **kwargs)
+
+        with self.guard.span(name=f"agent_ainvoke:{self.name}", agent_id=self.agent_id):
+            self.guard.emit_event(
+                event_type=EventType.AGENT_INVOKED,
+                agent_id=self.agent_id,
+                payload={
+                    "agent_name": self.name,
+                    "function": getattr(fn, "__name__", str(fn)),
+                }
+            )
+            if inspect.iscoroutinefunction(fn):
+                return await fn(*args, **kwargs)
+            return fn(*args, **kwargs)
+
+    def __call__(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Allow Agent instance to be used directly as a decorator."""
+        import functools
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if self.guard:
+                with self.guard.agent_context(self.agent_id):
+                    if inspect.iscoroutinefunction(fn):
+                        return self.ainvoke(fn, *args, **kwargs)
+                    return self.invoke(fn, *args, **kwargs)
+            else:
+                if inspect.iscoroutinefunction(fn):
+                    return fn(*args, **kwargs)
+                return fn(*args, **kwargs)
+        wrapper.agent = self  # type: ignore
+        return wrapper
+
+    def __enter__(self) -> "Agent":
+        if self.guard:
+            self._scope = self.guard.span(name=f"agent_scope:{self.name}", agent_id=self.agent_id)
+            self._scope.__enter__()
+        self.touch()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if hasattr(self, "_scope") and self._scope:
+            self._scope.__exit__(exc_type, exc_val, exc_tb)
+
+    def __repr__(self) -> str:
+        return f"<Agent id='{self.agent_id}' name='{self.name}' status='{self.status.value}' trust='{self.trust_level.value}'>"
+
+