Metadata-Version: 2.4
Name: hermes-axiorank
Version: 0.1.0
Summary: AxioRank security gateway plugin for the Hermes agent framework.
Project-URL: Homepage, https://axiorank.com
Project-URL: Documentation, https://app.axiorank.com/docs
Project-URL: Source, https://github.com/AxioRank/hermes-plugin
Project-URL: Issues, https://github.com/AxioRank/hermes-plugin/issues
Author: AxioRank
License: MIT
License-File: LICENSE
Keywords: agent,ai,axiorank,guardrails,hermes,hermes-agent,nousresearch,plugin,prompt-injection,security,zero-trust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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 :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: axiorank>=0.17
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: verify
Requires-Dist: axiorank[verify]>=0.17; extra == 'verify'
Description-Content-Type: text/markdown

# AxioRank security gateway for Hermes

Route every [Hermes](https://github.com/NousResearch/hermes-agent) agent tool call
through [AxioRank](https://axiorank.com), 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)

```bash
pip install hermes-axiorank
```

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

```bash
hermes plugins enable axiorank
```

### Directory drop

Copy the plugin into your Hermes plugins directory:

```bash
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:

```bash
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](https://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:

```bash
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`](https://pypi.org/project/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
