agent-mcp-guard 0.1.0
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 +177 -0
- package/README.md +119 -0
- package/bin/mcp-guard.js +15 -0
- package/docs/launch-checklist.md +34 -0
- package/docs/operator-runbook.md +102 -0
- package/docs/paid-audit.md +29 -0
- package/docs/privacy-and-security.md +28 -0
- package/docs/rules.md +35 -0
- package/docs/templates/audit-report-template.md +56 -0
- package/examples/safe-claude_desktop_config.json +11 -0
- package/examples/sample-report.md +47 -0
- package/examples/unsafe-claude_desktop_config.json +28 -0
- package/package.json +39 -0
- package/src/cli.js +156 -0
- package/src/config.js +60 -0
- package/src/discovery.js +39 -0
- package/src/redact.js +28 -0
- package/src/report.js +136 -0
- package/src/rules.js +270 -0
- package/src/scan.js +107 -0
- package/src/severity.js +24 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or Derivative
|
|
95
|
+
Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work, excluding
|
|
103
|
+
those notices that do not pertain to any part of the Derivative
|
|
104
|
+
Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
package/README.md
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# mcp-guard
|
|
2
|
+
|
|
3
|
+
Open-source CLI scanner for risky MCP server and AI agent tool configuration.
|
|
4
|
+
|
|
5
|
+
`mcp-guard` helps developers review MCP configs before giving AI agents access to files, shells, credentials, SaaS tools, or production systems.
|
|
6
|
+
|
|
7
|
+
## What It Detects
|
|
8
|
+
|
|
9
|
+
- Shell wrappers and inline scripts.
|
|
10
|
+
- `node -e`, `python -c`, and other interpreter eval modes.
|
|
11
|
+
- Remote package runners such as `npx`, `uvx`, `bunx`, and `pnpm dlx`.
|
|
12
|
+
- Unpinned MCP server package versions.
|
|
13
|
+
- Secret-like environment variables and headers.
|
|
14
|
+
- Broad filesystem access such as `/`, home, Desktop, Documents, or Downloads.
|
|
15
|
+
- Remote MCP server URLs.
|
|
16
|
+
- Dangerous command patterns such as `rm -rf`, `sudo`, `chmod 777`, and curl pipe to shell.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
For local development from this repo:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install -g .
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
After npm publication:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g agent-mcp-guard
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Usage
|
|
33
|
+
|
|
34
|
+
Scan common Claude Desktop, Cursor, and project MCP config locations:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
mcp-guard scan
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Scan a specific config:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
mcp-guard scan --config .mcp.json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Generate a Markdown report:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
mcp-guard scan --format markdown --output mcp-guard-report.md
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Use in CI and fail when high-risk findings are present:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
mcp-guard scan --config .mcp.json --fail-on high
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Supported Config Shape
|
|
59
|
+
|
|
60
|
+
`mcp-guard` supports the common MCP config shape used by Claude Desktop, Cursor, and many project configs:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"server-name": {
|
|
66
|
+
"command": "npx",
|
|
67
|
+
"args": ["@modelcontextprotocol/server-filesystem", "/path/to/project"],
|
|
68
|
+
"env": {
|
|
69
|
+
"API_KEY": "..."
|
|
70
|
+
},
|
|
71
|
+
"cwd": "/path/to/project"
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
It also accepts `servers` as an alternative top-level key.
|
|
78
|
+
|
|
79
|
+
## Example
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npm run scan:example
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
This scans `examples/unsafe-claude_desktop_config.json` and writes `examples/sample-report.md`.
|
|
86
|
+
|
|
87
|
+
## Exit Codes
|
|
88
|
+
|
|
89
|
+
- `0`: scan completed and did not hit the fail threshold.
|
|
90
|
+
- `1`: CLI usage or runtime error.
|
|
91
|
+
- `2`: finding severity met `--fail-on` threshold.
|
|
92
|
+
|
|
93
|
+
## Privacy
|
|
94
|
+
|
|
95
|
+
`mcp-guard` is local-first:
|
|
96
|
+
|
|
97
|
+
- It does not upload configs.
|
|
98
|
+
- It does not call external APIs.
|
|
99
|
+
- It redacts secret-like values in reports by default.
|
|
100
|
+
|
|
101
|
+
MCP configs and reports can still contain sensitive paths, hostnames, and configuration details. Review before sharing.
|
|
102
|
+
|
|
103
|
+
## Documentation
|
|
104
|
+
|
|
105
|
+
- [Rule reference](docs/rules.md)
|
|
106
|
+
- [Privacy and security](docs/privacy-and-security.md)
|
|
107
|
+
- [Paid audit service](docs/paid-audit.md)
|
|
108
|
+
- [Launch checklist](docs/launch-checklist.md)
|
|
109
|
+
- [Operator runbook](docs/operator-runbook.md)
|
|
110
|
+
|
|
111
|
+
## Commercial Support
|
|
112
|
+
|
|
113
|
+
Need a private AI Agent/MCP security audit?
|
|
114
|
+
|
|
115
|
+
The first paid service is a focused review of your MCP and agent tool setup: inventory, risk report, remediation checklist, and a hardening call. See [docs/paid-audit.md](docs/paid-audit.md).
|
|
116
|
+
|
|
117
|
+
## License
|
|
118
|
+
|
|
119
|
+
Apache-2.0
|
package/bin/mcp-guard.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { runCli } from "../src/cli.js";
|
|
4
|
+
|
|
5
|
+
runCli(process.argv, {
|
|
6
|
+
cwd: process.cwd(),
|
|
7
|
+
env: process.env,
|
|
8
|
+
stdout: process.stdout,
|
|
9
|
+
stderr: process.stderr
|
|
10
|
+
}).catch((error) => {
|
|
11
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
12
|
+
process.stderr.write(`mcp-guard: ${message}\n`);
|
|
13
|
+
process.exitCode = 1;
|
|
14
|
+
});
|
|
15
|
+
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Launch Checklist
|
|
2
|
+
|
|
3
|
+
## Before Public Launch
|
|
4
|
+
|
|
5
|
+
- [ ] Create GitHub repository.
|
|
6
|
+
- [ ] Push the local project.
|
|
7
|
+
- [ ] Confirm CI passes.
|
|
8
|
+
- [ ] Choose final package name on npm.
|
|
9
|
+
- [ ] Run `npm pack --dry-run`.
|
|
10
|
+
- [ ] Publish with `npm publish --access public`.
|
|
11
|
+
- [ ] Generate fresh sample report with `npm run scan:example`.
|
|
12
|
+
- [ ] Add screenshots or paste report excerpt into README.
|
|
13
|
+
- [ ] Post a short technical article or launch note.
|
|
14
|
+
- [ ] Contact 20 early users for free scans or paid hardening.
|
|
15
|
+
- [ ] Follow the detailed steps in `docs/operator-runbook.md`.
|
|
16
|
+
|
|
17
|
+
## User Setup
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g agent-mcp-guard
|
|
21
|
+
mcp-guard scan
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## CI Setup
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
mcp-guard scan --config .mcp.json --fail-on high
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Exit codes:
|
|
31
|
+
|
|
32
|
+
- `0`: scan completed and did not hit the fail threshold.
|
|
33
|
+
- `1`: CLI usage or runtime error.
|
|
34
|
+
- `2`: finding severity met `--fail-on` threshold.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Operator Runbook
|
|
2
|
+
|
|
3
|
+
This is the step-by-step launch path for the project owner.
|
|
4
|
+
|
|
5
|
+
## 1. Local Verification
|
|
6
|
+
|
|
7
|
+
From the repo root:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm test
|
|
11
|
+
npm run release:check
|
|
12
|
+
npm --cache ./.npm-cache pack --dry-run
|
|
13
|
+
node ./bin/mcp-guard.js scan --config examples/unsafe-claude_desktop_config.json
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
If your global npm cache has permission errors, either keep using the local cache flag above or fix ownership:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
sudo chown -R "$(id -u)":"$(id -g)" ~/.npm
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## 2. Create GitHub Repository
|
|
23
|
+
|
|
24
|
+
Create an empty public GitHub repo named:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
mcp-guard
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Do not initialize it with a README, license, or `.gitignore`; this local project already has them.
|
|
31
|
+
|
|
32
|
+
Then run:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
git init -b main
|
|
36
|
+
git add .
|
|
37
|
+
git commit -m "Initial mcp-guard CLI"
|
|
38
|
+
git remote add origin git@github.com:<your-username>/mcp-guard.git
|
|
39
|
+
git push -u origin main
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Or use the helper after `gh auth login`:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm run launch:github
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 3. Publish To npm
|
|
49
|
+
|
|
50
|
+
The product and CLI command are `mcp-guard`, but the npm package name is:
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
agent-mcp-guard
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`mcp-guard` is already taken on npm, so do not publish under that name.
|
|
57
|
+
|
|
58
|
+
Confirm the package name is still available:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm view agent-mcp-guard
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
If it is available, login and publish:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm login
|
|
68
|
+
npm publish --access public
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
If npm cache permission errors appear, use:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npm --cache ./.npm-cache publish --access public
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or use the helper after `npm login`:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
npm run publish:npm
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## 4. First Public Post
|
|
84
|
+
|
|
85
|
+
Short launch copy:
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
I just open-sourced mcp-guard, a local-first CLI that scans MCP server configs for risky AI agent permissions: shell wrappers, unpinned npx packages, broad filesystem access, exposed secrets, and remote MCP servers.
|
|
89
|
+
|
|
90
|
+
npm install -g agent-mcp-guard
|
|
91
|
+
mcp-guard scan
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## 5. First Sales Motion
|
|
95
|
+
|
|
96
|
+
Send this to 20 teams using MCP or AI agents:
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
I am building mcp-guard, an open-source security scanner for MCP and AI agent tool configs. It checks for risky shell access, unpinned remote packages, over-broad file permissions, exposed secrets, and unsafe remote server setup.
|
|
100
|
+
|
|
101
|
+
I am doing a few early scans for teams using MCP in real workflows. If you send a redacted config or run the CLI locally, I can help interpret the report and suggest hardening steps.
|
|
102
|
+
```
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# AI Agent/MCP Security Audit
|
|
2
|
+
|
|
3
|
+
This is the first paid service attached to `mcp-guard`.
|
|
4
|
+
|
|
5
|
+
## Who It Is For
|
|
6
|
+
|
|
7
|
+
- Teams using Claude Desktop, Cursor, Codex, Windsurf, or custom AI agents.
|
|
8
|
+
- Teams installing MCP servers from public registries.
|
|
9
|
+
- Startups connecting agents to GitHub, Slack, databases, browsers, files, or production tools.
|
|
10
|
+
|
|
11
|
+
## Deliverables
|
|
12
|
+
|
|
13
|
+
- MCP and agent tool inventory.
|
|
14
|
+
- Risk report covering shell access, package execution, filesystem scope, secrets, remote servers, and dangerous commands.
|
|
15
|
+
- Practical remediation checklist.
|
|
16
|
+
- Optional PR with safer config and policy changes.
|
|
17
|
+
- 60-minute hardening call.
|
|
18
|
+
|
|
19
|
+
Use `docs/templates/audit-report-template.md` as the starting point for client delivery.
|
|
20
|
+
|
|
21
|
+
## Suggested Pricing
|
|
22
|
+
|
|
23
|
+
- Indie or solo founder: USD 300-800.
|
|
24
|
+
- Small startup: USD 1,000-3,000.
|
|
25
|
+
- Funded team or private deployment pilot: USD 3,000-8,000.
|
|
26
|
+
|
|
27
|
+
## Sales Copy
|
|
28
|
+
|
|
29
|
+
I am building `mcp-guard`, an open-source scanner for MCP and AI agent tool security. It checks for risky shell access, unpinned remote packages, over-broad file permissions, exposed secrets, and unsafe remote server setup. I am offering a few early MCP security audits for teams using agents in real workflows.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Privacy And Security
|
|
2
|
+
|
|
3
|
+
## Default Behavior
|
|
4
|
+
|
|
5
|
+
`mcp-guard` is local-first.
|
|
6
|
+
|
|
7
|
+
- It reads MCP config files from disk.
|
|
8
|
+
- It does not upload config files.
|
|
9
|
+
- It does not call external APIs.
|
|
10
|
+
- It redacts secret-like environment values and headers in reports.
|
|
11
|
+
|
|
12
|
+
## Sensitive Data
|
|
13
|
+
|
|
14
|
+
MCP configs may contain tokens, API keys, local paths, usernames, and internal hostnames. Treat generated reports as sensitive unless you have reviewed them.
|
|
15
|
+
|
|
16
|
+
## Recommended Use
|
|
17
|
+
|
|
18
|
+
- Run locally before sharing a report.
|
|
19
|
+
- Remove unnecessary MCP servers.
|
|
20
|
+
- Use dedicated service accounts and scoped tokens.
|
|
21
|
+
- Prefer pinned package versions.
|
|
22
|
+
- Avoid broad filesystem paths such as home, root, Desktop, Documents, or Downloads.
|
|
23
|
+
- Avoid shell wrappers and inline scripts for MCP server startup.
|
|
24
|
+
|
|
25
|
+
## Disclaimer
|
|
26
|
+
|
|
27
|
+
This project is an assistive security review tool. It does not guarantee that all vulnerabilities, malicious packages, data leaks, or unsafe configurations will be found.
|
|
28
|
+
|
package/docs/rules.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Rule Reference
|
|
2
|
+
|
|
3
|
+
`mcp-guard` uses practical heuristics for the first public version. It is designed to surface risky MCP configuration quickly, not to prove a system is fully secure.
|
|
4
|
+
|
|
5
|
+
| Rule | Severity | What it detects |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| MCP000 | Low | No MCP config files found in common locations. |
|
|
8
|
+
| MCP001 | High | Server has neither `command` nor `url`. |
|
|
9
|
+
| MCP002 | Medium | Config file has no `mcpServers` or `servers` object. |
|
|
10
|
+
| MCP003 | High | Config file cannot be parsed as JSON. |
|
|
11
|
+
| MCP010 | High/Critical | MCP server runs through a shell, especially with inline `-c`. |
|
|
12
|
+
| MCP011 | High | Interpreter eval mode such as `node -e` or `python -c`. |
|
|
13
|
+
| MCP020 | Medium | Remote package runner such as `npx`, `uvx`, `bunx`, or `pnpm dlx`. |
|
|
14
|
+
| MCP021 | High | Remote package runner without exact package version pinning. |
|
|
15
|
+
| MCP030 | High | Secret-like environment variable exposed to the MCP server. |
|
|
16
|
+
| MCP040 | Medium/High | Broad working directory such as home, root, Desktop, Documents, or Downloads. |
|
|
17
|
+
| MCP041 | Medium/High | Broad filesystem path passed in server arguments. |
|
|
18
|
+
| MCP050 | Critical | Dangerous command pattern such as `rm -rf`, `sudo`, `chmod 777`, or curl pipe to shell. |
|
|
19
|
+
| MCP060 | Medium | Remote MCP server URL configured. |
|
|
20
|
+
| MCP061 | High | Secret-like header configured for a remote MCP server. |
|
|
21
|
+
|
|
22
|
+
## Severity Model
|
|
23
|
+
|
|
24
|
+
- Critical: likely direct execution or credential safety risk.
|
|
25
|
+
- High: strong signal requiring review before use.
|
|
26
|
+
- Medium: risky default or missing governance.
|
|
27
|
+
- Low: informational issue.
|
|
28
|
+
|
|
29
|
+
## Limitations
|
|
30
|
+
|
|
31
|
+
- The scanner does not execute MCP servers.
|
|
32
|
+
- The scanner does not upload configs.
|
|
33
|
+
- Detection is heuristic and will miss some risks.
|
|
34
|
+
- A clean report is not a security guarantee.
|
|
35
|
+
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# AI Agent/MCP Security Audit Report
|
|
2
|
+
|
|
3
|
+
Client: TBD
|
|
4
|
+
Date: TBD
|
|
5
|
+
Prepared by: TBD
|
|
6
|
+
|
|
7
|
+
## Executive Summary
|
|
8
|
+
|
|
9
|
+
TBD
|
|
10
|
+
|
|
11
|
+
## Scope
|
|
12
|
+
|
|
13
|
+
- MCP config files reviewed:
|
|
14
|
+
- Agent tools reviewed:
|
|
15
|
+
- Repositories or workspaces reviewed:
|
|
16
|
+
- Out-of-scope systems:
|
|
17
|
+
|
|
18
|
+
## Risk Summary
|
|
19
|
+
|
|
20
|
+
| Severity | Count |
|
|
21
|
+
| --- | ---: |
|
|
22
|
+
| Critical | TBD |
|
|
23
|
+
| High | TBD |
|
|
24
|
+
| Medium | TBD |
|
|
25
|
+
| Low | TBD |
|
|
26
|
+
|
|
27
|
+
## Key Findings
|
|
28
|
+
|
|
29
|
+
| Severity | Area | Finding | Recommended Action |
|
|
30
|
+
| --- | --- | --- | --- |
|
|
31
|
+
| TBD | TBD | TBD | TBD |
|
|
32
|
+
|
|
33
|
+
## MCP Server Inventory
|
|
34
|
+
|
|
35
|
+
| Server | Command/URL | Filesystem Scope | Credentials | Notes |
|
|
36
|
+
| --- | --- | --- | --- | --- |
|
|
37
|
+
| TBD | TBD | TBD | TBD | TBD |
|
|
38
|
+
|
|
39
|
+
## Immediate Remediation
|
|
40
|
+
|
|
41
|
+
1. TBD
|
|
42
|
+
2. TBD
|
|
43
|
+
3. TBD
|
|
44
|
+
|
|
45
|
+
## Hardening Plan
|
|
46
|
+
|
|
47
|
+
| Priority | Action | Owner | Target Date |
|
|
48
|
+
| --- | --- | --- | --- |
|
|
49
|
+
| P0 | TBD | TBD | TBD |
|
|
50
|
+
| P1 | TBD | TBD | TBD |
|
|
51
|
+
| P2 | TBD | TBD | TBD |
|
|
52
|
+
|
|
53
|
+
## Notes And Limitations
|
|
54
|
+
|
|
55
|
+
This audit is based on the provided configuration and evidence. It is not a guarantee that all vulnerabilities or unsafe agent behaviors were found.
|
|
56
|
+
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# mcp-guard Scan Report
|
|
2
|
+
|
|
3
|
+
Generated: 2026-05-10T06:56:59.977Z
|
|
4
|
+
|
|
5
|
+
## Summary
|
|
6
|
+
|
|
7
|
+
- Scanned files: 1
|
|
8
|
+
- MCP servers: 3
|
|
9
|
+
- Findings: 9
|
|
10
|
+
- Risk score: 98
|
|
11
|
+
- Critical: 2
|
|
12
|
+
- High: 5
|
|
13
|
+
- Medium: 2
|
|
14
|
+
- Low: 0
|
|
15
|
+
|
|
16
|
+
## Scanned Files
|
|
17
|
+
|
|
18
|
+
- `examples/unsafe-claude_desktop_config.json`
|
|
19
|
+
|
|
20
|
+
## MCP Server Inventory
|
|
21
|
+
|
|
22
|
+
| Server | Command | Args | CWD | URL | Env |
|
|
23
|
+
| --- | --- | --- | --- | --- | --- |
|
|
24
|
+
| filesystem-all-home | npx | @modelcontextprotocol/server-filesystem / | / | - | GITHUB_TOKEN=ghp...890 (32 chars) |
|
|
25
|
+
| shell-installer | bash | -c curl https://example.com/install.sh \| bash | - | - | - |
|
|
26
|
+
| remote-prod | - | - | - | https://mcp.example.com/sse | - |
|
|
27
|
+
|
|
28
|
+
## Findings
|
|
29
|
+
|
|
30
|
+
| Severity | Rule | Server | Finding | Evidence | Recommendation |
|
|
31
|
+
| --- | --- | --- | --- | --- | --- |
|
|
32
|
+
| critical | MCP010 | shell-installer | Shell command executes inline script | command=bash args=-c curl https://example.com/install.sh \| bash | Use a direct, pinned executable instead of a shell wrapper. If a shell is required, place the script in source control and review it. |
|
|
33
|
+
| critical | MCP050 | shell-installer | MCP server command includes a dangerous operation | curl pipe to shell | Remove the dangerous operation from MCP startup. Run destructive setup steps manually and review them separately. |
|
|
34
|
+
| high | MCP021 | filesystem-all-home | Remote MCP package is not version pinned | package=@modelcontextprotocol/server-filesystem | Pin the package to an exact version such as package@1.2.3 and review updates before changing it. |
|
|
35
|
+
| high | MCP030 | filesystem-all-home | Secret-like environment variable is exposed to MCP server | GITHUB_TOKEN=ghp...890 (32 chars) | Pass the least privileged token possible. Prefer scoped tokens, short-lived credentials, and a dedicated service account. |
|
|
36
|
+
| high | MCP040 | filesystem-all-home | MCP server has a broad working directory | cwd=/ | Run the server in a narrow project directory or sandbox with only the files it needs. |
|
|
37
|
+
| high | MCP041 | filesystem-all-home | MCP server argument grants broad filesystem access | arg=/ | Replace broad filesystem paths with a dedicated project folder or read-only sandbox path. |
|
|
38
|
+
| high | MCP061 | remote-prod | Secret-like header is configured for remote MCP server | Authorization=Bea...ken (27 chars) | Use scoped, short-lived credentials and avoid placing long-lived secrets directly in MCP config files. |
|
|
39
|
+
| medium | MCP020 | filesystem-all-home | MCP server is launched through a remote package runner | command=npx package=@modelcontextprotocol/server-filesystem | Pin the package version, review the package source, and prefer a local lockfile or vendored executable for sensitive tools. |
|
|
40
|
+
| medium | MCP060 | remote-prod | Remote MCP server URL is configured | url=https://mcp.example.com/sse | Verify the provider, use HTTPS, document the data sent to this server, and keep an allowlist of approved remote endpoints. |
|
|
41
|
+
|
|
42
|
+
## Notes
|
|
43
|
+
|
|
44
|
+
- This report is an assistive security review, not a guarantee that all issues were found.
|
|
45
|
+
- Secret-like values are redacted by default.
|
|
46
|
+
- Review each MCP server before granting access to files, shells, SaaS accounts, or production systems.
|
|
47
|
+
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"filesystem-all-home": {
|
|
4
|
+
"command": "npx",
|
|
5
|
+
"args": [
|
|
6
|
+
"@modelcontextprotocol/server-filesystem",
|
|
7
|
+
"/"
|
|
8
|
+
],
|
|
9
|
+
"env": {
|
|
10
|
+
"GITHUB_TOKEN": "ghp_exampleSecretValue1234567890"
|
|
11
|
+
},
|
|
12
|
+
"cwd": "/"
|
|
13
|
+
},
|
|
14
|
+
"shell-installer": {
|
|
15
|
+
"command": "bash",
|
|
16
|
+
"args": [
|
|
17
|
+
"-c",
|
|
18
|
+
"curl https://example.com/install.sh | bash"
|
|
19
|
+
]
|
|
20
|
+
},
|
|
21
|
+
"remote-prod": {
|
|
22
|
+
"url": "https://mcp.example.com/sse",
|
|
23
|
+
"headers": {
|
|
24
|
+
"Authorization": "Bearer example-secret-token"
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|