# boxdawn/guard architecture

> Architecture diagram of the GitHub repository boxdawn/guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boxdawn/guard
- Repository: https://github.com/boxdawn/guard

## Overview

Boxdawn guard is a pre-tool security plugin for Claude Code, with a Copilot CLI hook variant. Its main workflow receives a shell command, evaluates Bash or PowerShell against destructive-command and secret-file rules, then denies, asks for approval, or makes no decision. It also protects secret searches, supports signed rule bundles and optional undo snapshots, and can record and upload anonymized block events. The hook and evaluator relationships are supported by the excerpts and SOURCE INDEX; several secondary subsystem links are documented in the README rather than sampled implementation.

Main entry points: [`boxdawn_guard/command_hook.py`](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py) (Pre-tool hook), [`packaging/guard_entry.py`](https://github.com/boxdawn/guard/blob/main/packaging/guard_entry.py) (Hook dispatcher), [`boxdawn_guard/command_guard.py`](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_guard.py) (Bash evaluator), [`boxdawn_guard/block_send.py`](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/block_send.py) (Block uploader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hooks["Hook entrypoints"]
  node_hook["Pre-tool hook<br/>[command_hook.py]"]
  node_copilot_hook["Copilot hook<br/>[copilot_hook.py]"]
  node_dispatcher["Hook dispatcher<br/>[guard_entry.py]"]
end

subgraph group_judging["Command judging"]
  node_bash_eval["Bash evaluator<br/>[command_guard.py]"]
  node_ps_eval["PowerShell evaluator"]
  node_verdict["Decision response<br/>[command_hook.py]"]
end

subgraph group_rules["Rules and secrets"]
  node_fixed_rules["Fixed command rules"]
  node_secret_rules["Secret-file rules<br/>[secret_files.py]"]
  node_signed_rules["Signed rule bundles<br/>[rules_bundle.py]"]
  node_korean["Korean messages<br/>[messages_ko.py]"]
end

subgraph group_safety["Session safeguards"]
  node_grep_guard["Secret-safe Grep<br/>[command_hook.py]"]
  node_undo[("Undo snapshots<br/>[undo.py]")]
end

subgraph group_telemetry["Block records"]
  node_block_log[("Block log<br/>[block_log.py]")]
  node_block_send["Block uploader<br/>[block_send.py]"]
end

node_claude(("Claude Code"))
node_copilot(("Copilot CLI"))
node_boxdawn_service(("Boxdawn service"))

node_claude -->|"invokes hook"| node_hook
node_copilot -->|"invokes hook"| node_copilot_hook
node_dispatcher -->|"dispatches to"| node_hook
node_dispatcher -->|"dispatches to"| node_copilot_hook
node_hook -->|"evaluates Bash"| node_bash_eval
node_hook -->|"evaluates PowerShell"| node_ps_eval
node_hook -->|"emits decision"| node_verdict
node_bash_eval -->|"uses rules"| node_fixed_rules
node_bash_eval -->|"checks names"| node_secret_rules
node_ps_eval -->|"checks names"| node_secret_rules
node_hook -->|"loads rules"| node_signed_rules
node_signed_rules -->|"falls back to"| node_fixed_rules
node_hook -->|"translates reasons"| node_korean
node_hook -->|"filters searches"| node_grep_guard
node_grep_guard -->|"adds exclusions"| node_secret_rules
node_hook -->|"supports undo"| node_undo
node_hook -->|"records verdicts"| node_block_log
node_block_log -->|"supplies records"| node_block_send
node_dispatcher -->|"starts upload"| node_block_send
node_block_send -->|"sends records"| node_boxdawn_service

click node_hook "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py"
click node_copilot_hook "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/copilot_hook.py"
click node_dispatcher "https://github.com/boxdawn/guard/blob/main/packaging/guard_entry.py"
click node_bash_eval "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_guard.py"
click node_ps_eval "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/powershell_guard.py"
click node_verdict "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py"
click node_fixed_rules "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_rules_source.py"
click node_secret_rules "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/secret_files.py"
click node_signed_rules "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/rules_bundle.py"
click node_korean "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/messages_ko.py"
click node_grep_guard "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py"
click node_undo "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/undo.py"
click node_block_log "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/block_log.py"
click node_block_send "https://github.com/boxdawn/guard/blob/main/boxdawn_guard/block_send.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hook,node_copilot_hook,node_dispatcher toneBlue
class node_bash_eval,node_ps_eval,node_verdict toneAmber
class node_fixed_rules,node_secret_rules,node_signed_rules,node_korean toneMint
class node_grep_guard,node_undo toneRose
class node_block_log,node_block_send,node_claude,node_copilot,node_boxdawn_service toneIndigo
```

## Components

### Hook entrypoints

- [Pre-tool hook](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py): `boxdawn_guard/command_hook.py`
- [Copilot hook](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/copilot_hook.py): `boxdawn_guard/copilot_hook.py`
- [Hook dispatcher](https://github.com/boxdawn/guard/blob/main/packaging/guard_entry.py): `packaging/guard_entry.py`

### Command judging

- [Bash evaluator](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_guard.py): `boxdawn_guard/command_guard.py`
- [PowerShell evaluator](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/powershell_guard.py): `boxdawn_guard/powershell_guard.py`
- [Decision response](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py): `boxdawn_guard/command_hook.py`

### Rules and secrets

- [Fixed command rules](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_rules_source.py): `boxdawn_guard/command_rules_source.py`
- [Secret-file rules](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/secret_files.py): `boxdawn_guard/secret_files.py`
- [Signed rule bundles](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/rules_bundle.py): `boxdawn_guard/rules_bundle.py`
- [Korean messages](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/messages_ko.py): `boxdawn_guard/messages_ko.py`

### Session safeguards

- [Secret-safe Grep](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/command_hook.py): `boxdawn_guard/command_hook.py`
- [Undo snapshots](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/undo.py): `boxdawn_guard/undo.py`

### Block records

- [Block log](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/block_log.py): `boxdawn_guard/block_log.py`
- [Block uploader](https://github.com/boxdawn/guard/blob/main/boxdawn_guard/block_send.py): `boxdawn_guard/block_send.py`

### Other components

- **Claude Code**
- **Copilot CLI**
- **Boxdawn service**

## Connections

- Claude Code → Pre-tool hook: invokes hook (evidence: `README.md`)
- Copilot CLI → Copilot hook: invokes hook (evidence: `README.md`)
- Hook dispatcher → Pre-tool hook: dispatches to (evidence: `packaging/guard_entry.py`)
- Hook dispatcher → Copilot hook: dispatches to (evidence: `packaging/guard_entry.py`)
- Pre-tool hook → Bash evaluator: evaluates Bash (evidence: `boxdawn_guard/command_hook.py`)
- Pre-tool hook → PowerShell evaluator: evaluates PowerShell (evidence: `boxdawn_guard/command_hook.py`)
- Pre-tool hook → Decision response: emits decision (evidence: `boxdawn_guard/command_hook.py`)
- Bash evaluator → Fixed command rules: uses rules (evidence: `README.md`)
- Bash evaluator → Secret-file rules: checks names (evidence: `boxdawn_guard/command_guard.py`)
- PowerShell evaluator → Secret-file rules: checks names (evidence: `boxdawn_guard/powershell_guard.py`)
- Pre-tool hook → Signed rule bundles: loads rules (evidence: `boxdawn_guard/command_hook.py`)
- Signed rule bundles → Fixed command rules: falls back to (evidence: `boxdawn_guard/rules_bundle.py`)
- Pre-tool hook → Korean messages: translates reasons (evidence: `boxdawn_guard/command_hook.py`)
- Pre-tool hook → Secret-safe Grep: filters searches (evidence: `boxdawn_guard/command_hook.py`)
- Secret-safe Grep → Secret-file rules: adds exclusions (evidence: `boxdawn_guard/command_hook.py`)
- Pre-tool hook → Undo snapshots: supports undo (evidence: `boxdawn_guard/command_hook.py`)
- Pre-tool hook → Block log: records verdicts (evidence: `boxdawn_guard/command_hook.py`)
- Block log → Block uploader: supplies records (evidence: `boxdawn_guard/block_send.py`)
- Hook dispatcher → Block uploader: starts upload (evidence: `packaging/guard_entry.py`)
- Block uploader → Boxdawn service: sends records (evidence: `boxdawn_guard/block_send.py`)
