GitHub - StructuPath/herdr-guard: Cross-agent command policy for Herdr: audit, alert, and interrupt dangerous shell commands · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Uh oh!
There was an error while loading. Please reload this page.
StructuPath
herdr-guard
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>10 Commits<br>10 Commits
assets
assets
docs
docs
scripts
scripts
src
src
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
herdr-plugin.toml
herdr-plugin.toml
package.json
package.json
View all files
Repository files navigation
herdr-guard
Cross-agent command policy for Herdr: watch every pane,<br>audit risky commands, notify you, and best-effort interrupt dangerous shell<br>input.
Scripted dry-run using the real policy engine; the displayed command is never<br>executed.
Coverage (honest contract)
Pane<br>Guard sees<br>Interrupt guarantee
Interactive zsh/bash<br>Typed and unsubmitted input<br>Strong pre-execution cancel via ctrl+c
Raw/no-echo shell<br>Nothing typed<br>None; stty -echo is alerted
Pi/Claude/Codex TUIs<br>Only rendered terminal text<br>Incidental; harness hooks remain authoritative
Logs/builds<br>Printed output<br>Best-effort while process is running
Herdr popups<br>Nothing in v1<br>Blind spot
This is a text policy layer, not intent analysis. Shell obfuscation, detached<br>nested multiplexers, popup panes, and a stopped/disabled guard are documented<br>limitations. Use native agent hooks for authoritative tool-call enforcement.
Install
herdr plugin install StructuPath/herdr-guard
For local development:
herdr plugin link /path/to/herdr-guard
The startup hook seeds the per-user rules file and idempotently opens the Guard<br>pane. You can also focus or reopen it from the plugin action list with<br>structupath.guard.open. The pane subscribes to Herdr's<br>pane.output_matched events and maintains a local pane.read sweep backstop.<br>It does not modify other panes during installation.
Actions
Open guard — launch the dashboard pane.
Pause enforcement — pause actions for 15 minutes; matches remain audited.
Resume enforcement — reactivate immediately.
Test a command — dry-run text against active rules.
Reset guard rules — back up and reseed defaults.
Configuration
Rules live at $HERDR_PLUGIN_CONFIG_DIR/rules.json; runtime audit files live<br>at $HERDR_PLUGIN_STATE_DIR. Both directories are private (0700) and files<br>are written 0600. The configuration supports audit, alert, and<br>interrupt severity, regex or substring matching, and prompt_only.
A workspace may add substring rules in .herdr-guard.json. Project rules and<br>severity raises are always capped at alert; repository-controlled regex and<br>interrupt rules are rejected. Workspace rules cannot disable or lower global<br>rules unless the user explicitly enables allow_project_override in the<br>global configuration. Configuration writes are atomic and malformed updates<br>keep the last known-good policy.
The shipped policy covers destructive filesystem/Git/infrastructure commands,<br>secret-file reads, publishing, data exfiltration, and evasion indicators such<br>as stty -echo, detached tmux/screen, disown, base64-to-shell, and eval<br>subshells. Review the defaults before enabling interrupt rules in production.
Security and trust
This plugin is ordinary local code with the same privileges as Herdr and the<br>user who installs it. Herdr plugins are not sandboxed or reviewed. Inspect the<br>manifest and source before installing. The audit log contains sensitive<br>metadata even after token redaction; protect and rotate it appropriately.
The guard is advisory against a process that can disable the plugin, kill its<br>pane, stop Herdr, or use an unobserved popup/nested session. The socket API has<br>no plugin-specific read-only ACL in the current Herdr release. Events are<br>reconciled with baseline suppression to avoid replayed scrollback triggering a<br>fresh interrupt, and interrupt matches are intentionally never deduplicated.
Development
Requirements: Herdr 0.7.5+, Node.js...