Aegis Signer

Name: Aegis Signer
Rating: 3.5 (1 reviews)
Author: msbel5

By msbel5 👁 8 views ▲ 0 votes

Ed25519-signed tool-call audit for OpenClaw — fabrication permanent fix (arXiv 2603.12621)

Homepage GitHub

Install

pip install pynacl

Configuration Example

{
  plugins: {
    entries: {
      "aegis-signer": {
        enabled: true,
        config: {
          signerPython: "/home/msbel/.openclaw/aegis/.venv/bin/python",
          signerScript: "/home/msbel/.openclaw/aegis/signer.py"
        }
      }
    }
  }
}

README

# @msbel/openclaw-aegis-signer

> Ed25519-signed, SHA-256-chained tool-call audit log for OpenClaw.
> Permanently fixes "MISSION ACCOMPLISHED" fabrication.

[![npm version](https://img.shields.io/npm/v/@msbel/openclaw-aegis-signer.svg)](https://www.npmjs.com/package/@msbel/openclaw-aegis-signer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Inspired by **AEGIS: No Tool Call Left Unchecked** ([arXiv 2603.12621](https://arxiv.org/abs/2603.12621)).

## Why

Multi-agent LLM systems frequently fabricate. Captain says "Builder
ran the test and it passed", but no actual tool call happened. The
Inspector has no cryptographic way to verify the claim's provenance.

AEGIS solves this with three pieces:

1. Every agent has its own Ed25519 keypair.
2. Every tool call (`Bash`, `Edit`, `Write`, `sessions_spawn`, ...)
   is signed and appended to `~/.openclaw/audit-log.jsonl`.
3. Each entry chains to the previous via SHA-256 so any tampering
   breaks the chain.

When Inspector reviews a session, it runs the verifier and checks
that every Captain or Builder claim has a backing signed entry. If
not, that's caught fabrication.

## How it works

```
┌─────────┐   tool call    ┌─────────┐   audit         ┌──────────────────┐
│  Agent  ├───────────────▶│  Hook   ├────────────────▶│ audit-log.jsonl  │
└─────────┘                │ plugin  │                 │  (Ed25519 +      │
                           └─────────┘                 │   SHA256 chain)  │
                                                       └─────────┬────────┘
                                                                 │
                                                                 ▼
                                                       ┌─────────────────┐
                                                       │  Inspector      │
                                                       │  runs verifier  │
                                                       └─────────────────┘
```

## Install

This plugin uses `child_process` to invoke the Ed25519 signer (Python
+ pynacl). OpenClaw's safety guard requires the unsafe-install flag:

```bash
# 1. Install the plugin from npm or local path
openclaw plugins install --dangerously-force-unsafe-install \
    @msbel/openclaw-aegis-signer

# 2. Install the Python signer side
mkdir -p ~/.openclaw/aegis
cd ~/.openclaw/aegis
python3 -m venv .venv
.venv/bin/pip install pynacl

# 3. Drop signer.py + verifier.py + genkeys.py from this repo's
#    `signer/` dir into ~/.openclaw/aegis/
cp signer/*.py ~/.openclaw/aegis/

# 4. Generate per-agent keypairs (one-shot)
~/.openclaw/aegis/.venv/bin/python ~/.openclaw/aegis/genkeys.py

# 5. Add to plugins.allow + entries
openclaw plugins enable aegis-signer
# (or edit ~/.openclaw/openclaw.json directly:
#   plugins.allow += ["aegis-signer"]
#   plugins.entries["aegis-signer"] = {"enabled": true})

# 6. Restart gateway
systemctl --user restart openclaw-gateway
```

Verify it loaded:

```bash
openclaw plugins inspect aegis-signer
# Expect: Status: loaded, Typed hooks: after_tool_call
```

## Configuration

```jsonc
{
  plugins: {
    entries: {
      "aegis-signer": {
        enabled: true,
        config: {
          signerPython: "/home/msbel/.openclaw/aegis/.venv/bin/python",
          signerScript: "/home/msbel/.openclaw/aegis/signer.py"
        }
      }
    }
  }
}
```

## Audit log entry shape

```json
{
  "seq": 1715823014123,
  "ts": "2026-04-29T03:14:23.123Z",
  "agent": "builder",
  "session_id": "sess_a1b2c3",
  "tool": "Bash",
  "input_hash": "sha256:abc123...",
  "input_preview": "git checkout -b agent/...",
  "output_hash": "sha256:def456...",
  "exit_status": "ok",
  "prev_hash": "sha256:ghi789...",
  "signature": "ed25519:base64sig..."
}
```

## Verifying the chain

```bash
~/.openclaw/aegis/.venv/bin/python ~/.openclaw/aegis/verifier.py
# verified: 47 ok, 0 bad, total 47
```

Exit 0 means clean. Any bad signature or broken chain returns exit 1.

## Inspector integration

Add to your Inspector agent's `AGENT.md`:

> Before APPROVING any session that involves Builder claims (`I ran X`,
> `tests passed`, `committed Y`), run
> `python3 ~/.openclaw/aegis/verifier.py` and read the relevant entries
> from `~/.openclaw/audit-log.jsonl` for the session_id under review.
> If verifier exits non-zero or if a claim has no backing entry in the
> log, REJECT with the specific gap.

## Failure modes

| Mode | Behavior |
|------|----------|
| `signer.py` crashes | Logged to stderr, tool call proceeds (fail-soft) |
| `audit-log.jsonl` not writable | Logged, tool call proceeds |
| Python venv missing | Logged once, all subsequent calls no-op |
| Key file missing | Sign skipped, agent_id placeholder in entry |

The plugin **never blocks** a tool call. Audit completeness is verified
post-hoc by Inspector, not enforced inline.

## Performance

| Metric | Value |
|--------|-------|
| Latency added per tool call | ~30-50 ms (subprocess + Ed25519 sign) |
| Disk per entry | ~500 bytes |
| Disk per year | ~18 MB at 100 calls/day |
| CPU | negligible (Ed25519 is fast) |

## Compatibility

- OpenClaw `>= 2026.3.24-beta.2`
- Node `>= 20`
- Python `>= 3.10`

## Source

- Paper: [arXiv 2603.12621](https://arxiv.org/abs/2603.12621)
- Reference impl: this repo
- Original Alcyone deployment: [github.com/msbel5/alcyone-experiments/tree/agent/aegis-v1](https://github.com/msbel5/alcyone-experiments/tree/agent/aegis-v1)

## License

MIT — see [LICENSE](LICENSE).

## Author

Mami ([@msbel5](https://github.com/msbel5)) with help from Claude.
Personal AI infrastructure project: Alcyone.

voice