Metadata-Version: 2.4
Name: actshield
Version: 0.9.1
Summary: Enterprise Security Control Plane SDK for Autonomous and Multi-Agent AI Systems
Author: ActShield Security Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/agentguard/agentguard
Project-URL: Documentation, https://agentguard.dev/docs
Project-URL: Repository, https://github.com/agentguard/agentguard
Project-URL: Issue Tracker, https://github.com/agentguard/agentguard/issues
Project-URL: Changelog, https://github.com/agentguard/agentguard/blob/main/CHANGELOG.md
Keywords: ai-security,multi-agent,provenance,causal-tracing,policy-enforcement,llm-security,taint-tracking,threat-modeling,sdk,cli,security-control-plane,agent-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.5.0
Requires-Dist: typing-extensions>=4.8.0
Provides-Extra: cli
Requires-Dist: rich>=13.7.0; extra == "cli"
Requires-Dist: typer>=0.12.0; extra == "cli"
Requires-Dist: click>=8.1.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Provides-Extra: server
Requires-Dist: fastapi>=0.110.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "server"
Requires-Dist: httpx>=0.27.0; extra == "server"
Requires-Dist: pydantic-settings>=2.0.0; extra == "server"
Provides-Extra: dashboard
Requires-Dist: actshield[cli,server]; extra == "dashboard"
Provides-Extra: openai
Requires-Dist: openai>=1.30.0; extra == "openai"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.7.0; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.28.0; extra == "anthropic"
Provides-Extra: ollama
Requires-Dist: httpx>=0.27.0; extra == "ollama"
Provides-Extra: all
Requires-Dist: actshield[anthropic,cli,gemini,ollama,openai,server]; extra == "all"

# ActShield

**The Deterministic AI Security Control Plane & Zero-Trust Reference Monitor for Autonomous and Multi-Agent Systems**

