@remnux/mcp-server 0.1.7 → 0.1.9
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/README.md +104 -127
- package/dist/cli.js +10 -8
- package/dist/cli.js.map +1 -1
- package/dist/errors/error-mapper.d.ts +1 -1
- package/dist/errors/error-mapper.d.ts.map +1 -1
- package/dist/errors/error-mapper.js +5 -2
- package/dist/errors/error-mapper.js.map +1 -1
- package/dist/file-upload.d.ts +1 -1
- package/dist/file-upload.d.ts.map +1 -1
- package/dist/file-upload.js +9 -5
- package/dist/file-upload.js.map +1 -1
- package/dist/handlers/analyze-file.d.ts.map +1 -1
- package/dist/handlers/analyze-file.js +10 -2
- package/dist/handlers/analyze-file.js.map +1 -1
- package/dist/handlers/get-file-info.js +3 -3
- package/dist/handlers/get-file-info.js.map +1 -1
- package/dist/handlers/run-tool.d.ts.map +1 -1
- package/dist/handlers/run-tool.js +3 -2
- package/dist/handlers/run-tool.js.map +1 -1
- package/dist/handlers/suggest-tools.js +7 -7
- package/dist/handlers/suggest-tools.js.map +1 -1
- package/dist/handlers/upload-file.d.ts.map +1 -1
- package/dist/handlers/upload-file.js +2 -2
- package/dist/handlers/upload-file.js.map +1 -1
- package/dist/handlers/upload-from-host.d.ts.map +1 -1
- package/dist/handlers/upload-from-host.js +2 -2
- package/dist/handlers/upload-from-host.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +29 -8
- package/dist/index.js.map +1 -1
- package/dist/parsers/olevba.js +4 -4
- package/dist/parsers/olevba.js.map +1 -1
- package/dist/parsers/pdf-parser.js +2 -2
- package/dist/parsers/pdf-parser.js.map +1 -1
- package/dist/parsers/pdfid.js +2 -2
- package/dist/parsers/pdfid.js.map +1 -1
- package/dist/parsers/peframe.js +4 -4
- package/dist/parsers/peframe.js.map +1 -1
- package/dist/schemas/tools.js +4 -4
- package/dist/schemas/tools.js.map +1 -1
- package/dist/tools/definitions.js +10 -10
- package/dist/tools/definitions.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -32,49 +32,75 @@ This server enables AI assistants (Claude Code, OpenCode, Cursor, etc.) to execu
|
|
|
32
32
|
|
|
33
33
|
The server gives AI assistants structured access to REMnux tools with features purpose-built for malware analysis workflows. Beyond raw command execution, it guides the AI toward effective analysis strategies by recommending the right tools for each file type and providing structured output that the AI can reason about.
|
|
34
34
|
|
|
35
|
-
- **Unified connection layer** — Docker exec, SSH, and local execution behind one interface. Switch deployment
|
|
35
|
+
- **Unified connection layer** — Docker exec, SSH, and local execution behind one interface. Switch deployment scenarios without changing how your AI assistant interacts with tools.
|
|
36
36
|
- **File-type-aware analysis** — `analyze_file` detects file types and runs the appropriate tool chain automatically, returning structured output with IOC extraction. `suggest_tools` lets the AI agent request recommendations and decide what to run.
|
|
37
37
|
- **Defense-in-depth guardrails** — Pattern blocking catches common AI hallucinations such as `curl | bash` or `eval`. Optional path sandboxing (`--sandbox`) restricts file operations to the samples and output directories. These complement the container or VM isolation that serves as the primary security boundary.
|
|
38
38
|
- **Browsable tool registry** — MCP resources at `remnux://tools`, `remnux://tools/by-tag/{tag}`, and `remnux://tools/{name}` let the AI agent discover available tools and their metadata without external lookups.
|
|
39
39
|
|
|
40
40
|
## Architecture
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
Three deployment scenarios are supported depending on where the MCP server and AI assistant run.
|
|
43
43
|
|
|
44
|
-
###
|
|
44
|
+
### Scenario 1: Server on Analyst's Machine
|
|
45
45
|
|
|
46
|
-
The MCP server runs on the analyst's workstation and connects to REMnux over Docker exec or SSH.
|
|
46
|
+
The MCP server runs on the analyst's workstation and connects to a separate REMnux system over Docker exec or SSH.
|
|
47
47
|
|
|
48
48
|
```
|
|
49
|
-
|
|
50
|
-
| Analyst's Machine
|
|
51
|
-
|
|
|
52
|
-
| +----------------+
|
|
53
|
-
| | AI Assistant |---->| remnux-mcp-server (npm package)
|
|
54
|
-
| | (Claude Code, | MCP |
|
|
55
|
-
| | Cursor, etc) | | - Blocked command patterns
|
|
56
|
-
| +----------------+ | - Dangerous pipe blocking
|
|
57
|
-
| | - Path sandboxing (opt-in)
|
|
58
|
-
|
|
|
59
|
-
| |
|
|
60
|
-
|
|
|
61
|
-
| v
|
|
62
|
-
| +--------------+
|
|
63
|
-
| | Docker Exec |
|
|
64
|
-
| | (container) |
|
|
65
|
-
| +------+-------+
|
|
66
|
-
| |
|
|
67
|
-
|
|
68
|
-
v
|
|
69
|
-
+-----------+
|
|
70
|
-
| REMnux |
|
|
71
|
-
| Container |
|
|
72
|
-
+-----------+
|
|
49
|
+
+--------------------------------------------------------------------+
|
|
50
|
+
| Analyst's Machine |
|
|
51
|
+
| |
|
|
52
|
+
| +----------------+ +--------------------------------------+ |
|
|
53
|
+
| | AI Assistant |---->| remnux-mcp-server (npm package) | |
|
|
54
|
+
| | (Claude Code, | MCP | | |
|
|
55
|
+
| | Cursor, etc) | | - Blocked command patterns | |
|
|
56
|
+
| +----------------+ | - Dangerous pipe blocking | |
|
|
57
|
+
| | - Path sandboxing (opt-in) | |
|
|
58
|
+
| +------|-------------------------------+ |
|
|
59
|
+
| | |
|
|
60
|
+
| +-----------+----------+ |
|
|
61
|
+
| v v |
|
|
62
|
+
| +--------------+ +--------------+ |
|
|
63
|
+
| | Docker Exec | | SSH | |
|
|
64
|
+
| | (container) | | (VM) | |
|
|
65
|
+
| +------+-------+ +------+-------+ |
|
|
66
|
+
| | | |
|
|
67
|
+
+-------------------|---------------------|---------------------------+
|
|
68
|
+
v v
|
|
69
|
+
+-----------+ +-----------+
|
|
70
|
+
| REMnux | | REMnux |
|
|
71
|
+
| Container | | VM |
|
|
72
|
+
+-----------+ +-----------+
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
###
|
|
75
|
+
### Scenario 2: Everything on REMnux
|
|
76
76
|
|
|
77
|
-
The MCP server
|
|
77
|
+
The AI assistant and MCP server both run on the REMnux system. The server uses the Local connector with stdio transport — no network, no Docker exec, no SSH. This is the simplest setup.
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
+-------------------------------+
|
|
81
|
+
| REMnux (VM or bare metal) |
|
|
82
|
+
| |
|
|
83
|
+
| +----------------+ |
|
|
84
|
+
| | AI Assistant | |
|
|
85
|
+
| | (Claude Code, | stdio |
|
|
86
|
+
| | OpenCode) +--------+ |
|
|
87
|
+
| +----------------+ | |
|
|
88
|
+
| v |
|
|
89
|
+
| +-------------------------+ |
|
|
90
|
+
| | remnux-mcp-server | |
|
|
91
|
+
| | --mode=local (default) | |
|
|
92
|
+
| | | |
|
|
93
|
+
| | - Local connector | |
|
|
94
|
+
| | - Security layers | |
|
|
95
|
+
| +-------------------------+ |
|
|
96
|
+
| |
|
|
97
|
+
| REMnux tools (native) |
|
|
98
|
+
+-------------------------------+
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Scenario 3: Server Inside REMnux
|
|
102
|
+
|
|
103
|
+
The MCP server runs inside the REMnux VM or container using the Local connector. The AI assistant connects over the network via Streamable HTTP transport. This is the deployment scenario used by REMnux salt-states.
|
|
78
104
|
|
|
79
105
|
```
|
|
80
106
|
+----------------+ Streamable HTTP +------------------------------+
|
|
@@ -103,7 +129,7 @@ Choose the scenario that matches your setup.
|
|
|
103
129
|
|
|
104
130
|
### Scenario 1: AI Tool on Your Machine, REMnux as Docker/VM
|
|
105
131
|
|
|
106
|
-
Your AI assistant (Claude Code, Cursor, etc.) runs on your physical machine. The MCP server also runs on your machine and reaches into REMnux over Docker exec or SSH to run analysis tools.
|
|
132
|
+
Your AI assistant (Claude Code, Cursor, etc.) runs on your physical machine. The MCP server also runs on your machine and reaches into REMnux over Docker exec or SSH to run analysis tools.
|
|
107
133
|
|
|
108
134
|
**With Docker (recommended):**
|
|
109
135
|
|
|
@@ -139,33 +165,29 @@ The `upload_from_host` and `download_file` tools handle file transfer between yo
|
|
|
139
165
|
|
|
140
166
|
### Scenario 2: AI Tool and MCP Server Both on REMnux
|
|
141
167
|
|
|
142
|
-
Your AI assistant (OpenCode, Claude Code, etc.) runs directly on the REMnux VM or container. The MCP server runs on the same system using the local connector
|
|
168
|
+
Your AI assistant (OpenCode, Claude Code, etc.) runs directly on the REMnux VM or container. The MCP server runs on the same system using the local connector — no network, no Docker exec, no SSH. Tools execute natively.
|
|
143
169
|
|
|
144
170
|
**Stdio transport (same machine, recommended):**
|
|
145
171
|
|
|
146
|
-
|
|
147
|
-
# Add to your AI tool's MCP config — server runs as a child process
|
|
148
|
-
# OpenCode, Claude Code, etc. launch it automatically via stdio
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
MCP settings JSON:
|
|
172
|
+
Add the server to your AI tool's MCP config. The tool launches it automatically via stdio:
|
|
152
173
|
|
|
153
174
|
```json
|
|
154
175
|
{
|
|
155
176
|
"mcpServers": {
|
|
156
177
|
"remnux": {
|
|
157
|
-
"command": "remnux-mcp-server"
|
|
158
|
-
"args": ["--mode=local"]
|
|
178
|
+
"command": "remnux-mcp-server"
|
|
159
179
|
}
|
|
160
180
|
}
|
|
161
181
|
}
|
|
162
182
|
```
|
|
163
183
|
|
|
164
|
-
The default paths (`/home/remnux/files/samples` and `/home/remnux/files/output`) match the REMnux filesystem layout, so no additional configuration is needed.
|
|
184
|
+
Local mode is the default — no `--mode` flag needed. The default paths (`/home/remnux/files/samples` and `/home/remnux/files/output`) match the REMnux filesystem layout, so no additional configuration is needed.
|
|
185
|
+
|
|
186
|
+
In local mode, analysis tools also accept absolute file paths, so you can reference files anywhere on the filesystem without uploading them first.
|
|
165
187
|
|
|
166
188
|
### Scenario 3: AI Tool on Your Machine, MCP Server on REMnux (HTTP)
|
|
167
189
|
|
|
168
|
-
Your AI assistant runs on your physical machine, but instead of the MCP server also running on your machine (Scenario 1), it runs inside REMnux and listens on a network port. Your AI tool connects over HTTP.
|
|
190
|
+
Your AI assistant runs on your physical machine, but instead of the MCP server also running on your machine (Scenario 1), it runs inside REMnux and listens on a network port. Your AI tool connects over HTTP.
|
|
169
191
|
|
|
170
192
|
Use this when you want REMnux to be self-contained — the MCP server and analysis tools are co-located, and your AI tool just needs network access.
|
|
171
193
|
|
|
@@ -200,7 +222,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
200
222
|
}
|
|
201
223
|
```
|
|
202
224
|
|
|
203
|
-
|
|
225
|
+
#### Security Notes (HTTP transport)
|
|
204
226
|
|
|
205
227
|
- **Always use a token in production.** Without `--http-token` or `MCP_TOKEN`, any network client can execute commands.
|
|
206
228
|
- **Default bind is `127.0.0.1`** — set `--http-host=0.0.0.0` to allow network access.
|
|
@@ -213,8 +235,8 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
213
235
|
|
|
214
236
|
| Flag | Description | Default |
|
|
215
237
|
|------|-------------|---------|
|
|
216
|
-
| `--mode` | Connection mode: `
|
|
217
|
-
| `--container` | Docker container name/ID | `remnux` |
|
|
238
|
+
| `--mode` | Connection mode: `local`, `docker`, or `ssh` | `local` |
|
|
239
|
+
| `--container` | Docker container name/ID (for docker mode) | `remnux` |
|
|
218
240
|
| `--host` | SSH host (for ssh mode) | - |
|
|
219
241
|
| `--user` | SSH user (for ssh mode) | `remnux` |
|
|
220
242
|
| `--port` | SSH port (for ssh mode) | `22` |
|
|
@@ -223,7 +245,6 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
223
245
|
| `--output-dir` | Output directory path inside REMnux | `/home/remnux/files/output` |
|
|
224
246
|
| `--timeout` | Default command timeout in seconds | `300` |
|
|
225
247
|
| `--sandbox` | Enable path sandboxing (restrict files to samples/output dirs) | off |
|
|
226
|
-
| `--no-sandbox` | No-op (sandbox is already off by default) | - |
|
|
227
248
|
| `--transport` | Transport mode: `stdio` or `http` | `stdio` |
|
|
228
249
|
| `--http-port` | HTTP server port (for http transport) | `3000` |
|
|
229
250
|
| `--http-host` | HTTP bind address (for http transport) | `127.0.0.1` |
|
|
@@ -235,11 +256,11 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
235
256
|
|------|-------------|
|
|
236
257
|
| `run_tool` | Execute a command in REMnux (supports piped commands) |
|
|
237
258
|
| `get_file_info` | Get file type, hashes (SHA256, MD5), basic metadata |
|
|
238
|
-
| `list_files` | List files in samples or output directory
|
|
259
|
+
| `list_files` | List files in samples or output directory |
|
|
239
260
|
| `extract_archive` | Extract .zip, .7z, .rar archives with automatic password detection |
|
|
240
|
-
| `upload_from_host` | Upload a file from the host
|
|
241
|
-
| `download_from_url` | Download a file from a URL into the samples directory
|
|
242
|
-
| `download_file` | Download a file from the output directory to the host
|
|
261
|
+
| `upload_from_host` | Upload a file from the host to the samples directory (200MB limit) |
|
|
262
|
+
| `download_from_url` | Download a file from a URL into the samples directory |
|
|
263
|
+
| `download_file` | Download a file from the output directory to the host (password-protected archive by default) |
|
|
243
264
|
| `analyze_file` | Auto-select and run REMnux tools based on detected file type |
|
|
244
265
|
| `extract_iocs` | Extract IOCs (IPs, domains, URLs, hashes, registry keys, etc.) from text with confidence scoring |
|
|
245
266
|
| `suggest_tools` | Detect file type and return recommended tools with analysis hints (no execution) |
|
|
@@ -247,7 +268,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
247
268
|
|
|
248
269
|
#### Example: Using run_tool
|
|
249
270
|
|
|
250
|
-
```
|
|
271
|
+
```jsonc
|
|
251
272
|
// Analyze a PDF for suspicious elements
|
|
252
273
|
{
|
|
253
274
|
"command": "pdfid.py --nozero",
|
|
@@ -280,7 +301,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
280
301
|
|
|
281
302
|
#### Example: Using extract_archive
|
|
282
303
|
|
|
283
|
-
```
|
|
304
|
+
```jsonc
|
|
284
305
|
// Extract a password-protected archive (tries common passwords automatically)
|
|
285
306
|
{
|
|
286
307
|
"archive_file": "malware-sample.zip"
|
|
@@ -299,11 +320,11 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
299
320
|
}
|
|
300
321
|
```
|
|
301
322
|
|
|
302
|
-
**Password handling:** The tool automatically tries common malware archive passwords (`infected`, `malware`, `virus`) if the archive is encrypted. You can also provide a custom password via the `password` parameter, which will be tried first. The password list is
|
|
323
|
+
**Password handling:** The tool automatically tries common malware archive passwords (`infected`, `malware`, `virus`) if the archive is encrypted. You can also provide a custom password via the `password` parameter, which will be tried first. The default password list is defined in [`src/config/archive-passwords.txt`](src/config/archive-passwords.txt) in the source repository.
|
|
303
324
|
|
|
304
325
|
#### Example: Using upload_from_host
|
|
305
326
|
|
|
306
|
-
```
|
|
327
|
+
```jsonc
|
|
307
328
|
// Upload a file from the host filesystem
|
|
308
329
|
{
|
|
309
330
|
"host_path": "/path/to/suspicious.exe"
|
|
@@ -326,7 +347,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
326
347
|
|
|
327
348
|
#### Example: Using download_from_url
|
|
328
349
|
|
|
329
|
-
```
|
|
350
|
+
```jsonc
|
|
330
351
|
// Download a file from a URL
|
|
331
352
|
{
|
|
332
353
|
"url": "https://example.com/suspicious.exe"
|
|
@@ -355,7 +376,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
355
376
|
|
|
356
377
|
#### Example: Using download_file
|
|
357
378
|
|
|
358
|
-
```
|
|
379
|
+
```jsonc
|
|
359
380
|
// Download as password-protected archive (default behavior)
|
|
360
381
|
{
|
|
361
382
|
"file_path": "payload.exe",
|
|
@@ -381,7 +402,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
381
402
|
|
|
382
403
|
#### Example: Using analyze_file
|
|
383
404
|
|
|
384
|
-
```
|
|
405
|
+
```jsonc
|
|
385
406
|
// Auto-analyze a PE file (detects type, runs peframe, capa, floss, etc.)
|
|
386
407
|
{
|
|
387
408
|
"file": "sample.exe"
|
|
@@ -420,7 +441,7 @@ claude mcp add remnux --transport http http://REMNUX_IP:3000/mcp \
|
|
|
420
441
|
|
|
421
442
|
#### Example: Using extract_iocs
|
|
422
443
|
|
|
423
|
-
```
|
|
444
|
+
```jsonc
|
|
424
445
|
// Extract IOCs from strings output
|
|
425
446
|
{
|
|
426
447
|
"text": "C2 at 45.33.32.156\nHKLM\\Software\\Malware\\Run\nhttp://evil.example.com/payload.exe"
|
|
@@ -474,10 +495,14 @@ All three connection modes (docker, ssh, local) execute commands inside a dispos
|
|
|
474
495
|
|
|
475
496
|
| Threat | Target | Defense |
|
|
476
497
|
|--------|--------|---------|
|
|
477
|
-
|
|
|
478
|
-
| Dangerous pipes
|
|
479
|
-
| Catastrophic commands
|
|
480
|
-
|
|
|
498
|
+
| Command injection (prompt injection tricks AI into shell execution) | Analyst's workflow | Anti-injection patterns (`eval`, `$()`, backticks, etc.) |
|
|
499
|
+
| Dangerous pipes (attacker code piped to interpreters) | Analyst's workflow | Pipe-to-interpreter blocking (`\| bash`, `\| python`) |
|
|
500
|
+
| Catastrophic commands (`rm -rf /`, `mkfs`) | Analysis session | Narrow pattern guards for root wipes and filesystem formatting |
|
|
501
|
+
| Resource exhaustion (tools hang or consume excessive resources) | AI assistant / analysis session | Timeout enforcement (default 5 min), output budgets (80KB/tool, 200KB total) |
|
|
502
|
+
| Archive zip-slip (path traversal in archives) | Analysis session | Post-extraction validation rejects path escape attempts |
|
|
503
|
+
| SSH injection | SSH connection | Proper shell escaping using single quotes |
|
|
504
|
+
|
|
505
|
+
**Other considerations:** A theoretical TOCTOU race exists between path validation and tool execution; container isolation is the primary mitigation (use immutable sample storage for high-security contexts). Tool description poisoning is mitigated by using build-time constants rather than runtime lookups from external sources.
|
|
481
506
|
|
|
482
507
|
**What does NOT need protection (container/VM's job):**
|
|
483
508
|
- REMnux filesystem, packages, services (disposable)
|
|
@@ -485,16 +510,6 @@ All three connection modes (docker, ssh, local) execute commands inside a dispos
|
|
|
485
510
|
- REMnux network config, devices, mounts (container-isolated)
|
|
486
511
|
- Path traversal inside REMnux (nothing sensitive to protect)
|
|
487
512
|
|
|
488
|
-
**Threats mitigated:**
|
|
489
|
-
|
|
490
|
-
| Threat | Mitigation |
|
|
491
|
-
|--------|------------|
|
|
492
|
-
| Command injection | Anti-injection patterns (`eval`, backticks, `$()`, `${}`, `<()`, `$VAR`, `source`, newlines) |
|
|
493
|
-
| Dangerous pipes | Pipe-to-interpreter validation (`\| bash`, `\| python`, etc.) |
|
|
494
|
-
| Archive zip-slip | Post-extraction validation rejects path escape attempts |
|
|
495
|
-
| Resource exhaustion | Timeout enforcement (default 5 min), output budgets (80KB/tool, 200KB total) |
|
|
496
|
-
| SSH injection | Proper shell escaping using single quotes |
|
|
497
|
-
|
|
498
513
|
**Blocked command patterns (anti-injection):**
|
|
499
514
|
- Control characters: newline, carriage return, null bytes
|
|
500
515
|
- Shell escape: `eval`, `exec`, backticks, `$()`, `${}`, `$VAR`, process substitution `<()` `>()`
|
|
@@ -546,33 +561,6 @@ Malware may contain strings designed to manipulate AI assistants (e.g., "Ignore
|
|
|
546
561
|
|
|
547
562
|
Unexpected AI behavior during analysis may indicate prompt injection strings in the sample — which is itself an interesting indicator of attacker sophistication.
|
|
548
563
|
|
|
549
|
-
### Additional Threat Considerations
|
|
550
|
-
|
|
551
|
-
**Tool Poisoning:**
|
|
552
|
-
Tool descriptions in the registry are build-time constants, not runtime lookups
|
|
553
|
-
from external sources, mitigating description injection risks.
|
|
554
|
-
|
|
555
|
-
**Resource Exhaustion:**
|
|
556
|
-
Malware samples may be designed to cause analysis tools to hang or consume
|
|
557
|
-
excessive resources. The default 5-minute timeout (`--timeout`) provides
|
|
558
|
-
protection. For expensive tools like `capa` on large binaries, increase
|
|
559
|
-
timeout explicitly rather than globally.
|
|
560
|
-
|
|
561
|
-
**Archive Zip-Slip:**
|
|
562
|
-
Malicious archives may contain entries with path traversal (`../`).
|
|
563
|
-
The `extract_archive` tool validates output paths after extraction and
|
|
564
|
-
rejects archives containing escape attempts.
|
|
565
|
-
|
|
566
|
-
**Process Substitution:**
|
|
567
|
-
Bash process substitution (`<(cmd)` and `>(cmd)`) is blocked alongside
|
|
568
|
-
other command injection vectors. These could allow command execution
|
|
569
|
-
via what appears to be a filename argument.
|
|
570
|
-
|
|
571
|
-
**Time-of-Check/Time-of-Use (TOCTOU):**
|
|
572
|
-
A theoretical race exists between path validation and tool execution.
|
|
573
|
-
Container isolation is the primary mitigation. For high-security contexts,
|
|
574
|
-
use immutable sample storage.
|
|
575
|
-
|
|
576
564
|
## File Workflow
|
|
577
565
|
|
|
578
566
|
**Recommended: `upload_from_host` and `download_file`** — these work across all connection modes (Docker, SSH, local), require no extra setup, and maintain container isolation.
|
|
@@ -581,41 +569,25 @@ use immutable sample storage.
|
|
|
581
569
|
|
|
582
570
|
**Getting output out:** Most analysis tools write to stdout, which `run_tool` captures directly. For tools that write output files, use `download_file` to retrieve them from the output directory.
|
|
583
571
|
|
|
584
|
-
###
|
|
572
|
+
### Docker Volume Mounts
|
|
585
573
|
|
|
586
|
-
The `upload_from_host` tool has a 200MB limit. For larger files
|
|
574
|
+
The `upload_from_host` tool has a 200MB limit. For larger files (memory images, disk images, large PCAPs) or shared directories, mount host directories into the container instead. This reduces container isolation and adds setup complexity, so prefer `upload_from_host`/`download_file` unless you have a specific need.
|
|
587
575
|
|
|
588
576
|
```bash
|
|
589
|
-
# Mount an evidence directory
|
|
577
|
+
# Mount an evidence directory (large files, read-only)
|
|
590
578
|
docker run -d --name remnux \
|
|
591
579
|
-v /path/to/evidence:/home/remnux/files/samples/evidence:ro \
|
|
592
580
|
remnux/remnux-distro:noble
|
|
593
|
-
```
|
|
594
|
-
|
|
595
|
-
Then reference files using the subdirectory path:
|
|
596
581
|
|
|
597
|
-
|
|
598
|
-
|
|
582
|
+
# Or mount full workspace directories
|
|
583
|
+
# -v ~/remnux-workspace/samples:/home/remnux/files/samples:ro
|
|
584
|
+
# -v ~/remnux-workspace/output:/home/remnux/files/output:rw
|
|
599
585
|
```
|
|
600
586
|
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
### Advanced: Docker Volume Mounts
|
|
587
|
+
Then reference mounted files using the subdirectory path:
|
|
604
588
|
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
```
|
|
608
|
-
~/remnux-workspace/ # On analyst's machine
|
|
609
|
-
├── samples/ # Mounted read-only in REMnux
|
|
610
|
-
│ └── suspicious.exe
|
|
611
|
-
├── output/ # Mounted read-write in REMnux
|
|
612
|
-
│ └── capa-results.txt
|
|
613
|
-
└── config/ # Tool configs (yara rules, etc.)
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
```bash
|
|
617
|
-
-v ~/remnux-workspace/samples:/home/remnux/files/samples:ro # Read-only
|
|
618
|
-
-v ~/remnux-workspace/output:/home/remnux/files/output:rw # Read-write
|
|
589
|
+
```jsonc
|
|
590
|
+
{ "command": "vol3 -f evidence/memory.raw windows.pslist" }
|
|
619
591
|
```
|
|
620
592
|
|
|
621
593
|
## Troubleshooting
|
|
@@ -625,8 +597,7 @@ For direct host filesystem access, you can mount shared volumes. This reduces co
|
|
|
625
597
|
| Issue | Cause | Solution |
|
|
626
598
|
|-------|-------|----------|
|
|
627
599
|
| "Container 'remnux' is not running" | Docker container stopped | Run `docker start remnux` |
|
|
628
|
-
| "Command blocked: \<category\>" | Security pattern triggered | Review command for
|
|
629
|
-
| "Command blocked: \<category\>" | Pipe to interpreter blocked | Avoid piping to interpreters (bash, python, etc.) |
|
|
600
|
+
| "Command blocked: \<category\>" | Security pattern or pipe-to-interpreter triggered | Review command for injection patterns; avoid piping to interpreters |
|
|
630
601
|
| "Invalid file path" | Path traversal or special chars | Use simple relative paths without `..` |
|
|
631
602
|
| "Invalid file path" (with `--sandbox`) | Path outside samples/output dirs | Use a relative path or remove `--sandbox` |
|
|
632
603
|
| "Command timed out" | Tool took too long | Increase `--timeout` value |
|
|
@@ -647,7 +618,7 @@ docker exec remnux which olevba
|
|
|
647
618
|
|
|
648
619
|
### Security Pattern False Positives
|
|
649
620
|
|
|
650
|
-
If a legitimate command is blocked,
|
|
621
|
+
If a legitimate command is blocked, the blocked patterns are defined in [`src/security/blocklist.ts`](src/security/blocklist.ts) in the source repository. Open an issue if a pattern needs adjustment for a valid analysis use case.
|
|
651
622
|
|
|
652
623
|
## Development
|
|
653
624
|
|
|
@@ -708,6 +679,12 @@ LOCAL_LIVE_TEST=1 npx vitest run src/__tests__/local-live-integration.test.ts
|
|
|
708
679
|
- **Works offline**: No dependency on docs.remnux.org for tool validation
|
|
709
680
|
- **Flexible**: Any installed tool can be used without updating an allowlist
|
|
710
681
|
|
|
682
|
+
### Why neutral language in tool output?
|
|
683
|
+
|
|
684
|
+
Analysis tools flag capabilities that appear in both malware and legitimate software — API imports like `GetProcAddress`, PDF keywords like `/JavaScript`, VBA patterns like `CreateObject`. When these are labeled "suspicious" or "malicious" in structured output, AI assistants tend to treat the labels as conclusions rather than observations, producing confident malware verdicts from routine findings.
|
|
685
|
+
|
|
686
|
+
To counteract this confirmation bias, the server uses neutral language ("notable" instead of "suspicious") in parser findings and tool descriptions, and includes `analysis_guidance` in `analyze_file` responses that prompts the AI to consider benign explanations and state its confidence level. The underlying detection logic is unchanged — only the framing.
|
|
687
|
+
|
|
711
688
|
## Related Projects
|
|
712
689
|
|
|
713
690
|
- [REMnux](https://remnux.org) - Linux toolkit for malware analysis
|
package/dist/cli.js
CHANGED
|
@@ -3,8 +3,7 @@ import { startServer } from "./index.js";
|
|
|
3
3
|
function parseArgs() {
|
|
4
4
|
const args = process.argv.slice(2);
|
|
5
5
|
const config = {
|
|
6
|
-
mode: "
|
|
7
|
-
container: "remnux",
|
|
6
|
+
mode: "local",
|
|
8
7
|
samplesDir: "/home/remnux/files/samples",
|
|
9
8
|
outputDir: "/home/remnux/files/output",
|
|
10
9
|
timeout: 300,
|
|
@@ -111,8 +110,8 @@ USAGE:
|
|
|
111
110
|
npx @remnux/mcp-server [OPTIONS]
|
|
112
111
|
|
|
113
112
|
OPTIONS:
|
|
114
|
-
--mode <mode> Connection mode:
|
|
115
|
-
--container <name> Docker container name/ID (
|
|
113
|
+
--mode <mode> Connection mode: local, docker, or ssh (default: local)
|
|
114
|
+
--container <name> Docker container name/ID (for docker mode)
|
|
116
115
|
--host <host> SSH host (for ssh mode)
|
|
117
116
|
--user <user> SSH user (default: remnux)
|
|
118
117
|
--port <port> SSH port (default: 22)
|
|
@@ -130,14 +129,17 @@ OPTIONS:
|
|
|
130
129
|
-v, --version Show version
|
|
131
130
|
|
|
132
131
|
EXAMPLES:
|
|
133
|
-
#
|
|
132
|
+
# Local mode (default — run directly on REMnux)
|
|
133
|
+
npx @remnux/mcp-server
|
|
134
|
+
|
|
135
|
+
# Docker mode (REMnux in a container)
|
|
134
136
|
npx @remnux/mcp-server --mode=docker --container=remnux
|
|
135
137
|
|
|
136
|
-
# SSH mode
|
|
138
|
+
# SSH mode (remote REMnux host)
|
|
137
139
|
npx @remnux/mcp-server --mode=ssh --host=192.168.1.100 --user=remnux
|
|
138
140
|
|
|
139
|
-
# HTTP transport (
|
|
140
|
-
npx @remnux/mcp-server --
|
|
141
|
+
# HTTP transport (server inside REMnux)
|
|
142
|
+
npx @remnux/mcp-server --transport=http --http-token=SECRET
|
|
141
143
|
|
|
142
144
|
# Add to Claude Code (stdio)
|
|
143
145
|
claude mcp add remnux -- npx @remnux/mcp-server
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,WAAW,EAAqB,MAAM,YAAY,CAAC;AAE5D,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAiB;QAC3B,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
|
@@ -5,5 +5,5 @@
|
|
|
5
5
|
* with code, category, and remediation hint.
|
|
6
6
|
*/
|
|
7
7
|
import { REMnuxError } from "./remnux-error.js";
|
|
8
|
-
export declare function toREMnuxError(raw: unknown): REMnuxError;
|
|
8
|
+
export declare function toREMnuxError(raw: unknown, mode?: "docker" | "ssh" | "local"): REMnuxError;
|
|
9
9
|
//# sourceMappingURL=error-mapper.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"error-mapper.d.ts","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,
|
|
1
|
+
{"version":3,"file":"error-mapper.d.ts","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,WAAW,CAuC1F"}
|
|
@@ -5,13 +5,16 @@
|
|
|
5
5
|
* with code, category, and remediation hint.
|
|
6
6
|
*/
|
|
7
7
|
import { REMnuxError } from "./remnux-error.js";
|
|
8
|
-
export function toREMnuxError(raw) {
|
|
8
|
+
export function toREMnuxError(raw, mode) {
|
|
9
9
|
if (raw instanceof REMnuxError) {
|
|
10
10
|
return raw;
|
|
11
11
|
}
|
|
12
12
|
const msg = raw instanceof Error ? raw.message : String(raw);
|
|
13
13
|
if (/is not running|not running/i.test(msg)) {
|
|
14
|
-
|
|
14
|
+
const remediation = mode === "ssh" ? "Check SSH connectivity to the REMnux host" :
|
|
15
|
+
mode === "local" ? "Check that the command exists and PATH is correct" :
|
|
16
|
+
"Run `docker start remnux` or check the container status";
|
|
17
|
+
return new REMnuxError(msg, "CONNECTION_FAILED", "connection", remediation);
|
|
15
18
|
}
|
|
16
19
|
if (/ECONNREFUSED/i.test(msg)) {
|
|
17
20
|
return new REMnuxError(msg, "CONNECTION_FAILED", "connection", "Check SSH host/port configuration");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"error-mapper.js","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,aAAa,CAAC,GAAY;
|
|
1
|
+
{"version":3,"file":"error-mapper.js","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,IAAiC;IAC3E,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAE7D,IAAI,6BAA6B,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,WAAW,GACf,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,2CAA2C,CAAC,CAAC;YAC9D,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,mDAAmD,CAAC,CAAC;gBACxE,yDAAyD,CAAC;QAC5D,OAAO,IAAI,WAAW,CACpB,GAAG,EACH,mBAAmB,EACnB,YAAY,EACZ,WAAW,CACZ,CAAC;IACJ,CAAC;IAED,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,WAAW,CACpB,GAAG,EACH,mBAAmB,EACnB,YAAY,EACZ,mCAAmC,CACpC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,WAAW,CACpB,GAAG,EACH,iBAAiB,EACjB,SAAS,EACT,4CAA4C,CAC7C,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;AAC/D,CAAC"}
|
package/dist/file-upload.d.ts
CHANGED
|
@@ -40,5 +40,5 @@ export declare function validateHostPath(hostPath: string): {
|
|
|
40
40
|
* @param overwrite - Whether to overwrite if file exists (default: false)
|
|
41
41
|
* @returns Upload result with file path, size, and SHA256 hash
|
|
42
42
|
*/
|
|
43
|
-
export declare function uploadSampleFromHost(connector: Connector, samplesDir: string, hostPath: string, filename?: string, overwrite?: boolean): Promise<UploadResult>;
|
|
43
|
+
export declare function uploadSampleFromHost(connector: Connector, samplesDir: string, hostPath: string, filename?: string, overwrite?: boolean, mode?: "docker" | "ssh" | "local"): Promise<UploadResult>;
|
|
44
44
|
//# sourceMappingURL=file-upload.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../src/file-upload.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2BrF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBrF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,GAAE,OAAe,
|
|
1
|
+
{"version":3,"file":"file-upload.d.ts","sourceRoot":"","sources":["../src/file-upload.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2BrF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBrF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,GAAE,OAAe,EAC1B,IAAI,GAAE,QAAQ,GAAG,KAAK,GAAG,OAAkB,GAC1C,OAAO,CAAC,YAAY,CAAC,CA0GvB"}
|
package/dist/file-upload.js
CHANGED
|
@@ -72,7 +72,7 @@ export function validateHostPath(hostPath) {
|
|
|
72
72
|
* @param overwrite - Whether to overwrite if file exists (default: false)
|
|
73
73
|
* @returns Upload result with file path, size, and SHA256 hash
|
|
74
74
|
*/
|
|
75
|
-
export async function uploadSampleFromHost(connector, samplesDir, hostPath, filename, overwrite = false) {
|
|
75
|
+
export async function uploadSampleFromHost(connector, samplesDir, hostPath, filename, overwrite = false, mode = "docker") {
|
|
76
76
|
// Validate host path
|
|
77
77
|
const pathValidation = validateHostPath(hostPath);
|
|
78
78
|
if (!pathValidation.valid) {
|
|
@@ -96,12 +96,16 @@ export async function uploadSampleFromHost(connector, samplesDir, hostPath, file
|
|
|
96
96
|
if (stat.size > MAX_FILE_SIZE) {
|
|
97
97
|
const sizeMB = (stat.size / 1024 / 1024).toFixed(0);
|
|
98
98
|
const limitMB = MAX_FILE_SIZE / 1024 / 1024;
|
|
99
|
+
const advice = mode === "local"
|
|
100
|
+
? `Use absolute paths in analysis tools to reference the file directly without uploading.`
|
|
101
|
+
: mode === "ssh"
|
|
102
|
+
? `Place large files directly in the samples directory on the remote host via scp/sftp.`
|
|
103
|
+
: `For large files such as memory images, mount a host directory into the container instead:\n` +
|
|
104
|
+
` docker run -v /path/to/evidence:/home/remnux/files/samples/evidence remnux/remnux-distro\n` +
|
|
105
|
+
`Then reference files as: evidence/<filename>`;
|
|
99
106
|
return {
|
|
100
107
|
success: false,
|
|
101
|
-
error: `File size (${sizeMB}MB) exceeds the ${limitMB}MB upload limit.
|
|
102
|
-
`For large files such as memory images, mount a host directory into the container instead:\n` +
|
|
103
|
-
` docker run -v /path/to/evidence:/home/remnux/files/samples/evidence remnux/remnux-distro\n` +
|
|
104
|
-
`Then reference files as: evidence/<filename>`,
|
|
108
|
+
error: `File size (${sizeMB}MB) exceeds the ${limitMB}MB upload limit. ${advice}`,
|
|
105
109
|
};
|
|
106
110
|
}
|
|
107
111
|
// Determine target filename
|
package/dist/file-upload.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"file-upload.js","sourceRoot":"","sources":["../src/file-upload.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"file-upload.js","sourceRoot":"","sources":["../src/file-upload.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"analyze-file.d.ts","sourceRoot":"","sources":["../../src/handlers/analyze-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAwC3D,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,eAAe;;;;;;
|
|
1
|
+
{"version":3,"file":"analyze-file.d.ts","sourceRoot":"","sources":["../../src/handlers/analyze-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAwC3D,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,eAAe;;;;;;GAiKtB"}
|