🛡️ dsh-permission-rules
- 1024 store channel:
npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-permission-rules (counts toward the deepseek1024.com install ranking).
Claude Code-style declarative permission rules for DeepSeek Harness.
Rules decide what is known. A reviewer model decides what is not.
English · 简体中文 · Español · Português · हिन्दी
Compatibility
| Surface | Status |
|---|
| Harness | DeepSeek Harness dsh-v0.1.5-rc.2 (adapted 2026-09-09, full gate chain + profile install smoke): its Session.append still cannot stamp the ignorable marker — verified on the published 0.1.5-rc.2 package, where the third argument is silently dropped and the envelope field survives for stored-log reads only — so the whole 0.1.5-alpha line is pre-checked as unmarked and session-log audit stays disabled by default. The 0.1.3-alpha line keeps the same surface-only append signature. Both lines' log migrations refuse unclassified plugin events even when marked, so strip v1 audit rows before a 0.1.3-alpha host opens the log and v2 audit rows before a 0.1.5-alpha host migrates it (native v3 logs only need repair). |
| Node | `^22.19.0 |
| Platforms | All (host + web settings client) |
| Model | Any (deny/ask reasons surface through tool results) |
What you get
dsh-permission-rules puts an ordered allow / deny / ask rule list in front of every tool call on the tools/pre-execute waterfall — deterministic, instant, auditable, and written by you in plain YAML:
deny blocks the call; the rule's reason becomes the model-visible error.ask rides the official approval seam (mount dsh-auto-review for a second-model answerer, or a human answers; with neither, the harness fails closed).allow (and no-match) strictly delegates via next() — downstream listeners are never short-circuited.
Every hit and every passthrough is audit-logged as a permissionRules/decision session event (log-only — nothing extra is injected into the model context).
- Rich matching — tool-name globs (including
mcp__*), agent-identity selectors (main / subagent / preset:*), argument key/value globs or regexes (with !pattern negation and an absent key dimension), workspace-relative path globs at any nesting depth, when host conditions (env vars, platform), and shell command decomposition (argv: command word, argument tokens, pipeline signature) for token-precise command matching.
- Built-in high-risk baseline — a shipped deny/ask ruleset (destructive commands, privilege escalation, download-and-execute, sensitive paths) enabled by default and appended after user rules so a nearer user rule can override it; toggle with
builtin.enabled.
- Hierarchical rule files — optional
searchUp merges every .dsh/rules.yaml from the session cwd to the filesystem root, nearest first.
- Dry-run rollout —
enforce: false audits what the policy would do while passing every call through.
- Hot reload — Chokidar watch with debounce; a broken edit keeps the previous rules, never crashes. On a WSL host, or for a rule file under
/mnt/<drive>, the watch switches to polling because native change events are unreliable there.
- Fail loud — invalid YAML, unknown actions/fields, bad globs/regexes, backtracking-prone patterns, or more than
maxRules rules fail the load.
Rule syntax
# <project>/.dsh/rules.yaml
rules:
- match: { tools: [bash, pwsh], params: { command: "git push*" }, paths: ["**/secrets/**"] }
action: deny
reason: "No pushes from protected paths"
- match: { tools: [edit, write] }
action: ask
reason: "File writes need confirmation"
- Match dimensions —
tools (globs, incl. mcp__*), agents (main / subagent / preset:<name>; unknown identity never matches — fail closed), params (key/value globs or regexes, !pattern negation, absent key dimension), paths (workspace-relative globs extracted at any nesting depth), when (env var globs/regexes + a closed platform list), and network (domains / ips / ports / schemes — globs, wildcards, CIDRs, port ranges).
- Actions —
allow / deny / ask, evaluated in file order, first match wins.
- Rule metadata —
enabled: false (visible but inert), description, tags; unknown fields fail the load.
- Schema — a JSON Schema ships at docs/rules-format.schema.json (editor completion via
# yaml-language-server: $schema=...); the full vocabulary and a 5-rule security baseline live in docs/rules-format.en.md.
Network policy
A Codex-style process-level network policy: shell subprocess traffic flows through a built-in local HTTP/CONNECT proxy, and every connection is decided by ordered network rules or by three modes mapped onto the official sandbox presets:
-
deny-all — the read-only sandbox preset: block all outbound.
-
whitelist — the workspace-write preset: allow listed targets, unlisted: ask (or deny) for the rest.
-
allow-all — the danger-full-access preset: allow everything.
-
auto (default) — follows the sandbox preset; on hosts without the sandbox-policy service it resolves to autoFallback (allow-all).
-
Matching — match.network with domains / ips / ports / schemes (globs, wildcards, CIDRs, port ranges; numeric YAML ports are accepted). URL-candidate extraction on the tools/pre-execute hot path fires on web-tool arguments and URLs embedded in bash/pwsh command text; loopback targets can short-circuit rules per loopback policy. IPv4-mapped IPv6 literals are normalized to their IPv4 form before matching, and the proxy connects on the addresses the decision was made on — never a second DNS resolution — a connection whose adjudication resolved no address fails closed (502) instead of dialing the name.
-
Upstream chaining — network.upstreamProxy (default off) sends the connections this proxy allows through an upstream proxy: CONNECT asks the upstream for a tunnel (CONNECT host:port) and plain-HTTP requests are forwarded to it in absolute form. A blocked target never reaches the upstream — it still gets this plugin's structured 403. Two cases never chain even when an upstream is configured: a loopback target (a proxy outside this host cannot route its loopback) and any decision produced by an ips-scoped rule (chaining hands the hostname to the upstream, so "the connection lands on an address the rules saw" — issue #21 — would stop holding exactly where the rules cared about the address; those decisions keep dialing the adjudicated address directly), plus a target whose scheme has no usable upstream. The upstream's own hostname is operator configuration, not agent input, and is not adjudicated by these rules. A URL carrying credentials is never emitted raw: warnings, /rules network and the settings snapshot mask the password (http://user:***@host:port). An unreachable upstream, a timeout (10 s), or a non-2xx answer yields 502 — there is deliberately no silent fallback to a direct dial, so a misconfiguration stays visible.
Quick start
# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
# or from npm (published releases)
dsh plugin --profile web add dsh-permission-rules
# 2. restart and verify the row
dsh --profile web --dump-config | grep -A4 'id: permission-rules'
Install & uninstall
- git channel (latest
main): dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main" — the prepare script builds with production dependencies only.
- npm channel (published releases):
dsh plugin --profile web add dsh-permission-rules.
- tarball channel:
pnpm pack in this repo, then dsh plugin --profile web add ./dsh-permission-rules-<version>.tgz.
- uninstall:
dsh plugin --profile web remove dsh-permission-rules.
Configuration
All tunables are Schemastery Config fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need.
| Key | Default | Meaning |
|---|
rulesFile | .dsh/rules.yaml | Rule file location; relative = resolved against the calling session's cwd, absolute = global and validated at mount |
fallbackPath | (none) | Rule file used when per-cwd discovery finds nothing; validated at mount |
badFilePolicy | fail | Bad rule file: fail errors the pending tool call loudly; ignore-with-warning warns and continues empty |
maxRules | 256 | Hard cap on rule count across the effective source chain |
maxCachedWorkspaces | 512 | Hard cap on cached per-workspace rule loads (LRU eviction) |
patternMode | glob | params/paths/when.env pattern flavor: glob or regex (tool names are always globs) |
watch | true | Chokidar watch + reload on change |
watchStabilityThresholdMs | 200 | Reload debounce window (ms) |
language | en | /rules output language: en, zh, es, pt, hi |
caseInsensitivePaths | (win32) | paths patterns and workspace-root comparison ignore ASCII case; true on Windows |
audit | all | Audit granularity: all logs every hit AND passthrough; hits skips passthrough events |
searchUp | false | Walk parent directories from the session cwd and merge every found rule file, nearest first |
maxGlobStars | 2 | Hard cap on unbounded / quantifiers per glob pattern |
Tools & surfaces
| Surface | Kind | Notes |
|---|
tools/pre-execute | listener | First-match allow/deny/ask rules + network URL-candidate extraction |
/rules | command | list · reload · decisions [n] · test <tool> <json> |
permissionRules/decision | event | Log-only audit for every hit and passthrough |
permissionRules/network | event | Proxy-layer audit for blocked connections |
| HTTP/CONNECT proxy | service | Built-in local proxy governing shell subprocess traffic |
| settings page | client | Network-mode editor, rule editor, block counters, recent interceptions with a per-block allow action |
/rules list the active rules, their source files, and any last-reload error
/rules list explicit alias for the bare listing
/rules reload re-read the rule-file chain for this workspace
/rules decisions [n] show the last n permission decisions of this session (default 10)
/rules test <tool> <json> dry-evaluate the rules against a hypothetical call
/rules test also accepts leading flags: --cwd <dir>, --env KEY=VALUE (repeatable), --agent <selector> (repeatable), and --platform <name>. In multi-file chains (e.g. searchUp), every listed rule line is attributed to its own source file.
Permissions & data
- Permissions: declares
files:read, files:watch, files:write, session:append, and network:outbound in its workshop manifest. ask decisions ride the official approval seam — nothing is re-implemented or bypassed.
- Data: rule files are read from disk; no rule data is written. No model calls, no reviewer subagents.
- Session log:
permissionRules/decision is never injected into the model context and is appended with the envelope's ignorable: true marker so any harness build loads the log.
Security boundaries
- Policy, not a kernel.
paths candidates come only from a documented set of argument keys (at any nesting depth, depth-capped), and only workspace-relative paths match.
- No reviewer here. The plugin never spawns subagents or calls models — producing an
ask decision is the end of its work.
- No sandbox changes. OS-level sandbox policy belongs to the sandbox seam, not this plugin.
- Loud misconfiguration. Unknown YAML fields, unknown actions, and bad patterns are rejected at load.
- Backtracking bounds. Glob patterns are capped at
maxGlobStars unbounded star expansions; regex-mode patterns reject nested unbounded quantifiers and quantified overlapping literal alternations.
- Fail-closed dialing. Plain-HTTP forwards and CONNECT tunnels connect only to adjudicated addresses; an allow whose adjudication resolved no address fails closed with 502 instead of dialing the name (issue #23).
Known limitations
- Audit marker on pre-marker and refusing hosts.
permissionRules/decision is appended with ignorable: true; hosts whose Session.append predates the marker (the 0.1.0-rc.1–rc.7 and 0.1.1-rc.1–rc.7 lines) silently drop it, the 0.1.2-rc line ships the alpha.5 surface (no append option writes the marker), the 0.1.2-alpha line refuses plugin events on read even when marked, and the 0.1.3-alpha and 0.1.5-alpha lines keep the same surface-only append signature (verified on the published 0.1.3-alpha.1/0.1.5-alpha.1 packages) — the runtime pre-checks all of these before the first append and disables session-log audit with a one-time warning. Cross-generation migration refuses marked audit rows too: the 0.1.3-alpha v1→v2 gate refuses unknown v1 events, and the 0.1.5-alpha v2→v3 gate refuses every unclassified event (its inventory is frozen to the released v2 vocabulary), so strip v1 rows before a 0.1.3 host opens the log and v2 rows before upgrading to a 0.1.5 host. Native v3 logs accept marked plugin rows, so they only need repair. Set allowUnmarkedAudit: true to opt back in; repair already-written logs with scripts/repair-session-logs.mjs (its strip mode removes audit rows where the marker cannot help).
- Path candidates are heuristic. Only the documented argument keys feed path matching, and workspace-relative matching is ASCII-case-insensitive only when
caseInsensitivePaths is on.
- Globs are a conservative subset. No brace expansion — write two patterns, or use regex mode.
- The regex backtracking guard is structural, not exhaustive. Prefer glob mode for untrusted files.
- The host's own outbound requests do not go through this proxy. The injected proxy environment covers spawned shell children — which is what the injection is for — and any consumer that reads the proxy names at request time. It does not cover the host process's own
fetch-based traffic: the launcher installs undici's global dispatcher from the launch environment before the first plugin mounts, that dispatcher routes by its policy rather than by the environment, and Node samples the proxy environment at start — so a plugin mounting later cannot redirect it. Consequences: provider endpoints do not need an allow rule, and network.injectEnv: false does not take the host process out of anything. Measured 2026-09-10 on Node 22; reproduce with .
Collaborating with dsh-auto-review
dsh-permission-rules produces ask; dsh-auto-review answers on the approval/request waterfall with a read-only second-model verdict (or delegates to humans). Mount both for the full closed loop.- Integration-tested:
permissionRules/decision → approval/asked → autoReview/verdict → approval/decided, with the reviewer replaced by a scripted mock.
- The
never approval policy and every fail-closed guarantee of the official harness stay untouched.
Session log repair
Session logs written before the ignorable marker existed can be refused by newer harness builds (SessionFormatUnsupportedError). The shipped scripts/repair-session-logs.mjs rewrites only the targeted audit rows to carry ignorable: true, frame-preserving, with backups:
node scripts/repair-session-logs.mjs scan [--home DIR] # report foreign rows, change nothing
node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
node scripts/repair-session-logs.mjs strip [--home DIR] [--dry-run]
--home defaults to $DSH_HOME/sessions (or ~/.dsh/sessions). Every generation-addressed log is discovered by its canonical basename — session.jsonl, session.v2.jsonl, session.v3.jsonl, each optionally .zstd-compressed — so pick the mode by generation:
- v3 (
session.v3.jsonl, written natively by the 0.1.5-alpha line) — the read path accepts marked plugin rows, so repair is enough.
- v2 (
session.v2.jsonl, written by the 0.1.3-alpha line) — repair opens it on the host that wrote it, but the 0.1.5-alpha v2→v3 migration refuses every unclassified event even when marked: run strip on v2 logs before upgrading to a 0.1.5-alpha host.
- v1 (
session.jsonl) — the 0.1.3-alpha v1→v2 migration refuses unknown v1 events even when marked: run strip before a 0.1.3-or-later host first opens the log.
Development
pnpm install # node ^22.19 || >=24
pnpm run typecheck # tsc, src + tests
pnpm run lint # eslint, src + tests + scripts
pnpm test # vitest: 24 spec files
pnpm run test:coverage # coverage gate (90/80/90/90)
pnpm run build # tsc declarations + tsdown bundles (lib/)
pnpm run pack:check # build + pack (the published artifact)
node scripts/check-readme-sync.mjs # five-language README sync gate (also in CI)
See VERIFICATION.md for the headless end-to-end verification record.
Topics
dsh, dsh-plugin, deepseek-harness, permission, policy, allow-deny-ask, approval, safety, network, network-policy, proxy
Contributors
- @PerryLink — creator and maintainer: rule vocabulary and evaluation, runtime, HMR watch, session-log audit, network policy + proxy, and the five-language docs.
- @22xuan — the detailed report on rc.6 hosts silently dropping the audit event's
ignorable marker (#2) and the upstream harness discussion; the v0.4.1 runtime host-capability detection and the documentation correction drew directly from that analysis.
- @sjh9714 — proposed the shared rule-syntax test-vector corpus (#4, #5), shipped in v0.5.1 as
docs/rule-test-vectors/, and supplied the AST-decomposition boundary cases on the design discussion.
- @weipeng1999 — the AST-based command-decomposition feature proposal (#8) behind the design discussion.
- @alexchenzl — the DSH Directory listing request (#7).
- @zl190 — reported and verified the
0.1.0-rc.7 harness compatibility gap (PR #9).
- @cuohua — reported that the
0.1.1-rc line still drops the ignorable marker even though the version gate covered only 0.1.0 (#11); the widened gate drew directly from that analysis.
PerryLink DSH Plugin Family
This project is one of the 40 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:
| Plugin | One-liner |
|---|
| dsh-auto-review | Second-model auto-review on the approval chain, fail-closed by default |
| dsh-background-agents | Durable background child agents with a Web UI sidebar, messaging and interrupt |
| dsh-budget | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. |
| dsh-checkpoint-rewind | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
| dsh-claude-move | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
| dsh-click | Cross-platform native desktop control for DeepSeek Harness — Windows first. |
| dsh-composer-history | Terminal-style input history for the web composer: arrows, Ctrl+R search |
| dsh-data-quality | Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here) |
| dsh-defend | Prompt-injection, jailbreak, and secret-leak defense for DeepSeek Harness. |
| dsh-doublecheck | Engineering-discipline guard: requirements grill, test gates, adversary review |
| dsh-draw | Unified static-image generation routing for DeepSeek Harness. |
Install from the DSH Desktop Market
All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.
License
Apache License 2.0 © 2026 dsh-permission-rules contributors
