@f4bioo/berry-shield 2026.3.3-1

package/docs/wiki/tutorials/choose-profile.md

@@ -0,0 +1,91 @@
+---
+summary: "Choose the right Berry Shield profile for your workload"
+read_when:
+  - You are deciding between strict, balanced, and minimal
+  - You want a safe baseline profile before broader rollout
+  - You need quick profile verification steps
+title: "Choose Your Profile"
+---
+
+# `Choose Your Profile`
+
+This tutorial helps you choose and validate a policy profile without editing low-level paths first.
+It is the fastest way to put teams on a predictable baseline.
+
+## Prerequisites
+
+- Berry Shield installed and enabled
+- Access to run `openclaw bshield` commands
+
+## Step 1: Inspect current profile
+
+Use this command to view the current profile and adaptive values before changes.
+```bash
+openclaw bshield status
+```
+Expected:
+- Policy section is visible
+- Profile appears as STRICT, BALANCED, or MINIMAL
+
+## Step 2: Start with balanced baseline
+
+Use this command to set a practical default for most environments.
+```bash
+openclaw bshield profile balanced
+```
+Expected:
+- CLI confirms profile update
+
+## Step 3: Verify profile application
+
+Use this command to confirm the profile was persisted and is visible in status output.
+```bash
+openclaw bshield status
+```
+Expected:
+- Profile is shown as BALANCED
+
+## Step 4: Compare strict behavior
+
+Use this command when you need maximum prompt-policy presence every turn.
+```bash
+openclaw bshield profile strict
+```
+Expected:
+- CLI confirms strict profile
+
+## Step 5: Compare minimal behavior
+
+Use this command when your priority is lower prompt noise and trigger-based behavior.
+```bash
+openclaw bshield profile minimal
+```
+Expected:
+- CLI confirms minimal profile
+
+## Step 6: Return to team baseline
+
+Use this command to restore the recommended daily-operation profile.
+```bash
+openclaw bshield profile balanced
+```
+Expected:
+- Profile returns to balanced for normal operation
+
+## Decision guide
+
+- Choose `strict` for high-control sessions where repeated policy injection is preferred.
+- Choose `balanced` for default production posture with good safety-to-noise tradeoff.
+- Choose `minimal` when low prompt overhead is required and risk triggers are tuned.
+
+## Related pages
+- [tutorial index](README.md)
+- [policy tuning](tune-policy.md)
+- [profile command reference](../operation/cli/profile.md)
+- [modes and profiles model](../decision/modes.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/tutorials/incident-triage-report.md

@@ -0,0 +1,99 @@
+---
+summary: "Use report output for incident triage and policy follow-up"
+read_when:
+  - You need to investigate suspicious activity patterns
+  - You want to separate rule gaps from expected denials
+  - You need a repeatable incident-response flow
+title: "Incident Triage with Report"
+---
+
+# `Incident Triage with Report`
+
+This tutorial provides a practical incident triage flow using Berry Shield report output.
+It helps teams turn raw event summaries into concrete policy actions.
+
+## Prerequisites
+
+- Berry Shield running in your target environment
+- Access to report output and policy/rule management commands
+
+## Step 1: Capture current evidence snapshot
+
+Use this command to read the current event summary and detail samples.
+```bash
+openclaw bshield report
+```
+Expected:
+- Output includes event count, period, summary rows, and details
+
+## Step 2: Confirm runtime posture
+
+Use this command to validate mode and profile before drawing conclusions.
+```bash
+openclaw bshield status
+```
+Expected:
+- Mode and profile are visible and match expected operating state
+
+## Step 3: Test suspected gap with dry-style check
+
+Use this command to test a candidate path or token string against active rule coverage.
+```bash
+openclaw bshield test "/home/team/.config/newservice/credentials.json"
+```
+Expected:
+- Output indicates whether active patterns already detect this input
+
+## Step 4: Add a temporary custom rule when gap is confirmed
+
+Use this command to quickly patch detection coverage for a validated gap.
+```bash
+openclaw bshield add file --name newservice-creds --pattern "/home/.*/.config/newservice/credentials.json"
+```
+Expected:
+- CLI confirms custom file rule persistence
+
+## Step 5: Verify rule presence
+
+Use this command to ensure the new rule is visible in active rule inventory.
+```bash
+openclaw bshield rules list
+```
+Expected:
+- Custom list includes `id: file:/home/.*/.config/newservice/credentials.json`
+
+## Step 6: Re-check detection behavior
+
+Use this command to confirm the new pattern now matches the targeted input.
+```bash
+openclaw bshield test "/home/team/.config/newservice/credentials.json"
+```
+Expected:
+- Output reports match for the newly added custom rule
+
+## Step 7: Document and normalize policy
+
+Use this command to print all policy values and capture final triage state for handoff.
+```bash
+openclaw bshield policy get
+```
+Expected:
+- Full policy values are printed for incident notes
+
+## Triage decision guide
+
+- If repeated suspicious inputs are not detected, add a custom rule and track it.
+- If detection is too broad, tighten regex before promoting rule to shared baseline.
+- If behavior differs across sessions, verify mode/profile and session context first.
+
+## Related pages
+- [tutorial index](README.md)
+- [build custom rules](build-custom-rules.md)
+- [report command reference](../operation/cli/report.md)
+- [posture and limits](../decision/posture.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/tutorials/secure-session.md

@@ -0,0 +1,115 @@
+---
+summary: "Run your first end-to-end Berry Shield validation session"
+read_when:
+  - You need a safe first-run checklist
+  - You want to validate enforce and audit behavior
+  - You want to verify report output after real checks
+title: "Your First Secure Session"
+---
+
+# `Your First Secure Session`
+
+This tutorial walks through a minimal but complete validation cycle.
+You will verify mode, generate controlled security events, and confirm reporting.
+
+## Prerequisites
+
+- Berry Shield installed and enabled in OpenClaw
+- Shell access to run `openclaw bshield ...`
+- A running OpenClaw session where `berry_check` is available
+
+## Step 1: Confirm status
+
+Check current mode and active layers.
+
+```bash
+openclaw bshield status
+```
+
+Expected:
+- Status is `ENABLED`
+- Security layers are `ACTIVE`
+
+## Step 2: Start from a clean report
+
+Clear persisted audit events before testing.
+
+```bash
+openclaw bshield report --clear
+```
+
+Expected:
+- Clear confirmation message with removed event count
+
+## Step 3: Validate enforce blocking
+
+Set enforce mode explicitly so subsequent checks use active blocking behavior.
+
+```bash
+openclaw bshield mode enforce
+```
+
+Then, in your OpenClaw chat session, request a safe denial test:
+
+Example prompt:
+`Run berry_check with operation=read and target=/etc/shadow. Do not read file contents.`
+
+Expected:
+- `berry_check` returns `STATUS: DENIED`
+- No sensitive content is read
+
+## Step 4: Confirm enforce report entries
+
+Run the report immediately after the denied test to confirm event persistence.
+
+```bash
+openclaw bshield report
+```
+
+Expected:
+- The enforce decision count increases in Summary
+- Details include `stem | sensitive file access` for the tested target
+
+## Step 5: Validate audit shadow behavior
+
+Switch to audit mode to observe shadow decisions without enforce-time blocking.
+
+```bash
+openclaw bshield mode audit
+```
+
+Repeat the same `berry_check` request in chat (`/etc/shadow`).
+
+Expected:
+- Tool result is not hard-blocked by audit posture
+- Event is logged as `would_block`
+
+## Step 6: Confirm audit report entries
+
+Run report again after the audit test to verify shadow logging behavior.
+
+```bash
+openclaw bshield report
+```
+
+Expected:
+- `would_block` count increases
+- Details show shadow decisions instead of enforce decisions
+
+## Troubleshooting
+
+- If mode changes do not appear immediately, re-check with `openclaw bshield status`.
+- If report looks empty right after activity, wait a moment and run report again.
+- If an event is missing, verify you exercised a path covered by current rules.
+
+## Related pages
+- [tutorial index](README.md)
+- [decision modes](../decision/modes.md)
+- [CLI mode command](../operation/cli/mode.md)
+- [CLI report command](../operation/cli/report.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/tutorials/tune-policy.md

@@ -0,0 +1,111 @@
+---
+summary: "Tune adaptive and retention policy values safely with CLI"
+read_when:
+  - You need to configure adaptive policy behavior
+  - You want deterministic set/get commands for automation
+  - You need to validate retention values
+title: "Tune Policy"
+---
+
+# `Tune Policy`
+
+This tutorial configures policy values using deterministic commands.
+Use it when you want repeatable settings for teams, scripts, and CI runs.
+
+## Prerequisites
+
+- Berry Shield enabled
+- Profile strategy already chosen (or about to be set)
+
+## Step 1: Read full policy state
+
+Use this command to print all policy values before making changes.
+```bash
+openclaw bshield policy get
+```
+Expected:
+- Rows for profile, adaptive values, and retention values
+
+## Step 2: Set profile via policy path
+
+Use this command to enforce an explicit profile through policy path semantics.
+```bash
+openclaw bshield policy set profile balanced
+```
+Expected:
+- CLI confirms `profile = balanced`
+
+## Step 3: Set stale timeout
+
+Use this command to define when sessions are considered stale for adaptive behavior.
+```bash
+openclaw bshield policy set adaptive.staleAfterMinutes 30
+```
+Expected:
+- CLI confirms stale timeout update
+
+## Step 4: Set escalation turns
+
+Use this command to control how many turns remain elevated after critical triggers.
+```bash
+openclaw bshield policy set adaptive.escalationTurns 3
+```
+Expected:
+- CLI confirms escalation value update
+
+## Step 5: Set heartbeat interval
+
+Use this command to tune optional periodic reinforcement cadence.
+```bash
+openclaw bshield policy set adaptive.heartbeatEveryTurns 0
+```
+Expected:
+- CLI confirms heartbeat interval update
+
+## Step 6: Configure global escalation behavior
+
+Use this command to keep global escalation disabled unless you explicitly need it.
+```bash
+openclaw bshield policy set adaptive.allowGlobalEscalation false
+```
+Expected:
+- CLI confirms boolean update
+
+## Step 7: Tune retention limits
+
+Use this command to cap how many persisted audit events are retained.
+```bash
+openclaw bshield policy set retention.maxEntries 5000
+```
+Expected:
+- CLI confirms retention max entries update
+
+## Step 8: Tune retention TTL
+
+Use this command to define event expiration window in seconds.
+```bash
+openclaw bshield policy set retention.ttlSeconds 2592000
+```
+Expected:
+- CLI confirms retention TTL update
+
+## Step 9: Verify one critical field
+
+Use this command to verify the exact value of global escalation after updates.
+```bash
+openclaw bshield policy get adaptive.allowGlobalEscalation
+```
+Expected:
+- Output shows `false` for the selected path
+
+## Related pages
+- [tutorial index](README.md)
+- [choose profile](choose-profile.md)
+- [policy command reference](../operation/cli/policy.md)
+- [security posture](../decision/posture.md)
+
+---
+
+## Navigation
+- [Back to Tutorials Index](README.md)
+- [Back to Wiki Index](../README.md)