dsh-plugin-inspector 0.5.0 → 0.6.0

package/README.md

@@ -84,8 +84,8 @@ Findings are tiered by how much you should trust them:
 intent is not. Every Tier B check has a one-line bypass, and the tool says so per finding rather
 than implying a completeness it does not have. What it does guarantee is that it never runs the
 code it analyses — asserted from outside the unit suite by a CI canary whose fixture writes
-sentinel files from `preinstall`, `postinstall`, `prepare`, `!!js` config and module top level. Any
-sentinel on disk after a full analysis is a release blocker.
+sentinel files from `preinstall`, `postinstall`, `prepare`, `!!js` config, `!!js` disabled, and
+module top level. Any sentinel on disk after a full analysis is a release blocker.
 
 [What is not statically decidable →](https://charlotten7.github.io/dsh-plugin-inspector/ceiling.html) ·
 [What it reports on the real ecosystem →](https://charlotten7.github.io/dsh-plugin-inspector/ecosystem.html)
@@ -100,8 +100,13 @@ pnpm run test:coverage
 pnpm run test:e2e
 ```
 
-Severity calibration is pinned against a corpus of published packages, so a change that starts
-firing on ordinary code fails CI rather than shipping.
+Severity calibration is pinned against a corpus of forty published packages, in
+`tests/ecosystem-baseline.json`. **The sweep is not part of CI** — every other workflow here runs
+without a network, which is what lets the unit suite claim that analysing a package touches nothing
+outside the process — so it runs as a weekly cron and on request, and a change that starts firing
+on ordinary code does not fail the pull request that makes it. What catches it is the release: the
+baseline records the build that measured it and a unit test fails unless that matches the version
+in `package.json`, so a version bump is not finished until the sweep has been re-run against it.
 
 Design decisions and their rationale live in [ADR.md](ADR.md). Security policy is in
 [SECURITY.md](SECURITY.md).

package/lib/checks/tier-a.js

@@ -123,8 +123,12 @@ function checkDisabledRows(input) {
             // (vendor/loader/src/config/entry.ts). `null`, `0` and `""` therefore
             // leave the row running, and reporting them as a disabled row would be
             // confidently wrong about the one thing Tier A claims to be certain of.
-            // An expression node is an object, so it stays truthy here and is judged
-            // by what it can evaluate to rather than by its own shape.
+            // A `!!js` node is not that case. The loader evaluates the expression
+            // first and coerces its *result*, so `disabled: !!js false` also leaves
+            // the row running — which this tool cannot know without running the
+            // expression, and running it is the one thing it may never do. An
+            // expression is therefore read as what it could evaluate to, which
+            // raises the finding rather than dropping it.
             if (!override.disabled) {
                 const enabled = coreRowSeverity(override.id);
                 if (enabled === null)
@@ -643,7 +647,7 @@ function checkModelVisibleText(input) {
             detail: 'Skill and agent-instruction markdown reaches the model verbatim, unescaped and uncapped. Shipping it '
                 + 'in an npm package does not by itself put it in front of the model: it is discovered only when the plugin '
                 + 'registers it through ctx.skills, when a patch row redirects a skill root into this package (A15), or when '
-                + 'something copies it into the user\'s workspace. The text itself is scored separately by B10.',
+                + 'something copies it into the user\'s workspace. The text itself is scored separately by A21.',
             /* v8 ignore next -- the caller returns early on an empty list. */
             evidence: { file: input.modelVisibleFiles[0] ?? '', snippet: snippet(input.modelVisibleFiles.join(', ')) },
         })];

package/lib/checks/tier-b.js

@@ -53,6 +53,13 @@ export function matchesCredentialPath(text) {
 const DYNAMIC_CODE_CALLEES = new Set([
     'eval', 'runInNewContext', 'runInThisContext', 'runInContext', 'compileFunction',
 ]);
+/**
+ * The harness's own tool-definition helper, exported from
+ * `@deepseek-ai/dsh-tools`. Every registered tool in the harness is built by
+ * either calling it or handing `tools.register` a literal, so recognising the
+ * two shapes is what tells a tool `description` from every other kind.
+ */
+const TOOL_DEFINITION_HELPER = 'defineTool';
 /** `ctx.systemPrompt` members that change what the model is told. */
 const SYSTEM_PROMPT_MEMBERS = new Set([
     'section', 'context', 'variable', 'tools', 'suppressRuntimeContext',
@@ -350,6 +357,70 @@ function checkCredentialRead(file, node, accumulator) {
     accumulator.findings.push(finding);
     accumulator.credentialRead ??= finding;
 }
+/**
+ * Whether a call hands its arguments to the tool registry: the registry call
+ * itself, `<ctx>.tools.register(…)`, or the harness's `defineTool(…)` helper,
+ * whose argument is a tool definition and nothing else.
+ * @param node - the call expression.
+ * @returns true when its arguments are tool definitions.
+ */
+function isToolRegistration(node) {
+    const callee = node.expression;
+    if (ts.isIdentifier(callee))
+        return callee.text === TOOL_DEFINITION_HELPER;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'register'
+        && ts.isPropertyAccessExpression(callee.expression) && callee.expression.name.text === 'tools';
+}
+/**
+ * Whether a name bound in this file is passed to a tool registration call, so
+ * a definition built as `const tool = {…}` and registered on a later line is
+ * still recognised as one.
+ * @param name - the bound identifier.
+ * @param file - the parsed file it was bound in.
+ * @returns true when a registration call in the same file receives it.
+ */
+function isRegisteredName(name, file) {
+    let registered = false;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isToolRegistration(node)
+            && node.arguments.some(argument => ts.isIdentifier(argument) && argument.text === name)) {
+            registered = true;
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(file.node, visit);
+    return registered;
+}
+/**
+ * Whether a `description` property belongs to a tool definition this package
+ * registers.
+ *
+ * The receiver guard is the whole check. `description` is one of the commonest
+ * property names in JavaScript — a JSON schema, an OpenAPI document, a
+ * changelog entry and a CLI option table all carry one — and none of that text
+ * reaches a model. Without the guard the injection heuristics run on release
+ * notes, and the finding's title then asserts something about a tool that the
+ * package does not have.
+ *
+ * Nested properties count, because the whole definition is model-visible: a
+ * parameter's `description` is rendered into the tool schema the model
+ * receives alongside the tool's own.
+ * @param node - the `description` property assignment.
+ * @param file - the parsed file it came from.
+ * @returns true when an enclosing object literal is a registered tool definition.
+ */
+function isRegisteredToolDescription(node, file) {
+    let parent = node.parent;
+    for (;;) {
+        if (ts.isCallExpression(parent))
+            return isToolRegistration(parent);
+        if (ts.isVariableDeclaration(parent))
+            return ts.isIdentifier(parent.name) && isRegisteredName(parent.name.text, file);
+        if (!ts.isObjectLiteralExpression(parent) && !ts.isPropertyAssignment(parent))
+            return false;
+        parent = parent.parent;
+    }
+}
 /** B10 — injection phrasing in a registered tool description. */
 function checkToolDescription(file, node, accumulator) {
     if (!ts.isPropertyAssignment(node))
@@ -359,6 +430,8 @@ function checkToolDescription(file, node, accumulator) {
     const text = literalText(node.initializer);
     if (text === null)
         return;
+    if (!isRegisteredToolDescription(node, file))
+        return;
     for (const match of scanInjection(text)) {
         accumulator.findings.push(tierB({
             checkId: 'B10',
@@ -366,11 +439,14 @@ function checkToolDescription(file, node, accumulator) {
             subject: match.ruleId,
             severity: 'high',
             title: `Tool description ${match.meaning}`,
-            detail: `Heuristic \`${match.ruleId}\` matched a tool \`description\`, which is prompt text the model receives `
-                + 'verbatim on every request that lists the tool. This is a natural-language heuristic: it will miss a '
-                + 'rephrasing, and it can fire on a description that legitimately discusses the subject.',
+            detail: `Heuristic \`${match.ruleId}\` matched a \`description\` inside a registered tool definition, which is `
+                + 'prompt text the model receives verbatim on every request that lists the tool. This is a natural-language '
+                + 'heuristic: it will miss a rephrasing, and it can fire on a description that legitimately discusses the '
+                + 'subject.',
             evidence: { ...at(file, node), snippet: snippet(match.excerpt) },
-            bypass: 'any rephrasing the pattern does not cover, or building the description by concatenation',
+            bypass: 'any rephrasing the pattern does not cover, building the description by concatenation, or registering '
+                + 'the definition through a value this tool does not track — a definition exported from one file and passed '
+                + 'to `tools.register` in another is not matched',
         }));
     }
 }

