dsh-plugin-inspector 0.4.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

@@ -9,9 +9,9 @@
  * @module dsh-plugin-inspector/checks/tier-a
  */
 import { isJsExpr } from "../cordis-yaml.js";
-import { boundedJson, lineColumn, normalizePackagePath, snippet } from "../files.js";
+import { boundedJson, isNativeSource, lineColumn, normalizePackagePath, snippet } from "../files.js";
 import { scanInjection } from "../injection.js";
-import { CORE_ROWS, HARNESS_BUNDLE_PACKAGES, INSTALL_LIFECYCLE_SCRIPTS, LIFECYCLE_SIGNALS, MCP_CLIENT_PACKAGE, SECURITY_ROW_IDS, SECURITY_SEAM_KEYS, SEAM_KEYS, SKILL_FILESYSTEM_ROW, SKILL_ROOT_CONFIG_KEYS, } from "../knowledge.js";
+import { CORE_ROWS, GYP_COMMAND_KEYS, HARNESS_BUNDLE_PACKAGES, INSTALL_LIFECYCLE_SCRIPTS, MCP_CLIENT_PACKAGE, NATIVE_BUILD_FILE, SECURITY_ROW_IDS, SECURITY_SEAM_KEYS, SEAM_KEYS, SKILL_FILESYSTEM_ROW, SKILL_ROOT_CONFIG_KEYS, matchingLifecycleSignals, } from "../knowledge.js";
 import { declaredPackages } from "../manifest.js";
 /**
  * Checks that read a Cordis patch row. None of them may produce a finding
@@ -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)
@@ -424,7 +428,7 @@ function checkManifest(input) {
     for (const name of lifecycle) {
         /* v8 ignore next -- `name` came from filtering the same object's own keys. */
         const command = manifest.scripts[name] ?? '';
-        const signals = LIFECYCLE_SIGNALS.filter(signal => signal.pattern.test(command));
+        const signals = matchingLifecycleSignals(command);
         findings.push(tierA({
             checkId: 'A1',
             name: 'install-lifecycle-script',
@@ -548,6 +552,88 @@ function checkManifest(input) {
     }
     return findings;
 }
+/**
+ * Whether the package ships anything a native build would compile.
+ *
+ * Skipped files count: a `.cc` the reader passed over for its size is still a
+ * source in the tarball, and claiming a package has none because the analyzer
+ * declined to read one would be wrong in the direction that raises a finding.
+ * @param input - the decoded package.
+ * @returns true when C-family source is present.
+ */
+function shipsNativeSource(input) {
+    const paths = [...input.source.files.keys(), ...input.source.skipped.map(entry => entry.path)];
+    return paths.some(isNativeSource);
+}
+/**
+ * A24 — a native build declaration, which is an install-time execution point
+ * that appears in no entry the manifest declares.
+ *
+ * Tier A because the decidable half is the whole finding: the file is at the
+ * package root or it is not, and npm's default install command for a package
+ * that ships one and declares no `install` or `preinstall` script is
+ * `node-gyp rebuild`. Nothing has to be inferred about the code to know that a
+ * build runs, which is the same standard A1 and A22 are read at — a field npm
+ * itself must read literally in order to act on it.
+ *
+ * **The file is not parsed and never evaluated.** GYP is Python-ish, not JSON:
+ * single-quoted strings, `#` comments, trailing commas, and `conditions` whose
+ * first element is a Python expression written as a string. There is no
+ * maintained JavaScript parser for it — `node-gyp` shells out to Python — so
+ * parsing it here would mean hand-rolling one for an attacker-controlled file,
+ * and evaluating a condition is the one thing this tool may never do. It also
+ * would not change the verdict: what distinguishes a build declaration from a
+ * build step is the presence of an `actions`, `rules` or `postbuilds` key and
+ * the shape of the command line under it, and both are literal text in the file
+ * either way. The severity is therefore keyed on a key match plus the same
+ * command signals A1 grades a lifecycle script by.
+ * @param input - the decoded package.
+ * @returns the finding, or none when the package ships no `binding.gyp`.
+ */
+function checkNativeBuild(input) {
+    const text = input.source.files.get(NATIVE_BUILD_FILE);
+    if (text === undefined)
+        return [];
+    const runsCommands = GYP_COMMAND_KEYS.test(text);
+    const signals = runsCommands ? matchingLifecycleSignals(text) : [];
+    const empty = shipsNativeSource(input) ? '' : ' The package ships no C or C++ source, so there is nothing here for '
+        + 'a compiler to build and the build step is the only effect the file has.';
+    const first = signals[0];
+    let at = 0;
+    if (first !== undefined) {
+        /* v8 ignore next -- `first` is in the list because it matched this same text, so `exec` finds it again. */
+        at = first.pattern.exec(text)?.index ?? 0;
+    }
+    return [tierA({
+            checkId: 'A24',
+            name: 'native-build-declaration',
+            subject: NATIVE_BUILD_FILE,
+            severity: signals.length === 0 ? 'medium' : 'high',
+            title: signals.length === 0
+                ? 'Ships `binding.gyp`, which npm turns into an install-time build'
+                : 'Ships a `binding.gyp` whose build steps run commands rather than a compiler',
+            detail: 'A package that ships this file and declares no `install` or `preinstall` script gets `node-gyp rebuild` '
+                + 'as its install command by default, and `node-gyp` evaluates the file to decide what that build does. The '
+                + 'declaration is in none of the entry points a reader checks: not `main`, not `bin`, not `exports`, and not '
+                + '`scripts`. It runs under the same gate as A1 — pnpm and npm block a dependency\'s build until the package is '
+                + 'named in `allowBuilds` — but reaching that gate takes no key in `package.json` at all, which is why an '
+                + 'ecosystem where install hooks are off by default is one where this path is worth reading.'
+                + (signals.length === 0
+                    ? ' This file declares no `actions`, `rules` or `postbuilds` step whose command line does anything a compile '
+                        + 'does not, so what it describes is a build.'
+                    : ` It declares a build step whose command ${signals.map(signal => signal.meaning).join(', and ')}.`)
+                + empty
+                + ' The file was read as text, never parsed and never evaluated — GYP is Python-ish syntax whose conditions are '
+                + 'Python expressions. Reading it that way is enough to decide that a build runs, which is this finding. It is '
+                + 'not enough to decide what the build does, so the grade above reads the command line the way A1 reads a '
+                + 'lifecycle script\'s.',
+            evidence: {
+                file: NATIVE_BUILD_FILE,
+                path: lineColumn(text, at),
+                snippet: snippet(text.slice(at, at + 400)),
+            },
+        })];
+}
 /** A12 — shipped markdown that reaches the model when it is discovered. */
 function checkModelVisibleText(input) {
     if (input.modelVisibleFiles.length === 0)
@@ -561,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(', ')) },
         })];