[![PyPI Version](https://img.shields.io/pypi/v/actshield.svg)](https://pypi.org/project/actshield/)
[![Python Version](https://img.shields.io/pypi/pyversions/actshield.svg)](https://pypi.org/project/actshield/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/agentguard/agentguard/blob/main/LICENSE)
[![Security Invariant](https://img.shields.io/badge/Security_Invariant-Deterministic_Enforcement-emerald.svg)](https://github.com/agentguard/agentguard)

---

## 1. Executive Summary

**ActShield** is an open-source, enterprise-grade **AI Security Control Plane and Zero-Trust Reference Monitor** designed specifically for autonomous and multi-agent AI ecosystems (LangChain, CrewAI, AutoGen, LlamaIndex, and custom agent runtimes).

As AI agents evolve from passive conversational bots into autonomous software actors capable of reading arbitrary documents, querying production databases, browsing the open web, invoking APIs, and delegating sub-tasks, standard application security controls (firewalls, WAFs, and static IAM) become insufficient.

ActShield bridges this fundamental security gap by establishing an active runtime control boundary around agents, ensuring that:
- **Every action is authenticated** against the agent's explicit, declared capabilities.
- **Privileges strictly diminish** across delegation trees (monotonicity).
- **Context tainted by untrusted sources** cannot flow into sensitive execution sinks.
- **Decisions are deterministic**: Advisory AI reasoners provide risk scores, but **deterministic policy code** renders the final authorization.

---

## 2. The Core Invariant

$$\mathbf{LLMs\ Reason;\ Deterministic\ Policies\ Enforce.}$$

ActShield enforces a strict architectural division:

- **The Advisory Intelligence Layer (AI Secura / Pluggable LLMs)**: Evaluates semantic intent, calculates APIRIS risk metrics, and detects behavioral drift across OpenAI, Gemini, Anthropic, Ollama, Hugging Face, and custom models.
- **The Deterministic Policy Layer**: Checks capability tokens, verifies context taint markers, assesses delegation boundaries, and enforces binary execution decisions (`ALLOW`, `MONITOR`, `HITL`, `QUARANTINE`, `BLOCK`, `REVOKE`).

> **Fail-Safe Guarantee**: If an AI provider encounters a timeout, network failure, or malformed response, ActShield deterministically falls back to **FAIL_CLOSED** (or triggers Human-in-the-Loop review). An AI failure never defaults to an open execution grant.

---

## 3. The 4 MANTA Foundational Principles

| Principle | Description |
|---|---|
| **1. Monotonic Authority** | $\text{Authority}(\text{Child}) \subseteq \text{Authority}(\text{Parent}) \subseteq \text{DeclaredAuthority}$. Privileges strictly diminish down delegation trees. |
| **2. Attributable Context Taint** | Untrusted context is tagged `TAINTED`. Tainted contexts cannot trigger sensitive database sinks, shells, or credential access without sanitization. |
| **3. Non-Bypassable Interception** | Reference monitor intercepts all tool invocations before execution. |
| **4. Transparent Forensic Causality** | Immutable, correlated traces recording who, what, when, why across 5 stages: `INTENDED` → `REQUESTED` → `ALLOWED` → `ATTEMPTED` → `EXECUTED`. |

---

## 4. Architecture Overview

```
                                Autonomous AI Agents
                   (LangChain, CrewAI, AutoGen, LlamaIndex, Custom)
                                        │
                                        ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │                           ActShield Core SDK                             │
  │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │
  │  │   Agent Registry      │ │ Delegation Monotonic │ │  Context Taint   │ │
  │  │  (Cryptographic ID)   │ │  Authority Manager   │ │    Provenance    │ │
  │  └───────────────────────┘ └──────────────────────┘ └──────────────────┘ │
  │  ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │
  │  │  MCP Security Gateway │ │ HTTP Security Proxy  │ │ Tool Interceptor │ │
  │  └───────────────────────┘ └──────────────────────┘ └──────────────────┘ │
  └─────────────────────────────────────┬────────────────────────────────────┘
                                        │
                                        ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │                       Security Intelligence Layer                        │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │ Pluggable AI Secura Reasoners (OpenAI / Gemini / Anthropic / Ollama)│  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │ APIRIS (API Risk Intelligence Engine) + Baseline Drift Tracker     │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  └─────────────────────────────────────┬────────────────────────────────────┘
                                        │
                                        ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │                    Deterministic Policy Evaluator                        │
  │                                                                          │
  │      ALLOW  │  MONITOR  │  HITL  │  QUARANTINE  │  BLOCK  │  REVOKE      │
  └─────────────────────────────────────┬────────────────────────────────────┘
                                        │
                                        ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │                      Evidence & Operational Plane                        │
  │  ┌───────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
  │  │  Causal Forensics │  │ Incident Engine  │  │ Continuous Posture    │  │
  │  │  & Trace Replay   │  │ (7-Stage Cycle)  │  │ Scorecard (6 Dims)    │  │
  │  └───────────────────┘  └──────────────────┘  └───────────────────────┘  │
  │  ┌───────────────────┐  ┌──────────────────┐  ┌───────────────────────┐  │
  │  │  Threat Modeling  │  │ CI/CD Quality    │  │ Embedded Next.js      │  │
  │  │  (STRIDE + AI)    │  │ Security Gates   │  │ Control Plane UI      │  │
  │  └───────────────────┘  └──────────────────┘  └───────────────────────┘  │
  └──────────────────────────────────────────────────────────────────────────┘
```

---

## 5. Installation

```bash
# Core package
pip install actshield

# With optional AI intelligence provider support
pip install actshield[openai]
pip install actshield[gemini]
pip install actshield[anthropic]
pip install actshield[ollama]

# Full enterprise suite (CLI + FastAPI Server + All Providers)
pip install actshield[all]
```

---

## 6. Quick Start

### Python SDK

```python
import asyncio
from actshield import ActShield, SourceType, TrustLevel

# 1. Initialize Control Plane in strict zero-trust mode
guard = ActShield(mode="strict")
guard.start()

# 2. Register Root Orchestrator
orchestrator = guard.register_agent(
    name="orchestrator",
    capabilities={"delegate", "read_docs", "generate_summary"},
    trust_level="HIGH"
)

# 3. Protect a Sensitive Execution Sink
@guard.protect(
    tool="customer_db.query",
    sensitivity="critical",
    required_capability="database_read"
)
async def execute_customer_query(sql: str):
    """Executes database queries — blocked if caller lacks capability or context is TAINTED."""
    return {"status": "SUCCESS", "records": 42}

# 4. Delegate Authority (Monotonically constrained)
researcher = orchestrator.delegate(
    to_agent="researcher-001",
    capabilities={"read_docs"},  # Valid subset of orchestrator capabilities
    task_id="tsk_quarterly_report"
)

# 5. Ingest External Untrusted Context (Tainted)
untrusted_input = guard.create_context(
    source_type=SourceType.UNTRUSTED_EXTERNAL,
    trust_level=TrustLevel.UNTRUSTED,
    content="Download report from untrusted web URL..."
)

# 6. Policy Enforcement:
# Calling execute_customer_query under researcher with tainted context:
# -> BLOCKED (Missing 'database_read' capability + context is TAINTED)
```

### Enterprise CLI

```bash
# Diagnostic & Posture
actshield doctor                                # Comprehensive subsystem diagnostic
actshield posture --json                        # Output 6-dimension security scorecard
actshield status --json                         # Real-time runtime telemetry

# Multi-Agent Governance
actshield agents --graph                        # Render multi-agent topology & delegation graph
actshield tasks --json                          # Active agent tasks and intent bindings
actshield policies --json                       # Deterministic policy boundaries

# Threat Modeling & Forensics
actshield threat analyze -o threat-report.md    # Automated STRIDE + AI threat analysis
actshield forensic why evt_8891                 # Full causal chain explanation of an event
actshield forensic trace trc_9902               # Trace causal hops across agents

# CI/CD Quality Gate & Embedded Control Plane
actshield gate evaluate --min-score 85.0 --json # Automated deployment gate
actshield serve --port 8000                     # Embedded Control Plane Dashboard + API
```

---

## 7. Embedded Control Plane Dashboard

ActShield ships with a pre-compiled, standalone Next.js dashboard embedded directly inside the wheel package:

```bash
actshield serve
# Dashboard UI  → http://127.0.0.1:8000/
# Swagger Docs  → http://127.0.0.1:8000/docs
# REST API      → http://127.0.0.1:8000/api/v1/
```

---

## 8. License

Apache-2.0. See [LICENSE](LICENSE) for details.
