Hermes Security Plugin: Setup, Scan Modes and Safety Limits

Hermes Security is Nous Research's official plugin for reviewing a repository for security bugs. It builds a threat model, splits code between reviewers and keeps evidence alongside findings. To use it sensibly, start with a small static review and check its coverage before allowing tests or trusting a clean report.

The useful question is whether it can produce findings an engineer can investigate without starting the review again. Its documentation makes an important distinction between a problem supported by source code and one confirmed by a test. This guide follows the documented workflow; it is not a firsthand accuracy benchmark.

Install Hermes Security and enable the Desktop page

The official installation instructions require Hermes 0.21.5 or later and Python 3.11 or later. Install the plugin, then restart Hermes:

hermes plugins install hermes-security --enable

For later updates, use hermes plugins update hermes-security. In Hermes Desktop, also switch the plugin on under Capabilities → Plugins. The Desktop page depends on the Python plugin being installed and enabled; enabling one is not a substitute for checking the other.

If Desktop connects to Hermes on another machine, use Desktop's install dialog so it can fetch the page. Installing only on the remote backend can leave the page marked "unavailable (remote backend)". The repository path belongs to the machine running Hermes, which may not be the laptop displaying Desktop.

Run a useful first scan

Open the Security page, choose New scan and select a repository you own or are authorized to review. For a pending change, select Only my changes. The plugin uses uncommitted work or compares the branch with the default branch, depending on the repository state. Check which scope it selected before interpreting the result.

For a first whole-codebase review, choose a small, security-relevant folder and leave Deep scan and Run tests to confirm findings off. The model defaults to the one used by your chats. Additional context should describe the application and its trust boundaries, rather than ask vaguely for "all vulnerabilities."

For example, a team reviewing a multi-tenant invoice service could supply this context:

This service stores invoices for separate customer organizations.
Review the invoice download routes and their authorization helpers.
An authenticated user should only access invoices in their organization.
Trace where organization membership is checked and identify missing evidence.
Do not run tests or send requests to a running application.

This is an example review brief, not a test result. Its value is the explicit invariant: an authenticated user is not automatically authorized to read every invoice. A reviewer can trace the route, the organization lookup and the database query against that requirement instead of guessing what the application permits.

Start the scan and inspect the findings and coverage together. If background startup fails, the plugin drafts a chat message for you to send instead. You can also ask Hermes in chat to scan the repository for security issues.

Standard, deep and diff scans cover different work

A standard scan reads production source, configuration, CI, infrastructure code and migrations. It normally skips tests, fixtures, documentation, examples, generated files, assets and lockfiles, with an exception for committed secrets. Dependency checking is a separate step, so a lockfile excluded from the model's code review can still contribute advisory information.

The documented review plan splits code into roughly 4,000-line chunks and can run up to ten reviewers concurrently. A standard scan reads all production code if it fits within 90 chunks, roughly 360,000 lines. Beyond that budget, it prioritizes riskier files. Those numbers describe a coverage plan, not proof that every line was understood correctly.

Deep mode includes the categories standard mode skips and makes three independent passes by default. General exclusions such as vendored code, symlinks, special files and files over 8 MB still deserve attention in the report. More passes can increase model work without resolving a missing deployment assumption, so use deep mode for a specific reason rather than treating it as the only serious setting.

For routine development, a diff review is a sensible starting point because its findings have a smaller change set to investigate. A whole-repository review is more useful when you need to understand how a change interacts with authorization or other shared controls outside that diff.

Local reports do not mean local analysis

The marketplace disclosure says the configured model provider receives the code under review. Scan data stays in the active profile's plugin data folder, but that storage location does not make the review private to your machine. Check your provider and organization policy before scanning proprietary code.

Dependency checks have a separate data path. Package names and versions go to api.osv.dev, with api.deps.dev used for manifests without lockfiles; declared runtime versions go to endoflife.date. The first scan downloads a pinned osv-scanner release from GitHub, roughly 55 MB, and checks its SHA-256 before using it.

You can disable the dependency check with HERMES_SECURITY_DEPENDENCY_CHECK=off. That removes a useful source of advisory evidence and does not stop the configured model provider receiving review code. If the dependency check fails, the report marks the scan as partial. On a network that blocks the download, the documented alternative is an administrator-installed osv-scanner, referenced through HERMES_SECURITY_OSV_SCANNER.

There is no useful universal per-scan cost to quote from these instructions. The selected model, repository scope, repeated passes and retries affect the work performed. Start with a narrow scope and inspect provider usage before making whole-repository deep scans routine.

Test confirmation is not a sandbox

A temporary copy protects the original working tree, not the rest of the machine. Optional test confirmation runs reproductions using your normal toolchain and user account. Credential-looking environment variables are removed, but the documentation explicitly says this is not a sandbox. Only allow tests on code you trust, and use an appropriately isolated environment when execution could have consequences.

Testing a running application requires a separate per-scan grant. The documented grant allows up to 200 requests to one origin for one hour, with Stop revoking it early. Use a disposable test instance with non-production data rather than assuming an authorization checkbox makes active testing harmless.

The implementation contract requires both positive and negative controls before a finding becomes runtime-confirmed. In the invoice example, a useful test would show the unauthorized request succeeding when the control is missing and the expected rejection when the control is present. A proposed test that never ran remains NOT_RUN; it is not confirmation.

Read coverage before severity

Findings include evidence and remediation views, while proof gaps and counter-evidence are separate from severity. That separation is worth preserving in your team's triage: a severe possible outcome and a well-established exploit are different claims. Rejected and inconclusive candidates remain available rather than quietly disappearing.

A scan with zero findings and partial coverage is unfinished evidence, not a clean bill of health. Look for unread files, missing reviewer results and failed dependency checks. OWASP and ASVS mappings help organize the review, but they are not certification. Suggested patches are shown for inspection, not automatically applied, and reports can be exported as Markdown, JSON, CSV or SARIF.

If work stops partway through, use Continue scan or send another message. Automatic continuation is off by default. Enabling plugins.entries.hermes-security.allow_gateway_injection lets the plugin queue continuation messages, but it pauses after three automatic attempts without progress. A provider-error turn requires a message to resume, so unattended continuation is not a guarantee that a scan will finish.

The strongest way to adopt this plugin is to make the report part of an engineering decision: which assumption failed, which code proves it, what remains unread and which regression test would prevent a recurrence. A longer findings list is easy to generate. A finding that survives that review is what makes the tool useful.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help technical founders explain developer tools and AI workflows through clear technical writing that people can use and share.

Book a 30-minute call.