https://github.com/merciagents/riphook
Deterministic security layer for Openclaw(Clawdbot), Cursor and Claude Code. Write secure code, prevent data exfil, and more
https://github.com/merciagents/riphook
ai-agents clawdbot hooks moltbook moltbot openclaw openclaw-security security
Last synced: 3 months ago
JSON representation
Deterministic security layer for Openclaw(Clawdbot), Cursor and Claude Code. Write secure code, prevent data exfil, and more
- Host: GitHub
- URL: https://github.com/merciagents/riphook
- Owner: merciagents
- License: apache-2.0
- Created: 2026-02-04T05:26:35.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-04T21:14:28.000Z (5 months ago)
- Last Synced: 2026-02-05T07:42:18.471Z (5 months ago)
- Topics: ai-agents, clawdbot, hooks, moltbook, moltbot, openclaw, openclaw-security, security
- Language: TypeScript
- Homepage:
- Size: 1.6 MB
- Stars: 16
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-openclaw - merciagents/riphook - Webhook- und Event-Bridge-Tooling fuer agentengetriebene Automationen.  (Entwicklertools und Observability)
README
# Riphook
Riphook is a security hook suite for Cursor, Claude Code, and OpenClaw. It blocks risky tool calls, detects secrets/PII, and runs static analysis on edited files to help keep agent runs safe by default.
It also emits **Cursor agent-trace–compatible logs** (https://agent-trace.dev/), providing you a clear context-graph, so you can visualize agent behavior, human collaboration, tool usage, and points of failure.
# Quick Start
(Linux/macOS/Windows via Git Bash or WSL):
```bash
curl -fsSL https://raw.githubusercontent.com/merciagents/riphook/main/scripts/install.sh | bash
```
Windows support is experimental.
# Example Usage
```
$ openclaw agent --message "read /Users/atharv/projects/test/proj/apikey.txt" --agent main
đź“– Read
{}
{
"status": "error",
"tool": "read",
"error": "Secret detected in file read"
}
The file apikey.txt appears to contain a sensitive secret (likely an API key), so I’m unable to display its contents directly for security reasons. If you need to use this key for a specific purpose, let me know what you’d like to do with it, and I can help guide you safely.
```
## Why Hooks (Not Just Prompts)
Prompts, `SKILLS.md`, and MCP servers are helpful, but they are **advisory**. An agent can ignore or misinterpret them. Or not even choose to call them. Hooks are **deterministic enforcement**: they intercept tool calls, reads, and outputs and can block actions regardless of what the prompt says. That makes hooks a much more reliable control layer for safety.
Hooks are often overlooked because they live outside the prompt. They don't seem cool enough. However, they are the most reliable control layer for safety. They run at the system boundary, where the agent actually executes tools.
## Features
- **Secure code generation**: static analysis runs on edited files and hooks enforce findings, ensuring agents comply with security detections (Cursor + Claude). As the static analysis is run everytime an agent completes execution, and its result fed back to the agent if an issue is detected, it ensures that the agent can not stop execution until the issue is resolved.
- **Secret detection**: scans prompts, tool params, file reads, and tool outputs.
- **PII detection**: credit cards, emails, SSNs, and phone-like patterns (OpenClaw + others).
- **Dangerous command blocking**: blocks dangerous shell/SQL patterns (rm -rf, drop table, etc).
- **Audit trail**: emits agent-trace records for prompts, tools, shells, and session lifecycle. Logs follow the Cursor agent-trace specification, enabling visualizations of agent flows, human+agent collaboration, and failure hotspots.
## Install
Riphook works with **pnpm** or **npm**.
```bash
# Clone the repository
git clone https://github.com/merciagents/riphook.git
cd riphook
# Install dependencies
pnpm install
```
This sets up the hooks for Cursor, Claude Code, and OpenClaw automatically.
If you don’t have pnpm:
```bash
npm install -g pnpm
```
Or use npm directly:
```bash
npm install
```
`postinstall` does the following:
- Writes `.cursor/hooks.json` and `~/.cursor/hooks.json` to point Cursor hooks at `dist/cursor/entry.js`.
- Writes `.claude/settings.json` and `~/.claude/settings.json` to point Claude hooks at `dist/claude/entry.js`.
- If `openclaw` is installed, registers the plugin locally and updates `~/.openclaw/config.json` (and `openclaw.json` if present).
- Existing user hooks are preserved; Riphook merges into your current hook lists.
Hook command:
- Hooks run as `node ` for reliability.
## Logs & Artifacts
- **Agent traces**: `./.agent-trace/traces.jsonl` (created in the install directory)
## Manual hooks setup
Cursor:
```json
{
"preToolUse": [{ "command": "node", "args": ["dist/cursor/entry.js"] }]
}
```
Claude Code:
```json
{
"hooks": {
"PreToolUse": [{ "command": "node", "args": ["dist/claude/entry.js"] }]
}
}
```
OpenClaw:
```bash
openclaw plugins install -l .
```
Then add to `~/.openclaw/config.json`:
```json
{
"plugins": {
"entries": {
"riphook": { "enabled": true, "config": {} }
}
}
}
```
## Development
```bash
npm run build
npm test
```
## More to come
The current implementation of Riphook is a work in progress, and we are constantly improving it. Here are some of the known limitations that will be addressed soon in a better version of our tool:
- **Regex-based detections**: secret/PII detection uses regex and can miss or misclassify.
- **Static analysis limits**: Semgrep rules won’t catch every bug or vulnerability. Also it is fairly slow.
- **Agent/session failures**: if an agent crashes or is interrupted, some edits or stop-time scans may not run.
- **Multiple ways to do the same thing**: If a tool is blocked, Cursor has multiple ways to override the block. We are working on a more complete handling of these other capabilities.
We will be releasing an advanced version of our system soon - faster, more accurate deterministic security, support for any general long running agent, dashboard for easy access to non developers, etc.
Known Issues:
- Cursor Read File hooks are not always fired properly: https://forum.cursor.com/t/hook-beforereadfile-does-not-work-in-the-agent/150520