Skip to main content

Quickstart Guide

Get Shadow Executor running in under 5 minutes.

Prerequisites​

  • Node.js >= 20 (LTS)
  • npm >= 10

Installation​

Shadow Executor is published as an npm package. You can run it directly with npx without installing:

npx shadow-exec demo

This runs a self-contained demo showing Shadow Executor blocking a production database deletion.

Expected Output​

Shadow Executor v0.1.0 — Pre-Execution Simulation

Running demo scenario: AI agent attempts to delete a production RDS instance

  Agent Action:
    Service:    rds
    Operation:  DeleteDBInstance
    Resource:   arn:aws:rds:us-east-1:123456789012:db:prod-customer-data
    Tags:       Environment=production, Tier=critical

  IPI Check:     CLEAN  (score: 0.00)
  Simulation:    LOCAL MOCK

  Policy Evaluation:
    ✖  SE-001  CRITICAL  Block production database deletion
               Matched: service=rds, operation=DeleteDBInstance, tag Environment=production

  Decision:      BLOCKED
  Rule:          SE-001
  Log entry:     ~/.shadow-exec/audit.ndjson  [HMAC signed]

Action was blocked before reaching infrastructure.
Simulation took 12ms.

Initialize a Policy File​

Create a shadow-exec.policy.yaml file in your project directory:

npx shadow-exec init

This generates a starter policy file:

version: "1.0"
name: "Default Shadow Executor Policy"
rules:
  - id: SE-001
    name: Block production database deletion
    severity: CRITICAL
    action: BLOCK
    match:
      service: rds
      operation: DeleteDBInstance
      resource_tags:
        Environment: production

  - id: SE-002
    name: Require approval for IAM policy changes
    severity: HIGH
    action: REQUIRE_APPROVAL
    match:
      service: iam
      operation: [AttachUserPolicy, AttachRolePolicy, PutUserPolicy, PutRolePolicy]

  - id: SE-003
    name: Warn on S3 public access
    severity: MEDIUM
    action: WARN
    match:
      service: s3
      operation: PutBucketAcl
      parameters:
        ACL: [public-read, public-read-write]

Integrate with Your Agent Framework​

MCP Integration​

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

const shadowMiddleware = createShadowExecutorMiddleware({
  policyPath: './shadow-exec.policy.yaml',
  logPath: '~/.shadow-exec/audit.ndjson',
  logSecret: process.env.SHADOW_EXEC_LOG_SECRET,
  enableIPIDetection: true,
});

// Wrap your MCP server with Shadow Executor
server.use(shadowMiddleware);

Claude Code Integration​

Create ~/.shadow-exec/claude-code-config.json:

{
  "enabled": true,
  "policy_path": "./shadow-exec.policy.yaml",
  "log_path": "~/.shadow-exec/audit.ndjson",
  "simulation_mode": "local",
  "enable_ipi_detection": true
}

Shadow Executor automatically wraps Claude Code's MCP server via middleware injection.

LangGraph Integration​

import { createShadowExecutorTool } from '@shadow-executor/sdk/langgraph';

const tools = [
  createShadowExecutorTool({
    name: 'aws_rds_delete_db_instance',
    policyPath: './shadow-exec.policy.yaml',
    baseHandler: async (params) => {
      // Original tool logic
    }
  })
];

Verify Audit Log Integrity​

Shadow Executor signs all audit log entries with HMAC-SHA-256. Verify log integrity:

export SHADOW_EXEC_LOG_SECRET="your-secret-key"
npx shadow-exec verify-log

Expected output:

Shadow Executor - Audit Log Verification
=========================================

Log file: /Users/you/.shadow-exec/audit.ndjson

✓ Log integrity verified
  Total entries: 42
  All HMAC signatures valid

Next Steps​

Estimated Completion Time​

This quickstart should take 3-4 minutes from start to finish.

If you encountered issues, please check the FAQ or open an issue on GitHub.