Skip to content

architecture.md

Latest commit

 

History

History
143 lines (113 loc) · 7.6 KB

architecture.md

File metadata and controls

143 lines (113 loc) · 7.6 KB
Raw

Architecture

Goal

Claw Guard is an OpenClaw security plugin that intercepts risky agent activity, records audits, and can optionally ask Claw_Guard_Server for a remote policy decision.

For the planned modularization path that supports more commands, more hook listeners, and more local scanners, see docs/modular-refactor.md.

Main Runtime Flow

  1. OpenClaw loads the plugin entry from dist/index.js.
  2. The plugin resolves config from openclaw.plugin.json and runtime config.
  3. The plugin initializes through src/app/bootstrap.ts:
    • shared path and config-store services under src/app/services/
    • local guard engine
    • audit writer and audit query service
    • OpenClaw config/log access
    • model adapter
    • intel HTTP client
    • exposure scanner
    • config security scanner
    • pause runtime and dashboard service
    • auto-upgrade controller
  4. The thin entry src/index.ts delegates to bootstrap, which registers hooks, commands, and dashboard routes.
  5. Hook events are evaluated locally and may also be sent to the remote policy service.
  6. Decisions are written to structured audit logs and exposed in the dashboard.

Hook Model

Active hooks:

  • before_prompt_build: injects a skill-install security review instruction and the per-session local report path
  • before_tool_call: inspects command, file, URL, and generic tool-call events
  • after_tool_call: hashes installed skill artifacts when the download path is only known after completion
  • message_received: inspects inbound user text, especially install operations

Pause behavior:

  • When paused, all tool calls are blocked.
  • When paused, normal incoming messages are blocked.
  • Only the remaining chat control commands such as /sec_openclaw_upgrade, /sec_help, and /sec_language are allowed through.
  • Pause and resume operator actions stay available through the dashboard routes.

Decision Model

Local plugin modes:

  • ignore: observe only; policy results are recorded but not warned or blocked
  • standard: apply raw policy decisions as-is
  • enforce: upgrade non-allow policy decisions into blocks

Remote transport decisions:

  • block
  • warn
  • allow

Local guard decisions:

  • block
  • warn
  • allow

Typical behavior:

  • Local rules evaluate commands, paths, and URLs.
  • The local guard now uses a two-tier command taxonomy:
    • red-line operations default to block, including destructive disk/system actions, remote script execution, code-injection chains, credential exfiltration, reverse shells, persistence mutation, auth tampering, and core permission tampering
    • yellow-line operations default to warn, including sudo, package installs that change the environment, docker run, firewall rule changes, known service start/stop/restart, localhost access, and broad sensitive-path access
  • Unknown or partially-modeled tools fall back to generic tool_call evaluation instead of bypassing the guard.
  • Install operations can be intercepted from message text.
  • Remote policy can upgrade or confirm the decision.
  • The plugin keeps server compatibility by translating internal modes to the current server wire contract when it uploads SecurityPolicyRequest.
  • Skill archives and installed skill folders can be matched by hash against server-side intel.
  • Before skill installs, the plugin injects a system instruction that requires the agent to write a local JSON safety report.
  • The core Claw Guard skill-install policy lines stay in src/hooks/skill-report.ts, and extra generic operation-safety review text is loaded from src/system-prompts/operation-safety/internal-safety-review.md.
  • The injected instruction now requires the agent to compute the skill hash first and write one JSON record per skill under skill-reports/.
  • When Claw Guard observes a write into skill-reports/*.json, it reads that record and uploads the hash verdict immediately.
  • If remote evaluation fails, fallback behavior depends on intel.failClosed.
  • Guard detectors and remote policy still exchange stable reason codes such as denylist:url and dangerous:destructive_command, but all user-visible warning and block text is localized in src/i18n/ before delivery.

Main Components

  • src/index.ts: thin plugin entry that delegates runtime wiring
  • src/app/bootstrap.ts: composition root; creates runtime services and registers routes, commands, hooks, scanners, and controllers
  • src/app/services/: bootstrap-owned runtime services for plugin state paths, config writes, audit queries, pause orchestration, dashboard status/actions, and hook signal buffering
  • src/features/registry.ts: feature registry that assembles command and dashboard contributions
  • src/features/types.ts: shared feature contract and contribution registration
  • src/features/commands/index.ts: command registry that assembles per-command modules under src/features/commands/
  • src/features/dashboard/index.ts: dashboard route registry that assembles per-route modules under src/features/dashboard/
  • src/features/hooks/index.ts: hook registry that wires per-hook registration modules under src/features/hooks/
  • src/hooks/before-prompt-build.ts: prompt injection for mandatory skill-install review reporting
  • src/hooks/before-tool-call.ts: before_tool_call risk evaluation and remote decision flow
  • src/hooks/after-tool-call.ts: post-install skill hash lookup flow for download-style installs
  • src/hooks/skill-report.ts: local skill review report contract and upload payload builder
  • src/system-prompts/operation-safety/internal-safety-review.md: shared internal safety-review prompt text appended to the install-review system context
  • src/hooks/message-received.ts: message_received pause gating and observation flow
  • src/hooks/: shared hook helpers, tool metadata mapping, warning replies, and decision logs
  • src/guard/detectors.ts: detector registry that maps incoming events to risk subjects
  • src/guard/policies.ts: policy registry that evaluates detected subjects
  • src/guard/: local rule engine and per-kind evaluators
  • src/intel/: remote HTTP client and shared policy types
  • src/dashboard/: gateway dashboard page and JSON endpoints
  • src/i18n/: localized guard notices and dashboard strings
  • src/pause/: emergency pause, resume, snapshot, and child-process termination
  • src/commands/: upgrade, uninstall, auto-upgrade, and help commands
  • src/config-security/: OpenClaw config security scan
  • src/exposure/: public exposure scan
  • src/audit/: JSONL audit output
  • src/runtime/: OpenClaw file and model adapters

State And Persistence

  • Audit log: JSONL file under the plugin state directory unless overridden
  • Pause snapshot: pause-snapshot.json
  • Auto-upgrade state: auto-upgrade.json
  • Mutable plugin settings override: mutable-config.json
  • Notification locale override: notification-locale.json
  • Skill install review reports: skill-reports/<skill-hash-hex>.json
  • Dashboard recent hook events: in-memory ring buffer

Dashboard

Routes:

  • GET /clawguard
  • GET /clawguard/assets/:asset
  • GET /clawguard/api/status
  • POST /clawguard/api/action/:action

Implementation notes:

  • src/dashboard/http.ts now serves a minimal HTML shell plus bootstrap JSON.
  • The interactive dashboard UI is a Preact app under src/dashboard-app/.
  • src/app/services/dashboard-service.ts owns dashboard status assembly and action-side state, while the feature routes stay declarative.
  • npm run build first bundles the dashboard into dashboard-assets/, then copies those assets into dist/dashboard-assets/ so the compiled plugin remains loadable from built output.

Supported dashboard actions:

  • pause
  • resume
  • security-scan
  • settings