Skip to content

rioasmara/cyberTriageMCP

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
src
src
 
 
.gitignore
.gitignore
 
 
PROJECT_SUMMARY.md
PROJECT_SUMMARY.md
 
 
README.md
README.md
 
 
SETUP.md
SETUP.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

CyberTriage MCP Server

An MCP (Model Context Protocol) server that provides AI agents with access to CyberTriage incident database forensic analysis capabilities.

Features

This MCP server exposes 50+ forensic analysis tools organized into categories:

  • File System Analysis (10 tools) - File modifications, sizes, extensions, suspicious locations
  • Process Analysis (12 tools) - Process execution, privileges, command lines, DLLs, process trees
  • User Activity & Accounts (11 tools) - User accounts, file access, logon sessions, account attributes
  • Windows Event Logs (8 tools) - Event analysis, authentication, specific logs, keyword search
  • Network Activity (3 tools) - IP addresses, DNS mappings, outbound connections
  • Device Connections (2 tools) - USB devices, connection patterns
  • Security Analysis (3 tools) - Unsigned files, high-priority artifacts, hashset hits
  • Artifact Analysis (3 tools) - Artifact types, attributes, common types
  • Web Activity (3 tools) - Bookmarks, history, downloads
  • File Integrity & Hashes (3 tools) - Hash lookups (MD5/SHA256), duplicates
  • Timeline Analysis (1 tool) - Chronological event reconstruction
  • Statistics (2 tools) - Overall metrics, file type distribution

Prerequisites

  • Node.js 18+
  • TypeScript 5+
  • CyberTriage incident database file (incident_data.ind)

Installation

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Set the database path using environment variable or place incident_data.ind in the project root:

export CYBERTRIAGE_DB_PATH=/path/to/incident_data.ind

Usage

Running the Server

# Production
npm start

# Development (with watch mode)
npm run dev

The server communicates via stdio using the MCP protocol.

Connecting an AI Agent

Configure your AI agent (Claude Desktop, ChatGPT, etc.) to use this MCP server:

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "cybertriage": {
      "command": "node",
      "args": ["/path/to/cyberTriageMCP/dist/index.js"],
      "env": {
        "CYBERTRIAGE_DB_PATH": "/path/to/incident_data.ind"
      }
    }
  }
}

Example Tool Calls

Once connected, AI agents can call tools like:

  • get_files_by_time_range - Get files modified in a time period
  • get_elevated_processes - Find processes with admin privileges
  • get_authentication_failure_events - Find failed login attempts
  • get_usb_devices - List USB devices connected
  • get_unsigned_files - Find unsigned executables
  • get_timeline - Build a chronological timeline

Available Tools

This MCP server provides 50+ forensic analysis tools organized into the following categories:

📁 File System Analysis Tools (10 tools)

get_files_by_time_range

Get files that were created, modified, or accessed during a specific time period. Useful for timeline analysis and identifying activity during an incident window.

Parameters:

  • startTime (number, required): Start timestamp in milliseconds (Unix epoch)
  • endTime (number, required): End timestamp in milliseconds (Unix epoch)
  • limit (number, optional): Maximum number of results (default: 100)

Returns: File details including path, creation/modification/access times, size, MD5, and SHA256 hashes.

get_largest_files

Identify the largest files on the system. Helps identify data exfiltration, large downloads, or suspiciously large files.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files sorted by size with path, size, modification time, and hashes.

get_files_by_extension

Find files with specific extensions (e.g., .exe, .dll, .bat, .ps1, .vbs). Useful for finding executables, scripts, or specific file types.

Parameters:

  • extensions (array of strings, required): Array of file extensions (e.g., [".exe", ".dll"])
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files matching the specified extensions with path, size, modification time, and hashes.

get_files_in_suspicious_locations

Identify files in suspicious locations like Temp folders, AppData, Downloads, or Recent folders. These locations are commonly used by malware.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files in suspicious paths with timestamps and hashes.

get_deleted_files

Find files that have been deleted but are still recoverable from the file system. Important for finding evidence that attackers tried to hide.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Deleted files with paths, sizes, and modification times.

get_files_with_extension_mismatch

Detect files with unusual or mismatched extensions (e.g., a file with .exe extension but PDF MIME type). This can indicate file obfuscation or malicious files.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files with mismatched extensions and MIME types.

get_recently_modified_files

Get files modified in the last 24 hours before collection. Helps identify recent activity and potential indicators of compromise.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Recently modified files with paths, sizes, timestamps, and hashes.

get_unknown_files

Find files with no known hash matches (unknown files). These may be custom malware, new variants, or legitimate unknown software.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Unknown files with paths, sizes, timestamps, and hashes.

get_recycle_bin_files

