Hermes MCP workflow for security scans

Follow the current hermes integration guide and manually merge the server entry, preserving existing settings. Authenticate local stdio separately with npx -y lyrashield@0.2.14 login --oauth and use @lyrashield/mcp@0.2.12. Use pinned CLI commands for documented config or skill installs; marketplace plugins remain separately gated. Restart the client, confirm discovery, then call lyrashield_list_workspaces for authenticated read-only access. CLI doctor does not establish client authentication or scan completion.

You can pair Hermes AI with LyraShield AI over MCP to get target aware scans, recorded evidence states and fix proposals without leaving your agent workflow. In this guide you will add the local server using pinned npx -y @lyrashield/mcp@0.2.12 plus the remote endpoint at https://app.lyrashieldai.com/api/mcp inside ~/.hermes/config.yaml, verify tool discovery, run a scoped inline check and wire a diff aware GitHub Action gate that uploads SARIF for code scanning.

Fast generation from Hermes is powerful, but without review you can ship injection flaws, broken access control and vulnerable deps. Use the vibe coding security guide as your policy spine, then map categories to the OWASP Top 10 official standard and CWE Top 25 for concrete weakness definitions that justify your triage order. Bounded scans with explicit evidence states keep agents productive while preserving the limitations security teams need to see.

LyraShield follows a clear loop of Target to Scan to Evidence State to Fix Proposal to Retest to Assurance Report, with human approval retained for mutations.

1. Prerequisites and project baseline

You need Node.js 24 or newer which you can confirm via Node.js docs, Hermes installed locally, Git with PR workflow and a LyraShield API key shaped as lsk_… Export LYRASHIELD_API_KEY in your shell and never commit the raw value. Hermes reads ${env:VAR} inside config.yaml at startup, so the indirect reference stays safe.

LyraShield combines bounded repository review, SCA, secrets scanning, a GitHub Action and SARIF. Findings retain their recorded evidence states; scan detection alone is not a retest. Fix proposals and retests remain approval-gated and PR execution remains unavailable until a server-generated patch can be bound to an exact approval. Read Model Context Protocol to see why local stdio suits desktop tools and streamable HTTP suits remote servers.

Quick sanity check before editing config:

node -v
npm view @lyrashield/mcp version
ls ~/.hermes/
echo $LYRASHIELD_API_KEY | wc -c

Keep a sibling checklist handy such as Hermes app security checklist for fix patterns that match your generated stack. That checklist helps you translate a recorded finding into a concrete remediation, such as tightening auth middleware or upgrading a transitive dependency.

Define your target naming early. LyraShield treats target as the unit of verification. Examples include staging hermes app, production api or a preview deployment. A clear naming convention prevents confusion when you later add both local and remote servers and start sharing reports across the team.

2. Configure LyraShield MCP server in Hermes

Hermes stores MCP servers in ~/.hermes/config.yaml under mcp_servers. Each entry supports tools.include and tools.exclude filters, ssl_verify flag and env interpolation. Configure both local stdio and remote bearer.

mcp_servers:
  lyrashield:
    transport: stdio
    command: npx
    args: ["-y", "@lyrashield/mcp@0.2.12"]
    env:
      LYRASHIELD_API_KEY: ${env:LYRASHIELD_API_KEY}
    tools:
      include:
        - lyrashield_scan_target
        - lyrashield_get_findings
        - lyrashield_list_targets
        - lyrashield_get_scan_status
        - lyrashield_generate_fix_plan
        - lyrashield_record_fix_proposal
    ssl_verify: true
  lyrashield-remote:
    transport: streamable-http
    url: https://app.lyrashieldai.com/api/mcp
    headers:
      Authorization: Bearer ${env:LYRASHIELD_API_KEY}
    tools:
      include:
        - lyrashield_scan_target
        - lyrashield_get_findings
        - lyrashield_list_targets
    ssl_verify: true

This pins local to npx -y @lyrashield/mcp@0.2.12 and remote to https://app.lyrashieldai.com/api/mcp with bearer header. The canonical copy lives in Hermes integration guide. Use ${env:VAR} rather than raw keys. Keep tools.include explicit so only verification tools are exposed to the Hermes agent. Explicit includes also reduce accidental exposure of auxiliary tools that you do not want the agent to call without review.

If you run Hermes inside a shared container, mount the config file from a secure volume and ensure LYRASHIELD_API_KEY is injected via secret manager rather than baked into the image. That keeps rotation simple and avoids leaking keys into image layers.

3. Verify connection and list security tools

Restart Hermes after editing ~/.hermes/config.yaml. Open the MCP panel and expect lyrashield and lyrashield-remote to show connected with transport type stdio and streamable-http. If either shows failed, confirm that Node can resolve npx and that the shell that launched Hermes has LYRASHIELD_API_KEY exported. Also check that yaml indentation is exactly two spaces under mcp_servers, since Hermes uses strict yaml parsing. A common failure is launching Hermes from a GUI launcher or dock icon that does not inherit your shell environment, so the exported key never reaches the agent process; relaunch Hermes from the same terminal where you exported the key to fix the silent auth gap.

