Malware Samples API

The Malware Samples API provides secure access to malware analysis capabilities, sample management, and detection metrics through Cognix's malware analysis infrastructure.

---

Getting Started

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Please contact support at cognix.au/contact-us to obtain an API key.

---

API Reference

1. Sample Submission API

Submit malware samples for analysis.

Endpoint: POST https://api.cognix.au/v1/malware/submit

Request Body

{
  "file": "base64_encoded_file_content",
  "file_name": "suspicious_file.exe",
  "analysis_type": "full",
  "options": {
    "sandbox_analysis": true,
    "static_analysis": true,
    "network_analysis": true
  }
}

Example Response

{
  "status": "success",
  "data": {
    "sample_id": "sample_123",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "submission_time": "2024-01-31T15:45:00Z",
    "analysis_status": "in_progress",
    "estimated_completion": "2024-01-31T16:00:00Z"
  }
}

---

2. Sample Retrieval API

Retrieve information about specific malware samples.

Endpoint: GET https://api.cognix.au/v1/malware/sample/{sample_id}

Query Parameters

Parameter	Type	Required	Description
sample_id	string	Yes	Unique sample identifier
fields	string	No	Specific fields to retrieve

Example Response

{
  "status": "success",
  "data": {
    "sample_details": {
      "sample_id": "sample_123",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "file_type": "PE32 executable",
      "file_size": 256000,
      "first_seen": "2024-01-31T15:45:00Z",
      "last_analyzed": "2024-01-31T16:00:00Z"
    },
    "analysis_summary": {
      "malware_family": "ransomware",
      "threat_level": "high",
      "detection_ratio": "45/60",
      "capabilities": [
        "file_encryption",
        "persistence",
        "network_communication"
      ]
    }
  }
}

---

3. Analysis Results API

Retrieve detailed analysis results for a sample.

Endpoint: GET https://api.cognix.au/v1/malware/analysis/{sample_id}

Query Parameters

Parameter	Type	Required	Description
sample_id	string	Yes	Unique sample identifier
type	string	No	Analysis type (static, dynamic, network)

Example Response

{
  "status": "success",
  "data": {
    "static_analysis": {
      "file_properties": {
        "compiler": "Microsoft Visual C++ 8.0",
        "compilation_timestamp": "2024-01-15T10:30:00Z",
        "entry_point": "0x1000"
      },
      "imports": [
        {
          "dll": "kernel32.dll",
          "functions": ["CreateFile", "WriteFile"]
        }
      ],
      "strings": [
        {
          "value": "suspicious_command",
          "type": "ascii",
          "offset": "0x1234"
        }
      ]
    },
    "dynamic_analysis": {
      "behaviors": [
        {
          "category": "file_operations",
          "actions": [
            "Creates files in system directory",
            "Modifies registry keys"
          ]
        }
      ],
      "network_activity": [
        {
          "protocol": "http",
          "destination": "malicious.example.com",
          "port": 80
        }
      ]
    }
  }
}

---

4. Sample Search API

Search for malware samples based on various criteria.

Endpoint: GET https://api.cognix.au/v1/malware/search

Query Parameters

Parameter	Type	Required	Description
hash	string	No	SHA256, SHA1, or MD5 hash
family	string	No	Malware family name
date_range	string	No	Date range format: YYYY-MM-DDtoYYYY-MM-DD
threat_level	string	No	Minimum threat level

Example Response

{
  "status": "success",
  "data": {
    "results": [
      {
        "sample_id": "sample_123",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "threat_level": "high",
        "malware_family": "ransomware",
        "first_seen": "2024-01-31T15:45:00Z",
        "detection_ratio": "45/60"
      }
    ],
    "total_matches": 150,
    "page": 1,
    "total_pages": 15
  }
}

---

Error Handling

Response Codes

Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Requested sample doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error occurred
503	Service Unavailable - Temporary server maintenance

Error Response Format

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context about the error",
      "suggestion": "Recommended action to resolve the error"
    }
  },
  "request_id": "unique-request-identifier"
}

Common Error Codes

Authentication Errors

Error Code	Description	Resolution
INVALID_API_KEY	The provided API key is not valid	Verify your API key in the Cognix dashboard
EXPIRED_API_KEY	The API key has expired	Generate a new API key
MISSING_API_KEY	No API key provided in the request	Include API key in Authorization header

Malware-Specific Errors

Error Code	Description	Resolution
INVALID_SAMPLE	Invalid sample format or corrupted file	Check file integrity
SAMPLE_NOT_FOUND	Requested sample ID doesn't exist	Verify sample ID
ANALYSIS_FAILED	Analysis process failed	Check sample and retry
FILE_TOO_LARGE	Sample exceeds size limit	Contact support for large files

Best Practices for Error Handling

1. Always check the status field in the response
2. Implement retry logic with exponential backoff for rate limits
3. Log the request_id for all errors
4. Monitor error rates to detect potential issues
5. Handle errors gracefully in your application

---