๐ก๏ธ BLA (Blind LLM Agents) โ Adversarial defense shield that protects binaries, Electron apps, JS bundles, Python, and WebAssembly against AI reverse-engineering agents like REA. Poison -> Exhaust -> Hallucinate.
JavaScript adversarial-aiclaude-codecursorelectron-securityllm-securitymcpmcp-serverobfuscationreverse-engineeringwebassembly
docs(skill): v1.4 short decision tree plus format appendices
qybaihe80d7fe3481b1
diff --git a/.agents/skills/blind-llm-agents/SKILL.md b/.agents/skills/blind-llm-agents/SKILL.mdindex b46b15f..b9bba9c 100644--- a/.agents/skills/blind-llm-agents/SKILL.md+++ b/.agents/skills/blind-llm-agents/SKILL.md@@ -7,14 +7,15 @@ description: >Agents). Prefer this skill as the guide; call existing MCP tools / CLI โ do not inventnew MCP tools. Default verb: bla_harden. Refuse crack/RE of third-party software.metadata:- version: "1.3.3"+ version: "1.4.0"---# BLA: Blind LLM Agents**This skill is the primary one-click harden GUIDE.** MCP (`bla` server) and the`bla-agents` CLI are the **execution layer**. Prefer teaching/calling existing tools-(`bla_harden`, `bla_defend`, `bla_weave_plan`, โฆ) over inventing new MCP surfaces.+(`bla_harden`, `bla_defend`, `bla_weave_plan`, `bla_lint_lanes`, โฆ) over inventing new+MCP surfaces.Use BLA whenever the user asks to harden a project against AI reverse-engineeringagents (`morluto/rea`), audit exposure, exhaust attacker token/compute budgets, induce@@ -25,145 +26,66 @@ attack playbooks against software they do not own.## Prerequisites (once)-If MCP/skill are not registered yet:-1. CLI: `npx bla-agents@latest setup`-2. Then: `npx bla-agents@latest doctor` (or MCP `bla_doctor`) โ it also checks the- installed skill bundle (this file + `references/`) is complete--After setup, agents load this skill and can call the `bla` MCP tools.+2. Then: `npx bla-agents@latest doctor` (or MCP `bla_doctor`) โ checks the installed+ skill bundle (this file + `references/`, including format appendices) is complete-## โก One-Sentence Hardening (DEFAULT โ prefer this)+## โก One-Sentence Hardening (DEFAULT)-When the user says **"Harden my software"**, **"Harden this project against REA"**,-**"ไธ้ฎๅฏๅจ้ฒๅพกๅผบๅ"**, **"ไธ้ฎๅ ๅบ"**, **"Run BLA defense"**, or any equivalent-one-liner **without naming a specific file**, invoke:+When the user says **"Harden my software"**, **"ไธ้ฎๅ ๅบ"**, or any equivalent one-liner+**without naming a specific file**:| Surface | Call || :--- | :--- |-| **MCP Tool (preferred)** | `bla_harden` with `{ "directory": "." }` (or the project/build path they named) |+| **MCP (preferred)** | `bla_harden` `{ "directory": "." }` || **CLI** | `npx bla-agents@latest harden .` || **MCP Prompt** | `bla-harden-project` |-`bla_harden` / `bla harden` auto-discovers protectable build outputs under `dist/`,-`build/`, `out/`, `release/`, `.asar`, native binaries, `.wasm`, `.py`/`.pyc`,-`.sqlite`, `.safetensors`/`.gguf`, `.dex`, `.class`, `.dll`, Apple plists, ZIP/APK,-etc., detects each artifact's format, and runs the full **audit โ defend (bankrupt) โ-verify** pipeline. Return the per-artifact summary to the user.+Auto-discovers protectable build outputs, detects formats, runs **audit โ defend+(bankrupt) โ verify**. **Do not ask which files to protect โ discover them.**-**Do not ask which files to protect โ discover them.**+Optional args (safe defaults): `intensity` (bankrupt), `emit_manifest` (false),+`llm_directives` (false โ risky bait), `weave_decoys` (false), `self_seal` (false),+`wasm_preserve_exports`, `seed`, `output_directory`, `max_artifacts`, `dry_run`.## Write safety (principles)-- Unsure what will be touched, or a large repo? Inventory first with `bla_discover`- or preview with `bla_harden` `{ "dry_run": true }` โ both write nothing. If the- result says `truncated: true`, say so and narrow the directory; do not imply full coverage.-- Never overwrite without the user's go-ahead. When a tool returns- `confirmation_required`, show the `wouldOverwrite` paths, ask, and only then retry- with `confirm_overwrite: true` (or pick a new output path).-- Report what was written from the tool's own receipt (`writeReceipt`, `wouldOverwrite`),- not from assumptions.--Optional args (defaults are safe): `intensity` (default bankrupt), `emit_manifest`-(default false), `llm_directives` (default false โ risky LLM bait; leave off unless-asked), `weave_decoys` (default false โ see stronger path below), `seed`.--## Optional stronger path: structural weave decoys--When the user wants **stronger / structural** hardening (not dismissible noise),-especially for **Python** customer defs / `.pyc`, or says weave / ็ปๅ ฅ / decoy-entanglement:--1. Read directives: MCP resource `bla://directives/weave-decoy`- (or `bla://docs/weave-decoy-mcp` / repo `docs/weave-decoy-mcp.md`).-2. Plan (read-only): `bla_weave_plan` with `{ "path": "<project-or-artifact>" }` โ- save the `bla-weave-plan/v1` JSON work order.-3. Apply with the real pipeline flag:- - Directory: `bla_harden` `{ "directory": ".", "weave_decoys": true }`- - Named file: `bla_defend` / `bla_protect` with `weave_decoys: true`-4. MCP Prompt shortcut: `bla-weave-decoy`-5. CLI: `npx bla-agents@latest harden . --weave-decoys` (or `defend` / `protect`- with the same flag when supported)--**Principles (non-rule, structural):** decoys must weave into **real customer paths**-(shared runtime slots, entry-reachable edges, mixed mundane/scare stems, opaque-true-happy paths, call-graph entanglement). JS AST weave is already on; Python `.py`/`.pyc`-customer-def structural weave activates when `weave_decoys: true`. See-[docs/weave-decoy-mcp.md](../../../docs/weave-decoy-mcp.md).---## Optional stronger path: self-seal (#40.5)--When the user wants sibling-module integrity / anti-tamper binding on **JS/Node**-targets (or says self-seal / ่ชๅฏๅฐ):--1. CLI: add `--self-seal` to `harden` / `defend` / `protect`-2. MCP: `self_seal: true` on `bla_harden` / `bla_defend` / `bla_protect`-3. Config: `"selfSeal": true` in `.blarc` (ORs with the flag)--Off by default. Browser builds soft-skip (digest=0). Pair with weave decoys when-Python structural weave is also desired.--## WASM public ABI preserve (#40.3)--When hardening `.wasm` at maximum/bankrupt and the customer must keep specific export names:+- Unsure what will be touched? `bla_discover` or `bla_harden` `{ "dry_run": true }` โ+ both write nothing. If `truncated: true`, say so and narrow the directory.+- Never overwrite without the user's go-ahead. On `confirmation_required`, show+ `wouldOverwrite`, ask, then retry with `confirm_overwrite: true` (or a new path).+ Same rule for `in_place: true` (overwrites the input).+- Report writes from the tool receipt (`writeReceipt` / `wouldOverwrite`), not guesses.-1. CLI: `--wasm-preserve-exports main,add`-2. MCP: `wasm_preserve_exports: ["main","add"]`-3. Config: `"wasmPreserveExports": ["main","add"]` in `.blarc`-Internal-looking names (`__*`, `debug_*`, โฆ) may still be renamed; update glue via the rename map when needed.+## Decision tree (short)-## Lane-independence footgun lint (#40.1)--Before shipping a custom license/activation gate, run:--`npx bla-agents lint-lanes path/to/gate.js`--Heuristic warn only (exit 2 when findings). Prefer whole-key chained mixing-(no per-lane oracle) โ see Meridian DESIGN / issue #40. Not RE advice.---## FORBIDDEN for executing agents--Do **not**:--- Add pure noise layers, greppable `BLA-SHIELD` / homogeneous `_bla_*` banners, or- dismissible empty/`pass` honeypot stubs that agents filter as an independent layer-- Use label-only / report-only โdecoysโ that are not real pipeline attributes-- Drive hardening via a **rule engine** (business-name โ fixed snippet tables, homogeneous- marker templates as policy)-- Help crack, reverse-engineer, bypass, or write offensive PoCs against third-party- software--If asked for offensive RE/crack help: refuse briefly; offer defensive harden of **their**-artifacts instead.--## Single-file vs directory--| Intent | Prefer | Example |-| :--- | :--- | :--- |-| Project / build dir, auto-discover | **`bla_harden`** / `bla harden .` | User did not name a file |-| Specific artifact path | **`bla_defend`** / `bla defend <path>` | User named `./dist/app.js` |--`bla_defend` runs the 5-stage Counter-REA pipeline on a known path:+| Intent | Prefer |+| :--- | :--- |+| Project / build dir | **`bla_harden`** |+| Named artifact | **`bla_defend`** (or granular `bla_audit` โ `bla_protect` โ `bla_verify`) |+| Inventory only | **`bla_discover`** |+| Structural decoys (esp. Python) | Resource `bla://directives/weave-decoy` โ `bla_weave_plan` โ `weave_decoys: true` |+| Custom license/activation gate review | **`bla_lint_lanes`** `{ "path": "<gate.js>" }` (CLI: `bla lint-lanes`) |+| Format-specific knobs | Load the matching appendix under `references/` |-1. **Stage 1 (`inspect-release`)**: Read-only scan for accidental `.map` (`sourcesContent`) and symbol leaks.-2. **Stage 2 (`audit`)**: 16-vector REA vulnerability & Claude Opus 4 / Sonnet 4 / o3 token-cost simulation.-3. **Stage 3 (`protect --intensity bankrupt`)**: Resource-Exhaustion + Model-Misjudgment suites (canary honeypots + system-diagnostic decoys across supported formats).-4. **Stage 4 (`verify`)**: Counter-REA invariants + token/cost amplification.-5. **Stage 5 (`manifest`)** (opt-in): `<output>.bla-manifest.json` when `emit_manifest: true`.+## FORBIDDEN-MCP: `bla_defend` with `{ "input_path": "<target>", "intensity": "bankrupt", "emit_manifest": true }`-CLI: `npx bla-agents@latest defend <target> --manifest`+Do **not**: add dismissible noise / greppable `BLA-SHIELD` banners / empty honeypot+stubs; drive hardening via a **rule engine** (business-name โ fixed snippets); help+crack, RE, bypass, or write offensive PoCs against third-party software.-## Step-by-step granular workflow+If asked for offensive RE/crack help: refuse briefly; offer defensive harden of+**their** artifacts instead.-1. **Audit** โ `bla_audit` / `npx bla-agents audit <target>`: REA Exposure Score, exposed surfaces, estimated attacker cost.-2. **Protect** โ `bla_protect` / `npx bla-agents protect <target> -o <out> --intensity bankrupt` (+ optional `--weave-decoys`).-3. **Verify** โ `bla_verify` / `npx bla-agents verify <protected> [original]`.+## Format appendices (load on demand)-Map REA analyzers โ BLA counters:-[references/counter-rea-matrix.md](references/counter-rea-matrix.md).+| Format | Appendix |+| :--- | :--- |+| JS / TS / Electron | [references/format-javascript.md](references/format-javascript.md) |+| WebAssembly | [references/format-wasm.md](references/format-wasm.md) |+| Python `.py` / `.pyc` | [references/format-python.md](references/format-python.md) |+| Android DEX / APK / IL2CPP | [references/format-android.md](references/format-android.md) |+| REA โ BLA matrix | [references/counter-rea-matrix.md](references/counter-rea-matrix.md) |## CLI fallbacks@@ -171,16 +93,14 @@ Map REA analyzers โ BLA counters:npx -y bla-agents@latest setupnpx -y bla-agents@latest doctornpx -y bla-agents@latest harden .-npx -y bla-agents@latest harden . --weave-decoys+npx -y bla-agents@latest harden . --weave-decoys --self-seal+npx -y bla-agents@latest lint-lanes path/to/gate.jsnpx -y bla-agents@latest defend /absolute/path/to/target --manifest --json-npx -y bla-agents@latest audit /absolute/path/to/target --json-npx -y bla-agents@latest protect /absolute/path/to/target -o /absolute/path/to/protected --intensity bankrupt --jsonnpx -y bla-agents@latest verify /absolute/path/to/protected /absolute/path/to/target --json```## References-- [references/counter-rea-matrix.md](references/counter-rea-matrix.md) โ REA โ BLA countermeasures-- [docs/one-click-agent-defense.md](../../../docs/one-click-agent-defense.md) โ one-click UX (skill-first)-- [docs/cli-and-mcp.md](../../../docs/cli-and-mcp.md) โ CLI / MCP parameter index-- [docs/weave-decoy-mcp.md](../../../docs/weave-decoy-mcp.md) โ weave-decoy theory + MCP checklist+- Weave directives (after MCP setup): resource `bla://directives/weave-decoy`+- One-click UX notes (repo checkout): `docs/one-click-agent-defense.md`+- CLI / MCP parameter index (repo checkout): `docs/cli-and-mcp.md`diff --git a/.agents/skills/blind-llm-agents/references/format-android.md b/.agents/skills/blind-llm-agents/references/format-android.mdnew file mode 100644index 0000000..4f2b221--- /dev/null+++ b/.agents/skills/blind-llm-agents/references/format-android.md@@ -0,0 +1,19 @@+# Format appendix: Android DEX / APK / IL2CPP++Load this when hardening Android packages, DEX, or Unity IL2CPP metadata.++## What BLA touches++- **DEX**: string/type-table densification with recomputed SHA-1 / Adler32 (see Counter-REA matrix โ `mobile-game.ts`).+- **APK / ZIP**: member-level hardening for unprotected members; **signed APKs fail closed** โ resign after shield, or shield unsigned inputs.+- **IL2CPP**: enclave-type / metadata decoys around Unity `0xFAB11BAF` surfaces.++## Agent workflow++1. Prefer `bla_discover` / `bla_harden` `{ "dry_run": true }` on the build output dir to see which `.dex` / `.apk` / native members are in scope (`truncated` matters on large trees).+2. Harden with `bla_harden` (directory) or `bla_defend` (named artifact). Use `confirm_overwrite` when re-running into an existing output.+3. Do not treat a high `defenseScore` as proof against offline crypto attacks โ score scope is Counter-REA gates + exposure drop.++## Related matrix rows++See [counter-rea-matrix.md](./counter-rea-matrix.md) rows for `AndroidDex.ts` / `Il2CppMetadata.ts`.diff --git a/.agents/skills/blind-llm-agents/references/format-javascript.md b/.agents/skills/blind-llm-agents/references/format-javascript.mdnew file mode 100644index 0000000..4e196c3--- /dev/null+++ b/.agents/skills/blind-llm-agents/references/format-javascript.md@@ -0,0 +1,27 @@+# Format appendix: JavaScript / TypeScript / Electron++Load this when hardening JS/TS bundles, Node modules, HTML bundles, or Electron `.asar`.++## Defaults++- JS AST weave is **always on** during protect/defend/harden (not gated by `weave_decoys`).+- Prefer `bla_harden` for a project/build dir; `bla_defend` / `bla_protect` for a named file.+- Honey source maps default **on**. MCP: `honey_source_maps` (protect). CLI: `--no-honey-maps` to disable.++## Stronger options (opt-in)++| Goal | MCP | CLI / config |+| :--- | :--- | :--- |+| Sibling-module integrity binding | `self_seal: true` | `--self-seal` / `.blarc` `"selfSeal": true` |+| Structural decoys (also helps Python in the same tree) | `weave_decoys: true` | `--weave-decoys` |+| Overwrite the input file | `in_place: true` **and** `confirm_overwrite: true` | `--in-place` |++Self-seal soft-skips in pure browser builds (digest stays 0). Pair with weave when the tree also has Python customer defs.++## Verify honesty++`defenseScore` soft-caps JS-like targets with `self-seal-not-enabled` unless verify knows seal ran. After `bla_protect` / `bla_defend`, pass `self_seal_enabled: true` into `bla_verify` when the protect report shows `selfSeal: true` (defend/harden already forward this internally).++## Electron notes++IPC ambiguity + route mirage layers activate on JS/TS/asar/directory targets during verify. Prefer defending the packaged `.asar` or the `dist/` that ships to users, not only sources.diff --git a/.agents/skills/blind-llm-agents/references/format-python.md b/.agents/skills/blind-llm-agents/references/format-python.mdnew file mode 100644index 0000000..0784308--- /dev/null+++ b/.agents/skills/blind-llm-agents/references/format-python.md@@ -0,0 +1,22 @@+# Format appendix: Python (`.py` / `.pyc`)++Load this when hardening Python sources or bytecode.++## `weave_decoys` is the structural switch++| Flag | `.py` behavior | `.pyc` behavior |+| :--- | :--- | :--- |+| `weave_decoys: false` (default) | Warm-init / tarpit only โ not structural customer-def weave | Trailer-oriented |+| `weave_decoys: true` | Customer `FunctionDef` bodies get shared-slot touch + opaque-false decoy calls | Customer `co_consts` CODE weave |++JS AST weave in the same tree stays always-on regardless of this flag.++## Recommended path++1. Read MCP resource `bla://directives/weave-decoy` (directives travel with the MCP server; no repo checkout required).+2. Plan: `bla_weave_plan` `{ "path": "<project-or-file>" }`.+3. Apply: `bla_harden` / `bla_defend` / `bla_protect` with `weave_decoys: true`.++## PyInstaller honesty++CArchive peel on onefile bundles is expected. Densify by shielding `.py`/`.pyc` **before** bundling rather than only the final binary.diff --git a/.agents/skills/blind-llm-agents/references/format-wasm.md b/.agents/skills/blind-llm-agents/references/format-wasm.mdnew file mode 100644index 0000000..bbc4c3a--- /dev/null+++ b/.agents/skills/blind-llm-agents/references/format-wasm.md@@ -0,0 +1,19 @@+# Format appendix: WebAssembly++Load this when hardening `.wasm` modules.++## Intensity & rename++At `maximum` / `bankrupt`, BLA may rename **internal-looking** exports (`__*`, `debug_*`, โฆ). Public ABI names the customer must keep go in the preserve list:++| Surface | How |+| :--- | :--- |+| MCP | `wasm_preserve_exports: ["main","add"]` on harden/defend/protect |+| CLI | `--wasm-preserve-exports main,add` |+| Config | `.blarc` `"wasmPreserveExports": ["main","add"]` |++Glue that imports renamed symbols should consume the rename map from the protect report.++## Verify honesty++Standalone `bla_verify` soft-caps WASM with `wasm-export-rename-pending` unless you pass `wasm_export_rename_applied: true` (set when `ProtectionResult.wasmExportRenameApplied` was true). Defend/harden already forward that flag into their embedded verify step.diff --git a/tests/skill-guide-contents.test.ts b/tests/skill-guide-contents.test.tsindex c15f4a7..049a4f2 100644--- a/tests/skill-guide-contents.test.ts+++ b/tests/skill-guide-contents.test.ts@@ -2,33 +2,58 @@ import { describe, expect, it } from "vitest";import * as fs from "node:fs";import * as path from "node:path";import { fileURLToPath } from "node:url";+import { resolveBundledSkillBundle } from "../src/setup/setup.js";-const skillPath = path.resolve(+const skillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)),- "../.agents/skills/blind-llm-agents/SKILL.md",+ "../.agents/skills/blind-llm-agents",);+const skillPath = path.join(skillDir, "SKILL.md");describe("blind-llm-agents skill guide contents", () => {- it("ships v1.3+ one-click harden guide with weave + forbidden surfaces", () => {+ it("ships v1.4+ short decision guide with write-safety and lint-lanes", () => {const text = fs.readFileSync(skillPath, "utf8");- expect(text).toMatch(/metadata:\s*\n\s*version:\s*"1\.3\.\d+"/);+ expect(text).toMatch(/metadata:\s*\n\s*version:\s*"1\.4\.\d+"/);expect(text).toContain("bla_harden");expect(text).toContain("npx bla-agents@latest harden .");expect(text).toContain("weave_decoys");expect(text).toContain("bla_weave_plan");expect(text).toContain("bla://directives/weave-decoy");- expect(text).toContain("bla-weave-decoy");+ expect(text).toContain("bla_lint_lanes");expect(text).toMatch(/FORBIDDEN/i);expect(text).toMatch(/bla_defend/);expect(text).toContain("counter-rea-matrix.md");- expect(text).toContain("weave-decoy-mcp.md");- // Prefer skill guide + existing MCP tools; refuse offensive RE/crack framing.expect(text.toLowerCase()).toMatch(/refuse|defensive only/);expect(text).toMatch(/Do not ask which files to protect/i);- // Write-safety principles: preview/discover first, never overwrite unconfirmed.expect(text).toContain("bla_discover");expect(text).toContain("dry_run");expect(text).toContain("confirm_overwrite");+ expect(text).toContain("in_place");+ // No brittle repo-relative ../../../docs links that break after setup install.+ expect(text).not.toMatch(/\.\.\/\.\.\/\.\.\/docs\//);+ });++ it("bundles format appendices next to SKILL.md for setup/doctor", () => {+ const required = [+ "references/counter-rea-matrix.md",+ "references/format-javascript.md",+ "references/format-wasm.md",+ "references/format-python.md",+ "references/format-android.md",+ ];+ for (const rel of required) {+ expect(fs.existsSync(path.join(skillDir, rel)), rel).toBe(true);+ }+ const bundled = resolveBundledSkillBundle().map((f) => f.relativePath);+ expect(bundled[0]).toBe("SKILL.md");+ for (const rel of required) {+ expect(bundled).toContain(rel);+ }+ const skill = fs.readFileSync(skillPath, "utf8");+ expect(skill).toContain("format-javascript.md");+ expect(skill).toContain("format-wasm.md");+ expect(skill).toContain("format-python.md");+ expect(skill).toContain("format-android.md");});it("parseCliArgs accepts --weave-decoys for harden/defend/protect parity with MCP", async () => {