ingress-firewall

openclaw-ingress-firewall

Policy-driven ingress firewall middleware for OpenClaw.

This plugin adds a reusable security layer that inspects untrusted inbound content before it reaches model prompts or high-risk tool calls.

Status

• License: MIT
• Maturity: alpha / early implementation
• Default posture: disabled until explicitly enabled in OpenClaw config

Why this exists

OpenClaw can ingest content from many trust boundaries (internal chat, customer channels, webhooks, HTTP APIs, tool inputs). This plugin centralizes sanitization and policy decisions so teams do not depend on manual scanning habits.

What it enforces

Current hook coverage:

• before_agent_reply: scans inbound text before model execution
• before_tool_call: scans risky tool-call parameters before execution

Policy actions:

• allow
• warn
• block

Scanner sources:

• built-in local text heuristics
• optional steg-sanitizer adapter
• optional external command-based scanners

Threat model (high-level)

Targets:

• prompt injection attempts
• hidden Unicode payloads
• suspicious data crossing trust boundaries
• untrusted tool arguments (web/file heavy flows)

Non-goals (for now):

• full malware sandboxing
• auto-disinfection/rewriting of malicious payloads
• universal file-type deep forensics

Quick start (local development)

pnpm install
pnpm lint
pnpm test
pnpm build

Install as OpenClaw plugin

openclaw plugins install --link /path/to/openclaw-ingress-firewall

Example config (kept disabled until review)

{
  plugins: {
    entries: {
      "ingress-firewall": {
        enabled: false,
        config: {
          enabled: true,
          warnOnly: false,
          riskyTools: ["web_fetch", "browser", "pdf", "image", "read"],
          scanners: {
            localText: { enabled: true },
            stegSanitizer: {
              enabled: true,
              command: "python3",
              scriptPath: "~/.openclaw/skills/steg-sanitizer/sanitize.py",
              timeoutMs: 5000
            }
          },
          routes: [
            {
              id: "customer-facing-strict",
              match: { agentId: "pulse" },
              warnAt: "LOW",
              blockAt: "MEDIUM",
              onScannerError: "block"
            },
            {
              id: "internal-balanced",
              match: { channelId: "discord" },
              warnAt: "MEDIUM",
              blockAt: "HIGH",
              onScannerError: "warn"
            }
          ],
          fallback: {
            warnAt: "MEDIUM",
            blockAt: "HIGH",
            onScannerError: "warn"
          }
        }
      }
    }
  }
}

Agent-friendly contributor map

If you are an AI agent (or a human contributor), start here:

1. Read CONTRIBUTING.md 2. Run pnpm lint && pnpm test && pnpm build 3. Keep changes scoped to one behavior per PR 4. Add/adjust tests with every behavior change 5. Do not enable this plugin in runtime configs in the same PR

Core files:

• src/index.ts -> plugin registration + config schema
• src/policy.ts -> route matching + allow/warn/block decisions
• src/scanners/* -> scanner adapters and orchestration
• src/hooks/* -> enforcement hooks
• examples/openclaw.config.patch.json -> config template only (not auto-applied)

Fully automated contributor incentives (no bounty, no direct maintainer interaction required)

This project can reward contributors through machine-verifiable outcomes:

• merged PR appears in git history + contributor graph
• release notes can be generated from merged conventional commits
• a benchmark/regression board can score contributions on:
• reduced false positives
• improved test coverage
• lower scan latency
• fewer bypass regressions

In short: ship measurable improvements, get durable public attribution.

Security notes

• Keep deployment tokens/credentials out of this repo.
• Treat all scanner subprocess outputs as untrusted and parse defensively.
• Prefer fail-closed for customer-facing routes.

License

MIT (see LICENSE).