Malware Intelligence Integration Guide

Overview

The Malware Intelligence integration (integration service: malware-intelligence) allows your NINA workflows to query and search the Zynap malware intelligence database. Unlike the Zynap Sandbox integration (malware-api) which focuses on submitting and analyzing samples, Malware Intelligence is a read-only interface for retrieving existing threat intelligence data, signatures, behavioral analysis, and performing advanced searches across the malware knowledge base.

This is an internal integration service designed for security teams to access Zynap's accumulated malware intelligence within automated workflows.

Status

The integration currently supports:

• Sample Lookup: Retrieve malware information by SHA256 hash (basic, detailed, and Zynap intelligence)
• Bulk Queries: Fetch Zynap intelligence for multiple hashes in a single request
• Signature Analysis: Access malware signatures and detection data
• Target Information: Retrieve behavioral and target data from dynamic analysis
• Listing Operations: List and filter malware samples, info, Zynap data, and signatures with pagination
• Advanced Search: Execute complex queries using MongoDB-style filters across dozens of threat indicators

Comparison with Zynap Sandbox

Feature	Malware Intelligence	Zynap Sandbox
Purpose	Query existing intelligence	Submit and analyze samples
Authentication	Client ID + Secret	No auth (network-level)
File Upload	No	Yes
Analysis Jobs	No	Yes
Read Operations	Full	Full
Write Operations	None	Upload, analyze
Identifier	malware-intelligence	malware-api

Credential Configuration

Authentication Method

The Malware Intelligence integration uses client credentials for authentication:

Field	Description	Required	Example
gRPC Address	gRPC server address for the Malware API	Yes	10.10.0.61:50051
Client ID	Client ID for authentication	Yes	—
Secret	Secret for authentication	Yes	—

How to obtain credentials:

1. Contact your organization's security team or platform administrator
2. Request client credentials for the Malware Intelligence API
3. Ensure network access to the internal gRPC service

Creating a Malware Intelligence Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Malware Intelligence Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Malware Intelligence"
   • gRPC Address: Enter the gRPC server address
   • Client ID: Your client ID
   • Secret: Your authentication secret
4. Click Test Connection to verify gRPC connectivity
5. Click Save to store the credential

Supported Resources and Operations

Malware

Operation	Description
Get Malware	Retrieve basic malware information by SHA256 hash
Get Malware Info	Retrieve detailed malware information and metadata
Get Malware Zynap	Retrieve Zynap-specific intelligence and analysis
Get Malware Zynap Bulk	Retrieve Zynap information for multiple samples in bulk
Get Malware Signatures	Retrieve signature information for a malware sample
Get Malware Target	Retrieve behavioral and target data from dynamic analysis
List Malware	List malware samples with filtering and pagination
List Malware Info	List detailed malware info with filtering and pagination
List Malware Zynap	List Zynap intelligence data with filtering and pagination
List Malware Signatures	List signature data with filtering and pagination
Malware Hunt	Search for malware using advanced filters (MongoDB query)

Parameter Merging

The Malware Intelligence integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Malware Intelligence Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

Example: Retrieving Malware Intelligence

Getting Basic Malware Information

{
  "resource": "malware",
  "operation": "getMalware",
  "parameters": {
    "sha256": "a1b2c3d4e5f6789abcdef1234567890abcdef1234567890abcdef1234567890ab"
  }
}

Getting Detailed Information

{
  "resource": "malware",
  "operation": "getMalwareInfo",
  "parameters": {
    "sha256": "{{hash_from_previous_node}}"
  }
}

Getting Zynap Intelligence

{
  "resource": "malware",
  "operation": "getMalwareZynap",
  "parameters": {
    "sha256": "{{hash_from_previous_node}}"
  }
}

Getting Signature Information

{
  "resource": "malware",
  "operation": "getMalwareSignatures",
  "parameters": {
    "sha256": "{{hash_from_previous_node}}"
  }
}

Getting Target/Behavioral Data

{
  "resource": "malware",
  "operation": "getMalwareTarget",
  "parameters": {
    "sha256": "{{hash_from_previous_node}}"
  }
}

Example: Bulk Intelligence Lookup

Fetch Zynap intelligence for multiple hashes in a single request:

{
  "resource": "malware",
  "operation": "getMalwareZynapBulk",
  "parameters": {
    "sha256_hashes": [
      "a1b2c3d4e5f6789abcdef1234567890abcdef1234567890abcdef1234567890ab",
      "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
      "invalid_hash_will_be_skipped"
    ]
  }
}

The response separates results into success, failed, and skipped arrays, allowing you to process large batches while handling errors gracefully.

Example: Listing Data with Pagination

Listing Malware Samples

{
  "resource": "malware",
  "operation": "listMalware",
  "parameters": {
    "filters": {
      "status_in": ["COMPLETED", "ANALYZED"],
      "sha256_in": ["a1b2c3d4..."]
    },
    "pagination": {
      "page_size": 50,
      "cursor": "eyJpZCI6IjEyMzQ1NiJ9"
    }
  }
}

Listing Zynap Intelligence

{
  "resource": "malware",
  "operation": "listMalwareZynap",
  "parameters": {
    "pagination": {
      "page_size": 25
    }
  }
}

Cursor-Based Pagination

All listing operations support cursor-based pagination. The first request omits the cursor; the response includes a cursor value to fetch the next page:

{
  "pagination": {
    "page_size": 50,
    "cursor": "eyJpZCI6IjEyMzQ1NiJ9"
  }
}

Example: Advanced Malware Hunt

The executeMalwareMongoQuery operation (named "Malware Hunt" in the schema) enables complex searches across dozens of threat indicators.

Basic Search

{
  "resource": "malware",
  "operation": "executeMalwareMongoQuery",
  "parameters": {
    "page_size": 100,
    "filters": {
      "confidence_min": 3,
      "severity_min": 4,
      "first_seen_from": "2025-01-01"
    }
  }
}

Complex Threat Hunt

{
  "resource": "malware",
  "operation": "executeMalwareMongoQuery",
  "parameters": {
    "page_size": 100,
    "filters": {
      "confidence_min": 3,
      "severity_min": 4,
      "first_seen_from": "2025-01-01",
      "ip_in": ["192.168.1.100", "10.0.0.50"],
      "domain_in": ["malicious.com", "evil.net"],
      "attack_pattern_id_in": ["T1055", "T1059"],
      "tag_in": ["APT29", "BANKING_TROJAN"],
      "process_name_in": ["powershell.exe", "cmd.exe"]
    }
  }
}

Available Filters

Basic Filters

• sha256_in: Array of SHA256 hashes
• confidence_min / confidence_max: Confidence level range (1-5)
• severity_min / severity_max: Severity level range (0-5)
• first_seen_from / first_seen_to: Date range (ISO 8601 format)

Network Indicators

• ip_in: IP addresses
• url_in: URLs
• domain_in: Domains
• email_in: Email addresses

Process and System Indicators

• process_name_in: Process names
• mutex_in: Mutex names

Certificate Information

• certificates_serial_number_in: Certificate serial numbers
• certificates_md5_in / certificates_sha1_in / certificates_sha256_in: Certificate hashes
• certificates_subject_email_in: Certificate subject emails
• certificates_subject_common_name_in: Certificate common names
• certificates_subject_postal_code_in: Certificate postal codes
• certificates_subject_country_in: Certificate countries

Metadata Filters

• metadata_ssdeep_original_in: SSDEEP hashes
• metadata_crc32_original_in: CRC32 checksums
• metadata_pe_imphash_in: PE import hashes

Threat Intelligence

• attack_pattern_id_in: MITRE ATT&CK pattern IDs
• tag_in: Threat tags (must be uppercase)
• snort_sid_in: Snort signature IDs

Crime Server Data

• crimeservers_c2_in: Command and control servers
• crimeservers_binary_downloads_in: Binary download URLs
• crimeservers_proxies_in: Proxy servers
• malware_config_in: Malware configuration data

Filter Behavior

• Omitted filter and empty array: silently ignored — the filter is not applied.
• Multiple filters: combined with AND logic — a record must match all specified filters.
• String array fields (domain_in, ip_in, etc.): require exact matches, not partial.

Example: Workflow — Enrich IOCs with Intelligence

A common pattern is to take indicators of compromise from an upstream node and enrich them with Zynap intelligence:

Step 1: Extract hashes from upstream node

Input data from a previous node:

{
  "indicators": {
    "sha256_hashes": [
      "a1b2c3d4e5f6789abcdef1234567890abcdef1234567890abcdef1234567890ab",
      "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
    ]
  }
}

Step 2: Bulk lookup

{
  "resource": "malware",
  "operation": "getMalwareZynapBulk",
  "parameters": {
    "sha256_hashes": "{{indicators.sha256_hashes}}"
  }
}

Step 3: Use enriched data in downstream nodes

The enriched intelligence data (classifications, severity, confidence, signatures) is available to all downstream nodes in the workflow.

Troubleshooting

Common Issues

Issue	Resolution
gRPC connection refused	Verify the gRPC address is correct and the service is reachable from your network. Check with your administrator.
Authentication failed	Double-check the Client ID and Secret. Credentials may have been rotated.
Empty results	Verify the SHA256 hash is correct (64 hex characters). The sample may not exist in the intelligence database.
Timeout on large queries	Reduce page_size or add more specific filters to narrow the result set.
Bulk lookup partial failures	Expected behavior — the response separates results into success/failed/skipped arrays. Check the failed array for details.

Best Practices

1. Use Bulk Operations: When looking up multiple hashes, use getMalwareZynapBulk rather than individual lookups for better performance.

2. Filter Strategically: Use specific filters in Malware Hunt queries to reduce result sets. String array fields require exact matches.

3. Paginate Large Results: Use cursor-based pagination for listing operations. Start without a cursor, then use the returned cursor for subsequent pages.

4. Validate Hashes: Ensure SHA256 hashes are valid 64-character hex strings before querying. Invalid hashes in bulk operations are skipped silently.

5. Leverage Template Variables: Use {{variable_name}} syntax to dynamically pass values from upstream nodes.

6. Choose the Right Integration: Use Malware Intelligence for querying existing data; use Zynap Sandbox (malware-api) when you need to submit samples for analysis.

7. Cache Results: Store intelligence results locally within your workflow to avoid redundant lookups of the same hashes.

8. Use Tags in Uppercase: The tag_in filter requires uppercase values (e.g., APT29, not apt29).

Updated: 2026-04-16