hermes-plugin-guard 0.1.3__tar.gz

hermes_plugin_guard-0.1.3/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.3] - 2026-07-28
+
+### Added
+
+- Recognize pip-distributed Hermes plugins declared through
+  `[project.entry-points."hermes_agent.plugins"]`, including multiple entry points per package,
+  without requiring `plugin.yaml`; validate entry-point and dashboard declarations additively when
+  a plugin ships more than one supported declaration.
+- Inspect `plugin.yaml` `pip_dependencies` and flag remote installer commands that download and
+  pipe mutable scripts directly to a shell as `HPG204`.
+- Report `register_middleware()` as a privileged execution surface.
+
+### Changed
+
+- Match the current Hermes contracts for `optional_env`, exclusive memory-provider lifecycle
+  hooks, dashboard manifest required fields, and dashboard entry bundles.
+- Stop treating Python docstrings as sensitive-path findings, and resolve literal `__import__()`
+  targets so their process and network behavior is reported in addition to `HPG101`.
+- Ignore a Python distribution's own extras when checking third-party dependency bounds and avoid
+  secret-name findings for metadata variables ending in `_URL`, `_URI`, `_SCOPE`, `_ID`, `_NAME`,
+  or `_PATH`.
+- Bound every untrusted manifest parse by size and depth, including the dependency pass.
+
+## [0.1.2] - 2026-07-25
+
+### Added
+
+- `HPG112` inventories concrete outbound Python network calls without executing code, resolving
+  DNS, or making requests.
+- Destination-aware findings redact credentials, paths, queries, fragments, headers, and payloads,
+  and distinguish loopback, encrypted, cleartext, and link-local/cloud-metadata targets.
+
+### Changed
+
+- Recognize the current Hermes `pre_verify` and Kanban task hooks so valid plugin manifests do not
+  receive `HPG006` compatibility findings.
+
+## [0.1.1] - 2026-07-23
+
+### Added
+
+- Five-minute beta-test quickstart and a structured feedback issue form.
+- A reproducible 20-second terminal demo for the README and community posts.
+- Opt-in, tokenless PyPI Trusted Publishing workflow for published GitHub releases, including
+  distribution attestations and a safe configuration gate.
+- Maintainer release checklist for the one-time PyPI and GitHub environment setup.
+
+### Changed
+
+- Ignore tests, fixtures, caches, virtual environments, and generated directories during default
+  behavior and secret scanning so development-only samples do not dominate plugin reports.
+- Recognize nested plugin repositories and official dashboard-only plugins that use
+  `dashboard/manifest.json`.
+- Update the reusable GitHub Action and documentation examples to current Node 24-based action
+  releases.
+- Clarified that scans remain local, do not execute target plugin code, make no network requests,
+  include no telemetry, and upload neither source nor results.
+- Updated installation and GitHub Action examples for the v0.1.1 release.
+
+## [0.1.0] - 2026-07-23
+
+### Added
+
+- Static discovery and validation of one plugin or a repository of plugins.
+- Manifest checks for metadata, plugin kind, entry point, declared environment, and hook drift.
+- AST-based checks for high-risk Python capabilities and load-time behavior.
+- Heuristic scanning for committed secret material.
+- Remote-dependency pinning and version-bound checks.
+- Human-readable, JSON, SARIF, and GitHub annotation output.
+- Configurable failure thresholds and per-rule command-line exclusions.
+- Composite GitHub Action and pinned continuous-integration workflow.
+
+[Unreleased]: https://github.com/mauricemohr88-debug/hermes-plugin-guard/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/mauricemohr88-debug/hermes-plugin-guard/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/mauricemohr88-debug/hermes-plugin-guard/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/mauricemohr88-debug/hermes-plugin-guard/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/mauricemohr88-debug/hermes-plugin-guard/releases/tag/v0.1.0

