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): add write-safety principles (discover/dry-run first, confirm before overwrite) and document new MCP params

qybaihe009e29da042c
diff --git a/.agents/skills/blind-llm-agents/SKILL.md b/.agents/skills/blind-llm-agents/SKILL.md
index b5775f7..b46b15f 100644
--- a/.agents/skills/blind-llm-agents/SKILL.md
+++ b/.agents/skills/blind-llm-agents/SKILL.md
@@ -7,7 +7,7 @@ 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.2"
+ version: "1.3.3"
---
# BLA: Blind LLM Agents
@@ -28,7 +28,8 @@ attack playbooks against software they do not own.
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`)
+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.
@@ -52,6 +53,17 @@ verify** pipeline. Return the per-artifact summary to the user.
**Do not ask which files to protect β€” discover them.**
+## 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`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2efdc42..4b1861e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- **Agent write safety (MCP/Skill 2.0, stage A):** read-only `bla_discover`; `bla_harden` `dry_run` (CLI `harden --dry-run`) writes zero bytes and reports `truncated` / `wouldOverwrite`; `bla_harden` / `bla_defend` / `bla_protect` refuse to overwrite existing outputs without `confirm_overwrite: true` and return a `writeReceipt`.
+- **Full skill bundle install:** `bla setup` installs `SKILL.md` plus `references/` (counter-rea-matrix); `bla doctor` reports `skillMissingFiles` / `skillModifiedFiles` and fails on an incomplete bundle; uninstall removes owned bundle files.
- **Self-seal (#40.5):** opt-in CLI `--self-seal` / MCP `self_seal` / `.blarc selfSeal` injects Node sibling-module + env-fingerprint integrity binding into JS AST shield and entangles the opaque-predicate seed.
- **WASM preserve ABI (#40.3):** `.blarc`/`CLI`/`MCP` `wasmPreserveExports` / `--wasm-preserve-exports` / `wasm_preserve_exports` keeps listed export names when rename runs.
- **WASM export rename (#40.3):** `protectWasmBinary` renames internal-looking exports at maximum/bankrupt (preserve public ABI via `preserveExports`); returns `exportsRenamed`.
diff --git a/docs/cli-and-mcp.md b/docs/cli-and-mcp.md
index 34ea42e..76b2ddb 100644
--- a/docs/cli-and-mcp.md
+++ b/docs/cli-and-mcp.md
@@ -20,16 +20,25 @@ For coding agents, the **[`blind-llm-agents` skill](../.agents/skills/blind-llm-
## MCP Tools (`bla` Server)
-- `bla_harden`: Preferred one-sentence harden of a project directory (`directory`, `intensity`, `emit_manifest` default false, `llm_directives` default false, `weave_decoys` default false, `seed`).
-- `bla_defend`: Full Counter-REA pipeline on a known path (`input_path`, `output_path`, `intensity`, `emit_manifest` default false, `llm_directives` default false, `weave_decoys` default false, `seed`).
+- `bla_harden`: Preferred one-sentence harden of a project directory (`directory`, `intensity`, `emit_manifest` default false, `llm_directives` default false, `weave_decoys` default false, `seed`, `dry_run` default false, `max_artifacts` default 64, `confirm_overwrite` default false). The report carries `dryRun`, `truncated`, `maxArtifacts` and `wouldOverwrite`.
+- `bla_discover`: Read-only inventory using the same discovery as `bla_harden` (`directory`, `max_artifacts`) β†’ `{ directory, artifacts[{path, relativePath, format}], truncated, maxArtifacts }`. Writes nothing.
+- `bla_defend`: Full Counter-REA pipeline on a known path (`input_path`, `output_path`, `intensity`, `emit_manifest` default false, `llm_directives` default false, `weave_decoys` default false, `seed`, `confirm_overwrite` default false).
- `bla_audit`: Pre-flight REA exposure and token-economics audit (`path`).
-- `bla_protect`: Granular shield injection (`input_path`, `output_path`, `intensity`, `seed`, `llm_directives` default false, `weave_decoys` default false).
+- `bla_protect`: Granular shield injection (`input_path`, `output_path`, `intensity`, `seed`, `llm_directives` default false, `weave_decoys` default false, `confirm_overwrite` default false).
+- `bla_doctor`: also reports `skillMissingFiles` / `skillModifiedFiles` per client; a missing bundle file (e.g. `references/counter-rea-matrix.md`) fails the client.
- `bla_verify`: Counter-REA invariant verification (`target_path`, `original_path`).
- `bla_benchmark`: Runs the 8-target showcase benchmark suite.
- `bla_emit_headers`: Generates C/C++, Rust, or Go defense headers (`language`, `intensity`).
- `bla_doctor`: Diagnostics for BLA engines and agent client registrations.
- `bla_weave_plan`: Read-only weave-decoy planner (`path`, optional `max_targets`) β†’ `bla-weave-plan/v1` JSON (defensive theory checklist; no crack/RE).
+### Write safety (dry-run, confirmation, receipts)
+
+- `bla_harden` with `dry_run: true` (CLI `bla harden . --dry-run`) discovers targets and plans outputs with **zero bytes written** (no `.bla-hardened/`, no summary, no `.blarc` seed).
+- Discovery is capped (`max_artifacts`, default 64); when more targets exist the result sets `truncated: true` instead of silently dropping them.
+- `bla_harden` / `bla_defend` / `bla_protect` refuse to overwrite an existing output file unless `confirm_overwrite: true`. A refusal is `isError: true` with `{ status: "confirmation_required", wouldOverwrite: [...], wrote: [] }`; nothing is written.
+- Successful `bla_defend` / `bla_protect` calls add `writeReceipt: { status: "written", wrote, overwrote, confirmed }`. In-place overwrite of the input stays CLI-only (`--in-place`).
+
`weave_decoys: true` activates structural Python customer-def weave (shared-slot touch + opaque-false decoy calls) after the #51 tarpit; when false, Python stays warm-init-only. JS AST weave remains always-on.
Project config parity: set `"weaveDecoys": true` in `.blarc` / `bla.config.json` (schema `bla.config.v1.json`) to enable the same flag without repeating `--weave-decoys` / MCP `weave_decoys` on every invoke. CLI/MCP flags still OR with the config value.
diff --git a/tests/skill-guide-contents.test.ts b/tests/skill-guide-contents.test.ts
index 8ada0d4..c15f4a7 100644
--- a/tests/skill-guide-contents.test.ts
+++ b/tests/skill-guide-contents.test.ts
@@ -25,6 +25,10 @@ describe("blind-llm-agents skill guide contents", () => {
// 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");
});
it("parseCliArgs accepts --weave-decoys for harden/defend/protect parity with MCP", async () => {