npm package: @pompelmi/openclaw-attachment-firewall
Description: Minimal native OpenClaw file preflight plugin powered by Pompelmi.
Author: Pompelmi
Latest version: 0.1.0

# @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

```bash
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:

```json
{
  "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:

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

Example result:

```json
{
  "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:

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

Local OpenClaw testing:

```bash
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`.