Skip to main content

API Reference

Complete API documentation for Shadow Executor core and SDK modules.

Package Structure​

@shadow-executor/
├── core                  # Core policy engine, IPI detector, audit logger
├── cli                   # Command-line interface (npx shadow-exec)
└── sdk                   # Framework integrations
    ├── mcp/             # MCP middleware
    ├── claude-code/     # Claude Code integration
    └── langgraph/       # LangGraph tool wrappers

Core Modules​

@shadow-executor/core​

Policy Engine

  • evaluateAction(action, policyPath) — Evaluate action against policy
  • loadPolicy(policyPath) — Load and validate policy YAML
  • PolicyDecision — Policy evaluation result type

IPI Detector

  • detectIPI(action) — Detect Indirect Prompt Injection attempts
  • IPIDetectorResult — IPI detection result type

Audit Logger

  • signDecision(decision, secret) — Sign policy decision with HMAC
  • verifyEntry(entry, secret) — Verify HMAC signature
  • appendToLog(entry, logPath) — Append entry to audit log
  • readAuditLog(logPath, filters) — Query audit log
  • verifyLog(logPath, secret) — Verify all log entries
  • exportLog(entries, format) — Export to JSON/CSV/NDJSON
  • rotateLogIfNeeded(logPath, maxSize, maxEntries) — Rotate log file

Simulator

  • simulateAction(action) — Simulate action in LocalStack
  • SimulationResult — Simulation result type

Approval Workflow

  • requestApproval(decision, config) — Create approval request
  • pollApprovalStatus(requestId) — Check approval status
  • waitForApproval(decision) — Wait for approval with timeout
  • updateApprovalStatus(requestId, status) — Manually approve/deny

SDK Modules​

@shadow-executor/sdk/mcp​

MCP Middleware

  • wrapToolHandler(handler, config) — Wrap single MCP tool handler
  • wrapAllToolHandlers(handlers, config) — Wrap multiple tool handlers
  • convertToAgentAction(toolName, args) — Convert MCP call to AgentAction
  • BlockedActionError — Error thrown when action blocked

@shadow-executor/sdk/claude-code​

Claude Code Integration

  • loadClaudeCodeConfig() — Load Claude Code configuration
  • wrapClaudeCodeTool(tool, config) — Wrap Claude Code tool
  • wrapAllClaudeCodeTools(tools, config) — Wrap all tools
  • isClaudeCodeProtectionEnabled() — Check if protection enabled

@shadow-executor/sdk/langgraph​

LangGraph Integration (TypeScript)

  • createShadowExecutorTool(config) — Create protected LangGraph tool
  • wrapLangGraphTools(tools, config) — Wrap multiple tools

LangGraph Integration (Python)

  • create_shadow_executor_tool(name, func, policy_path, ...) — Create protected tool
  • wrap_langgraph_tools(tools, policy_path, ...) — Wrap multiple tools

CLI Commands​

npx shadow-exec​

Commands:

  • init — Initialize shadow-exec.policy.yaml
  • run — Run policy enforcement
  • demo — Self-contained demo
  • verify-log — Verify audit log integrity

Options:

  • --policy-path <path> — Path to policy file
  • --log-path <path> — Path to audit log
  • --secret <secret> — HMAC secret for signing

Type Reference​

See individual module pages for complete type definitions:

Usage Examples​

Basic Policy Enforcement​

import { evaluateAction } from '@shadow-executor/core';

const action = {
  service: 'rds',
  operation: 'DeleteDBInstance',
  resource: 'prod-db-01',
  resource_tags: { Environment: 'production' },
  timestamp: new Date().toISOString(),
};

const decision = await evaluateAction(action, './shadow-exec.policy.yaml');

if (decision.action === 'BLOCK') {
  console.error('Action blocked:', decision.reason);
  throw new Error(`Blocked by policy rule ${decision.matched_rule_id}`);
}

MCP Integration​

import { wrapToolHandler } from '@shadow-executor/sdk/mcp';

const protectedTool = wrapToolHandler(originalHandler, {
  toolName: 'aws_rds_delete_db_instance',
  policyPath: './shadow-exec.policy.yaml',
  logSecret: process.env.SHADOW_EXEC_LOG_SECRET!,
});

// Use protectedTool in your MCP server

Audit Log Query​

import { readAuditLog } from '@shadow-executor/core';

const blocked = readAuditLog('~/.shadow-exec/audit.ndjson', {
  action: 'BLOCK',
  service: 'rds',
  after: '2026-05-01T00:00:00.000Z',
  limit: 100,
});

console.log(`Blocked ${blocked.length} RDS operations since May 1st`);

Next Steps​

Explore specific modules: