Skip to main content

MISP Integration Guide

Overview​

The MISP integration allows your NINA workflows to seamlessly connect with MISP (Malware Information Sharing Platform) for threat intelligence sharing and collaboration. This integration enables you to create, retrieve, update, and manage MISP events, attributes, and tags directly from your workflows, facilitating efficient threat intelligence operations and community sharing.

Status​

We currently support comprehensive CRUD operations for Events, Attributes, and Tags, including:

  • Event Management: Create, retrieve, update, delete, publish, and search threat intelligence events
  • Attribute Operations: Add, edit, search, and manage IoCs and contextual information
  • Tag Management: Create, assign, and manage classification tags for better organization
  • Advanced Search: Powerful search capabilities with filtering and correlation features

Some of the main capabilities include:

  • Threat Intelligence Events: Create structured events to encapsulate threat information
  • Indicator Management: Add and manage various types of indicators and attributes
  • Collaborative Sharing: Publish events for community sharing with distribution controls
  • Tag-based Classification: Organize and classify events and attributes using tags
  • Event Enrichment: Enhance events with additional data from enrichment modules
  • Advanced Filtering: Search across events and attributes with comprehensive filtering options

Credential Configuration​

Before using the MISP integration in your workflows, you need to configure your MISP instance credentials. The integration uses API key authentication to securely connect to your MISP instance.

Authentication Method​

API Key Authentication​

For connecting to your MISP instance:

FieldDescriptionExample
Base URLYour MISP instance URLhttps://misp.example.org
API KeyAPI key generated from your MISP account settingsabcd1234efgh5678ijkl9012mnop3456qrst7890

How to get your API Key:

  1. Log in to your MISP instance
  2. Navigate to My Profile (click on your username in the top-right corner)
  3. Go to the Auth Keys tab
  4. Click Add authentication key
  5. Provide a comment describing the key's purpose (e.g., "NINA Integration")
  6. Copy the generated API key immediately (it won't be shown again)

Creating a MISP 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., "MISP Production")
    • Description: Optional details about the credential's purpose
    • Integration Service: Select "MISP"
    • Auth Type: Select "API Key"
    • Base URL: Enter your MISP instance URL
    • API Key: Enter your MISP API key

  4. Click Test Connection to verify credentials

  5. Click Save to store the credential

Supported Resources and Operations​

The MISP integration supports the following resources and operations:

Event​

OperationDescription
Get All EventsRetrieves a list of all events
Get EventRetrieves details of a specific event by ID
Create EventCreates a new MISP event
Update EventUpdates an existing event
Delete EventDeletes an event
Publish EventPublishes an event for community sharing
Unpublish EventUnpublishes a previously published event
Search EventsSearches for events using various criteria
Add Tag to EventAdds a classification tag to an event
Remove Tag from EventRemoves a tag from an event
Enrich EventEnriches an event with additional data from modules

Attribute​

OperationDescription
Add AttributeAdds an indicator or contextual information to an event
Search AttributesSearches for attributes using comprehensive filtering
Edit AttributeUpdates an existing attribute
Delete AttributeDeletes an attribute
Restore AttributeRestores a previously deleted attribute
Add Tag to AttributeAdds a tag to an attribute
Remove Tag from AttributeRemoves a tag from an attribute

Tag​

OperationDescription
Get All TagsRetrieves all available tags
Get TagRetrieves details of a specific tag
Add TagCreates a new classification tag
Delete TagDeletes a tag
Edit TagUpdates an existing tag
Search TagsSearches for tags by name or criteria

Parameter Merging and Templating​

The MISP integration takes full advantage of NINA's parameter merging and templating capabilities:

Parameter Sources (in order of precedence)​

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

When a MISP Integration Node executes:

  • It combines parameters from all sources
  • Node parameters take precedence over extracted parameters
  • Template variables within parameters are processed (using {{variable_name}} syntax)
  • The combined parameters are used to execute the MISP operation

Example: Creating a MISP Event​

Basic Event Creation​

Below is an example of creating a threat intelligence event using the Integration Node:

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "create",
  "parameters": {
    "info": "APT29 Campaign - Phishing Infrastructure",
    "distribution": "3",
    "threat_level_id": "2",
    "analysis": "1",
    "date": "2024-01-15",
    "published": false
  }
}

Creating an Event with Template Variables​

You can use template variables to dynamically insert values from input data:

Input Data from Previous Node:​

{
  "threat_report": {
    "title": "APT29 Campaign - Phishing Infrastructure",
    "date": "2024-01-15",
    "severity": "high",
    "analysis_status": "ongoing"
  },
  "distribution_level": "community",
  "should_publish": false
}

Node Configuration with Template Variables:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "create",
  "parameters": {
    "info": "{{threat_report.title}}",
    "distribution": "{{#if (eq distribution_level 'organization')}}0{{else if (eq distribution_level 'community')}}1{{else}}3{{/if}}",
    "threat_level_id": "{{#if (eq threat_report.severity 'critical')}}1{{else if (eq threat_report.severity 'high')}}2{{else}}3{{/if}}",
    "analysis": "{{#if (eq threat_report.analysis_status 'initial')}}0{{else if (eq threat_report.analysis_status 'ongoing')}}1{{else}}2{{/if}}",
    "date": "{{threat_report.date}}",
    "published": "{{should_publish}}"
  }
}

Example: Adding Attributes to Events​

Adding IoC Attributes​

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "attribute",
  "operation": "add",
  "parameters": {
    "eventId": "12345",
    "type": "ip-src",
    "category": "Network activity",
    "value": "192.168.1.100",
    "to_ids": true,
    "comment": "C2 server identified in APT29 campaign",
    "distribution": "3"
  }
}

Adding Multiple Attributes with Template Variables​

Input Data:​

{
  "event_id": "12345",
  "indicators": [
    {
      "type": "domain",
      "value": "malicious-domain.com",
      "category": "Network activity",
      "comment": "Command and control domain"
    },
    {
      "type": "md5",
      "value": "5d41402abc4b2a76b9719d911017c592",
      "category": "Payload delivery",
      "comment": "Malicious payload hash"
    }
  ]
}

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "attribute",
  "operation": "add",
  "parameters": {
    "eventId": "{{event_id}}",
    "type": "{{indicators.0.type}}",
    "category": "{{indicators.0.category}}",
    "value": "{{indicators.0.value}}",
    "to_ids": true,
    "comment": "{{indicators.0.comment}}",
    "distribution": "5"
  }
}

Example: Searching for Threat Intelligence​

Searching Events​

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "search",
  "parameters": {
    "tags": ["APT29", "phishing"],
    "from": "2024-01-01",
    "to": "2024-01-31",
    "published": true,
    "limit": 50
  }
}

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "attribute",
  "operation": "search",
  "parameters": {
    "type": "ip-src",
    "category": "Network activity",
    "value": "192.168.*",
    "to_ids": true,
    "from": "7d",
    "includeEventTags": true,
    "includeCorrelations": true,
    "limit": 100
  }
}

Searching with Complex Criteria​

Input Data:​

{
  "search_criteria": {
    "indicator_types": ["ip-src", "domain", "url"],
    "timeframe": "30d",
    "threat_levels": ["1", "2"],
    "include_context": true
  }
}

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "attribute",
  "operation": "search",
  "parameters": {
    "type": "{{search_criteria.indicator_types}}",
    "last": "{{search_criteria.timeframe}}",
    "threat_level_id": "{{search_criteria.threat_levels}}",
    "includeEventTags": "{{search_criteria.include_context}}",
    "includeEventUuid": "{{search_criteria.include_context}}",
    "to_ids": true,
    "deleted": false
  }
}

Example: Tag Management​

Creating and Assigning Tags​

Creating a New Tag:​

{
  "integration_service": "misp",
  "resource": "tag",
  "operation": "add",
  "parameters": {
    "name": "tlp:amber",
    "colour": "#FFC000",
    "exportable": true
  }
}

Adding Tag to Event:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "addTag",
  "parameters": {
    "eventId": "{{event_id}}",
    "tagId": "{{tag_id}}",
    "local": true
  }
}

Searching Tags​

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "tag",
  "operation": "search",
  "parameters": {
    "searchTerm": "%tlp%"
  }
}

Example: Event Publishing and Sharing​

Publishing Events​

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "publish",
  "parameters": {
    "eventId": "{{event_id}}"
  }
}

Event Enrichment​

Input Data:​

{
  "event_id": "12345",
  "enrichment_modules": ["virustotal", "shodan", "passivedns"]
}

Node Configuration:​

{
  "integration_service": "misp",
  "resource": "event",
  "operation": "enrich",
  "parameters": {
    "eventId": "{{event_id}}",
    "modules": "{{enrichment_modules}}"
  }
}

Distribution Levels and Threat Levels​

Distribution Levels​

  • 0 - Your organization only: Event is only visible within your organization
  • 1 - This community only: Shared within your connected MISP community
  • 2 - Connected communities: Shared with connected communities
  • 3 - All communities: Shared with all MISP communities
  • 4 - Sharing group: Shared with a specific sharing group
  • 5 - Inherit Event: Inherits distribution from the parent event

Threat Levels​

  • 1 - High: High threat level requiring immediate attention
  • 2 - Medium: Medium threat level requiring monitoring
  • 3 - Low: Low threat level for informational purposes
  • 4 - Undefined: Threat level not yet determined

Analysis Levels​

  • 0 - Initial: Initial analysis phase
  • 1 - Ongoing: Analysis is in progress
  • 2 - Complete: Analysis has been completed

Attribute Categories​

Main Categories​

  • Internal reference: References and identifiers internal to your organization
  • Targeting data: Information about targets of the threat
  • Antivirus detection: AV signatures and detection information
  • Payload delivery: Indicators related to malware delivery
  • Artifacts dropped: Files, registry keys, and other artifacts
  • Payload installation: Installation mechanisms and persistence
  • Persistence mechanism: Methods used to maintain access
  • Network activity: Network-based indicators and communications
  • Payload type: Classification of malware type
  • Attribution: Information about threat actors
  • External analysis: Links to external analysis and reports
  • Financial fraud: Financial crime related indicators
  • Support Tool: Tools used in the attack
  • Social network: Social media and communication platforms
  • Person: Personal information related to threats
  • Other: Miscellaneous information

Troubleshooting​

Complete workflow showing MISP integration nodes connected with other node types

IssueResolution
Authentication failuresVerify your API key is correct and active. Check that the Base URL is properly formatted (include https://).
"Event ID not found" errorsEnsure the event ID exists and you have permission to access it. Check if the event might have been deleted.
Invalid distribution level errorsUse valid distribution levels (0-5). Ensure sharing groups exist if using distribution level 4.
Attribute validation errorsVerify the attribute type and category combination is valid. Check MISP documentation for allowed combinations.
Permission denied errorsEnsure your API key has sufficient permissions for the requested operation. Contact your MISP administrator.
Tag assignment failuresVerify the tag exists and you have permission to use it. Check if the tag name is spelled correctly.
Search timeout errorsReduce the scope of your search by adding more specific filters or reducing the time range.
SSL certificate errorsFor self-signed certificates, ensure your MISP instance SSL configuration is correct.

Best Practices​

  1. Use Descriptive Event Information: Create clear, specific event titles that describe the threat or campaign being tracked.

  2. Set Appropriate Distribution Levels: Choose distribution levels carefully based on your sharing policies and the sensitivity of the information.

  3. Leverage Template Variables: Use {{variable_name}} syntax to dynamically insert values from upstream nodes for consistent data flow.

  4. Implement Proper Tagging: Use standardized tags like TLP (Traffic Light Protocol) tags for proper information sharing controls.

  5. Validate IoC Quality: Ensure indicators are properly formatted and validated before adding to events.

  6. Use Correlation Features: Enable correlation when searching to identify relationships between different indicators.

  7. Monitor Event Lifecycle: Track events through their analysis phases (Initial → Ongoing → Complete).

  8. Batch Operations: When adding multiple attributes, consider the impact on performance and use appropriate limits.

  9. Handle Sensitive Data: Be cautious with distribution levels and ensure sensitive information is properly classified.

  10. Maintain Data Quality: Regularly review and update events, removing obsolete information and adding new context.

  11. Use Event Enrichment: Leverage enrichment modules to automatically enhance events with additional intelligence.

  12. Implement Error Handling: Handle API errors gracefully, especially for operations that might fail due to permissions or data validation.

  13. Search Efficiently: Use specific search criteria to avoid overwhelming the MISP instance with broad queries.

  14. Version Control: Keep track of changes to events and attributes for audit and rollback purposes.

  15. Community Collaboration: Actively participate in threat intelligence sharing while respecting sharing agreements and policies.