@@ -652,6 +738,7 @@ function checkInjectionText(input) {
 export function runTierA(input) {
     const findings = [
         ...checkManifest(input),
+        ...checkNativeBuild(input),
         ...checkDisabledRows(input),
         ...checkOverriddenRows(input),
         ...checkExpressions(input),

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

@@ -16,6 +16,7 @@
  */
 import ts from 'typescript';
 import { lineColumn, snippet } from "../files.js";
+import { MAX_EXAMPLES } from "../model.js";
 /** A line longer than this is not written by hand. */
 const MINIFIED_LINE_LENGTH = 500;
 /** Below this many bytes, a low line count says nothing. */
@@ -35,14 +36,26 @@ const NAMED_TARGET_CALLEES = new Set([
 function tierC(finding) {
     return { ...finding, tier: 'C', confidence: 'moderate', examples: [finding.evidence], occurrences: 1 };
 }
-/** C1 — source that is not written to be read. */
-function checkMinification(input) {
-    const findings = [];
+/**
+ * Parse every shipped source file once.
+ * @param input - the decoded package.
+ * @returns one entry per source file, in `sourceFiles` order.
+ */
+function parseSources(input) {
+    const files = [];
     for (const path of input.sourceFiles) {
         const text = input.source.files.get(path);
         /* v8 ignore next -- `sourceFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
         if (text === undefined)
             continue;
+        files.push({ path, text, node: ts.createSourceFile(path, text, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS) });
+    }
+    return files;
+}
+/** C1 — source that is not written to be read. */
+function checkMinification(files) {
+    const findings = [];
+    for (const { path, text } of files) {
         const lines = text.split('\n');
         const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
         const dense = text.length >= MINIFICATION_SIZE_FLOOR && lines.length < 5;
@@ -73,14 +86,9 @@ function checkMinification(input) {
     return findings;
 }
 /** C2 — names the analyzer cannot resolve without running the code. */
-function checkDynamicDispatch(input) {
+function checkDynamicDispatch(files) {
     const findings = [];
-    for (const path of input.sourceFiles) {
-        const text = input.source.files.get(path);
-        /* v8 ignore next -- `sourceFiles` is filtered from `source.files`'s own keys, so the lookup always hits. */
-        if (text === undefined)
-            continue;
-        const source = ts.createSourceFile(path, text, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS);
+    for (const { path, text, node: source } of files) {
         const report = (node, what) => {
             findings.push(tierC({
                 checkId: 'C2',
@@ -194,18 +202,80 @@ function literalOf(node) {
         return node.text;
     return null;
 }
+/**
+ * C8 — identifiers spelled with Unicode escapes.
+ *
+ * An escaped spelling and a plain one are the same identifier: the escape is
+ * resolved in the scanner, before any binding, so the two are the same program
+ * and only a reader sees a difference. That is the whole technique — the file
+ * says one thing to a person and another to the engine.
+ *
+ * It says the same thing to this tool as to the engine. `ts.createSourceFile`
+ * hands back `node.text === 'fetch'` for the escaped form, so every Tier B
+ * check that matches a name matches the escaped spelling too. That is measured
+ * rather than assumed — `tests/unit/detection.spec.ts` runs escaped spellings
+ * through B6, B7, B9 and B12 — which is why this finding sits with C3 in
+ * {@link NON_DEGRADING_CHECKS} rather than making every Tier B negative
+ * unreliable.
+ * @param files - the parsed source files.
+ * @returns one finding for the package, or none.
+ */
+function checkEscapedIdentifiers(files) {
+    const sites = [];
+    for (const { path, text, node: source } of files) {
+        const visit = (node) => {
+            if (ts.isIdentifier(node)) {
+                const start = node.getStart(source);
+                const raw = text.slice(start, node.end);
+                // An identifier token holds a backslash only as part of a `\uXXXX` or
+                // `\u{X}` escape; nothing else in the grammar puts one there.
+                if (raw.includes('\\')) {
+                    sites.push({ name: node.text, evidence: { file: path, path: lineColumn(text, start), snippet: snippet(raw) } });
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(source, visit);
+    }
+    const first = sites[0];
+    if (first === undefined)
+        return [];
+    const names = [...new Set(sites.map(site => site.name))].sort();
+    return [{
+            ...tierC({
+                checkId: 'C8',
+                name: 'escaped-identifier',
+                subject: 'escaped-identifier',
+                severity: 'medium',
+                title: 'Writes identifier names as Unicode escapes',
+                detail: `The escapes resolve to ${names.map(name => `\`${name}\``).join(', ')}. JavaScript resolves an `
+                    + 'identifier escape in the scanner, so the escaped and the plain spelling are the same program and no '
+                    + 'behavior distinguishes them — the difference is only visible to whoever reads the file. Nothing writes a '
+                    + 'name this way by accident, and a published package has no build reason to.'
+                    + ' This does not weaken the rest of the report: the parser resolves the escape before any check sees the '
+                    + 'name, so a `\\u`-escaped `fetch` is still reported as network egress and an escaped `process.env` read is '
+                    + 'still reported as a credential read. What the escape defeats is the reading, not the detection.',
+                evidence: first.evidence,
+                bypass: 'concealing the name a way this check is not about — a computed member or a string assembled at '
+                    + 'runtime, which is C2',
+            }),
+            examples: sites.slice(0, MAX_EXAMPLES).map(site => site.evidence),
+            occurrences: sites.length,
+        }];
+}
 /**
  * Tier C checks that do **not** make a Tier B negative unreliable.
  *
- * Every other check here says the analyzer could not read something. C3 says
- * the opposite: the bytes were read exactly as written and exactly as they will
- * run — what cannot be checked is whether they match the repository that
- * claims to have produced them. That is worth reporting and it is not a reason
- * to distrust the parse, and treating it as one marks every ordinary published
- * tarball `degraded`, because shipping built output and no source is what
- * publishing a package *is*.
+ * Every other check here says the analyzer could not read something. C3 and C8
+ * say the opposite. C3: the bytes were read exactly as written and exactly as
+ * they will run — what cannot be checked is whether they match the repository
+ * that claims to have produced them. Treating that as an unreadable package
+ * marks every ordinary published tarball `degraded`, because shipping built
+ * output and no source is what publishing a package *is*. C8: the escape is
+ * resolved by the parser before any check reads the name, so the analysis of an
+ * escaped identifier is exactly as good as the analysis of a plain one.
  */
-export const NON_DEGRADING_CHECKS = new Set(['C3']);
+export const NON_DEGRADING_CHECKS = new Set(['C3', 'C8']);
 /** C3, C6 — shipped build output with nothing to compare it against. */
 function checkSourcelessBuild(input) {
     const built = input.sourceFiles.filter(path => /^(?:lib|dist|build|out)\//.test(path));
@@ -260,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',
@@ -308,9 +380,11 @@ function checkPatchAliases(input) {
  * @returns findings, unordered.
  */
 export function runTierC(input) {
+    const files = parseSources(input);
     return [
-        ...checkMinification(input),
-        ...checkDynamicDispatch(input),
+        ...checkMinification(files),
+        ...checkDynamicDispatch(files),
+        ...checkEscapedIdentifiers(files),
         ...checkSourcelessBuild(input),
         ...checkUnreadableFiles(input),
         ...checkPatchWalkLimit(input),

package/lib/files.js

@@ -20,6 +20,23 @@ export function isSourceFile(path) {
         return false;
     return SOURCE_EXTENSIONS.some(extension => path.endsWith(extension));
 }
+/** Extensions a `binding.gyp` target compiles. */
+const NATIVE_SOURCE_EXTENSIONS = [
+    '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx', '.m', '.mm', '.s', '.asm',
+];
+/**
+ * Whether a path is C-family source a native build would compile.
+ *
+ * Used to answer one question about a package that ships a `binding.gyp`: is
+ * there anything in it to build. A gyp with no compilable source is a build
+ * declaration whose only effect is that a build runs.
+ * @param path - package-relative POSIX path.
+ * @returns true when the file is C-family source or a header.
+ */
+export function isNativeSource(path) {
+    const lower = path.toLowerCase();
+    return NATIVE_SOURCE_EXTENSIONS.some(extension => lower.endsWith(extension));
+}
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *

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/knowledge.js

@@ -329,6 +329,38 @@ export const LIFECYCLE_SIGNALS = [
         meaning: 'decodes an encoded payload, which is how a command hides what it runs',
     },
 ];
+/**
+ * Every lifecycle signal a command line matches.
+ *
+ * One entry point rather than the filter written out twice, because the table
+ * now grades two different things — a `package.json` lifecycle command (A1) and
+ * a `binding.gyp` build step (A24) — and a rule added to it has to reach both.
+ * @param command - the command line, or the text that holds one.
+ * @returns the matching signals, in table order.
+ */
+export function matchingLifecycleSignals(command) {
+    return LIFECYCLE_SIGNALS.filter(signal => signal.pattern.test(command));
+}
+/**
+ * The file `node-gyp` reads, at the package root and nowhere else.
+ *
+ * npm and pnpm treat its presence as a declaration: a package that ships one
+ * and declares no `install` or `preinstall` script gets `node-gyp rebuild` as
+ * its install command. That default appears in no field of `package.json`.
+ */
+export const NATIVE_BUILD_FILE = 'binding.gyp';
+/**
+ * GYP keys that carry a command line rather than a list of sources to compile.
+ *
+ * `actions` and `rules` run a program during the build; `postbuilds` runs one
+ * after it. A target that only lists `sources`, `include_dirs` and `libraries`
+ * compiles code the package shipped and runs nothing else.
+ *
+ * Matched against the whole file, so a block nested inside a `conditions` arm
+ * counts the same as a top-level one — which is the point, because a condition
+ * is where a build step goes to be read past.
+ */
+export const GYP_COMMAND_KEYS = /['"](?:actions?|rules?|postbuilds)['"]\s*:/;
 /** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
 export const STATIC_ENTRY_FIELDS = [
     'id', 'name', 'group', 'inject', 'intercept', 'isolate',

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/checks/tier-c.d.ts

@@ -14,18 +14,19 @@
  * from claiming nothing was found.
  * @module dsh-plugin-inspector/checks/tier-c
  */
-import type { Finding } from '../model.ts';
+import { type Finding } from '../model.ts';
 import type { CheckInput } from './input.ts';
 /**
  * Tier C checks that do **not** make a Tier B negative unreliable.
  *
- * Every other check here says the analyzer could not read something. C3 says
- * the opposite: the bytes were read exactly as written and exactly as they will
- * run — what cannot be checked is whether they match the repository that
- * claims to have produced them. That is worth reporting and it is not a reason
- * to distrust the parse, and treating it as one marks every ordinary published
- * tarball `degraded`, because shipping built output and no source is what
- * publishing a package *is*.
+ * Every other check here says the analyzer could not read something. C3 and C8
+ * say the opposite. C3: the bytes were read exactly as written and exactly as
+ * they will run — what cannot be checked is whether they match the repository
+ * that claims to have produced them. Treating that as an unreadable package
+ * marks every ordinary published tarball `degraded`, because shipping built
+ * output and no source is what publishing a package *is*. C8: the escape is
+ * resolved by the parser before any check reads the name, so the analysis of an
+ * escaped identifier is exactly as good as the analysis of a plain one.
  */
 export declare const NON_DEGRADING_CHECKS: ReadonlySet<string>;
 /**

package/lib/types/files.d.ts

@@ -10,6 +10,16 @@
  * @returns true when the file should be parsed.
  */
 export declare function isSourceFile(path: string): boolean;
+/**
+ * Whether a path is C-family source a native build would compile.
+ *
+ * Used to answer one question about a package that ships a `binding.gyp`: is
+ * there anything in it to build. A gyp with no compilable source is a build
+ * declaration whose only effect is that a build runs.
+ * @param path - package-relative POSIX path.
+ * @returns true when the file is C-family source or a header.
+ */
+export declare function isNativeSource(path: string): boolean;
 /**
  * Whether a path is markdown that can reach the model verbatim.
  *

package/lib/types/knowledge.d.ts

@@ -134,6 +134,36 @@ export interface LifecycleSignal {
  * that shape is deliberately not a signal here.
  */
 export declare const LIFECYCLE_SIGNALS: readonly LifecycleSignal[];
+/**
+ * Every lifecycle signal a command line matches.
+ *
+ * One entry point rather than the filter written out twice, because the table
+ * now grades two different things — a `package.json` lifecycle command (A1) and
+ * a `binding.gyp` build step (A24) — and a rule added to it has to reach both.
+ * @param command - the command line, or the text that holds one.
+ * @returns the matching signals, in table order.
+ */
+export declare function matchingLifecycleSignals(command: string): LifecycleSignal[];
+/**
+ * The file `node-gyp` reads, at the package root and nowhere else.
+ *
+ * npm and pnpm treat its presence as a declaration: a package that ships one
+ * and declares no `install` or `preinstall` script gets `node-gyp rebuild` as
+ * its install command. That default appears in no field of `package.json`.
+ */
+export declare const NATIVE_BUILD_FILE = "binding.gyp";
+/**
+ * GYP keys that carry a command line rather than a list of sources to compile.
+ *
+ * `actions` and `rules` run a program during the build; `postbuilds` runs one
+ * after it. A target that only lists `sources`, `include_dirs` and `libraries`
+ * compiles code the package shipped and runs nothing else.
+ *
+ * Matched against the whole file, so a block nested inside a `conditions` arm
+ * counts the same as a top-level one — which is the point, because a condition
+ * is where a build step goes to be read past.
+ */
+export declare const GYP_COMMAND_KEYS: RegExp;
 /** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
 export declare const STATIC_ENTRY_FIELDS: readonly string[];
 /**

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.4.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",