package/lib/checks/tier-c.js

@@ -330,7 +330,9 @@ function checkUnreadableFiles(input) {
         detail: reason === 'binary'
             ? 'Binary payloads — native addons, WebAssembly, archives — are shipped code this tool cannot read at all. '
                 + 'A mounted layer can load a `.node` addon with no restriction whatsoever.'
-            : 'These files exceeded a size or count cap and were not read. Nothing is claimed about their contents.',
+            : 'These files were not read: each either passed a size or count cap, or is not a regular file the reader '
+                + 'can open — a symbolic link, a FIFO, a socket, or a directory it was refused. The subject names which. '
+                + 'Nothing is claimed about their contents.',
         /* v8 ignore next -- a reason only appears in the map once a path was pushed under it. */
         evidence: { file: paths[0] ?? '', snippet: snippet(paths.slice(0, 8).join(', ')) },
         bypass: 'none — this finding is about the analysis, not about the plugin',

package/lib/injection.js

@@ -39,7 +39,13 @@ export const INJECTION_RULES = [
     },
     {
         id: 'credential-exfiltration',
-        pattern: /\b(?:send|post|upload|transmit|exfiltrate|forward|report)\b[^.\n]{0,60}\b(?:api[_ -]?key|access[_ -]?token|secret|credential|password|\.env|id_rsa|\.npmrc)\b/i,
+        // The dotted filenames carry their own boundary. A `\b` in front of the
+        // whole alternation cannot match at the start of `.env` or `.npmrc`: the
+        // preceding character is a space and the next is a `.`, so neither side of
+        // that position is a word character and the boundary does not exist there.
+        // Under a shared `\b` those two alternatives match nothing, while the
+        // word-initial ones beside them keep working and hide it.
+        pattern: /\b(?:send|post|upload|transmit|exfiltrate|forward|report)\b[^.\n]{0,60}(?:\b(?:api[_ -]?key|access[_ -]?token|secret|credential|password|id_rsa)\b|\.(?:env|npmrc)\b)/i,
         meaning: 'instructs the model to move a credential somewhere',
     },
     {

package/lib/report.js

@@ -140,7 +140,11 @@ function renderFacts(report, paint) {
             ? []
             : [
                 ['fetched from', `${provenance.tarball} (${provenance.tarballBytes} bytes, never written to disk)`],
-                ['verified', `${provenance.digest} matched dist.integrity before anything parsed it`],
+                // Which field matched is not cosmetic: `dist.shasum` is SHA-1 and is
+                // only reached on packages published before npm 5, so naming
+                // `dist.integrity` there would report a stronger check than ran.
+                ['verified', `${provenance.digest} matched `
+                        + `${provenance.algorithm === 'sha1' ? 'dist.shasum' : 'dist.integrity'} before anything parsed it`],
                 ['install script', provenance.hasInstallScript
                         ? 'yes — the registry marks this package as running one at install time'
                         : 'no — the registry does not mark this package as running one'],

package/lib/source.js

@@ -15,7 +15,9 @@
  * cap.
  *
  * Symbolic links are recorded and never followed, for the same reason: a link
- * pointing outside the package is not part of the package.
+ * pointing outside the package is not part of the package. Anything else that
+ * is not a regular file — a FIFO, a socket, a device node — is recorded the
+ * same way and never opened.
  * @module dsh-plugin-inspector/source
  */
 import { createReadStream, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from 'node:fs';
@@ -131,8 +133,15 @@ function walkDirectory(root, directory, collector, published) {
             walkDirectory(root, absolute, collector, published);
             continue;
         }
-        if (!entry.isFile())
+        if (!entry.isFile()) {
+            // A FIFO, socket or device node the publish set includes is content the
+            // analyzer did not read, and "how much could be read" is the one number
+            // that may never be overstated. Reading one is also not an option: a
+            // `readFileSync` on a FIFO blocks until somebody writes to it.
+            if (published.includes(path))
+                collector.skipped.push({ path, reason: 'unreadable' });
             continue;
+        }
         if (!published.includes(path)) {
             collector.unpublished += 1;
             continue;

package/lib/types/model.d.ts

@@ -17,7 +17,7 @@ export type Severity = 'critical' | 'high' | 'medium' | 'low';
  * `certain`; Tier B recognises syntax and is downgraded when Tier C fires.
  */
 export type Confidence = 'certain' | 'high' | 'moderate' | 'low';
-/** Which analysis produced a finding. See PLAN.md §6. */
+/** Which analysis produced a finding. See the check catalogue, `docs/checks.md`. */
 export type Tier = 'A' | 'B' | 'C';
 /** Severity ordering, ascending. Used for `--fail-on` comparison and ranking. */
 export declare const SEVERITY_RANK: Readonly<Record<Severity, number>>;
@@ -49,7 +49,7 @@ export declare const MAX_EXAMPLES = 3;
  * finding that does.
  */
 export interface Finding {
-    /** Catalogue id from PLAN.md §6, e.g. `A2`. Stable across releases. */
+    /** Catalogue id from `docs/checks.md`, e.g. `A2`. Stable across releases. */
     readonly checkId: string;
     /** Machine-readable check name, e.g. `core-row-disabled`. Stable across releases. */
     readonly name: string;
@@ -116,7 +116,7 @@ export interface Facts {
     readonly unmountedPatchFiles: readonly string[];
     readonly dependencies: readonly string[];
     readonly peerDependencies: readonly string[];
-    /** Shipped markdown that can reach the model. See PLAN.md §6.1 reach note. */
+    /** Shipped markdown that can reach the model. See the A12 reach note in `docs/checks.md`. */
     readonly modelVisibleFiles: readonly string[];
     readonly filesRead: number;
     readonly bytesRead: number;

package/lib/types/source.d.ts

@@ -15,7 +15,9 @@
  * cap.
  *
  * Symbolic links are recorded and never followed, for the same reason: a link
- * pointing outside the package is not part of the package.
+ * pointing outside the package is not part of the package. Anything else that
+ * is not a regular file — a FIFO, a socket, a device node — is recorded the
+ * same way and never opened.
  * @module dsh-plugin-inspector/source
  */
 import type { SkippedFile } from './model.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Know what a DeepSeek Harness plugin does before you install it — static pre-install analysis of a plugin directory or tarball",
   "license": "MIT",
   "author": "Ivan Tyshchenko",