Skip to main content

How to use dsh-permission-rules

Place a YAML rule gate before DSH tool calls, generating allow/deny/ask decisions based on tool name/parameters/path/agent/network target; control local agent outbound traffic with full read-only audit.

This article is auto-derived from indexed fields (wiki / faq / compatibility_json), not freshly AI-generated.

This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

dsh-permission-rules

— source: plugin_wiki.wiki_content

Install & verify

dsh plugin --profile web add dsh-permission-rules

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

  • 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.
  • 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.

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

What else needs to be done after installation?

After installation, you must restart the profile for the id: permission-rules line to attach; for rules to actually take effect, place a .rules.yaml in the working directory (or configure a global fallback file via fallbackPath). Having no rules file is equivalent to "allow all".

What's the relationship with dsh-auto-review? Do they need to be installed together?

The two are complementary in function: this plugin produces ask (yields the approval channel), and dsh-auto-review hangs a second model on the approval channel for ruling; when only this plugin is installed, ask goes to human approval or host default behavior. Only when both plugins are installed do they form the closed loop of "rule filtering + model review".

What if I want to first observe whether the new rules will cause false positives?

In cordis.yml, temporarily set this plugin's enforce to false to enter dry-run mode: deny/ask hits only write audit logs with dryRun markers, don't block calls, and all events continue flowing to downstream.

What happens if I write incorrect YAML?

Default badFilePolicy: 'fail' — the current waiting tool call directly errors; in HMR hot-reload scenarios, the last successfully loaded rules are retained, never crash; if you want to be more tolerant, change to ignore-with-warning which will log warnings and continue with empty rules.

How does the network policy work by default?

Default network.enabled: true and network.mode: 'auto', which automatically follows official sandbox presets (readonly→full ban, workspace write→whitelist, danger-full-access→full allow); when host doesn't connect to sandbox service, falls back to autoFallback (default allow-all), can manually change to deny-all/whitelist/allow-all to lock it in.

Why can't I see events in the audit log after installation?

Host versions 0.1.0-rc.6 and before will drop the ignorable marker, causing audit events to not carry the marker, breaking session recovery on new hosts; the plugin will proactively degrade to not open session log audit and print a one-time warning; if you really want to keep audit on old host, set allowUnmarkedAudit: true, but old logs may need scripts/repair-session-logs.mjs to fix.

How to see the currently active rules and recent decisions?

Run /rules in the session to list sources and hit lines, /rules reload to forcibly reload the current workspace's rule chain, /rules decisions [n] to see the last n session decisions (default 10), /rules test <tool> <json> can also dry-run a rule comparison once.

How to uninstall?

One line dsh plugin --profile web remove dsh-permission-rules, transactional uninstall, doesn't affect other plugins or session state outside the profile.

— source: plugin_wiki.faq_json

Compatibility

  • DSH: 0.1.0-rc.8+（peerDependencies 全家桶锁 >=0.1.0-rc.8 <0.2.0，dshWorkshop.compatibility.dshVersions 列出 rc.5/rc.7/rc.8）
  • Node: ^22.19.0 || >=24.0.0（package.json#engines.node）

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule