mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
docs: comprehensive documentation audit — fix 9 HIGH, 20+ MEDIUM gaps (#4087)
Reference docs fixes: - cli-commands.md: remove non-existent --provider alibaba, add hermes profile/completion/plugins/mcp to top-level table, add --profile/-p global flag, add --source chat option - slash-commands.md: add /yolo and /commands, fix /q alias conflict (resolves to /queue not /quit), add missing aliases (/bg, /set-home, /reload_mcp, /gateway) - toolsets-reference.md: fix hermes-api-server (not same as hermes-cli, omits clarify/send_message/text_to_speech) - profile-commands.md: fix show name required not optional, --clone-from not --from, add --remove/--name to alias, fix alias path, fix export/ import arg types, remove non-existent fish completion - tools-reference.md: add EXA_API_KEY to web tools requires_env - mcp-config-reference.md: add auth key for OAuth, tool name sanitization - environment-variables.md: add EXA_API_KEY, update provider values - plugins.md: remove non-existent ctx.register_command(), add ctx.inject_message() Feature docs additions: - security.md: add /yolo mode, approval modes (manual/smart/off), configurable timeout, expanded dangerous patterns table - cron.md: add wrap_response config, [SILENT] suppression - mcp.md: add dynamic tool discovery, MCP sampling support - cli.md: add Ctrl+Z suspend, busy_input_mode, tool_preview_length - docker.md: add skills/credential file mounting Messaging platform docs: - telegram.md: add webhook mode, DoH fallback IPs - slack.md: add multi-workspace OAuth support - discord.md: add DISCORD_IGNORE_NO_MENTION - matrix.md: add MSC3245 native voice messages - feishu.md: expand from 129 to 365 lines (encrypt key, verification token, group policy, card actions, media, rate limiting, markdown, troubleshooting) - wecom.md: expand from 86 to 264 lines (per-group allowlists, media, AES decryption, stream replies, reconnection, troubleshooting) Configuration docs: - quickstart.md: add DeepSeek, Copilot, Copilot ACP providers - configuration.md: add DeepSeek provider, Exa web backend, terminal env_passthrough/images, browser.command_timeout, compression params, discord config, security/tirith config, timezone, auxiliary models 21 files changed, ~1000 lines added
This commit is contained in:
Teknium
GitHub
parent
3c8f910973
commit
7e0c2c3ce3
21 changed files with 1004 additions and 83 deletions
|
|
@ -22,6 +22,61 @@ The security model has five layers:
|
|||
|
||||
Before executing any command, Hermes checks it against a curated list of dangerous patterns. If a match is found, the user must explicitly approve it.
|
||||
|
||||
### Approval Modes
|
||||
|
||||
The approval system supports three modes, configured via `approvals.mode` in `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
approvals:
|
||||
mode: manual # manual | smart | off
|
||||
timeout: 60 # seconds to wait for user response (default: 60)
|
||||
```
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| **manual** (default) | Always prompt the user for approval on dangerous commands |
|
||||
| **smart** | Use an auxiliary LLM to assess risk. Low-risk commands (e.g., `python -c "print('hello')"`) are auto-approved. Genuinely dangerous commands are auto-denied. Uncertain cases escalate to a manual prompt. |
|
||||
| **off** | Disable all approval checks — equivalent to running with `--yolo`. All commands execute without prompts. |
|
||||
|
||||
:::warning
|
||||
Setting `approvals.mode: off` disables all safety prompts. Use only in trusted environments (CI/CD, containers, etc.).
|
||||
:::
|
||||
|
||||
### YOLO Mode
|
||||
|
||||
YOLO mode bypasses **all** dangerous command approval prompts for the current session. It can be activated three ways:
|
||||
|
||||
1. **CLI flag**: Start a session with `hermes --yolo` or `hermes chat --yolo`
|
||||
2. **Slash command**: Type `/yolo` during a session to toggle it on/off
|
||||
3. **Environment variable**: Set `HERMES_YOLO_MODE=1`
|
||||
|
||||
The `/yolo` command is a **toggle** — each use flips the mode on or off:
|
||||
|
||||
```
|
||||
> /yolo
|
||||
⚡ YOLO mode ON — all commands auto-approved. Use with caution.
|
||||
|
||||
> /yolo
|
||||
⚠ YOLO mode OFF — dangerous commands will require approval.
|
||||
```
|
||||
|
||||
YOLO mode is available in both CLI and gateway sessions. Internally, it sets the `HERMES_YOLO_MODE` environment variable which is checked before every command execution.
|
||||
|
||||
:::danger
|
||||
YOLO mode disables **all** dangerous command safety checks for the session. Use only when you fully trust the commands being generated (e.g., well-tested automation scripts in disposable environments).
|
||||
:::
|
||||
|
||||
### Approval Timeout
|
||||
|
||||
When a dangerous command prompt appears, the user has a configurable amount of time to respond. If no response is given within the timeout, the command is **denied** by default (fail-closed).
|
||||
|
||||
Configure the timeout in `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
approvals:
|
||||
timeout: 60 # seconds (default: 60)
|
||||
```
|
||||
|
||||
### What Triggers Approval
|
||||
|
||||
The following patterns trigger approval prompts (defined in `tools/approval.py`):
|
||||
|
|
@ -30,21 +85,32 @@ The following patterns trigger approval prompts (defined in `tools/approval.py`)
|
|||
|---------|-------------|
|
||||
| `rm -r` / `rm --recursive` | Recursive delete |
|
||||
| `rm ... /` | Delete in root path |
|
||||
| `chmod 777` | World-writable permissions |
|
||||
| `chmod 777/666` / `o+w` / `a+w` | World/other-writable permissions |
|
||||
| `chmod --recursive` with unsafe perms | Recursive world/other-writable (long flag) |
|
||||
| `chown -R root` / `chown --recursive root` | Recursive chown to root |
|
||||
| `mkfs` | Format filesystem |
|
||||
| `dd if=` | Disk copy |
|
||||
| `> /dev/sd` | Write to block device |
|
||||
| `DROP TABLE/DATABASE` | SQL DROP |
|
||||
| `DELETE FROM` (without WHERE) | SQL DELETE without WHERE |
|
||||
| `TRUNCATE TABLE` | SQL TRUNCATE |
|
||||
| `> /etc/` | Overwrite system config |
|
||||
| `systemctl stop/disable/mask` | Stop/disable system services |
|
||||
| `kill -9 -1` | Kill all processes |
|
||||
| `curl ... \| sh` | Pipe remote content to shell |
|
||||
| `bash -c`, `python -e` | Shell/script execution via flags |
|
||||
| `find -exec rm`, `find -delete` | Find with destructive actions |
|
||||
| `pkill -9` | Force kill processes |
|
||||
| Fork bomb patterns | Fork bombs |
|
||||
| `bash -c` / `sh -c` / `zsh -c` / `ksh -c` | Shell command execution via `-c` flag (including combined flags like `-lc`) |
|
||||
| `python -e` / `perl -e` / `ruby -e` / `node -c` | Script execution via `-e`/`-c` flag |
|
||||
| `curl ... \| sh` / `wget ... \| sh` | Pipe remote content to shell |
|
||||
| `bash <(curl ...)` / `sh <(wget ...)` | Execute remote script via process substitution |
|
||||
| `tee` to `/etc/`, `~/.ssh/`, `~/.hermes/.env` | Overwrite sensitive file via tee |
|
||||
| `>` / `>>` to `/etc/`, `~/.ssh/`, `~/.hermes/.env` | Overwrite sensitive file via redirection |
|
||||
| `xargs rm` | xargs with rm |
|
||||
| `find -exec rm` / `find -delete` | Find with destructive actions |
|
||||
| `cp`/`mv`/`install` to `/etc/` | Copy/move file into system config |
|
||||
| `sed -i` / `sed --in-place` on `/etc/` | In-place edit of system config |
|
||||
| `pkill`/`killall` hermes/gateway | Self-termination prevention |
|
||||
| `gateway run` with `&`/`disown`/`nohup` | Prevents starting gateway outside service manager |
|
||||
| `gateway run` with `&`/`disown`/`nohup`/`setsid` | Prevents starting gateway outside service manager |
|
||||
|
||||
:::info
|
||||
**Container bypass**: When running in `docker`, `singularity`, `modal`, or `daytona` backends, dangerous command checks are **skipped** because the container itself is the security boundary. Destructive commands inside a container can't harm the host.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue