traceshield 🛡️

Part of the Agent OS suite — kernel · network · memory · policy · audit · testing

Audit trail and policy enforcement for AI agent actions.

Every action an AI agent takes — tool call, API request, file write, decision — is recorded, attributed, and policy-checked in real time. Like an immutable audit log for your agent fleet.

OWASP Agentic AI Top 10 Coverage

traceshield's detection, blocking, and audit capabilities mapped to the OWASP Top 10 for Agentic Applications (ASI01–ASI10:2026):

Risk	Threat	traceshield capability
ASI01	Agent Goal Hijack	Injection detection + runtime guard blocking
ASI02	Tool Misuse & Exploitation	Policy engine rules, rate limits, tool allowlists
ASI03	Agent Identity & Privilege Abuse	Attribution chains + human approval gates
ASI04	Agentic Supply Chain Compromise	traceshield scan MCP config auditing
ASI05	Unexpected Code Execution	Pre-execution interception, shell-flag scanning
ASI06	Memory & Context Poisoning	Injection detector on memory writes
ASI07	Insecure Inter-Agent Communication	SHA-256 hash chain, tamper detection
ASI08	Cascading Agent Failures	Behavior baselines + attribution graphs
ASI09	Human-Agent Trust Exploitation	Forced approval gates + red team toolkit
ASI10	Rogue Agents	Per-agent anomaly detection + quarantine alerts

→ Full matrix (shipped / partial / planned, per module): docs/owasp-asi-mapping.md

---

The Problem

AI agents operate autonomously. When something goes wrong — a bad API call, a policy violation, unexpected output — you need answers:

• What exactly did the agent do?
• Why did it make that decision?
• Who authorized this action?
• Did it comply with our policies?

Without traceshield, answering these questions means sifting through unstructured logs. With traceshield, every action is cryptographically chained, attributed, and policy-checked.

---

Features

• 📝 Immutable trace log — every agent action recorded with hash-chain integrity
• 🔗 Attribution — link every action to the agent, user, and trigger that caused it
• 🚦 Policy engine — define rules (YAML or code) that block or flag policy violations
• 🛡️ Runtime guard — intercept actions before they execute and enforce policies
• 🔍 Audit queries — query traces by agent, time, action type, or policy outcome
• 💾 Storage adapters — in-memory, SQLite, PostgreSQL
• 🔌 LLM adapters — OpenAI, LangChain integration out of the box
• 🚨 Violation webhooks — real-time Slack/SIEM alerts on policy violations (v0.2.0)
• 🧪 Prompt injection detection — multi-layer pattern-based prevention (v0.2.0)
• 📈 Behavior baseline — anomaly detection via per-agent learning (v0.2.0)
• 🔴 Red team toolkit — adversarial attack scenarios (v0.2.0)
• 🧠 Threat intel feed — dynamic policy updates from MISP/OpenCTI (v0.2.0)
• 📦 Compliance export — JSON-LD / CEF / JSON with integrity proof (v0.2.0)
• 🔐 ZK compliance proofs — privacy-preserving audits (v0.2.0)
• 🔎 MCP config scanner — traceshield scan audits MCP client configs (Claude Desktop, VS Code, Cursor) for tool-description poisoning, hidden Unicode smuggling, and dangerous permission combos (v0.5.0)

---

Installation

npm install traceshield

For persistent storage:

npm install traceshield better-sqlite3   # SQLite
npm install traceshield pg               # PostgreSQL

---

Quick Start

import { TraceRecorder, RuntimeGuard, PolicyEngine } from 'traceshield';

// 1. Set up policy engine
const policy = new PolicyEngine();
policy.loadFromYaml(`
rules:
  - name: no-external-api-without-approval
    match: { action: 'http-request', external: true }
    require: { approval: true }
    on_violation: block

  - name: rate-limit-tool-calls
    match: { action: 'tool-call' }
    limit: { per_minute: 20, per_agent: true }
    on_violation: throttle

  - name: log-sensitive-data-access
    match: { action: 'data-read', tags: ['pii', 'sensitive'] }
    on_match: flag
`);

// 2. Wrap your agent with the runtime guard
const guard = new RuntimeGuard({ policy });

// 3. Record traces
const recorder = new TraceRecorder({ guard });

// Intercept agent actions
const trace = await recorder.record({
  agentId: 'data-processor',
  action: 'data-read',
  resource: 'users.csv',
  tags: ['pii'],
  metadata: { userId: 'u-123' },
}, async () => {
  // Your agent's actual action
  return await readUserData('users.csv');
});

console.log(trace.id);          // unique trace ID
console.log(trace.hash);        // SHA-256 of trace content
console.log(trace.prevHash);    // links to previous trace (hash chain)
console.log(trace.policy);      // { outcome: 'flagged', rule: 'log-sensitive-data-access' }

