berry-shield

🍓 Berry Shield - Security plugin for OpenClaw

🧐 Why this exists

Berry Shield was created from a practical problem: during routine setup checks, the agent could expose sensitive data directly in chat (API keys, tokens, SSH material, and other secrets).

Typical examples included:

reading config files that contained credentials (openclaw.json, .env, cloud credentials)
returning sensitive command/file output without sanitization
exposing private paths or secret-bearing content in normal troubleshooting flows

Design principles:

Agents can read or execute sensitive operations by mistake.
Prompt-only guardrails are not enough in real runtimes.
Security controls must be visible, configurable, and testable from CLI.

The goal of Berry Shield is to reduce that risk in day-to-day usage by adding guardrails for access checks, runtime blocking, and output redaction.

---

What it is / What it is not

✓ What it is

Berry Shield is an OpenClaw plugin that adds layered guardrails, audit, and redaction for agent workflows.
Enforces a pre-flight security gate with berry_check before risky operations.
Intercepts tool calls and blocks destructive or sensitive access patterns.
Scans and redacts sensitive output before persistence and outbound delivery.
Supports enforce and audit modes for rollout and validation.
Provides CLI management for status, mode, policy, layers, rules, and report.

✗ What it is not

Not a sandbox, VM, container isolation, or kernel boundary.
Not a replacement for host hardening, least privilege, or secrets management.
Not a guarantee against fully compromised hosts or malicious dependencies.

---

🧭 When to use / When not to use

Use Berry Shield when

Your agent has command/file capabilities and you need to reduce accidental leakage.
You operate on chat surfaces where unsafe output can be exposed quickly.
You need auditability for security decisions (allowed, blocked, redacted, would_*).

Do not use Berry Shield as

The only security boundary in untrusted multi-tenant environments.
A compliance silver bullet without operational governance.

---

⚡ 90-second demo

Baseline runtime state before the demo (plugin enabled, enforce mode, all core layers active):

---

1) Enforce: external-risk action is blocked Watch demo: Vine Layer

> In chat/runtime: ingest external content with web_fetch, then preflight an exec write

Expected: denied in enforce after external untrusted ingestion.

---

2) Audit: same flow is allowed but logged as would_block Watch demo: Vine Layer

> Same write-like operation under audit mode

Expected: allowed execution plus would_block evidence in report/audit logs.

---

3) Sensitive file read is blocked (Stem)

Expected: denied read when attempting to access protected files.

Runtime evidence:

2026-02-27T15:53:59.195Z [gateway] [berry-shield] Berry.Stem: DENIED read - sensitive file: /home/zyn/.openclaw/openclaw.json

---

4) Redaction: sensitive output is sanitized (Pulp)

openclaw config get channels.telegram

Expected: sensitive fields are masked in tool output, e.g. botToken becomes [BOTTOKEN_REDACTED].

Why this matters: even read-only tools can still return sensitive values during normal operations. Operator intent ("do not expose secrets") is useful, but not sufficient by itself; protection must happen in the output path.

Implementation basis:

Berry.Pulp scans tool outputs at tool_result_persist and redacts matched secrets/PII before transcript persistence.
Berry.Pulp also scans message_sending to redact sensitive data in outgoing assistant messages when supported by runtime hooks.
In audit, events are logged as would_redact; in enforce, values are actively redacted.

Evidence (real redacted output):

{
  "enabled": true,
  "dmPolicy": "pairing",
  "botToken": "[BOTTOKEN_REDACTED]",
  "groupPolicy": "allowlist",
  "streaming": "partial"
}

---

⚡ Quickstart

Install from npm package:

openclaw plugins install @f4bioo/berry-shield

---

🛡️ Security Audit & Installation Notice

> [!WARNING] > Expected heuristic warnings: > During openclaw plugins install, OpenClaw may flag patterns such as child_process usage and environment-based runtime resolution. > In Berry Shield, these patterns are used for legitimate host integration (OpenClaw CLI/config bridge), not hidden execution paths. > > This is a heuristic warning, not a malware verdict. > For a code-level mapping of each warning, see Security Audit.

