Recorded Future Integration Guide

Overview

The Recorded Future integration allows your NINA workflows to connect with Recorded Future's threat intelligence platform for comprehensive IOC enrichment and threat actor analysis. This integration enables you to enrich indicators of compromise (IOCs), search for threat actors, retrieve MITRE ATT&CK TTPs, and analyze targeting information directly from your security automation workflows.

Status

The integration currently supports comprehensive threat intelligence operations:

• IOC Enrichment: Enrich multiple IOC types simultaneously (IP addresses, domains, URLs, file hashes, vulnerabilities)
• Threat Actor Intelligence: Search for threat actors and retrieve detailed information
• MITRE ATT&CK Mapping: Retrieve TTPs (Tactics, Techniques, and Procedures) associated with threat actors
• Targeting Analysis: Identify targeted companies, organizations, and locations
• Entity Relationships: Discover relationships and links between entities

Advanced features include:

• Bulk Enrichment: Process up to 1000 IOCs in a single request across all types
• Multi-Type Support: Handle IPs, domains, URLs, hashes (MD5/SHA1/SHA256), and CVEs in one operation
• Risk Scoring: Access comprehensive risk scores and threat intelligence data
• Entity Linking: Retrieve relationships between threat actors, infrastructure, and targets
• Real-Time Intelligence: Access up-to-date threat intelligence from Recorded Future's extensive database

Credential Configuration

Before using the Recorded Future integration in your workflows, you need to configure credentials for authentication. The integration uses API key authentication with the Recorded Future API.

Authentication Method

The Recorded Future integration uses API key authentication:

Field	Description	Example
API Key	Your Recorded Future API key	your_api_key_here_32chars
Base URL	Recorded Future API base URL	https://api.recordedfuture.com

How to Get Your Recorded Future API Key

1. Log in to Recorded Future: Visit Recorded Future Portal and log in to your account
2. Navigate to User Settings: Click on your profile icon in the top-right corner
3. Access API Settings: Select User Settings → API Access
4. Generate or Retrieve Key: Copy your existing API key or generate a new one
5. Note Your Permissions: Verify your API key has access to the necessary endpoints (SOAR API, Threat Intelligence API)

API Access Levels:

• Standard API: Access to basic threat intelligence operations
• SOAR API: Enhanced access for security orchestration with enrichment endpoints
• Premium API: Full access to all threat intelligence features and higher rate limits

Important Notes:

• API keys are tied to your subscription level and feature access
• Monitor your API usage to stay within rate limits
• Keep your API key secure and rotate it regularly
• Some advanced features may require premium subscriptions

Creating a Recorded Future 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., "Recorded Future Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Recorded Future"
   • Auth Type: "API Key"
   • API Key: Paste your Recorded Future API key
   • Base URL: Enter the API base URL (default: https://api.recordedfuture.com)

4. Click Test Connection to verify credentials

5. Click Save to store the credential

Supported Resources and Operations

The Recorded Future integration supports the following resources and operations:

Enrichment

Operation	Name	Description
bulkEnrich	Bulk Enrich IOCs	Enrich multiple IOCs in a single request (max 1000 total across all types)

Supported IOC Types:

• IP Addresses: IPv4 and IPv6 addresses
• Domains: Domain names and subdomains
• URLs: Complete URLs including protocol and path
• File Hashes: MD5, SHA1, and SHA256 hashes
• Vulnerabilities: CVE identifiers (e.g., CVE-2021-44228)

Threat Actor

Operation	Name	Description
search	Search Threat Actors	Search for threat actors by name with flexible matching (exact, prefix, infix, relevance). Default limit: 10 results
getLinks	Get Entity Links	Retrieve links/relationships for entities
getTTPs	Get Threat Actor TTPs	Retrieve MITRE ATT&CK TTPs for a threat actor
getTargets	Get Threat Actor Targets	Retrieve targeting information (companies, locations) for a threat actor

Parameter Merging

The Recorded Future integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

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

When a Recorded Future Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the Recorded Future operation

Examples

Bulk IOC Enrichment

Enrich multiple IOCs of different types in a single request:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "enrichment",
  "operation": "bulkEnrich",
  "parameters": {
    "ip": ["8.8.8.8", "1.1.1.1"],
    "domain": ["example.com", "test-domain.net"],
    "vulnerability": ["CVE-2021-44228", "CVE-2023-23397"]
  }
}

This will enrich 2 IP addresses, 2 domains, and 2 CVEs in a single API call, returning comprehensive threat intelligence data including risk scores, detection rules, and contextual information.

Enrich Single IP Address

Enrich a single IP address by providing it in an array:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "enrichment",
  "operation": "bulkEnrich",
  "parameters": {
    "ip": ["203.0.113.45"]
  }
}

Enrich File Hashes

