Zakaria
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# security-guidance
|
|
|
|
Pattern-matched security warnings for code the agent writes. When the agent
|
|
calls `write_file`, `patch`, or `skill_manage` with content that matches a
|
|
known-dangerous code pattern (eval, pickle.load, yaml.load, os.system,
|
|
subprocess with `shell=True`, `dangerouslySetInnerHTML`, `verify=False`, ECB
|
|
mode, GitHub Actions `${{ github.event.* }}` injection, `torch.load` without
|
|
`weights_only=True`, ...), the plugin appends a warning to the tool's result.
|
|
The file is still written; the model sees the warning in the next turn and
|
|
can fix the code or briefly document why the construct is safe.
|
|
|
|
This is layer 1 of Anthropic's `security-guidance` plugin design — a fast
|
|
first-pass that runs locally with zero LLM tokens spent. Layers 2 and 3 (LLM
|
|
diff review on turn end, agentic commit review) are not ported; the agent
|
|
can already run those kinds of reviews on demand via `delegate_task`.
|
|
|
|
## Coverage (25 rules)
|
|
|
|
The pattern set is forked verbatim from Anthropic's `claude-plugins-official`
|
|
under Apache-2.0. Categories:
|
|
|
|
| Category | Rules |
|
|
|---|---|
|
|
| Unsafe deserialization | `pickle.load`, `cPickle/cloudpickle/dill.load`, `marshal.loads`, `shelve.open`, `yaml.load`, `yaml.unsafe_load`, `torch.load` (without `weights_only=True`), `joblib.load`, `pandas.read_pickle`, `numpy.load(allow_pickle=True)` |
|
|
| Command injection | `os.system`, `subprocess(..., shell=True)`, JS `child_process.exec`, Go `exec.Command("sh"...)` |
|
|
| Code injection | `eval(`, JS `new Function(...)` |
|
|
| XSS sinks | `.innerHTML =`, `.outerHTML =`, `.insertAdjacentHTML(`, `document.write`, React `dangerouslySetInnerHTML` |
|
|
| Crypto footguns | AES ECB mode, Node `crypto.createCipher` (no IV), TLS verification disabled (`verify=False`, `rejectUnauthorized: false`, `InsecureSkipVerify: true`, ...) |
|
|
| XXE | `xml.etree`, `minidom`, `xml.sax` without `defusedxml` |
|
|
| Supply chain | `<script src="https://..."` without `integrity=` SRI hash |
|
|
| CI/CD injection | GitHub Actions workflow files using `${{ github.event.* }}` in `run:` |
|
|
|
|
The pattern data uses Python regex + literal-substring matching. Each rule
|
|
carries a per-extension `path_filter` lambda — Python-only rules skip `.js`,
|
|
JS rules skip `.py`, all rules skip `.md/.txt/.rst/.json/.yaml`. Lookbehind
|
|
assertions exclude method calls (so `model.eval()` and `redis.eval()` don't
|
|
trip the `eval(` rule). False-positive rate is mediocre but tolerable; the
|
|
plugin is warn-by-default precisely because of that.
|
|
|
|
## Enabling
|
|
|
|
Plugins are opt-in. Add it to your allow-list:
|
|
|
|
```bash
|
|
hermes plugins enable security-guidance
|
|
# or edit ~/.hermes/config.yaml manually:
|
|
plugins:
|
|
enabled:
|
|
- security-guidance
|
|
```
|
|
|
|
## Modes
|
|
|
|
| Env var | Default | Effect |
|
|
|---|---|---|
|
|
| (none) | warn | Appends a `⚠️ Security guidance` block to the tool result. The file is written. |
|
|
| `SECURITY_GUIDANCE_BLOCK=1` | unset | Refuses the write entirely with the warning as the block reason. Use for stricter environments. |
|
|
| `SECURITY_GUIDANCE_DISABLE=1` | unset | Kill switch — plugin loads but does nothing. |
|
|
|
|
## What it does **not** do (yet)
|
|
|
|
* **No LLM diff review.** Anthropic's layer 2 spawns an auxiliary LLM call
|
|
on every agent turn that touched files. On hermes that would route
|
|
through the main model by default (`auxiliary_client._resolve_auto()` is
|
|
main-model-first), which is real money on reasoning models. A separate
|
|
PR can wire layer 2 to a cheap auxiliary model with explicit opt-in.
|
|
* **No agentic commit review.** Anthropic's layer 3 spawns an SDK subagent
|
|
with `Read`/`Grep`/`Glob` to trace data flow on `git commit`. That's a
|
|
follow-up that would build on `delegate_task`.
|
|
* **No project-local rules file.** Anthropic's `.claude/claude-security-guidance.md`
|
|
is read by their layer 2/3 LLM prompts, not the pattern scanner. We can
|
|
add an analogous `.hermes/security-guidance.md` once layer 2 lands.
|
|
|
|
## Limitations
|
|
|
|
This is a best-effort assistive tool. Pattern matching can miss
|
|
vulnerabilities and produce false positives. Treat warnings as suggestions,
|
|
not a substitute for code review, SAST, dependency scanning, or pen testing.
|
|
|
|
## Attribution and licensing
|
|
|
|
* `patterns.py` is a verbatim fork from
|
|
[`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/security-guidance/hooks)
|
|
(commit `0bde168`, 2026-05-26), licensed under the
|
|
[Apache License 2.0](./LICENSE). See [NOTICE](./NOTICE) for the full
|
|
attribution.
|
|
* `__init__.py`, `plugin.yaml`, `README.md`, and tests are original work by
|
|
NousResearch, MIT-licensed alongside the rest of hermes-agent.
|