Skip to content

Commit b750c40

Browse files
tim-warzclaude
tim-warz
and
claude
committed
Initial commit: NetExec MCP server
MCP server providing AI assistants access to NetExec (nxc) network penetration testing tool via SSH to Kali Linux. Supports SMB, WinRM, SSH, LDAP, MSSQL, RDP, and WMI protocols with full credential handling, password spraying, and BloodHound collection capabilities. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
0 parents  commit b750c40

7 files changed

Lines changed: 2640 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# IDE and editor files
8+
.idea/
9+
.vscode/
10+
*.swp
11+
*.swo
12+
*~
13+
.DS_Store
14+
15+
# Environment files
16+
.env
17+
.env.local
18+
.env.*.local
19+
20+
# Logs
21+
logs/
22+
*.log
23+
npm-debug.log*
24+
25+
# Test coverage
26+
coverage/
27+
28+
# TypeScript cache
29+
*.tsbuildinfo
30+
31+
# OS files
32+
Thumbs.db
33+
.DS_Store
34+
35+
# SSH keys (never commit these)
36+
*.pem
37+
*.key
38+
id_rsa*
39+
id_ed25519*

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 schwarztim
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.

‎README.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# NetExec MCP Server
2+
3+
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
6+
[![NetExec](https://img.shields.io/badge/NetExec-Network%20Execution-red)](https://www.netexec.wiki/)
7+
8+
A Model Context Protocol (MCP) server that provides AI assistants with access to [NetExec](https://github.com/Pennyw0rth/NetExec) (nxc), the powerful network execution and penetration testing tool formerly known as CrackMapExec.
9+
10+
## Features
11+
12+
This MCP server enables AI assistants to execute NetExec commands via SSH to a Kali Linux machine, supporting:
13+
14+
| Protocol | Capabilities |
15+
|----------|-------------|
16+
| **SMB** | Windows enumeration, credential dumping (SAM/LSA/NTDS), command execution, pass-the-hash |
17+
| **WinRM** | Remote Windows management, PowerShell execution, credential dumping |
18+
| **SSH** | Linux/Unix authentication, key-based auth, remote command execution |
19+
| **LDAP** | Active Directory enumeration, Kerberoasting, ASREPRoast, BloodHound collection |
20+
| **MSSQL** | SQL Server queries, xp_cmdshell execution, login enumeration |
21+
| **RDP** | Credential validation, screenshot capture |
22+
| **WMI** | Windows Management Instrumentation command execution |
23+
24+
Additional features:
25+
- Password spraying across all protocols
26+
- Module management and execution
27+
- SMB share enumeration and file operations
28+
- NetExec credential database queries
29+
30+
## Prerequisites
31+
32+
- Node.js 18+
33+
- SSH access to a Kali Linux machine with NetExec installed
34+
- SSH key-based authentication (recommended) or password
35+
36+
## Installation
37+
38+
```bash
39+
# Clone the repository
40+
git clone https://github.com/schwarztim/sec-netexec-mcp.git
41+
cd sec-netexec-mcp
42+
43+
# Install dependencies
44+
npm install
45+
46+
# Build the project
47+
npm run build
48+
```
49+
50+
## Configuration
51+
52+
### Environment Variables
53+
54+
| Variable | Description | Default |
55+
|----------|-------------|---------|
56+
| `KALI_HOST` | SSH hostname or IP for Kali machine | `kali` |
57+
| `SSH_USER` | SSH username | (none) |
58+
| `SSH_KEY` | Path to SSH private key file | (none) |
59+
| `SSH_TIMEOUT` | Command timeout in seconds | `300` |
60+
61+
### Claude Desktop Configuration
62+
63+
Add to your `claude_desktop_config.json`:
64+
65+
```json
66+
{
67+
"mcpServers": {
68+
"netexec": {
69+
"command": "node",
70+
"args": ["/path/to/sec-netexec-mcp/dist/index.js"],
71+
"env": {
72+
"KALI_HOST": "your-kali-host",
73+
"SSH_USER": "kali",
74+
"SSH_KEY": "/path/to/ssh/key"
75+
}
76+
}
77+
}
78+
}
79+
```
80+
81+
## Available Tools
82+
83+
### `nxc_smb`
84+
SMB protocol operations including enumeration, share listing, user/group/session enumeration, credential dumping (SAM, LSA, NTDS), and command execution.
85+
86+
### `nxc_winrm`
87+
WinRM remote management for authentication testing, cmd/PowerShell execution, and credential dumping.
88+
89+
### `nxc_ssh`
90+
SSH protocol for authentication testing, key-based auth, and remote command execution.
91+
92+
### `nxc_ldap`
93+
LDAP/Active Directory operations including user/group/computer enumeration, Kerberoasting, ASREPRoast, BloodHound collection, and trust enumeration.
94+
95+
### `nxc_mssql`
96+
SQL Server operations including queries, xp_cmdshell execution, and login enumeration.
97+
98+
### `nxc_rdp`
99+
RDP credential validation and screenshot capture.
100+
101+
### `nxc_wmi`
102+
WMI-based command execution on Windows targets.
103+
104+
### `nxc_modules`
105+
List and query available NetExec modules for each protocol.
106+
107+
### `nxc_spray`
108+
Password spraying with configurable options including user/password lists, jitter, and continue-on-success.
109+
110+
### `nxc_shares`
111+
SMB share enumeration and file operations (spider, get, put).
112+
113+
### `nxc_raw`
114+
Execute raw NetExec commands for advanced scenarios not covered by other tools.
115+
116+
### `nxc_database`
117+
Query the NetExec credential database for stored hosts and credentials.
118+
119+
## Usage Examples
120+
121+
### Enumerate SMB Hosts
122+
```json
123+
{
124+
"tool": "nxc_smb",
125+
"arguments": {
126+
"target": "192.168.1.0/24"
127+
}
128+
}
129+
```
130+
131+
### List Shares with Credentials
132+
```json
133+
{
134+
"tool": "nxc_smb",
135+
"arguments": {
136+
"target": "192.168.1.10",
137+
"username": "admin",
138+
"password": "P@ssw0rd",
139+
"domain": "CORP",
140+
"action": "shares"
141+
}
142+
}
143+
```
144+
145+
### Pass-the-Hash Attack
146+
```json
147+
{
148+
"tool": "nxc_smb",
149+
"arguments": {
150+
"target": "192.168.1.10",
151+
"username": "admin",
152+
"hash": "aad3b435b51404eeaad3b435b51404ee:5fbc3d5fec8206a30f4b6c473d68ae76",
153+
"domain": "CORP",
154+
"action": "shares"
155+
}
156+
}
157+
```
158+
159+
### Password Spray
160+
```json
161+
{
162+
"tool": "nxc_spray",
163+
"arguments": {
164+
"protocol": "smb",
165+
"target": "192.168.1.0/24",
166+
"userList": "/tmp/users.txt",
167+
"password": "Summer2024!",
168+
"domain": "CORP",
169+
"continueOnSuccess": true
170+
}
171+
}
172+
```
173+
174+
### BloodHound Collection
175+
```json
176+
{
177+
"tool": "nxc_ldap",
178+
"arguments": {
179+
"target": "dc01.corp.local",
180+
"username": "user",
181+
"password": "password",
182+
"domain": "CORP",
183+
"action": "bloodhound",
184+
"bloodhoundCollection": "All"
185+
}
186+
}
187+
```
188+
189+
### Dump NTDS from Domain Controller
190+
```json
191+
{
192+
"tool": "nxc_smb",
193+
"arguments": {
194+
"target": "dc01.corp.local",
195+
"username": "admin",
196+
"password": "P@ssw0rd",
197+
"domain": "CORP",
198+
"action": "ntds"
199+
}
200+
}
201+
```
202+
203+
## Security Considerations
204+
205+
This tool is intended for **authorized security testing only**. Always ensure you have:
206+
207+
- Written authorization to test target systems
208+
- Proper scope definition for penetration testing engagements
209+
- Compliance with applicable laws and regulations
210+
211+
**Never use this tool against systems you do not have explicit permission to test.**
212+
213+
## Development
214+
215+
```bash
216+
# Watch mode for development
217+
npm run dev
218+
219+
# Build for production
220+
npm run build
221+
222+
# Start the server
223+
npm start
224+
```
225+
226+
## Architecture
227+
228+
```
229+
┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐
230+
│ AI Assistant │────▶│ NetExec MCP │────▶│ Kali Linux │
231+
│ (Claude, etc.) │ │ Server (Node.js)│ SSH │ (nxc) │
232+
└─────────────────┘ └──────────────────┘ └────────────────┘
233+
│
234+
│ stdio
235+
▼
236+
┌──────────────┐
237+
│ MCP Protocol │
238+
└──────────────┘
239+
```
240+
241+
## References
242+
243+
- [NetExec Official Wiki](https://www.netexec.wiki/)
244+
- [NetExec GitHub Repository](https://github.com/Pennyw0rth/NetExec)
245+
- [Model Context Protocol](https://modelcontextprotocol.io)
246+
- [NetExec Cheat Sheet](https://www.stationx.net/netexec-cheat-sheet/)
247+
- [Kali Linux NetExec](https://www.kali.org/tools/netexec/)
248+
249+
## License
250+
251+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
252+
253+
## Disclaimer
254+
255+
This software is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this program. Users are responsible for ensuring compliance with all applicable laws and regulations.

0 commit comments

Comments
 (0)