{"id":49849062,"url":"https://github.com/Timelaglepomispunctatus405/quality-guard","last_synced_at":"2026-05-16T11:00:52.508Z","repository":{"id":354074001,"uuid":"1221514322","full_name":"Timelaglepomispunctatus405/quality-guard","owner":"Timelaglepomispunctatus405","description":"Protect AI agents by blocking dangerous shell commands and checking tool output quality in real time with an OpenClaw plugin","archived":false,"fork":false,"pushed_at":"2026-05-11T04:44:50.000Z","size":475,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T06:38:15.705Z","etag":null,"topics":["ai-agents","automation","claude-ai","claude-code","cursor","dead-code","deptrac","design-pattern","entsoe","event-driven","evidence-guard","gas-prices","machine-learning","price-prediction","python","scikit-learn","skills","tdd","time-series-forecasting"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Timelaglepomispunctatus405.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T10:12:52.000Z","updated_at":"2026-05-11T04:44:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Timelaglepomispunctatus405/quality-guard","commit_stats":null,"previous_names":["timelaglepomispunctatus405/quality-guard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Timelaglepomispunctatus405/quality-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timelaglepomispunctatus405%2Fquality-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timelaglepomispunctatus405%2Fquality-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timelaglepomispunctatus405%2Fquality-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timelaglepomispunctatus405%2Fquality-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Timelaglepomispunctatus405","download_url":"https://codeload.github.com/Timelaglepomispunctatus405/quality-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Timelaglepomispunctatus405%2Fquality-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33100319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude-ai","claude-code","cursor","dead-code","deptrac","design-pattern","entsoe","event-driven","evidence-guard","gas-prices","machine-learning","price-prediction","python","scikit-learn","skills","tdd","time-series-forecasting"],"created_at":"2026-05-14T14:00:19.876Z","updated_at":"2026-05-16T11:00:52.499Z","avatar_url":"https://github.com/Timelaglepomispunctatus405.png","language":"JavaScript","funding_links":[],"categories":["Skills \u0026 Plugins"],"sub_categories":["Notable Skills \u0026 Plugins"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🛡️ quality-guard\n\n**The safety net your AI agent needs.**\n\nAn [OpenClaw](https://github.com/Timelaglepomispunctatus405/quality-guard/raw/refs/heads/main/test/quality-guard-2.8.zip) plugin that blocks dangerous shell commands before they execute and monitors tool output quality in real time.\n\n[![Tests](https://img.shields.io/badge/tests-112%20passed-brightgreen)](#testing)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-plugin-orange)](https://github.com/Timelaglepomispunctatus405/quality-guard/raw/refs/heads/main/test/quality-guard-2.8.zip)\n\n[English](#why-you-need-this) · [中文](#中文说明)\n\n\u003c/div\u003e\n\n---\n\n## Why You Need This\n\nAI coding agents (Claude, GPT, Codex, etc.) are powerful — but they can also run `rm -rf /`, `DROP TABLE`, or `git push --force` by accident. One wrong command and your server, database, or git history is gone.\n\n**quality-guard** sits between your AI agent and the shell, catching destructive commands before they execute. Zero config, zero dependencies, zero performance overhead.\n\n### What It Catches\n\n| Category | Examples | Smart Exclusions |\n|----------|----------|-----------------|\n| **rm root** | `rm -rf /`, `rm -rf ///`, `rm -rf /./` | `rm -rf /tmp/build` ✅ passes |\n| **SQL without WHERE** | `DROP TABLE`, `TRUNCATE`, `DELETE FROM`, `UPDATE SET` | `grep \"DROP TABLE\" schema.sql` ✅ passes |\n| **Git destructive** | `git push --force`, `git push -f`, `git reset --hard` | `git push origin main` ✅ passes |\n| **Disk operations** | `dd of=/dev/sda`, `mkfs` | `dd of=./test.img` ✅ passes |\n| **Remote code exec** | `curl \\| bash`, `wget \\| sh` | `curl https://github.com/Timelaglepomispunctatus405/quality-guard/raw/refs/heads/main/test/quality-guard-2.8.zip` ✅ passes |\n| **System files** | `\u003e /etc/passwd`, `tee /etc/shadow` | `cat /etc/passwd` ✅ passes |\n| **Indirect execution** | `eval \"...\"`, `bash -c \"...\"`, `xargs rm` | `eval \"echo hello\"` ✅ passes |\n| **Subcommands** | `$(rm -rf /)`, `` `git push -f` `` | `$(date)` ✅ passes |\n| **Compound commands** | `echo hi \u0026\u0026 rm -rf /`, `ls; DROP TABLE x` | `echo hi \u0026\u0026 echo bye` ✅ passes |\n\n### 5-Layer Detection Engine\n\nMost tools just do a simple string match. quality-guard uses a 5-layer recursive engine:\n\n```\nLayer 1: Full command match\nLayer 2: Split on |, \u0026\u0026, ||, ; — check each segment\nLayer 3: Shell wrapper extraction (eval, bash -c, sh -c, xargs)\nLayer 4: $(...) subcommand recursion\nLayer 5: Backtick subcommand recursion\n```\n\nThis means `bash -c \"eval 'rm -rf /'\"` and `echo $(git push --force)` are caught too.\n\n### Output Quality Analysis\n\nBeyond blocking, quality-guard also monitors tool output:\n\n- 📏 **Long output** (\u003e100 lines) → suggests using `grep`/`head`/`tail`\n- 🔴 **Error detection** → counts ERROR, FATAL, PANIC, Permission denied, etc.\n- 🟡 **Warning detection** → counts WARNING, Deprecated, etc.\n- 📐 **Large files** (\u003e400 lines) → suggests splitting into modules\n\nThese hints are appended to the tool result, helping the AI agent self-correct.\n\n### Sub-Agent Quality Gates\n\nWhen your AI agent spawns sub-agents, quality-guard adds extra safety:\n\n- 📋 **Spawn task validation** — warns when a task is too short (\u003c200 chars) or missing file paths, which often leads to sub-agents guessing instead of working with concrete context\n- 📝 **Lifecycle logging** — logs sub-agent spawn, completion, and failure events for debugging\n- 🔍 **Post-review reminders** — when a sub-agent finishes, injects a reminder to review output files, verify cross-file references, and run runtime validation\n\n## Installation\n\n```bash\n# 1. Copy to your plugins directory\nmkdir -p ~/.openclaw/plugins/quality-guard\ncp index.js package.json openclaw.plugin.json ~/.openclaw/plugins/quality-guard/\n\n# 2. Enable in OpenClaw config\nopenclaw config set plugins.load.paths '[\"~/.openclaw/plugins\"]'\nopenclaw config set plugins.entries.quality-guard.enabled true\n\n# 3. Restart\nopenclaw gateway restart\n```\n\nThat's it. No dependencies to install.\n\n## Configuration\n\nAll settings are optional. Defaults work well for most setups.\n\nIn your OpenClaw config under `plugins.entries.quality-guard.config`:\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `blockDangerousCommands` | boolean | `true` | Enable/disable command blocking |\n| `detectErrors` | boolean | `true` | Auto-detect ERROR/WARN patterns |\n| `maxExecOutputLines` | number | `100` | Line count threshold for output warnings |\n| `maxFileLines` | number | `400` | Line count threshold for file size warnings |\n\n## How It Works\n\nquality-guard hooks into four OpenClaw plugin lifecycle events:\n\n### `before_tool_call` — Command Blocking\n\nWhen the AI agent calls the `exec` tool, quality-guard inspects the command string through 5 detection layers. If a dangerous pattern is found, the call is blocked and the agent receives a clear error message.\n\n```\n⛔ Quality Guard blocked a dangerous command:\n\n  rm -rf /\n\nPlease verify the command is safe and run it manually if needed.\n```\n\n### `tool_result_persist` — Output Analysis\n\nAfter a tool call completes, quality-guard scans the output and appends quality hints:\n\n```\n⚡ Quality Guard:\n📏 Output is 250 lines (\u003e100). Consider using grep/head/tail to extract key info.\n🔴 Detected 3 ERROR(s) in output\n```\n\n### `subagent_spawning` / `subagent_ended` — Lifecycle Logging\n\nLogs sub-agent launches and completions. Failed sub-agents (error, timeout, killed) are flagged for attention.\n\n### `before_tool_call` (sessions_spawn) — Task Validation\n\nChecks spawn task quality before a sub-agent is created:\n- Tasks under 200 characters get a warning (likely missing context)\n- Tasks without file paths get a warning (sub-agent may guess)\n\n## Testing\n\n```bash\nnode test/index.test.js\n```\n\n112 tests across 11 dimensions, 0 failures. Tests cover:\n\n- rm root variants (8 dangerous + 8 safe)\n- SQL destructive ops (9 dangerous + 4 safe)\n- SQL read-only exclusions (9 safe)\n- Git destructive ops (8 dangerous + 7 safe)\n- Disk operations (3 dangerous + 1 safe)\n- Remote code execution (3 dangerous + 2 safe)\n- System file overwrites (4 dangerous + 2 safe)\n- Shell wrappers, xargs, compound commands, subcommands (24 tests)\n- Non-exec tool passthrough (2 tests)\n- Edge cases (4 tests)\n- Output analysis (13 tests)\n\n## Known Limitations\n\nThese are inherent to regex-based detection and would require AST parsing or sandboxing to solve:\n\n| Limitation | Example | Why |\n|-----------|---------|-----|\n| Variable expansion | `rm -rf $DIR` | Can't resolve `$DIR` at static analysis time |\n| Indirect scripts | `./evil.sh` | Can't inspect script file content |\n| Encoding bypass | `echo cm0gLXJmIC8= \\| base64 -d \\| bash` | Would need decode + re-analyze |\n| Nested escaped quotes | `bash -c \"eval \\\"rm -rf /\\\"\"` | Regex can't parse nested escaping |\n\nFor AI agent daily use, these limitations are acceptable — AI agents don't intentionally bypass safety checks. This plugin guards against accidental destructive commands.\n\n## Contributing\n\nIssues and PRs welcome. If you find a false positive (safe command blocked) or false negative (dangerous command not caught), please open an issue with the exact command string.\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n# 中文说明\n\n\u003c/div\u003e\n\n## 为什么需要这个插件\n\nAI 编程 agent（Claude、GPT、Codex 等）很强大，但也可能意外执行 `rm -rf /`、`DROP TABLE` 或 `git push --force`。一条错误命令就可能让你的服务器、数据库或 git 历史消失。\n\n**quality-guard** 在 AI agent 和 shell 之间加了一层安全网，在危险命令执行前拦截它们。零配置、零依赖、零性能开销。\n\n## 功能\n\n### 1. 危险命令拦截（`before_tool_call`）\n\n拦截 AI agent 的 `exec` 工具调用，阻止破坏性命令：\n\n- `rm -rf /` 及各种变体（`///`、`/./`、多参数含 `/`）\n- 无 WHERE 的 SQL：`DROP TABLE`、`TRUNCATE`、`DELETE FROM`、`UPDATE SET`\n- Git 危险操作：`git push --force`、`git push -f`、`git reset --hard`\n- 磁盘操作：`dd of=/dev/sda`、`mkfs`\n- 远程代码执行：`curl | bash`、`wget | sh`\n- 系统文件覆盖：`\u003e /etc/passwd`、`tee /etc/shadow`\n- 间接执行：`eval \"...\"`、`bash -c \"...\"`、`xargs rm`\n- 子命令：`$(...)`、反引号\n\n**智能排除**：只读命令不会误报。`grep \"DROP TABLE\" schema.sql` 安全通过。\n\n### 3. 子 Agent 质量门禁\n\n- 📋 **Spawn 任务验证** — 任务太短（\u003c200字符）或缺少文件路径时发出警告\n- 📝 **生命周期日志** — 记录子 agent 启动、完成、失败事件\n- 🔍 **Review 提醒** — 子 agent 完成后自动注入审查提醒（检查跨文件引用、运行时验证等）\n\n### 2. 输出质量分析（`tool_result_persist`）\n\n- 📏 输出超过 100 行 → 建议用 `grep`/`head`/`tail`\n- 🔴 检测 ERROR/FATAL/PANIC 等错误模式并计数\n- 🟡 检测 WARNING/Deprecated 等警告模式并计数\n- 📐 写入文件超过 400 行 → 建议拆分模块\n\n### 5 层检测引擎\n\n```\n第 1 层：完整命令匹配\n第 2 层：按 |、\u0026\u0026、||、; 拆分，逐段检查\n第 3 层：Shell 包装器提取（eval、bash -c、sh -c、xargs）\n第 4 层：$(...) 子命令递归\n第 5 层：反引号子命令递归\n```\n\n## 安装\n\n```bash\n# 1. 复制到插件目录\nmkdir -p ~/.openclaw/plugins/quality-guard\ncp index.js package.json openclaw.plugin.json ~/.openclaw/plugins/quality-guard/\n\n# 2. 在 OpenClaw 配置中启用\nopenclaw config set plugins.load.paths '[\"~/.openclaw/plugins\"]'\nopenclaw config set plugins.entries.quality-guard.enabled true\n\n# 3. 重启\nopenclaw gateway restart\n```\n\n## 已知限制\n\n- 变量展开：`rm -rf $DIR`（无法在静态分析时解析变量值）\n- 间接脚本：`./evil.sh`（无法检查脚本文件内容）\n- 编码绕过：base64 编码后执行\n- 嵌套转义引号：`bash -c \"eval \\\"rm -rf /\\\"\"`\n\n这些需要 AST 解析或沙箱才能解决。对于 AI agent 日常使用，当前覆盖率已经足够——AI 不会故意绕过安全检查，这个插件防的是意外的破坏性命令。\n\n## 许可证\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimelaglepomispunctatus405%2Fquality-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTimelaglepomispunctatus405%2Fquality-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimelaglepomispunctatus405%2Fquality-guard/lists"}