TraceSig

Sigma-style detection rules for AI agent tool-call traces. An open rule format, a small reference engine, and rule packs for Claude Code and agent-policy-gateway, so a detection written once runs on any agent.

pip install "git+https://github.com/howardhsieh/tracesig@v0.2.1"   # PyPI release coming soon
tracesig scan ~/.claude/projects/      # hunt through your own Claude Code sessions

Why

SIEM detection engineering has Sigma: one open YAML format for detection rules and a shared rule library. AI agents have nothing equivalent. Every agent framework logs tool calls differently, there is no common rule language, and most products that watch agent behavior are closed.

TraceSig is the open layer:

1. A trace schema: one JSONL shape for any agent's tool calls, with provenance labels (web, untrusted, secret, pii, mcp, …).
2. A rule format and engine: Sigma-style YAML, five detection primitives, one dependency (PyYAML).
3. Rule packs and normalizers: 23 rules across three packs; Claude Code transcripts, Claude Code OpenTelemetry and agent-policy-gateway audit exports are read directly.

Detections key on provenance and behavior, not content filtering: "a secret was read, then data left the machine" survives paraphrase and novel payloads that keyword filters miss.

Quick start

pip install "git+https://github.com/howardhsieh/tracesig@v0.2.1"

# Claude Code: transcripts live in ~/.claude/projects/<project>/<session>.jsonl
tracesig scan ~/.claude/projects/
tracesig scan ~/.claude/projects/ --min-severity high --json > findings.json

# agent-policy-gateway: export the audit log, then scan it
apg audit export audit.jsonl --format tracesig -o apg-trace.jsonl
tracesig scan apg-trace.jsonl

# Any agent: write your tool calls in the TraceSig schema
tracesig scan trace.jsonl --rules my-rules/ --fail-on critical   # exit 2 in CI

The input format is detected per file, and TraceSig picks the rule pack that fits it. Choose packs yourself with --pack core|claude-code|apg|all, add your own rules with --rules DIR, force a format with --from.

Exit codes: 0 ok, 1 bad input or rules, 2 a finding at or above --fail-on.

How a rule looks

id: TS-EXF-001
title: Untrusted web content followed by outbound email
severity: critical
category: exfiltration
detection:
  taint:
    source_label: web
    sink|matches: "(send_email|send_message|webhook|http_post)"

taint is the core agent-security primitive: an event whose data carries a source label (web, pii, secret), then a sink tool later in the same session. That is the indirect prompt-injection exfiltration chain, caught by data flow rather than keywords.

Conditions use field, field|contains or field|matches (regex) on tool, args, labels, result_preview, agent, session_id, or any original field as raw.<name>. Full grammar: docs/rule-spec.md.

Rule packs

core (12 rules): generic tool names, any agent.

claude-code (7 rules): Claude Code tool names, with Bash commands classified as Bash(network), Bash(publish), Bash(destructive) or Bash(install).

apg (4 rules): use agent-policy-gateway's own verdicts and taint labels.

Example traces under examples/ exercise the packs, and CI checks that the risky ones fire and the benign ones stay quiet.

Trace schema

One event per tool call, one JSON object per line:

{"session_id":"s1","seq":0,"tool":"web_fetch","args":"https://…","labels":["web"],"result_preview":"…"}

labels carry data provenance: the signal taint rules run on. Spec: docs/trace-schema.md. Normalizers and their label rules: docs/normalizers.md.

How it compares

Content rules catch the payload in one message; TraceSig catches what the agent did next. Most agent detection today matches text inside a single event. TraceSig's rules are about behavior across calls: where data came from, what the agent did after, and whether a required approval came first.

They combine well: run ATR's content rules on each message and TraceSig's behavior rules on the session. What TraceSig adds:

• Provenance as a first-class field. Normalizers label what each call returned (web, untrusted, secret, mcp), so a rule says "secret read, then a network call" instead of guessing from command text.
• Hunt without deploying anything. tracesig scan ~/.claude/projects/ reads the transcripts Claude Code already keeps; no proxy, agent or account.
• Rules that know the gateway's verdict. The apg pack reads agent-policy-gateway's allow and deny decisions, so it can flag a blocked exfiltration followed by an allowed one.

Where this fits

TraceSig is the detect layer of an open agent-security stack:

Roadmap

• More normalizers: OpenAI Agents SDK, LangGraph, MCP gateway logs
• Cross-session correlation
• An ATR adapter, so content rules and behavior rules run in one pass
• SARIF and Sigma export for SIEM pipelines
• A shared tool-category taxonomy so one rule covers many agents
• A community rule repository, the way SigmaHQ hosts SIEM rules

Contributions welcome: a rule is one YAML file plus an example trace. See CONTRIBUTING.md.

License

Apache-2.0. Built by Howard Hsieh.