# BLA (`bla-agents`) — Complete Technical Reference for LLMs & Coding Agents - **Official Website**: https://bla.tools/ - **GitHub Repository**: https://github.com/qybaihe/bla - **npm Package**: https://www.npmjs.com/package/bla-agents (aliases: `bla`, `bla-agents`, `bla-shield`) - **License**: MIT - **Node.js Runtime Floor**: `^22.23.4 || >=24.0.0` (uses built-in `node:sqlite` and `node:crypto` with minimal dependencies) ## 1. What Problem BLA Solves Modern AI reverse-engineering agents (e.g., `morluto/rea`) connect LLMs to Ghidra, IDA Pro, Hopper, V8 Inspector/CDP, Frida, `node:sqlite`, and binary parsers over the Model Context Protocol (MCP). Standalone legacy obfuscation (such as single-pass control-flow flattening or textbook `x*(x+1)&1` opaque predicates) is routinely simplified by frontier reasoning models. **BLA (`bla-agents` — Blind LLM Agents)** is the defensive Blue Team counterpart: 1. **Packaging Footgun Gates (`bla lint` / `bla_lint`)**: Fails closed before shipping if source maps, plaintext secrets, reversible seal sidecars, offline byte-by-byte verification oracles, `.env` / PEM keys, `SOLUTION.txt`, or unstripped `.pdb`/`.dSYM` debug symbols are present. 2. **Surgical Resource Exhaustion**: Saturates static/dynamic analyzer budgets (`obligation-flooder`, strongly connected `callgraph-labyrinth`, BPE token amplification, CDP object-shape budget guards, Frida capture saturators). 3. **Parameterized MBA & Multi-Layer Entanglement**: Applies Newton-Raphson parameterized affine Mixed Boolean-Arithmetic (MBA) instruction substitutions over Z_{2^32} and unsigned-domain MBA predicates, plus Agent-Driven Structural Weave (`bla_weave_plan` + `bla_verify_weave`) coupling business logic with shared mutable state. 4. **Multi-Round Hypothesis-Revision Decoys**: Plants warm-executed, non-crashing shadow business logic and hardware-enclave delegation mirages that survive static-vs-dynamic evidence arbitration. 5. **Runtime Self-Seal & Sidecar Entanglement (`--self-seal`, `--sidecar-entangle`)**: Enforces process-start canonical self-digest and sibling artifact SHA-256 verification across CommonJS, ES Modules (`.mjs` / `"type": "module"`), Python, Electron ASAR, and host-verifiable notes for WASM, `.pyc`, GGUF, Safetensors, and Bun standalone binaries. ## 2. Supported Artifact Formats (26 Formats) - **Web, Node.js & Desktop**: JavaScript (CommonJS & ES Modules), TypeScript (`.ts`/`.tsx`), HTML bundles, Source Maps (`.map`), Electron `.asar` archives & Electron Fuses, Bun standalone executables. - **Native & Compile-Time Headers**: ELF64 executables & shared libraries (`.so` mapped `.enclave` `PT_LOAD` decoy islands + `W^X`), Mach-O / Universal FAT binaries, Windows PE32/PE32+ (`.exe`/`.dll`), Go/Flutter symbol & buildinfo shields, plus compile-time C/C++, Rust, and Go headers (`bla emit-headers --lang c|rust|go`). - **Virtual Machines & Bytecode**: WebAssembly (`.wasm`), Python source (`.py`) & CPython bytecode (`.pyc`), Android Dalvik (`.dex`), APK/AAB/IPA/JAR archives, Android binary `AndroidManifest.xml`, R8/ProGuard dictionaries, JVM `.class`, .NET CLR managed assemblies, Erlang/OTP `.beam`, EVM Solidity bytecode. - **Data, Firmware & Edge AI Models**: SQLite databases (`.sqlite`/`.db`), Safetensors (`.safetensors` — bit-exact tensor preservation), GGUF v2/v3 (`.gguf` — alignment-preserving metadata shield), Apple PropertyLists (`.plist`), UF2 firmware, NVIDIA PTX modules (`.ptx`), and `libpcap` captures (`.pcap`). ## 3. Core CLI Commands ```bash # 1. Auto-register MCP server & agent skill for Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Antigravity npx bla-agents setup --all-detected -y # 2. Recommended 4-stage Agent-Driven Hardening workflow npx bla-agents lint . npx bla-agents weave-plan ./src npx bla-agents verify-weave ./src npx bla-agents harden . --weave-decoys --self-seal --sidecar-entangle # 3. Single-target one-click defense + signed Ed25519 manifest npx bla-agents defend ./dist --manifest npx bla-agents verify-manifest ./dist/.bla-manifest.json --public-key pub.pem --require-pinned-key npx bla-agents verify-sidecar ./dist/core.wasm # 4. Compile-time C/Rust/Go headers for native builds npx bla-agents emit-headers --lang rust -o src/bla_shield.rs # 5. Environment & MCP readiness diagnostics npx bla-agents doctor ``` ## 4. Bundler Integration (`bla-agents/bundler`) ```ts // vite.config.ts import { defineConfig } from "vite"; import { blaVitePlugin } from "bla-agents/bundler"; export default defineConfig({ plugins: [blaVitePlugin({ intensity: "balanced" })], }); ``` Also exports `blaRollupPlugin`, `blaWebpackPlugin`, and `blaEsbuildPlugin`. ## 5. Honesty Red Line (Security Boundaries) BLA enforces strict defense-score honesty (`src/engine/defense-score-honesty.ts`): - Client-side obfuscation and tarpits raise automated reverse-engineering cost and induce model misjudgment; they **never** replace server-side authentication, authorization, or secret custody. - Never ship real API keys, private keys, or master secrets inside client artifacts. - Post-link native binary shields and host-verified metadata notes (`wasm`, `pyc`, `gguf`, `safetensors`, `bun`) report honest score caps rather than claiming compile-time CFG rewriting or OS loader enforcement.