YARA Scanner MCP Server

MCP server wrapping YARA for malware detection, pattern matching, and security analysis. Provides comprehensive tools for scanning files, directories, and processes with YARA rules.

Features

• File Scanning: Scan individual files with custom or built-in YARA rules
• Directory Scanning: Recursively scan directories with file extension filtering
• Process Scanning: Scan running process memory (requires root)
• Rule Management: Compile, validate, and generate YARA rules
• Built-in Rulesets: Use curated rulesets for malware, webshells, exploits, and more
• Security: Path validation, rule content validation, sandboxed execution

Prerequisites

Required

• YARA CLI: Install the YARA command-line tool

  # macOS
  brew install yara
  
  # Ubuntu/Debian
  sudo apt-get install yara
  
  # From source
  git clone https://github.com/VirusTotal/yara.git
  cd yara
  ./bootstrap.sh
  ./configure
  make
  sudo make install

Optional

• Built-in Rulesets: For yara_scan_with_builtin tool

  • Set YARA_RULES_PATH environment variable, or
  • Install rules to /opt/yara-rules/
  • Recommended: Awesome YARA rules

  # Example: Install common rulesets
  sudo mkdir -p /opt/yara-rules
  cd /opt/yara-rules
  
  # Download popular rule repositories
  git clone https://github.com/Yara-Rules/rules.git yara-rules-repo
  
  # Organize by category
  cp yara-rules-repo/malware/*.yar malware.yar
  cp yara-rules-repo/webshells/*.yar webshell.yar
  # ... etc

Installation

cd yara-scanner
bun install
bun run build

Configuration

Add to your MCP settings file:

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yara-scanner": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/yara-scanner/src/index.ts"],
      "env": {
        "YARA_RULES_PATH": "/opt/yara-rules"
      }
    }
  }
}

Environment Variables

• YARA_RULES_PATH: Base directory for built-in rulesets (default: /opt/yara-rules)

Tools

yara_scan_file

Scan a single file with YARA rules.

Parameters:

• file_path (required): Absolute path to file to scan
• rule_path (optional): Path to YARA rule file (.yar/.yara)
• rule_content (optional): YARA rule content (alternative to rule_path)
• timeout (optional): Maximum scan duration in seconds (default: 60, max: 300)

Note: Must provide either rule_path or rule_content, not both.

Example:

{
  "file_path": "/home/user/suspicious.exe",
  "rule_path": "/opt/yara-rules/malware.yar",
  "timeout": 60
}

Returns:

{
  "file": "/home/user/suspicious.exe",
  "matches": [
    {
      "rule": "Win32_Trojan_Generic",
      "tags": ["trojan", "win32"],
      "strings": [
        {
          "offset": "0x1234",
          "identifier": "$suspicious_string",
          "data": "malicious payload"
        }
      ]
    }
  ],
  "match_count": 1
}

yara_scan_directory

Scan a directory (optionally recursive) with YARA rules.

Parameters:

• dir_path (required): Absolute path to directory to scan
• rule_path (optional): Path to YARA rule file
• rule_content (optional): YARA rule content
• recursive (optional): Scan directories recursively (default: false)
• file_extensions (optional): Filter by file extensions (e.g., [".exe", ".dll"])
• timeout (optional): Maximum scan duration in seconds (default: 60)

Example:

{
  "dir_path": "/var/www/html",
  "rule_path": "/opt/yara-rules/webshell.yar",
  "recursive": true,
  "file_extensions": [".php", ".jsp", ".asp"]
}

Returns:

{
  "directory": "/var/www/html",
  "files_scanned": 42,
  "matches": [
    {
      "file": "/var/www/html/upload/shell.php",
      "rule": "PHP_Webshell",
      "tags": ["webshell", "php"],
      "strings": [...]
    }
  ],
  "total_matches": 1
}

yara_scan_process

Scan a running process memory with YARA rules. Requires root privileges.

Parameters:

• pid (required): Process ID to scan (positive integer)
• rule_path (optional): Path to YARA rule file
• rule_content (optional): YARA rule content
• timeout (optional): Maximum scan duration in seconds (default: 60)

Example:

{
  "pid": 1234,
  "rule_content": "rule suspicious { strings: $a = \"malware\" condition: $a }"
}

Returns:

{
  "pid": 1234,
  "matches": [
    {
      "rule": "suspicious",
      "tags": [],
      "strings": [...]
    }
  ],
  "match_count": 1
}

yara_compile_rules

Compile and validate YARA rules without executing a scan.

Parameters:

• rule_content (required): YARA rule content to validate (max 500KB)

Example:

{
  "rule_content": "rule test { strings: $a = \"test\" condition: $a }"
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": []
}

yara_rule_info

Extract metadata and information from a YARA rule file.

Parameters:

• rule_path (required): Path to YARA rule file

Example:

{
  "rule_path": "/opt/yara-rules/malware.yar"
}

Returns:

{
  "rules": [
    {
      "name": "Win32_Trojan_Generic",
      "tags": ["trojan", "win32"],
      "meta": {
        "author": "Security Researcher",
        "description": "Generic trojan detection",
        "date": "2024-01-01"
      },
      "strings_count": 5,
      "condition": "3 of them"
    }
  ],
  "total_rules": 1
}

yara_generate_rule

Generate a YARA rule from components and validate by compiling.

Parameters:

• name (required): Rule name
• strings (required): Array of string definitions
  • identifier: String identifier (e.g., "$s1")
  • value: String value or hex pattern
  • type: "text", "hex", or "regex" (default: "text")
• condition (optional): YARA condition expression (default: "any of them")
• tags (optional): Array of rule tags
• meta (optional): Metadata key-value pairs

Example:

{
  "name": "Custom_Malware_Detector",
  "tags": ["malware", "custom"],
  "meta": {
    "author": "Security Team",
    "description": "Detects custom malware variant"
  },
  "strings": [
    {
      "identifier": "$s1",
      "value": "malicious string",
      "type": "text"
    },
    {
      "identifier": "$hex1",
      "value": "6D 61 6C 77 61 72 65",
      "type": "hex"
    }
  ],
  "condition": "all of them"
}

Returns:

{
  "rule_content": "rule Custom_Malware_Detector : malware custom\n{\n    meta:\n        author = \"Security Team\"\n        description = \"Detects custom malware variant\"\n    strings:\n        $s1 = \"malicious string\"\n        $hex1 = { 6D 61 6C 77 61 72 65 }\n    condition:\n        all of them\n}",
  "valid": true,
  "compilation_errors": []
}

yara_scan_with_builtin

Scan a file using curated built-in YARA rulesets.

Parameters:

• file_path (required): Absolute path to file to scan
• ruleset (required): Built-in ruleset category
  • malware: General malware detection
  • suspicious: Suspicious patterns and behaviors
  • crypto: Cryptographic algorithms and ransomware
  • webshell: Web shell detection
  • exploit: Exploit code patterns
  • packer: Executable packers
  • ransomware: Ransomware-specific signatures
• timeout (optional): Maximum scan duration in seconds (default: 60)

Example:

{
  "file_path": "/home/user/suspicious.exe",
  "ruleset": "malware",
  "timeout": 120
}

Returns:

{
  "file": "/home/user/suspicious.exe",
  "ruleset": "malware",
  "matches": [
    {
      "rule": "Generic_Malware",
      "tags": ["malware"],
      "strings": [...]
    }
  ],
  "match_count": 1
}

Security Features

Path Validation

• All paths must be absolute
• No path traversal (..) allowed
• No null bytes in paths
• Access to /proc, /sys, /dev is blocked

Rule Content Validation

• Maximum rule size: 500KB
• Must contain at least one rule definition
• Only safe YARA modules allowed:
  • Allowed: pe, elf, math, hash, console, time, string
  • Blocked: cuckoo, dotnet, and other potentially dangerous modules

Process Scanning

• Requires root privileges (UID 0)
• Process ID must be positive integer
• Validates process exists before scanning

Execution Safety

• Command timeout enforcement (10-300 seconds)
• SIGKILL safety timer (timeout + 5 seconds)
• Maximum output buffer: 10MB
• Temporary files cleaned up automatically

Example YARA Rules

Simple Text Match

rule Simple_Text_Match {
    strings:
        $text = "malicious"
    condition:
        $text
}

Hex Pattern Match

rule Hex_Pattern {
    strings:
        $hex = { 4D 5A 90 00 }  // PE header
    condition:
        $hex at 0
}

Complex Rule with Metadata

rule Advanced_Detection {
    meta:
        author = "Security Team"
        description = "Detects advanced threat"
        severity = "high"

    strings:
        $s1 = "suspicious_function" ascii wide
        $s2 = /http:\/\/[a-z]+\.evil\.com/
        $hex1 = { E8 [4] 83 C4 ?? }

    condition:
        2 of them and filesize < 1MB
}

Using PE Module

import "pe"

rule PE_Characteristics {
    condition:
        pe.is_pe and
        pe.number_of_sections > 5 and
        pe.imports("kernel32.dll", "CreateRemoteThread")
}

Troubleshooting

YARA not found

Error: spawn yara ENOENT

Solution: Install YARA CLI and ensure it's in your PATH.

Permission denied (process scanning)

Error: Process scanning requires root privileges

Solution: Run with sudo or as root user.

Built-in ruleset not found

Error: Failed to scan with built-in ruleset 'malware'

Solution: Set YARA_RULES_PATH environment variable or install rules to /opt/yara-rules/.

Rule compilation errors

{
  "valid": false,
  "errors": ["syntax error, unexpected $end"],
  "warnings": []
}

Solution: Check YARA rule syntax. Use yara_compile_rules to debug.

Dangerous module import blocked

Error: Dangerous module import detected: "cuckoo"

Solution: Remove unsafe module imports or use only allowed modules (pe, elf, math, hash, console, time, string).

Performance Tips

1. Use specific rules: More specific rules = faster scanning
2. Set appropriate timeouts: Large files may need longer timeouts
3. Filter by extension: When scanning directories, use file_extensions filter
4. Avoid deep recursion: Deep directory trees can be slow
5. Optimize rule conditions: Simple conditions are faster than complex ones

Best Practices

1. Test rules first: Use yara_compile_rules to validate before scanning
2. Use metadata: Add author, description, date to rules
3. Tag appropriately: Use tags for categorization (malware, trojan, ransomware, etc.)
4. Start specific: Scan individual files before scanning directories
5. Monitor performance: Use appropriate timeouts for large scans
6. Keep rules updated: Regularly update built-in rulesets
7. Document custom rules: Use metadata fields for documentation

Use Cases

• Malware Detection: Scan files for known malware signatures
• Incident Response: Scan compromised systems for IOCs
• Threat Hunting: Search for suspicious patterns across filesystems
• Web Security: Detect webshells in web application directories
• Memory Forensics: Scan running processes for malicious code
• File Analysis: Analyze unknown files with custom rules
• Automated Scanning: Integrate with CI/CD for security scanning

License

MIT

References

• YARA Official Documentation
• YARA GitHub Repository
• Awesome YARA Rules
• YARA Rule Writing Guide