Yara Data Analysis

Runs Yara-X rules against user-provided test data in real-time. Supports both custom rules and community rules for malware detection and file analysis rule validation.

Yara Data Analysis

Runs Yara-X rules against user-provided test data in real-time. Supports both custom rules and community rules for malware detection and file analysis rule validation.

API Endpoint

POST /analysis/yara/data

HTTP Headers

  • Content-Type: application/json
  • X-Cursed-Api-Token: API token for authentication

Request Method

POST

Parameters

Request Body (JSON):

ParameterTypeRequiredDescription
test_datastringYesBase64-encoded test data (any format - binary, text, etc.)
operationstringYesAnalysis operation ("run_rule" or "run_community_rules")
rulestringConditionalBase64-encoded Yara rule (required if operation is "run_rule")

Request Body Schema

{
  "test_data": "string (base64-encoded)",
  "operation": "string (run_rule|run_community_rules)",
  "rule": "string (base64-encoded, conditional)"
}

Response Format

Success Response (200 OK):

{
  "results": [
    {
      "Table": {
        "title": "string",
        "data": [["array", "of", "strings"]],
        "category": "Yara"
      }
    },
    {
      "Metadata": {
        "title": "string", 
        "data": {
          "warnings": "string with compiler warnings",
          "custom_rule": "string with rule content"
        },
        "category": "Yara"
      }
    },
    {
      "Error": {
        "message": "string"
      }
    }
  ]
}

Response Types

Table Result for Community Rules

{
  "results": [
    {
      "Table": {
        "title": "Yara Community Rules",
        "data": [
          ["File", "Rule", "Description", "Author", "Tags"],
          ["Custom Data", "APT_Equation_Malware", "Detects Equation Group malware", "Florian Roth", "apt,equation,malware"],
          ["Custom Data", "Trojan_Generic", "Generic trojan detection rule", "Security Team", "trojan,malware"]
        ],
        "category": "Yara"
      }
    }
  ]
}

Table Result for Custom Rule with Warnings

{
  "results": [
    {
      "Table": {
        "title": "Yara Analysis Results",
        "data": [
          ["File", "Rule"],
          ["Custom Data", "SuspiciousExecutable"]
        ],
        "category": "Yara"
      }
    },
    {
      "Metadata": {
        "title": "Rule metadata",
        "data": {
          "warnings": "warning[text_as_hex]: hex pattern could be written as text literal\n  --> line:12:9\n   |\n12 |         $hex_pattern = { 4D 5A }\n   |         ----------------------\n   |         |\n   |         this pattern can be written as a text literal\n   |         help: replace with \"MZ\"\n   |",
          "custom_rule": "rule SuspiciousExecutable\n{\n    meta:\n        description = \"Detects suspicious executable patterns\"\n        author = \"Cursed Tools\"\n        date = \"2024-01-01\"\n        \n    strings:\n        $suspicious_string1 = \"malware\" nocase\n        $suspicious_string2 = \"backdoor\" nocase\n        $api_call = \"CreateRemoteThread\"\n        $hex_pattern = { 4D 5A 90 00 }\n        \n    condition:\n        $hex_pattern at 0 and \n        any of ($suspicious_string*, $api_call)\n}"
        },
        "category": "Yara"
      }
    }
  ]
}

Error Result

{
  "results": [
    {
      "Error": {
        "message": "The file was either corrupted or exceeded the maximum permitted size"
      }
    }
  ]
}

No Matches Result

{
  "results": [
    {
      "message": "No matches found for the provided test data"
    }
  ]
}

Error Response (400 Bad Request):

Invalid test data format

Error Response (401 Unauthorized):

Unauthorized

Error Response (422 Unprocessable Entity):

Rule is required

Error Codes

HTTP StatusDescription
200Success - Analysis completed
400Bad Request - Invalid test data format
401Unauthorized - Authentication required
422Unprocessable Entity - Missing or invalid rule
500Internal Server Error - Server processing error

Operation Types

OperationDescription
run_ruleRun a custom Yara rule against the test data
run_community_rulesRun all community Yara rules against the test data

Example cURL Commands

Run Custom Rule

