Agent Security Context Pack

Runtime security scaffolding for local AI assistants. Provides capability-based access control, a tool-call firewall, and tamper-evident audit logging.

Why This Exists

AI assistants running locally can read files, browse the web, execute tools, and interact with external services. Without proper guardrails, they're vulnerable to:

• Prompt injection from malicious web content or emails
• Data exfiltration to attacker-controlled endpoints
• Credential theft through path traversal or forbidden file access
• Supply chain attacks via compromised tools/skills

This package provides defense-in-depth security that works at runtime, not through prompts.

Features

• Capability Tiers (T0-T3): Progressive permission levels from read-only to shell execution
• Tool-Call Firewall: 7-stage validation pipeline for every operation
• Taint Tracking: Labels untrusted data and blocks it from dangerous contexts
• Path Validation: Blocks traversal attacks and forbidden paths (.ssh, .env, etc.)
• Domain Validation: Allowlists, blocklists, and SSRF protection
• Shell Validation: Blocks dangerous command patterns
• Rate Limiting: Token-bucket algorithm prevents abuse
• Approval Queue: Step-up authentication for sensitive operations
• Hash-Chained Audit Logs: Tamper-evident logging with Merkle proofs
• Tool Registry: Hash-pinned tool verification

Installation

npm install agent-security-context-pack

Quick Start

import {
  createSecurityContext,
  PolicyEngine,
  TrustLevel,
} from 'agent-security-context-pack';

// Load policy from YAML
const policy = await PolicyEngine.fromFiles(['./policy.yaml']);

// Create security context
const { firewall, taintTracker, auditLogger } = createSecurityContext({
  policy,
  auditPath: './audit.ndjson',
});

// Wrap your tool executor
const secureExecutor = firewall.wrap(async (tool, args) => {
  // Your tool execution logic
  return await executeTool(tool, args);
});

// Mark external data as untrusted
const webContent = await fetch('https://example.com');
taintTracker.taint(webContent, TrustLevel.UNTRUSTED, {
  id: 'web:example.com',
  type: 'web_fetch',
});

// Execute tool calls through the firewall
try {
  const result = await secureExecutor({
    id: 'call-123',
    tool: 'file:read',
    arguments: { path: '/path/to/file' },
    sourceTrust: TrustLevel.TRUSTED,
    context: { sessionId: 'session-1', agentId: 'agent-1' },
  });
} catch (error) {
  if (error instanceof ApprovalRequiredError) {
    // Handle approval flow
  }
}

Security Guarantees

| Threat | Protection | How | |--------|------------|-----| | Prompt injection | High | Taint tracking blocks untrusted data in shell/file/email contexts | | Data exfiltration | High | Domain allowlists + approval for external sends | | Credential theft | High | Forbidden paths block .ssh, .env, *.pem, etc. | | Path traversal | High | Normalized paths, blocked .. sequences | | Shell injection | High | T3 disabled by default, dangerous patterns blocked | | Supply chain attacks | Medium | Hash-pinned tools, signature verification | | Audit tampering | High | Hash-chained logs with Merkle proofs |

See THREAT_MODEL.md for detailed analysis.

Documentation

• Quickstart Guide - Get running in 5 minutes
• Integration Guide - Deep dive into integration patterns
• Threat Model - Security analysis and guarantees

Examples

• Policy Presets - Ready-to-use security configurations
• Attack Scenarios - See the protections in action
• Molt Config - Example AI assistant configuration

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Tool Call Request                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    FIREWALL (7 Stages)                       │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Schema  │→│  Tier   │→│Validator│→│  Trust  │→ ...      │
│  │  Check  │ │  Check  │ │  Check  │ │  Check  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
         ┌─────────┐    ┌─────────┐    ┌─────────┐
         │ ALLOWED │    │ DENIED  │    │APPROVAL │
         └─────────┘    └─────────┘    │REQUIRED │
                                       └─────────┘

Policy Configuration

Policies are defined in YAML:

tiers:
  T0_READ_ONLY:
    enabled: true
    requires_approval: never
    operations:
      - "file:read"
      - "web:fetch"

  T2_WRITE_SEND:
    enabled: false  # Disabled by default
    requires_approval: always
    operations:
      - "file:write"
      - "email:send"

resources:
  filesystem:
    forbidden_paths:
      - "${HOME}/.ssh"
      - "**/.env"

See POLICY/capabilities.yaml for full reference.

Known Limitations (v0.1.0-alpha)

This is an alpha release. The core security primitives work and are tested, but some features are stubbed:

| Feature | Status | Notes | |---------|--------|-------| | Firewall | Working | 7-stage validation, all validators functional | | Taint Tracking | Working | Trust levels, propagation, hard blocks | | Path Validation | Working | Traversal detection, forbidden paths | | Domain Validation | Working | Allowlists, SSRF protection | | Shell Validation | Working | Dangerous pattern detection | | Rate Limiting | Working | Token bucket, in-memory only | | Hash Verification | Stub | HashVerifier.verify() always returns true | | Signature Verification | Stub | No real Ed25519 - placeholder only | | Audit Persistence | Stub | Logs to memory, not disk | | Lock File I/O | Stub | In-memory only | | CLI (ascp) | Not Implemented | Planned for v0.2.0 | | YAML Parsing | Partial | codeExecution/skillInstall use hardcoded defaults |

What works today: Firewall, taint tracking, all validators, approval queue, hash-chained audit logs (in memory).

What's coming: Persistent storage, real cryptography, CLI tools. See the roadmap below.

Roadmap

| Version | Focus | Key Features | |---------|-------|--------------| | v0.2.0 | Persistence & CLI | Audit log persistence, lock file I/O, basic CLI | | v0.3.0 | Real Cryptography | Ed25519 signatures, actual hash verification | | v0.4.0 | Production | Policy hot-reload, MCP server wrapper | | v1.0.0 | Stable | Security audit, full feature parity |

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for development)

License

MIT - See LICENSE

Contributing

Contributions welcome. Please read the threat model first to understand security requirements.

Security

If you discover a security vulnerability, please report it privately rather than opening a public issue.