MISP Integration Guide

This guide provides the official documentation for integrating Vysion with MISP (Malware Information Sharing Platform) using the official Byron Labs MISP modules and feeds.

The Vysion MISP integration includes:

Expansion Module: Enrich MISP attributes with Vysion threat intelligence data
MISP Objects: Custom objects for Vysion-specific data (vysion-page, vysion-ransomware-feed)
Feed Integration: Automated ransomware victim feed from Vysion
Support for Multiple IOC Types: Domains, URLs, emails, cryptocurrency addresses, and more

Prerequisites

Before starting, ensure you have:

MISP Core and MISP Modules installed (MISP Installation Guide)
Python 3.8 or higher
Vysion API key (request at vysion.ai or byronlabs.io)
Administrative access to your MISP instance

Required Dependencies

The integration requires only two Python packages:

pip install pymisp[email,fileobjects,openioc,pdfexport,url]==2.4.194 vysion>=2.0.8

Installation Methods

The Vysion MISP integration can be installed using three methods:

Automated Installer (Recommended)
Ansible Deployment

For systems installed with the official MISP installer, use the provided installation script:

# Download the Vysion MISP integration
git clone https://github.com/ByronLabs/vysion-cti.git
cd vysion-cti/misp

# Run the automated installer (requires root privileges)
sudo chmod +x installer.sh
sudo ./installer.sh

The installer script will:

Copy MISP objects to the appropriate directories
Install the expansion module
Install Python dependencies
Configure the misp-modules service
Restart services automatically

Step 1: Install Dependencies

# Install in MISP's virtual environment
/var/www/MISP/venv/bin/python3 -m pip install pymisp[email,fileobjects,openioc,pdfexport,url]==2.4.194
/var/www/MISP/venv/bin/python3 -m pip install vysion>=2.0.8

Step 2: Install MISP Objects

Copy the custom objects to MISP object directories:

