IMPLEMENTATION.md•5.08 kB
# MalwareAnalyzerMCP Implementation
This document describes the implementation details of the MalwareAnalyzerMCP server, with a particular focus on the specialized malware analysis commands.
## Project Structure
The project consists of several key files:
- `index.js` - Main entry point that imports and runs the server
- `serverMCP.js` - Core MCP server implementation with tool handlers
- `terminalManager.js` - Manages terminal processes, executes commands, and reads output
- `commands.js` - Configuration for specialized malware analysis commands
- `loader.js` - Debug proxy for logging communications between Claude and the server
## Implementation Approach
For the specialized malware analysis commands, a configuration-driven approach was chosen to maximize code reuse and make it easy to add new commands in the future.
### Design Decision
Three potential designs were considered:
1. **Direct Extension** - Adding each new tool as a completely separate MCP tool with its own schema and handler
2. **Specialized Command Factory** - Creating a command factory that generates commands based on tool name
3. **Command Configuration Approach** - Defining a configuration object for each command with its parameters and logic
The **Command Configuration Approach** was selected for its balance of flexibility, maintainability, and code reuse.
### Key Components
#### 1. Command Configuration (`commands.js`)
Each specialized command is defined as an object with:
- `name`: Command name
- `description`: Human-readable description
- `schema`: Zod schema for validating parameters
- `buildCommand`: Function to construct the command string from parameters
- `helpText`: Usage examples
All commands share a base schema with common parameters:
- `target`: Target file to analyze
- `options`: Additional command-line options
Each command then extends this base schema with its own specific parameters.
```javascript
export const commands = {
file: {
name: 'file',
description: 'Analyze a file and determine its type',
schema: baseCommandSchema,
buildCommand: (args) => {...},
helpText: '...'
},
// Additional commands...
};
```
#### 2. MCP Server Integration (`serverMCP.js`)
The server integrates the specialized commands in two main ways:
1. **Tool Registration**:
```javascript
const specializedTools = Object.values(commands).map(cmd => ({
name: cmd.name,
description: cmd.description + (cmd.helpText ? '\n' + cmd.helpText : ''),
inputSchema: zodToJsonSchema(cmd.schema),
}));
```
2. **Command Execution**:
```javascript
if (commands[name]) {
// Validate arguments against schema
const validationResult = cmdConfig.schema.safeParse(args);
// Build the command string
const commandStr = cmdConfig.buildCommand(validationResult.data);
// Execute via terminal manager
const result = await terminalManager.shellCommand(commandStr);
}
```
#### 3. Terminal Manager (`terminalManager.js`)
The `TerminalManager` class provides the core functionality for executing commands and tracking their output. Key methods:
- `shellCommand(command, timeoutMs)`: Executes a command and returns a promise with result
- `readOutput(pid)`: Reads output from a running or completed process
- `shutdown()`: Terminates all active processes
## Execution Flow
1. Claude sends a request to execute a specialized command (e.g., `strings`)
2. The server validates the request parameters against the command's schema
3. The `buildCommand` function constructs the command string with all options
4. The command is executed via the `TerminalManager.shellCommand` method
5. The command's output is captured and made available via the `read_output` tool
## Adding New Commands
To add a new specialized command:
1. Add a new entry to the `commands` object in `commands.js`
2. Define the command's schema, extending `baseCommandSchema` as needed
3. Implement the `buildCommand` function to construct the command string
4. Add usage examples in the `helpText` property
No changes to `serverMCP.js` are required, as it automatically discovers and registers all commands defined in the configuration.
## Security Considerations
- All user input is validated against defined schemas
- Command execution is handled through the `spawn` function from Node.js `child_process` module
- Timeouts prevent long-running commands from blocking the server
- Process termination is gracefully handled during shutdown
## Error Handling
Errors at different levels are handled appropriately:
1. Schema validation errors return detailed feedback
2. Command execution errors are logged and reported
3. Process errors are captured and included in the output
## Future Improvements
Potential enhancements:
1. Add file path validation to prevent path traversal attacks
2. Implement command caching to improve performance for repeated analyses
3. Add support for batch processing of multiple files
4. Create specialized output parsers for structured results
5. Add support for command chaining and pipelines