curl -X POST https://api.cursed.tools/analysis/yara/data \
  -H "Content-Type: application/json" \
  -H "X-Cursed-Api-Token: your_api_token" \
  -d '{
    "test_data": "TVoQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "operation": "run_rule",
    "rule": "cnVsZSBTdXNwaWNpb3VzRXhlY3V0YWJsZQp7CiAgICBtZXRhOgogICAgICAgIGRlc2NyaXB0aW9uID0gIkRldGVjdHMgc3VzcGljaW91cyBleGVjdXRhYmxlIHBhdHRlcm5zIgogICAgICAgIGF1dGhvcgkgPSAiQ3Vyc2VkIFRvb2xzIgogICAgICAgIGRhdGUgPSAiMjAyNS0wMS0wMSIKICAgICAgICAKICAgIHN0cmluZ3M6CiAgICAgICAgJHN1c3BpY2lvdXNfc3RyaW5nMSA9ICJtYWx3YXJlIiBub2Nhc2UKICAgICAgICAkc3VzcGljaW91c19zdHJpbmcyID0gImJhY2tkb29yIiBub2Nhc2UKICAgICAgICAkYXBpX2NhbGwgPSAiQ3JlYXRlUmVtb3RlVGhyZWFkIgogICAgICAgICRoZXhfcGF0dGVybiA9IHsgNEQgNUEgOTAgMDAgfQogICAgICAgICAgICAKICAgIGNvbmRpdGlvbjoKICAgICAgICAkaGV4X3BhdHRlcm4gYXQgMCBhbmQgCiAgICAgICAgYW55IG9mICgkc3VzcGljaW91c19zdHJpbmcqLCAkYXBpX2NhbGwpCn0="
  }'

Run Community Rules

curl -X POST https://api.cursed.tools/analysis/yara/data \
  -H "Content-Type: application/json" \
  -H "X-Cursed-Api-Token: your_api_token" \
  -d '{
    "test_data": "TVoQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "operation": "run_community_rules"
  }'

Example Test Data Format

* IMPORTANT: Yara rules can analyze any type of data - binary files, text files, memory dumps, network packets, etc. All data should be base64-encoded before sending.

Binary Data (Base64 encode it)

MZ\x90\x00This is a sample file content that might contain malware signatures.
The file includes suspicious API calls like CreateRemoteThread and other indicators.
This text is used for testing Yara rules against various patterns and signatures.

Some hex patterns might be present: 4D5A9000
And some strings that could trigger rules: malware, backdoor, virus, trojan

Text Data (Base64 encode it)

This is sample text content for analysis.
It may contain suspicious strings like:
- Registry modifications
- Network connections  
- File system operations
- Process injection techniques

API calls: CreateProcess, WriteProcessMemory, VirtualAllocEx
File paths: C:\Windows\System32\malware.exe

Hexadecimal Data (Base64 encode it)

4D5A90000300000004000000FFFF0000B800000000000000400000000000000000000000

Example Response (with Community Rules)

{
  "results": [
    {
      "Table": {
        "title": "Yara Community Rules Analysis",
        "data": [
          ["Rule", "Description", "Author", "Tags", "Severity"],
          ["apt_malware_family", "APT malware family detection", "@MalwareResearcher", "apt, malware, trojan", "high"],
          ["suspicious_api_calls", "Detects suspicious API call patterns", "@SecurityTeam", "api, injection, persistence", "medium"]
        ],
        "category": "Yara"
      }
    }
  ]
}

Compiler Warnings

When using custom rules, Yara-X may return compiler warnings in a Metadata object:

{
  "Metadata": {
    "title": "Rule metadata",
    "data": {
      "warnings": "warning[text_as_hex]: hex pattern could be written as text literal\n  --> line:12:9\n   |\n12 |         $hex_pattern = { 4D 5A }\n   |         ----------------------\n   |         |\n   |         this pattern can be written as a text literal\n   |         help: replace with \"MZ\"\n   |"
    },
    "category": "Yara"
  }
}

Notes

  • Test data can be any format (binary, text, hex, etc.) and must be base64-encoded
  • Yara rules support pattern matching, string detection, and condition logic
  • Custom rules must be valid Yara format and base64-encoded
  • Results are returned immediately and no job is created
  • Authentication is optional but affects rate limiting and priority execution
  • Invalid rule formats will return descriptive error messages
  • The endpoint supports malware detection, file analysis, and threat hunting use cases
  • Supports all Yara-X features including metadata, string modifiers, extended modules (pe, elf, macho, math, hash, and other) and complex conditions
  • Compiler warnings are provided when rules have optimization suggestions
  • Both successful analysis and errors return unified response format with results array