aiSecurityWarden

aiSecurityWarden client

The open-source client for [aiSecurityWarden](https://aisecuritywarden.com), a secrets service with scoped, revocable machine tokens, end-to-end encryption and human approval for AI agents. Built so AI agents (like Hermes Agent) and other unattended services can fetch API keys at startup without ever storing those keys on disk.

All encryption and decryption happens here, in the client. The server only ever receives ciphertext, proofs it keeps only as Argon2id hashes, and wrapped keys, so you can check what leaves your machine by reading this code.

Get an account and see how it works at [aisecuritywarden.com](https://aisecuritywarden.com).

This repository contains:

• the Python client library (securitywarden.client.SecurityWardenClient);
• swctl, the command-line tool (machines: swctl export / swctl run; admins: swctl admin ...);
• swadmin, a small desktop admin window;
• the cryptography (src/securitywarden/crypto.py), the approval-policy and address-list parsers, and the shared test vectors other implementations are checked against;
• the protocol and design document: docs/DESIGN.md.

The aiSecurityWarden server is a separate product.

Status: alpha. The design is deliberately small and reviewable, but it has not had an independent

security audit. Read the threat model.

How it works

 Admin workstation                 aiSecurityWarden server                Agent box (e.g. jarvis)

───────────────── ───────────────────── ─────────────────────── swctl admin ... stores only: sw1.m. . : • creates project key ───────▶ • ciphertext (chmod 600 file) • encrypts secrets • Argon2 hashes │ • wraps project key • wrapped keys ◀── id+secret ─────┤ 1. auth → 5-min JWT per machine token • audit log ─── ciphertext ──▶ │ 2. fetch │ 3. decrypt locally with ▼ KEY=VALUE → agent env → tools

A machine token has three parts:

So the server can authenticate a token and hand out ciphertext, but it cannot read any secret. A full copy of the server's database is useless without a token key.

Threat model

Protects against

• Secrets at rest on agent machines: only a token sits on disk, not your API keys. Backups, copied dotfiles and logs leak a token you can revoke in one command.
• Server compromise: the database holds only AES-256-GCM ciphertext, Argon2 hashes and wrapped keys. Ciphertext is bound to its project, token and name (AAD), so a malicious server can't swap blobs around either.
• Over-broad access: each token is read-only and scoped to one project.
• Stale credentials: tokens can expire; revocation takes effect on the next request (access JWTs are re-checked against the database every time).
• Brute force: Argon2id hashing, per-IP and per-token failure rate limiting, and the same timing for unknown token ids.

Does not protect against

• An attacker who already controls the agent machine while it's running. They can read the token file, or read the decrypted secrets from the process memory or environment. No secrets manager can prevent that.
• Losing the admin credential. Project keys are wrapped under it; without it the secrets can't be recovered (by design). Keep it in your password manager.
• A server operator who swaps in malicious *client* code. Install swctl from a source you trust.

Install

pipx install aisecuritywarden     # or: pip install aisecuritywarden (in a virtual environment)

It installs the commands swctl, sw-mcp and swadmin. In Python code (connectors) the package is imported as securitywarden, e.g. from securitywarden.mcp import Connector.

Coming from 0.6 (installed as `securitywarden`)? Reinstall once under the new name; your tokens and settings stay where they are:

pip uninstall securitywarden && pip install aisecuritywarden     # same environment as before

Needs Python 3.10+, on Linux, Windows or macOS (all three are tested in CI). swadmin also needs Tkinter: it ships with the python.org installers for Windows and macOS; on Debian/Ubuntu, sudo apt install python3-tk.

macOS

1. Install Python from python.org (3.10 or newer). Its installer includes a current Tk, so swadmin works. Avoid Apple's built-in /usr/bin/python3: its Tk is old and draws windows badly. With Homebrew's Python, also run brew install python-tk.
2. Install the client in its own virtual environment:

   python3 -m venv ~/.venvs/securitywarden

~/.venvs/securitywarden/bin/pip install aisecuritywarden ~/.venvs/securitywarden/bin/swadmin # the admin window; swctl and sw-mcp are next to it

1. Files live where they do on Linux: ~/.config/securitywarden/ (tokens, the admin credential file if you use one, swctl's cached 2FA session), each readable by you only.

The website works in Safari too (CI runs it in WebKit, Safari's engine).

Updating

sw-mcp update --check     # or: swctl update --check

sw-mcp update # installs the newest signed release; never an older one

Or ask your agent: "check for aiSecurityWarden updates" / "update aiSecurityWarden". The agent's securitywarden_update tool asks you to approve the exact version first. Restart the agent app afterwards. When a newer client is out, the agent is told once (and every time if the server requires it). Updates are signed with an offline release key and checked against the key built into the client; see DESIGN.md "Client updates".

From source:

git clone https://github.com/SoftDevEng/aiSecurityWarden-client && cd aiSecurityWarden-client

pip install -e ".[dev]" && pytest

Quick start

You need the address of an aiSecurityWarden server and, to administer it, its admin credential.

1. Admin (from your workstation)

mkdir -p ~/.config/securitywarden

echo 'sw1.a....' > ~/.config/securitywarden/admin.cred && chmod 600 ~/.config/securitywarden/admin.cred export SW_SERVER_URL=https://vault.example.com

swctl admin project create hermes-webull swctl admin secret set hermes-webull WEBULL_APP_KEY # prompts; value never in argv/history swctl admin secret set hermes-webull WEBULL_APP_SECRET swctl admin token create hermes-webull --name jarvis --expires-days 180

2. Machine

export SW_SERVER_URL=https://vault.example.com SW_TOKEN_ID=<token id> SW_TOKEN_NAME=jarvis

swctl setup # paste the one-time setup code the website (or --setup-code) shows

swctl export # KEY=VALUE lines swctl export --format json swctl run -- python my_bot.py # run a command with secrets in its environment

Hermes Agent integration

Hermes supports custom vaults through a command helper that prints KEY=VALUE lines at launch. That's exactly what swctl export does. See examples/hermes/ for a wrapper script and config.

AI agent tools with approval (sw-mcp)

sw-mcp gives an agent tools for an application, such as Gmail, as an MCP server. Every action goes through the token's rules in aiSecurityWarden: reading may be allowed outright, while sending an email waits until you approve exactly that email (on the website, in swadmin, Telegram or ntfy). The agent is told it's waiting and checks back. See docs/mcp-gmail.md for the Gmail set-up with Hermes, and DESIGN.md for writing a connector for another application.

sw-mcp tools --connector gmail          # the tools, their actions, risks and suggested rules

sw-mcp serve --connector gmail # what Hermes runs (stdio) sw-mcp call gmail_search query=is:unread limit=5 # try one tool by hand; waits for approval if needed sw-mcp setup --token-file ~/.config/securitywarden/gmail-token # store the token from a one-time setup code

Other applications get a connector: one Python class whose tools each declare an action and a risk. An AI can write one: sw-mcp new-connector NAME creates the project (with instructions for the AI in AGENTS.md), sw-mcp guide prints the rules, and sw-mcp check plus the generated tests confirm it's right. Installed connector packages are found by name (--connector NAME). See docs/connectors.md.

Connectors can also come from aiSecurityWarden itself: turn a built-in one (Gmail) on for a project on the website, or upload your own (sw-mcp pack NAME, then Connectors > Upload; encrypted in the browser, account-wide, versioned with a backup of the version replaced). sw-mcp serve then loads whatever the token's project uses, with no --connector needed, and picks up new versions as you choose: at once, or on the next restart.

Teaching the agent the rules

Every agent connected to sw-mcp is told the essentials when it connects: how to wait for an approval, to treat email and web content as untrusted, to use only setup codes you typed, and to update through securitywarden_update (never pip or pipx, never killing sw-mcp). Agents that support skills can get the full guide too:

sw-mcp skill install hermes     # Hermes Agent: ~/.hermes/skills/aisecuritywarden/SKILL.md

sw-mcp skill install claude # Claude Code: ~/.claude/skills/aisecuritywarden/SKILL.md sw-mcp skill zip claude # Claude app: upload the .zip in its Skills settings

Then start a new session in the agent. sw-mcp serve keeps skills it installed up to date after each client update; a SKILL.md you wrote yourself is never replaced.

Admin commands

| swctl admin approvals list / approve ID [--match NN] / deny ID | decide pendi