hermes-axiorank 0.1.0

AxioRank security gateway plugin for the Hermes agent framework.

AxioRank security gateway for Hermes

Route every Hermes agent tool call through AxioRank, the security gateway for AI agents. It scores tool calls and tool results for live secrets, prompt injection, destructive operations, PII, and risky egress, injects a live guardrail policy into the model's turn, and can hard block a dangerous action before it runs.

Works offline with no API key (local detectors). Add an AXIORANK_API_KEY to also escalate verdicts to the hosted gateway, apply your workspace policy, land the session in a central audit log, and mint a signed, offline-verifiable Coding Session Seal.

What you get

• Guard tools the agent can call: axiorank_inspect (score a command, content, or a tool call), axiorank_scan_mcp (verify an external MCP server or agent card before trusting it), axiorank_verify (offline-verify an audit receipt).
• A guardrail injected into every session: a standing policy banner plus a one-shot taint warning when a tool result is flagged, so a poisoned web page or MCP reply cannot quietly steer the agent.
• Audit and sealing: a per-session trace, a running risk tally, and a signed Coding Session Seal on exit (with a key).
• Optional hard blocking: a pre_tool_call shell hook that denies a dangerous action before it executes, installed with one command.
• A bundled skill that teaches the agent to self-gate risky actions.

Install

With pip (recommended)

pip install hermes-axiorank

Hermes discovers the plugin automatically on next start. Enable it:

hermes plugins enable axiorank

Directory drop

Copy the plugin into your Hermes plugins directory:

mkdir -p ~/.hermes/plugins/axiorank
cp -R src/hermes_axiorank/* ~/.hermes/plugins/axiorank/
pip install 'axiorank>=0.17'   # the detection engine
hermes plugins enable axiorank

Use

Start Hermes. You should see axiorank: axiorank_inspect, axiorank_scan_mcp, axiorank_verify in the tool list. Check status any time:

/axiorank status

The agent will call the guard tools on its own (guided by the bundled skill). To load the skill explicitly:

skill_view("axiorank:secure-tool-use")

Hosted mode (optional)

Set a workspace API key to escalate to the hosted gateway and enable session seals:

export AXIORANK_API_KEY=axr_live_...
# optional, defaults to https://app.axiorank.com
export AXIORANK_BASE_URL=https://app.axiorank.com

Get a key from app.axiorank.com.

Hard enforcement (optional)

Python plugin hooks observe tool calls but cannot block them mid-flight. To hard block a dangerous action before it runs, install the shell hook:

hermes axiorank init                 # guards terminal, write_file, file_edit, patch, web_fetch, mcp__*
hermes axiorank init --tools all     # guard every tool
hermes axiorank init --api-key axr_live_...   # also save the key to ./.env
hermes axiorank init --print         # print the config snippet instead of editing

This adds a pre_tool_call hook to ~/.hermes/config.yaml that runs axiorank-hermes-guard. It denies a call the detectors flag as high risk and stays silent otherwise, so Hermes's own permission flow is unaffected.

Configuration

The plugin runs with sensible defaults and no configuration. Environment variables:

Variable	Meaning
AXIORANK_API_KEY	Workspace key for hosted escalation and session seals. Optional.
AXIORANK_BASE_URL	Gateway base URL. Defaults to https://app.axiorank.com.
AXIORANK_MODE	enforce or monitor for the shell guard. Defaults to enforce once installed.
AXIORANK_HERMES_GUARD_DISABLE_REMOTE	Force local-only scoring in the shell guard.
AXIORANK_HERMES_GUARD_TIMEOUT_MS	Shell guard hosted-call timeout.

Posture (mode, deny threshold, blocked categories, result inspection, context injection) can also be set through the host plugin config. Defaults: monitor posture for the in-session hooks (they observe and inject context), a deny threshold of 75, a review band from 50, and blocked categories secret, destructive, malware, injection.

How it works

• Scoring uses the AxioRank detectors from the axiorank Python SDK, offline and keyless by default.
• With a key, each call is also reported to POST /api/gateway/tool-call; the central decision can only tighten the local one.
• The pre_llm_call hook returns context that Hermes appends to the user turn (never the system prompt), so the guardrail rides alongside the user's message and does not break prompt caching.

License

MIT