# Copy to main MISP objects directory
cp -r objects/* /var/www/MISP/app/files/misp-objects/objects/

# Copy to PyMISP objects directory
cp -r objects/* /var/www/MISP/PyMISP/pymisp/data/misp-objects/objects/

# Set correct permissions
chown -R www-data:www-data /var/www/MISP/app/files/misp-objects/objects/
chown -R www-data:www-data /var/www/MISP/PyMISP/pymisp/data/misp-objects/objects/

# Reinstall PyMISP to register new objects
/var/www/MISP/venv/bin/python3 -m pip install /var/www/MISP/PyMISP

Step 3: Install Expansion Module

# Copy expansion module
cp modules/expansion/vysion-expansion.py /usr/local/src/misp-modules/misp_modules/modules/expansion/

# Set permissions
chown misp /usr/local/src/misp-modules/misp_modules/modules/expansion/vysion-expansion.py

# Restart misp-modules service
systemctl restart misp-modules

For automated deployment across multiple servers:

# Clone the repository
git clone https://github.com/ByronLabs/vysion-cti.git
cd vysion-cti/misp

# Configure your inventory and run the playbook
ansible-playbook -u vysion --ask-pass -i ansible ansible/vysion-misp.yml -K -vvv

Refer to the Ansible documentation for advanced configuration.

MISP Configuration

1. Byron Labs Organization Setup

First, add Byron Labs as a trusted organization in MISP:

Navigate to Administration > Add Organisations
Configure the organization with these details:

Organisation Identifier: Byron Labs
UUID: efcd64f5-49db-49d6-a7cb-07c23d12e534
Nationality: Spain
Sector: infosec

2. Enable the Expansion Module

Go to Administration > Server Settings & Maintenance > Plugin settings
Navigate to the Enrichment section
Enable the Vysion expansion module:
- Set vysion-expansion_enabled to true
- Configure vysion-expansion_apikey with your Vysion API key

3. Configure Proxy Settings (Optional)

If your MISP instance is behind a proxy, configure these settings:

vysion-expansion_proxy_host: your-proxy.domain.com
vysion-expansion_proxy_port: 8080
vysion-expansion_proxy_username: username (optional)
vysion-expansion_proxy_password: password (optional)

Expansion Module Usage

The Vysion expansion module automatically enriches the following attribute types:

Supported Attribute Types

MISP Attribute Type	Vysion API Method	Description
`email`	`find_email()`	Search for email addresses in threat intelligence data
`domain`	`find_url()`	Find domains in ransomware and dark web sources
`hostname`	`find_url()`	Search for hostnames in collected data
`url`	`find_url()`	Analyze URLs for threat intelligence
`text`	`search()`	General text search across all data sources
`target-org`	`search()`	Search for organization names
`phone-number`	`search()`	Find phone numbers in collected data
`btc`	`find_wallet("BTC")`	Bitcoin address analysis
`xmr`	`find_wallet("XMR")`	Monero address analysis
`dash`	`find_wallet("DASH")`	Dash address analysis

Example Enrichment Workflow

Create or import an event with relevant attributes
Right-click on an attribute you want to enrich
Select “Enrich attribute” from the context menu
Choose “Vysion expansion” from the available modules
Review the enrichment results and merge relevant data

The module will return:

Related MISP objects (vysion-page, vysion-ransomware-feed)
Additional attributes found in Vysion data
Relevant tags for categorization

Feed Integration

Ransomware Victim Feed

Vysion provides an automated feed of ransomware victims that can be directly imported into MISP.

Setup Instructions

Navigate to Sync Actions > List feeds > Add feed
Configure the feed with these settings:

Enabled: true
Name: Vysion Ransomware Feed
Provider: Byron Labs
Input Source: Network
URL: https://api.vysion.ai/api/v2/feed/ransomware/misp
Source Format: MISP Feed
Distribution: Your organization only

Add the API key header:
- Header name: x-api-key
- Header value: your_vysion_api_key
Save and fetch: Click “Fetch and store all feed metadata”

Feed Content

The ransomware feed includes:

Newly identified ransomware victims
Associated cryptocurrency wallets
Dark web leak site URLs
Industry and geographical information
Detection timestamps

{
  "enabled": true,
  "name": "Vysion Ransomware Feed",
  "provider": "Byron Labs",
  "url": "https://api.vysion.ai/api/v2/feed/ransomware/misp",
  "distribution": 1,
  "sharing_group_id": null,
  "tag_id": null,
  "headers": {
    "x-api-key": "your_api_key_here"
  }
}

{
  "enabled": true,
  "name": "Vysion Ransomware Feed",
  "provider": "Byron Labs",
  "url": "https://api.vysion.ai/api/v2/feed/ransomware/misp",
  "distribution": 1,
  "sharing_group_id": null,
  "tag_id": null,
  "headers": {
    "x-api-key": "your_api_key_here",
    "User-Agent": "MISP-Feed-Client/1.0"
  },
  "fixed_event": false,
  "delta_merge": true,
  "event_id": null,
  "source_format": "misp"
}

MISP Objects

The integration includes two custom MISP objects designed specifically for Vysion data:

vysion-page Object

Represents a page or document found in Vysion’s threat intelligence database.

Attributes:

title: Page title
url: Source URL
content: Page content or excerpt
detection-date: When the page was first detected
tags: Associated threat intelligence tags

vysion-ransomware-feed Object

Represents a ransomware victim entry from Vysion feeds.

Attributes:

company-name: Victim organization name
ransomware-group: Responsible threat actor group
leak-site-url: Dark web leak site URL
company-website: Victim’s official website
industry: Business sector
country: Geographic location
description: Additional victim information

API Integration Examples

Basic Enrichment Script

import json
from pymisp import ExpandedPyMISP, MISPAttribute
import vysion.client as vysion

# Initialize clients
misp = ExpandedPyMISP('https://your-misp-instance.com', 'your_misp_key', True)
vysion_client = vysion.Client(api_key='your_vysion_key')

def enrich_attribute(event_id, attribute_id):
    """Enrich a MISP attribute with Vysion data."""

    # Get the attribute from MISP
    attribute = misp.get_attribute(attribute_id)
    attr_type = attribute['Attribute']['type']
    attr_value = attribute['Attribute']['value']

    # Query Vysion based on attribute type
    result = None
    if attr_type == 'domain':
        result = vysion_client.find_url(attr_value)
    elif attr_type == 'btc':
        result = vysion_client.find_wallet('BTC', attr_value)
    elif attr_type == 'email':
        result = vysion_client.find_email(attr_value)

    if result and result.get('data', {}).get('hits'):
        # Process and add enrichment data to MISP event
        for hit in result['data']['hits']:
            # Add related URLs
            if 'url' in hit:
                misp.add_attribute(event_id, 'url', hit['url'],
                                 comment=f'Related URL from Vysion enrichment')

            # Add cryptocurrency addresses
            for wallet_type in ['bitcoin_address', 'ethereum_address']:
                if wallet_type in hit and hit[wallet_type]:
                    for wallet in hit[wallet_type]:
                        misp.add_attribute(event_id, 'btc' if wallet_type == 'bitcoin_address' else 'other',
                                         wallet['value'], comment='From Vysion enrichment')

# Usage example
enrich_attribute(event_id=123, attribute_id=456)

Bulk Enrichment Script

from datetime import datetime, timedelta
import time

def bulk_enrich_recent_events(days=7, delay=1):
    """Enrich all recent events with Vysion data."""

    # Get recent events
    recent_events = misp.search(timestamp=f'{days}d', limit=50)

    for event in recent_events:
        event_id = event['Event']['id']
        print(f"Processing event {event_id}: {event['Event']['info']}")

        # Process each attribute in the event
        for attr in event['Event'].get('Attribute', []):
            if attr['type'] in ['domain', 'url', 'btc', 'email']:
                try:
                    enrich_attribute(event_id, attr['id'])
                    time.sleep(delay)  # Rate limiting
                except Exception as e:
                    print(f"Error enriching attribute {attr['id']}: {e}")

# Run bulk enrichment
bulk_enrich_recent_events()

Troubleshooting

Common Issues

1. Module Not Loading

Problem: Vysion expansion module doesn’t appear in MISP enrichment options.

Solutions:

Verify the module file is in the correct directory: /usr/local/src/misp-modules/misp_modules/modules/expansion/
Check file permissions: chown misp vysion-expansion.py
Restart misp-modules service: systemctl restart misp-modules
Check logs: journalctl -u misp-modules -f

2. API Authentication Errors

Problem: “A Vysion api key is required for this module” error.

Solutions:

Verify API key is correctly configured in MISP settings
Test API key independently: curl -H "x-api-key: YOUR_KEY" https://api.vysion.ai/api/v2/search?q=test
Check for special characters or spaces in the API key

3. Proxy Configuration Issues

Problem: Module fails with network connectivity errors.

Solutions:

# Test proxy settings manually
import requests

proxies = {
    'http': 'http://username:password@proxy.domain.com:8080',
    'https': 'http://username:password@proxy.domain.com:8080'
}

response = requests.get('https://api.vysion.ai/api/v2/search?q=test',
                       proxies=proxies,
                       headers={'x-api-key': 'your_key'})

4. Feed Import Failures

Problem: Ransomware feed fails to import.

Solutions:

Verify feed URL is accessible: curl -H "x-api-key: YOUR_KEY" https://api.vysion.ai/api/v2/feed/ransomware/misp
Check MISP feed settings for correct headers
Review MISP logs for specific error messages
Ensure sufficient disk space for feed data

Debug Mode

Enable debug logging for detailed troubleshooting:

import logging

# Enable debug logging for the Vysion module
logging.getLogger('vysion').setLevel(logging.DEBUG)

# Test the expansion module directly
import sys
sys.path.append('/usr/local/src/misp-modules/misp_modules/modules/expansion')

from vysion_expansion import handler

test_request = {
    "config": {"apikey": "your_api_key"},
    "attribute": {
        "type": "domain",
        "value": "example.com",
        "uuid": "test-uuid"
    }
}

result = handler(json.dumps(test_request))
print(json.dumps(result, indent=2))

Performance Optimization

Rate Limiting

The Vysion API has rate limits. Implement delays between requests:

import time

def rate_limited_enrichment(items, requests_per_minute=30):
    delay = 60 / requests_per_minute

    for item in items:
        # Process item
        enrich_attribute(item['event_id'], item['attribute_id'])
        time.sleep(delay)

Batch Processing

Process multiple attributes efficiently:

def batch_enrich_events(event_ids, batch_size=10):
    """Process events in batches to optimize performance."""

    for i in range(0, len(event_ids), batch_size):
        batch = event_ids[i:i + batch_size]

        for event_id in batch:
            try:
                enrich_event(event_id)
            except Exception as e:
                print(f"Error processing event {event_id}: {e}")

        # Pause between batches
        time.sleep(2)

Best Practices

1. API Key Management

Store API keys securely in MISP configuration
Rotate API keys regularly
Use separate API keys for different environments (dev/staging/prod)
Monitor API usage through Vysion dashboard

2. Data Quality

Review enrichment results before accepting all suggested attributes
Use appropriate TLP (Traffic Light Protocol) markings
Validate cryptocurrency addresses before adding as IOCs
Set proper distribution levels for sensitive data

3. Performance

Implement rate limiting to respect API quotas
Schedule bulk enrichments during off-peak hours
Monitor MISP performance impact of enrichment activities
Use selective enrichment for high-value events only

4. Integration Workflow

graph TD
    A[New MISP Event] --> B[Automatic Feed Import]
    B --> C[Manual Attribute Addition]
    C --> D[Enrichment with Vysion]
    D --> E[Review and Validate]
    E --> F[Share with Community]
    F --> G[Monitor for Updates]

Advanced Configuration

Custom Object Templates

Create custom templates for specific use cases:

{
  "name": "vysion-custom-threat",
  "meta-category": "network",
  "description": "Custom threat intelligence object for Vysion data",
  "version": 1,
  "uuid": "custom-uuid-here",
  "attributes": {
    "threat-actor": {
      "misp-attribute": "threat-actor"
    },
    "confidence-level": {
      "misp-attribute": "text"
    },
    "first-seen": {
      "misp-attribute": "datetime"
    }
  }
}

Webhook Integration

Set up webhooks for real-time enrichment:

from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/vysion-webhook', methods=['POST'])
def handle_vysion_webhook():
    """Handle incoming Vysion webhook notifications."""

    data = request.get_json()

    # Process new threat intelligence data
    if data.get('type') == 'new_ransomware_victim':
        create_misp_event_from_victim(data['victim'])

    return {'status': 'processed'}

def create_misp_event_from_victim(victim_data):
    """Create MISP event from ransomware victim data."""

    event = misp.new_event(
        info=f"Ransomware victim: {victim_data['company_name']}",
        distribution=1,
        threat_level_id=2
    )

    # Add victim details as attributes
    misp.add_attribute(event.id, 'target-org', victim_data['company_name'])
    misp.add_attribute(event.id, 'url', victim_data['leak_site_url'])

    return event

Migration and Updates

Updating the Integration

To update to a newer version:

# Backup current configuration
cp /usr/local/src/misp-modules/misp_modules/modules/expansion/vysion-expansion.py \
   /usr/local/src/misp-modules/misp_modules/modules/expansion/vysion-expansion.py.backup

# Download and install updates
git pull origin main
sudo ./installer.sh

# Restart services
systemctl restart misp-modules
systemctl restart apache2

Data Migration

When migrating between MISP instances:

def export_vysion_enriched_events():
    """Export events that have been enriched with Vysion data."""

    # Search for events with Vysion tags
    events = misp.search(tags=['vysion:*'], return_format='json')

    # Export to file
    with open('vysion_enriched_events.json', 'w') as f:
        json.dump(events, f, indent=2)

def import_vysion_enriched_events():
    """Import previously exported Vysion-enriched events."""

    with open('vysion_enriched_events.json', 'r') as f:
        events = json.load(f)

    for event in events:
        misp.add_event(event)

Support and Resources

Getting Help

Official Documentation: developers.vysion.ai
MISP Community: MISP Project Forums
Byron Labs Support: Contact through byronlabs.io

Additional Resources

Source Code

The complete Vysion MISP integration source code is available at: github.com/ByronLabs/vysion-cti

This integration is maintained by Byron Labs and is designed to work with MISP 2.4+ and the latest versions of the Vysion API.