okaditya84 / dsh-agent-sentinel

dsh-agent-sentinel

English | 中文

dsh-agent-sentinel is a dsh-plugin for DeepSeek Harness that adds four independent, best-effort safety layers to an agent loop: secret redaction on tool output, a pattern-based denylist for destructive shell commands, indirect prompt-injection scanning on file reads and web fetches, and syntax verification on file writes. Every finding is written to an append-only JSONL audit log.

It hooks into the real Cordis extension points ctx.tools.guard() and the tools/post-execute waterfall, the same points the official @deepseek-ai/dsh-repeat-tool-reminder guard plugin uses.

What this is, honestly

Each layer below is a heuristic, not a guarantee. Read this section before enabling strictMode or relying on this plugin as your only safety net.

• Secret redaction — regex + Shannon-entropy scanning. Catches known secret shapes (OpenAI/DeepSeek/GitHub/AWS/Stripe/Anthropic keys, private key blocks, JWTs, DB connection strings) and generic high-entropy KEY=...-style assignments. It cannot catch a secret format it has no pattern for, and it only inspects content (text) blocks — a PostToolDecision that carries a bare value instead of content is logged (value_result_not_scanned) but not scanned, since safely rewriting value requires framework-level revalidation this plugin doesn't perform.
• Command guard — a fixed regex denylist for known-destructive shapes (rm -rf /, find / -delete, disk wipes, curl | bash, chmod -R 777 /, ...). This is defense-in-depth, not a sandbox. It does not parse shell grammar, so variable indirection (T=/; rm -rf $T), command substitution, or a tool this rule set doesn't yet name can bypass it. Pair it with real containment (@deepseek-ai/dsh-sandbox-*, @deepseek-ai/dsh-user-approval) for actual guarantees.
• Prompt-injection scanner — regex matching for common override/jailbreak phrasing and zero-width Unicode. Each pattern carries a hand-assigned severity weight, not a calibrated probability from any measured detection rate.
• Syntax verifier — a real parse for JS/TS (via the TypeScript compiler's transpileModule, which correctly understands ES module import/export syntax) and JSON (JSON.parse); for Python it shells out to a real python3/python interpreter when one is on PATH, falling back to a string/comment-aware bracket-balance heuristic otherwise.

Quickstart

pnpm add dsh-agent-sentinel

Mount via a Cordis composition file (cordis.yml)

- id: sentinel
  name: 'dsh-agent-sentinel'
  config:
    redactSecrets: true
    blockDangerousCommands: true
    detectPromptInjections: true
    verifyCodeSyntax: true
    auditLogPath: '.sentinel-audit.jsonl'
    strictMode: false

Programmatic mount

import { Context } from '@deepseek-ai/cordis'
import * as sentinel from 'dsh-agent-sentinel'

const ctx = new Context()

ctx.plugin(sentinel, {
  redactSecrets: true,
  blockDangerousCommands: true,
  auditLogPath: '.sentinel-audit.jsonl',
})

const summary = ctx.sentinel.getThreatSummary()
console.log(`Total security events: ${summary.totalEvents}`)

Configuration reference

Option	Type	Default	Description
redactSecrets	boolean	true	Redact secrets/credentials found in tool output content blocks.
customSecretPatterns	{ name, pattern }[]	[]	Additional secret regex patterns.
blockDangerousCommands	boolean	true	Veto shell calls matching the built-in destructive-command denylist.
customCommandRules	{ id, pattern, reason, severity? }[]	[]	Additional shell command denylist rules.
detectPromptInjections	boolean	true	Scan file-read/fetch output for prompt-injection patterns.
verifyCodeSyntax	boolean	true	Verify syntax of file writes/edits (JS, TS, JSON, Python).
auditLogPath	string	.sentinel-audit.jsonl	Path for the append-only JSONL audit log.
strictMode	boolean	false	Block (rather than just log) a write that introduces a syntax error.
maxAuditHistory	number	500	In-memory audit ring-buffer size (independent of the on-disk log, which is never truncated by this plugin).

A note on this package's dependency setup

As of this writing, @deepseek-ai/dsh-tools (and every sibling @deepseek-ai/dsh-* package checked) depends transitively on @deepseek-ai/dsh-type-meta, which 404s on the public npm registry — the whole @deepseek-ai/dsh-* family is not independently installable outside the deepseek-harness monorepo's own workspace right now. That includes even declaring it as an optional peer dependency: pnpm's peer-resolution walk still tries to resolve dsh-tools's own manifest and fails the same way, breaking pnpm install for every consumer. So dsh-tools is deliberately not listed in package.json at all — this plugin relies on it purely at runtime (it is always present in a real harness process; nothing else provides ctx.tools) and mirrors the small slice of its published type surface it needs locally in src/vendor/dsh-tools-types.ts, with each type's exact source (package, version, file) documented in that file's header. If @deepseek-ai/dsh-type-meta becomes installable, that file can be replaced with real imports without changing any call site — every mirrored name matches the real export name.

Running tests

pnpm test            # vitest run
pnpm test:coverage   # vitest run --coverage
pnpm typecheck       # tsc --noEmit, against the real installed @deepseek-ai/cordis types

License

MIT © Aditya Jethani