claudecode-linter 2.1.148-patch.2 → 2.1.148-patch.4

package/README.md

@@ -23,6 +23,17 @@ Or run directly:
 npx claudecode-linter ~/projects/my-plugin/
 ```
 
+Or build it from a clone of this repository — there is no `dist/` until you build:
+
+```bash
+git clone https://github.com/retif/claudecode-linter
+cd claudecode-linter
+npm ci && npm run build      # install dependencies, compile to dist/
+node dist/index.js path/to/plugin/
+```
+
+Commands elsewhere in this README are written as `claudecode-linter …` (the global / `npx` install); from a clone, that is `node dist/index.js …`.
+
 ## Usage
 
 ### Lint
@@ -211,6 +222,82 @@ Formatting is powered by [prettier](https://prettier.io/) for consistent JSON an
 | 1 | Lint errors found |
 | 2 | Fatal error |
 
+## Running on untrusted plugins
+
+claudecode-linter is a **static analyzer** — it parses and validates the artifacts it inspects, it never executes them. There is no `eval`, no `child_process`, no declared hooks are run, and no MCP servers are spawned. Linting **trusted** code needs no special isolation.
+
+For **untrusted** plugins — especially with `--fix`, which writes files back to disk — run the linter sandboxed. claudecode-linter is verified to run correctly fully confined: no network, a read-only root filesystem, all Linux capabilities dropped, `no-new-privileges`, a non-root UID, and only the target directory mounted.
+
+### The Docker image
+
+Two multi-arch (`linux/amd64`, `linux/arm64`) images are published to the GitHub Container Registry — two separate packages, each with its own `:latest` rolling tag and `:<version>` tag:
+
+| Image | Built from | Notes |
+|-------|-----------|-------|
+| `ghcr.io/retif/node-claudecode-linter` | `Dockerfile` — `node:24-alpine` | default |
+| `ghcr.io/retif/bun-claudecode-linter` | `Dockerfile.compile` — `bun build --compile` single executable | smaller (~44 MB compressed) |
+
+**Pull a published image:**
+
+```bash
+docker pull ghcr.io/retif/node-claudecode-linter   # default (node:24-alpine)
+docker pull ghcr.io/retif/bun-claudecode-linter    # smaller (bun --compile)
+```
+
+**Or build it locally** from a checkout of this repo:
+
+```bash
+docker build -t node-claudecode-linter .                       # default (Dockerfile)
+docker build -f Dockerfile.compile -t bun-claudecode-linter .   # smaller variant
+```
+
+Both images behave identically. The `docker run` recipes below use `ghcr.io/retif/node-claudecode-linter`; substitute `ghcr.io/retif/bun-claudecode-linter` or a locally-built tag as you prefer.
+
+### Sandboxed invocation
+
+**Docker — read-only lint:**
+
+```bash
+docker run --rm --network none --read-only --tmpfs /tmp \
+  --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
+  -v "$PWD":/work:ro -w /work  ghcr.io/retif/node-claudecode-linter  /work
+```
+
+**Docker — `--fix`:** the mount must be read-write so fixes can be written back. Otherwise identical, plus the `--fix` flag:
+
+```bash
+docker run --rm --network none --read-only --tmpfs /tmp \
+  --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
+  -v "$PWD":/work -w /work  ghcr.io/retif/node-claudecode-linter  --fix /work
+```
+
+All four recipes here are verified. On Linux without Docker, [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) gives the equivalent boundary: `--unshare-all` cuts network (confirmed: `ECONNREFUSED` inside the sandbox), and nothing is writable except — for `--fix` — the target directory (confirmed: a write outside it is refused).
+
+**bwrap — read-only (lint):**
+
+```bash
+bwrap \
+  --ro-bind / / --dev /dev --proc /proc --tmpfs /tmp \
+  --unshare-all --die-with-parent \
+  --chdir "$PWD" \
+  claudecode-linter "$PWD"
+```
+
+**bwrap — read-write (`--fix`):** the later `--bind` overrides the read-only root for just the target directory:
+
+```bash
+bwrap \
+  --ro-bind / / --bind "$PWD" "$PWD" \
+  --dev /dev --proc /proc --tmpfs /tmp \
+  --unshare-all --die-with-parent \
+  --chdir "$PWD" \
+  claudecode-linter --fix "$PWD"
+```
+
+`--ro-bind / /` can be replaced with explicit per-path `--ro-bind` entries (e.g. just `/usr`, `/nix`, and the target) for least-read-authority.
+
+See [`SECURITY.md`](SECURITY.md) for the full security model, the audited input-handling hardening, and how to report a vulnerability.
+
 ## Versioning
 
 This linter's version tracks the Claude Code version it was extracted from:

package/dist/config.js

@@ -1,9 +1,8 @@
 import { readFileSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import { parse as parseYaml } from "yaml";
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { assetCandidates } from "./utils/asset-path.js";
 const DEFAULT_CONFIG = {
     rules: {},
 };
@@ -13,7 +12,7 @@ export function loadConfig(configPath) {
         return DEFAULT_CONFIG;
     try {
         const content = readFileSync(path, "utf-8");
-        const parsed = parseYaml(content);
+        const parsed = parseYaml(content, { maxAliasCount: 100 });
         if (!parsed || typeof parsed !== "object")
             return DEFAULT_CONFIG;
         const config = { rules: {} };
@@ -47,10 +46,16 @@ function findConfigFile() {
         if (existsSync(homePath))
             return homePath;
     }
-    // 3. Fall back to bundled defaults
-    const bundled = join(__dirname, "..", ".claudecode-lint.defaults.yaml");
-    if (existsSync(bundled))
-        return bundled;
+    // 3. Fall back to bundled defaults. Resolved relative to import.meta.url
+    //    first (Node / npm package), then relative to process.execPath as a
+    //    fallback for the `bun build --compile` single-executable variant.
+    for (const bundled of assetCandidates(import.meta.url, [
+        "..",
+        ".claudecode-lint.defaults.yaml",
+    ])) {
+        if (existsSync(bundled))
+            return bundled;
+    }
     return undefined;
 }
 export function mergeCliRules(config, enable, disable) {

package/dist/formatters/human.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { sanitizeForTerminal } from "../utils/terminal.js";
 const SEVERITY_ICONS = {
     error: pc.red("error"),
     warning: pc.yellow("warn "),
@@ -16,12 +17,12 @@ export function formatHuman(results, quiet) {
         if (filtered.length === 0)
             continue;
         lines.push("");
-        lines.push(pc.underline(result.file));
+        lines.push(pc.underline(sanitizeForTerminal(result.file)));
         for (const d of filtered) {
             const loc = d.line
                 ? pc.dim(`:${d.line}${d.column ? `:${d.column}` : ""}`)
                 : "";
-            lines.push(`  ${SEVERITY_ICONS[d.severity]}  ${d.message}  ${pc.dim(d.rule)}${loc}`);
+            lines.push(`  ${SEVERITY_ICONS[d.severity]}  ${sanitizeForTerminal(d.message)}  ${pc.dim(d.rule)}${loc}`);
             if (d.severity === "error")
                 errorCount++;
             else if (d.severity === "warning")

package/dist/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, copyFileSync, existsSync, statSync, } from "node:fs";
 import { resolve, relative, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import sade from "sade";
 import pc from "picocolors";
 import { loadConfig, mergeCliRules } from "./config.js";
+import { assetCandidates } from "./utils/asset-path.js";
+import { writeBlockedReason } from "./utils/safe-write.js";
+import { sanitizeForTerminal } from "./utils/terminal.js";
 import { discoverArtifacts, detectArtifactTypes } from "./discovery.js";
 import { formatHuman } from "./formatters/human.js";
 import { formatJson } from "./formatters/json.js";
@@ -71,6 +74,12 @@ const ALL_RULES = [
     ...MONITORS_JSON_RULES,
     ...MISPLACED_FILE_RULES,
 ];
+/**
+ * Hard cap on artifact file size. Real Claude Code artifacts are KB-scale;
+ * this only exists to reject pathological / malicious inputs (e.g. a
+ * multi-gigabyte file crafted to exhaust memory).
+ */
+const MAX_ARTIFACT_BYTES = 5 * 1024 * 1024;
 function simpleDiff(oldContent, newContent, filePath) {
     if (oldContent === newContent)
         return "";
@@ -106,7 +115,21 @@ function simpleDiff(oldContent, newContent, filePath) {
     }
     return lines.join("\n");
 }
-const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+function readPkgVersion() {
+    // package.json ships beside dist/ (Node) or beside the executable
+    // (bun-compiled single-executable). Try every candidate; fall back to
+    // "0.0.0" if none resolve (e.g. an unexpected layout) rather than crashing.
+    for (const p of assetCandidates(import.meta.url, ["..", "package.json"])) {
+        try {
+            return JSON.parse(readFileSync(p, "utf8")).version;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return "0.0.0";
+}
+const pkgVersion = readPkgVersion();
 sade("claudecode-linter", true)
     .version(pkgVersion)
     .describe("Linter for Claude Code plugin artifacts")
@@ -133,9 +156,11 @@ sade("claudecode-linter", true)
     const fixDryRun = !!opts["fix-dry-run"];
     try {
         if (opts.init !== undefined) {
-            const __filename = fileURLToPath(import.meta.url);
-            const pkgDir = dirname(dirname(__filename));
-            const defaultsFile = join(pkgDir, ".claudecode-lint.defaults.yaml");
+            const defaultsFile = assetCandidates(import.meta.url, [
+                "..",
+                ".claudecode-lint.defaults.yaml",
+            ]).find((p) => existsSync(p)) ??
+                join(dirname(dirname(fileURLToPath(import.meta.url))), ".claudecode-lint.defaults.yaml");
             const targetDir = typeof opts.init === "string" ? resolve(opts.init) : process.cwd();
             const targetFile = join(targetDir, ".claudecode-lint.yaml");
             if (existsSync(targetFile)) {
@@ -197,10 +222,33 @@ sade("claudecode-linter", true)
                 ignore: ignorePatterns,
             });
             if (artifacts.length === 0) {
-                process.stderr.write(pc.yellow(`No plugin artifacts found in ${targetPath}\n`));
+                process.stderr.write(pc.yellow(`No plugin artifacts found in ${sanitizeForTerminal(targetPath)}\n`));
                 continue;
             }
+            // All --fix / --format writes for this target must stay inside
+            // rootDir. If targetPath is a file, rootDir is its parent dir.
+            const resolvedTarget = resolve(targetPath);
+            let rootDir = resolvedTarget;
+            try {
+                if (!statSync(resolvedTarget).isDirectory()) {
+                    rootDir = dirname(resolvedTarget);
+                }
+            }
+            catch {
+                rootDir = dirname(resolvedTarget);
+            }
             for (const artifact of artifacts) {
+                let sizeBytes;
+                try {
+                    sizeBytes = statSync(artifact.filePath).size;
+                }
+                catch {
+                    sizeBytes = 0;
+                }
+                if (sizeBytes > MAX_ARTIFACT_BYTES) {
+                    process.stderr.write(pc.yellow(`Skipping ${sanitizeForTerminal(artifact.filePath)}: file exceeds ${MAX_ARTIFACT_BYTES}-byte limit (${sizeBytes} bytes)\n`));
+                    continue;
+                }
                 let content = readFileSync(artifact.filePath, "utf-8");
                 const relPath = relative(process.cwd(), artifact.filePath);
                 if (opts.format) {
@@ -208,8 +256,14 @@ sade("claudecode-linter", true)
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
-                            writeFileSync(artifact.filePath, fixedContent);
-                            formatted.push(relPath);
+                            const blocked = writeBlockedReason(artifact.filePath, rootDir);
+                            if (blocked) {
+                                process.stderr.write(pc.red(`Refusing to write ${sanitizeForTerminal(artifact.filePath)}: ${blocked}\n`));
+                            }
+                            else {
+                                writeFileSync(artifact.filePath, fixedContent);
+                                formatted.push(relPath);
+                            }
                         }
                     }
                     continue;
@@ -221,9 +275,15 @@ sade("claudecode-linter", true)
                     if (fixer) {
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
-                            writeFileSync(artifact.filePath, fixedContent);
-                            content = fixedContent;
-                            fixed = 1;
+                            const blocked = writeBlockedReason(artifact.filePath, rootDir);
+                            if (blocked) {
+                                process.stderr.write(pc.red(`Refusing to write ${sanitizeForTerminal(artifact.filePath)}: ${blocked}\n`));
+                            }
+                            else {
+                                writeFileSync(artifact.filePath, fixedContent);
+                                content = fixedContent;
+                                fixed = 1;
+                            }
                         }
                     }
                 }
@@ -233,7 +293,7 @@ sade("claudecode-linter", true)
                         const fixedContent = await fixer.fix(artifact.filePath, content, config);
                         if (fixedContent !== content) {
                             const diff = simpleDiff(content, fixedContent, artifact.filePath);
-                            process.stdout.write(diff + "\n");
+                            process.stdout.write(sanitizeForTerminal(diff) + "\n");
                         }
                     }
                 }

package/dist/plugin-schema.js

@@ -8,11 +8,10 @@
  * resolver if the file is being run from an alternate layout (e.g. monorepo).
  */
 import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Ajv2020 } from "ajv/dist/2020.js";
 // biome-ignore lint/style/useImportType: runtime import; types only.
 import * as addFormatsNs from "ajv-formats";
+import { assetCandidates } from "./utils/asset-path.js";
 // ajv-formats ships as CJS with a default function export. Under Node16
 // ESM resolution we have to reach in for `.default`.
 const addFormats = addFormatsNs.default;
@@ -29,10 +28,9 @@ function getAjv() {
 function loadCompiledSchema(fileName) {
     if (compiledCache.has(fileName))
         return compiledCache.get(fileName) ?? null;
-    const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(here, "..", "contracts", fileName),
-        resolve(here, "..", "..", "contracts", fileName),
+        ...assetCandidates(import.meta.url, ["..", "contracts", fileName]),
+        ...assetCandidates(import.meta.url, ["..", "..", "contracts", fileName]),
     ];
     let raw = null;
     for (const p of candidates) {
@@ -84,10 +82,14 @@ export function loadCommandFrontmatterSchema() {
 export function loadPluginSchema() {
     if (cached)
         return cached;
-    const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(here, "..", "contracts", "plugin.schema.json"),
-        resolve(here, "..", "..", "contracts", "plugin.schema.json"),
+        ...assetCandidates(import.meta.url, ["..", "contracts", "plugin.schema.json"]),
+        ...assetCandidates(import.meta.url, [
+            "..",
+            "..",
+            "contracts",
+            "plugin.schema.json",
+        ]),
     ];
     let raw = null;
     for (const p of candidates) {

package/dist/utils/asset-path.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve runtime assets (contracts/*.schema.json, .claudecode-lint.defaults.yaml,
+ * package.json) that ship alongside the package on disk.
+ *
+ * Normally these are found relative to `import.meta.url` — the location of the
+ * compiled `.js` file inside `dist/`. That works for the Node build and for the
+ * published npm package.
+ *
+ * Inside a `bun build --compile` single-executable, `import.meta.url` points
+ * into Bun's virtual embedded filesystem (`/$bunfs/...`), so disk reads of
+ * sibling assets fail. To support that variant, we ALSO emit candidates
+ * relative to `process.execPath` (the real on-disk path of the running
+ * executable). The compiled-binary image ships `contracts/` and
+ * `.claudecode-lint.defaults.yaml` next to the executable, so those fallback
+ * candidates resolve there.
+ *
+ * For the Node runtime, the `process.execPath`-relative candidates simply point
+ * at the `node` binary's directory and won't match — harmless extra lookups
+ * appended AFTER the existing ones, so Node resolution is byte-for-byte
+ * unchanged.
+ */
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Build a list of candidate paths for an asset shipped with the package.
+ *
+ * @param importMetaUrl  `import.meta.url` of the calling module.
+ * @param segments       Path segments, relative to a base directory, that
+ *                        locate the asset (e.g. `["..", "contracts", "x.json"]`
+ *                        for a module under `dist/`).
+ * @returns Ordered candidate paths: `import.meta.url`-relative first (existing
+ *          behavior), then `process.execPath`-relative fallbacks.
+ */
+export function assetCandidates(importMetaUrl, segments) {
+    const candidates = [];
+    // 1. import.meta.url-relative — the existing, primary resolution.
+    const here = dirname(fileURLToPath(importMetaUrl));
+    candidates.push(resolve(here, ...segments));
+    // 2. process.execPath-relative fallbacks for the compiled single-executable.
+    //    The binary lives next to `contracts/` and the defaults YAML, so we try
+    //    both the executable's own directory and one level up (mirroring the
+    //    dist/ -> package-root step the segments encode).
+    try {
+        const execDir = dirname(process.execPath);
+        // Drop leading ".." segments: assets sit directly beside the executable.
+        const beside = segments.filter((s) => s !== "..");
+        candidates.push(resolve(execDir, ...beside));
+        candidates.push(resolve(execDir, ...segments));
+    }
+    catch {
+        // process.execPath unavailable — ignore.
+    }
+    // De-duplicate while preserving order.
+    return [...new Set(candidates)];
+}
+//# sourceMappingURL=asset-path.js.map

package/dist/utils/frontmatter.js

@@ -32,7 +32,7 @@ export function parseFrontmatter(content) {
     const body = lines.slice(closingIndex + 1).join("\n");
     const bodyStartLine = closingIndex + 2; // 1-based
     try {
-        const data = parseYaml(frontmatterRaw);
+        const data = parseYaml(frontmatterRaw, { maxAliasCount: 100 });
         if (typeof data !== "object" || data === null || Array.isArray(data)) {
             return {
                 data: {},

package/dist/utils/safe-write.js

@@ -0,0 +1,36 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { sep } from "node:path";
+/**
+ * Decide whether writing to `filePath` (a fix/format target) is safe.
+ *
+ * The linter may write fixes back to artifact paths supplied by a plugin.
+ * A malicious plugin can ship an artifact path that is actually a symlink
+ * pointing outside the target tree (`~/.bashrc`, an SSH key, a CI secret);
+ * a bare `writeFileSync` would then clobber the symlink's target.
+ *
+ * Returns a human-readable reason to REFUSE the write, or `null` if the
+ * write is safe. The check fails closed: if anything throws (path missing,
+ * permission error, etc.) a refusal reason is returned.
+ *
+ * Refuses when:
+ *  - `filePath` itself is a symbolic link, or
+ *  - the real path of `filePath` is not `rootDir` itself and not located
+ *    under `rootDir + path.sep`.
+ */
+export function writeBlockedReason(filePath, rootDir) {
+    try {
+        if (lstatSync(filePath).isSymbolicLink()) {
+            return "path is a symlink";
+        }
+        const realRoot = realpathSync(rootDir);
+        const realPath = realpathSync(filePath);
+        if (realPath !== realRoot && !realPath.startsWith(realRoot + sep)) {
+            return "path resolves outside the target directory";
+        }
+        return null;
+    }
+    catch {
+        return "path could not be safely resolved";
+    }
+}
+//# sourceMappingURL=safe-write.js.map

package/dist/utils/terminal.js

@@ -0,0 +1,18 @@
+/**
+ * Strip C0 control characters and DEL from a string before it is written to
+ * a terminal, while preserving tab and newline.
+ *
+ * Diagnostic messages, file paths and `--fix-dry-run` diffs embed untrusted
+ * strings (rule content, field values, file content, plugin-controlled file
+ * and directory names). Without sanitization an attacker-supplied artifact
+ * could smuggle ANSI/control sequences into the user's terminal.
+ *
+ * Strips U+0000-U+0008, U+000B-U+001F and U+007F (DEL) - every C0 control
+ * char and DEL except U+0009 (tab) and U+000A (newline), which are kept.
+ * The stripped set includes U+000D (CR) and U+001B (ESC) by design.
+ */
+export function sanitizeForTerminal(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, "");
+}
+//# sourceMappingURL=terminal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudecode-linter",
-	"version": "2.1.148-patch.2",
+	"version": "2.1.148-patch.4",
 	"description": "Standalone linter for Claude Code plugins and configuration files",
 	"type": "module",
 	"bin": {