@botarmor/mcp 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +219 -2
- package/dist/api.js +87 -0
- package/dist/index.js +64 -0
- package/dist/tools.js +172 -0
- package/package.json +50 -4
- package/server.json +36 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BotArmor AI (Andrii Sydorenko EI)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,220 @@
|
|
|
1
|
-
#
|
|
1
|
+
# BotArmor MCP server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Crash-test your chatbot or AI agent from your AI assistant: Claude Code, Claude Desktop, ChatGPT, OpenAI Codex, Gemini CLI, Cursor, VS Code (Copilot) or Windsurf. Ask "test my agent with BotArmor" and BotArmor attacks the agent on up to 12 levels:
|
|
4
|
+
|
|
5
|
+
- fake manager;
|
|
6
|
+
- angry customer;
|
|
7
|
+
- fake lawyer;
|
|
8
|
+
- prompt injection;
|
|
9
|
+
- role-play;
|
|
10
|
+
- phishing;
|
|
11
|
+
- AI disclosure under the EU AI Act;
|
|
12
|
+
- invented facts;
|
|
13
|
+
- and more.
|
|
14
|
+
|
|
15
|
+
Level 13 is added for agents with tools. The assistant gets back a report written for it: what broke, how badly, and the exact text to add to the agent's instructions. It can then edit your code and run the audit again.
|
|
16
|
+
|
|
17
|
+
It is a thin wrapper over the [BotArmor API](https://app.botarmor.eu/api/v1/openapi.yaml), the same one the Make app, the n8n node and the GitHub Action use.
|
|
18
|
+
|
|
19
|
+
## How it works
|
|
20
|
+
|
|
21
|
+
1. **You ask your assistant.** For example: "Check the support agent in this repo with BotArmor."
|
|
22
|
+
2. **The assistant calls `start_audit`.** It passes the agent's system prompt, which it reads from your code.
|
|
23
|
+
- **Prompt mode** (default): BotArmor plays that prompt on its own model. Use it for an agent on localhost or not deployed yet.
|
|
24
|
+
- **Live mode**: BotArmor talks to your running bot at a public https URL. The assistant must first ask you to confirm you own the bot.
|
|
25
|
+
3. **BotArmor attacks.** For each level it runs 5 adaptive sessions. A judge model rules on each session, and a jury of three models confirms every break. An audit takes 5–20 minutes and uses one credit.
|
|
26
|
+
4. **The assistant polls `get_audit_status`.** It shows progress: levels done out of total.
|
|
27
|
+
5. **It reads `get_audit_report`.** The report gives the grade A–F, a table of levels with severity, and for each failed level what happened plus a ready-to-paste fix for the system prompt.
|
|
28
|
+
6. **It proposes the fix in your code.** With your OK it applies the fix, then runs `start_audit` again to check that the level now holds.
|
|
29
|
+
|
|
30
|
+
Your API key stays in your MCP client's configuration. The assistant never receives it. Prompts are not stored by BotArmor, only a SHA-256 fingerprint.
|
|
31
|
+
|
|
32
|
+
## Get an API key
|
|
33
|
+
|
|
34
|
+
Create a key in the [BotArmor dashboard](https://app.botarmor.eu/app/), tab **API**. It starts with `ba_live_`. In the examples below, replace `ba_live_xxx` with it. Keep the key out of your repository: use user-level configuration, or an environment variable.
|
|
35
|
+
|
|
36
|
+
## Connect your assistant
|
|
37
|
+
|
|
38
|
+
### Claude Code
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
claude mcp add botarmor --scope user -e BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Check with `claude mcp list`, or `/mcp` inside a session.
|
|
45
|
+
|
|
46
|
+
### Claude Desktop
|
|
47
|
+
|
|
48
|
+
Menu **Settings → Developer → Edit Config** opens `claude_desktop_config.json`:
|
|
49
|
+
|
|
50
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
51
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
52
|
+
|
|
53
|
+
Add the server, then fully quit and reopen Claude Desktop:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"botarmor": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
61
|
+
"env": { "BOTARMOR_API_KEY": "ba_live_xxx" }
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### ChatGPT (web) and claude.ai: remote server, no install
|
|
68
|
+
|
|
69
|
+
Hosts that only connect to servers on the internet use BotArmor's hosted endpoint:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
https://app.botarmor.eu/mcp
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
1. Add it as a custom MCP server or connector in your host. In ChatGPT this is the apps and connectors settings with developer mode. In claude.ai it is **Settings → Connectors → Add custom connector**. Menu names change often; look for "MCP server" or "custom connector".
|
|
76
|
+
2. The host opens a BotArmor page. Paste your API key there and click **Connect**.
|
|
77
|
+
3. The host receives its own token (OAuth 2.1 with PKCE). It never sees your API key.
|
|
78
|
+
4. To disconnect, remove the connector, or revoke the API key in the BotArmor dashboard.
|
|
79
|
+
|
|
80
|
+
The tools are the same four.
|
|
81
|
+
|
|
82
|
+
### ChatGPT desktop app and OpenAI Codex (CLI and IDE)
|
|
83
|
+
|
|
84
|
+
They share one configuration. Use either the command line:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
codex mcp add botarmor --env BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
or `~/.codex/config.toml`:
|
|
91
|
+
|
|
92
|
+
```toml
|
|
93
|
+
[mcp_servers.botarmor]
|
|
94
|
+
command = "npx"
|
|
95
|
+
args = ["-y", "@botarmor/mcp"]
|
|
96
|
+
env = { BOTARMOR_API_KEY = "ba_live_xxx" }
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
In the ChatGPT desktop app you can also add it under **Settings → MCP servers → STDIO**, with command `npx`, arguments `-y @botarmor/mcp` and the env variable.
|
|
100
|
+
|
|
101
|
+
### Gemini CLI
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
gemini mcp add -s user -e BOTARMOR_API_KEY=ba_live_xxx botarmor npx -y @botarmor/mcp
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
or `~/.gemini/settings.json`:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"mcpServers": {
|
|
112
|
+
"botarmor": {
|
|
113
|
+
"command": "npx",
|
|
114
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
115
|
+
"env": { "BOTARMOR_API_KEY": "$BOTARMOR_API_KEY" }
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`$BOTARMOR_API_KEY` is read from your shell environment, so the key is not written in the file. Check with `/mcp` in a session.
|
|
122
|
+
|
|
123
|
+
### Cursor
|
|
124
|
+
|
|
125
|
+
`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"mcpServers": {
|
|
130
|
+
"botarmor": {
|
|
131
|
+
"command": "npx",
|
|
132
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
133
|
+
"env": { "BOTARMOR_API_KEY": "ba_live_xxx" }
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### VS Code (GitHub Copilot agent mode)
|
|
140
|
+
|
|
141
|
+
Run **MCP: Open User Configuration** from the Command Palette and add the server. VS Code asks for the key once and stores it securely:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"inputs": [
|
|
146
|
+
{ "type": "promptString", "id": "botarmor-key", "description": "BotArmor API key (ba_live_...)", "password": true }
|
|
147
|
+
],
|
|
148
|
+
"servers": {
|
|
149
|
+
"botarmor": {
|
|
150
|
+
"type": "stdio",
|
|
151
|
+
"command": "npx",
|
|
152
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
153
|
+
"env": { "BOTARMOR_API_KEY": "${input:botarmor-key}" }
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Note that VS Code uses `servers`, not `mcpServers`.
|
|
160
|
+
|
|
161
|
+
### Windsurf and other MCP clients
|
|
162
|
+
|
|
163
|
+
Any client that runs local MCP servers (stdio) works with the same three values:
|
|
164
|
+
|
|
165
|
+
- command: `npx`
|
|
166
|
+
- args: `-y @botarmor/mcp`
|
|
167
|
+
- env: `BOTARMOR_API_KEY`
|
|
168
|
+
|
|
169
|
+
In Windsurf, use the `mcpServers` block as for Cursor, in `~/.codeium/windsurf/mcp_config.json`.
|
|
170
|
+
|
|
171
|
+
## What to ask
|
|
172
|
+
|
|
173
|
+
- "Check my agent on localhost:3000 with BotArmor." This runs a **prompt audit** from the system prompt in your code, because BotArmor's servers cannot reach your localhost.
|
|
174
|
+
- "Audit our staging bot at https://staging.example.com/v1/chat/completions with BotArmor, it's OpenAI-compatible, the token is in .env." This runs a **live audit**; the assistant asks you to confirm you own the bot.
|
|
175
|
+
- "Is the BotArmor audit done? Show me the report and fix the prompt."
|
|
176
|
+
- "List my last BotArmor audits."
|
|
177
|
+
|
|
178
|
+
## Tools
|
|
179
|
+
|
|
180
|
+
| Tool | What it does |
|
|
181
|
+
|---|---|
|
|
182
|
+
| `start_audit` | Starts an audit and returns its id (`BA-XXXXXXXX`). It takes 5–20 minutes and uses one audit credit. |
|
|
183
|
+
| `get_audit_status` | Status, progress (levels done out of total), and the grade once completed. |
|
|
184
|
+
| `get_audit_report` | Grade, a table of levels with severity, and for each failed level what happened plus the text to paste into the system prompt. |
|
|
185
|
+
| `list_audits` | Your latest audits. |
|
|
186
|
+
|
|
187
|
+
`start_audit` parameters:
|
|
188
|
+
|
|
189
|
+
- `system_prompt` (required): the agent's instructions. For a live audit it is also the rulebook the judge checks answers against.
|
|
190
|
+
- `target_type`, one of:
|
|
191
|
+
- `prompt`: the default when no URL is given;
|
|
192
|
+
- `openai-compatible`: a chat-completions endpoint;
|
|
193
|
+
- `webhook`: any JSON endpoint.
|
|
194
|
+
- `endpoint_url`: a public https URL, for live audits.
|
|
195
|
+
- `headers`: what the target needs. A credential header (`Authorization`, `X-API-Key`…) is stored encrypted by BotArmor and never returned.
|
|
196
|
+
- `model`: for `openai-compatible`, the model name sent in the body.
|
|
197
|
+
- `body_template` and `response_path`: for `webhook`. The body uses `{{input}}`, `"{{history}}"` or `"{{messages}}"`; the path points to the reply, e.g. `data.reply`.
|
|
198
|
+
- `levels`: a subset of `logic, toxic, hacker, lawyer, multilang, loop, roleplay, phishing, ethics, burst, disclosure, facts, agency`.
|
|
199
|
+
- `lang`: the report language (`fr`, `en`, `de`, `es`, `ru`).
|
|
200
|
+
- `min_grade`: the pass threshold.
|
|
201
|
+
- `authorization_confirmed`: must be `true` for a live audit. Set it only when you own the bot or hold the owner's written permission. BotArmor never tests third-party bots.
|
|
202
|
+
|
|
203
|
+
## Errors you may see
|
|
204
|
+
|
|
205
|
+
- **"BotArmor rejected the API key"**: check `BOTARMOR_API_KEY`.
|
|
206
|
+
- **"No audit credit left"**: buy a pack or upgrade in the dashboard.
|
|
207
|
+
- **"... is only reachable from this machine"**: use `target_type: "prompt"`, or a public tunnel such as `cloudflared tunnel --url http://localhost:3000`.
|
|
208
|
+
- **"the target bot did not answer"**: the live bot was down, or its URL or headers are wrong.
|
|
209
|
+
- **"An audit is already running"**: one audit at a time per account.
|
|
210
|
+
|
|
211
|
+
## Develop
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
npm install
|
|
215
|
+
npm test # builds, then runs unit tests and an end-to-end stdio test against a mock API
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`BOTARMOR_API_URL` points the server at another API base (default `https://app.botarmor.eu/api/v1`).
|
|
219
|
+
|
|
220
|
+
MIT licence. BotArmor AI is a brand of Rhone IA (Andrii Sydorenko EI), France. Reports are point-in-time test attestations, not certifications.
|
package/dist/api.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// Thin client for the BotArmor API v1 (the same API the Make app and the n8n node use).
|
|
2
|
+
// The API key comes from the environment and is never logged or echoed back to the model.
|
|
3
|
+
export const DEFAULT_BASE_URL = "https://app.botarmor.eu/api/v1";
|
|
4
|
+
export class BotArmorError extends Error {
|
|
5
|
+
status;
|
|
6
|
+
constructor(message, status) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.status = status;
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
// Plain-language messages for the errors a user can act on.
|
|
12
|
+
function explain(status, apiMessage) {
|
|
13
|
+
switch (status) {
|
|
14
|
+
case 401:
|
|
15
|
+
return "BotArmor rejected the API key. Check BOTARMOR_API_KEY (it starts with ba_live_; create one in the BotArmor dashboard, tab API).";
|
|
16
|
+
case 402:
|
|
17
|
+
return `No audit credit left on this BotArmor account (${apiMessage}). Buy a pack or upgrade the plan in the dashboard.`;
|
|
18
|
+
case 403:
|
|
19
|
+
return `BotArmor refused the audit: ${apiMessage}. A live audit needs authorization_confirmed: true, which means the user owns the bot or holds the owner's written permission.`;
|
|
20
|
+
case 404:
|
|
21
|
+
return `Not found: ${apiMessage}.`;
|
|
22
|
+
case 409:
|
|
23
|
+
return `${apiMessage}. Wait for the running audit to finish (get_audit_status) before starting another one.`;
|
|
24
|
+
case 429:
|
|
25
|
+
return `BotArmor rate limit reached (${apiMessage}). Retry in a minute.`;
|
|
26
|
+
case 503:
|
|
27
|
+
return `BotArmor is temporarily unavailable: ${apiMessage}.`;
|
|
28
|
+
default:
|
|
29
|
+
return `BotArmor API error ${status}: ${apiMessage}`;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
export class BotArmorClient {
|
|
33
|
+
apiKey;
|
|
34
|
+
baseUrl;
|
|
35
|
+
fetchImpl;
|
|
36
|
+
constructor(apiKey, baseUrl = DEFAULT_BASE_URL, fetchImpl = fetch) {
|
|
37
|
+
this.apiKey = apiKey;
|
|
38
|
+
this.baseUrl = baseUrl;
|
|
39
|
+
this.fetchImpl = fetchImpl;
|
|
40
|
+
if (!apiKey)
|
|
41
|
+
throw new BotArmorError("BOTARMOR_API_KEY is not set. Add it to the MCP server's environment (claude mcp add botarmor -e BOTARMOR_API_KEY=ba_live_... -- npx -y @botarmor/mcp).");
|
|
42
|
+
}
|
|
43
|
+
async request(method, path, body, headers = {}) {
|
|
44
|
+
let res;
|
|
45
|
+
try {
|
|
46
|
+
res = await this.fetchImpl(`${this.baseUrl}${path}`, {
|
|
47
|
+
method,
|
|
48
|
+
headers: { authorization: `Bearer ${this.apiKey}`, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}), ...headers },
|
|
49
|
+
body: body ? JSON.stringify(body) : undefined,
|
|
50
|
+
signal: AbortSignal.timeout(30_000),
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
catch (err) {
|
|
54
|
+
throw new BotArmorError(`Cannot reach the BotArmor API at ${this.baseUrl}: ${err.message}`);
|
|
55
|
+
}
|
|
56
|
+
const text = await res.text();
|
|
57
|
+
let data;
|
|
58
|
+
try {
|
|
59
|
+
data = text ? JSON.parse(text) : {};
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
data = { error: text.slice(0, 200) };
|
|
63
|
+
}
|
|
64
|
+
// 412 = completed below the threshold in strict mode; the body is still the status.
|
|
65
|
+
if (!res.ok && res.status !== 412)
|
|
66
|
+
throw new BotArmorError(explain(res.status, data?.error || res.statusText), res.status);
|
|
67
|
+
return data;
|
|
68
|
+
}
|
|
69
|
+
listAgents() {
|
|
70
|
+
return this.request("GET", "/agents");
|
|
71
|
+
}
|
|
72
|
+
createAgent(body) {
|
|
73
|
+
return this.request("POST", "/agents", body);
|
|
74
|
+
}
|
|
75
|
+
startAudit(body, idempotencyKey) {
|
|
76
|
+
return this.request("POST", "/audits", body, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {});
|
|
77
|
+
}
|
|
78
|
+
status(code) {
|
|
79
|
+
return this.request("GET", `/audits/${encodeURIComponent(code)}/status`);
|
|
80
|
+
}
|
|
81
|
+
audit(code) {
|
|
82
|
+
return this.request("GET", `/audits/${encodeURIComponent(code)}`);
|
|
83
|
+
}
|
|
84
|
+
listAudits(limit) {
|
|
85
|
+
return this.request("GET", `/audits?limit=${limit}`);
|
|
86
|
+
}
|
|
87
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// BotArmor MCP server (stdio). Install in Claude Code:
|
|
3
|
+
// claude mcp add botarmor -e BOTARMOR_API_KEY=ba_live_... -- npx -y @botarmor/mcp
|
|
4
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
5
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
import { BotArmorClient, BotArmorError, DEFAULT_BASE_URL } from "./api.js";
|
|
8
|
+
import { LEVELS, startAudit, getAuditStatus, getAuditReport, listAudits } from "./tools.js";
|
|
9
|
+
const VERSION = "0.1.1";
|
|
10
|
+
const server = new McpServer({ name: "botarmor", version: VERSION });
|
|
11
|
+
// The client is created on first use, so a missing key becomes a readable tool error instead of a crash at start.
|
|
12
|
+
let client = null;
|
|
13
|
+
const api = () => (client ??= new BotArmorClient(process.env.BOTARMOR_API_KEY ?? "", process.env.BOTARMOR_API_URL || DEFAULT_BASE_URL));
|
|
14
|
+
async function run(fn) {
|
|
15
|
+
try {
|
|
16
|
+
return { content: [{ type: "text", text: await fn() }] };
|
|
17
|
+
}
|
|
18
|
+
catch (err) {
|
|
19
|
+
const message = err instanceof BotArmorError ? err.message : `Unexpected error: ${err.message}`;
|
|
20
|
+
return { content: [{ type: "text", text: message }], isError: true };
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
const CODE = z.string().regex(/^BA-[0-9A-Z]{8}$/).describe("Audit id, e.g. BA-7NRZ26D4");
|
|
24
|
+
server.registerTool("start_audit", {
|
|
25
|
+
title: "Start a BotArmor audit",
|
|
26
|
+
description: "Crash-test a chatbot or AI agent with BotArmor: up to 12 attack levels (fake manager, angry customer, fake lawyer, prompt injection, role-play, phishing, AI disclosure under the EU AI Act, invented facts...) plus level 13 for agents with tools, 5 adaptive sessions each. " +
|
|
27
|
+
"Two modes. target_type 'prompt' (default when no endpoint_url): BotArmor plays the agent's system prompt on its own model; use it for an agent running on localhost or not deployed yet, reading the system prompt from the code. " +
|
|
28
|
+
"target_type 'openai-compatible' or 'webhook': a live audit of a running bot at a public https URL; requires authorization_confirmed: true, only after the user confirmed they own the bot or have written permission. " +
|
|
29
|
+
"Returns the audit id; an audit takes 5 to 20 minutes, then use get_audit_status and get_audit_report. Uses one audit credit.",
|
|
30
|
+
inputSchema: {
|
|
31
|
+
system_prompt: z.string().min(1).max(8000).describe("The agent's system prompt / instructions, as in its code. For a live audit it is also the rulebook the judge checks answers against."),
|
|
32
|
+
target_type: z.enum(["prompt", "openai-compatible", "webhook"]).optional().describe("Default: 'webhook' when endpoint_url is given, else 'prompt'."),
|
|
33
|
+
endpoint_url: z.string().optional().describe("Public https URL of the running agent (live audits only). localhost cannot be reached from BotArmor's servers."),
|
|
34
|
+
headers: z.record(z.string(), z.string()).optional().describe("Headers the target needs, e.g. {\"Authorization\": \"Bearer ...\"}. A credential header is stored encrypted by BotArmor."),
|
|
35
|
+
model: z.string().optional().describe("openai-compatible only: the model name sent in the request body."),
|
|
36
|
+
body_template: z.unknown().optional().describe("webhook only: JSON body with {{input}} (current message), \"{{history}}\" or \"{{messages}}\". Default {message: \"{{input}}\", session_id: \"{{session_id}}\"}."),
|
|
37
|
+
response_path: z.string().optional().describe("webhook only: dot path to the reply text in the response JSON, e.g. data.reply."),
|
|
38
|
+
levels: z.array(z.enum(LEVELS)).optional().describe("Subset of levels; default all 12 (plus 'agency' when tools are declared)."),
|
|
39
|
+
name: z.string().max(120).optional().describe("Name shown in the report."),
|
|
40
|
+
lang: z.enum(["fr", "en", "de", "es", "ru"]).optional().describe("Report language, default en."),
|
|
41
|
+
min_grade: z.enum(["A", "B", "C", "D", "F"]).optional().describe("Pass threshold shown by get_audit_status, default B."),
|
|
42
|
+
authorization_confirmed: z.boolean().optional().describe("Live audits only. true = the user confirmed they own the bot or hold the owner's written permission to test it."),
|
|
43
|
+
},
|
|
44
|
+
annotations: { destructiveHint: false, openWorldHint: true },
|
|
45
|
+
}, async (input) => run(() => startAudit(api(), input)));
|
|
46
|
+
server.registerTool("get_audit_status", {
|
|
47
|
+
title: "BotArmor audit status",
|
|
48
|
+
description: "Status and progress of a BotArmor audit (levels done out of total), and the grade once completed.",
|
|
49
|
+
inputSchema: { audit_id: CODE },
|
|
50
|
+
annotations: { readOnlyHint: true },
|
|
51
|
+
}, async ({ audit_id }) => run(() => getAuditStatus(api(), audit_id)));
|
|
52
|
+
server.registerTool("get_audit_report", {
|
|
53
|
+
title: "BotArmor audit report",
|
|
54
|
+
description: "Findings of a completed BotArmor audit: grade, a table of levels with severity and breaks, and for every failed level what happened and the exact text to add to the agent's system prompt. Use it to propose the fix in the agent's code, then re-run start_audit to check.",
|
|
55
|
+
inputSchema: { audit_id: CODE },
|
|
56
|
+
annotations: { readOnlyHint: true },
|
|
57
|
+
}, async ({ audit_id }) => run(() => getAuditReport(api(), audit_id)));
|
|
58
|
+
server.registerTool("list_audits", {
|
|
59
|
+
title: "List BotArmor audits",
|
|
60
|
+
description: "The user's latest BotArmor audits, newest first, with status, grade and score.",
|
|
61
|
+
inputSchema: { limit: z.number().int().min(1).max(50).optional().describe("How many, default 10.") },
|
|
62
|
+
annotations: { readOnlyHint: true },
|
|
63
|
+
}, async ({ limit }) => run(() => listAudits(api(), limit ?? 10)));
|
|
64
|
+
await server.connect(new StdioServerTransport());
|
package/dist/tools.js
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
// The four tools, as plain functions over BotArmorClient so they can be tested without an MCP transport.
|
|
2
|
+
// Outputs are Markdown written for a model: what broke, how badly, and the exact text to paste into the agent's
|
|
3
|
+
// instructions, so the assistant can propose the fix in the user's code right away.
|
|
4
|
+
import { BotArmorError } from "./api.js";
|
|
5
|
+
export const LEVELS = ["logic", "toxic", "hacker", "lawyer", "multilang", "loop", "roleplay", "phishing", "ethics", "burst", "disclosure", "facts", "agency"];
|
|
6
|
+
// Addresses our cloud cannot reach (and the API refuses on purpose: SSRF protection).
|
|
7
|
+
const LOCAL_HOST = /^(localhost|.*\.localhost|.*\.local|.*\.internal|127(\.\d+){3}|0\.0\.0\.0|10(\.\d+){3}|192\.168(\.\d+){2}|172\.(1[6-9]|2\d|3[01])(\.\d+){2}|\[?::1\]?|host\.docker\.internal)$/i;
|
|
8
|
+
// One header can be stored encrypted as the agent's key: the one that looks like a credential.
|
|
9
|
+
const SECRET_HEADER = /^(authorization|x-api-key|api-key|apikey|x-auth-token|x-access-token)$/i;
|
|
10
|
+
export function splitHeaders(headers = {}) {
|
|
11
|
+
const plain = {};
|
|
12
|
+
let secret = null;
|
|
13
|
+
for (const [k, v] of Object.entries(headers)) {
|
|
14
|
+
if (!secret && SECRET_HEADER.test(k))
|
|
15
|
+
secret = { header: k, value: String(v) };
|
|
16
|
+
else
|
|
17
|
+
plain[k] = String(v);
|
|
18
|
+
}
|
|
19
|
+
return { plain, secret };
|
|
20
|
+
}
|
|
21
|
+
export async function startAudit(client, input) {
|
|
22
|
+
const type = input.target_type ?? (input.endpoint_url ? "webhook" : "prompt");
|
|
23
|
+
const common = {
|
|
24
|
+
system_prompt: input.system_prompt,
|
|
25
|
+
...(input.levels?.length ? { levels: input.levels } : {}),
|
|
26
|
+
lang: input.lang ?? "en",
|
|
27
|
+
...(input.min_grade ? { min_grade: input.min_grade } : {}),
|
|
28
|
+
};
|
|
29
|
+
if (type === "prompt") {
|
|
30
|
+
const started = await client.startAudit({ ...common, target: { type: "prompt", name: input.name || "Agent tested from MCP" } });
|
|
31
|
+
return started_text(started, "simulated");
|
|
32
|
+
}
|
|
33
|
+
if (!input.endpoint_url)
|
|
34
|
+
throw new BotArmorError("endpoint_url is required for a live audit (target_type webhook or openai-compatible).");
|
|
35
|
+
let url;
|
|
36
|
+
try {
|
|
37
|
+
url = new URL(input.endpoint_url);
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
throw new BotArmorError(`endpoint_url is not a valid URL: ${input.endpoint_url}`);
|
|
41
|
+
}
|
|
42
|
+
if (LOCAL_HOST.test(url.hostname)) {
|
|
43
|
+
throw new BotArmorError(`${url.host} is only reachable from this machine, so BotArmor's servers cannot attack it. Either run a prompt-only audit (target_type "prompt" with the agent's system prompt from the code: no network needed), or expose the agent through a public https tunnel (e.g. "cloudflared tunnel --url ${url.origin}" or ngrok) and audit that URL.`);
|
|
44
|
+
}
|
|
45
|
+
if (url.protocol !== "https:")
|
|
46
|
+
throw new BotArmorError("endpoint_url must use https.");
|
|
47
|
+
if (input.authorization_confirmed !== true) {
|
|
48
|
+
throw new BotArmorError("A live audit attacks a running bot. Set authorization_confirmed: true only after the user confirms they own this bot or hold the owner's written permission to test it.");
|
|
49
|
+
}
|
|
50
|
+
const agentId = await ensureAgent(client, input, type, url.toString());
|
|
51
|
+
const started = await client.startAudit({ ...common, target: { type: "webhook", agent_id: agentId }, authorization_confirmed: true });
|
|
52
|
+
return started_text(started, "live");
|
|
53
|
+
}
|
|
54
|
+
async function ensureAgent(client, input, type, endpoint) {
|
|
55
|
+
// Reuse the bot already registered for this URL (its stored key and settings stay as they were).
|
|
56
|
+
const { agents = [] } = await client.listAgents();
|
|
57
|
+
const existing = agents.find((a) => a.endpoint_url === endpoint && a.platform === "webhook");
|
|
58
|
+
if (existing)
|
|
59
|
+
return existing.id;
|
|
60
|
+
const { plain, secret } = splitHeaders(input.headers);
|
|
61
|
+
const config = { headers: plain };
|
|
62
|
+
if (secret)
|
|
63
|
+
config.auth = { header: secret.header, prefix: "" };
|
|
64
|
+
if (type === "openai-compatible") {
|
|
65
|
+
config.body_template = { model: input.model || "default", messages: "{{messages}}" };
|
|
66
|
+
config.response_path = "choices.0.message.content";
|
|
67
|
+
}
|
|
68
|
+
else {
|
|
69
|
+
if (input.body_template !== undefined)
|
|
70
|
+
config.body_template = input.body_template;
|
|
71
|
+
if (input.response_path)
|
|
72
|
+
config.response_path = input.response_path;
|
|
73
|
+
}
|
|
74
|
+
const created = await client.createAgent({
|
|
75
|
+
name: input.name || `${new URL(endpoint).host} (MCP)`,
|
|
76
|
+
endpoint_url: endpoint,
|
|
77
|
+
...(secret ? { api_key: secret.value } : {}),
|
|
78
|
+
config,
|
|
79
|
+
});
|
|
80
|
+
const id = created.agent?.id ?? created.id;
|
|
81
|
+
if (!id)
|
|
82
|
+
throw new BotArmorError("BotArmor did not return the new agent's id.");
|
|
83
|
+
return id;
|
|
84
|
+
}
|
|
85
|
+
function started_text(started, mode) {
|
|
86
|
+
return [
|
|
87
|
+
`Audit ${started.audit_code} started (${started.mode ?? mode}).`,
|
|
88
|
+
started.idempotent_replay ? "This is the same audit as an earlier identical request." : "",
|
|
89
|
+
"A full audit takes about 5 to 20 minutes. Poll get_audit_status with this id, then call get_audit_report.",
|
|
90
|
+
started.mode === "simulated" || mode === "simulated"
|
|
91
|
+
? "Mode simulated: BotArmor played the system prompt on its own model. It is an estimate; a live audit of the running bot is the reliable verdict."
|
|
92
|
+
: "",
|
|
93
|
+
]
|
|
94
|
+
.filter(Boolean)
|
|
95
|
+
.join("\n");
|
|
96
|
+
}
|
|
97
|
+
export async function getAuditStatus(client, code) {
|
|
98
|
+
const s = await client.status(code);
|
|
99
|
+
const p = s.progress;
|
|
100
|
+
const lines = [
|
|
101
|
+
`Audit ${s.audit_code}: ${s.status} (${s.mode}).`,
|
|
102
|
+
p?.levels_total ? `Progress: ${p.levels_done}/${p.levels_total} levels.` : "",
|
|
103
|
+
s.status === "completed" ? `Grade ${s.grade} (${s.overall_score}/100). Gate ${s.gate?.min_grade}: ${s.gate?.passed ? "passed" : "failed"}.` : "",
|
|
104
|
+
s.status === "failed" ? `Failed: ${s.error}${/unreachable|HTTP \d|timed? ?out|ECONN/i.test(s.error ?? "") ? " (the target bot did not answer: check its URL, headers and that it is online)" : ""}` : "",
|
|
105
|
+
s.status === "running" ? "Still running: check again in a minute or two." : "",
|
|
106
|
+
s.status === "completed" ? "Call get_audit_report for the findings and fixes." : "",
|
|
107
|
+
];
|
|
108
|
+
return lines.filter(Boolean).join("\n");
|
|
109
|
+
}
|
|
110
|
+
const SEVERITY_ORDER = ["critical", "high", "medium", "low", "none"];
|
|
111
|
+
export function formatReport(audit) {
|
|
112
|
+
if (audit.status === "running")
|
|
113
|
+
return `Audit ${audit.audit_code} is still running. Poll get_audit_status first.`;
|
|
114
|
+
if (audit.status === "failed")
|
|
115
|
+
return `Audit ${audit.audit_code} failed: ${audit.error}`;
|
|
116
|
+
const report = audit.report?.report;
|
|
117
|
+
if (!report)
|
|
118
|
+
return `Audit ${audit.audit_code} has no report yet.`;
|
|
119
|
+
// Verdict and patch per level come from the level summaries in the event log.
|
|
120
|
+
const summaries = new Map();
|
|
121
|
+
for (const e of audit.events ?? [])
|
|
122
|
+
if (e.event_type === "level_summary")
|
|
123
|
+
summaries.set(e.payload?.level, e.payload);
|
|
124
|
+
const checks = (report.checks ?? []).filter((c) => c.trials || c.severity);
|
|
125
|
+
checks.sort((a, b) => SEVERITY_ORDER.indexOf(a.severity ?? "none") - SEVERITY_ORDER.indexOf(b.severity ?? "none"));
|
|
126
|
+
const failed = checks.filter((c) => c.passed === false);
|
|
127
|
+
const out = [];
|
|
128
|
+
out.push(`# BotArmor audit ${report.audit_code}: grade ${report.grade} (${report.scores?.overall ?? audit.overall_score}/100)`);
|
|
129
|
+
out.push(`Agent: ${report.agent_name ?? audit.agent_name}. Signed report, public verification: ${report.verify_url}`);
|
|
130
|
+
if (report.severity_counts)
|
|
131
|
+
out.push(`Severity counts: ${Object.entries(report.severity_counts).map(([k, v]) => `${k} ${v}`).join(", ")}.`);
|
|
132
|
+
out.push("");
|
|
133
|
+
out.push("| Level | Severity | Breaks | Score | Passed |");
|
|
134
|
+
out.push("|---|---|---|---|---|");
|
|
135
|
+
for (const c of checks)
|
|
136
|
+
out.push(`| ${c.label ?? c.id} | ${c.severity ?? "none"} | ${c.trials ? `${c.trials.breaks}/${c.trials.n}` : "-"} | ${c.score ?? "-"} | ${c.passed ? "yes" : "no"} |`);
|
|
137
|
+
out.push("");
|
|
138
|
+
if (!failed.length) {
|
|
139
|
+
out.push("No level broke. Nothing to fix; re-run after the next change to the agent's instructions.");
|
|
140
|
+
}
|
|
141
|
+
else {
|
|
142
|
+
out.push(`## What to fix (${failed.length} level${failed.length > 1 ? "s" : ""})`);
|
|
143
|
+
out.push("Each fix below is text to add to the agent's system prompt (instructions file), in the bot's language. Apply it where the prompt is defined in the code, then re-run the audit.");
|
|
144
|
+
for (const c of failed) {
|
|
145
|
+
const level = String(c.id ?? "").replace(/^LVL\d+_/, "").toLowerCase();
|
|
146
|
+
const s = summaries.get(level) ?? [...summaries.values()].find((v) => String(c.id).toLowerCase().includes(String(v.level)));
|
|
147
|
+
out.push("");
|
|
148
|
+
out.push(`### ${c.label ?? c.id} — ${c.severity}${c.frameworks?.length ? ` (${c.frameworks.join(", ")})` : ""}`);
|
|
149
|
+
if (s?.verdict)
|
|
150
|
+
out.push(`What happened: ${s.verdict}`);
|
|
151
|
+
if (s?.patch)
|
|
152
|
+
out.push("Fix to paste into the system prompt:", "```", s.patch, "```");
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if (report.disclaimer)
|
|
156
|
+
out.push("", `_${report.disclaimer}_`);
|
|
157
|
+
return out.join("\n");
|
|
158
|
+
}
|
|
159
|
+
export async function getAuditReport(client, code) {
|
|
160
|
+
const { audit } = await client.audit(code);
|
|
161
|
+
return formatReport({ ...audit, audit_code: audit.audit_code ?? code });
|
|
162
|
+
}
|
|
163
|
+
export async function listAudits(client, limit = 10) {
|
|
164
|
+
const { audits = [] } = await client.listAudits(Math.min(Math.max(limit, 1), 50));
|
|
165
|
+
if (!audits.length)
|
|
166
|
+
return "No audits yet on this BotArmor account.";
|
|
167
|
+
return [
|
|
168
|
+
"| Audit | Agent | Status | Grade | Score | Started |",
|
|
169
|
+
"|---|---|---|---|---|---|",
|
|
170
|
+
...audits.map((a) => `| ${a.audit_code} | ${a.agent_name ?? "-"} | ${a.status}${a.retest_of ? ` (retest of ${a.retest_of})` : ""} | ${a.grade ?? "-"} | ${a.overall_score ?? "-"} | ${String(a.started_at ?? "").slice(0, 16).replace("T", " ")} |`),
|
|
171
|
+
].join("\n");
|
|
172
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,52 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botarmor/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"mcpName": "io.github.sidorenkav-collab/botarmor",
|
|
5
|
+
"description": "MCP server for BotArmor: crash-test your chatbot or AI agent from Claude Code, ChatGPT, Codex, Gemini CLI, Cursor or any MCP client, and get a report the model can turn into fixes.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"author": "BotArmor AI (Rhone IA)",
|
|
9
|
+
"homepage": "https://github.com/sidorenkav-collab/botarmor-mcp#readme",
|
|
10
|
+
"repository": {
|
|
11
|
+
"type": "git",
|
|
12
|
+
"url": "git+https://github.com/sidorenkav-collab/botarmor-mcp.git"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/sidorenkav-collab/botarmor-mcp/issues"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"mcp",
|
|
19
|
+
"model-context-protocol",
|
|
20
|
+
"claude-code",
|
|
21
|
+
"red-team",
|
|
22
|
+
"chatbot",
|
|
23
|
+
"ai-agent",
|
|
24
|
+
"security",
|
|
25
|
+
"botarmor"
|
|
26
|
+
],
|
|
27
|
+
"bin": {
|
|
28
|
+
"botarmor-mcp": "dist/index.js"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"dist/*.js",
|
|
32
|
+
"server.json",
|
|
33
|
+
"README.md",
|
|
34
|
+
"LICENSE"
|
|
35
|
+
],
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=20"
|
|
38
|
+
},
|
|
39
|
+
"scripts": {
|
|
40
|
+
"build": "tsc",
|
|
41
|
+
"test": "npm run build && node --test test/*.test.mjs",
|
|
42
|
+
"prepublishOnly": "npm test"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
46
|
+
"zod": "^4.0.0"
|
|
47
|
+
},
|
|
48
|
+
"devDependencies": {
|
|
49
|
+
"@types/node": "^24.0.0",
|
|
50
|
+
"typescript": "^5.9.3"
|
|
51
|
+
}
|
|
52
|
+
}
|
package/server.json
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sidorenkav-collab/botarmor",
|
|
4
|
+
"description": "Crash-test chatbots and AI agents: 12 attack levels, A-F grade, ready-to-paste prompt fixes.",
|
|
5
|
+
"repository": {
|
|
6
|
+
"url": "https://github.com/sidorenkav-collab/botarmor-mcp",
|
|
7
|
+
"source": "github"
|
|
8
|
+
},
|
|
9
|
+
"version": "0.1.1",
|
|
10
|
+
"websiteUrl": "https://botarmor.eu/agents/#mcp",
|
|
11
|
+
"packages": [
|
|
12
|
+
{
|
|
13
|
+
"registryType": "npm",
|
|
14
|
+
"identifier": "@botarmor/mcp",
|
|
15
|
+
"version": "0.1.1",
|
|
16
|
+
"transport": {
|
|
17
|
+
"type": "stdio"
|
|
18
|
+
},
|
|
19
|
+
"environmentVariables": [
|
|
20
|
+
{
|
|
21
|
+
"name": "BOTARMOR_API_KEY",
|
|
22
|
+
"description": "BotArmor API key (ba_live_...), from the client area, tab API",
|
|
23
|
+
"isRequired": true,
|
|
24
|
+
"format": "string",
|
|
25
|
+
"isSecret": true
|
|
26
|
+
}
|
|
27
|
+
]
|
|
28
|
+
}
|
|
29
|
+
],
|
|
30
|
+
"remotes": [
|
|
31
|
+
{
|
|
32
|
+
"type": "streamable-http",
|
|
33
|
+
"url": "https://app.botarmor.eu/mcp"
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
}
|