Ask Hermes to list tools:

Prompt: List MCP servers and tools from ~/.hermes/config.yaml.
Show transport, url or command and tool names for lyrashield entries.

Expected output:

lyrashield (stdio via npx -y @lyrashield/mcp@0.2.12):
- lyrashield_scan_target(targetId, goal, mode)
- lyrashield_get_findings(targetId)
- lyrashield_list_targets()
- lyrashield_get_scan_status(scanId)
- lyrashield_generate_fix_plan(findingId)
- lyrashield_record_fix_proposal(findingId, summary)

lyrashield-remote (streamable-http at https://app.lyrashieldai.com/api/mcp):
- lyrashield_scan_target, lyrashield_get_findings, lyrashield_list_targets

For context on supply chain findings, skim OSV database and for CI gating see GitHub Actions docs. These references explain how SARIF and dependency data flow together. Seeing identical core tools across both servers confirms that your auth works for both transports.

4. Run an inline security check from Hermes

With tools listed, run a focused verification without leaving Hermes. Keep scope tight to changed files for fast feedback. Tight scope also helps you stay within context limits when Hermes pulls file contents for evidence.

Prompt for Hermes agent:
Use lyrashield_scan_target for target staging-hermes-app.
Scope: src/app/api, src/lib. Exclude generated .next and node_modules.
Return findings with their recorded evidence state, CWE, evidence, file and line, severity.
Add OWASP mapping when present.
Persist report id for PR gate.

A good response contains finding id, severity, evidence state, CWE, file and line, evidence snippet and suggested patch location. Prioritize retest-confirmed findings while retaining detected and inconclusive items for triage. See OWASP Top 10 and CWE Top 25 for definitions when triaging.

This inline step also surfaces secrets that were templated into fixtures. Since v1 includes secrets scanning alongside SCA, one scan can reveal both hardcoded creds and vulnerable packages. Rotate any exposed secret before merging the fix PR.

Do not claim fixes, branches or PRs are automatic. Generate and record a fix proposal, apply it through the approved development workflow and queue a server-owned retest.

5. Wire a diff aware GitHub Action gate

Local checks are fast, but teams need PR enforcement that survives skipped local steps. Wire the official GitHub Action in diff aware mode and upload SARIF.

name: lyrashield security gate
on:
  pull_request:
    paths:
      - "src/**"
      - "app/**"
      - "packages/**"
  push:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - name: LyraShield diff scan
        uses: ecryptoguru/lyrashield-ai@v2
        with:
          fail_on_severity: HIGH

Require the security job in branch protection. The pairing of MCP for local dev and the Action for CI reflects ideas from Model Context Protocol around keeping context close to the agent while enforcing policy centrally. Details for reusable workflows live in GitHub Actions docs. Once required, developers cannot merge when findings meet the configured severity gate; that policy does not turn a detected finding into a retest-confirmed one.

6. Add agent rules for consistent secure coding

Add a repo local rules file that Hermes loads, for example hermes.md or .hermes/rules.md at project root. This file makes secure behavior the default.

# Hermes security rules

- Before finishing a feature, call lyrashield_scan_target on changed scope.
- Surface findings with CWE, file evidence and their recorded evidence state.
- For high severity findings, generate and record a fix proposal; do not claim a branch or PR was created.
- On every PR, ensure lyrashield security gate passed and SARIF uploaded.
- Reference OWASP Top 10 and internal vibe coding security guide when drafting PR descriptions.
- Never log raw secrets. Use ${env:LYRASHIELD_API_KEY}.

This file encodes the loop of Target to Scan to Evidence State to Fix Proposal to Retest to Assurance Report as daily practice. Keep it in version control so all Hermes sessions inherit the guardrail.

Stage	Hermes behavior	LyraShield verification	Evidence artifact
Generation	Generates APIs and UI from prompts via nousresearch patterns	N/A	Prompt trace
Inline check	Calls lyrashield_scan_target with tight scope	Findings, evidence states, SCA and secrets	Finding id plus CWE plus file path
PR gate	Pushes diff to GitHub	Diff aware scan plus SARIF plus fail on high	GitHub check green and code scanning annotations
Fix loop	Reviews and applies an approved proposal	Recorded fix proposal and server-owned retest	Retest outcome plus scan reference

Why pair Hermes with LyraShield

Hermes gives you strong local capability and prompt control, but local generation still needs centralized policy. LyraShield records bounded findings with explicit evidence states, maps issues to OWASP Top 10 and CWE Top 25, explains dependency risk with context from OSV and keeps the workflow inside MCP so you avoid switching to a separate UI. For Hermes users that value local control, this pairing preserves local execution for stdio while still giving you remote reporting via bearer auth when you need shared visibility.

Finish by running AI app security checklist on the release candidate and confirming your yaml matches Hermes integration guide. When ready to evaluate managed verification, create an account at LyraShield AI and keep the PR gate as your source of truth.