@pompelmi/openclaw-attachment-firewall

Minimal native OpenClaw file preflight plugin powered by Pompelmi.

Main Pompelmi repository: https://github.com/pompelmi/pompelmi

This repository is an ecosystem integration package, not the main product. The core scanner direction, broader engine work, and primary roadmap live in the main Pompelmi repository:

https://github.com/pompelmi/pompelmi

Scope

This plugin keeps a deliberately small MVP surface:

• native OpenClaw tool: pompelmi_scan_file
• native OpenClaw hook: before_tool_call
• local file/path preflight scanning only
• no UI
• no cloud backend
• no exaggerated malware-engine claims

Current checks stay lightweight and deterministic:

• file existence and regular-file validation
• maximum file size enforcement
• explicit extension blocklist checks
• suspicious executable and script extension handling
• lightweight file-header signature sniffing where practical
• stable structured verdict output for both the tool and hook flow

Install

openclaw plugins install @pompelmi/openclaw-attachment-firewall

After install, configure the plugin under plugins.entries.openclaw-attachment-firewall and restart the OpenClaw gateway if needed.

If you want the deeper scanner engine or the main roadmap, start with:

https://github.com/pompelmi/pompelmi

Configuration

openclaw.plugin.json exposes this config:

{
  "plugins": {
    "entries": {
      "openclaw-attachment-firewall": {
        "enabled": true,
        "config": {
          "enabled": true,
          "mode": "advisory",
          "blockSuspicious": false,
          "blockMalicious": true,
          "scanArchives": true,
          "maxBytes": 26214400,
          "extensionsBlocklist": [],
          "pathParamKeys": [
            "file",
            "path",
            "filePath",
            "attachment",
            "attachments",
            "input",
            "target"
          ]
        }
      }
    }
  }
}

Notes:

• mode: "advisory" logs findings and allows the original tool call
• mode: "enforce" blocks malicious files and can also block suspicious files when blockSuspicious is true
• scanArchives currently covers outer-file archive handling only
• pathParamKeys limits which tool arguments are treated as local file candidates

Behavior

Explicit tool call:

{
  "tool": "pompelmi_scan_file",
  "arguments": {
    "path": "/tmp/invoice.pdf"
  }
}

Example result:

{
  "inputPath": "/tmp/invoice.pdf",
  "path": "/tmp/invoice.pdf",
  "fileName": "invoice.pdf",
  "extension": "pdf",
  "sizeBytes": 48123,
  "mime": "application/pdf",
  "detectedType": "pdf",
  "verdict": "clean",
  "recommendedAction": "allow",
  "reasons": [],
  "signals": []
}

Hook behavior:

• if a tool argument looks like a local file path under configured keys such as path, filePath, or attachment, the plugin scans it before execution
• in advisory mode, execution continues and the plugin logs the verdict summary
• in enforce mode, malicious files are blocked, and suspicious files are blocked only when configured to do so

Development

Local validation:

npm install --ignore-scripts
npm run typecheck
npm pack --dry-run

Local OpenClaw testing:

openclaw plugins install -l .
openclaw plugins inspect openclaw-attachment-firewall
openclaw plugins doctor

The deeper engine and future integration work should continue in the main Pompelmi repository:

https://github.com/pompelmi/pompelmi

License

MIT. See LICENSE.