List files in the Windows Recycle Bin. Useful for finding deleted files that users thought were removed.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files in Recycle Bin with paths and modification times.

get_accessed_not_modified_files

Find files that have been accessed but never modified. Can indicate files that were read but not changed, potentially for data exfiltration.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files with access times but no modification after access.

🔄 Process Analysis Tools (12 tools)

get_all_processes

Get all processes that were running on the system, including MD5 and SHA256 hashes. Provides a complete view of process execution.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Process details including name, path, arguments, start/end times, PID, PPID, user, privileges, and file hashes.

get_elevated_processes

Find processes executed with elevated/admin privileges. Critical for identifying privilege escalation or unauthorized administrative activity.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Elevated processes with execution details and file hashes.

get_processes_from_suspicious_locations

Identify processes executed from suspicious locations (Temp, Downloads, AppData). Malware often executes from these locations.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes from suspicious paths with execution details and hashes.

get_process_dlls

Get DLLs loaded by a specific process. Useful for understanding process dependencies and detecting DLL hijacking or suspicious DLL loads.

Parameters:

  • processName (string, required): Process name (e.g., "cmd.exe")
  • limit (number, optional): Maximum number of results (default: 100)

Returns: DLLs loaded by the specified process with paths and MD5 hashes.

get_processes_with_suspicious_arguments

Find processes with unusual or suspicious command-line arguments. Detects obfuscated commands, encoded payloads, or malicious command patterns.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes with suspicious arguments (powershell, base64, download commands, etc.) and file hashes.

get_processes_by_user

Get all processes executed by a specific user. Helps attribute activity to specific user accounts.

Parameters:

  • username (string, required): Username/login name
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes executed by the user with execution details and hashes.

get_unique_processes_by_user_with_hashes

Get unique processes executed by a specific user with execution counts, time ranges, and file hashes. Groups by process name and path to show execution patterns.

Parameters:

  • username (string, required): Username/login name
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Unique processes with execution counts, first/last execution times, and hashes.

get_process_tree

Get parent-child relationships between processes. Essential for understanding process spawning chains and attack progression.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Process tree relationships showing parent and child processes with PIDs and start times.

get_processes_by_time_range

Get processes executed during a specific time window. Useful for correlating process activity with incident timelines.

Parameters:

  • startTime (number, required): Start timestamp in milliseconds
  • endTime (number, required): End timestamp in milliseconds
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes executed in the time range with execution details.

get_longest_running_processes

Identify processes with the longest execution times. Can indicate persistence mechanisms or long-running malicious processes.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes sorted by duration with start/end times and calculated duration.

get_processes_by_observation_type

Filter processes by observation type (LiveSnapshot vs LocalTrace). Helps distinguish between live system analysis and historical traces.

Parameters:

  • observationType (string, required): Either "LocalTrace" or "LiveSnapshot"
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Processes matching the observation type.

get_latest_process_run

Get the latest execution of a process by name and/or path, including best-effort user attribution and file hashes. Useful for finding the most recent instance of a specific process.

Parameters:

  • processName (string, optional): Process name (e.g., "padang-triage.exe")
  • processPath (string, optional): Full process path (e.g., "/Users/foo/Downloads/a.exe")

Returns: Latest process execution with user attribution, execution details, and file hashes.

👤 User Activity & Account Tools (10 tools)

get_all_user_accounts

Get all user accounts that exist on the system. Provides a complete list of user accounts for analysis.

Parameters: None

Returns: User accounts with login names, full names, SIDs, types, creation dates, and status.

get_files_accessed_by_user

Get files accessed by a specific user. Helps understand user activity and data access patterns.

Parameters:

  • username (string, required): Username/login name
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files accessed by the user with access dates and paths.

get_user_files_last_login

Get files accessed by a user within N days prior to the user's most recent successful logon. Useful for identifying suspicious activity around login events.

Parameters:

  • username (string, required): Username/login name
  • days (number, optional): Days prior to last successful logon (default: 30)
  • limit (number, optional): Maximum number of results (default: 1000)

Returns: Files accessed before the last login with access dates.

get_recently_accessed_files

Get the most recently accessed files by any user. Helps identify recent activity across all users.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Most recently accessed files with user information and access dates.

get_recently_created_accounts

Get user accounts that have been created recently. Important for detecting unauthorized account creation.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Recently created user accounts with creation dates and details.

get_logon_sessions_by_user

Get logon sessions for a specific user. Provides authentication history and session information.

Parameters:

  • username (string, required): Username/login name
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Logon sessions with start/end times, logon types, direction, status, IP addresses, and hostnames.

get_successful_logons

Get all successful logon sessions. Helps establish baseline authentication patterns and identify legitimate access.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Successful logon sessions with details.

get_failed_logons

