@f4bioo/berry-shield 2026.3.3-1

package/docs/wiki/layers/stem.md

@@ -0,0 +1,139 @@
+---
+summary: "Layer reference for Berry.Stem (security gate tool for exec/read/write decisions)"
+read_when:
+  - You need to understand how pre-operation deny/allow decisions are made
+  - You are validating audit vs enforce behavior on operation checks
+  - You are debugging why an operation was denied or allowed
+title: "stem"
+---
+
+# `Berry.Stem`
+
+Berry.Stem is the **security gate tool layer**.
+
+It registers the gate tool used by the agent before risky operations.
+The tool evaluates operation intent (exec, read, write) against destructive-command and sensitive-file patterns.
+
+## What Stem does
+
+- Registers the gate tool for operation checks.
+- Validates tool input schema (operation + target + optional session key).
+- Evaluates:
+  - destructive command intent in exec requests
+  - sensitive file references in exec requests
+  - sensitive file access in read/write requests
+- Emits structured audit events in both audit and enforce paths.
+- Returns allow/deny response payloads to the agent.
+- Triggers adaptive escalation signaling on enforce denies.
+
+## What Stem does not do
+
+- It does not directly execute shell or file operations.
+- It does not redact output text.
+- It does not depend on before_tool_call hook availability.
+- It does not guarantee model compliance by itself; it provides gate decisions the model should follow.
+
+## Runtime flow
+
+```mermaid
+flowchart TD
+    A[Agent requests gate check] --> B[Berry.Stem]
+    B --> C{Input valid?}
+    C -->|No| E[Reject request]
+    C -->|Yes| D{Risk match?}
+    D -->|No| ALLOW[Return ALLOWED]
+    D -->|Yes + audit| WB[Emit would_block event]
+    D -->|Yes + enforce| DENY[Return DENIED + blocked event]
+    WB --> ALLOW
+    DENY --> ESC[Adaptive escalation signal]
+```
+
+## Decision inputs
+
+Stem consumes:
+- operation type (exec, read, write)
+- target string (command or file path)
+- optional session key for adaptive escalation binding
+- effective sensitive/destructive pattern sets (built-in + custom)
+- runtime mode (audit or enforce)
+
+## Decision behavior (high level)
+
+### Exec operation
+- checks destructive command patterns
+- checks sensitive file references inside command target
+- audit: records observation and returns allow path
+- enforce: records blocked decision and returns denied response
+
+### Read or write operation
+- checks sensitive file patterns against target path
+- audit: records observation and returns allow path
+- enforce: records blocked decision and returns denied response
+
+### Adaptive escalation signal
+- on enforce deny, signals policy runtime state
+- prefers session-scoped escalation when session key exists
+- can use configured global escalation fallback when session key is missing
+
+## How Stem interacts with other layers
+
+### With Root
+- Root injects policy guidance that instructs the agent to call the gate tool first.
+- Stem returns concrete allow/deny decisions.
+- Root improves calling discipline; Stem provides operational gate outcomes.
+
+### With Thorn
+- Thorn can block direct tool calls via hook path where available.
+- Stem remains valuable as a tool-level gate even when hook coverage varies.
+
+### With Pulp
+- Stem controls operation permission before execution.
+- Pulp controls output sanitation after content exists.
+
+### With Leaf
+- Leaf provides inbound sensitive-input observability.
+- Stem provides operation-time gate decisions.
+
+## Operational value
+
+Stem is useful for:
+- pre-operation control independent of hook wiring variability
+- deterministic deny messages for risky operations
+- unified gate behavior for exec/read/write checks
+- adaptive policy escalation signals tied to denied actions
+
+## Limits and caveats
+
+- Gate effectiveness depends on the agent actually calling the gate tool before operation attempts.
+- Pattern matching is heuristic; coverage quality depends on pattern sets.
+- Command-string analysis may miss some complex indirect execution forms.
+- Enforce/audit behavior must be interpreted together with runtime mode and policy profile.
+
+## Validation checklist
+
+1. Run gate check for benign target and confirm ALLOWED response.
+2. Run gate check for sensitive read target and confirm:
+   - enforce: denied path
+   - audit: observation event + allow path
+3. Run gate check for destructive exec target and confirm mode-specific outcome.
+4. Validate report output reflects expected blocked/observation counts.
+
+## See layers
+
+- [root](root.md)
+- [thorn](thorn.md)
+- [pulp](pulp.md)
+- [leaf](leaf.md)
+
+## Related pages
+- [layers index](README.md)
+- [decision modes](../decision/modes.md)
+- [decision patterns](../decision/patterns.md)
+- [CLI test](../operation/cli/test.md)
+- [CLI report](../operation/cli/report.md)
+
+---
+
+## Navigation
+- [Back to Layers Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/layers/thorn.md

@@ -0,0 +1,139 @@
+---
+summary: "Layer reference for Berry.Thorn (pre-tool-call interception and blocking when hook is available)"
+read_when:
+  - You need to understand hook-level blocking behavior
+  - You are validating runtime interception before tool execution
+  - You are debugging blockReason results from tool-call interception
+title: "thorn"
+---
+
+# `Berry.Thorn`
+
+Berry.Thorn is the **hook-level tool blocker layer**.
+
+It intercepts tool calls before execution and evaluates command/path intent against risk patterns.
+When risk is detected, behavior depends on runtime mode.
+
+## What Thorn does
+
+- Hooks into before_tool_call.
+- Extracts command candidates from tool params for execution-like calls.
+- Extracts file path candidates from tool params for file-like calls.
+- Matches candidates against destructive-command and sensitive-file patterns.
+- Emits structured audit events in both audit and enforce paths.
+- In enforce, can return block response with block reason.
+- Signals adaptive escalation on enforce denies.
+
+## What Thorn does not do
+
+- It does not execute tools.
+- It does not redact output content.
+- It does not replace the gate tool path from Stem.
+- It is only effective when before_tool_call is available/invoked in host runtime.
+
+## Runtime flow
+
+```mermaid
+flowchart TD
+    A[Tool call attempt] --> H[Hook: before_tool_call]
+    H --> T[Berry.Thorn]
+    T --> X{Candidate extracted?}
+    X -->|No| PASS[Allow call path]
+    X -->|Yes| M{Risk match?}
+    M -->|No| PASS
+    M -->|Yes + audit| WB[Emit would_block event]
+    M -->|Yes + enforce| BLK[Return block + blocked event]
+    WB --> PASS
+    BLK --> ESC[Adaptive escalation signal]
+```
+
+## Decision inputs
+
+Thorn consumes:
+- tool name
+- tool params payload
+- optional session key from hook context
+- effective destructive and sensitive-file pattern sets
+- runtime mode (audit or enforce)
+
+## Decision behavior (high level)
+
+### Destructive command path
+- command candidate extracted from known command fields
+- if destructive pattern match:
+  - audit: record observation and allow path
+  - enforce: return block response with security reason
+
+### Sensitive file reference in command path
+- command text also checked for sensitive file references
+- same audit/enforce split as above
+
+### Sensitive file access path
+- file path candidate extracted for file-like tools
+- if sensitive path match:
+  - audit: record observation and allow path
+  - enforce: return block response with security reason
+
+### Adaptive escalation signal
+- on enforce block, sends denied signal to policy runtime state
+- prefers session-scoped escalation when session key exists
+- optional configured global escalation fallback when session key is missing
+
+## How Thorn interacts with other layers
+
+### With Stem
+- Thorn is hook-based interception.
+- Stem is tool-based security gate.
+- They are complementary: Stem covers gate-tool path even if hook coverage varies.
+
+### With Root
+- Root guides model behavior to call gate checks early.
+- Thorn enforces at interception point when hook fires.
+
+### With Pulp
+- Thorn can stop risky execution paths before tool run.
+- Pulp sanitizes content on output-side paths.
+
+### With Leaf
+- Leaf provides incoming-message observability.
+- Thorn provides pre-execution interception signals.
+
+## Operational value
+
+Thorn is useful for:
+- hard stop behavior on risky tool calls where host hook is active
+- consistent block reason payloads for agent/tool feedback
+- capturing pre-execution blocked telemetry for report/audit analysis
+
+## Limits and caveats
+
+- Hook availability/invocation depends on host runtime behavior.
+- Candidate extraction relies on known param keys and tool-name heuristics.
+- Complex/obfuscated command forms may reduce detection quality.
+- Should be operated together with Stem for stronger coverage.
+
+## Validation checklist
+
+1. Trigger file-tool call with sensitive path and confirm mode-specific outcome.
+2. Trigger exec-tool call with destructive command and confirm block behavior in enforce.
+3. Switch to audit and confirm same inputs emit observation events without hard block.
+4. Confirm report reflects expected blocked or observation counts.
+
+## See layers
+
+- [root](root.md)
+- [stem](stem.md)
+- [pulp](pulp.md)
+- [leaf](leaf.md)
+
+## Related pages
+- [layers index](README.md)
+- [decision modes](../decision/modes.md)
+- [decision patterns](../decision/patterns.md)
+- [decision posture](../decision/posture.md)
+
+---
+
+## Navigation
+- [Back to Layers Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/layers/vine.md

@@ -0,0 +1,154 @@
+---
+summary: "Layer reference for Berry.Vine (external-content trust guard and prompt-injection hardening)"
+read_when:
+  - You need to understand how Berry handles untrusted external content
+  - You are validating external-signal blocking behavior in audit/enforce
+  - You are tuning false positives around unknown-origin content
+title: "vine"
+---
+
+# `Berry.Vine`
+
+Berry.Vine is the **external-content trust guard layer**.
+
+It reduces prompt-injection risk by treating external content as untrusted by default and enforcing trust-aware checks before sensitive operations.
+
+## What Vine does
+
+- Tracks external-risk signals per session.
+- Marks risk when external-ingestion tool paths are observed.
+- Guards sensitive actions in `before_tool_call` when risk is active.
+- Applies different behavior in `audit` and `enforce`.
+- Adds a short context reminder in `before_agent_start` only when needed (throttled).
+- Clears session state on `session_end`.
+
+## What Vine does not do
+
+- It does not guarantee complete prevention of all prompt-injection techniques.
+- It does not replace Stem/Thorn/Pulp controls.
+- It does not rely on semantic AI classification.
+- It does not auto-remediate without explicit operator action.
+
+## Runtime flow
+
+```mermaid
+flowchart TD
+    EXT[External tool/content signal] --> AT[Hook: after_tool_call]
+    AT --> STATE[Vine risk state per session]
+    STATE --> BT[Hook: before_tool_call]
+    BT --> DEC{Sensitive action + risk?}
+    DEC -->|No| ALLOW[Allow path]
+    DEC -->|Yes + audit| WB[Emit would_block]
+    DEC -->|Yes + enforce| BLOCK[Block action]
+    STATE --> BAS[Hook: before_agent_start]
+    BAS --> REM[Inject short untrusted-content reminder]
+```
+
+## Trust labels and policy intent
+
+Vine tracks origin trust labels as runtime signals:
+- `trusted_user`
+- `external_untrusted`
+- `system_internal`
+- `unknown`
+
+Key operational rule:
+- User-origin message does not automatically mean instruction trust.
+- External payload and copied third-party instructions remain untrusted until confirmed by user intent.
+
+## Mode behavior
+
+### Enforce
+- Sensitive actions under active external risk can be blocked.
+- In strict profile, unknown-origin sensitive attempts can also block.
+
+### Audit
+- No hard block.
+- Emits `would_block` events for tuning and validation.
+
+## Interaction with other layers
+
+### With Root
+- Vine can add short trust reminders at turn start.
+- Root still owns global policy injection strategy (full/short/none).
+
+### With Stem and Thorn
+- Stem/Thorn remain execution gates.
+- Vine adds trust-origin context so risky instructions from external content are less likely to pass.
+
+### With Pulp
+- Pulp sanitizes output content.
+- Vine focuses on trust of instruction origin before sensitive actions.
+
+## Operational value
+
+Vine is useful for:
+- browser/email/webhook-heavy workflows
+- reducing "execute what this page says" risk
+- introducing trust-aware controls without replacing existing rule engine
+
+
+## Real-world examples
+
+### Case: external page tells the agent to run a command
+- If the page is ingested through an external tool path observed by Vine, session risk is marked.
+- A later sensitive write-like or destructive action is guarded.
+- In `audit`, Vine records `would_block`.
+- In enforce, Vine can block and report a blocked decision event.
+
+### Case: user pastes external text manually
+- Vine may classify this as `unknown` instead of `external_untrusted`.
+- Behavior depends on Vine mode:
+- `balanced`: tends to observe and escalate carefully.
+- `strict`: can block unknown-origin sensitive attempts.
+
+### Case: no sensitive action follows
+- Vine does not block "just for reading".
+- Guarding happens when a sensitive action is attempted.
+
+## Threat-model boundaries
+
+Vine is focused on instruction-origin trust before sensitive actions. It does not replace:
+- Pulp for output redaction and leak minimization.
+- Stem/Thorn for broader execution gates.
+- Host/runtime sandboxing and OS-level isolation.
+
+## Runtime validation principles
+
+Vine validation is a runtime behavior check, not an exploit demonstration.
+
+Use this principle:
+- run normal agent/tool workflows that include external-content ingestion;
+- let Berry observe and decide during regular execution flow;
+- verify evidence in structured outcomes (`would_block` in `audit`, active mitigation decision in `enforce`) through report/log telemetry.
+
+Important scope:
+- this validation assumes operator-guided execution in a real OpenClaw runtime;
+- the objective is to confirm decision posture and traceability, not to publish bypass or injection recipes.
+
+## Limits and caveats
+
+- Hook timing and availability still depend on host runtime behavior.
+- Unknown-origin classification can create false positives if over-tuned.
+- Risk decay should not depend only on elapsed time.
+
+## See layers
+
+- [root](root.md)
+- [stem](stem.md)
+- [thorn](thorn.md)
+- [pulp](pulp.md)
+- [leaf](leaf.md)
+
+## Related pages
+- [layers index](README.md)
+- [decision modes](../decision/modes.md)
+- [decision patterns](../decision/patterns.md)
+- [decision posture](../decision/posture.md)
+- [CLI status](../operation/cli/status.md)
+
+---
+
+## Navigation
+- [Back to Layers Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/operation/README.md

@@ -0,0 +1,31 @@
+---
+summary: "Operation reference index for Berry Shield interaction surfaces"
+read_when:
+  - Adding or changing operation docs for CLI or Web
+  - Reviewing user-facing operation guidance
+title: "Operation Reference"
+---
+
+# `Operation reference`
+
+This page is the entry point for operation-level documentation.
+If interaction surfaces change, update this index and linked pages.
+
+## Operation surfaces
+
+- [CLI](cli/README.md) (terminal command reference for `openclaw bshield`)
+- [Web](web/README.md) (web operation guidance; planned)
+
+## Scope
+
+Operation docs describe:
+- how users interact with Berry Shield surfaces
+- how to execute common workflows safely
+- where to find command-specific references
+
+---
+
+## Navigation
+
+- [Back to Wiki Index](../README.md)
+- [Back to Repository README](../../../README.md)

package/docs/wiki/operation/cli/README.md

@@ -0,0 +1,122 @@
+---
+summary: "Berry Shield CLI reference index for openclaw bshield commands"
+read_when:
+  - Adding or changing Berry Shield CLI commands
+  - Documenting command usage, options, and operational flows
+  - Reviewing CLI docs for consistency with runtime behavior
+title: "Berry Shield CLI Reference"
+---
+
+# `Berry Shield CLI reference`
+
+This page is the entry point for Berry Shield CLI documentation.
+If command behavior changes, update this index and the command pages.
+
+## Command pages
+
+- [help](help.md) (global discovery and command help)
+- [init](init.md)
+- [status](status.md)
+- [mode](mode.md)
+- [profile](profile.md)
+- [policy](policy.md)
+- [vine](vine.md)
+- [toggle](toggle.md)
+- [add](add.md)
+- [rules](rules.md)
+- [remove](remove.md)
+- [reset](reset.md)
+- [list](list.md)
+- [test](test.md)
+- [report](report.md)
+
+## Global command shape
+Use this syntax as the baseline for all Berry Shield CLI operations.
+
+```bash
+openclaw bshield <command> [options]
+```
+Expected: Run one Berry Shield command with optional flags and arguments.
+
+## Quick start
+
+### 1) Inspect current state
+Use this to confirm mode, policy profile, rule counts, and active layers.
+```bash
+openclaw bshield status
+```
+Expected: Status output includes `Mode`, `Rules`, `Policy`, and `Security Layers`.
+
+### 2) Set enforce mode
+Use this for active protection behavior.
+```bash
+openclaw bshield mode enforce
+```
+Expected: CLI confirms ENFORCE mode is active.
+
+### 3) Set balanced profile
+Use this as the recommended default profile for general operation.
+```bash
+openclaw bshield profile balanced
+```
+Expected: CLI confirms profile changed to `balanced`.
+
+### 4) Open policy wizard
+Use this for interactive policy tuning.
+```bash
+openclaw bshield policy
+```
+Expected: Wizard prompts for profile, adaptive, and retention values.
+
+### 5) List rules inventory
+Use this to inspect baseline and custom rules in one place.
+```bash
+openclaw bshield rules list
+```
+Expected: CLI shows baseline and custom IDs, including `[ENABLED]` and `[DISABLED]` status.
+
+### 6) Disable one baseline rule
+Use this to disable one baseline rule by stable ID.
+```bash
+openclaw bshield rules disable baseline secret:openai-key
+```
+Expected: CLI marks the target baseline rule as disabled.
+
+### 7) Disable one custom rule
+Use this to keep a custom rule stored but inactive.
+```bash
+openclaw bshield rules disable custom secret:my-token-rule
+```
+Expected: CLI marks the target custom rule as disabled.
+
+### 8) Tune Vine mode for smoke tests
+Use this to switch Vine behavior deterministically.
+```bash
+openclaw bshield vine set mode strict
+```
+Expected: CLI confirms strict Vine mode for external-content guard behavior.
+
+## Documentation structure
+
+Each command page follows the same structure:
+- What it does
+- When to use
+- Syntax
+- Options
+- Examples (one command per `bash` block)
+- Expected output
+- Common errors
+- Related commands
+
+## Notes
+
+- Keep examples deterministic and copy/paste-safe.
+- Keep one `openclaw bshield` command per `bash` block.
+- Prefer explicit expected outcomes after each example.
+
+---
+
+## Navigation
+
+- [Back to Operation Index](../README.md)
+- [Back to Wiki Index](../../README.md)