mcp-sentinel 0.1.0 → 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.
Files changed (2) hide show
  1. package/README.md +90 -157
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <p align="center">
2
2
  <h1 align="center">MCP Sentinel</h1>
3
3
  <p align="center">
4
- <strong>Audit and enforce security policies on MCP servers before you trust them.</strong>
4
+ <strong>Know what your MCP servers can do — before your AI agent does.</strong>
5
5
  </p>
6
6
  <p align="center">
7
7
  <a href="https://www.npmjs.com/package/mcp-sentinel"><img src="https://img.shields.io/npm/v/mcp-sentinel.svg" alt="npm version"></a>
@@ -12,15 +12,22 @@
12
12
 
13
13
  ---
14
14
 
15
- MCP servers run third-party code with access to your files, credentials, and shell. MCP Sentinel connects to any server, shows you exactly what it exposes, and **enforces security policies** — blocking dangerous tools before your agent can call them.
15
+ ## The Problem
16
+
17
+ You add an MCP server to Claude Desktop, Cursor, or your agent framework. Now that server has tools your AI can call — tools that might read your files, run shell commands, or delete data.
18
+
19
+ **You're trusting code you haven't reviewed.**
20
+
21
+ MCP Sentinel connects to any MCP server, shows you every tool it exposes, and lets you define security policies that block dangerous ones automatically.
22
+
23
+ ## Quick Start
16
24
 
17
25
  ```bash
18
- npx mcp-sentinel --policy .mcp-policy.yml npx @modelcontextprotocol/server-filesystem /tmp
26
+ # Scan any MCP server — no install needed
27
+ npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp
19
28
  ```
20
29
 
21
- ## Real Output
22
-
23
- Scanned against the official [MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem):
30
+ That's it. You'll see every tool the server exposes, categorized by risk:
24
31
 
25
32
  ```
26
33
  🔍 MCP Sentinel v0.1.0
@@ -28,46 +35,40 @@ Scanned against the official [MCP filesystem server](https://www.npmjs.com/packa
28
35
  📦 Server: secure-filesystem-server v0.2.0
29
36
  Capabilities: tools
30
37
 
31
- 🔧 Tools (14) 11 read • 3 write • 0 admin
38
+ 🔧 Tools (14) 11 read · 3 write · 0 admin
32
39
 
33
- ✅ read_file Read the complete contents of a file as text... (3 params)
34
- * string path
35
- number tail
36
- number head
37
- ✅ read_text_file Read the complete contents of a file from... (3 params)
38
- ✅ read_media_file Read an image or audio file... (1 params)
40
+ ✅ read_file Read the complete contents of a file... (3 params)
39
41
  ✅ read_multiple_files Read multiple files simultaneously... (1 params)
40
- ✏️ write_file Create a new file or overwrite an existing... [write] (2 params)
41
- * string path
42
- * string content
43
- ✅ edit_file Make line-based edits to a text file... (3 params)
44
- ✏️ create_directory Create a new directory... [write] (1 params)
45
- ✅ list_directory Get a detailed listing of all files... (1 params)
46
- ✏️ move_file Move or rename files and directories... [write] (2 params)
47
- ✅ search_files Recursively search for files... (3 params)
48
- ✅ get_file_info Retrieve detailed metadata... (1 params)
49
- ✅ list_allowed_directories Returns the list of allowed directories
50
-
51
- 🛡️ Aguara Security Analysis
52
-
53
- 0 finding(s)
42
+ ✏️ write_file Create a new file or overwrite... [write] (2 params)
43
+ ✏️ create_directory Create a new directory... [write] (1 params)
44
+ ✏️ move_file Move or rename files... [write] (2 params)
45
+ ✅ list_directory Get a detailed listing of all files... (1 params)
46
+ ✅ search_files Recursively search for files... (3 params)
47
+ ...
54
48
 
55
49
  Scanned in 1706ms
56
50
  ```
57
51
 
58
- ### With Policy Enforcement
52
+ ## Add a Security Policy
59
53
 
60
- Using this policy:
54
+ Create a `.mcp-policy.yml` in your project root:
61
55
 