Get all failed logon attempts. Critical for detecting brute force attacks, account enumeration, or unauthorized access attempts.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Failed logon attempts with failure reasons, timestamps, and source information.

get_logon_statistics

Get statistics on incoming vs outgoing logon sessions. Provides overview of authentication patterns.

Parameters: None

Returns: Statistics grouped by direction, logon type, and status.

get_files_owned_by_user

Get files owned by a specific user account. Helps identify user data and file ownership patterns.

Parameters:

  • username (string, required): Username/login name
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Files owned by the user with paths, sizes, and modification times.

get_user_account_attributes

Get account attributes for a specific user. Provides detailed account information including security settings and metadata.

Parameters:

  • username (string, required): Username/login name

Returns: User account attributes including types, values, and timestamps.

📋 Windows Event Log Tools (8 tools)

get_events_by_time_range

Get Windows events that occurred during a specific time period. Essential for timeline analysis and correlating events with incidents.

Parameters:

  • startTime (number, required): Start timestamp in milliseconds
  • endTime (number, required): End timestamp in milliseconds
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Windows events with log names, event IDs, timestamps, user information, and payloads.

get_most_common_event_ids

Get the most common Windows event IDs. Helps identify normal vs. unusual event patterns.

Parameters:

  • limit (number, optional): Maximum number of results (default: 50)

Returns: Most frequent event IDs with counts and log names.

get_authentication_failure_events

Get Windows events related to authentication failures. Critical for detecting credential-based attacks.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Authentication failure events (Event IDs 4625, 4648, 4771, 4776) with details.

get_events_by_user

Get Windows events involving a specific user. Helps track user activity through event logs.

Parameters:

  • username (string, required): Username or SID
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Events associated with the user with timestamps and payloads.

get_events_by_log_name

Get events from specific event logs (Security, System, Application). Allows focused analysis of particular log sources.

Parameters:

  • logName (string, required): Event log name (e.g., "Security", "System")
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Event statistics for the specified log with counts and time ranges.

get_events_by_keyword

Get Windows events with specific keywords in their payload. Useful for searching for specific activities or indicators.

Parameters:

  • keyword (string, required): Keyword to search for
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Events containing the keyword in their payload.

get_winrm_events

Get WinRM (Windows Remote Management) events. Important for detecting remote management activity and potential lateral movement.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: WinRM-related events with timestamps and payloads.

get_events_around_incident

Get events that occurred around the time of a specific incident. Helps build context around an incident timeline.

Parameters:

  • incidentTime (number, required): Incident timestamp in milliseconds
  • hoursBefore (number, optional): Hours before incident (default: 1)
  • hoursAfter (number, optional): Hours after incident (default: 1)
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Events within the specified time window around the incident.

🌐 Network Activity Tools (3 tools)

get_network_addresses

Get network addresses (IPs and hostnames) associated with hosts. Provides network topology information.

Parameters: None

Returns: Network addresses with types, hostnames, and active times.

get_dns_ip_mappings

Get DNS names mapped to IP addresses. Useful for understanding DNS resolution and identifying suspicious domains.

Parameters: None

Returns: DNS to IP mappings with timestamps.

get_outbound_network_connections

Get applications with outbound network connections, including destination IP addresses and ports. Critical for detecting data exfiltration and C2 communications.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Outbound connections from web downloads and history with hostnames, IPs, ports, and timestamps.

🔌 Device Connection Tools (2 tools)

get_usb_devices

Get USB devices that were connected to the system. Important for detecting unauthorized storage devices or data exfiltration via USB.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: USB devices with vendor, product, serial numbers, connection times, and event types.

get_devices_by_time_range

Get devices connected during a specific time period. Helps correlate device connections with incident timelines.

Parameters:

  • startTime (number, required): Start timestamp in milliseconds
  • endTime (number, required): End timestamp in milliseconds
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Devices connected in the time range with connection details.

🔒 Security Analysis Tools (3 tools)

get_unsigned_files

Get files that are unsigned or have verification failures. Unsigned executables can indicate malware or unauthorized software.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Unsigned or untrusted files with paths, hashes, and verification status.

get_high_priority_artifacts

Get artifacts with high significance or priority scores. These are flagged by CyberTriage as potentially important findings.

Parameters:

  • minSignificance (number, optional): Minimum significance score (default: 50)
  • minPriority (number, optional): Minimum priority score (default: 50)
  • limit (number, optional): Maximum number of results (default: 100)

Returns: High-priority artifacts with significance/priority scores, conclusions, and justifications.

get_hashset_hits

Get hashset hits (known malicious files). Identifies files that match known malware hashes.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Known malicious files with paths, hashes, modification times, and analysis conclusions.

🎯 Artifact Analysis Tools (3 tools)

get_artifacts_by_type