Enrich multiple file hashes (supports MD5, SHA1, SHA256):

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "enrichment",
  "operation": "bulkEnrich",
  "parameters": {
    "hash": [
      "44d88612fea8a8f36de82e1278abb02f",
      "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f"
    ]
  }
}

This example includes both an MD5 hash and a SHA256 hash for enrichment.

Enrich Mixed IOC Types

Combine different IOC types in one request:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "enrichment",
  "operation": "bulkEnrich",
  "parameters": {
    "ip": ["203.0.113.45"],
    "domain": ["suspicious-site.com"],
    "url": ["http://example.com/suspicious-path"],
    "hash": ["44d88612fea8a8f36de82e1278abb02f"],
    "vulnerability": ["CVE-2021-44228"]
  }
}

This enriches 5 different IOCs across all supported types in a single request.

Search for Threat Actors

Search for threat actors by name with flexible matching options:

Node Configuration (Basic Search):

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "search",
  "parameters": {
    "name": "APT29",
    "limit": 10,
    "offset": 0
  }
}

This searches for threat actors with "APT29" in their name, common names, or aliases (case-insensitive) and returns up to 10 results.

Advanced Search with Prefix Options

The prefix parameter allows you to control how the search matches threat actor names:

Prefix	Match Type	Description	Example
no-prefix	Freetext (default)	Matches anywhere in name, common name, or alias	"name": "panda" returns all actors with "panda" anywhere
exact	Exact match	Matches only exact name	"name": "APT41", "prefix": "exact" returns only "APT41"
prefix	Prefix match	Matches beginning of names	"name": "APT", "prefix": "prefix" returns APT1, APT29, etc.
infix	Infix match	Matches anywhere in names	"name": "bear", "prefix": "infix" finds actors with "bear"
relevance	Relevance match	Matches by text relevance	"name": "chinese espionage", "prefix": "relevance"

Example: Exact Match

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "search",
  "parameters": {
    "name": "APT41",
    "prefix": "exact",
    "limit": 10
  }
}

This returns only threat actors whose name exactly matches "APT41", filtering out partial matches like "APT410" or "Sub-APT41".

Example: Prefix Match

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "search",
  "parameters": {
    "name": "APT",
    "prefix": "prefix",
    "limit": 50
  }
}

This returns all threat actors whose name starts with "APT" (APT1, APT28, APT29, APT41, etc.).

Note: If no limit is specified, the default is 10 results to prevent returning thousands of matches. If no prefix is specified, it defaults to no-prefix (freetext match).

Get Threat Actor TTPs

Retrieve MITRE ATT&CK techniques used by a threat actor:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "getTTPs",
  "parameters": {
    "entityId": "abc123xyz"
  }
}

Note: The entityId is obtained from threat actor search results. Replace abc123xyz with the actual entity ID from your search.

Get Threat Actor Targets

Retrieve targeting information for a threat actor:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "getTargets",
  "parameters": {
    "entityId": "abc123xyz"
  }
}

This returns companies, organizations, and locations targeted by the specified threat actor.

Get Entity Links

Retrieve general relationships for entities:

Node Configuration:

{
  "integration_service": "recorded-future",
  "resource": "threatActor",
  "operation": "getLinks",
  "parameters": {
    "entities": ["abc123xyz"],
    "filters": {
      "entity_types": ["type:IpAddress", "type:InternetDomainName"],
      "sections": ["relatedMalware"]
    }
  }
}

This retrieves links between the threat actor and related IP addresses, domains, and malware.

Response Structure

Enrichment Response

IOC enrichment responses typically include:

• Entity Information: Type, value, and basic metadata
• Risk Score: Numerical risk score (0-99) indicating threat level
• Risk Rules: Specific detection rules triggered by this IOC
• Threat Links: Associated threat actors, malware families, and campaigns
• Evidence Summary: Evidence sources and observations
• Timestamps: First seen, last seen, and analysis dates
• Intelligence Cards: Contextual intelligence reports

Example risk score interpretation:

• 0-24: Low risk
• 25-64: Medium risk
• 65-89: High risk
• 90-99: Very high/critical risk

Threat Actor Response

Threat actor search results include:

• Entity ID: Unique identifier for the threat actor
• Name: Threat actor name and aliases
• Type: Entity type (e.g., ThreatActor)
• Attributes: Descriptions, motivations, and capabilities
• Links: Related entities and infrastructure
• Intelligence: Associated reports and analysis

Entity Links Response

Entity relationship queries return:

• Entities: Dictionary of linked entities with details
• Counts: Count of entities by type
• Sections: Categorized relationships (e.g., relatedMalware, attackedInfrastructure)
• Evidence: Supporting evidence for relationships

Best Practices

1. Batch Your Requests: Use bulkEnrich to process multiple IOCs in a single request rather than making individual calls. This is more efficient and reduces API quota usage.

2. Mix IOC Types Freely: Don't hesitate to combine different IOC types (IPs, domains, hashes, CVEs) in one bulkEnrich request. The API handles them all efficiently.

3. Respect the 1000 IOC Limit: The total number of IOCs across all arrays cannot exceed 1000 in a single request. Plan your batches accordingly.

4. Monitor Rate Limits: Track your API usage to avoid hitting rate limits. Implement exponential backoff for rate limit errors (HTTP 429).

5. Use Entity IDs Correctly: Threat actor entity IDs from search results are required for getTTPs and getTargets operations. Store these IDs from search results.

6. Use Appropriate Search Prefixes: When searching for threat actors, use the prefix parameter to get precise results:

   • Use exact when you know the exact threat actor name to avoid false positives
   • Use prefix to find all actors in a family (e.g., all APT groups)
   • Use relevance for multi-word searches or conceptual queries
   • The default no-prefix (freetext) returns the most results but may be less precise

7. Set Search Limits: Always specify a limit parameter for threat actor searches. Without it, the default is 10 results, which prevents accidentally returning thousands of matches.

8. Filter Entity Links: When using getLinks, apply filters to narrow down results to relevant entity types and sections to reduce response size.

9. Cache Enrichment Results: IOC enrichment data doesn't change frequently. Consider caching results for a reasonable time (e.g., 24 hours) to reduce API calls.

10. Handle Empty Results: Not all IOCs will have intelligence data. Handle cases where enrichment returns no results gracefully.

11. Parse Risk Scores: Use risk scores as initial indicators, but review detailed risk rules and evidence for accurate threat assessment.

12. Leverage Threat Intelligence: Combine IOC enrichment with threat actor intelligence to understand the broader threat landscape and attribution.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify API key is correct and active; check if key has required permissions
403 Forbidden	Ensure your subscription includes access to the SOAR API endpoints
404 Not Found	Verify the API endpoint path is correct; check Recorded Future API version
429 Too Many Requests	Rate limit exceeded; implement exponential backoff and reduce request frequency
Empty enrichment results	The IOC may not exist in Recorded Future's database; verify IOC format is correct
Invalid IOC format	Ensure IPs, domains, URLs, hashes, and CVEs are properly formatted
Entity ID not found	Verify the entity ID is correct; entity may have been removed or merged
Bulk request limit exceeded	Total IOCs across all arrays exceeds 1000; split into multiple requests
Missing entity relationships	Some entities may have limited relationship data; try different filter criteria
"name is required" error	Update threat actor search to use name parameter instead of deprecated query parameter
Too many threat actor results	Add limit parameter (defaults to 10) or use exact prefix for more precise matching

Workflow Context

This integration is particularly useful for:

• Automated IOC Enrichment: Automatically enrich IOCs extracted from security alerts, emails, logs, or threat feeds
• Incident Response: Enhance security incidents with Recorded Future intelligence during investigation workflows
• Threat Intelligence Platform (TIP): Feed enriched IOC data into your TIP or SIEM for correlation
• Threat Hunting: Discover threat actors, their TTPs, and targeted infrastructure during proactive hunting
• Alert Triage: Prioritize alerts based on Recorded Future risk scores and threat intelligence
• Attribution Analysis: Link IOCs to known threat actors and campaigns for better attribution
• Vulnerability Management: Enrich CVEs with threat intelligence to prioritize patching efforts
• Security Orchestration: Integrate Recorded Future intelligence into SOAR playbooks for automated response
• Intelligence Reporting: Generate threat intelligence reports combining IOC data with actor profiles
• Malware Analysis: Enrich file hashes and infrastructure IOCs during malware investigation

Security Considerations

1. Protect API Keys: Store API keys securely using NINA's credential management; never commit to version control or expose in logs.

2. Sensitive IOC Handling: Be aware that IOCs enriched through the API may be logged by Recorded Future for service improvement.

3. Data Privacy: Consider the sensitivity of IOCs before submitting them to third-party threat intelligence platforms.

4. Access Control: Limit credential access to authorized personnel and workflows only.

5. API Quota Management: Monitor API usage to prevent quota exhaustion that could impact critical security operations.

6. Rate Limiting: Implement proper rate limiting to maintain service availability and avoid API key suspension.

7. Error Handling: Ensure workflows handle API errors gracefully to prevent sensitive information leakage in error messages.

8. Audit Logging: Enable audit logging for all Recorded Future API operations to track intelligence queries.

9. Credential Rotation: Rotate API keys regularly and immediately revoke compromised credentials.

10. Subscription Tier: Ensure your subscription level matches your operational requirements to avoid service disruptions.

Additional Resources

• Recorded Future API Documentation
• Recorded Future SOAR API Guide
• MITRE ATT&CK Framework
• Understanding Risk Scores
• Recorded Future Intelligence Cloud Platform
• API Rate Limits and Best Practices