---

Core Concepts

Hash Chain Integrity

Every trace record includes a hash of its content plus a reference to the previous hash — forming an immutable chain:

Trace #1: hash=abc123, prevHash=null
Trace #2: hash=def456, prevHash=abc123
Trace #3: hash=ghi789, prevHash=def456

Tampering with any record breaks the chain. Verify integrity:

const { valid, brokenAt } = await recorder.verifyChain();
if (!valid) {
  console.error(`Chain broken at trace ${brokenAt.id}`);
}

Policy Engine

Define policies in YAML or TypeScript:

policy.addRule({
  name: 'require-human-approval-for-deletions',
  match: (action) => action.type === 'delete',
  check: async (action) => {
    const approved = await checkHumanApproval(action);
    return approved ? 'allow' : 'block';
  },
  onViolation: 'block',
  message: 'Deletion requires human approval',
});

Attribution Analyzer

Trace the root cause of any action:

const attribution = await analyzer.trace(traceId);
console.log(attribution);
// {
//   traceId: 'tr-789',
//   agentId: 'data-processor',
//   triggeredBy: { agentId: 'coordinator', traceId: 'tr-456' },
//   userRequest: { userId: 'u-001', sessionId: 'sess-123' },
//   causalChain: ['tr-123', 'tr-456', 'tr-789'],
// }

---

LLM Adapters

OpenAI

import { OpenAIAdapter } from 'traceshield/adapters/openai';

const tracedClient = new OpenAIAdapter(openai, recorder);
// All completions, tool calls, and embeddings are automatically traced
const response = await tracedClient.chat.completions.create({...});

LangChain

import { TraceShieldCallbackHandler } from 'traceshield/adapters/langchain';

const handler = new TraceShieldCallbackHandler(recorder);
const chain = new LLMChain({ ..., callbacks: [handler] });

---

Audit Queries

// Get all traces for an agent in the last hour
const traces = await recorder.query({
  agentId: 'data-processor',
  from: Date.now() - 3600_000,
  actionTypes: ['data-read', 'tool-call'],
});

// Get policy violations
const violations = await recorder.query({
  policyOutcome: ['blocked', 'flagged'],
  limit: 100,
});

// Full audit report
const report = await recorder.auditReport({
  from: startOfDay,
  to: endOfDay,
  groupBy: 'agent',
});

---

CLI

traceshield ships an audit CLI (status / traces / violations / verify — see traceshield help) plus a supply-chain scanner:

# Scan well-known MCP config locations for the current user
npx @cdzzy/traceshield scan

# Scan specific files or directories (directories are searched for known config names)
npx @cdzzy/traceshield scan ~/.claude/claude_desktop_config.json ./project

# Machine-readable output for CI
npx @cdzzy/traceshield scan --json

The scanner detects tool-description poisoning (instruction-override phrases), hidden Unicode smuggling (zero-width / bidi characters), and dangerous permission combos (permissive execution flags, shell wrappers with secrets, wildcard tool allowlists, root filesystem mounts). Exit code is 1 when high/critical findings are present, so it can gate CI directly.

---

Comparison

Feature	traceshield	LangSmith	Helicone	Custom Logging
Hash-chain integrity	✅	❌	❌	❌
Policy enforcement	✅	❌	❌	❌
Attribution tracing	✅	✅	❌	❌
Self-hosted	✅	⚠️	❌	✅
LLM adapter SDK	✅	✅	✅	❌

---

Roadmap

• Compliance report templates (SOC2, GDPR) ✅ (src/compliance-reports.ts)
• Real-time violation webhooks ✅ (src/webhook-notifier.ts, v0.2.0)
• Prompt injection detection ✅ (src/injection-detector.ts, v0.2.0)
• Behavior baseline learning ✅ (src/behavior-baseline.ts, v0.2.0)
• Red team toolkit ✅ (src/red-team.ts, v0.2.0)
• Threat intelligence integration ✅ (src/threat-intel.ts, v0.2.0)
• Tamper-evident audit export (JSON-LD / CEF) ✅ (src/compliance-exporter.ts, v0.2.0)
• ZK compliance proofs ✅ (src/zk-compliance.ts, v0.2.0)
• Policy-as-code + GitOps (validatePolicySet CI gate + diffPolicySets PR review with Markdown rendering) ✅ (v0.5.0)
• Differential privacy for sensitive trace data
• traceshield CLI for audit investigation (status / traces / violations / verify, with lossless full export) ✅ (v0.3.0)
• Multi-agent attribution graph visualization (agent→action→policy Mermaid/DOT rendering) ✅ (v0.4.0)
• MCP configuration scanner (scan CLI: poisoning phrases, hidden Unicode, dangerous permission combos; --json output) ✅ (v0.5.0)

---

License

Apache 2.0 © cdzzy