agentsentinel-cli 0.3.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.
Files changed (15) hide show
  1. agentsentinel_cli-0.3.0/.gitignore +19 -0
  2. agentsentinel_cli-0.3.0/PKG-INFO +187 -0
  3. agentsentinel_cli-0.3.0/README.md +158 -0
  4. agentsentinel_cli-0.3.0/agentsentinel_cli/__init__.py +3 -0
  5. agentsentinel_cli-0.3.0/agentsentinel_cli/cli.py +338 -0
  6. agentsentinel_cli-0.3.0/agentsentinel_cli/discover.py +691 -0
  7. agentsentinel_cli-0.3.0/agentsentinel_cli/discover_report.py +206 -0
  8. agentsentinel_cli-0.3.0/agentsentinel_cli/frameworks.py +144 -0
  9. agentsentinel_cli-0.3.0/agentsentinel_cli/mcp_client.py +241 -0
  10. agentsentinel_cli-0.3.0/agentsentinel_cli/mcp_report.py +186 -0
  11. agentsentinel_cli-0.3.0/agentsentinel_cli/mcp_rules.py +231 -0
  12. agentsentinel_cli-0.3.0/agentsentinel_cli/report.py +191 -0
  13. agentsentinel_cli-0.3.0/agentsentinel_cli/rules.py +239 -0
  14. agentsentinel_cli-0.3.0/agentsentinel_cli/scanner.py +314 -0
  15. agentsentinel_cli-0.3.0/pyproject.toml +56 -0
