jkrandom-sudo/dsh-plugin-audit
40Last commit Aug 14, 2026
dsh-plugin-audit DSH plugin
dsh-plugin-audit is a DSH plugin that provides static auditing of third-party plugins and a runtime sentinel that intercepts tool calls. The static scanner generates a permission profile card showing which files, processes, hosts, and credentials the plugin touches. The sentinel monitors the harness's pre-execute waterfall and asks for user approval when a tool call accesses credential paths or egresses to unknown hosts.
How to install the dsh-plugin-audit DSH plugin
dsh plugin --profile web add dsh-plugin-auditCopying does not run this command. Review the repository and version before installing the dsh-plugin-audit DSH plugin.
dsh-plugin-audit DSH plugin data source
dsh-plugin-audit DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-plugin-audit DSH plugin can do
- Static audit of any plugin directory, scanning source, package.json, and cordis.patch.yml to produce a permission profile card with risk level and findings.
- Runtime sentinel on the tools/pre-execute waterfall that returns an 'ask' verdict for credential access, shell egress to unknown hosts, or writes to home-directory dotfiles.
- Read-only operation by contract; every audit report includes writesPerformed: false, with an optional invariant companion to enforce it.
- Configurable allowedHosts list for shell egress, supporting exact matches and wildcard suffix rules.
- No network calls or telemetry; all hosts in reports are extracted from source text, never contacted.
- Supports both Markdown and JSON output formats for the audit summary.
Where the dsh-plugin-audit DSH plugin fits
- Audit a third-party plugin before installing it to understand what resources it accesses.
- Monitor running tool calls to prevent accidental credential exposure or data exfiltration.
- Review your own plugin development to check for unintended permission usage.
- Enforce security policies by requiring approval for any egress to unapproved hosts.
- Integrate with automated workflows by using the JSON audit output for CI checks.
Who the dsh-plugin-audit DSH plugin is for
- DSH users who install third-party plugins and want to evaluate their security posture.
- Plugin developers who need to understand the permission profile of their code.
- Security-conscious operators managing DSH environments with multiple plugins.
dsh-plugin-audit DSH plugin limitations
- Scanner works on source text, not an AST; strings and comments can trigger false positives.
- Does not follow symlink targets; the walker caps at 400 files / 256 KB per file and skips node_modules, .git, lib, and dist.
- Sentinel only works on DSH profiles that provide the tools/pre-execute waterfall; requires a specific DSH mainline snapshot (2026-08-14) and Node.js ^22.19.0 || >=24.0.0.
- The plugin is an audit aid, not an antivirus; a clean report means 'no evidence found by these rules', not 'safe'.
- Build-output-only packages (only dist/lib) always score at least NOTICE because there is nothing to scan.
dsh-plugin-audit DSH plugin: from the repository README
Quoted from the jkrandom-sudo/dsh-plugin-audit README, the upstream source of the dsh-plugin-audit DSH plugin. Copyright remains with the original authors.
**Know what a DSH plugin can do before you let it run.** `dsh-plugin-audit` profiles third-party plugins statically — which files, processes, hosts, env vars and credential paths their code touches, with file/line evidence — and arms a runtime sentinel that asks for your approval when any tool call reaches for credentials or moves data to unknown hosts. ## What it does **1. Static audit — the `plugin_audit` tool.** Point it at any plugin directory; it scans the source, `package.json` and `cordis.patch.yml`, then returns a permission profile card: ```markdown ## Plugin audit: fixture-suspicious-plugin **Risk: REVIEW** — REVIEW — human review recommended before installing > 1 files scanned; risk=review; 10 findings (4 review, 4 notice, 2 info) ### Permission profile | Surface | Observed | |---|---| | Filesystem read | **yes** | | Filesystem write | **yes** | | Child processes | **yes** | | Network | **yes** | | Outbound hosts | `evil.example.com`, `exfil.badhost.io`, `telemetry.example.net` | | Env variables | `GITHUB_TOKEN`, `HOME` | | Credential-looking env | `GITHUB_TOKEN` | | Credential paths | `.npmrc`, `.ssh` | | Dynamic code execution | **yes** | | Injected services | `
Read the full READMERepository license: MIT
dsh-plugin-audit DSH plugin questions
How do I install dsh-plugin-audit?
Run `dsh plugin --profile web add dsh-plugin-audit` in your DSH environment. This registers the package and applies the cordis.patch.yml configuration including the sentinel. After installation, restart the profile to activate the plugin.
How can I audit a plugin with this tool?
You can ask the agent to 'Audit the plugin at <path>' or call the plugin_audit tool directly with a JSON object like `{ "path": "/absolute/path/to/plugin", "format": "markdown" }`. The tool returns a Markdown permission profile card and a JSON summary that includes the risk level, file count, and findings.
What does the runtime sentinel do?
The sentinel hooks into the harness's `tools/pre-execute` waterfall. Whenever a tool call is about to execute, it checks against risk rules: credential path access, shell egress to unknown hosts, or writes to home-directory dotfiles. If a match is found, it returns an `ask` verdict, prompting the host's approval prompt. If no approval channel exists, the call is denied silently.
How do I configure allowed hosts for the sentinel?
Edit the plugin's row in your profile's `cordis.patch.yml` under the `config` section. Add the `allowedHosts` list with hosts like `github.com` or `*.deepseek.com`. The sentinel will automatically allow shell egress to those hosts without prompting for confirmation.
How do I uninstall dsh-plugin-audit?
Run `dsh plugin --profile web remove dsh-plugin-audit`. This removes the dependency from the profile's package.json and deletes the bundle row. After that, restart the profile. The plugin writes no persistent data outside the profile's own dependency metadata, so no further cleanup is needed.