iso27001-mcp 0.8.1 → 0.8.3
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/README.md +346 -178
- package/dist/index.js +618 -78
- package/package.json +15 -5
package/README.md
CHANGED
|
@@ -1,157 +1,209 @@
|
|
|
1
1
|
# iso27001-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Turn Claude into an ISO 27001 compliance assistant** — controls, risk register, policies, evidence tracking, SoA generation, and full audit workflows in one local encrypted MCP server.
|
|
4
|
+
|
|
5
|
+
[](https://socket.dev/npm/package/iso27001-mcp/overview/0.8.3)
|
|
4
6
|
[](https://npmjs.com/package/iso27001-mcp)
|
|
5
|
-
[](https://npmjs.com/package/iso27001-mcp)
|
|
8
|
+
[](https://github.com/Sushegaad/MCP-Server-for-ISO27001/actions/workflows/ci.yml)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://www.iso.org/standard/27001)
|
|
6
11
|
|
|
7
12
|
**[▶ Live Interactive Demo](https://sushegaad.github.io/MCP-Server-for-ISO27001/)**
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
---
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
Claude ──MCP──► iso27001-mcp ──► encrypted SQLite (isms.db)
|
|
13
|
-
│
|
|
14
|
-
├── 93 ISO 27001:2022 controls (seeded)
|
|
15
|
-
├── 114 ISO 27001:2013 controls (seeded)
|
|
16
|
-
├── Gap assessments & remediation roadmaps
|
|
17
|
-
├── Risk register & treatment plans
|
|
18
|
-
├── Policy & procedure documents (Mustache templates)
|
|
19
|
-
├── Statement of Applicability
|
|
20
|
-
├── Audit findings & corrective actions
|
|
21
|
-
└── Evidence tracking (+ Jira / GitHub)
|
|
22
|
-
```
|
|
16
|
+
## Why this exists
|
|
23
17
|
|
|
24
|
-
|
|
18
|
+
ISO 27001 compliance work is typically scattered across spreadsheets, Word docs, ticketing systems, and shared drives. Security teams and consultants spend more time chasing evidence and reformatting documents than actually improving security posture.
|
|
25
19
|
|
|
26
|
-
|
|
20
|
+
**`iso27001-mcp` solves this by giving Claude a live, stateful ISMS** — all 93 ISO 27001:2022 controls seeded and ready, a real risk register, policy and procedure generators, evidence tracking, audit workflows, and a Statement of Applicability, backed by an encrypted local database that never leaves your machine.
|
|
27
21
|
|
|
28
|
-
|
|
29
|
-
- [Use Cases](#use-cases)
|
|
30
|
-
- [Installation](#installation)
|
|
31
|
-
- [Configuration](#configuration)
|
|
32
|
-
- [Connecting to Claude](#connecting-to-claude)
|
|
33
|
-
- [Tools Reference](#tools-reference)
|
|
34
|
-
- [Group 1 — Control Registry](#group-1--control-registry-minimum-role-viewer)
|
|
35
|
-
- [Group 2 — Gap Analysis](#group-2--gap-analysis-reads-viewer-writes-analyst)
|
|
36
|
-
- [Group 3 — Risk Management](#group-3--risk-management-reads-viewer-writes-analyst)
|
|
37
|
-
- [Group 4 — Policy Management](#group-4--policy-management-reads-viewer-create-analyst-update-admin)
|
|
38
|
-
- [Group 5 — Statement of Applicability](#group-5--statement-of-applicability-minimum-role-analyst)
|
|
39
|
-
- [Group 6 — Audit Management](#group-6--audit-management-reads-viewer-writes-admin)
|
|
40
|
-
- [Group 7 — Evidence Tracking](#group-7--evidence-tracking-reads-viewer-writes-analyst)
|
|
41
|
-
- [Group 8 — Server Info](#group-8--server-info-minimum-role-viewer)
|
|
42
|
-
- [Group 9 — Admin & Key Management](#group-9--admin--key-management-minimum-role-admin)
|
|
43
|
-
- [Group 10 — Organisation Profile](#group-10--organisation-profile-minimum-role-admin-for-writes-viewer-for-reads)
|
|
44
|
-
- [Group 11 — Procedure Management](#group-11--procedure-management-reads-viewer-createexport-analyst-update-admin)
|
|
45
|
-
- [Group 12 — Management Review](#group-12--management-review-reads-viewer-writes-admin--clause-93)
|
|
46
|
-
- [Group 13 — Improvement Plan](#group-13--improvement-plan-reads-viewer-writes-analyst--clause-101)
|
|
47
|
-
- [Group 14 — Evidence Templates](#group-14--evidence-templates-reads-viewer-generate-analyst)
|
|
48
|
-
- [MCP Resources](#mcp-resources)
|
|
49
|
-
- [Architecture](#architecture)
|
|
50
|
-
- [Modes](#modes)
|
|
51
|
-
- [Integrations](#integrations)
|
|
52
|
-
- [Development](#development)
|
|
53
|
-
- [Security](#security)
|
|
22
|
+
The difference from generating static documents: Claude can *query, reason, and update* across your entire ISMS in a single conversation. Ask it to run a gap assessment, identify which open risks are linked to unimplemented controls, generate the policies that close those gaps, and produce a remediation roadmap — all without switching tools.
|
|
54
23
|
|
|
55
|
-
|
|
24
|
+
**Who it's for:** Security teams · Compliance consultants · GRC engineers · Startups preparing for ISO 27001 · Internal audit functions
|
|
56
25
|
|
|
57
|
-
|
|
26
|
+
---
|
|
58
27
|
|
|
59
|
-
|
|
28
|
+
## What Claude can do with it
|
|
29
|
+
|
|
30
|
+
| Capability | Example prompt |
|
|
31
|
+
|------------|----------------|
|
|
32
|
+
| **Gap assessment** | *"Run an ISO 27001:2022 gap assessment for a 50-person SaaS company."* |
|
|
33
|
+
| **Risk register** | *"Create a risk register for a startup using AWS, GitHub, Slack, and Google Workspace."* |
|
|
34
|
+
| **Statement of Applicability** | *"Generate a Statement of Applicability for all 93 ISO 27001:2022 controls."* |
|
|
35
|
+
| **Policy generation** | *"Create an Access Control Policy mapped to ISO 27001 controls."* |
|
|
36
|
+
| **Procedure generation** | *"Generate an Incident Handling Procedure with GDPR breach notification triggers."* |
|
|
37
|
+
| **Internal audit** | *"Plan an internal audit for clause 9.1 — Performance Evaluation."* |
|
|
38
|
+
| **Corrective actions** | *"List open audit findings and suggest corrective actions."* |
|
|
39
|
+
| **Evidence tracking** | *"Show me all implemented controls with no current evidence."* |
|
|
40
|
+
| **Remediation roadmap** | *"Generate a 26-week remediation roadmap grouped by risk level."* |
|
|
41
|
+
| **Management review** | *"Prepare agenda items for our Clause 9.3 management review."* |
|
|
60
42
|
|
|
61
|
-
|
|
43
|
+
---
|
|
62
44
|
|
|
63
|
-
|
|
45
|
+
## Quick Start
|
|
64
46
|
|
|
65
|
-
|
|
66
|
-
node --version # should print v20.x.x or higher
|
|
67
|
-
```
|
|
47
|
+
### Prerequisites
|
|
68
48
|
|
|
69
|
-
- **
|
|
49
|
+
- **Node.js 20.11.0+** — [nodejs.org](https://nodejs.org) or [nvm](https://github.com/nvm-sh/nvm) / [Volta](https://volta.sh)
|
|
50
|
+
- **Build tools** (for the encrypted SQLite native module):
|
|
70
51
|
- **macOS:** `xcode-select --install`
|
|
71
52
|
- **Ubuntu/Debian:** `sudo apt-get install build-essential python3`
|
|
72
|
-
- **Windows:**
|
|
53
|
+
- **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) → "Desktop development with C++"
|
|
73
54
|
|
|
74
|
-
###
|
|
55
|
+
### Four commands to get running
|
|
75
56
|
|
|
76
57
|
```bash
|
|
77
|
-
npm install -g iso27001-mcp
|
|
58
|
+
npm install -g iso27001-mcp # 1. install globally
|
|
59
|
+
iso27001-mcp init # 2. interactive setup wizard
|
|
60
|
+
iso27001-mcp keygen --label "me" --role admin # 3. generate admin API key (if not already done by init)
|
|
61
|
+
iso27001-mcp doctor # 4. verify everything is working
|
|
78
62
|
```
|
|
79
63
|
|
|
80
|
-
|
|
64
|
+
After running `iso27001-mcp doctor` you should see:
|
|
81
65
|
|
|
82
|
-
|
|
66
|
+
```
|
|
67
|
+
iso27001-mcp — health check
|
|
68
|
+
────────────────────────────────────────────────────────
|
|
69
|
+
✅ DB_ENCRYPTION_KEY set (64 hex chars)
|
|
70
|
+
✅ HMAC_SECRET set (64 hex chars)
|
|
71
|
+
✅ MCP_API_KEY set (starts with iso27001_)
|
|
72
|
+
✅ Database file /Users/you/.iso27001/isms.db
|
|
73
|
+
✅ Database accessible opened and queried successfully
|
|
74
|
+
✅ Migrations 6/6 applied
|
|
75
|
+
✅ Controls seeded 93 ISO 27001:2022 controls
|
|
76
|
+
✅ Active API key 1 active key found
|
|
77
|
+
✅ Claude Desktop config /Users/you/.../claude_desktop_config.json
|
|
78
|
+
✅ iso27001-mcp entry present in mcpServers
|
|
79
|
+
────────────────────────────────────────────────────────
|
|
80
|
+
All 10 checks passed. Restart Claude Desktop if you just ran init.
|
|
81
|
+
```
|
|
83
82
|
|
|
84
|
-
|
|
83
|
+
Then **restart Claude Desktop** (quit fully and reopen). You should see 63 tools in the tools panel.
|
|
84
|
+
|
|
85
|
+
### Five prompts to try first
|
|
85
86
|
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
```
|
|
88
|
+
"Use get_server_info to verify the server is running."
|
|
89
|
+
"Run an ISO 27001 gap assessment for a 50-person SaaS company."
|
|
90
|
+
"Create a risk register for a startup using AWS, GitHub, Slack, and Google Workspace."
|
|
91
|
+
"Generate a Statement of Applicability for ISO 27001:2022."
|
|
92
|
+
"Create an Access Control Policy mapped to ISO 27001 controls."
|
|
89
93
|
```
|
|
90
94
|
|
|
91
|
-
|
|
95
|
+
---
|
|
92
96
|
|
|
93
|
-
|
|
97
|
+
## Tool Categories
|
|
98
|
+
|
|
99
|
+
63 tools across 14 groups. All require an API key; minimum role is shown.
|
|
100
|
+
|
|
101
|
+
| Group | Tools | Min. role | What it does |
|
|
102
|
+
|-------|-------|-----------|--------------|
|
|
103
|
+
| **Control Registry** | 7 | viewer | Search, filter, and compare ISO 27001:2022 and 2013 controls; browse clause requirements |
|
|
104
|
+
| **Gap Analysis** | 7 | viewer / analyst | Create and track gap assessments; export gap reports; generate remediation roadmaps |
|
|
105
|
+
| **Risk Management** | 8 | viewer / analyst | Risk register with likelihood × impact scoring, treatment plans, and heat-map summaries |
|
|
106
|
+
| **Policy Management** | 4 | viewer / analyst / admin | Generate, version, and export policies from 12 Mustache templates |
|
|
107
|
+
| **Statement of Applicability** | 3 | analyst | Build and export SoA from a gap assessment; all 93 controls with applicability decisions |
|
|
108
|
+
| **Audit Management** | 5 | viewer / admin | Plan audits, record findings (NCs, OFIs), raise CARs, and close with effectiveness check |
|
|
109
|
+
| **Evidence Tracking** | 5 | viewer / analyst | Register evidence artefacts, spot gaps, link to Jira / GitHub issues |
|
|
110
|
+
| **Server Info** | 1 | viewer | Server version, tool count, capability summary |
|
|
111
|
+
| **Admin & Key Management** | 6 | admin | Generate / revoke API keys, query the HMAC audit log |
|
|
112
|
+
| **Organisation Profile** | 2 | admin (write) / viewer (read) | Set org name, scope, and defaults used by all templates |
|
|
113
|
+
| **Procedure Management** | 5 | viewer / analyst / admin | Generate, version, and export procedures from 12 Mustache templates |
|
|
114
|
+
| **Management Review** | 6 | viewer / admin | Full Clause 9.3 lifecycle — inputs, outputs, completion (enforces all 7 required input categories) |
|
|
115
|
+
| **Improvement Plan** | 4 | viewer / analyst | Clause 10.1 improvement opportunities — track, link, and report |
|
|
116
|
+
| **Evidence Templates** | 3 | viewer / analyst | Generate Mustache-rendered evidence documents; dual-write to evidence and generated_evidence tables |
|
|
94
117
|
|
|
95
|
-
|
|
118
|
+
---
|
|
96
119
|
|
|
97
|
-
|
|
98
|
-
export HMAC_SECRET=<your_hmac_secret>
|
|
99
|
-
export DB_ENCRYPTION_KEY=<your_db_key>
|
|
100
|
-
export DB_PATH=$HOME/.iso27001/isms.db
|
|
120
|
+
## Templates
|
|
101
121
|
|
|
102
|
-
|
|
103
|
-
```
|
|
122
|
+
The server ships 30 Mustache templates that Claude renders on demand with your organisation's name, scope, and control references automatically injected.
|
|
104
123
|
|
|
105
|
-
|
|
124
|
+
### ISO 27001 Policy Templates
|
|
106
125
|
|
|
107
|
-
|
|
126
|
+
Generate any of these with a single Claude prompt:
|
|
108
127
|
|
|
109
|
-
|
|
128
|
+
`information_security` · `access_control` · `risk_management` · `asset_management` · `incident_response` · `business_continuity` · `supplier_security` · `cryptography` · `physical_security` · `acceptable_use` · `data_classification` · `secure_development`
|
|
110
129
|
|
|
111
|
-
|
|
130
|
+
### ISO 27001 Procedure Templates
|
|
112
131
|
|
|
113
|
-
|
|
114
|
-
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
132
|
+
`incident_handling` · `access_provisioning` · `asset_onboarding_offboarding` · `audit_log_review` · `backup_restore` · `bcp_testing` · `change_management` · `cryptographic_key_management` · `data_classification_handling` · `secure_development_workflow` · `supplier_onboarding` · `vulnerability_management`
|
|
115
133
|
|
|
116
|
-
|
|
134
|
+
### Evidence Document Templates
|
|
117
135
|
|
|
118
|
-
|
|
119
|
-
{
|
|
120
|
-
"mcpServers": {
|
|
121
|
-
"iso27001": {
|
|
122
|
-
"command": "iso27001-mcp",
|
|
123
|
-
"env": {
|
|
124
|
-
"HMAC_SECRET": "your_hmac_secret",
|
|
125
|
-
"DB_ENCRYPTION_KEY": "your_db_encryption_key",
|
|
126
|
-
"MCP_API_KEY": "iso27001_your_api_key_here",
|
|
127
|
-
"DB_PATH": "/Users/you/.iso27001/isms.db"
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
}
|
|
132
|
-
```
|
|
136
|
+
Pre-structured evidence documents for auditor submissions: `risk_assessment` · `internal_audit` · `management_review` · `access_review` · `incident_review` · `bcp_test`
|
|
133
137
|
|
|
134
|
-
|
|
138
|
+
### Sample Outputs
|
|
135
139
|
|
|
136
|
-
|
|
140
|
+
The [`samples/`](samples/) directory contains auditor-ready example outputs for a fictitious organisation ("Acme Financial Services Ltd") — a full gap assessment, remediation roadmap, risk register CSV, SoA CSV, access control policy, incident handling procedure, internal audit report, corrective action records, and evidence package. See [Sample Outputs](#sample-outputs) for the full index.
|
|
137
141
|
|
|
138
|
-
|
|
142
|
+
> **ISO 27001 keywords:** ISO 27001 Statement of Applicability generator · ISO 27001 risk register template · ISO 27001 gap assessment tool · ISO 27001 audit evidence tracker · ISO 27001 MCP server · Claude ISO 27001 compliance assistant · AI GRC tool open source
|
|
139
143
|
|
|
140
|
-
|
|
144
|
+
---
|
|
141
145
|
|
|
142
|
-
|
|
146
|
+
## Security Model
|
|
143
147
|
|
|
144
|
-
###
|
|
148
|
+
### Role-Based Access Control (RBAC)
|
|
145
149
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
150
|
+
Three roles with strict hierarchy. A key can only call tools at or below its assigned role level.
|
|
151
|
+
|
|
152
|
+
| Capability | Viewer | Analyst | Admin |
|
|
153
|
+
|------------|--------|---------|-------|
|
|
154
|
+
| Read controls, clauses, version mappings | ✅ | ✅ | ✅ |
|
|
155
|
+
| Read gap assessments, risks, policies, audits, evidence | ✅ | ✅ | ✅ |
|
|
156
|
+
| Create / update gap assessments and control statuses | — | ✅ | ✅ |
|
|
157
|
+
| Create and manage risks and treatment plans | — | ✅ | ✅ |
|
|
158
|
+
| Generate policies and procedures | — | ✅ | ✅ |
|
|
159
|
+
| Create and export Statements of Applicability | — | ✅ | ✅ |
|
|
160
|
+
| Track and link evidence artefacts | — | ✅ | ✅ |
|
|
161
|
+
| Record and track improvement opportunities | — | ✅ | ✅ |
|
|
162
|
+
| Plan and close internal audits; raise CARs | — | — | ✅ |
|
|
163
|
+
| Set organisation profile | — | — | ✅ |
|
|
164
|
+
| Run management reviews (Clause 9.3) | — | — | ✅ |
|
|
165
|
+
| View and query the audit log | — | — | ✅ |
|
|
166
|
+
| Generate and revoke API keys | — | — | ✅ |
|
|
167
|
+
|
|
168
|
+
**Tool counts:** Viewer — 31 tools · Analyst — 49 tools · Admin — 63 tools
|
|
169
|
+
|
|
170
|
+
### What never leaves your machine
|
|
171
|
+
|
|
172
|
+
In `local` mode (stdio, the default), no data leaves the machine. The encrypted SQLite database, the `.env` secrets file, and the append-only audit log are all stored locally. There is no telemetry, no cloud sync, and no outbound network calls — unless you explicitly configure the optional Jira or GitHub integrations.
|
|
173
|
+
|
|
174
|
+
For the full security profile — threat model, hardening guide, supply chain attestation, and audit log integrity verification — see the **[Trust Center](https://github.com/Sushegaad/MCP-Server-for-ISO27001/tree/main/docs/security/)**.
|
|
175
|
+
|
|
176
|
+
### Encryption and audit trail summary
|
|
177
|
+
|
|
178
|
+
- **Database** — AES-256 encrypted SQLite via `better-sqlite3-multiple-ciphers`
|
|
179
|
+
- **API keys** — HMAC-SHA256 hashed; raw key printed once and never stored
|
|
180
|
+
- **Audit log** — HMAC-SHA256 hash chain; every row linked to its predecessor — insertion, deletion, or reordering is detectable
|
|
181
|
+
- **Prompt injection** — free-text fields sanitised before passing to any handler
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Table of Contents
|
|
186
|
+
|
|
187
|
+
- [Why this exists](#why-this-exists)
|
|
188
|
+
- [What Claude can do with it](#what-claude-can-do-with-it)
|
|
189
|
+
- [Quick Start](#quick-start)
|
|
190
|
+
- [Tool Categories](#tool-categories)
|
|
191
|
+
- [Templates](#templates)
|
|
192
|
+
- [Security Model](#security-model)
|
|
193
|
+
- [Use Cases](#use-cases)
|
|
194
|
+
- [Installation](#installation)
|
|
195
|
+
- [Connecting to Claude](#connecting-to-claude)
|
|
196
|
+
- [Advanced / Manual Setup](#advanced--manual-setup)
|
|
197
|
+
- [Tools Reference](#tools-reference)
|
|
198
|
+
- [MCP Resources](#mcp-resources)
|
|
199
|
+
- [Architecture](#architecture)
|
|
200
|
+
- [Modes](#modes)
|
|
201
|
+
- [Sample Outputs](#sample-outputs)
|
|
202
|
+
- [Integrations](#integrations)
|
|
203
|
+
- [Roadmap](#roadmap)
|
|
204
|
+
- [Development](#development)
|
|
205
|
+
- [Contributing](#contributing)
|
|
206
|
+
- [Security](#security)
|
|
155
207
|
|
|
156
208
|
---
|
|
157
209
|
|
|
@@ -268,83 +320,41 @@ npm install -g iso27001-mcp
|
|
|
268
320
|
|
|
269
321
|
The `iso27001-mcp` command is now available globally. The encrypted SQLite module (`better-sqlite3-multiple-ciphers`) downloads a prebuilt binary on supported platforms; it compiles from source if none is available.
|
|
270
322
|
|
|
271
|
-
|
|
323
|
+
### Step 2 — Run the setup wizard
|
|
272
324
|
|
|
273
325
|
```bash
|
|
274
|
-
|
|
275
|
-
cd iso27001-mcp
|
|
276
|
-
npm install
|
|
277
|
-
npm run build
|
|
278
|
-
# Use `node dist/index.js` instead of `iso27001-mcp` in all commands below
|
|
326
|
+
iso27001-mcp init
|
|
279
327
|
```
|
|
280
328
|
|
|
281
|
-
|
|
329
|
+
The wizard handles everything in one guided session — no `openssl` required:
|
|
282
330
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
331
|
+
- Generates `DB_ENCRYPTION_KEY` and `HMAC_SECRET` (AES-256 / HMAC-SHA256, 64 hex chars each)
|
|
332
|
+
- Writes a `~/.iso27001/.env` file with mode `600`
|
|
333
|
+
- Creates and seeds the encrypted SQLite database with all 93 ISO 27001:2022 controls
|
|
334
|
+
- Generates an admin API key
|
|
335
|
+
- Detects your Claude Desktop config and offers to add the `iso27001-mcp` entry automatically
|
|
286
336
|
|
|
287
|
-
|
|
337
|
+
### Step 3 — Verify
|
|
288
338
|
|
|
289
339
|
```bash
|
|
290
|
-
|
|
291
|
-
openssl rand -hex 32 # → paste into HMAC_SECRET
|
|
292
|
-
|
|
293
|
-
# Generate a 32-byte AES-256 database encryption key
|
|
294
|
-
openssl rand -hex 32 # → paste into DB_ENCRYPTION_KEY
|
|
340
|
+
iso27001-mcp doctor
|
|
295
341
|
```
|
|
296
342
|
|
|
297
|
-
|
|
343
|
+
Runs 10 health checks and prints `✅ / ❌ / --` for each. All green means Claude Desktop is ready.
|
|
298
344
|
|
|
299
|
-
|
|
300
|
-
|----------|----------|---------|-------------|
|
|
301
|
-
| `HMAC_SECRET` | ✅ | — | 32-byte hex secret for HMAC-signing API keys |
|
|
302
|
-
| `DB_ENCRYPTION_KEY` | ✅ | — | 32-byte hex key for AES-256 SQLite encryption |
|
|
303
|
-
| `DB_PATH` | | `./isms.db` | Path to the encrypted database file |
|
|
304
|
-
| `AUDIT_LOG_PATH` | | `./audit.jsonl` | Path for the append-only JSON-L audit log (`.jsonl` or `.log` only) |
|
|
305
|
-
| `RATE_LIMIT_RPM` | | `500` | Tool calls per minute per API key |
|
|
306
|
-
| `SESSION_TTL_HOURS` | | `4` | SSE session TTL (hosted/team modes) |
|
|
307
|
-
| `SSE_PORT` | | `3000` | Port for the SSE server (hosted/team modes) |
|
|
308
|
-
| `BEHIND_TLS_PROXY` | | `false` | Set `true` when behind nginx/Caddy in production |
|
|
309
|
-
| `JIRA_BASE_URL` | | — | e.g. `https://your-org.atlassian.net` |
|
|
310
|
-
| `JIRA_API_TOKEN` | | — | Jira API token for the integration |
|
|
311
|
-
| `JIRA_PROJECT_KEY` | | — | e.g. `SEC` |
|
|
312
|
-
| `JIRA_USER_EMAIL` | | — | Email address associated with the Jira API token |
|
|
313
|
-
| `GITHUB_TOKEN` | | — | GitHub personal access token (scope: `issues:write`) |
|
|
314
|
-
| `GITHUB_REPO` | | — | e.g. `your-org/your-repo` |
|
|
315
|
-
|
|
316
|
-
### Step 3 — Generate an API Key
|
|
345
|
+
### Step 4 — Restart Claude Desktop
|
|
317
346
|
|
|
318
|
-
|
|
347
|
+
Quit the app fully and reopen it. The ISO 27001 tools will appear in the tools panel.
|
|
319
348
|
|
|
320
|
-
|
|
321
|
-
# Viewer — read-only access to 25 tools
|
|
322
|
-
iso27001-mcp keygen --label "Alice" --role viewer
|
|
323
|
-
|
|
324
|
-
# Analyst — read + write for gap/risk/policy/procedure/evidence tools (49 tools)
|
|
325
|
-
iso27001-mcp keygen --label "Bob" --role analyst --expires 90d
|
|
326
|
-
|
|
327
|
-
# Admin — all 63 tools including audit log and key management
|
|
328
|
-
iso27001-mcp keygen --label "CISO" --role admin --expires 1y
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
The raw key is printed **once** and never stored in plaintext. Save it immediately.
|
|
332
|
-
|
|
333
|
-
```bash
|
|
334
|
-
# List all keys
|
|
335
|
-
iso27001-mcp keys list
|
|
336
|
-
|
|
337
|
-
# Revoke a key immediately
|
|
338
|
-
iso27001-mcp keys revoke --label "Alice"
|
|
339
|
-
```
|
|
349
|
+
> **Tip:** Ask Claude `"Use get_server_info to verify the server is running"` to confirm the connection.
|
|
340
350
|
|
|
341
351
|
---
|
|
342
352
|
|
|
343
353
|
## Connecting to Claude
|
|
344
354
|
|
|
345
|
-
### Claude Desktop
|
|
355
|
+
### Claude Desktop (automatic via `init`)
|
|
346
356
|
|
|
347
|
-
|
|
357
|
+
`iso27001-mcp init` writes the following entry into `claude_desktop_config.json` automatically. You can also add or update it manually:
|
|
348
358
|
|
|
349
359
|
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
350
360
|
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
@@ -352,39 +362,114 @@ Add the server to your Claude Desktop MCP configuration file:
|
|
|
352
362
|
```json
|
|
353
363
|
{
|
|
354
364
|
"mcpServers": {
|
|
355
|
-
"iso27001": {
|
|
365
|
+
"iso27001-mcp": {
|
|
356
366
|
"command": "iso27001-mcp",
|
|
357
367
|
"env": {
|
|
358
|
-
"
|
|
359
|
-
"
|
|
360
|
-
"MCP_API_KEY": "
|
|
361
|
-
"DB_PATH": "/Users/you/.iso27001/isms.db"
|
|
368
|
+
"DB_ENCRYPTION_KEY": "<generated by init>",
|
|
369
|
+
"HMAC_SECRET": "<generated by init>",
|
|
370
|
+
"MCP_API_KEY": "<generated by init>",
|
|
371
|
+
"DB_PATH": "/Users/you/.iso27001/isms.db",
|
|
372
|
+
"AUDIT_LOG_PATH": "/Users/you/.iso27001/audit.jsonl"
|
|
362
373
|
}
|
|
363
374
|
}
|
|
364
375
|
}
|
|
365
376
|
}
|
|
366
377
|
```
|
|
367
378
|
|
|
368
|
-
Restart Claude Desktop. The ISO 27001 tools will appear in the tools panel.
|
|
369
|
-
|
|
370
|
-
> **Tip:** Store your `isms.db` in a stable location like `~/.iso27001/isms.db` so it persists across upgrades.
|
|
371
|
-
|
|
372
379
|
### Claude Code
|
|
373
380
|
|
|
374
381
|
```bash
|
|
375
382
|
# Add to your project's MCP config
|
|
376
|
-
claude mcp add iso27001 iso27001-mcp
|
|
383
|
+
claude mcp add iso27001-mcp iso27001-mcp
|
|
377
384
|
```
|
|
378
385
|
|
|
379
386
|
Then set the required env vars in your shell or `.env`:
|
|
380
387
|
|
|
381
388
|
```bash
|
|
382
|
-
export HMAC_SECRET=your_hmac_secret
|
|
383
389
|
export DB_ENCRYPTION_KEY=your_db_encryption_key
|
|
390
|
+
export HMAC_SECRET=your_hmac_secret
|
|
384
391
|
export MCP_API_KEY=iso27001_your_key_here
|
|
385
392
|
export DB_PATH=$HOME/.iso27001/isms.db
|
|
386
393
|
```
|
|
387
394
|
|
|
395
|
+
### Managing API Keys
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
# Generate additional keys for team members
|
|
399
|
+
iso27001-mcp keygen --label "Alice" --role viewer # read-only, 31 tools
|
|
400
|
+
iso27001-mcp keygen --label "Bob" --role analyst --expires 90d # 49 tools
|
|
401
|
+
iso27001-mcp keygen --label "CISO" --role admin --expires 1y # all 63 tools
|
|
402
|
+
|
|
403
|
+
# List all keys
|
|
404
|
+
iso27001-mcp keys list
|
|
405
|
+
|
|
406
|
+
# Revoke a key immediately
|
|
407
|
+
iso27001-mcp keys revoke --label "Alice"
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
The raw key is printed **once** and never stored in plaintext. Save it immediately.
|
|
411
|
+
|
|
412
|
+
---
|
|
413
|
+
|
|
414
|
+
## Advanced / Manual Setup
|
|
415
|
+
|
|
416
|
+
> Use this path if you need a custom database location, CI/CD integration, or prefer to manage secrets without the wizard.
|
|
417
|
+
|
|
418
|
+
**1. Generate secrets:**
|
|
419
|
+
|
|
420
|
+
```bash
|
|
421
|
+
openssl rand -hex 32 # → DB_ENCRYPTION_KEY
|
|
422
|
+
openssl rand -hex 32 # → HMAC_SECRET
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
**2. Create `.env`** (store outside your project root, never commit):
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
DB_ENCRYPTION_KEY=<64 hex chars>
|
|
429
|
+
HMAC_SECRET=<64 hex chars>
|
|
430
|
+
DB_PATH=/path/to/isms.db
|
|
431
|
+
AUDIT_LOG_PATH=/path/to/audit.jsonl
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
**3. Generate an admin API key:**
|
|
435
|
+
|
|
436
|
+
```bash
|
|
437
|
+
source /path/to/.env # or export vars individually
|
|
438
|
+
iso27001-mcp keygen --label admin --role admin
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
**4. Add the `iso27001-mcp` entry** to `claude_desktop_config.json` manually (see JSON block above), then restart Claude Desktop.
|
|
442
|
+
|
|
443
|
+
**Full environment variable reference:**
|
|
444
|
+
|
|
445
|
+
| Variable | Required | Default | Description |
|
|
446
|
+
|----------|----------|---------|-------------|
|
|
447
|
+
| `DB_ENCRYPTION_KEY` | ✅ | — | 32-byte hex key for AES-256 SQLite encryption |
|
|
448
|
+
| `HMAC_SECRET` | ✅ | — | 32-byte hex secret for HMAC-signing API keys |
|
|
449
|
+
| `DB_PATH` | | `./isms.db` | Path to the encrypted database file |
|
|
450
|
+
| `AUDIT_LOG_PATH` | | `./audit.jsonl` | Path for the append-only JSON-L audit log (`.jsonl` or `.log` only) |
|
|
451
|
+
| `RATE_LIMIT_RPM` | | `500` | Tool calls per minute per API key |
|
|
452
|
+
| `SESSION_TTL_HOURS` | | `4` | SSE session TTL (hosted/team modes) |
|
|
453
|
+
| `SSE_PORT` | | `3000` | Port for the SSE server (hosted/team modes) |
|
|
454
|
+
| `BEHIND_TLS_PROXY` | | `false` | Set `true` when behind nginx/Caddy in production |
|
|
455
|
+
| `CORS_ORIGIN` | | `http://localhost` (dev) / `https://claude.ai` (prod) | Allowed CORS origin for the SSE server — never set to `*` |
|
|
456
|
+
| `JIRA_BASE_URL` | | — | e.g. `https://your-org.atlassian.net` |
|
|
457
|
+
| `JIRA_API_TOKEN` | | — | Jira API token for the integration |
|
|
458
|
+
| `JIRA_PROJECT_KEY` | | — | e.g. `SEC` |
|
|
459
|
+
| `JIRA_USER_EMAIL` | | — | Email address associated with the Jira API token |
|
|
460
|
+
| `GITHUB_TOKEN` | | — | GitHub personal access token (scope: `issues:write`) |
|
|
461
|
+
| `GITHUB_REPO` | | — | e.g. `your-org/your-repo` |
|
|
462
|
+
|
|
463
|
+
**Run from source** (for development or to get the latest unreleased changes):
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
git clone https://github.com/Sushegaad/MCP-Server-for-ISO27001
|
|
467
|
+
cd MCP-server-for-ISO27001
|
|
468
|
+
npm install
|
|
469
|
+
npm run build
|
|
470
|
+
# Use `node dist/index.js` instead of `iso27001-mcp` in all commands below
|
|
471
|
+
```
|
|
472
|
+
|
|
388
473
|
---
|
|
389
474
|
|
|
390
475
|
## Tools Reference
|
|
@@ -1248,6 +1333,24 @@ Sessions expire after `SESSION_TTL_HOURS` hours of inactivity. In `NODE_ENV=prod
|
|
|
1248
1333
|
|
|
1249
1334
|
---
|
|
1250
1335
|
|
|
1336
|
+
## Sample Outputs
|
|
1337
|
+
|
|
1338
|
+
The [`samples/`](samples/) directory contains auditor-ready example outputs generated from a demo ISMS for a fictitious organisation ("Acme Financial Services Ltd" — a UK payments processor preparing for ISO 27001:2022 certification). Each file states which tool(s) produced it.
|
|
1339
|
+
|
|
1340
|
+
| Sample | Description |
|
|
1341
|
+
|--------|-------------|
|
|
1342
|
+
| [gap-assessment-summary.md](samples/gap-assessment-summary.md) | Complete gap assessment across all 93 controls |
|
|
1343
|
+
| [remediation-roadmap.md](samples/remediation-roadmap.md) | 26-week prioritised remediation plan with owners and effort estimates |
|
|
1344
|
+
| [risk-register.csv](samples/risk-register.csv) | Risk register with 10 risks, scores, and treatment plans |
|
|
1345
|
+
| [statement-of-applicability.csv](samples/statement-of-applicability.csv) | Full SoA — all 93 ISO 27001:2022 controls with applicability justifications |
|
|
1346
|
+
| [access-control-policy.md](samples/access-control-policy.md) | Generated access control policy (Annex A 5.15–5.18, 8.2–8.5) |
|
|
1347
|
+
| [incident-handling-procedure.md](samples/incident-handling-procedure.md) | Incident handling procedure with severity tiers and GDPR notification |
|
|
1348
|
+
| [internal-audit-report.md](samples/internal-audit-report.md) | Internal audit report — 3 major NCs, 4 minor NCs, 2 positive observations |
|
|
1349
|
+
| [corrective-action-record.md](samples/corrective-action-record.md) | Two corrective action records: one in progress, one closed and verified |
|
|
1350
|
+
| [evidence-package.md](samples/evidence-package.md) | 47-item evidence inventory with 28-control gap analysis |
|
|
1351
|
+
|
|
1352
|
+
---
|
|
1353
|
+
|
|
1251
1354
|
## Integrations
|
|
1252
1355
|
|
|
1253
1356
|
### Jira
|
|
@@ -1272,6 +1375,32 @@ Use `link_github_issue` to create an issue with `compliance` and `iso27001` labe
|
|
|
1272
1375
|
|
|
1273
1376
|
---
|
|
1274
1377
|
|
|
1378
|
+
## Roadmap
|
|
1379
|
+
|
|
1380
|
+
The following features are planned or under consideration. Contributions welcome — see [Contributing](#contributing).
|
|
1381
|
+
|
|
1382
|
+
### Near-term (next 1–2 releases)
|
|
1383
|
+
|
|
1384
|
+
- **ISO 27001:2022 ↔ SOC 2 control mapping** — show which ISO 27001 controls satisfy which SOC 2 Trust Services Criteria
|
|
1385
|
+
- **Evidence expiry alerts** — surface evidence artefacts approaching their `expiry_date` in gap summaries and audit reports
|
|
1386
|
+
- **Bulk control status import** — accept a CSV to batch-update control statuses in a gap assessment
|
|
1387
|
+
- **HTML export** — add `html` as an export format for gap reports, SoA, and the risk register
|
|
1388
|
+
|
|
1389
|
+
### Medium-term
|
|
1390
|
+
|
|
1391
|
+
- **ISO 27001:2022 ↔ NIST CSF 2.0 mapping** — cross-reference controls to NIST Cybersecurity Framework 2.0 functions and categories
|
|
1392
|
+
- **PostgreSQL backend** — optional PostgreSQL transport via a pluggable DB adapter (SQLite stays default for local use)
|
|
1393
|
+
- **Supplier risk register** — track third-party suppliers against ISO 27001 Annex A 5.19–5.22 controls
|
|
1394
|
+
- **Multi-ISMS support** — scope-isolated tenants sharing a single server instance (hosted mode)
|
|
1395
|
+
|
|
1396
|
+
### Under consideration
|
|
1397
|
+
|
|
1398
|
+
- GDPR Article 30 RoPA generation linked to the risk register
|
|
1399
|
+
- NIS2 control mapping
|
|
1400
|
+
- Automated evidence collection via API integrations (AWS Config, GitHub Security Advisories, etc.)
|
|
1401
|
+
|
|
1402
|
+
---
|
|
1403
|
+
|
|
1275
1404
|
## Development
|
|
1276
1405
|
|
|
1277
1406
|
```bash
|
|
@@ -1304,8 +1433,13 @@ npm run dev
|
|
|
1304
1433
|
|
|
1305
1434
|
```
|
|
1306
1435
|
src/
|
|
1307
|
-
├── index.ts CLI entry (keygen, keys, server startup)
|
|
1436
|
+
├── index.ts CLI entry (init, doctor, keygen, keys, server startup)
|
|
1308
1437
|
├── server.ts McpServer factory — registers tools + resources
|
|
1438
|
+
├── cli/
|
|
1439
|
+
│ ├── init.ts Interactive setup wizard (iso27001-mcp init)
|
|
1440
|
+
│ ├── doctor.ts 10-check health report (iso27001-mcp doctor)
|
|
1441
|
+
│ ├── prompt.ts Lazy readline wrapper — ask, confirm, banner, check
|
|
1442
|
+
│ └── claude-config.ts Claude Desktop config detection + entry builder
|
|
1309
1443
|
├── auth/
|
|
1310
1444
|
│ ├── api-key.ts Key generation, HMAC validation, expiry, revocation
|
|
1311
1445
|
│ ├── rbac.ts Permission matrix (63 tools × 3 roles)
|
|
@@ -1320,7 +1454,7 @@ src/
|
|
|
1320
1454
|
├── db/
|
|
1321
1455
|
│ ├── connection.ts Encrypted SQLite open/close/migrate
|
|
1322
1456
|
│ ├── dal.ts Shared helpers: newId, now, toJson, fromJsonArray, computeEvidenceStatus
|
|
1323
|
-
│ └── migrations/ 0001_initial.sql
|
|
1457
|
+
│ └── migrations/ 0001_initial.sql through 0006_audit_log_hmac.sql
|
|
1324
1458
|
├── seed/
|
|
1325
1459
|
│ ├── seeder.ts Idempotent seed runner with checksum verification
|
|
1326
1460
|
│ ├── controls-2022.json 93 ISO 27001:2022 Annex A controls
|
|
@@ -1377,8 +1511,42 @@ tests/
|
|
|
1377
1511
|
|
|
1378
1512
|
---
|
|
1379
1513
|
|
|
1514
|
+
## Contributing
|
|
1515
|
+
|
|
1516
|
+
Contributions are welcome — bug fixes, new policy/procedure templates, additional integrations, and documentation improvements are all valuable.
|
|
1517
|
+
|
|
1518
|
+
**Getting started:**
|
|
1519
|
+
|
|
1520
|
+
```bash
|
|
1521
|
+
git clone https://github.com/Sushegaad/MCP-Server-for-ISO27001
|
|
1522
|
+
cd MCP-server-for-ISO27001
|
|
1523
|
+
npm install
|
|
1524
|
+
npm test # should pass before any changes
|
|
1525
|
+
npm run typecheck # zero errors required
|
|
1526
|
+
```
|
|
1527
|
+
|
|
1528
|
+
**Before opening a PR:**
|
|
1529
|
+
|
|
1530
|
+
- Run `npm run typecheck` — zero TypeScript errors required
|
|
1531
|
+
- Run `npm test` — all tests must pass
|
|
1532
|
+
- Run `npm run lint` — no new lint errors
|
|
1533
|
+
- If adding seed data, run `npm run generate-checksums` and commit the updated checksums file
|
|
1534
|
+
|
|
1535
|
+
**Areas where help is most needed:**
|
|
1536
|
+
|
|
1537
|
+
- Additional policy and procedure templates (currently 12 + 12; ISO 27001 has room for more)
|
|
1538
|
+
- More evidence document templates
|
|
1539
|
+
- ISO 27001 ↔ other framework mappings (SOC 2, NIST CSF, CIS Controls)
|
|
1540
|
+
- Windows and Linux testing (most development is on macOS)
|
|
1541
|
+
|
|
1542
|
+
Please open an issue before starting significant work so we can align on direction.
|
|
1543
|
+
|
|
1544
|
+
---
|
|
1545
|
+
|
|
1380
1546
|
## Security
|
|
1381
1547
|
|
|
1548
|
+
For the full security profile — threat model, hardening guide, data flow documentation, supply chain attestation, and audit log integrity verification — see the **[Trust Center](https://github.com/Sushegaad/MCP-Server-for-ISO27001/tree/main/docs/security/)**.
|
|
1549
|
+
|
|
1382
1550
|
### API Key Storage
|
|
1383
1551
|
|
|
1384
1552
|
API keys are never stored in plaintext. Only an HMAC-SHA256 hash is persisted in the database. The raw `iso27001_...` key is printed once to stdout at generation time — there is no way to retrieve it afterwards.
|