auditrail

dsh-audit-trail

Security auditing & session forensics for DeepSeek Harness (dsh).

A dsh bundle (plugin) that records every tool-invocation across the harness session stream and the tool pipeline, flags high-risk operations, persists a redacted, hash-chained audit trail to SQLite, and gives you query, export, policy, and plain-text replay tools — plus a standalone CLI that works on the same database without starting the harness.

Fills a gap: the dsh ecosystem has observability plugins for *performance*

(OTel / Prometheus). Nobody was doing a *security* audit trail — complete

tool-invocation-chain recording with sensitive-operation marking, privacy

masking, query/export, and text-terminal replay. That is what this bundle is.

Table of contents

• What it does
• How it works
• Install & integrate with dsh
• Configuration
• Model-facing tools
• CLI
• Replay
• Compliance export format
• Sensitive-operation rules
• Privacy & redaction
• SQLite schema
• Project layout
• Development
• License

What it does

1. Complete audit chain recording — subscribes to the append-only

session/event stream and the live tool pipeline (tools/result, tools/change) and records, for every event: *who* (session/actor), *when* (timestamp + sequence), *which command* (tool name + masked argument digest), *which files* were touched, *which outbound network destinations* were targeted, *result status*, and *duration*.

1. Sensitive-operation marking — a configurable rule table detects

high-risk patterns (rm -rf, curl | sh, key/secret material, destructive git/db operations, outbound exfil-style requests, privilege escalation, …) and attaches severity + rule tags to the affected records.

1. SQLite (WAL) persistence with privacy — all stored content is masked

and truncated by default; nothing raw is persisted unless you relax the redaction config. An append-only hash chain ties each row to the previous one, so tampering is detectable with auditrail chain verify.

1. Query & export — filter records by time window, session, tool, minimum

severity, sensitive-rule tag, and kind; export JSON reports, Markdown reports, or the fixed-format compliance JSONL (with optional hash chain).

1. Session replay — render the audit trail as a plain-text terminal

timeline and slow-play it with pause / step / seek / speed controls. No browser involved.

1. Compliance output — a versioned, fixed-format JSONL (`schema:

dsh-audit-trail/compliance/1`) that third parties can validate with the bundled verifier or their own tooling.

1. Tool chain — four model-facing tools (audit_query, audit_export,

audit_playback, audit_policy) plus a standalone CLI (auditrail).

How it works

 ┌────────────── dsh harness ──────────────┐
 │ session/event  (append-only durable log) │
 │ tools/result   (live tool dispatch)      │
 │ tools/change   (registry changes)        │
 └──────────────┬──────────────────────────-┘
                │  Recorder (contained, never throws)
                ▼
        Normalize → RuleEngine (flag) → Redact/mask/truncate
                │
                ▼
        AuditStore (SQLite, WAL, hash chain, tags)
                │
        ┌───────┴───────────┐
        ▼                   ▼
   audit_query / export   auditrail CLI
   /playback / policy      (same database)

Record kinds

audit_query --chains merges tool_call + tool_result + tool_dispatch (correlated by callId / session+turn+step) into one invocation chain per tool call — a single row with status, duration, files, network, severity, and flags.

Ordering & determinism

The recorder ingests synchronously in arrival order and the store assigns a monotonic AUTOINCREMENT id, so identical input streams produce byte-identical trails (verified by a dedicated determinism test). Within a session the durable event stream is already ordered; cross-source ordering (session log vs. live tool pipeline) is the harness's emission order, and the query layer re-joins the two sources deterministically by correlation keys.

Install & integrate with dsh

The bundle follows the official dsh bundle spec:

• package.json declares dsh: { bundle: { patch: "./cordis.patch.yml" } }
• cordis.patch.yml mounts the plugin row
• the entry module exports name, inject, and apply(ctx, config)

Local development bundle (link)

# from a dsh profile directory (a profile's package.json has "dsh": {"profile": {...}})
dsh plugin --profile <name> add /path/to/dsh-plugin/auditrail
dsh --profile <name>

dsh plugin add links the package into the profile's dependencies and appends it to dsh.profile.bundles, which activates the cordis.patch.yml layer.

From a tarball / npm

npm pack            # produces dsh-audit-trail-0.1.0.tgz
dsh plugin --profile <name> add ./dsh-audit-trail-0.1.0.tgz

On boot the patch layer inserts one row:

- insert:
  - id: audit-trail
    name: 'dsh-audit-trail'

You normally need no configuration — every field defaults in code. To tune a single profile, override that row (id: audit-trail) from the profile's own cordis.patch.yml (a patch replaces the whole config block — restate every field you keep).

Requirements

• Node.js >= 22.13 (uses the built-in node:sqlite, no native deps).
• A harness that emits session/event and tools/* events (everything in the

current @deepseek-ai/dsh-* set does).

Configuration

All fields optional. Defaults shown.

interface AuditConfig {
  storage: {
    /** null => <dshHome>/audit-trail/audit.sqlite
     *  dshHome = $DSH_HOME || ~/.dsh; AUDITRAIL_DB overrides for the CLI */
    path: string | null;
  };
  redact: {
    /** Mask known secret patterns before storing (default true). */
    maskSecrets: boolean;
    /** Tool-argument digest cap in chars.            */ truncateArgs: number;   // 512
    /** Summary cap in chars.                         */ truncateSummary: number; // 240
    /** Detail JSON cap in chars.                     */ truncateDetail: number;  // 4096
    /** Max file paths captured per record.           */ maxFiles: number;        // 16
    /** Max outbound destinations captured per record.*/ maxNetwork: number;      // 16
    /** Extra secret regex patterns (regex source).   */ extraSecretPatterns: string[];
  };
  rules: {
    /** Built-in rule ids to disable, e.g. ["net:plaintext-http"]. */
    disabledIds: string[];
    /** Operator rules added to (not replacing) the default table. */
    custom: Array<{
      id: string; severity: 'info'|'low'|'medium'|'high'|'critical';
      pattern: string; scope: 'args'|'result'|'files'|'network'|'all'|'tool';
      flags?: string; tool?: string[]; description?: string;
    }>;
  };
  capture: {
    chunks: boolean;        // false — record assistant_chunk per token?
    turnEvents: boolean;    // true
    stepEvents: boolean;    // true
    toolDispatch: boolean;  // true — record live tool_dispatch rows
    toolRegistered: boolean;// true — record tools/change deltas
  };
}

Example (cordis.patch.yml override):

- insert:
  - id: audit-trail
    name: 'dsh-audit-trail'
    config:
      storage:
        path: '/srv/audit/audit.sqlite'
      redact:
        truncateArgs: 256
        extraSecretPatterns:
          - '\\bCUSTOM_SECRET_[A-Z0-9]{20,}\\b'
      rules:
        disabledIds:
          - 'net:plaintext-http'
        custom:
          - id: 'my:purge'
            severity: 'critical'
            pattern: '\\bpurgelogs\\b'
            scope: 'args'
      capture:
        chunks: false

Model-facing tools

All four are registered on ctx.tools when the plugin loads.

audit_query

Query the stored trail.

• Parameters: session_id, tool_name, min_severity

(info|low|medium|high|critical), flag (rule tag, e.g. shell:rm-rf), kind, from, to (ISO date or epoch ms), limit (≤ 10000), chains (merge into invocation chains), format (json | markdown).

• Returns: { count, total?, format, records | chains | text }

(privacy-redacted; total is present on the raw-record path).

audit_export

Export filtered records.

• Parameters: format (json | markdown | jsonl), optional path (writes

the file), the query filters above, hash_chain (jsonl only), chains.

• Returns: { format, count, path?, bytes?, hash_chain, content? }.

audit_policy

Inspect / change the sensitive-rule table at runtime.

• action: list returns every rule with its enabled state.
• action: show|enable|disable on a rule_id.
• action: add with id, pattern, severity, scope, description.
• Runtime-only: persist changes via the plugin config.

audit_playback

Render the trail as a plain-text timeline (one line per event: timecode, id, kind, tool, severity, flags, redacted summary, duration).

• Parameters: query filters + limit, cap (max lines), chains (collapse to

invocation-chain lines).

• Returns: { count, totalLines, truncated, text }. For interactive

pause/step/speed replay use the auditrail playback CLI.

CLI

auditrail reads the same SQLite database the plugin writes to, so you can operate on a live trail without starting the harness.

auditrail help
auditrail stats [--db P]
auditrail query [--db P] [--from D] [--to D] [--session S] [--tool T]
                [--severity LVL] [--flag TAG] [--kind K] [--limit N] [--offset N]
                [--order asc|desc] [--sort id|time] [--json|--markdown] [--chains]
auditrail export --format json|markdown|jsonl [--out PATH] [--hash-chain] [--chains] [filters]
auditrail playback [--session S] [--speed N] [--interactive] [--cap N] [--colors] [--chains]
auditrail policy list | show <id> | enable <id> | disable <id> | add --id X --pattern RE [--severity S] [--scope ARG]
auditrail chain verify [--db P]
auditrail verify-compliant --file PATH

Database resolution: --db P → $AUDITRAIL_DB → <dshHome>/audit-trail/audit.sqlite. (--db :memory: opens an in-memory store.)

Note: auditrail policy mutations are runtime-only for that process —

every CLI invocation is a fresh process, so a rule added by one command is

gone by the next. Toggle/add persistent rules through the dsh plugin's

audit_policy tool (long-lived process) or via the plugin configuration.

Examples:

auditrail query --session sess-42 --min-severity high --markdown
auditrail export --format jsonl --hash-chain --out trail.jsonl --flag shell:rm-rf
auditrail verify-compliant --file trail.jsonl
auditrail playback --session sess-42 --interactive --speed 2 --colors
auditrail chain verify

Replay

renderTimeline() produces a deterministic plain-text line per event:

09:00:05.000  #000002  user_message     -           [INFO]   fetch the deployment script and run it
09:00:10.000  #000003  tool_call        bash        [CRITICAL] shell:pipe-to-shell  curl -sSL ... | sh
09:00:15.000  #000004  tool_result      -           [INFO]   ok in 5000ms

PlaybackController slow-plays the lines with pause / step / seek / speed; runInteractive() binds it to a raw TTY. Keys (interactive):

space  pause / resume      s  step one line       + / -  speed up / down
g      jump to start        q  (or Ctrl-C) quit

Non-TTY (--interactive omitted, or piped) renders the whole timeline at once.

Compliance export format

Fixed, versioned, line-oriented JSON:

{"schema":"dsh-audit-trail/compliance/1","generatedAt":1750000000000,"count":2,"hashChain":true}
{"recordId":1,"prevHash":null,"payload":{"id":1,"sessionId":"sess-42","ts":1750000000000,"kind":"tool_call","turn":1,"step":1,"toolName":"bash","callId":"call-1","argsDigest":"{\"command\":\"curl ...\"}","status":"pending","durationMs":null,"severity":"critical","flags":["shell:pipe-to-shell"],"filesRead":[],"filesWritten":[],"network":["https://..."],"actor":null,"sourceType":"tool/call","sourceSeq":1,"summary":"bash"},"hashSelf":"a1b2..."}

• Line 1 is a header (schema, generatedAt, count, hashChain).
• Each data line is a single JSON object; the payload uses one fixed field set

(see compliancePayload in src/query.ts).

• With hashChain: true, hashSelf is `sha256(prevHash + "\n" + canonical

line + "\n") and prevHash echoes the previous line's hashSelf, forming a chain. auditrail verify-compliant and verifyComplianceJsonl()` validate it (and will report any tampered or reordered line).

Sensitive-operation rules

Built-in table (rules can be disabled / extended; each has a dedicated test in test/rules.test.ts):

Matched rule ids are stored as tags on the record (and in the audit_tags table), the record severity becomes the highest matched severity, and both can be queried (--flag, --severity / min_severity).

Privacy & redaction

• Only redacted content is persisted by default: argument digests are

masked (private keys, bearer/basic tokens, key=value secrets, long high-entropy runs) and truncated; summaries and details are capped.

• digestArgs also understands structure: an object value whose key looks like

a secret (password, token, api_key, authorization, …) is replaced entirely while its key (a label) is kept.

• The audit trail itself records *that* sensitive operations happened (the

forensic value); it does not store their secret values.

• Disable masking with redact.maskSecrets: false only if you fully trust the

store location — this is not recommended.

SQLite schema

One store, a handful of tables (WAL journal, synchronous = NORMAL):

audit_meta     key/value metadata (schema_version)
audit_events   the append-only trail
   id, session_id, ts, kind, turn, step, tool_name, call_id, args_digest,
   status, duration_ms, severity, severity_rank, summary, detail,
   files_read, files_written, network, actor, source_type, source_seq,
   hash_prev, hash_self, created_at
audit_tags     (event_id, tag) — sensitive-rule tags, indexed

Indexes cover ts, session_id, tool_name, severity_rank, kind, tag. chain verify walks rows by id and recomputes every hash.

Project layout

auditrail/
  package.json        dsh bundle manifest (dsh.bundle.patch) + scripts
  cordis.patch.yml    bundle patch layer mounting the plugin
  tsconfig.json       TypeScript → lib/ (NodeNext ESM)
  bin/auditrail.mjs   CLI launcher (calls lib/cli.js)
  src/
    index.ts          bundle entry: name / inject / apply + programmatic exports
    config.ts         config types, defaults, tolerant normalization
    types.ts          domain types (severity, kinds, records, filters)
    rules.ts          sensitive-rule table + deterministic matcher (RuleEngine)
    redact.ts         secret masking, truncation, argument digesting
    scan.ts           heuristic file-path / network extraction + attribution
    store.ts          node:sqlite WAL store, queries, hash chain, stats
    recorder.ts       event subscription + normalization + correlation
    query.ts          chain merging + JSON/Markdown/compliance reports + verify
    playback.ts       plain-text timeline renderer + playback controller + TTY
    tools.ts          audit_query / audit_export / audit_policy / audit_playback
    service.ts        facade shared by tools and CLI
    cli.ts            standalone CLI
  test/               node:test suite (record completeness, flagging, query,
                      export, playback, redaction, plugin contract, CLI)
  examples/           usage.mjs + generator + committed sample artifacts
  README.md / README.zh.md / LICENSE

Development

npm install
npm run build        # tsc → lib/
npm run typecheck    # tsc --noEmit
npm test             # build + node --test test/*.test.ts
node bin/auditrail.mjs help
node examples/generate-examples.mjs    # refresh examples/*.jsonl|*.md
node examples/usage.mjs                # programmatic API demo

License

MIT — see LICENSE.