agentsentinel_cli-0.3.0/.gitignore ADDED
@@ -0,0 +1,19 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ *.pyo
5
+ .env
6
+ .coverage
7
+ htmlcov/
8
+ .pytest_cache/
9
+ *.egg-info/
10
+ dist/
11
+ build/
12
+ ui/.env
13
+ ui/node_modules/
14
+ ui/dist/
15
+ nginx/certs/*.crt
16
+ nginx/certs/*.key
17
+ nginx/certs/*.pem
18
+ prompt/
19
+ tmp/
agentsentinel_cli-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentsentinel-cli
3
+ Version: 0.3.0
4
+ Summary: Security scanner for AI agents and MCP servers — finds exfiltration paths, unauthenticated tool exposure, code execution risks, and misconfigured agents
5
+ Project-URL: Homepage, https://github.com/jaydenaung/agentsentinel
6
+ Project-URL: Repository, https://github.com/jaydenaung/agentsentinel
7
+ License: Apache-2.0
8
+ Keywords: agent-security,ai-security,cli,devsecops,discovery,langchain,llm,mcp,openai,scanner
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: Apache Software License
13
+ Classifier: Topic :: Security
14
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
+ Requires-Python: >=3.10
16
+ Requires-Dist: click>=8.0.0
17
+ Requires-Dist: rich>=13.0.0
18
+ Provides-Extra: all
19
+ Requires-Dist: httpx>=0.24.0; extra == 'all'
20
+ Requires-Dist: psutil>=5.9.0; extra == 'all'
21
+ Provides-Extra: connect
22
+ Requires-Dist: httpx>=0.24.0; extra == 'connect'
23
+ Provides-Extra: discover
24
+ Requires-Dist: httpx>=0.24.0; extra == 'discover'
25
+ Requires-Dist: psutil>=5.9.0; extra == 'discover'
26
+ Provides-Extra: mcp
27
+ Requires-Dist: httpx>=0.24.0; extra == 'mcp'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # agentsentinel-cli
31
+
32
+ One-command security scanner for AI agents and MCP servers. No server, no Docker, no setup.
33
+
34
+ ```bash
35
+ pip install agentsentinel-cli
36
+ sentinel scan my_agent.py
37
+ sentinel mcp scan http://localhost:3000
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pip install agentsentinel-cli
46
+
47
+ # With MCP server scanning (HTTP transport):
48
+ pip install "agentsentinel-cli[mcp]"
49
+
50
+ # With agent discovery (process + network scanning):
51
+ pip install "agentsentinel-cli[discover]"
52
+
53
+ # Everything:
54
+ pip install "agentsentinel-cli[all]"
55
+ ```
56
+
57
+ ---
58
+
59
+ ## Commands
60
+
61
+ ### `sentinel scan` — audit an agent file
62
+
63
+ Detects exfiltration paths, dangerous grants, hardcoded credentials, and more
64
+ from static analysis of Python agent files.
65
+
66
+ ```bash
67
+ # Scan a single file
68
+ sentinel scan my_agent.py
69
+
70
+ # Scan a directory recursively
71
+ sentinel scan ./agents/
72
+
73
+ # Fail with exit code 1 if CRITICAL findings exist (for CI)
74
+ sentinel scan my_agent.py --fail-on CRITICAL
75
+
76
+ # Output JSON (for piping into other tools)
77
+ sentinel scan my_agent.py --format json
78
+
79
+ # Include live behavior data from a running AgentSentinel instance
80
+ sentinel scan my_agent.py --connect http://localhost:9000
81
+ ```
82
+
83
+ **What it detects:**
84
+
85
+ | Rule | Severity | Description |
86
+ |------|----------|-------------|
87
+ | `EXFILTRATION_PATH` | CRITICAL | Agent holds internal-read AND external-write grants |
88
+ | `CODE_EXECUTION_GRANT` | CRITICAL | Agent holds bash/exec/shell grants |
89
+ | `HARDCODED_CREDENTIALS` | CRITICAL | API keys or secrets hardcoded in source |
90
+ | `SECRETS_ACCESS_GRANT` | HIGH | Agent holds runtime access to vaults or tokens |
91
+ | `PROMPT_INJECTION_VECTOR` | HIGH | Agent reads from web AND holds write grants |
92
+ | `LATERAL_MOVEMENT_PATH` | HIGH | Admin/IAM grants combined with infrastructure grants |
93
+ | `UNBOUNDED_FILE_ACCESS` | HIGH | Filesystem write grants with no scoped description |
94
+ | `PRIVILEGE_EXCESS` | HIGH | Write grants on a read-only described agent |
95
+ | `DANGEROUS_GRANTS` | HIGH | Agent holds dangerous tool grants |
96
+ | `TOOL_SPRAWL` | MEDIUM | Too many tools across too many categories |
97
+ | `UNDESCRIBED_WRITE_AGENT` | MEDIUM | Write grants with no agent description |
98
+ | `MISSING_RATE_LIMIT` | LOW | Dangerous grants without rate limit configuration |
99
+
100
+ ---
101
+
102
+ ### `sentinel mcp scan` — audit an MCP server
103
+
104
+ Connects to any MCP server, enumerates all exposed tools, and checks for
105
+ authentication gaps, exfiltration paths, code execution exposure, and input
106
+ validation weaknesses.
107
+
108
+ ```bash
109
+ # Scan an HTTP MCP server
110
+ sentinel mcp scan http://localhost:3000
111
+
112
+ # Scan with authentication
113
+ sentinel mcp scan http://localhost:3000 --auth-header "Authorization: Bearer token"
114
+
115
+ # Scan a stdio-transport server (launch as subprocess)
116
+ sentinel mcp scan --stdio "python my_mcp_server.py"
117
+
118
+ # JSON output for CI pipelines
119
+ sentinel mcp scan http://localhost:3000 --format json
120
+
121
+ # Fail CI on CRITICAL findings
122
+ sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
123
+ ```
124
+
125
+ **What it detects:**
126
+
127
+ | Rule | Severity | Description |
128
+ |------|----------|-------------|
129
+ | `NO_AUTH` | CRITICAL | Server accepts tool enumeration with no credentials (HTTP) |
130
+ | `UNAUTH_DANGEROUS_EXEC` | CRITICAL | Dangerous tools callable without authentication (HTTP) |
131
+ | `EXFILTRATION_PATH` | CRITICAL | Server exposes internal-read AND external-write tools |
132
+ | `CODE_EXECUTION_TOOL` | CRITICAL | Server exposes code execution tools |
133
+ | `UNBOUNDED_INPUT` | HIGH | Tools accept unconstrained string inputs — injection surface |
134
+ | `TOOL_SPRAWL` | MEDIUM | Excessive tool count or category breadth |
135
+ | `VAGUE_TOOL_DESCRIPTIONS` | MEDIUM | Short/missing descriptions expand injection surface |
136
+ | `MISSING_RATE_LIMIT` | LOW | Dangerous tools present with no visible rate limiting |
137
+
138
+ See [`docs/mcp-scan-testing.md`](../docs/mcp-scan-testing.md) for test server examples
139
+ that trigger every finding.
140
+
141
+ ---
142
+
143
+ ### `sentinel discover` — find AI agents in your environment
144
+
145
+ ```bash
146
+ sentinel discover # scan processes + network
147
+ sentinel discover --docker # include Docker containers
148
+ sentinel discover --path ./agents # scan a source directory
149
+ sentinel discover --subnet 10.0.0.0/24 # scan an internal subnet
150
+ sentinel discover --format json # machine-readable output
151
+ ```
152
+
153
+ ---
154
+
155
+ ## CI/CD integration
156
+
157
+ ```yaml
158
+ # .github/workflows/security.yml
159
+ - name: Scan AI agents
160
+ run: |
161
+ pip install agentsentinel-cli
162
+ sentinel scan ./agents/ --fail-on CRITICAL
163
+
164
+ - name: Scan MCP server
165
+ run: |
166
+ pip install "agentsentinel-cli[mcp]"
167
+ sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
168
+ ```
169
+
170
+ ---
171
+
172
+ ## Tool detection (`sentinel scan`)
173
+
174
+ The scanner detects tools defined via:
175
+ - `@tool` decorator (LangChain)
176
+ - `@SentinelTool` decorator (AgentSentinel middleware)
177
+ - `BaseTool` / `StructuredTool` subclasses
178
+ - `Tool(name=...)` and `StructuredTool(name=...)` instantiations
179
+
180
+ ---
181
+
182
+ ## Requirements
183
+
184
+ - Python 3.10+
185
+ - No running server required for static scan or stdio MCP scan
186
+ - `httpx` required for HTTP MCP scanning: `pip install "agentsentinel-cli[mcp]"`
187
+ - `psutil` + `httpx` required for `sentinel discover`: `pip install "agentsentinel-cli[discover]"`
agentsentinel_cli-0.3.0/README.md ADDED
@@ -0,0 +1,158 @@
1
+ # agentsentinel-cli
2
+
3
+ One-command security scanner for AI agents and MCP servers. No server, no Docker, no setup.
4
+
5
+ ```bash
6
+ pip install agentsentinel-cli
7
+ sentinel scan my_agent.py
8
+ sentinel mcp scan http://localhost:3000
9
+ ```
10
+
11
+ ---
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pip install agentsentinel-cli
17
+
18
+ # With MCP server scanning (HTTP transport):
19
+ pip install "agentsentinel-cli[mcp]"
20
+
21
+ # With agent discovery (process + network scanning):
22
+ pip install "agentsentinel-cli[discover]"
23
+
24
+ # Everything:
25
+ pip install "agentsentinel-cli[all]"
26
+ ```
27
+
28
+ ---
29
+
30
+ ## Commands
31
+
32
+ ### `sentinel scan` — audit an agent file
33
+
34
+ Detects exfiltration paths, dangerous grants, hardcoded credentials, and more
35
+ from static analysis of Python agent files.
36
+
37
+ ```bash
38
+ # Scan a single file
39
+ sentinel scan my_agent.py
40
+
41
+ # Scan a directory recursively
42
+ sentinel scan ./agents/
43
+
44
+ # Fail with exit code 1 if CRITICAL findings exist (for CI)
45
+ sentinel scan my_agent.py --fail-on CRITICAL
46
+
47
+ # Output JSON (for piping into other tools)
48
+ sentinel scan my_agent.py --format json
49
+
50
+ # Include live behavior data from a running AgentSentinel instance
51
+ sentinel scan my_agent.py --connect http://localhost:9000
52
+ ```
53
+
54
+ **What it detects:**
55
+
56
+ | Rule | Severity | Description |
57
+ |------|----------|-------------|
58
+ | `EXFILTRATION_PATH` | CRITICAL | Agent holds internal-read AND external-write grants |
59
+ | `CODE_EXECUTION_GRANT` | CRITICAL | Agent holds bash/exec/shell grants |
60
+ | `HARDCODED_CREDENTIALS` | CRITICAL | API keys or secrets hardcoded in source |
61
+ | `SECRETS_ACCESS_GRANT` | HIGH | Agent holds runtime access to vaults or tokens |
62
+ | `PROMPT_INJECTION_VECTOR` | HIGH | Agent reads from web AND holds write grants |
63
+ | `LATERAL_MOVEMENT_PATH` | HIGH | Admin/IAM grants combined with infrastructure grants |
64
+ | `UNBOUNDED_FILE_ACCESS` | HIGH | Filesystem write grants with no scoped description |
65
+ | `PRIVILEGE_EXCESS` | HIGH | Write grants on a read-only described agent |
66
+ | `DANGEROUS_GRANTS` | HIGH | Agent holds dangerous tool grants |
67
+ | `TOOL_SPRAWL` | MEDIUM | Too many tools across too many categories |
68
+ | `UNDESCRIBED_WRITE_AGENT` | MEDIUM | Write grants with no agent description |
69
+ | `MISSING_RATE_LIMIT` | LOW | Dangerous grants without rate limit configuration |
70
+
71
+ ---
72
+
73
+ ### `sentinel mcp scan` — audit an MCP server
74
+
75
+ Connects to any MCP server, enumerates all exposed tools, and checks for
76
+ authentication gaps, exfiltration paths, code execution exposure, and input
77
+ validation weaknesses.
78
+
79
+ ```bash
80
+ # Scan an HTTP MCP server
81
+ sentinel mcp scan http://localhost:3000
82
+
83
+ # Scan with authentication
84
+ sentinel mcp scan http://localhost:3000 --auth-header "Authorization: Bearer token"
85
+
86
+ # Scan a stdio-transport server (launch as subprocess)
87
+ sentinel mcp scan --stdio "python my_mcp_server.py"
88
+
89
+ # JSON output for CI pipelines
90
+ sentinel mcp scan http://localhost:3000 --format json
91
+
92
+ # Fail CI on CRITICAL findings
93
+ sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
94
+ ```
95
+
96
+ **What it detects:**
97
+
98
+ | Rule | Severity | Description |
99
+ |------|----------|-------------|
100
+ | `NO_AUTH` | CRITICAL | Server accepts tool enumeration with no credentials (HTTP) |
101
+ | `UNAUTH_DANGEROUS_EXEC` | CRITICAL | Dangerous tools callable without authentication (HTTP) |
102
+ | `EXFILTRATION_PATH` | CRITICAL | Server exposes internal-read AND external-write tools |
103
+ | `CODE_EXECUTION_TOOL` | CRITICAL | Server exposes code execution tools |
104
+ | `UNBOUNDED_INPUT` | HIGH | Tools accept unconstrained string inputs — injection surface |
105
+ | `TOOL_SPRAWL` | MEDIUM | Excessive tool count or category breadth |
106
+ | `VAGUE_TOOL_DESCRIPTIONS` | MEDIUM | Short/missing descriptions expand injection surface |
107
+ | `MISSING_RATE_LIMIT` | LOW | Dangerous tools present with no visible rate limiting |
108
+
109
+ See [`docs/mcp-scan-testing.md`](../docs/mcp-scan-testing.md) for test server examples
110
+ that trigger every finding.
111
+
112
+ ---
113
+
114
+ ### `sentinel discover` — find AI agents in your environment
115
+
116
+ ```bash
117
+ sentinel discover # scan processes + network
118
+ sentinel discover --docker # include Docker containers
119
+ sentinel discover --path ./agents # scan a source directory
120
+ sentinel discover --subnet 10.0.0.0/24 # scan an internal subnet
121
+ sentinel discover --format json # machine-readable output
122
+ ```
123
+
124
+ ---
125
+
126
+ ## CI/CD integration
127
+
128
+ ```yaml
129
+ # .github/workflows/security.yml
130
+ - name: Scan AI agents
131
+ run: |
132
+ pip install agentsentinel-cli
133
+ sentinel scan ./agents/ --fail-on CRITICAL
134
+
135
+ - name: Scan MCP server
136
+ run: |
137
+ pip install "agentsentinel-cli[mcp]"
138
+ sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Tool detection (`sentinel scan`)
144
+
145
+ The scanner detects tools defined via:
146
+ - `@tool` decorator (LangChain)
147
+ - `@SentinelTool` decorator (AgentSentinel middleware)
148
+ - `BaseTool` / `StructuredTool` subclasses
149
+ - `Tool(name=...)` and `StructuredTool(name=...)` instantiations
150
+
151
+ ---
152
+
153
+ ## Requirements
154
+
155
+ - Python 3.10+
156
+ - No running server required for static scan or stdio MCP scan
157
+ - `httpx` required for HTTP MCP scanning: `pip install "agentsentinel-cli[mcp]"`
158
+ - `psutil` + `httpx` required for `sentinel discover`: `pip install "agentsentinel-cli[discover]"`
agentsentinel_cli-0.3.0/agentsentinel_cli/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """AgentSentinel CLI — one-command security scanner for AI agents."""
2
+
3
+ __version__ = "0.1.0"