dsh-plugin-gate

Usage

Ask the agent to scan a plugin before installing it (the plugin also injects prompt guidance that tells the agent to do this automatically):

gate_scan target: "npm:dsh-plugin-some-package"
gate_scan target: "npm:dsh-plugin-some-package@1.2.3"   # pinned version
gate_scan target: "./downloaded-plugin"                 # local directory

Result shape:

{
  "verdict": "BLOCK" | "WARN" | "PASS",
  "score": 254,
  "summary": { "high": 0, "medium": 1, "low": 3, "categories": { "network": 4 } },
  "network": { "hosts": [...], "unallowlisted": [...], "readAndSendFiles": [...] },
  "hits": [{ "rule": "fetch_call", "category": "network", "severity": "medium",
             "file": "lib/index.js", "line": 12, "evidence": "...", "hint": "..." }],
  "recommendations": [...]
}

Verdict semantics

• BLOCK — at least one high-severity signature. Do not install until the maintainer ships a clean rebuild you can scan again.
• WARN — medium-severity patterns that need manual review (network I/O, home-path writes, base64 blobs). Inspect every hit in context.
• PASS — no risky signatures. Heuristic only — keep normal caution with unknown maintainers.

Context-aware rules: exec()/execSync() hits are downgraded when the file does not import child_process (typical RegExp#exec false positive); code-context rules (exec, eval, curl|sh, PowerShell…) are downgraded to low when found in comments or documentation (examples, not behavior) — while secrets and webhooks stay flagged even in comments. Dependencies installed from git/http/file URLs are flagged as risky_dependency, and >4000-char minified lines as minified_line (low).

Configuration

Key	Default	Meaning
maxFiles	1000	hard cap on scanned files per directory walk
maxFileBytes	2 MiB	per-file text cap
includeNodeModules	false	descend into node_modules
maxTarballBytes	32 MiB	npm tarball download cap
allowlistHosts	[]	hosts never listed as unallowlisted
promptSection	true	inject agent guidance
sectionOrder	5	prompt section order