dsh-vet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roger Deng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# dsh-vet
+
+Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain
+audits before install, graded via the open [`dsh-vet/v1`](docs/dsh-vet-v1.md)
+report standard.
+
+> **Status: v0.1 complete.** Contract draft, reference scanner + CLI, rule
+> set with public rationales, and an 11-package calibration sweep are in;
+> the `0.1.0` npm release is the remaining step.
+
+## Install
+
+Requires Node ≥ 20.
+
+```sh
+npm install -g dsh-vet        # or: pnpm add -g dsh-vet / bun add -g dsh-vet
+dsh-vet --help
+```
+
+Prefer not installing? `npx dsh-vet <specifier>` runs the same scanner with
+zero footprint. The scanner is the only thing that runs — dsh-vet never
+installs the plugin it audits.
+
+## Usage
+
+```sh
+npx dsh-vet <specifier>          # npm package, git URL, or local path
+npx dsh-vet --json <specifier>   # dsh-vet/v1 report on stdout
+npx dsh-vet --strict <specifier> # exit 1 on findings >= high (confidence >= medium)
+npx dsh-vet --rules dep.install-scripts <specifier>
+```
+
+Any completed report exits `0` — grades describe findings, they do not gate.
+Scanner failures exit non-zero. The scanner runs locally, reads the npm
+registry for dependency metadata only, and never transmits audited code.
+
+Shipped rules (each with a public rationale under
+[`docs/rules/`](docs/rules)):
+
+| Family | Rules |
+|---|---|
+| `perm.*` | seam-mismatch, undeclared-fs-write, subprocess-spawn, network-client, unreachable-files |
+| `dep.*` | install-scripts, floating-range, typosquat-proximity |
+| `obf.*` | eval-detect, dynamic-require, encoded-payload, charcode-chain, unparseable |
+| `egress.*` | outbound-endpoints, secret-adjacent |
+
+dsh-vet audits itself with the same scanner:
+[`examples/dsh-vet.report.json`](examples/dsh-vet.report.json) is generated
+from the exact tarball that ships (`npm pack` → scan), seams declared in
+package.json. It is not an A-by-cheating report — every signal the scanner
+finds in itself is in there.
+
+## Why
+
+DSH's everything-is-a-plugin architecture is its greatest strength and its
+largest attack surface: a plugin you install can register tools, touch the
+filesystem, and open network connections. The community's single most-upvoted
+feature request asks for marketplace standards and review mechanisms
+([deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115)),
+and incidents like a Full Access session deleting a user's home directory
+([#461](https://github.com/deepseek-ai/deepseek-harness/discussions/461)) show
+the stakes. The official marketplace will take time; trust tooling cannot.
+
+`dsh-vet` exists so that "should I install this plugin?" has a shared,
+machine-readable answer instead of vibes.
+
+## What it checks (v0.1 scope)
+
+- **Capability surface** — which Cordis seams a plugin injects (`fs`, `shell`,
+  `web`, …) versus what its manifest and README claim
+- **Supply chain** — dependency tree, install scripts, `postinstall` hooks,
+  typosquat-adjacent package names
+- **Obfuscated behavior** — `eval` / `new Function` / dynamic `require` /
+  encoded payloads
+- **Data egress** — outbound endpoints reachable from code that can read
+  secrets, session data, or the DSH home directory
+
+## The `dsh-vet/v1` report standard
+
+The differentiating piece is not another scanner — it is
+[`docs/dsh-vet-v1.md`](docs/dsh-vet-v1.md): an implementation-agnostic,
+deterministic JSON report contract (findings with severity **and confidence**,
+derived A–F grades) that any scanner may emit and any marketplace, CI job, or
+UI may consume, in the spirit of the community's `dsh-doctor/v1` contract.
+The TypeScript reference types ship from this package; third-party emitters
+are welcome and listed here once verified.
+
+## How it differs
+
+| Tool | Form | Focus |
+|---|---|---|
+| `dsh-plugin-vetting` | dsh plugin | install-time static heuristics |
+| `dsh-audit` | CLI | ecosystem-wide catalog scoring (maintenance / docs / npm, security veto) |
+| `dsh-plugin-audit` | dsh plugin | per-plugin permission profiling + runtime sentinel |
+| `plugin_vet` skill pack | agent skills | audit methodology + gate |
+| **`dsh-vet`** | library + CLI + CI action | the open `dsh-vet/v1` report contract, a reference scanner, and author-side badges — the shared trust layer others can emit and consume |
+
+## Findings are signals, not verdicts
+
+A report describes what code does, not what its author intended. Low-confidence
+findings never lower a grade, and every finding carries evidence and a
+remediation. If you believe a finding about your plugin is wrong, open a
+[false-positive dispute](.github/ISSUE_TEMPLATE/false-positive.md) — disputed
+rules get re-examined and the rule set gets corrected in public.
+
+## Roadmap
+
+- **v0.1** — contract frozen; reference CLI (`dsh vet <pkg>`) with the four
+  check families above
+- **v0.2** — GitHub Action + badge so plugin authors self-audit and publish
+  their grade
+- **v0.3** — marketplace integrations render `dsh-vet/v1` reports; contract
+  adopted by at least one third-party emitter
+
+The detailed, trackable plan — task breakdowns, recorded decisions,
+definitions of done, risks, and kill criteria — lives in
+[ROADMAP.md](ROADMAP.md).
+
+## Develop
+
+```sh
+pnpm install
+pnpm test      # vitest
+pnpm build     # tsdown → lib/
+pnpm verify    # typecheck + test + build + pack check
+```
+
+## Security
+
+Reporting a vulnerability in dsh-vet itself: see [SECURITY.md](SECURITY.md).
+dsh-vet runs locally, reads the npm registry for dependency metadata, and
+never transmits audited code or results anywhere.
+
+## License
+
+[MIT](LICENSE)

package/bin/dsh-vet.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../lib/index.mjs'
+
+process.exit(await runCli(process.argv.slice(2), {
+  stdout: (line) => process.stdout.write(line + '\n'),
+  stderr: (line) => process.stderr.write(line + '\n'),
+}))

package/docs/calibration-v0.1.md

@@ -0,0 +1,58 @@
+# v0.1 calibration sweep
+
+ROADMAP T6 requires a sweep of ~10 real ecosystem plugins with tuning until
+zero **obvious** false positives. Swept on 2026-08-30 with scanner 0.1.0;
+reports are committed under [`examples/sweep/`](../examples/sweep).
+
+## Packages
+
+| Package | Grade | Graded findings |
+|---|---|---|
+| `dsh-searxng@0.1.1` | C | network-client (no `web` seam declared) |
+| `@linxin666/dsh-doctor@0.3.6` | C | secret-adjacent¹, network-client, subprocess-spawn, undeclared-fs-write¹ |
+| `dsh-zcf@0.5.3` | C | secret-adjacent¹, network-client, subprocess-spawn, undeclared-fs-write¹ |
+| `@mlgbnb/dsh-archive-manager@1.0.7` | C | network-client, undeclared-fs-write¹ |
+| `@michengai/dsh-skills-manager@0.1.30` | C | network-client, undeclared-fs-write¹ |
+| `dsh-wechat@0.7.2` | C | network-client, undeclared-fs-write¹ |
+| `dsh-find-plugin@0.3.7` | C | network-client |
+| `dsh-better-sidebar@0.17.1` | C | secret-adjacent¹, encoded-payload¹, network-client, subprocess-spawn, undeclared-fs-write¹ |
+| `@linxin666/dsh-live-stats@0.1.20` | A | — |
+| `@aiwayds/dsh-tui-pi@1.1.0` | C | secret-adjacent¹, network-client, subprocess-spawn, undeclared-fs-write¹ |
+| `dsh-fabric-host@0.1.11` | A | — |
+
+¹ Emitted at `low` confidence (or includes only low-confidence parts) —
+reported, never grade-affecting, per the contract.
+
+Every capability finding was hand-checked against the package's code; every
+one describes real code shape. No scanner failures, no criticals.
+
+## What the sweep says about the ecosystem
+
+- No swept package declares `dsh.seams` yet (the vocabulary ships with
+  dsh-vet), so honest plugins that legitimately use the network or spawn
+  processes read as C until they declare. That is the designed adoption
+  path, not a defect: the remediation in each finding is "declare the seam
+  or drop the capability".
+- Bundled web UIs put `process.env` reads and `fetch` in one file; the
+  `egress.secret-adjacent` finding fires at `low` confidence there — signal,
+  not verdict, exactly as documented.
+
+## Tuning performed
+
+1. **`obf.encoded-payload`: hex literals now require ≥ 8 distinct
+   characters.** `dsh-better-sidebar`'s repeated-digit palette strings
+   (`8888…`) are tables, not encodings; encoded payloads use the hex
+   alphabet broadly. This removed 2 of 3 findings on that package.
+2. **`dep.typosquat-proximity`: popular-name list verified against npm.**
+   `dsh-ankh-guard` was removed (not installable — a name that cannot be
+   installed cannot be typosquatted); verified-active names were added
+   (`dsh-zcf`, `dsh-wechat`, `dsh-better-sidebar`, `dsh-find-plugin`). The
+   list is now all-real by construction and re-checked each sweep.
+
+## Accepted residuals
+
+- One 60-char high-diversity hex literal in `dsh-better-sidebar`
+  (`4e79a7…` — concatenated d3 category colors). Indistinguishable from a
+  real encoding by charset statistics; stays as a medium/**low** finding.
+- Typosquat distance-2 findings remain possible on short names; they emit
+  at `low` severity and cannot lower a grade.

package/docs/dsh-vet-v1.md

@@ -0,0 +1,159 @@
+# The `dsh-vet/v1` report contract
+
+Status: **draft** — open for community input before v0.1 freezes it.
+Reference TypeScript types: `src/contract.ts` (shipped from this package).
+
+`dsh-vet/v1` defines a machine-readable audit report for a DeepSeek Harness
+(DSH) plugin. It is implementation-agnostic: any scanner may emit it, and any
+marketplace, CI job, or UI may consume it. It follows the community pattern
+proven by `dsh-doctor/v1`: freeze a small, boring contract first, compete on
+implementations.
+
+## Design rules
+
+1. **Findings are signals, not verdicts.** A report describes what code does.
+   It does not assert maliciousness, and it never names intent.
+2. **Confidence gates severity.** Only findings with confidence `medium` or
+   `high` may lower a grade. A `low`-confidence finding is reported but cannot
+   cost the audited plugin a grade — false positives must not damage authors.
+3. **Reports are deterministic.** `findings` are sorted (worst severity
+   first, then rule id ascending); `summary` is always derived from
+   `findings`, never asserted by the emitter. Two runs over the same artifact
+   with the same scanner version produce byte-identical reports (timestamps
+   aside).
+4. **Consumers must ignore unknown fields.** Emitters may attach extra fields
+   (encouraged to prefix them `x-`); consumers must tolerate them. Emitters
+   must not change the meaning of fields defined here.
+
+## Report envelope
+
+```jsonc
+{
+  "schema": "dsh-vet/v1",          // literal; required
+  "target":   { /* what was audited */ },
+  "scanner":  { /* who audited, when */ },
+  "summary":  { /* derived grade + counts */ },
+  "findings": [ /* zero or more findings, sorted */ }
+}
+```
+
+### `target`
+
+| Field | Type | Notes |
+|---|---|---|
+| `kind` | `'npm-package' \| 'git-repo' \| 'local-path'` | |
+| `specifier` | `string` | e.g. `dsh-vault@1.10.6`, a git URL, or a path |
+| `resolved.version` | `string?` | version actually audited |
+| `resolved.commit` | `string?` | for `git-repo` targets |
+| `resolved.integrity` | `string?` | subresource integrity of the exact artifact scanned, when available |
+
+### `scanner`
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | `string` | emitting implementation, e.g. `dsh-vet` |
+| `version` | `string` | its version |
+| `ranAt` | `string` | RFC 3339 timestamp of the run |
+
+### `finding`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | rule id; see below |
+| `title` | `string` | one line, human |
+| `severity` | `'critical' \| 'high' \| 'medium' \| 'low' \| 'info'` | |
+| `confidence` | `'high' \| 'medium' \| 'low'` | |
+| `evidence` | `VetEvidence[]` | at least one item |
+| `remediation` | `string?` | how to make the finding go away |
+| `references` | `string[]?` | URLs to rule documentation |
+
+`VetEvidence` = `{ file, line?, snippet?, note? }`. Snippets must be minimal
+and must never include secrets.
+
+#### Severity definitions
+
+- **critical** — direct credential/secret exfiltration, code execution during
+  install, or destructive filesystem operations outside any declared scope
+- **high** — capability that contradicts the plugin's declared purpose
+  (undeclared broad fs/shell/net), obfuscated payloads, obvious typosquat
+- **medium** — suspicious-but-explainable egress, `eval` of non-literal
+  input, install scripts without evident need
+- **low** — hygiene: unpinned dependencies, missing license, unscoped
+  permissions in the manifest
+- **info** — purely informational; never affects the grade
+
+### Rule ids
+
+Pattern: `^[a-z0-9-]+(\.[a-z0-9-]+)+$` — two or more dot-separated lowercase
+segments. Reference rules use two segments (`perm.broad-fs-write`,
+`dep.postinstall-script`); third-party rule sets prefix their own vendor
+segment (`acme.eval-detect`). The pattern is deliberately open-ended about
+segment count: a closed single-segment pattern is exactly how `dsh-doctor/v1`
+initially broke vendor-prefixed check ids — do not repeat that.
+
+### `summary`
+
+`counts` = per-severity finding totals. `grade` is derived:
+
+| Grade | Condition (over findings with confidence ≥ `medium`) |
+|---|---|
+| `A` | none, or only `info`/`low`-severity findings |
+| `B` | worst graded finding is `low` |
+| `C` | worst graded finding is `medium` |
+| `D` | worst graded finding is `high` |
+| `F` | at least one `critical` |
+| `X` | scan incomplete or errored — never presented as the plugin's grade |
+
+## CLI recommendations (non-normative)
+
+Emitters that ship a CLI should exit `0` whenever a report was produced —
+findings are data, not failures — and non-zero only on scanner failure.
+A `--strict` flag may exit `1` when findings of severity ≥ `high` with
+confidence ≥ `medium` exist, for CI gating.
+
+## Example
+
+```json
+{
+  "schema": "dsh-vet/v1",
+  "target": {
+    "kind": "npm-package",
+    "specifier": "fixture-plugin@1.2.3",
+    "resolved": { "version": "1.2.3", "integrity": "sha512-…" }
+  },
+  "scanner": { "name": "dsh-vet", "version": "0.1.0", "ranAt": "2026-09-01T00:00:00Z" },
+  "summary": { "grade": "C", "counts": { "critical": 0, "high": 0, "medium": 1, "low": 1, "info": 1 } },
+  "findings": [
+    {
+      "id": "egress.endpoint-reach",
+      "title": "Sends data to an endpoint from code that can read the DSH home directory",
+      "severity": "medium",
+      "confidence": "high",
+      "evidence": [{ "file": "host-half.js", "line": 42, "note": "fetch to https://example.example/collect" }],
+      "remediation": "Document the endpoint and what is sent, or remove the call."
+    },
+    {
+      "id": "dep.unpinned",
+      "title": "Dependency ranges are not pinned",
+      "severity": "low",
+      "confidence": "medium",
+      "evidence": [{ "file": "package.json" }]
+    },
+    {
+      "id": "meta.no-license",
+      "title": "No license field",
+      "severity": "info",
+      "confidence": "high",
+      "evidence": [{ "file": "package.json" }]
+    }
+  ]
+}
+```
+
+## Versioning
+
+`/v1` freezes at the v0.1 release of this package. Backward-compatible
+additions (new optional fields, new rule ids) stay in `/v1`; semantic changes
+get `/v2` with a migration note. Discussion happens in
+[GitHub Discussions](https://github.com/rogerdigital/dsh-vet/discussions)
+and the [dsh-plugin topic](https://github.com/topics/dsh-plugin).

package/docs/rules/dep.floating-range.md

@@ -0,0 +1,26 @@
+# dep.floating-range
+
+Runtime dependencies that resolve to whatever the registry serves.
+
+## What it looks for
+
+`dependencies` entries whose spec is `*`, `latest`, `x`, or empty — anything
+the registry can satisfy with a version that did not exist when the plugin
+was last reviewed. `^` and `~` ranges are **not** flagged: they are normal
+npm practice and stay within a reviewed major/minor.
+
+Only `dependencies` are checked; `devDependencies` do not execute on the
+installing user's machine.
+
+## Severity / confidence policy
+
+**medium / high** — the spec's supply-chain tier.
+
+## False positives
+
+Rare; the floating set is deliberately minimal. If an ecosystem convention
+emerges around another spec form, it gets listed here.
+
+## Remediation
+
+Pin to an exact version or a narrow range.

package/docs/rules/dep.install-scripts.md

@@ -0,0 +1,26 @@
+# dep.install-scripts
+
+Runs code at install time.
+
+## What it looks for
+
+`preinstall`, `install`, and `postinstall` entries in package.json
+`scripts`. These execute on the **installing** user's machine, before the
+plugin has been audited or sandboxed by anything.
+
+## Severity / confidence policy
+
+**medium / high.** Presence is a fact from the manifest. The spec calls
+install scripts without evident need *medium*; static analysis cannot see
+"need", so the finding carries a remediation instead of a guess.
+
+## False positives
+
+Genuine build-from-source cases (native modules). The remediation documents
+the expectation: explain the script in the README, or move the work to
+publish time.
+
+## Remediation
+
+Remove the lifecycle script, or move the work to a prepublish/build step and
+document why install-time execution is required.

package/docs/rules/dep.typosquat-proximity.md

@@ -0,0 +1,30 @@
+# dep.typosquat-proximity
+
+Dependency name is one or two edits from a popular `dsh-*` package.
+
+## What it looks for
+
+Each runtime dependency is compared (bounded Levenshtein distance) against a
+curated list of popular `dsh-*` package names. Every list entry is verified
+to exist on npm — a name that cannot be installed cannot be typosquatted —
+and the list is re-checked during calibration sweeps. Exact matches to a
+popular name are skipped.
+
+## Severity / confidence policy
+
+- Distance 1 (one insert/delete/substitute away): **high / medium.**
+- Distance 2: **low / medium** — reported, cannot lower a grade.
+
+Confidence stays medium because proximity is a heuristic, not proof: the
+dependency's repository, publisher, and download history decide.
+
+## False positives
+
+Legitimate adjacent names (a monorepo's `-cli`/`-core` companions, or a name
+that happens to differ by one edit). Dispute with the package's provenance
+and, if the name is established, it joins the popular list.
+
+## Remediation
+
+Verify the dependency is the package you mean — exact spelling, real
+repository, real publisher.

package/docs/rules/egress.outbound-endpoints.md

@@ -0,0 +1,29 @@
+# egress.outbound-endpoints
+
+Outbound endpoints the code can contact.
+
+## What it looks for
+
+Literal hosts and URLs passed to the network-client calls tracked by
+`perm.network-client`. One evidence entry per unique endpoint (URLs reduce
+to their host), sorted, with the first call site.
+
+## Severity / confidence policy
+
+**info / high.** This rule is inventory, never a judgment: contacting a host
+is not wrong, but every host is a data-flow decision the author owns, and
+consumers of the report deserve the list. Grading is left to
+`egress.secret-adjacent` when endpoints meet secret reads.
+
+Endpoints with non-literal (runtime-computed) targets cannot be listed —
+that gap shows up as `obf.dynamic-require`-style opacity elsewhere.
+
+## False positives
+
+Endpoints that are never contacted in practice (dead code paths) still
+appear; reachability from an entry point is visible in the report via
+`perm.unreachable-files`.
+
+## Remediation
+
+Document each endpoint in the README.

package/docs/rules/egress.secret-adjacent.md

@@ -0,0 +1,31 @@
+# egress.secret-adjacent
+
+Network calls reachable from code that reads secrets.
+
+## What it looks for
+
+Files that read secrets — `process.env`, `os.homedir()`, or credential-like
+file paths (`.env*`, `credentials`, `auth.json`, `token`, `.dsh/`, `.ssh`,
+`.npmrc`, `.netrc`) — and any network-client call in that file or in files
+statically reachable **from** it.
+
+## Severity / confidence policy
+
+- **high** severity. Secrets plus egress in one static graph is the shape of
+  exfiltration; it is also the shape of every API client that authenticates,
+  so severity stays at high, not critical — critical requires proof of data
+  flow, which static analysis does not have.
+- Confidence **medium** when the same file reads a secret and calls a
+  literal endpoint (the common, explainable API-client case); **low** when
+  the connection only exists through imports.
+
+## False positives
+
+Any legitimate authenticated client. This finding is the report's most
+important *signal, not verdict* case: read the endpoints, decide if the data
+flow matches the plugin's documented purpose.
+
+## Remediation
+
+Keep secret reads and network clients in separate modules, or document the
+intended data flow for each endpoint.

package/docs/rules/obf.charcode-chain.md

@@ -0,0 +1,24 @@
+# obf.charcode-chain
+
+Builds strings from character codes.
+
+## What it looks for
+
+`String.fromCharCode(...)` calls with 8+ numeric literal arguments. The
+finding's note shows the decoded preview, so the reviewer sees what is being
+hidden from grep.
+
+## Severity / confidence policy
+
+**medium / medium.** Building a readable string through charcodes is not a
+normal authoring pattern; there is a credible benign population (obfuscating
+game spoilers, license checks) small enough to justify the confidence.
+
+## False positives
+
+Table-driven encoders (font subsets, protocol codecs) that feed arrays, not
+inline literals — the literal-argument requirement excludes most of them.
+
+## Remediation
+
+Write the string literal directly.

package/docs/rules/obf.dynamic-require.md

@@ -0,0 +1,27 @@
+# obf.dynamic-require
+
+Loads modules through a computed specifier.
+
+## What it looks for
+
+`require(x)` and `import(x)` where `x` is not a plain string literal —
+runtime variables, or concatenations that static evaluation can recover
+(`'./mod-' + 'ule.js'`).
+
+## Severity / confidence policy
+
+- Concatenation that statically resolves to one value: **medium / medium.**
+  The loaded module is knowable, but the graph hides from naive review.
+- Fully runtime-dependent specifier: **medium / low** (ROADMAP D2 — depends
+  on runtime values, so it never lowers a grade by itself).
+
+## False positives
+
+Optional-dependency loaders (`require(name)` in a try/catch) and plugin
+systems that resolve names from config. Those are exactly the patterns the
+finding asks you to make visible — the specifier is recoverable, say it in
+the source.
+
+## Remediation
+
+Use plain specifiers so the module graph stays auditable.

package/docs/rules/obf.encoded-payload.md

@@ -0,0 +1,29 @@
+# obf.encoded-payload
+
+Long base64/hex string literals in shipped code.
+
+## What it looks for
+
+String literals of 48+ characters with no whitespace whose entire charset is
+base64 (letters + digits + `/` `=`, actually mixing cases with digits) or hex
+— and for hex, using at least 8 distinct characters. Palette and table data
+(think `8888…`, d3 category colors) reuse a handful of digits; encoded
+payloads use the alphabet broadly. The diversity floor was calibrated on the
+v0.1 ecosystem sweep ([calibration record](../calibration-v0.1.md)).
+
+## Severity / confidence policy
+
+**medium / low.** An encoded blob is often legitimate (fonts, hashes,
+fixtures) — hence low confidence: reported, never grade-affecting on its own.
+It matters when it sits next to `eval` or egress, which is exactly what a
+reviewer checks next.
+
+## False positives
+
+Sourcemaps-in-strings, embedded assets, test vectors. The finding is
+inventory for reviewers; a blob with a visible decoder gets disputed in one
+message.
+
+## Remediation
+
+Decode payloads to plain assets, or ship them as files a reviewer can open.

package/docs/rules/obf.eval-detect.md

@@ -0,0 +1,26 @@
+# obf.eval-detect
+
+Evaluates dynamically built code.
+
+## What it looks for
+
+`eval(...)` calls and `new Function(...)` constructions in shipped JS.
+
+## Severity / confidence policy
+
+- Argument is not a string literal (variable, concatenation, decoding result):
+  **medium / medium** — the spec's "eval of non-literal input" tier.
+- Argument is a constant string: **info / high** — inert (the code is visible
+  in the literal), still reported because eval-shaped code is where payload
+  injection starts.
+
+## False positives
+
+DSLs and template engines that genuinely need runtime compilation. Declare
+the case in your README; if the pattern is common enough, the rule learns a
+documented exception.
+
+## Remediation
+
+Replace `eval`/`new Function` with direct code; dynamic evaluation defeats
+static audit.

package/docs/rules/obf.unparseable.md

@@ -0,0 +1,25 @@
+# obf.unparseable
+
+Shipped JS files that no standard parser accepts.
+
+## What it looks for
+
+Files with a `.js`/`.mjs`/`.cjs` extension (or Node-shebang bin scripts) that
+fail to parse both as an ECMAScript module and as a script under acorn.
+
+## Severity / confidence policy
+
+**medium / high.** That the file does not parse is certain; what it actually
+runs is not. Shipped-unparseable JS usually means generated or deliberately
+mangled code that plain review tooling cannot see into — the finding asks
+for source that reviewers can read.
+
+## False positives
+
+New syntax acorn has not learned yet (bleeding-edge proposals), or files
+that are data with a misleading extension. Dispute with the syntax; the
+finder tracks acorn's version.
+
+## Remediation
+
+Ship parseable source, or source maps that let tooling see the real code.