62
56
  ```yaml
63
- # .mcp-policy.yml
64
57
  deny:
65
- categories: [admin]
66
- tools: ["write_*", "move_*"]
58
+ categories: [admin] # Block dangerous tools (delete, exec, shell)
59
+ tools: ["write_*", "move_*"] # Block by name pattern
60
+
67
61
  require:
68
- maxTools: 10
62
+ maxTools: 10 # Limit attack surface
63
+
69
64
  allow:
70
- tools: ["write_file"] # Allow write_file despite deny pattern
65
+ tools: ["write_file"] # Exceptions to deny rules
66
+ ```
67
+
68
+ Then enforce it:
69
+
70
+ ```bash
71
+ npx mcp-sentinel --policy .mcp-policy.yml npx @modelcontextprotocol/server-filesystem /tmp
71
72
  ```
72
73
 
73
74
  ```
@@ -79,68 +80,25 @@ allow:
79
80
  ✖ [require.maxTools] Server exposes 14 tools, policy allows max 10
80
81
  ```
81
82
 
82
- **Exit code 2** — `write_file` was allowed by the exception, but `move_file` and the tool count violated the policy. Your CI pipeline stops here.
83
-
84
- ## Why MCP Sentinel
85
-
86
- Every MCP client already shows you the tool list. MCP Sentinel goes further:
83
+ Exit code `2` = violations found. Your CI pipeline stops here.
87
84
 
88
- | Feature | MCP Client | MCP Sentinel |
89
- |---------|-----------|---------------|
90
- | See tool list | Yes | Yes |
91
- | **Security policy enforcement** | No | **Yes** |
92
- | **CI/CD pipeline gate** | No | **Yes** |
93
- | **Drift detection** between versions | No | **Yes** |
94
- | **Fleet scan** all configured servers | No | **Yes** |
95
- | Deep security analysis (aguara) | No | **Yes** |
96
- | Exportable reports (JSON/Markdown) | No | **Yes** |
85
+ > `write_file` was allowed by the exception, but `move_file` and the tool count violated the policy.
97
86
 
98
- ## Policy Enforcement
87
+ ## Use It in CI/CD
99
88
 
100
- Define what's allowed in `.mcp-policy.yml`:
89
+ Add one line to your GitHub Actions workflow:
101
90
 
102
91
  ```yaml
103
- deny:
104
- categories:
105
- - admin # No admin tools (delete, exec, shell)
106
- tools:
107
- - "execute_*" # Block all execution patterns
108
- - "push_*" # Block push operations
109
-
110
- require:
111
- aguara: clean # Zero security findings required
112
- maxTools: 20 # Limit attack surface
113
-
114
- allow:
115
- tools:
116
- - "execute_query" # Allow specific tools even if pattern-denied
92
+ - run: npx mcp-sentinel --policy .mcp-policy.yml npx ./your-mcp-server
117
93
  ```
118
94
 
119
- ### Policy Rules
120
-
121
- | Rule | Description |
122
- |------|-------------|
123
- | `deny.categories` | Block tools by category: `read`, `write`, `admin` |
124
- | `deny.tools` | Block tools by name or glob pattern (`delete_*`, `exec*`) |
125
- | `require.aguara` | Require aguara scan with zero findings (`clean`) |
126
- | `require.maxTools` | Maximum number of tools a server can expose |
127
- | `allow.tools` | Exception list — allow specific tools even if they match deny rules |
128
-
129
- ### Example Policies
95
+ If the server violates your policy, the build fails. See a [full workflow example](examples/github-action.yml).
130
96
 
131
- Ready-to-use policies in [`examples/policies/`](examples/policies/):
132
-
133
- | Policy | Use case |
134
- |--------|----------|
135
- | [`strict.yml`](examples/policies/strict.yml) | Production — blocks admin + write, requires aguara clean |
136
- | [`standard.yml`](examples/policies/standard.yml) | Development — blocks admin + exec patterns, allows writes |
137
- | [`permissive.yml`](examples/policies/permissive.yml) | Local dev — only blocks destructive patterns (delete, drop, destroy) |
138
- | [`ci-pipeline.yml`](examples/policies/ci-pipeline.yml) | CI/CD — blocks admin + deploy + push, requires aguara clean |
139
-
140
- ### CI/CD Integration
97
+ <details>
98
+ <summary>Full GitHub Actions example</summary>
141
99
 
142
100
  ```yaml
143
- # .github/workflows/mcp-sentinel.yml
101
+ # .github/workflows/mcp-audit.yml
144
102
  name: MCP Security Audit
145
103
  on: [pull_request]
146
104
 
@@ -152,86 +110,76 @@ jobs:
152
110
  - uses: actions/setup-node@v4
153
111
  with: { node-version: 20 }
154
112
  - run: npx mcp-sentinel --policy .mcp-policy.yml npx ./your-mcp-server
155
- # Exit code 2 = policy violations → build fails
156
- ```
157
-
158
- See full example in [`examples/github-action.yml`](examples/github-action.yml).
159
-
160
- ## Install & Use
161
-
162
- ```bash
163
- # No install needed
164
- npx mcp-sentinel <command> [args...]
165
113
  ```
166
114
 
167
- ### Quick Start
168
-
169
- ```bash
170
- # 1. Scan a server
171
- npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp
172
-
173
- # 2. Create a policy
174
- cat > .mcp-policy.yml << 'EOF'
175
- deny:
176
- categories: [admin]
177
- tools: ["execute_*", "delete_*"]
178
- require:
179
- aguara: clean
180
- maxTools: 20
181
- EOF
182
-
183
- # 3. Enforce it
184
- npx mcp-sentinel --policy .mcp-policy.yml npx @modelcontextprotocol/server-filesystem /tmp
185
- ```
115
+ </details>
186
116
 
187
- ### More Examples
117
+ ## What Else Can It Do?
188
118
 
189
119
  ```bash
190
- # Scan remote servers via HTTP
120
+ # Scan a remote server over HTTP
191
121
  npx mcp-sentinel http://localhost:3000/mcp
192
122
 
193
- # Scan all servers from your config (Claude Desktop, Cursor, Windsurf)
123
+ # Scan all servers from Claude Desktop, Cursor, or Windsurf config
194
124
  npx mcp-sentinel --config
195
125
 
196
- # Diff mode: detect changes between server versions
126
+ # Detect changes between server versions
197
127
  npx mcp-sentinel npx @mcp/server --json > baseline.json
198
128
  npx mcp-sentinel npx @mcp/server --diff baseline.json
199
129
 
200
- # Scan multiple servers at once
130
+ # Scan multiple servers in one command
201
131
  npx mcp-sentinel npx @mcp/server-a --- npx @mcp/server-b
202
132
 
203
- # JSON output for scripting
133
+ # Export as JSON or Markdown
204
134
  npx mcp-sentinel --json npx @mcp/server
205
-
206
- # Markdown report
207
135
  npx mcp-sentinel --markdown report.md npx @mcp/server
208
136
  ```
209
137
 
210
- ### With Aguara (recommended)
138
+ ## Policy Reference
211
139
 
