Hermes-agent

2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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.