dsh-plugin-inspector 0.4.0 → 0.5.0

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
@@ -424,7 +424,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 +548,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)
@@ -652,6 +734,7 @@ function checkInjectionText(input) {
 export function runTierA(input) {
     const findings = [
         ...checkManifest(input),
+        ...checkNativeBuild(input),
         ...checkDisabledRows(input),
         ...checkOverriddenRows(input),
         ...checkExpressions(input),

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));
@@ -308,9 +378,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.4.0",
+  "version": "0.5.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",