hermes_plugin_guard-0.1.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code of conduct
+
+## Our commitment
+
+We are committed to making participation in this project a respectful, harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience, education,
+socioeconomic status, nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Expected behavior
+
+Examples of behavior that supports a healthy community include:
+
+- using welcoming and inclusive language;
+- giving specific, technical, and empathetic feedback;
+- respecting differing viewpoints and experience;
+- accepting responsibility, apologizing, and learning from mistakes;
+- focusing on what is best for users and the wider community.
+
+Unacceptable behavior includes harassment, threats, discriminatory language, sexualized
+attention, deliberate intimidation, publishing another person's private information, and
+sustained disruption of project discussion.
+
+## Scope
+
+This code applies in project spaces and when someone publicly represents the project, including
+issues, pull requests, reviews, discussions, release channels, and community events.
+
+## Enforcement
+
+Project maintainers may edit, remove, or reject contributions and may temporarily or permanently
+restrict participation when behavior violates these standards. Enforcement decisions should be
+proportionate, documented privately, and protect the privacy and safety of people who report an
+incident.
+
+Report conduct concerns privately through the repository's
+[security advisory form](https://github.com/mauricemohr88-debug/hermes-plugin-guard/security/advisories/new)
+and start the title with `Code of Conduct`. Do not include sensitive personal information beyond
+what is needed to understand the incident. Reports will be reviewed promptly and as
+confidentially as practical.
+
+## Attribution
+
+This policy is informed by the [Contributor Covenant, version
+2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

hermes_plugin_guard-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for helping make Hermes plugin review more repeatable. Small, focused pull requests are
+easiest to review.
+
+## Set up a development environment
+
+```bash
+git clone https://github.com/mauricemohr88-debug/hermes-plugin-guard.git
+cd hermes-plugin-guard
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+Run the same checks as CI:
+
+```bash
+ruff check .
+ruff format --check .
+pytest --cov=hermes_plugin_guard --cov-report=term-missing
+python -m build
+```
+
+To apply formatting locally:
+
+```bash
+ruff check --fix .
+ruff format .
+```
+
+## Propose a change
+
+1. Search existing issues and pull requests for related work.
+2. Open an issue first for broad behavior changes or rule-ID changes.
+3. Create a focused branch and keep unrelated formatting out of the change.
+4. Add or update tests.
+5. Update the README and changelog when user-visible behavior changes.
+6. Explain the threat scenario, expected output, and false-positive tradeoff in the pull request.
+
+## Detection-rule expectations
+
+Rules are a public interface. New or changed rules should:
+
+- use the next stable `HPG` identifier and keep existing IDs unchanged;
+- describe observable behavior rather than label a plugin as malicious;
+- include a concise remediation;
+- report the narrowest useful file and line location;
+- have a positive fixture that triggers and a nearby negative fixture that does not;
+- avoid importing, executing, resolving, or installing target plugin code;
+- stay deterministic and avoid network access;
+- document important blind spots and expected false positives.
+
+Prefer Python AST inspection over regular expressions when syntax matters. Secret detection and
+non-Python metadata checks may use bounded text matching. Scanners must skip symlinks and handle
+malformed or unexpectedly encoded input without crashing the entire run.
+
+## Tests
+
+Use synthetic values in fixtures. Never commit real credentials, private plugin code, or a token
+that resembles a live credential more closely than the test requires.
+
+Tests should cover exit behavior and every supported output format when a change touches reporting
+or the CLI. Keep ordering deterministic so generated JSON and SARIF are stable.
+
+## Reporting security issues
+
+Follow [SECURITY.md](SECURITY.md). Please do not demonstrate an exploitable scanner issue in a
+public issue or pull request before a fix is available.
+
+By participating, you agree to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

hermes_plugin_guard-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maurice Mohr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_plugin_guard-0.1.3/MANIFEST.in

@@ -0,0 +1,7 @@
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+recursive-include docs *.svg
+recursive-include tests *.json *.py *.txt *.yaml
+recursive-include tests LICENSE SECURITY.md

hermes_plugin_guard-0.1.3/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-guard
+Version: 0.1.3
+Summary: Static, no-execution security checks for Hermes Agent plugins
+Author: Maurice Mohr
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mauricemohr88-debug/hermes-plugin-guard
+Project-URL: Issues, https://github.com/mauricemohr88-debug/hermes-plugin-guard/issues
+Project-URL: Repository, https://github.com/mauricemohr88-debug/hermes-plugin-guard
+Project-URL: Security, https://github.com/mauricemohr88-debug/hermes-plugin-guard/security/policy
+Keywords: hermes-agent,plugins,security,static-analysis,sarif
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: pytest<10,>=8.3; extra == "dev"
+Requires-Dist: pytest-cov<8,>=6; extra == "dev"
+Requires-Dist: ruff<1,>=0.11; extra == "dev"
+Dynamic: license-file
+
+# Hermes Plugin Guard
+
+[![CI](https://github.com/mauricemohr88-debug/hermes-plugin-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/mauricemohr88-debug/hermes-plugin-guard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab.svg)](pyproject.toml)
+
+![Hermes Plugin Guard social card](https://raw.githubusercontent.com/mauricemohr88-debug/hermes-plugin-guard/main/docs/social-card.svg)
+
+Review a Hermes Agent plugin before you enable it.
+
+Hermes Plugin Guard (`hpg`) is a local static scanner for
+[NousResearch Hermes Agent](https://github.com/NousResearch/hermes-agent) plugins. It
+checks plugin manifests, Python source, dependency declarations, likely secret material, and
+basic repository hygiene. Target plugin code is read as data: it is never imported or executed.
+
+This is an unofficial community project. It is not affiliated with, endorsed by, or maintained
+by Nous Research.
+
+![20-second terminal demo of installing and running Hermes Plugin Guard](https://raw.githubusercontent.com/mauricemohr88-debug/hermes-plugin-guard/v0.1.2/docs/demo.gif)
+
+## Five-minute beta test
+
+If you maintain or use a Hermes plugin, one local scan is enough to help improve the rules.
+Python 3.11 or newer and [pipx](https://pipx.pypa.io/stable/) are required.
+
+1. Install the v0.1.3 release directly from GitHub:
+
+   ```bash
+   pipx install \
+     "git+https://github.com/mauricemohr88-debug/hermes-plugin-guard.git@v0.1.3"
+   ```
+
+2. Scan your plugin without failing the command on findings:
+
+   ```bash
+   hpg scan /absolute/path/to/your-plugin --fail-on none
+   ```
+
+3. Send a short
+   [beta-test report](https://github.com/mauricemohr88-debug/hermes-plugin-guard/issues/new?template=beta-test.yml)
+   with the rule IDs that were useful, noisy, or missing. A public plugin URL is helpful but not
+   required.
+
+The scan stays on your computer. `hpg` reads target files as data, does not import or execute
+target plugin code, makes no network requests, includes no telemetry, and uploads neither source
+code nor results. Do not paste private code, credentials, or unsanitized paths into a public issue.
+
+Once v0.1.3 is visible on
+[PyPI](https://pypi.org/project/hermes-plugin-guard/), the shorter installation command is:
+
+```bash
+pipx install hermes-plugin-guard
+```
+
+Already installed? Use `pipx upgrade hermes-plugin-guard` for a PyPI installation, or reinstall
+the tagged GitHub URL above.
+
+## Why this exists
+
+Hermes plugins are Python extensions, not isolated data files. A third-party plugin can register
+tools and hooks and can run with the permissions of the Hermes process. Code review remains the
+most important control; `hpg` adds a fast, repeatable first pass before enablement and in CI.
+
+The scanner is designed to make high-risk patterns visible, including:
+
+- direct subprocess calls that bypass Hermes' terminal-tool approval path;
+- dynamic execution and unsafe deserialization;
+- sensitive-path access, destructive filesystem operations, and disabled TLS verification;
+- all-interface listeners, networking capability, concrete outbound calls with redacted
+  destinations, and undeclared secret environment variables;
+- privileged registration and middleware surfaces, plus work performed during import or
+  registration;
+- likely committed credentials, mutable remote dependencies, and remote scripts piped to shells;
+- plugin declaration drift, missing tests, and missing project policies.
+
+## Install
+
+Python 3.11 or newer is required.
+
+Install the current release directly from GitHub with
+[pipx](https://pipx.pypa.io/stable/) (recommended for command-line tools):
+
+```bash
+pipx install \
+  "git+https://github.com/mauricemohr88-debug/hermes-plugin-guard.git@v0.1.3"
+```
+
+After the release is published to
+[PyPI](https://pypi.org/project/hermes-plugin-guard/), install it by package name:
+
+```bash
+pipx install hermes-plugin-guard
+```
+
+Or install from a local checkout:
+
+```bash
+git clone https://github.com/mauricemohr88-debug/hermes-plugin-guard.git
+cd hermes-plugin-guard
+python -m pip install .
+```
+
+Both `hpg` and `hermes-plugin-guard` invoke the same command.
+
+## Usage
+
+Scan one plugin directory:
+
+```bash
+hpg scan /path/to/my-plugin
+```
+
+Scan a repository containing multiple plugins and fail when a high or critical finding exists:
+
+```bash
+hpg scan /path/to/plugins-repository --fail-on high
+```
+
+The scanner recognizes directory plugins using `plugin.yaml`, dashboard-only plugins using
+`dashboard/manifest.json`, and pip-distributed plugins using
+`[project.entry-points."hermes_agent.plugins"]` in `pyproject.toml`.
+
+Write machine-readable results:
+
+```bash
+hpg scan ./my-plugin --format json --output hpg.json
+hpg scan ./my-plugin --format sarif --output hpg.sarif
+```
+
+Show GitHub workflow annotations:
+
+```bash
+hpg scan ./my-plugin --format github
+```
+
+Exclude a reviewed rule for one invocation:
+
+```bash
+hpg scan ./my-plugin --exclude HPG106 --exclude HPG203
+```
+
+List the complete rule catalog and remediation guidance:
+
+```bash
+hpg rules
+```
+
+The default failure threshold is `high`. Use `--fail-on critical`, `high`, `medium`,
+`low`, `info`, or `none` to set policy. Exit code `0` means no finding reached the selected
+threshold, `1` means the policy threshold was reached, and `2` indicates an invocation or scan
+error.
+
+## Output
+
+`hpg` keeps rule IDs stable so findings can be discussed and tracked across runs.
+
+| Format | Intended use |
+| --- | --- |
+| `text` | Human-readable local review (default) |
+| `github` | File and line annotations in GitHub Actions logs |
+| `json` | Automation, baselines, and custom reporting |
+| `sarif` | SARIF-compatible code-scanning consumers |
+
+JSON includes the scan root, plugin and file counts, severity totals, sorted findings, and a
+stable fingerprint for each finding. SARIF includes rule metadata and source locations. Output is
+deterministic for unchanged inputs.
+
+## GitHub Actions
+
+The repository includes a composite action:
+
+```yaml
+name: Plugin security
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: mauricemohr88-debug/hermes-plugin-guard@v0.1.3
+        with:
+          path: path/to/plugin
+          fail-on: high
+          format: github
+```
+
+For stronger supply-chain controls, pin `hermes-plugin-guard` to a reviewed full commit SHA
+instead of a moving tag.
+
+## Rules at a glance
+
+| IDs | Area | Examples |
+| --- | --- | --- |
+| `HPG001`–`HPG006` | Declaration | Missing or invalid declarations, unknown kind, entry point and hook drift |
+| `HPG101`–`HPG112` | Python | Execution, deserialization, processes, sensitive paths, network and privileged behavior |
+| `HPG201`–`HPG204` | Supply chain | Likely secrets, mutable dependencies, unbounded versions, remote installers |
+| `HPG301`–`HPG303` | Project | License, security policy, and automated tests |
+
+Run `hpg rules` for the current severity, explanation, and suggested remediation for every rule.
+
+### Network-egress inventory
+
+`HPG106` reports that a plugin imports a network-capable module. `HPG112` is more specific: it
+reports a concrete outbound request or connection and records the statically visible destination.
+The scanner never resolves DNS or makes a request while doing this.
+
+Destination evidence is deliberately limited to the scheme, hostname, and port. User information,
+paths, query strings, fragments, headers, and payloads are never copied into a finding. Dynamic or
+relative destinations are reported as `<dynamic destination>`. Loopback calls default to low,
+encrypted external calls to medium, and explicitly cleartext HTTP, FTP, WebSocket, or gRPC and
+link-local/cloud-metadata targets to high. Raw TCP and SMTP stay medium because the protocol may
+upgrade to TLS after connecting.
+
+## Threat model
+
+The scanner assumes a plugin directory may be untrusted and inspects it without importing its
+Python modules. It aims to catch explicit, statically visible patterns that deserve human review.
+It also helps maintainers enforce a consistent minimum policy in pull requests.
+
+Scanning is a review aid, not a sandbox, signature verifier, malware detector, or proof that a
+plugin is safe. Enabling a plugin still grants its code the permissions of the Hermes process.
+Review the source, dependencies, requested environment variables, network destinations, and
+maintainer history before installation.
+
+## Limitations
+
+- Static analysis cannot reliably resolve dynamically constructed names, paths, commands, or
+  network destinations.
+- Egress checks cover common Python HTTP, WebSocket, socket, FTP, SMTP, and gRPC APIs. Calls hidden
+  behind dependencies, arbitrary SDK wrappers, native extensions, or dashboard JavaScript can
+  require manual review.
+- A finding describes a risky capability or pattern, not necessarily a vulnerability.
+- The absence of findings does not establish safety.
+- Secret matching is heuristic and may produce false positives or miss encoded or split secrets.
+- Dependency checks inspect `requirements*.txt`, `pyproject.toml`, and relevant `plugin.yaml`
+  declarations; they do not resolve, download, or audit dependency contents.
+- Symlinks and oversized files are skipped rather than followed or executed.
+- Suppressions are command-line policy choices and should be documented in the consuming project.
+
+If a result looks wrong, please open an issue with the smallest safe reproducer. Never attach
+live credentials or private plugin code to a public report.
+
+## Development and contributing
+
+Contributions are welcome, especially focused detection rules with both positive and negative
+tests. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and design expectations,
+[SECURITY.md](SECURITY.md) for private vulnerability reporting, and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
+
+## License
+
+MIT. See [LICENSE](LICENSE).