Get all artifacts of a specific type. Allows filtering by artifact category for focused analysis.

Parameters:

  • artifactType (string, required): Artifact type name (e.g., "TSK_WEB_DOWNLOAD")
  • limit (number, optional): Maximum number of results (default: 100)

Returns: Artifacts of the specified type with IDs and timestamps.

get_artifact_attributes

Get attributes associated with a specific artifact. Provides detailed information about a particular artifact.

Parameters:

  • artifactId (number, required): Artifact ID

Returns: All attributes for the artifact including types, values, sources, and contexts.

get_most_common_artifact_types

Get the most common artifact types found. Helps understand what types of artifacts are present in the investigation.

Parameters:

  • limit (number, optional): Maximum number of results (default: 50)

Returns: Most common artifact types with counts.

🌍 Web Activity Tools (3 tools)

get_web_bookmarks

Get web bookmarks that were found. Can reveal user interests, visited sites, or potential indicators.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Web bookmarks with URLs and bookmark names.

get_web_history

Get web history entries. Critical for understanding browsing activity and identifying suspicious websites.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Web history entries with URLs, visit times, and contexts.

get_web_downloads

Get web downloads that occurred. Important for identifying downloaded files, especially potential malware.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Web downloads with URLs, file paths, and download times.

🔐 File Integrity & Hash Tools (3 tools)

get_files_by_md5

Get files with specific MD5 hashes. Useful for finding files matching known hashes or verifying file integrity.

Parameters:

  • hashes (array of strings, required): Array of MD5 hashes

Returns: Files matching the MD5 hashes with paths, sizes, and timestamps.

get_files_by_sha256

Get files with specific SHA256 hashes. More secure than MD5 for hash-based file identification.

Parameters:

  • hashes (array of strings, required): Array of SHA256 hashes

Returns: Files matching the SHA256 hashes with paths, sizes, and timestamps.

get_duplicate_files

Get files with duplicate hashes (potential duplicates or copies). Can indicate file copying, backups, or suspicious file replication.

Parameters:

  • limit (number, optional): Maximum number of results (default: 100)

Returns: Duplicate file groups with hash, file count, and file paths.

⏱️ Timeline Analysis Tools (1 tool)

get_timeline

Get a chronological timeline combining processes, file modifications, and events. Essential for understanding the sequence of events during an incident.

Parameters:

  • startTime (number, required): Start timestamp in milliseconds
  • endTime (number, required): End timestamp in milliseconds
  • limit (number, optional): Maximum number of results (default: 5000)

Returns: Unified timeline of processes, file modifications, and Windows events in chronological order.

📊 Statistics Tools (2 tools)

get_investigation_statistics

Get overall statistics for the investigation. Provides high-level metrics about the incident data.

Parameters: None

Returns: Statistics including total files, processes, events, artifacts, users, devices, and high-priority artifacts.

get_file_type_distribution

Get distribution of file types. Helps understand what types of files are present in the investigation.

Parameters:

  • limit (number, optional): Maximum number of results (default: 50)

Returns: File type distribution with counts and total sizes per extension.

Response Format

All tools return results in a consistent format:

{
  "columns": ["column1", "column2", ...],
  "rows": [
    ["value1", "value2", ...],
    ...
  ],
  "rowCount": 10,
  "data": [...]
}

Development

Project Structure

src/
  ├── index.ts              # Main MCP server
  ├── database.ts           # Database connection and utilities
  ├── tools/
  │   ├── registry.ts       # Tool registry
  │   ├── fileSystem.ts     # File system tools
  │   ├── processes.ts      # Process analysis tools
  │   ├── users.ts          # User activity tools
  │   ├── events.ts         # Event log tools
  │   └── other.ts          # Other tools (network, devices, etc.)

Adding New Tools

  1. Add tool definition to appropriate category file in src/tools/
  2. Implement executor function in the same file
  3. Register the category in src/tools/registry.ts

Example:

// In src/tools/fileSystem.ts
export function createFileSystemTools(db: CyberTriageDatabase): Tool[] {
  return [
    {
      name: 'my_new_tool',
      description: 'Description of what the tool does',
      inputSchema: {
        type: 'object',
        properties: {
          param1: { type: 'string', description: 'Parameter description' }
        },
        required: ['param1']
      }
    }
  ];
}

export async function executeFileSystemTool(
  name: string,
  args: any,
  db: CyberTriageDatabase
): Promise<any> {
  switch (name) {
    case 'my_new_tool': {
      const { param1 } = args;
      const sql = `SELECT * FROM table WHERE column = ?`;
      return db.query(sql, [param1]);
    }
    // ... other cases
  }
}

License

MIT

Support

For issues or questions, please refer to the CyberTriage documentation or create an issue in the repository.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages