Yara File Analysis

Runs Yara-X rules against uploaded files, or custom data, to detect malware, analyze suspicious patterns, and identify threats. Supports both community rules and custom user-provided rules for comprehensive file analysis. This endpoint creates background jobs for processing files asynchronously.

Yara File Analysis

Runs Yara-X rules against uploaded files, or custom data, to detect malware, analyze suspicious patterns, and identify threats. Supports both community rules and custom user-provided rules for comprehensive file analysis. This endpoint creates background jobs for processing files asynchronously.

API Endpoint

POST /analysis/yara/file

HTTP Headers

  • Content-Type: application/json
  • X-Cursed-Api-Token: API token for authentication
  • X-Cursed-Api-Enc-Key: Encryption key for authenticated users (required if using encrypted files)

Request Method

POST

Parameters

Request Body (JSON):

ParameterTypeRequiredDescription
file_idsarrayYesArray of file UUIDs to analyze (100 files maximum limit and up to 250 MB total)
operationstringYesAnalysis operation ("run_rule" or "run_community_rules")
rulestringConditionalBase64-encoded Yara rule (required if operation is "run_rule")

Request Body Schema

{
  "file_ids": ["string (UUID)", "string (UUID)", ...],
  "operation": "string (run_rule|run_community_rules)",
  "rule": "string (base64-encoded, optional)"
}

Response Format

Success Response (200 OK):

{
  "id": "string (UUID)",
  "job_name": "string",
  "message": "Job created successfully",
  "category": "Yara"
}

Response Schema

FieldTypeDescription
idstring (UUID)Unique job identifier for tracking progress
job_namestringAuto-generated memorable job name
messagestringConfirmation message
categorystringAlways "Yara" for Yara analysis jobs

Job Results Format

Once the job completes, results can be retrieved using the job status endpoint (/analysis/job/{id}). The results follow the same format as the data endpoint:

{
  "id": "job_uuid",
  "job_name": "Creative Job Name",
  "status": "Completed",
  "insights": [
    {
      "Table": {
        "title": "Yara Analysis Results",
        "data": [
          ["File", "Rule", "Description", "Author"],
          ["malware_sample.exe", "APT_Malware_Family", "Detects APT malware family signatures", "Malware Research Team"]
        ],
        "category": "Yara"
      }
    },
    {
      "Metadata": {
        "title": "Rule metadata", 
        "data": {
          "warnings": "compiler warning messages if any",
          "custom_rule": "rule content for custom rules"
        },
        "category": "Yara"
      }
    }
  ]
}

Error Response (400 Bad Request):

{
  "error": "No file IDs provided"
}

{
  "error": "Max File analysis size limit exceeded (250MB)"
}

{
  "error": "Failed to download file"
}

Error Response (401 Unauthorized):

{
  "error": "Unauthorized"
}

Error Codes

HTTP StatusDescription
200Success - Analysis job queued
400Bad Request - Invalid parameters or file limit exceeded
401Unauthorized - Missing authentication for private files
413Payload Too Large - Files exceed 250MB total size limit
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server processing error

Operation Types

OperationDescription
run_ruleRun a custom Yara rule provided in the request
run_community_rulesRun the built-in community Yara rules

Example cURL Commands

Run Community Rules

curl -X POST https://api.cursed.tools/analysis/yara/file \
  -H "Content-Type: application/json" \
  -H "X-Cursed-Api-Token: your_api_token" \
  -H "X-Cursed-Api-Enc-Key: your_encryption_key" \
  -d '{
    "file_ids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "a72a10f9-b8b3-4ba5-bd15-9418a37a3202"
    ],
    "operation": "run_community_rules"
  }'

Run Custom Rule

curl -X POST https://api.cursed.tools/analysis/yara/file \
  -H "Content-Type: application/json" \
  -H "X-Cursed-Api-Token: your_api_token" \
  -H "X-Cursed-Api-Enc-Key: your_encryption_key" \
  -d '{
    "file_ids": ["123e4567-e89b-12d3-a456-426614174000"],
    "operation": "run_rule",
    "rule": "cnVsZSBNYWx3YXJlRGV0ZWN0aW9uCnsKICAgIG1ldGE6CiAgICAgICAgZGVzY3JpcHRpb24gPSAiRGV0ZWN0cyBtYWx3YXJlIHBhdHRlcm5zIgogICAgICAgIGF1dGhvciA9ICJTZWN1cml0eSBUZWFtIgogICAgICAgIGRhdGUgPSAiMjAyNC0wMS0wMSIKICAgICAgICAKICAgIHN0cmluZ3M6CiAgICAgICAgJG1hbHdhcmVfc3RyaW5nID0gIm1hbGljaW91cyIgbm9jYXNlCiAgICAgICAgJGhleFBhdHRlcm4gPSB7IDREIDVBIDkwIDAwIH0KICAgICAgICAKICAgIGNvbmRpdGlvbjoKICAgICAgICAkaGV4UGF0dGVybiBhdCAwIGFuZCAkbWFsd2FyZV9zdHJpbmcKfQ=="
  }'

Example Response

{
  "id": "987e6543-e89b-12d3-a456-426614174000",
  "job_name": "Malware Hunter Analysis",
  "message": "Job created successfully", 
  "category": "Yara"
}

Job Tracking

After receiving the job ID, track progress using:

curl -X GET https://api.cursed.tools/analysis/job/987e6543-e89b-12d3-a456-426614174000 \
  -H "X-Cursed-Api-Token: your_api_token"

Job statuses:

  • Pending - Job queued, waiting to start
  • Processing - Analysis in progress
  • Completed - Analysis finished successfully
  • Failed - Analysis encountered an error

File Type Support

Yara rules can analyze any file type including:

  • Executables: .exe, .dll, .sys, .scr
  • Archives: .zip, .rar, .7z, .tar, .gz
  • Documents: .pdf, .doc, .docx, .xls, .xlsx, .ppt
  • Scripts: .js, .vbs, .ps1, .py, .bat, .cmd
  • Images: .png, .jpg, .gif, .bmp, .ico
  • Binary Files: Any binary or text format
  • Memory Dumps: Raw memory captures
  • Network Captures: .pcap, .pcapng files

Example Yara Rule Format

rule SuspiciousExecutable
{
    meta:
        description = "Detects suspicious executable patterns"
        author = "Security Team"
        date = "2024-01-01"
        severity = "high"
        
    strings:
        $mz_header = { 4D 5A }
        $suspicious_api1 = "CreateRemoteThread" ascii
        $suspicious_api2 = "WriteProcessMemory" ascii
        $malware_string = "malware" nocase
        
    condition:
        $mz_header at 0 and
        any of ($suspicious_api*) and
        $malware_string
}

Notes

  • Maximum of 100 files can be analyzed in a single request
  • Total file size limit is 250MB across all files
  • Job results can be retrieved using the job status endpoint (/analysis/job/{id})
  • Authentication is required for private/encrypted files
  • Community rules include signatures for malware families, APTs, and suspicious patterns
  • Custom rules must be valid Yara format and base64-encoded
  • Job names are auto-generated using creative memorable combinations
  • Priority is determined by user subscription level
  • Unauthenticated users can analyze public files only
  • The analysis creates a background job that processes files asynchronously
  • Supports all Yara-X features including imports, modules, and advanced conditions
  • Results include rule matches, metadata, and file analysis details
  • Jobs may include compiler warnings in Metadata objects for custom rules
  • Polling the job status endpoint is recommended for real-time updates
  • Completed jobs retain results for retrieval and can be shared via job URLs

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 Rules Retrieval

Retrieves specific Yara rules from the community rule set by name. Allows users to fetch one or multiple rules for inspection, customization or context enrichment. This API endpoint is supplemental and performs lookups for rules that matched when the user desires to see more context on top of the rule metadata.