Skip to content

armgit / bla

Public Imported from GitHub
0

๐Ÿ›ก๏ธ 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.

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.md
index 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 invent
new 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-engineering
agents (`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 setup
npx -y bla-agents@latest doctor
npx -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.js
npx -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 --json
npx -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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
index 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 () => {