Note: Berry Shield is plug-and-play after install. No extra setup is required for baseline protection.

---

See more:

Berry Shield Installation guide

---

Note: If you want to customize mode, layers, or policy, use:

openclaw bshield --help

See more:

Berry Shield CLI reference

---

🧠 Mental model (single flow)

Berry Shield is designed with multiple layers. The idea is that if an interaction isn't caught by one layer, it might be caught by another.

🧬 Layers in plain language

See more:

Berry Shield layers

---

⚙️ Modes and profiles

Modes (`mode`)

Profiles (`policy.profile`)

See more:

Berry Shield modes and profiles

---

🚧 Technical Limitations & SDK Diary

Berry Shield's effectiveness is tied to the underlying OpenClaw SDK capabilities. We maintain a detailed diary that tracks known bugs and blind spots across OpenClaw versions.

Key Points for v2026.3.13:

Hook Reliability: In our v2026.3.13 checkpoint, before_tool_call and message_sending were observed as functional, but hook behavior remains runtime/version-dependent.
Soft Guardrails: Prompt-based defenses (Berry.Root) are advisory and can be bypassed by clever user instructions.
Timing Gaps: Redaction happens during persistence, which might create a transient data exposure.
Host Hook Behavior: If the host explicitly disables prompt-injection style prepend behavior for plugin hooks, Berry.Root guidance and Vine reminder text from before_agent_start can be partially degraded. This should be treated as host-configurable behavior, not as evidence that Berry Shield runtime protection is broken.

See more:

---

📚 Docs map

Wiki overview: docs/wiki/README.md
Install and deploy: docs/wiki/deploy/installation.md
CLI commands: docs/wiki/operation/cli/README.md
Layer internals: docs/wiki/layers/README.md
Mode/profile decisions: docs/wiki/decision/modes.md
Pattern strategy: docs/wiki/decision/patterns.md
Tutorials: docs/wiki/tutorials/README.md

---

⚖️ License

Apache-2.0. See LICENSE.

For contributor workflow and internal quality process, see CONTRIBUTING.md.

Summary

Install to Claude Code

🍓 Berry Shield - Security plugin for OpenClaw

🧐 Why this exists

What it is / What it is not

✓ What it is

✗ What it is not

🧭 When to use / When not to use

Use Berry Shield when

Do not use Berry Shield as

⚡ 90-second demo

1) Enforce: external-risk action is blocked Watch demo: Vine Layer

2) Audit: same flow is allowed but logged as would_block Watch demo: Vine Layer

3) Sensitive file read is blocked (Stem)

4) Redaction: sensitive output is sanitized (Pulp)

⚡ Quickstart

🛡️ Security Audit & Installation Notice

🧠 Mental model (single flow)

🧬 Layers in plain language

⚙️ Modes and profiles

Modes (`mode`)

Profiles (`policy.profile`)

🚧 Technical Limitations & SDK Diary

Key Points for v2026.3.13:

📚 Docs map

⚖️ License

Related plugins

berry-shield

Summary

Install to Claude Code

🍓 Berry Shield - Security plugin for OpenClaw

🧐 Why this exists

What it is / What it is not

✓ What it is

✗ What it is not

🧭 When to use / When not to use

Use Berry Shield when

Do not use Berry Shield as

⚡ 90-second demo

1) Enforce: external-risk action is blocked Watch demo: Vine Layer

2) Audit: same flow is allowed but logged as would_block Watch demo: Vine Layer

3) Sensitive file read is blocked (Stem)

4) Redaction: sensitive output is sanitized (Pulp)

⚡ Quickstart

🛡️ Security Audit & Installation Notice

🧠 Mental model (single flow)

🧬 Layers in plain language

⚙️ Modes and profiles

Modes (mode)

Profiles (policy.profile)

🚧 Technical Limitations & SDK Diary

Key Points for v2026.3.13:

📚 Docs map

⚖️ License

Related plugins

Modes (`mode`)

Profiles (`policy.profile`)