@gendigital/sage-openclaw 0.8.0 → 0.10.0

package/README.md

@@ -1,42 +1,85 @@
-# @gendigital/sage-openclaw
+# Sage — Safety for Agents
 
-**Safety for Agents** - Agent Detection & Response (ADR) plugin for [OpenClaw](https://openclaw.dev).
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gendigitalinc/sage/main/images/logo-shaded.png" alt="Sage" width="250">
+</p>
 
-Sage intercepts tool calls (shell commands, URL fetches, file writes) and checks them against URL reputation services, local heuristic threat rules, and package supply-chain checks before they execute.
+<p align="center">
+  Protect your AI coding agent from dangerous commands, malicious URLs, and harmful file operations.
+</p>
 
-## Installation
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gendigitalinc/sage/main/images/block-openclaw-allow.gif" alt="Sage blocking a dangerous command in OpenClaw" width="700">
+</p>
+
+## What is Sage?
+
+Sage is a security layer for OpenClaw. It intercepts tool calls — shell commands, URL fetches, file writes — and checks them for threats before they execute. If something looks dangerous, Sage blocks it with a native approval dialog.
+
+
+## What it protects against
+
+- **Malicious URLs** — phishing, malware, and scam sites detected via cloud reputation
+- **Dangerous commands** — reverse shells, pipe-to-curl, credential theft, data exfiltration
+- **Prompt injection** — heuristics + a fine-tuned ML model detect injected instructions in fetched content
+- **Suspicious file operations** — writes to sensitive paths, credential files, system configs
+- **Supply-chain attacks** — malicious or typosquatted npm/PyPI packages
+- **Compromised plugins** — automatic scanning of installed plugins at session start
+
+## Install
+
+See the [install guide](https://ai.gendigital.com/sage#install-openclaw) for step-by-step instructions, or run:
 
 ```bash
 openclaw plugins install @gendigital/sage-openclaw
 ```
 
-## What It Does
+Sage loads automatically — no configuration needed.
+
+> To verify it's working, ask your agent to run `echo __sage_test_deny_cmd_a75bf229__`. Sage should block this harmless canary command.
 
-- Intercepts `exec`, `web_fetch`, `write`, `edit`, `read`, and `apply_patch` tool calls
-- Checks URLs against cloud-based malware/phishing detection
-- Matches commands and file paths against YAML-based threat definitions
-- Validates npm/PyPI packages against supply-chain risks
-- Scans installed plugins for threats at session start
-- Provides native approval dialogs for interactive approval of flagged actions
+## What Sage intercepts
+
+Sage hooks into OpenClaw's `before_tool_call` lifecycle:
+
+- **exec** — shell commands
+- **write / edit** — file modifications
+- **read** — file reads (sensitive paths)
+- **web_fetch** — URL fetches and downloads
+- **apply_patch** — patch application
+
+## How it works
+
+When your agent makes a tool call, Sage evaluates it and returns a verdict:
+
+| Verdict | What happens |
+|---------|-------------|
+| **Allow** | No threats detected — the action proceeds normally |
+| **Ask** | Suspicious activity — you're prompted via native approval dialog |
+| **Deny** | Threat detected — the action is blocked |
+
+Sage is designed to fail open: if anything goes wrong internally, the action proceeds. Your agent is never blocked due to a Sage error.
 
 ## Configuration
 
-Sage works out of the box with no configuration. Optional config file at `~/.sage/config.json`:
+Sage works out of the box with no configuration. To customize behavior, edit `~/.sage/config.json`:
 
 ```json
 {
   "sensitivity": "balanced",
   "url_check": { "enabled": true },
-  "file_check": { "enabled": true }
+  "heuristics_enabled": true
 }
 ```
 
-## Links
-
-- [Source & documentation](https://github.com/gendigitalinc/sage)
-- [OpenClaw platform guide](https://github.com/gendigitalinc/sage/blob/main/docs/platform-guides/openclaw.md)
-- [Privacy policy](https://github.com/gendigitalinc/sage/blob/main/docs/privacy.md)
+See [Configuration](https://github.com/gendigitalinc/sage/blob/main/docs/configuration.md) for all options.
 
-## License
+## Links
 
-Apache License 2.0 - Copyright 2026 Gen Digital Inc.
+- [User Guide](https://github.com/gendigitalinc/sage/blob/main/docs/user-guide.md) — verify install, handle alerts, manage false positives
+- [Configuration](https://github.com/gendigitalinc/sage/blob/main/docs/configuration.md) — all config options
+- [Exceptions](https://github.com/gendigitalinc/sage/blob/main/docs/exceptions.md) — pattern-based allow/deny rules
+- [Privacy](https://github.com/gendigitalinc/sage/blob/main/docs/privacy.md) — what data is sent, what stays local
+- [GitHub](https://github.com/gendigitalinc/sage)