212
- Install [Aguara](https://github.com/garagon/aguara) for deep security analysis (prompt injection, exfiltration, supply chain, credential leaks):
140
+ | Rule | What it does | Example |
141
+ |------|-------------|---------|
142
+ | `deny.categories` | Block tools by category | `[admin]`, `[admin, write]` |
143
+ | `deny.tools` | Block by name or glob | `["delete_*", "run_command"]` |
144
+ | `require.maxTools` | Max number of tools allowed | `20` |
145
+ | `require.aguara` | Require zero security findings | `clean` |
146
+ | `allow.tools` | Exceptions to deny rules | `["execute_query"]` |
147
+
148
+ ### Starter Policies
149
+
150
+ Pick one from [`examples/policies/`](examples/policies/) and customize:
151
+
152
+ | Policy | Best for |
153
+ |--------|----------|
154
+ | [`permissive.yml`](examples/policies/permissive.yml) | Local development — blocks only destructive patterns |
155
+ | [`standard.yml`](examples/policies/standard.yml) | Team development — blocks admin + exec, allows writes |
156
+ | [`strict.yml`](examples/policies/strict.yml) | Production — blocks admin + write, requires security scan |
157
+ | [`ci-pipeline.yml`](examples/policies/ci-pipeline.yml) | CI/CD — blocks admin + deploy + push |
158
+
159
+ ## Deep Security Analysis with Aguara
160
+
161
+ MCP Sentinel can optionally integrate with [Aguara](https://github.com/garagon/aguara), a security scanner with 177 rules that detects prompt injection, data exfiltration, credential leaks, and more.
213
162
 
214
163
  ```bash
164
+ # Install Aguara (optional)
215
165
  curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash
216
166
  ```
217
167
 
218
- MCP Sentinel auto-detects Aguara and runs its 177-rule engine against tool descriptions. Combine with `require.aguara: clean` in your policy to enforce zero findings.
168
+ Once installed, MCP Sentinel auto-detects it and runs the analysis. Add `require.aguara: clean` to your policy to enforce zero findings.
219
169
 
220
- ## Options
170
+ ## All Options
221
171
 
222
172
  | Flag | Description |
223
173
  |------|-------------|
224
- | `--policy <file>` | Enforce security policy (auto-detects `.mcp-policy.yml`) |
225
- | `--config` | Auto-detect and scan servers from config files |
226
- | `--diff <file.json>` | Compare against a previous JSON scan |
174
+ | `--policy <file>` | Enforce a security policy (auto-detects `.mcp-policy.yml`) |
175
+ | `--config` | Scan servers from Claude Desktop / Cursor / Windsurf config |
176
+ | `--diff <file.json>` | Compare against a previous scan |
227
177
  | `--transport <type>` | Force transport: `stdio`, `sse`, `streamable-http` |
228
- | `--json` | Structured JSON output |
229
- | `--markdown <file>` | Export report as Markdown |
178
+ | `--json` | JSON output |
179
+ | `--markdown <file>` | Export Markdown report |
230
180
  | `--fail-on-findings` | Exit code 2 if aguara finds issues |
231
- | `--no-color` | Disable colored output |
181
+ | `--no-color` | Disable colors |
232
182
  | `--timeout <ms>` | Connection timeout (default: 30000) |
233
- | `-h, --help` | Show help |
234
- | `-v, --version` | Show version |
235
183
 
236
184
  ## How It Works
237
185
 
@@ -241,13 +189,13 @@ MCP Sentinel auto-detects Aguara and runs its 177-rule engine against tool descr
241
189
  ┌──────── │ (local) │
242
190
  │ └────────────────┘
243
191
  ┌───────────┤
244
- │ mcp- │ HTTP/ ┌────────────────┐
245
- │ inspector │ SSE │ MCP Server │
192
+ │ mcp- │ HTTP/ ┌────────────────┐
193
+ │ sentinel │ SSE │ MCP Server │
246
194
  │ ├──────── │ (remote) │
247
- │ Scan │ └────────────────┘
248
- │ Enforce │
249
- │ Diff │ ┌──────────────────┐
250
- │ Report │ ──────► │ Aguara (177 │
195
+ │ Scan │ └────────────────┘
196
+ │ Enforce │
197
+ │ Diff │ ┌──────────────────┐
198
+ │ Report │ ──────► │ Aguara (177 │
251
199
  └───────────┘ │ security rules) │
252
200
  │ └──────────────────┘
253
201
  ▼
@@ -266,24 +214,9 @@ MCP Sentinel is part of the [Aguara](https://github.com/garagon/aguara) security
266
214
  | **MCP Sentinel** | Policy enforcement — audit, enforce, and monitor MCP servers |
267
215
  | **[Aguara Watch](https://aguarascan.com)** | Cloud platform — continuous monitoring of MCP registries |
268
216
 
269
- ## Roadmap
270
-
271
- - [x] Runtime introspection (tools, resources, prompts, capabilities)
272
- - [x] **Policy enforcement engine**
273
- - [x] Aguara integration
274
- - [x] HTTP/SSE transport support
275
- - [x] Diff mode
276
- - [x] Config auto-detection (Claude Desktop, Cursor, Windsurf)
277
- - [ ] Per-server policy overrides
278
- - [ ] Registry integration (Smithery, mcp.run)
279
- - [ ] GitHub Action (reusable workflow)
280
- - [ ] VS Code extension
281
-
282
217
  ## Contributing
283
218
 
284
- Contributions welcome. Please open an issue first to discuss what you'd like to change.
285
-
286
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development standards.
219
+ Contributions welcome. Please open an issue first to discuss what you'd like to change. See [CONTRIBUTING.md](CONTRIBUTING.md).
287
220
 
288
221
  ## License
289
222
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-sentinel",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Audit and enforce security policies on MCP servers — policy engine, drift detection, CI/CD gate",
5
5
  "author": "Gustavo Aragon (@oktsec)",
6
6
  "license": "MIT",