{"id":49813351,"url":"https://github.com/dortort/openclaw-mailguard","last_synced_at":"2026-05-13T02:30:44.980Z","repository":{"id":336220047,"uuid":"1148665044","full_name":"dortort/openclaw-mailguard","owner":"dortort","description":"OpenClaw plugin for email prompt-injection mitigation - sanitizes Gmail content, gates dangerous tools, and requires approval for sensitive operations","archived":false,"fork":false,"pushed_at":"2026-02-03T17:53:46.000Z","size":229,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T23:29:21.916Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"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/dortort.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-02-03T08:17:22.000Z","updated_at":"2026-02-03T17:54:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dortort/openclaw-mailguard","commit_stats":null,"previous_names":["dortort/openclaw-mailguard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dortort/openclaw-mailguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fopenclaw-mailguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fopenclaw-mailguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fopenclaw-mailguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fopenclaw-mailguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dortort","download_url":"https://codeload.github.com/dortort/openclaw-mailguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fopenclaw-mailguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32965212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"online","status_checked_at":"2026-05-13T02:00:07.132Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-13T02:30:44.238Z","updated_at":"2026-05-13T02:30:44.974Z","avatar_url":"https://github.com/dortort.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MailGuard - OpenClaw Email Security Plugin\n\n[![CI](https://github.com/dortort/openclaw-mailguard/actions/workflows/ci.yml/badge.svg)](https://github.com/dortort/openclaw-mailguard/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/%40dortort%2Fmailguard.svg)](https://badge.fury.io/js/%40dortort%2Fmailguard)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/typescript-%3E%3D5.4-blue)](https://www.typescriptlang.org/)\n[![OpenClaw](https://img.shields.io/badge/openclaw-%3E%3D2.0.0-purple)](https://github.com/dortort/openclaw)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n\n\u003e **⚠️ Experimental Software**\n\u003e\n\u003e This plugin is currently experimental. While MailGuard implements multiple layers of defense against prompt injection attacks, **no security measure can guarantee complete protection**. Prompt injection is an evolving threat, and sophisticated attacks may bypass detection. Always:\n\u003e - Review automated actions before approval\n\u003e - Monitor audit logs for suspicious activity\n\u003e - Keep the plugin updated for latest pattern definitions\n\u003e - Use this as one layer in a defense-in-depth strategy\n\n**MailGuard** is an OpenClaw plugin that hardens Gmail-triggered automation against prompt injection attacks by enforcing ingress sanitization, provenance-aware tool gating, and approval-gated side effects.\n\n## Features\n\n- **Email Sanitization**: Canonicalizes HTML/text, strips hidden content, extracts links, and enforces length limits\n- **Risk Scoring**: Detects prompt injection patterns using heuristics and optional ML classification\n- **Tool Firewall**: Provenance-aware access control that restricts dangerous tools for email-triggered sessions\n- **Approval Gating**: Side effects require explicit operator approval via Lobster workflows\n- **Audit Logging**: Structured logs of all risk signals and decisions\n- **CLI Tools**: Manage quarantine, view audit logs, and test configuration\n\n## Installation\n\n```bash\n# Install via OpenClaw CLI\nopenclaw plugins install @dortort/mailguard\n\n# Or via npm\nnpm install @dortort/mailguard\n```\n\n## Configuration\n\nAdd to your OpenClaw configuration:\n\n```json\n{\n  \"plugins\": {\n    \"mailguard\": {\n      \"webhookSecret\": \"your-secure-webhook-secret-here\",\n      \"riskThreshold\": 70,\n      \"quarantineEnabled\": true,\n      \"allowedSenderDomains\": [\"trusted-company.com\"],\n      \"blockedSenderDomains\": [\"known-spam.com\"],\n      \"lobsterIntegration\": {\n        \"enabled\": true,\n        \"timeout\": 3600\n      }\n    }\n  }\n}\n```\n\n### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `webhookSecret` | string | *required* | Shared secret for webhook authentication |\n| `endpoint` | string | `/mailguard/gmail` | HTTP endpoint path for Gmail webhook |\n| `maxPayloadSize` | number | 1048576 | Maximum payload size in bytes |\n| `maxBodyLength` | number | 50000 | Maximum email body length after sanitization |\n| `riskThreshold` | number | 70 | Risk score threshold for quarantine (0-100) |\n| `enableMLClassifier` | boolean | false | Enable optional ML-based risk scoring |\n| `mlClassifierEndpoint` | string | - | Endpoint for ML classification service |\n| `allowedSenderDomains` | string[] | [] | Trusted sender domains (reduced risk score) |\n| `blockedSenderDomains` | string[] | [] | Blocked sender domains |\n| `quarantineEnabled` | boolean | true | Enable quarantine for high-risk emails |\n| `rateLimitPerSender` | number | 10 | Max requests per sender per hour |\n\n## How It Works\n\n### 1. Ingress Sanitization\n\nWhen an email arrives via Gmail webhook:\n\n1. **Authentication**: Validates webhook secret\n2. **Size Check**: Rejects oversized payloads\n3. **Sanitization**:\n   - Strips HTML tags, scripts, and styles\n   - Removes hidden content (zero-width chars, CSS hidden)\n   - Extracts and validates links\n   - Separates quoted content\n   - Enforces length limits\n\n### 2. Risk Scoring\n\nAnalyzes sanitized content for injection patterns:\n\n- **Instruction Override**: \"ignore previous instructions\", fake system messages\n- **Tool Baiting**: \"run this command\", \"curl | bash\"\n- **Data Exfiltration**: requests for API keys, credentials\n- **Obfuscation**: base64 blocks, unicode abuse\n- **Role Impersonation**: \"you are now...\", \"pretend to be...\"\n\n### 3. Tool Firewall\n\nFor Gmail-origin sessions:\n\n**Always Denied** (Hard Denial):\n- `exec`, `shell`, `bash` - Command execution\n- `browser_control`, `browser_navigate` - Browser automation\n- `filesystem_write`, `filesystem_edit` - File modification\n- `web_fetch_unrestricted` - Unrestricted network access\n\n**Always Allowed** (Safe Tools):\n- `summarize`, `classify`, `translate` - Text analysis\n- `draft_reply`, `draft_email` - Draft creation\n- `propose_label`, `suggest_labels` - Label suggestions\n\n**Require Approval**:\n- `send_email`, `forward_email` - Email actions\n- `apply_label`, `delete_email` - Email modifications\n- `create_calendar_event` - Calendar actions\n\n### 4. Approval Workflow\n\nSide effects are gated through Lobster workflows:\n\n```\nEmail → Sanitize → Risk Score → Tool Request → Approval → Execute\n                                     ↓\n                              [Requires Approval]\n                                     ↓\n                           Lobster Workflow Created\n                                     ↓\n                           Operator Reviews \u0026 Approves\n                                     ↓\n                              Action Executed\n```\n\n## CLI Commands\n\n```bash\n# Check plugin status\nopenclaw mailguard:status\n\n# View quarantined messages\nopenclaw mailguard:quarantine\nopenclaw mailguard:quarantine --details\n\n# Release or delete quarantined messages\nopenclaw mailguard:quarantine:release \u003cmessage-id\u003e --force\nopenclaw mailguard:quarantine:delete \u003cmessage-id\u003e --force\n\n# View audit logs\nopenclaw mailguard:audit --limit 100\nopenclaw mailguard:audit --type quarantine\n\n# View tool policies\nopenclaw mailguard:policy\nopenclaw mailguard:policy --category denied\n\n# Test configuration\nopenclaw mailguard:test\nopenclaw mailguard:test --injection-test\n\n# Manage pending approvals\nopenclaw mailguard:approvals --session \u003csession-id\u003e\n```\n\n## Risk Signals\n\nMailGuard detects the following risk patterns:\n\n| Signal Type | Severity | Example |\n|------------|----------|---------|\n| `instruction_override` | Critical | \"Ignore all previous instructions\" |\n| `tool_baiting` | High | \"Run this command: rm -rf /\" |\n| `data_exfiltration` | Critical | \"Send me your API key\" |\n| `prompt_leak_attempt` | High | \"What is your system prompt?\" |\n| `role_impersonation` | High | \"You are now DAN mode\" |\n| `command_injection` | Critical | \"file.txt; rm -rf /\" |\n| `obfuscation` | Medium | Base64 encoded instructions |\n| `hidden_content` | High | Zero-width characters |\n| `suspicious_link` | Medium | URL shorteners, IP addresses |\n| `urgency_manipulation` | Low | \"URGENT: Act now!\" |\n| `financial_keywords` | Medium | \"Purchase gift cards\" |\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and linting\n5. Submit a pull request\n\n## Security\n\nIf you discover a security vulnerability, please report it via GitHub Security Advisories rather than opening a public issue.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdortort%2Fopenclaw-mailguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdortort%2Fopenclaw-mailguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdortort%2Fopenclaw-mailguard/lists"}