ActShield

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

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

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

# 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

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

# 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:

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 for details.