agentconfig-audit-lite 0.1.0__tar.gz

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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PyForge (https://py-forge.com)
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.
@@ -0,0 +1,5 @@
1
+ include LICENSE
2
+ include README.md
3
+ include pyproject.toml
4
+ include agentconfig_audit_lite.py
5
+ include test_agentconfig_audit_lite.py
@@ -0,0 +1,125 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentconfig-audit-lite
3
+ Version: 0.1.0
4
+ Summary: Audit MCP config for secrets: plaintext tokens and unpinned npx/uvx servers in .mcp.json and CLAUDE.md.
5
+ Author: Alessio Auretto
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/alessio1999xx-debug/agentconfig-audit-lite
8
+ Project-URL: Pro version, https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner
9
+ Keywords: mcp,mcp-security,model-context-protocol,claude-code,cursor,ai-agents,secret-scanning,cli,stdlib
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Security
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # agentconfig-audit-lite: audit MCP config for secrets, unpinned servers and unsafe Claude Code settings
28
+
29
+ agentconfig-audit-lite helps with auditing MCP config for secrets and a quick check of the AI agent setup in one project: it lists the MCP server configs and agent rule files it finds, and flags plaintext tokens, `npx`/`uvx` MCP servers with no version pin, and Claude Code settings that don't keep the agent away from `.env` files and migrations. One file, Python 3.9+ standard library only, read-only, MIT.
30
+
31
+ - Optional `pip install`, or just download the one file. No config, no state, no network calls.
32
+ - Secrets are shown as masked previews only (`ghp_****(40 chars)`), never in full.
33
+ - Flags: `--file`, `--version`. After `pip install`, use `agentconfig-audit-lite` in place of `python3 agentconfig_audit_lite.py`.
34
+
35
+ ## Install
36
+
37
+ ```bash
38
+ pip install agentconfig-audit-lite
39
+ agentconfig-audit-lite --help
40
+ ```
41
+
42
+ Or download the single file (Python 3.9+, stdlib only, no extra packages):
43
+
44
+ ```bash
45
+ curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/agentconfig-audit-lite/main/agentconfig_audit_lite.py
46
+ python3 agentconfig_audit_lite.py --help
47
+ ```
48
+
49
+ ## Scan a project's MCP config and CLAUDE.md / AGENTS.md rules
50
+
51
+ ```bash
52
+ python3 agentconfig_audit_lite.py ~/code/my-app
53
+ # agentconfig-audit-lite 0.1.0: /home/me/code/my-app
54
+ #
55
+ # Found 3 agent config / rule file(s):
56
+ # settings .claude/settings.json
57
+ # mcp .mcp.json
58
+ # rules CLAUDE.md
59
+ #
60
+ # 3 finding(s):
61
+ # FAIL [unpinned-server] .mcp.json: server 'github' runs `npx @modelcontextprotocol/server-github` with no version pin (pin e.g. pkg@1.2.3 or pkg==1.2.3)
62
+ # FAIL [plaintext-secret] .mcp.json: server 'github' env GITHUB_PERSONAL_ACCESS_TOKEN = ghp_****(40 chars) (GitHub token)
63
+ # FAIL [migrations-not-denied] .claude/settings.json: project has a migrations dir but no Edit and Write deny rules for it and no PreToolUse hook
64
+
65
+ # also check a config that lives outside the project
66
+ python3 agentconfig_audit_lite.py . --file ~/.cursor/mcp.json --file ~/.claude/settings.json
67
+ ```
68
+
69
+ ## Which MCP configs and agent rule files it checks
70
+
71
+ Files (searched in the project dir, skipping `.git`, `node_modules`, virtualenvs and build dirs):
72
+
73
+ - MCP configs: `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `mcp.json`, `claude_desktop_config.json`, `mcp_config.json`
74
+ - Agent rule files: `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.cursor/rules/*`, `copilot-instructions.md`
75
+ - Claude Code settings: `.claude/settings.json`, `.claude/settings.local.json` (any `.claude/settings*.json`)
76
+
77
+ Checks:
78
+
79
+ | Check | What it flags |
80
+ | --- | --- |
81
+ | `plaintext-secret` | Known token formats (GitHub, OpenAI/Anthropic-style `sk-`, AWS, Slack, GitLab, Google, Stripe live, Bearer, private keys) in MCP `env`/`headers`/args and rule files, plus hardcoded values under names like `*_TOKEN` or `*_PASSWORD`. `${VAR}` references are fine. |
82
+ | `unpinned-server` | `npx`, `uvx` or `bunx` MCP servers with no exact version (`pkg`, `pkg@latest`, `pkg@^1.2`). `pkg@1.2.3` and `pkg==1.2.3` pass. |
83
+ | `env-not-denied` | The project has a `.env` file (not `.env.example`) and Claude Code settings have no `Read(...env...)` deny rule and no `PreToolUse` hook. |
84
+ | `migrations-not-denied` | The project has a `migrations` dir and settings don't deny both `Edit` and `Write` on it, and there's no `PreToolUse` hook. |
85
+ | `secret-in-allow-rule` | A token pasted into a `permissions.allow` rule in `.claude/settings*.json` (this happens when you approve a command that had a key in it). |
86
+
87
+ The two Claude Code settings checks only run when the project uses Claude Code (a `CLAUDE.md` or `.claude/settings*.json` exists). A `PreToolUse` hook is counted as protection, but the lite version doesn't check what the hook actually does. A rule in `CLAUDE.md` saying "don't touch .env" is not counted: it's an instruction, not a permission.
88
+
89
+ JSON with comments can't be parsed by the standard library; those files get a `NOTE` and a plain-text token scan only.
90
+
91
+ ## Exit codes for CI or cron
92
+
93
+ | Exit code | Meaning |
94
+ | --- | --- |
95
+ | `0` | No findings |
96
+ | `1` | At least one finding |
97
+ | `2` | Bad arguments, project dir or `--file` not found |
98
+
99
+ ## agentconfig-audit-lite vs AgentConfig Audit
100
+
101
+ agentconfig-audit-lite checks one project dir and prints a plain text list. That's it.
102
+
103
+ The full **[AgentConfig Audit](https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite)** helps with:
104
+
105
+ - finding the MCP configs installed on the machine (Claude Desktop, Cursor, VS Code, Windsurf, Codex, `~/.claude.json`) on macOS, Linux and Windows
106
+ - MCP servers given the whole filesystem (`/`, `~`, `/home`, `C:\`) and remote MCP endpoints with no auth header or plain `http://`
107
+ - hidden Unicode (zero-width and bidi override characters) and prompt-injection phrases in rule files
108
+ - JSON and SARIF 2.1.0 reports, written to a file if you want
109
+ - a suggested fix or command for each finding, severity levels and a `--strict` mode for HIGH/CRITICAL only
110
+
111
+ One-time payment, yours to keep. No subscription.
112
+
113
+ Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite).
114
+
115
+ ## Tests
116
+
117
+ ```bash
118
+ python3 test_agentconfig_audit_lite.py
119
+ ```
120
+
121
+ The tests are offline and build their fixtures in temp dirs. Fake tokens are generated at runtime.
122
+
123
+ ## License
124
+
125
+ MIT (this lite version). The full AgentConfig Audit is sold separately under its own license.
@@ -0,0 +1,99 @@
1
+ # agentconfig-audit-lite: audit MCP config for secrets, unpinned servers and unsafe Claude Code settings
2
+
3
+ agentconfig-audit-lite helps with auditing MCP config for secrets and a quick check of the AI agent setup in one project: it lists the MCP server configs and agent rule files it finds, and flags plaintext tokens, `npx`/`uvx` MCP servers with no version pin, and Claude Code settings that don't keep the agent away from `.env` files and migrations. One file, Python 3.9+ standard library only, read-only, MIT.
4
+
5
+ - Optional `pip install`, or just download the one file. No config, no state, no network calls.
6
+ - Secrets are shown as masked previews only (`ghp_****(40 chars)`), never in full.
7
+ - Flags: `--file`, `--version`. After `pip install`, use `agentconfig-audit-lite` in place of `python3 agentconfig_audit_lite.py`.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pip install agentconfig-audit-lite
13
+ agentconfig-audit-lite --help
14
+ ```
15
+
16
+ Or download the single file (Python 3.9+, stdlib only, no extra packages):
17
+
18
+ ```bash
19
+ curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/agentconfig-audit-lite/main/agentconfig_audit_lite.py
20
+ python3 agentconfig_audit_lite.py --help
21
+ ```
22
+
23
+ ## Scan a project's MCP config and CLAUDE.md / AGENTS.md rules
24
+
25
+ ```bash
26
+ python3 agentconfig_audit_lite.py ~/code/my-app
27
+ # agentconfig-audit-lite 0.1.0: /home/me/code/my-app
28
+ #
29
+ # Found 3 agent config / rule file(s):
30
+ # settings .claude/settings.json
31
+ # mcp .mcp.json
32
+ # rules CLAUDE.md
33
+ #
34
+ # 3 finding(s):
35
+ # FAIL [unpinned-server] .mcp.json: server 'github' runs `npx @modelcontextprotocol/server-github` with no version pin (pin e.g. pkg@1.2.3 or pkg==1.2.3)
36
+ # FAIL [plaintext-secret] .mcp.json: server 'github' env GITHUB_PERSONAL_ACCESS_TOKEN = ghp_****(40 chars) (GitHub token)
37
+ # FAIL [migrations-not-denied] .claude/settings.json: project has a migrations dir but no Edit and Write deny rules for it and no PreToolUse hook
38
+
39
+ # also check a config that lives outside the project
40
+ python3 agentconfig_audit_lite.py . --file ~/.cursor/mcp.json --file ~/.claude/settings.json
41
+ ```
42
+
43
+ ## Which MCP configs and agent rule files it checks
44
+
45
+ Files (searched in the project dir, skipping `.git`, `node_modules`, virtualenvs and build dirs):
46
+
47
+ - MCP configs: `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `mcp.json`, `claude_desktop_config.json`, `mcp_config.json`
48
+ - Agent rule files: `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.cursor/rules/*`, `copilot-instructions.md`
49
+ - Claude Code settings: `.claude/settings.json`, `.claude/settings.local.json` (any `.claude/settings*.json`)
50
+
51
+ Checks:
52
+
53
+ | Check | What it flags |
54
+ | --- | --- |
55
+ | `plaintext-secret` | Known token formats (GitHub, OpenAI/Anthropic-style `sk-`, AWS, Slack, GitLab, Google, Stripe live, Bearer, private keys) in MCP `env`/`headers`/args and rule files, plus hardcoded values under names like `*_TOKEN` or `*_PASSWORD`. `${VAR}` references are fine. |
56
+ | `unpinned-server` | `npx`, `uvx` or `bunx` MCP servers with no exact version (`pkg`, `pkg@latest`, `pkg@^1.2`). `pkg@1.2.3` and `pkg==1.2.3` pass. |
57
+ | `env-not-denied` | The project has a `.env` file (not `.env.example`) and Claude Code settings have no `Read(...env...)` deny rule and no `PreToolUse` hook. |
58
+ | `migrations-not-denied` | The project has a `migrations` dir and settings don't deny both `Edit` and `Write` on it, and there's no `PreToolUse` hook. |
59
+ | `secret-in-allow-rule` | A token pasted into a `permissions.allow` rule in `.claude/settings*.json` (this happens when you approve a command that had a key in it). |
60
+
61
+ The two Claude Code settings checks only run when the project uses Claude Code (a `CLAUDE.md` or `.claude/settings*.json` exists). A `PreToolUse` hook is counted as protection, but the lite version doesn't check what the hook actually does. A rule in `CLAUDE.md` saying "don't touch .env" is not counted: it's an instruction, not a permission.
62
+
63
+ JSON with comments can't be parsed by the standard library; those files get a `NOTE` and a plain-text token scan only.
64
+
65
+ ## Exit codes for CI or cron
66
+
67
+ | Exit code | Meaning |
68
+ | --- | --- |
69
+ | `0` | No findings |
70
+ | `1` | At least one finding |
71
+ | `2` | Bad arguments, project dir or `--file` not found |
72
+
73
+ ## agentconfig-audit-lite vs AgentConfig Audit
74
+
75
+ agentconfig-audit-lite checks one project dir and prints a plain text list. That's it.
76
+
77
+ The full **[AgentConfig Audit](https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite)** helps with:
78
+
79
+ - finding the MCP configs installed on the machine (Claude Desktop, Cursor, VS Code, Windsurf, Codex, `~/.claude.json`) on macOS, Linux and Windows
80
+ - MCP servers given the whole filesystem (`/`, `~`, `/home`, `C:\`) and remote MCP endpoints with no auth header or plain `http://`
81
+ - hidden Unicode (zero-width and bidi override characters) and prompt-injection phrases in rule files
82
+ - JSON and SARIF 2.1.0 reports, written to a file if you want
83
+ - a suggested fix or command for each finding, severity levels and a `--strict` mode for HIGH/CRITICAL only
84
+
85
+ One-time payment, yours to keep. No subscription.
86
+
87
+ Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite).
88
+
89
+ ## Tests
90
+
91
+ ```bash
92
+ python3 test_agentconfig_audit_lite.py
93
+ ```
94
+
95
+ The tests are offline and build their fixtures in temp dirs. Fake tokens are generated at runtime.
96
+
97
+ ## License
98
+
99
+ MIT (this lite version). The full AgentConfig Audit is sold separately under its own license.
@@ -0,0 +1,125 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentconfig-audit-lite
3
+ Version: 0.1.0
4
+ Summary: Audit MCP config for secrets: plaintext tokens and unpinned npx/uvx servers in .mcp.json and CLAUDE.md.
5
+ Author: Alessio Auretto
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/alessio1999xx-debug/agentconfig-audit-lite
8
+ Project-URL: Pro version, https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner
9
+ Keywords: mcp,mcp-security,model-context-protocol,claude-code,cursor,ai-agents,secret-scanning,cli,stdlib
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Security
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # agentconfig-audit-lite: audit MCP config for secrets, unpinned servers and unsafe Claude Code settings
28
+
29
+ agentconfig-audit-lite helps with auditing MCP config for secrets and a quick check of the AI agent setup in one project: it lists the MCP server configs and agent rule files it finds, and flags plaintext tokens, `npx`/`uvx` MCP servers with no version pin, and Claude Code settings that don't keep the agent away from `.env` files and migrations. One file, Python 3.9+ standard library only, read-only, MIT.
30
+
31
+ - Optional `pip install`, or just download the one file. No config, no state, no network calls.
32
+ - Secrets are shown as masked previews only (`ghp_****(40 chars)`), never in full.
33
+ - Flags: `--file`, `--version`. After `pip install`, use `agentconfig-audit-lite` in place of `python3 agentconfig_audit_lite.py`.
34
+
35
+ ## Install
36
+
37
+ ```bash
38
+ pip install agentconfig-audit-lite
39
+ agentconfig-audit-lite --help
40
+ ```
41
+
42
+ Or download the single file (Python 3.9+, stdlib only, no extra packages):
43
+
44
+ ```bash
45
+ curl -fsSLO https://raw.githubusercontent.com/alessio1999xx-debug/agentconfig-audit-lite/main/agentconfig_audit_lite.py
46
+ python3 agentconfig_audit_lite.py --help
47
+ ```
48
+
49
+ ## Scan a project's MCP config and CLAUDE.md / AGENTS.md rules
50
+
51
+ ```bash
52
+ python3 agentconfig_audit_lite.py ~/code/my-app
53
+ # agentconfig-audit-lite 0.1.0: /home/me/code/my-app
54
+ #
55
+ # Found 3 agent config / rule file(s):
56
+ # settings .claude/settings.json
57
+ # mcp .mcp.json
58
+ # rules CLAUDE.md
59
+ #
60
+ # 3 finding(s):
61
+ # FAIL [unpinned-server] .mcp.json: server 'github' runs `npx @modelcontextprotocol/server-github` with no version pin (pin e.g. pkg@1.2.3 or pkg==1.2.3)
62
+ # FAIL [plaintext-secret] .mcp.json: server 'github' env GITHUB_PERSONAL_ACCESS_TOKEN = ghp_****(40 chars) (GitHub token)
63
+ # FAIL [migrations-not-denied] .claude/settings.json: project has a migrations dir but no Edit and Write deny rules for it and no PreToolUse hook
64
+
65
+ # also check a config that lives outside the project
66
+ python3 agentconfig_audit_lite.py . --file ~/.cursor/mcp.json --file ~/.claude/settings.json
67
+ ```
68
+
69
+ ## Which MCP configs and agent rule files it checks
70
+
71
+ Files (searched in the project dir, skipping `.git`, `node_modules`, virtualenvs and build dirs):
72
+
73
+ - MCP configs: `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `mcp.json`, `claude_desktop_config.json`, `mcp_config.json`
74
+ - Agent rule files: `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.cursor/rules/*`, `copilot-instructions.md`
75
+ - Claude Code settings: `.claude/settings.json`, `.claude/settings.local.json` (any `.claude/settings*.json`)
76
+
77
+ Checks:
78
+
79
+ | Check | What it flags |
80
+ | --- | --- |
81
+ | `plaintext-secret` | Known token formats (GitHub, OpenAI/Anthropic-style `sk-`, AWS, Slack, GitLab, Google, Stripe live, Bearer, private keys) in MCP `env`/`headers`/args and rule files, plus hardcoded values under names like `*_TOKEN` or `*_PASSWORD`. `${VAR}` references are fine. |
82
+ | `unpinned-server` | `npx`, `uvx` or `bunx` MCP servers with no exact version (`pkg`, `pkg@latest`, `pkg@^1.2`). `pkg@1.2.3` and `pkg==1.2.3` pass. |
83
+ | `env-not-denied` | The project has a `.env` file (not `.env.example`) and Claude Code settings have no `Read(...env...)` deny rule and no `PreToolUse` hook. |
84
+ | `migrations-not-denied` | The project has a `migrations` dir and settings don't deny both `Edit` and `Write` on it, and there's no `PreToolUse` hook. |
85
+ | `secret-in-allow-rule` | A token pasted into a `permissions.allow` rule in `.claude/settings*.json` (this happens when you approve a command that had a key in it). |
86
+
87
+ The two Claude Code settings checks only run when the project uses Claude Code (a `CLAUDE.md` or `.claude/settings*.json` exists). A `PreToolUse` hook is counted as protection, but the lite version doesn't check what the hook actually does. A rule in `CLAUDE.md` saying "don't touch .env" is not counted: it's an instruction, not a permission.
88
+
89
+ JSON with comments can't be parsed by the standard library; those files get a `NOTE` and a plain-text token scan only.
90
+
91
+ ## Exit codes for CI or cron
92
+
93
+ | Exit code | Meaning |
94
+ | --- | --- |
95
+ | `0` | No findings |
96
+ | `1` | At least one finding |
97
+ | `2` | Bad arguments, project dir or `--file` not found |
98
+
99
+ ## agentconfig-audit-lite vs AgentConfig Audit
100
+
101
+ agentconfig-audit-lite checks one project dir and prints a plain text list. That's it.
102
+
103
+ The full **[AgentConfig Audit](https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite)** helps with:
104
+
105
+ - finding the MCP configs installed on the machine (Claude Desktop, Cursor, VS Code, Windsurf, Codex, `~/.claude.json`) on macOS, Linux and Windows
106
+ - MCP servers given the whole filesystem (`/`, `~`, `/home`, `C:\`) and remote MCP endpoints with no auth header or plain `http://`
107
+ - hidden Unicode (zero-width and bidi override characters) and prompt-injection phrases in rule files
108
+ - JSON and SARIF 2.1.0 reports, written to a file if you want
109
+ - a suggested fix or command for each finding, severity levels and a `--strict` mode for HIGH/CRITICAL only
110
+
111
+ One-time payment, yours to keep. No subscription.
112
+
113
+ Or get every PyForge tool, current and future, with the [All-Access Pass](https://py-forge.com/pass?utm_source=github&utm_medium=readme&utm_campaign=agentconfig-audit-lite).
114
+
115
+ ## Tests
116
+
117
+ ```bash
118
+ python3 test_agentconfig_audit_lite.py
119
+ ```
120
+
121
+ The tests are offline and build their fixtures in temp dirs. Fake tokens are generated at runtime.
122
+
123
+ ## License
124
+
125
+ MIT (this lite version). The full AgentConfig Audit is sold separately under its own license.
@@ -0,0 +1,11 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ README.md
4
+ agentconfig_audit_lite.py
5
+ pyproject.toml
6
+ test_agentconfig_audit_lite.py
7
+ agentconfig_audit_lite.egg-info/PKG-INFO
8
+ agentconfig_audit_lite.egg-info/SOURCES.txt
9
+ agentconfig_audit_lite.egg-info/dependency_links.txt
10
+ agentconfig_audit_lite.egg-info/entry_points.txt
11
+ agentconfig_audit_lite.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ agentconfig-audit-lite = agentconfig_audit_lite:main
@@ -0,0 +1 @@
1
+ agentconfig_audit_lite
@@ -0,0 +1,355 @@
1
+ #!/usr/bin/env python3
2
+ """agentconfig-audit-lite: audit MCP configs and AI agent rule files in one project.
3
+
4
+ Lists the MCP server configs and agent rule files in one project directory
5
+ (CLAUDE.md, AGENTS.md, .cursor/rules, .claude/settings*.json, .mcp.json,
6
+ .cursor/mcp.json, claude_desktop_config.json, ...) and flags:
7
+
8
+ - plaintext tokens / API keys (masked in the report)
9
+ - npx / uvx MCP servers launched without a version pin
10
+ - Claude Code settings with no Read deny for .env files or no Edit/Write
11
+ deny for migrations (and no PreToolUse hook)
12
+ - tokens embedded in .claude/settings*.json permission allow rules
13
+
14
+ Read-only, plain text report, exit 1 when something is found. One file,
15
+ Python 3.9+ standard library only. MIT License.
16
+
17
+ Full version (machine-wide config discovery, JSON/SARIF reports, fix
18
+ commands, more checks): https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import argparse
24
+ import json
25
+ import os
26
+ import re
27
+ import sys
28
+ from typing import Any, Dict, Iterable, List, Optional, Tuple
29
+
30
+ __version__ = "0.1.0"
31
+
32
+ SKIP_DIRS = {".git", ".hg", ".svn", "node_modules", ".venv", "venv", "env",
33
+ "__pycache__", "build", "dist", ".tox", ".mypy_cache", ".next"}
34
+
35
+ RULE_FILE_NAMES = {"claude.md", "claude.local.md", "agents.md", "agent.md", "gemini.md",
36
+ ".cursorrules", ".windsurfrules", "copilot-instructions.md"}
37
+ MCP_FILE_NAMES = {".mcp.json", "mcp.json", "claude_desktop_config.json", "mcp_config.json"}
38
+
39
+ # (regex, label). Group 1, when present, is the secret value itself.
40
+ SECRET_PATTERNS: List[Tuple[str, str]] = [
41
+ (r"\b(sk-ant-[A-Za-z0-9_\-]{20,})", "Anthropic API key"),
42
+ (r"\b(sk-(?:proj-)?[A-Za-z0-9_\-]{20,})", "OpenAI-style API key"),
43
+ (r"\b(ghp_[A-Za-z0-9]{36,})\b", "GitHub token"),
44
+ (r"\b(gh[ousr]_[A-Za-z0-9]{36,})\b", "GitHub token"),
45
+ (r"\b(github_pat_[A-Za-z0-9_]{40,})\b", "GitHub fine-grained token"),
46
+ (r"\b(glpat-[A-Za-z0-9_\-]{20,})\b", "GitLab token"),
47
+ (r"\b(xox[baprs]-[A-Za-z0-9\-]{10,})\b", "Slack token"),
48
+ (r"\b(AKIA[0-9A-Z]{16})\b", "AWS access key ID"),
49
+ (r"\b(AIza[0-9A-Za-z_\-]{35})\b", "Google API key"),
50
+ (r"\b((?:sk|rk)_live_[0-9A-Za-z]{16,})\b", "Stripe live key"),
51
+ (r"(?i)\bbearer\s+([A-Za-z0-9_\-\.=]{20,})", "Bearer token"),
52
+ (r"(-----BEGIN [A-Z ]*PRIVATE KEY-----)", "private key"),
53
+ ]
54
+ SECRETISH_KEY = re.compile(r"(?i)(token|secret|passw(or)?d|api[_-]?key|access[_-]?key|private[_-]?key|auth)")
55
+ PLACEHOLDER = re.compile(r"(?i)^(\$\{?[A-Z0-9_:\-]+\}?|<[^>]*>|x+|\*+|your[_-].*|changeme|placeholder|example.*|\.\.\.)$")
56
+ RUNNERS = {"npx", "uvx", "bunx"}
57
+ RANGE_CHARS = set("^~><*x|")
58
+
59
+
60
+ def mask(value: str) -> str:
61
+ """Masked preview: first 4 characters, then the length. Never the full value."""
62
+ value = value.strip()
63
+ if value.startswith("-----BEGIN"):
64
+ return value[:16] + "..."
65
+ return "%s****(%d chars)" % (value[:4], len(value))
66
+
67
+
68
+ def find_secrets(text: str) -> List[Tuple[str, str]]:
69
+ """Return (label, masked preview) for every known token pattern in text."""
70
+ out: List[Tuple[str, str]] = []
71
+ seen = set()
72
+ for pattern, label in SECRET_PATTERNS:
73
+ for m in re.finditer(pattern, text):
74
+ val = m.group(1)
75
+ if PLACEHOLDER.match(val) or val in seen:
76
+ continue
77
+ if any(val in s or s in val for s in seen):
78
+ continue
79
+ seen.add(val)
80
+ out.append((label, mask(val)))
81
+ return out
82
+
83
+
84
+ class Finding:
85
+ def __init__(self, path: str, check: str, message: str):
86
+ self.path, self.check, self.message = path, check, message
87
+
88
+ def __repr__(self) -> str:
89
+ return "Finding(%r, %r, %r)" % (self.path, self.check, self.message)
90
+
91
+
92
+ # ---------------------------------------------------------------- discovery
93
+
94
+ def classify(rel: str) -> Optional[str]:
95
+ """Return 'mcp', 'settings', 'rules' or None for a project-relative path."""
96
+ parts = rel.replace("\\", "/").split("/")
97
+ name = parts[-1].lower()
98
+ parent = parts[-2].lower() if len(parts) > 1 else ""
99
+ if parent == ".claude" and re.match(r"^settings.*\.json$", name):
100
+ return "settings"
101
+ if name in MCP_FILE_NAMES:
102
+ return "mcp"
103
+ if name in RULE_FILE_NAMES:
104
+ return "rules"
105
+ if ".cursor" in [p.lower() for p in parts[:-1]] and "rules" in [p.lower() for p in parts[:-1]]:
106
+ return "rules"
107
+ if name.endswith(".mdc") and ".cursor" in [p.lower() for p in parts]:
108
+ return "rules"
109
+ return None
110
+
111
+
112
+ def discover(root: str) -> List[Tuple[str, str]]:
113
+ """Walk one project dir; return sorted (relative path, kind)."""
114
+ found: List[Tuple[str, str]] = []
115
+ for dirpath, dirnames, filenames in os.walk(root):
116
+ dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
117
+ for fname in filenames:
118
+ rel = os.path.relpath(os.path.join(dirpath, fname), root)
119
+ kind = classify(rel)
120
+ if kind:
121
+ found.append((rel, kind))
122
+ return sorted(found)
123
+
124
+
125
+ # ---------------------------------------------------------------- checks
126
+
127
+ def _package_arg(cmd: str, args: List[str]) -> Optional[str]:
128
+ """Return the package spec an npx/uvx/bunx call will run, or None."""
129
+ i = 0
130
+ while i < len(args):
131
+ a = args[i]
132
+ if a in ("--package", "-p", "--from", "--with") and i + 1 < len(args):
133
+ return args[i + 1]
134
+ if a.startswith(("--package=", "--from=")):
135
+ return a.split("=", 1)[1]
136
+ if a.startswith("-"):
137
+ i += 1
138
+ continue
139
+ return a
140
+ return None
141
+
142
+
143
+ def is_pinned(spec: str) -> bool:
144
+ if "==" in spec:
145
+ return not any(c in spec.split("==", 1)[1] for c in "*")
146
+ body = spec[1:] if spec.startswith("@") else spec
147
+ if "@" not in body:
148
+ return False
149
+ ver = body.split("@", 1)[1].strip()
150
+ if not ver or ver.lower() in ("latest", "next", "canary", "beta"):
151
+ return False
152
+ if any(c in RANGE_CHARS for c in ver) or not ver[0].isdigit():
153
+ return False
154
+ return True
155
+
156
+
157
+ def check_mcp_servers(rel: str, data: Any) -> List[Finding]:
158
+ out: List[Finding] = []
159
+ if not isinstance(data, dict):
160
+ return out
161
+ servers = data.get("mcpServers")
162
+ if not isinstance(servers, dict):
163
+ servers = data.get("servers") if isinstance(data.get("servers"), dict) else {}
164
+ # ~/.claude.json style: per-project mcpServers blocks
165
+ projects = data.get("projects")
166
+ if isinstance(projects, dict):
167
+ for proj in projects.values():
168
+ if isinstance(proj, dict) and isinstance(proj.get("mcpServers"), dict):
169
+ servers = dict(servers, **proj["mcpServers"])
170
+ for name, cfg in servers.items():
171
+ if not isinstance(cfg, dict):
172
+ continue
173
+ cmd = str(cfg.get("command", "") or "")
174
+ args = cfg.get("args") or []
175
+ args = [str(a) for a in args] if isinstance(args, list) else []
176
+ cmd_parts = cmd.split()
177
+ if len(cmd_parts) > 1: # "npx -y pkg" written as one string
178
+ cmd, args = cmd_parts[0], cmd_parts[1:] + args
179
+ runner = os.path.basename(cmd).lower()
180
+ if runner.endswith(".cmd") or runner.endswith(".exe"):
181
+ runner = runner[:-4]
182
+ if runner in RUNNERS:
183
+ spec = _package_arg(runner, args)
184
+ if spec and not is_pinned(spec):
185
+ out.append(Finding(rel, "unpinned-server",
186
+ "server '%s' runs `%s %s` with no version pin (pin e.g. pkg@1.2.3 or pkg==1.2.3)"
187
+ % (name, runner, spec)))
188
+ for section in ("env", "headers"):
189
+ block = cfg.get(section)
190
+ if not isinstance(block, dict):
191
+ continue
192
+ for key, val in block.items():
193
+ if not isinstance(val, str) or PLACEHOLDER.match(val.strip()) or "${" in val:
194
+ continue
195
+ hits = find_secrets(val)
196
+ if hits:
197
+ for label, prev in hits:
198
+ out.append(Finding(rel, "plaintext-secret",
199
+ "server '%s' %s %s = %s (%s)" % (name, section, key, prev, label)))
200
+ elif SECRETISH_KEY.search(key) and len(val) >= 12 and " " not in val:
201
+ out.append(Finding(rel, "plaintext-secret",
202
+ "server '%s' %s %s = %s (hardcoded value)" % (name, section, key, mask(val))))
203
+ for label, prev in find_secrets(" ".join(args + [str(cfg.get("url", ""))])):
204
+ out.append(Finding(rel, "plaintext-secret", "server '%s' args/url contain %s %s" % (name, label, prev)))
205
+ return out
206
+
207
+
208
+ def _rules(settings: List[Dict[str, Any]], key: str) -> List[str]:
209
+ rules: List[str] = []
210
+ for s in settings:
211
+ perms = s.get("permissions") if isinstance(s, dict) else None
212
+ if isinstance(perms, dict) and isinstance(perms.get(key), list):
213
+ rules.extend(str(r) for r in perms[key])
214
+ return rules
215
+
216
+
217
+ def _has_pretooluse(settings: List[Dict[str, Any]]) -> bool:
218
+ for s in settings:
219
+ hooks = s.get("hooks") if isinstance(s, dict) else None
220
+ if isinstance(hooks, dict) and hooks.get("PreToolUse"):
221
+ return True
222
+ return False
223
+
224
+
225
+ def check_claude_settings(root: str, files: Dict[str, Any], has_env: bool, has_migrations: bool) -> List[Finding]:
226
+ """files: rel path -> parsed JSON for .claude/settings*.json in the project root."""
227
+ out: List[Finding] = []
228
+ for rel, data in files.items():
229
+ for rule in _rules([data], "allow"):
230
+ for label, prev in find_secrets(rule):
231
+ out.append(Finding(rel, "secret-in-allow-rule",
232
+ "permissions.allow rule contains %s %s; rotate it and allow the command without the token"
233
+ % (label, prev)))
234
+ settings = list(files.values())
235
+ where = ", ".join(sorted(files)) or ".claude/settings.json (missing)"
236
+ hook = _has_pretooluse(settings)
237
+ deny = _rules(settings, "deny")
238
+ if has_env and not hook:
239
+ if not any(re.match(r"^Read\(.*\.env", r) for r in deny):
240
+ out.append(Finding(where, "env-not-denied",
241
+ "project has .env files but no Read deny rule such as \"Read(./.env*)\" and no PreToolUse hook"))
242
+ if has_migrations and not hook:
243
+ tools = {m.group(1) for r in deny for m in [re.match(r"^(Edit|Write|MultiEdit)\(.*migrations", r)] if m}
244
+ if not ({"Edit", "Write"} <= tools):
245
+ out.append(Finding(where, "migrations-not-denied",
246
+ "project has a migrations dir but no Edit and Write deny rules for it and no PreToolUse hook"))
247
+ return out
248
+
249
+
250
+ def project_flags(root: str) -> Tuple[bool, bool]:
251
+ has_env = has_mig = False
252
+ for dirpath, dirnames, filenames in os.walk(root):
253
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
254
+ if any(d.lower() == "migrations" for d in dirnames) or os.path.basename(dirpath).lower() == "migrations":
255
+ has_mig = True
256
+ if any(f == ".env" or f.startswith(".env.") for f in filenames
257
+ if not f.endswith((".example", ".sample", ".template", ".dist"))):
258
+ has_env = True
259
+ return has_env, has_mig
260
+
261
+
262
+ def audit(root: str, extra_files: Iterable[str] = ()) -> Tuple[List[Tuple[str, str]], List[Finding], List[str]]:
263
+ extra_files = list(extra_files)
264
+ """Return (inventory, findings, notes). Read-only."""
265
+ inventory = discover(root)
266
+ for f in extra_files:
267
+ name = os.path.basename(f)
268
+ inventory.append((f, "settings" if name.startswith("settings") else
269
+ ("mcp" if name.endswith(".json") else "rules")))
270
+ findings: List[Finding] = []
271
+ notes: List[str] = []
272
+ claude_settings: Dict[str, Any] = {}
273
+ uses_claude = False
274
+ for rel, kind in inventory:
275
+ path = rel if os.path.isabs(rel) or rel in extra_files else os.path.join(root, rel)
276
+ try:
277
+ with open(path, "r", encoding="utf-8", errors="replace") as fh:
278
+ text = fh.read()
279
+ except OSError as exc:
280
+ notes.append("%s: could not read (%s)" % (rel, exc.strerror or exc))
281
+ continue
282
+ if os.path.basename(rel).lower().startswith("claude") or kind == "settings":
283
+ uses_claude = True
284
+ if kind in ("mcp", "settings"):
285
+ try:
286
+ data = json.loads(text)
287
+ except ValueError:
288
+ notes.append("%s: not valid JSON, skipped structured checks" % rel)
289
+ data = None
290
+ for label, prev in find_secrets(text):
291
+ findings.append(Finding(rel, "plaintext-secret", "%s %s" % (label, prev)))
292
+ if data is not None:
293
+ findings.extend(check_mcp_servers(rel, data))
294
+ if kind == "settings":
295
+ if os.path.dirname(rel).replace("\\", "/") == ".claude":
296
+ claude_settings[rel] = data
297
+ else:
298
+ for r in _rules([data], "allow"):
299
+ for label, prev in find_secrets(r):
300
+ findings.append(Finding(rel, "secret-in-allow-rule",
301
+ "permissions.allow rule contains %s %s" % (label, prev)))
302
+ else:
303
+ for n, line in enumerate(text.splitlines(), 1):
304
+ for label, prev in find_secrets(line):
305
+ findings.append(Finding("%s:%d" % (rel, n), "plaintext-secret", "%s %s" % (label, prev)))
306
+ if uses_claude or claude_settings:
307
+ has_env, has_mig = project_flags(root)
308
+ findings.extend(check_claude_settings(root, claude_settings, has_env, has_mig))
309
+ return inventory, findings, notes
310
+
311
+
312
+ def render(root: str, inventory, findings, notes) -> str:
313
+ lines = ["agentconfig-audit-lite %s: %s" % (__version__, os.path.abspath(root)), ""]
314
+ lines.append("Found %d agent config / rule file(s):" % len(inventory))
315
+ for rel, kind in inventory:
316
+ lines.append(" %-9s %s" % (kind, rel))
317
+ if not inventory:
318
+ lines.append(" (none)")
319
+ lines.append("")
320
+ for n in notes:
321
+ lines.append("NOTE " + n)
322
+ if findings:
323
+ lines.append("%d finding(s):" % len(findings))
324
+ for f in findings:
325
+ lines.append(" FAIL [%s] %s: %s" % (f.check, f.path, f.message))
326
+ else:
327
+ lines.append("OK: no findings")
328
+ return "\n".join(lines)
329
+
330
+
331
+ def main(argv: Optional[List[str]] = None) -> int:
332
+ ap = argparse.ArgumentParser(
333
+ prog="agentconfig-audit-lite",
334
+ description="Read-only audit of MCP configs and AI agent rule files in one project dir. "
335
+ "Exit 0 = clean, 1 = findings, 2 = usage error.")
336
+ ap.add_argument("project", nargs="?", default=".", help="project directory to scan (default: .)")
337
+ ap.add_argument("--file", action="append", default=[], metavar="PATH",
338
+ help="also check this config file, e.g. ~/.cursor/mcp.json (repeatable)")
339
+ ap.add_argument("--version", action="version", version="%(prog)s " + __version__)
340
+ args = ap.parse_args(argv)
341
+ if not os.path.isdir(args.project):
342
+ print("error: not a directory: %s" % args.project, file=sys.stderr)
343
+ return 2
344
+ extra = [os.path.expanduser(f) for f in args.file]
345
+ for f in extra:
346
+ if not os.path.isfile(f):
347
+ print("error: file not found: %s" % f, file=sys.stderr)
348
+ return 2
349
+ inventory, findings, notes = audit(args.project, extra)
350
+ print(render(args.project, inventory, findings, notes))
351
+ return 1 if findings else 0
352
+
353
+
354
+ if __name__ == "__main__":
355
+ sys.exit(main())
@@ -0,0 +1,48 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "agentconfig-audit-lite"
7
+ version = "0.1.0"
8
+ description = "Audit MCP config for secrets: plaintext tokens and unpinned npx/uvx servers in .mcp.json and CLAUDE.md."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{name = "Alessio Auretto"}]
14
+ keywords = [
15
+ "mcp",
16
+ "mcp-security",
17
+ "model-context-protocol",
18
+ "claude-code",
19
+ "cursor",
20
+ "ai-agents",
21
+ "secret-scanning",
22
+ "cli",
23
+ "stdlib",
24
+ ]
25
+ classifiers = [
26
+ "Development Status :: 4 - Beta",
27
+ "Environment :: Console",
28
+ "Intended Audience :: Developers",
29
+ "Operating System :: OS Independent",
30
+ "Programming Language :: Python :: 3",
31
+ "Programming Language :: Python :: 3.9",
32
+ "Programming Language :: Python :: 3.10",
33
+ "Programming Language :: Python :: 3.11",
34
+ "Programming Language :: Python :: 3.12",
35
+ "Programming Language :: Python :: 3.13",
36
+ "Topic :: Security",
37
+ "Topic :: Utilities",
38
+ ]
39
+
40
+ [project.urls]
41
+ Homepage = "https://github.com/alessio1999xx-debug/agentconfig-audit-lite"
42
+ "Pro version" = "https://py-forge.com/products/agentconfig-audit-mcp-and-rules-scanner"
43
+
44
+ [project.scripts]
45
+ agentconfig-audit-lite = "agentconfig_audit_lite:main"
46
+
47
+ [tool.setuptools]
48
+ py-modules = ["agentconfig_audit_lite"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,176 @@
1
+ """Offline tests for agentconfig-audit-lite (temp-dir fixtures, no network).
2
+
3
+ Fake secrets are built at runtime so no real-looking token is stored in the repo.
4
+ """
5
+ import io
6
+ import json
7
+ import os
8
+ import shutil
9
+ import tempfile
10
+ import unittest
11
+ from contextlib import redirect_stderr, redirect_stdout
12
+
13
+ import agentconfig_audit_lite as aca
14
+
15
+ GH_TOKEN = "ghp_" + "A1b2C3d4E5" * 4
16
+ SK_KEY = "sk-" + "test0Key1" * 4
17
+
18
+
19
+ def run(*argv):
20
+ out, err = io.StringIO(), io.StringIO()
21
+ with redirect_stdout(out), redirect_stderr(err):
22
+ code = aca.main(list(argv))
23
+ return code, out.getvalue(), err.getvalue()
24
+
25
+
26
+ class T(unittest.TestCase):
27
+ def setUp(self):
28
+ self.d = tempfile.mkdtemp()
29
+
30
+ def tearDown(self):
31
+ shutil.rmtree(self.d, ignore_errors=True)
32
+
33
+ def write(self, rel, content):
34
+ p = os.path.join(self.d, rel)
35
+ os.makedirs(os.path.dirname(p), exist_ok=True)
36
+ with open(p, "w", encoding="utf-8") as fh:
37
+ fh.write(content if isinstance(content, str) else json.dumps(content))
38
+ return p
39
+
40
+ def checks(self):
41
+ _, findings, _ = aca.audit(self.d)
42
+ return [f.check for f in findings], findings
43
+
44
+ def test_inventory_lists_known_files(self):
45
+ self.write("CLAUDE.md", "# rules\n")
46
+ self.write("AGENTS.md", "# rules\n")
47
+ self.write(".cursor/rules/style.mdc", "use tabs\n")
48
+ self.write(".cursor/mcp.json", {"mcpServers": {}})
49
+ self.write(".mcp.json", {"mcpServers": {}})
50
+ self.write(".claude/settings.local.json", {})
51
+ self.write("node_modules/pkg/CLAUDE.md", "ignored\n")
52
+ self.write("README.md", "not an agent file\n")
53
+ inv = dict(aca.discover(self.d))
54
+ self.assertEqual(inv[".cursor/rules/style.mdc"], "rules")
55
+ self.assertEqual(inv[".cursor/mcp.json"], "mcp")
56
+ self.assertEqual(inv[".mcp.json"], "mcp")
57
+ self.assertEqual(inv[".claude/settings.local.json"], "settings")
58
+ self.assertEqual(inv["CLAUDE.md"], "rules")
59
+ self.assertNotIn("README.md", inv)
60
+ self.assertFalse(any(k.startswith("node_modules") for k in inv))
61
+
62
+ def test_clean_project_exits_zero(self):
63
+ self.write("AGENTS.md", "Run tests before committing.\n")
64
+ self.write(".mcp.json", {"mcpServers": {"fs": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem@2025.8.21", "./docs"],
65
+ "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}}}})
66
+ code, out, _ = run(self.d)
67
+ self.assertEqual(code, 0, out)
68
+ self.assertIn("OK: no findings", out)
69
+
70
+ def test_plaintext_token_in_mcp_env_is_masked(self):
71
+ self.write("claude_desktop_config.json", {"mcpServers": {"gh": {"command": "docker", "args": ["run", "ghcr.io/github/github-mcp-server"],
72
+ "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": GH_TOKEN}}}})
73
+ code, out, _ = run(self.d)
74
+ self.assertEqual(code, 1)
75
+ self.assertIn("plaintext-secret", out)
76
+ self.assertIn("ghp_****", out)
77
+ self.assertNotIn(GH_TOKEN, out)
78
+ self.assertNotIn(GH_TOKEN[4:], out)
79
+
80
+ def test_hardcoded_value_under_secret_key_name(self):
81
+ self.write(".mcp.json", {"mcpServers": {"db": {"command": "uvx", "args": ["mcp-db==0.3.1"], "env": {"DB_PASSWORD": "hunter2hunter2!!"}}}})
82
+ checks, _ = self.checks()
83
+ self.assertEqual(checks, ["plaintext-secret"])
84
+
85
+ def test_unpinned_npx_and_uvx(self):
86
+ self.write(".cursor/mcp.json", {"mcpServers": {
87
+ "a": {"command": "npx", "args": ["-y", "@scope/server"]},
88
+ "b": {"command": "uvx", "args": ["mcp-server-fetch"]},
89
+ "c": {"command": "npx", "args": ["-y", "pkg@latest"]},
90
+ "d": {"command": "npx", "args": ["-y", "pkg@^1.2.0"]},
91
+ "e": {"command": "npx -y other-server"},
92
+ "ok1": {"command": "npx", "args": ["-y", "@scope/server@1.4.2"]},
93
+ "ok2": {"command": "uvx", "args": ["--from", "mcp-git==0.6.2", "mcp-server-git"]},
94
+ "ok3": {"command": "/usr/local/bin/uvx", "args": ["mcp-time@0.2.0"]},
95
+ }})
96
+ checks, findings = self.checks()
97
+ self.assertEqual(checks.count("unpinned-server"), 5)
98
+ names = " ".join(f.message for f in findings)
99
+ for bad in ("'a'", "'b'", "'c'", "'d'", "'e'"):
100
+ self.assertIn(bad, names)
101
+ self.assertNotIn("'ok", names)
102
+
103
+ def test_env_and_migrations_not_denied(self):
104
+ self.write("CLAUDE.md", "Never edit migrations.\n")
105
+ self.write(".env", "X=1\n")
106
+ self.write("app/migrations/0001_init.py", "\n")
107
+ self.write(".claude/settings.json", {"permissions": {"allow": ["Bash(npm test)"], "deny": []}})
108
+ checks, _ = self.checks()
109
+ self.assertIn("env-not-denied", checks)
110
+ self.assertIn("migrations-not-denied", checks)
111
+
112
+ def test_deny_rules_across_settings_files_pass(self):
113
+ self.write(".env.local", "X=1\n")
114
+ self.write("migrations/001.sql", "\n")
115
+ self.write(".claude/settings.json", {"permissions": {"deny": ["Read(./.env*)", "Edit(./migrations/**)"]}})
116
+ self.write(".claude/settings.local.json", {"permissions": {"deny": ["Write(./migrations/**)"]}})
117
+ checks, _ = self.checks()
118
+ self.assertEqual(checks, [])
119
+
120
+ def test_pretooluse_hook_counts_as_protection(self):
121
+ self.write(".env", "X=1\n")
122
+ self.write(".claude/settings.json", {"hooks": {"PreToolUse": [{"matcher": "Read|Edit", "hooks": [{"type": "command", "command": "./guard.sh"}]}]}})
123
+ checks, _ = self.checks()
124
+ self.assertNotIn("env-not-denied", checks)
125
+
126
+ def test_env_example_only_is_not_flagged(self):
127
+ self.write(".env.example", "X=\n")
128
+ self.write(".claude/settings.json", {"permissions": {}})
129
+ self.assertEqual(self.checks()[0], [])
130
+
131
+ def test_token_in_allow_rule(self):
132
+ self.write(".claude/settings.local.json", {"permissions": {
133
+ "allow": ["Bash(curl -H 'Authorization: Bearer %s' https://api.example.com)" % SK_KEY]}})
134
+ code, out, _ = run(self.d)
135
+ self.assertEqual(code, 1)
136
+ self.assertIn("secret-in-allow-rule", out)
137
+ self.assertNotIn(SK_KEY, out)
138
+
139
+ def test_token_in_rule_file_reports_line(self):
140
+ self.write("AGENTS.md", "# Setup\nuse key %s for the API\n" % SK_KEY)
141
+ _, findings = self.checks()
142
+ self.assertEqual(len(findings), 1)
143
+ self.assertEqual(findings[0].path, "AGENTS.md:2")
144
+
145
+ def test_invalid_json_is_note_not_crash(self):
146
+ self.write(".vscode/mcp.json", "{ // comment\n }")
147
+ code, out, _ = run(self.d)
148
+ self.assertEqual(code, 0)
149
+ self.assertIn("not valid JSON", out)
150
+
151
+ def test_extra_file_and_usage_errors(self):
152
+ outside = tempfile.mkdtemp()
153
+ try:
154
+ p = os.path.join(outside, "mcp.json")
155
+ with open(p, "w") as fh:
156
+ json.dump({"mcpServers": {"x": {"command": "npx", "args": ["srv"]}}}, fh)
157
+ code, out, _ = run(self.d, "--file", p)
158
+ self.assertEqual(code, 1)
159
+ self.assertIn("unpinned-server", out)
160
+ finally:
161
+ shutil.rmtree(outside)
162
+ self.assertEqual(run(os.path.join(self.d, "nope"))[0], 2)
163
+ self.assertEqual(run(self.d, "--file", os.path.join(self.d, "nope.json"))[0], 2)
164
+
165
+ def test_read_only(self):
166
+ p = self.write(".mcp.json", {"mcpServers": {"x": {"command": "npx", "args": ["srv"], "env": {"API_KEY": SK_KEY}}}})
167
+ before = {f: os.stat(os.path.join(r, f)).st_mtime_ns for r, _, fs in os.walk(self.d) for f in fs}
168
+ run(self.d)
169
+ after = {f: os.stat(os.path.join(r, f)).st_mtime_ns for r, _, fs in os.walk(self.d) for f in fs}
170
+ self.assertEqual(before, after)
171
+ with open(p) as fh:
172
+ self.assertIn(SK_KEY, fh.read())
173
+
174
+
175
+ if __name__ == "__main__":
176
+ unittest.main(verbosity=2)