@f4bioo/berry-shield 2026.3.3-1

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

@@ -0,0 +1,119 @@
+---
+summary: "CLI reference for `openclaw bshield test` (test one input against active match patterns)"
+read_when:
+  - You need to verify if a string matches built-in or custom patterns
+  - You are validating custom regex behavior before production use
+title: "test"
+---
+
+# `openclaw bshield test`
+
+Test one input string against active built-in and custom match patterns.
+
+## What it does
+- Loads built-in secret/PII patterns and custom secret rules.
+- Evaluates the provided input against active patterns.
+- Prints either no-match output or match details with rule source and redaction placeholder.
+
+## Scope and limitation
+- This command validates only:
+  - baseline secret and pii patterns
+  - custom secret rules
+- This command evaluates enabled rules only.
+- This command does not validate custom command or file rules.
+
+### Inspect file/command rules
+Use this when you need full visibility for custom file and command rules.
+```bash
+openclaw bshield rules list --detailed
+```
+Expected: CLI prints full custom and baseline inventory with ID and pattern.
+
+## When to use
+- Validating new custom secret patterns.
+- Debugging false positives or false negatives.
+- Verifying expected redaction placeholder mapping.
+
+## Syntax
+
+### Test one input
+Use this command to evaluate one input string against current match rules.
+```bash
+openclaw bshield test "<input>"
+```
+Expected: CLI reports no matches or prints one or more matching rule entries.
+
+## Options
+Positional argument:
+- `<input>`: string to test against active built-in and custom patterns.
+
+## Examples
+
+### Test a string with no expected match
+Use this to validate baseline no-match behavior.
+```bash
+openclaw bshield test "hello world"
+```
+Result: CLI reports no matches found.
+
+### Test a token-like string
+Use this to validate secret-pattern detection.
+```bash
+openclaw bshield test "sk_live_1234567890abcdef123456"
+```
+Result: CLI reports one or more matches with source and redaction placeholder.
+
+### Test after adding one custom rule
+Use this to verify new custom match behavior.
+```bash
+openclaw bshield test "MY_CUSTOM_TOKEN_ABC123"
+```
+Result: CLI reports custom match entry if the pattern is configured correctly.
+
+### Expected no-match for custom command/file strings
+Use this when checking a string that belongs to custom command or file rules.
+```bash
+openclaw bshield test "SMOKE_WEB_CMD"
+```
+Expected: `No matches found` because this command does not evaluate custom command/file rules.
+
+### Typed ID input is not a payload value
+Use this when input is a rule ID format.
+```bash
+openclaw bshield test "command:smoke-web-cmd"
+```
+Expected: no matches and guidance that typed IDs are rule identifiers, not payload values for this command.
+
+### Confirm command/file rule state
+Use this after the no-match output above.
+Use the detailed list command shown in `Inspect file/command rules`.
+Expected: command and file entries appear with full patterns so you can verify rule exists, is `ENABLED`, and has the expected active pattern.
+
+## Common errors
+
+### Shell quoting issue on input value
+Use this when shell splits the intended input unexpectedly.
+```bash
+openclaw bshield test sk_live_1234567890abcdef123456
+```
+Expected: CLI still runs, but testing semantics depend on shell parsing of the input.
+
+### Pattern read failure
+Use this when command output is missing expected custom matches due to storage/runtime issues.
+```bash
+openclaw bshield test "sample"
+```
+Expected: On failure, runtime reports storage/read issues for custom rule loading.
+
+## Related commands
+- [index](README.md)
+- [add](add.md)
+- [rules](rules.md)
+- [list](list.md)
+- [remove](remove.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,90 @@
+---
+summary: "CLI reference for `openclaw bshield toggle` (enable or disable one security layer)"
+read_when:
+  - You need to temporarily disable or re-enable one Berry Shield layer
+  - You are debugging behavior at layer level
+title: "toggle"
+---
+
+# `openclaw bshield toggle`
+
+Toggle one Berry Shield security layer between enabled and disabled states.
+
+## What it does
+- Validates layer name against known layer keys.
+- Reads current layer state (or uses default when config is missing).
+- Writes the inverse state to config.
+- Returns explicit success or failure output.
+
+## When to use
+- Isolated diagnostics for one layer.
+- Controlled troubleshooting in non-production workflows.
+- Temporary layer disable/enable during rule tuning.
+
+## Syntax
+
+### Toggle one layer
+Use this to invert the current state of a selected layer.
+```bash
+openclaw bshield toggle <layer>
+```
+Expected: CLI confirms selected layer is now ENABLED or DISABLED.
+
+## Options
+Positional argument:
+- `<layer>`: one of root, pulp, thorn, leaf, stem.
+
+## Examples
+
+### Toggle root layer
+Use this when debugging root policy injection behavior.
+```bash
+openclaw bshield toggle root
+```
+Result: Root layer flips state and CLI confirms the new value.
+
+### Toggle stem layer
+Use this when isolating gate behavior during security tests.
+```bash
+openclaw bshield toggle stem
+```
+Result: Stem layer flips state and CLI confirms the new value.
+
+### Verify layer states after toggle
+Use this check after any toggle operation.
+```bash
+openclaw bshield status
+```
+Result: Security Layers section reflects ACTIVE or OFF for each layer.
+
+## Common errors
+
+### Invalid layer name
+Use this to validate layer allowlist behavior.
+```bash
+openclaw bshield toggle kernel
+```
+Expected: CLI fails with message listing available layers.
+
+### Toggle write failure
+Use this when toggle command reports operation failure.
+```bash
+openclaw bshield toggle leaf
+```
+Expected: On failure, CLI prints operation failure and returns non-zero exit code.
+
+Possible causes:
+- Config write permission issue.
+- Config backend/runtime error.
+
+## Related commands
+- [index](README.md)
+- [status](status.md)
+- [mode](mode.md)
+- [policy](policy.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,193 @@
+---
+summary: "CLI reference for `openclaw bshield vine` (status, get/set, and allowlist operations)"
+read_when:
+  - You need deterministic Berry.Vine tuning for tests or operations
+  - You want to inspect or update Vine thresholds without editing JSON manually
+title: "vine"
+---
+
+# `openclaw bshield vine`
+
+Manage Berry.Vine configuration and tool allowlist from CLI.
+
+## What it does
+- Prints current Vine configuration (status).
+- Reads Vine values (get).
+- Writes deterministic Vine paths (set).
+- Adds one tool to Vine allowlist (allow).
+- Removes one tool from Vine allowlist (deny).
+
+## When to use
+- Before smoke tests that need strict/balanced Vine behavior.
+- During incident response for false-positive tuning.
+- In scripts where Vine changes must be reproducible.
+
+## Syntax
+
+### Status (default action)
+Use this to print the current effective Vine configuration.
+```bash
+openclaw bshield vine
+```
+Expected: CLI prints mode, thresholds, retention, and allowlist count.
+
+### Explicit status
+Use this when you want explicit command intent.
+```bash
+openclaw bshield vine status
+```
+Expected: Same output as default action.
+
+### Read values
+Use this to inspect all Vine values or one specific path.
+```bash
+openclaw bshield vine get [path]
+```
+Expected: CLI prints all Vine fields or one selected path.
+
+### Update one value
+Use this to update one supported Vine path.
+```bash
+openclaw bshield vine set <path> <value>
+```
+Expected: CLI confirms updated path and value.
+
+### Allow one tool
+Use this to exempt one tool from Vine escalation.
+```bash
+openclaw bshield vine allow <toolName>
+```
+Expected: Tool name is appended to `vine.toolAllowlist`.
+
+### Deny one tool
+Use this to remove one tool from Vine allowlist.
+```bash
+openclaw bshield vine deny <toolName>
+```
+Expected: Tool name is removed from `vine.toolAllowlist`.
+
+## Options
+Actions:
+- status
+- get
+- set
+- allow
+- deny
+
+Supported `set` paths:
+- `mode` (`balanced | strict`)
+- `thresholds.externalSignalsToEscalate` (integer `>= 1`)
+- `thresholds.forcedGuardTurns` (integer `>= 1`)
+- `retention.maxEntries` (integer `>= 1`)
+- `retention.ttlSeconds` (integer `>= 1`)
+
+## Tuning guide
+
+| Field | Change when | Typical direction | Tradeoff |
+| --- | --- | --- | --- |
+| `mode` | You need stronger or softer protection posture | `balanced -> strict` for harder blocking | `strict` reduces risk but may increase false positives |
+| `thresholds.externalSignalsToEscalate` | Vine escalates too early or too late | Increase to reduce sensitivity, decrease to escalate faster | Lower values improve safety response, higher values reduce noise |
+| `thresholds.forcedGuardTurns` | Guard window is too short or too long after escalation | Increase for stronger persistence, decrease for faster recovery | Higher values improve protection continuity but may impact UX |
+| `retention.maxEntries` | High session churn or memory pressure appears | Decrease on constrained hosts, increase for larger workloads | Lower values save memory, higher values keep more Vine state |
+| `retention.ttlSeconds` | Session risk state expires too fast or remains too long | Increase for longer correlation, decrease for faster cleanup | Longer TTL helps traceability, shorter TTL reduces stale state |
+
+## Allowlist guide
+
+### What allowlist is for
+- Allowlist is an exception list for tool names.
+- If a tool is allowlisted, Vine does not escalate risk based on that tool output.
+- Use this only for tools you trust and control.
+
+### When to use allowlist
+- A known-safe internal tool keeps triggering Vine noise.
+- You need short-term tuning during controlled tests.
+- You validated the tool output path and ownership.
+
+### Risk to understand first
+- Allowlisting reduces Vine coverage for that tool.
+- If the allowlisted tool starts returning risky external content, Vine may not react as expected.
+- Keep the list small and review it often.
+
+### Add one tool
+Use this to create one allowlist exception.
+Use the allow command shown in Syntax with the trusted tool name.
+Expected: selected tool is added to allowlist.
+
+### Check current allowlist state
+Use this to confirm count and current Vine posture.
+Use the explicit status command shown in Syntax.
+Expected: Vine section shows current allowlist count.
+
+### Remove one tool
+Use this to restore normal Vine protection for a tool.
+Use the deny command shown in Syntax with the same tool name previously allowlisted.
+Expected: selected tool is removed from allowlist.
+
+## Examples
+
+### Set strict mode for aggressive blocking
+Use this for high-sensitivity validation runs.
+```bash
+openclaw bshield vine set mode strict
+```
+Result: CLI confirms `mode = strict`.
+
+### Reduce guard turns after escalation
+Use this to lower Vine persistence during tuning.
+```bash
+openclaw bshield vine set thresholds.forcedGuardTurns 2
+```
+Result: CLI confirms forced guard turns updated.
+
+### Allowlist one tool
+Use this when one trusted tool should not trigger Vine escalation.
+```bash
+openclaw bshield vine allow web_fetch
+```
+Result: tool is added to allowlist.
+
+### Remove allowlisted tool
+Use this when previously trusted tool should be guarded again.
+```bash
+openclaw bshield vine deny web_fetch
+```
+Result: tool is removed from allowlist.
+
+## See more:
+
+- [Vine runtime validation principles](../../layers/vine.md#runtime-validation-principles)
+
+## Common errors
+
+### Invalid action
+Use this check when command fails before execution.
+```bash
+openclaw bshield vine edit mode strict
+```
+Expected: CLI fails and prints valid actions.
+
+### Invalid path
+Use this check when deterministic set path is not allowlisted.
+```bash
+openclaw bshield vine set thresholds.unknown 1
+```
+Expected: CLI fails and prints allowed Vine paths.
+
+### Invalid value type
+Use this check for numeric/type validation.
+```bash
+openclaw bshield vine set thresholds.forcedGuardTurns zero
+```
+Expected: CLI fails with integer validation message.
+
+## Related commands
+- [index](README.md)
+- [status](status.md)
+- [policy](policy.md)
+- [mode](mode.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,27 @@
+---
+summary: "Web operation reference index for Berry Shield"
+read_when:
+  - Defining or documenting Berry Shield behavior in web surfaces
+  - Linking future web operation guides
+title: "Web Operation Reference"
+---
+
+# `Web operation reference`
+
+This page is reserved for Berry Shield web operation documentation.
+
+## Status
+
+Web operation pages are not published yet.
+When web workflows are defined, add pages under this directory.
+
+## Planned topics
+- web configuration workflow
+- web mode/profile/policy editing behavior
+- web verification flows and troubleshooting
+
+---
+
+## Navigation
+- [Back to Operation Index](../README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/tutorials/README.md

@@ -0,0 +1,40 @@
+---
+summary: "Tutorial index for step-by-step Berry Shield onboarding flows"
+read_when:
+  - You are new to Berry Shield and need guided workflows
+  - You want practical command sequences with expected outcomes
+  - You need a safe validation flow before production usage
+title: "Tutorials"
+---
+
+# `Tutorials`
+
+This section provides practical, step-by-step workflows for Berry Shield.
+Use these pages when you want guided execution rather than command reference.
+
+## Available tutorials
+
+- [secure session](secure-session.md): end-to-end first session with verification checkpoints
+- [choose your profile](choose-profile.md): decide strict/balanced/minimal with practical checks
+- [tune policy](tune-policy.md): configure adaptive and retention values safely
+- [build custom rules](build-custom-rules.md): add, test, list, and remove organization-specific rules
+- [audit-to-enforce rollout](audit-to-enforce-rollout.md): move from observation to active mitigation
+- [incident triage with report](incident-triage-report.md): investigate events and close detection gaps
+
+## How tutorials differ from CLI reference
+
+- Tutorials focus on outcome-driven flows.
+- CLI reference focuses on command contracts and options.
+- Use tutorials first, then jump to CLI pages for advanced tuning.
+
+## Related pages
+- [operation index](../operation/README.md)
+- [CLI reference](../operation/cli/README.md)
+- [decision modes](../decision/modes.md)
+- [decision posture](../decision/posture.md)
+
+---
+
+## Navigation
+- [Back to Wiki Index](../README.md)
+- [Back to Repository README](../../../README.md)

package/docs/wiki/tutorials/audit-to-enforce-rollout.md

@@ -0,0 +1,99 @@
+---
+summary: "Roll out from audit observation to enforce protection safely"
+read_when:
+  - You are preparing first production rollout
+  - You need controlled transition from audit to enforce
+  - You want evidence-driven go/no-go criteria
+title: "Audit-to-Enforce Rollout"
+---
+
+# `Audit-to-Enforce Rollout`
+
+This tutorial defines a safe rollout sequence from observation to active protection.
+It reduces rollout risk by using measured checkpoints and explicit validation.
+
+## Prerequisites
+
+- Team agreement on target profile and policy values
+- Access to run operational CLI commands during rollout window
+- A chat session where controlled `berry_check` prompts can be executed
+
+## Step 1: Set audit mode for observation
+
+Use this command to start in shadow posture before enabling active mitigation.
+```bash
+openclaw bshield mode audit
+```
+Expected:
+- CLI confirms audit mode
+
+## Step 2: Clear previous report baseline
+
+Use this command to ensure rollout observations are measured from a clean baseline.
+```bash
+openclaw bshield report --clear
+```
+Expected:
+- CLI confirms clear count
+
+## Step 3: Generate controlled security activity
+
+Use this prompt in chat to trigger a sensitive-path decision without exposing content.
+Example prompt:
+`Run berry_check with operation=read and target=/etc/shadow. Do not read file contents.`
+Expected:
+- Decision is captured as a shadow-style event in audit posture
+
+## Step 4: Inspect audit evidence
+
+Use this command to confirm audit observations are persisted and visible.
+```bash
+openclaw bshield report
+```
+Expected:
+- Summary and details show new audit-observation decisions
+
+## Step 5: Switch to enforce mode
+
+Use this command to activate active mitigation after audit evidence is reviewed.
+```bash
+openclaw bshield mode enforce
+```
+Expected:
+- CLI confirms enforce mode
+
+## Step 6: Re-run the same controlled test
+
+Use the same prompt in chat to compare behavior under enforce posture.
+Example prompt:
+`Run berry_check with operation=read and target=/etc/shadow. Do not read file contents.`
+Expected:
+- Sensitive read attempt is denied under enforce
+
+## Step 7: Confirm enforce evidence
+
+Use this command to verify enforce decisions are now represented in report output.
+```bash
+openclaw bshield report
+```
+Expected:
+- New enforce-time decisions appear in summary/details
+
+## Go-live checklist
+
+- Profile is the intended one (`status` confirms).
+- Mode is `ENFORCE` after final switch.
+- Controlled denial test behaves as expected.
+- Report evidence is available for post-rollout review.
+
+## Related pages
+- [tutorial index](README.md)
+- [secure session](secure-session.md)
+- [mode command reference](../operation/cli/mode.md)
+- [report command reference](../operation/cli/report.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/tutorials/build-custom-rules.md

@@ -0,0 +1,99 @@
+---
+summary: "Create, validate, and maintain custom rules with safe workflow"
+read_when:
+  - You need organization-specific secret/file/command coverage
+  - You want to avoid broad or unsafe regex patterns
+  - You need a repeatable custom-rule lifecycle
+title: "Build Custom Rules"
+---
+
+# `Build Custom Rules`
+
+This tutorial shows a full custom-rule lifecycle: add, validate, list, and remove.
+Use it to extend built-in coverage for your environment.
+
+## Prerequisites
+
+- Berry Shield enabled
+- Basic regex familiarity for custom patterns
+
+## Step 1: Add one custom secret rule
+
+Use this command to create a deterministic secret pattern entry.
+```bash
+openclaw bshield add secret --name team_token_rule --pattern "team_tok_[a-z0-9]{16}"
+```
+Expected:
+- CLI confirms rule was persisted
+
+## Step 2: Validate rule matching behavior
+
+Use this command to test whether your custom pattern matches expected sample input.
+```bash
+openclaw bshield test "team_tok_a1b2c3d4e5f6g7h8"
+```
+Expected:
+- Output reports a custom rule match
+
+## Step 3: Validate negative sample
+
+Use this command to verify non-matching strings do not produce false positives.
+```bash
+openclaw bshield test "team_token_invalid_shape"
+```
+Expected:
+- Output reports no match
+
+## Step 4: List active rules
+
+Use this command to inspect built-in and custom rule counts and entries.
+```bash
+openclaw bshield rules list
+```
+Expected:
+- Rule list includes your custom `team_token_rule` entry
+
+## Step 5: Remove test rule when done
+
+Use this command to remove the temporary custom rule after validation.
+```bash
+openclaw bshield rules remove custom team_token_rule
+```
+Expected:
+- CLI confirms rule removal
+
+## Step 6: Confirm clean state
+
+Use this command to verify the removed rule no longer appears.
+```bash
+openclaw bshield rules list
+```
+Expected:
+- `team_token_rule` is absent from custom entries
+
+## Optional: Use wizard for guided creation
+
+Use this command when you want prompts, preview loop, and confirmation flow.
+```bash
+openclaw bshield add
+```
+Expected:
+- Wizard guides type selection, pattern input, and save decision
+
+## Rule quality checklist
+
+- Keep patterns narrow and specific to reduce accidental matches.
+- Validate both positive and negative samples before production use.
+- Use clear rule names that encode source or owner context.
+
+## Related pages
+- [tutorial index](README.md)
+- [add command reference](../operation/cli/add.md)
+- [test command reference](../operation/cli/test.md)
+- [pattern model](../decision/patterns.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)