SDKs overview

Pulsedive provides tools and libraries designed to facilitate interaction with its Threat Intelligence Platform (TIP) programmatically. These resources enable developers to integrate Pulsedive's extensive threat intelligence capabilities into custom applications, security orchestrators, and automated workflows. The primary interface is a RESTful API, accessible via standard HTTP requests and authenticated using an API key Pulsedive API documentation. SDKs simplify this interaction by abstracting HTTP requests and responses into native language objects and methods.

The core functionality supported by the SDKs includes querying for indicator details, enriching observations with Pulsedive's context, submitting new indicators for analysis, and managing threat intelligence data. This enables use cases such as automated incident response, continuous monitoring for new threats, and integration with existing security information and event management (SIEM) systems or security orchestration, automation, and response (SOAR) platforms.

While a foundational Python SDK is officially supported, the open nature of APIs encourages the development of client libraries in various languages, often driven by community contributions. These libraries aim to reduce the boilerplate code required to interact with the Pulsedive API, allowing developers to focus on integrating threat intelligence into their applications rather than managing HTTP specifics or JSON parsing.

Official SDKs by language

Pulsedive officially maintains a Software Development Kit (SDK) for Python, providing a structured and supported way to interact with its API. This SDK is designed to offer a consistent and reliable interface for developers building applications that require threat intelligence integration. The official Python SDK encapsulates the underlying API calls, handles authentication, and parses responses into usable Python objects, aligning with general API client library practices Google API client library best practices.

The following table outlines the key details of the officially supported Python SDK:

Language Package Name Installation Command Maturity
Python pulsedive pip install pulsedive Stable

The official Python SDK provides methods for various API endpoints, including:

  • Indicator Search and Enrichment: Querying for details about IP addresses, domains, URLs, or file hashes.
  • Threat Lookup: Retrieving threat profiles and associated indicators.
  • Feed Management: Accessing and processing threat intelligence feeds.
  • Submission: Submitting new indicators or observations to Pulsedive.

Developers are encouraged to consult the Pulsedive API documentation for the most up-to-date information on SDK functionality, available methods, and detailed usage examples.

Installation

The installation process for the official Pulsedive Python SDK typically involves using Python's package installer, pip. This method ensures that the SDK and its dependencies are correctly downloaded and configured within your Python environment. Before installation, it is recommended to have a stable Python environment (version 3.6 or newer) set up on your system.

Prerequisites

  • Python 3.6+ installed.
  • pip, Python's package installer, usually included with Python installations.

Steps for Installation

  1. Open your terminal or command prompt.

  2. Run the installation command:
    Execute the following command to install the pulsedive package:

    pip install pulsedive

    This command will fetch the latest stable version of the Pulsedive SDK from PyPI (Python Package Index) and install it along with any required dependencies.

  3. Verify the installation (optional):
    You can verify that the package was installed correctly by attempting to import it in a Python interpreter:

    python -c "import pulsedive; print('Pulsedive SDK installed successfully!')"

    If no error messages appear, the SDK is ready for use.

Managing Dependencies

For project-specific environments, it is good practice to use a virtual environment to manage dependencies. This prevents conflicts between packages from different projects:

python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
pip install pulsedive

This approach ensures that the Pulsedive SDK and its dependencies are isolated to your project, maintaining a clean development environment. For more advanced dependency management, tools like Poetry or Rye can be used, which build upon pip and provide additional features for project setup and dependency locking Poetry documentation.

Quickstart example

This quickstart example demonstrates how to use the official Pulsedive Python SDK to query for an indicator's details. To run this example, you will need your Pulsedive API key, which can be obtained from your Pulsedive account settings.

Example: Get Indicator Details

The following Python code snippet illustrates how to initialize the SDK with your API key and retrieve information for a given indicator, such as an IP address or domain.

import pulsedive
import os

# Replace with your actual Pulsedive API key or set as an environment variable
# It's recommended to use environment variables for security.
api_key = os.environ.get("PULSEDIVE_API_KEY", "YOUR_PULSEDIVE_API_KEY")

# Initialize the Pulsedive client
# If PULSEDIVE_API_KEY environment variable is set, it will be used automatically.
# Otherwise, pass the api_key explicitly.
client = pulsedive.Pulsedive(api_key=api_key)

# Define the indicator to query
indicator_value = "8.8.8.8" # Example: Google DNS IP address

try:
    # Query for indicator details
    print(f"Querying Pulsedive for indicator: {indicator_value}...")
    indicator_data = client.api_get_indicator(indicator_value)

    # Print some details from the response
    if indicator_data and indicator_data.get('id'):
        print(f"Indicator ID: {indicator_data.get('id')}")
        print(f"Indicator Value: {indicator_data.get('value')}")
        print(f"Indicator Type: {indicator_data.get('type')}")
        print(f"Risk: {indicator_data.get('risk')}")
        print(f"Risk Reason: {indicator_data.get('riskreason')}")
        print(f"Threats associated: {', '.join([t['name'] for t in indicator_data.get('threats', [])])}")
    else:
        print(f"No details found for indicator: {indicator_value}")
        print(f"Full response: {indicator_data}")

except pulsedive.PulsediveAPIError as e:
    print(f"Pulsedive API Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Explanation:

  1. Import pulsedive: Imports the necessary library.
  2. API Key: The code attempts to retrieve the API key from an environment variable named PULSEDIVE_API_KEY for security best practices. If not found, it falls back to a placeholder. It is crucial to replace "YOUR_PULSEDIVE_API_KEY" with your actual key or set the environment variable.
  3. Initialize Client: An instance of the pulsedive.Pulsedive client is created, which will handle all interactions with the API.
  4. Define Indicator: The indicator_value variable holds the threat intelligence indicator you wish to query (e.g., an IP address, domain, or URL).
  5. Make API Call: client.api_get_indicator(indicator_value) makes the actual API request to retrieve details for the specified indicator.
  6. Process Response: The returned indicator_data is a dictionary containing all information Pulsedive has on that indicator. The example prints selected fields like ID, value, type, risk, and associated threats.
  7. Error Handling: Basic try-except blocks are included to catch potential API-specific errors (pulsedive.PulsediveAPIError) or general exceptions, ensuring graceful failure.

This example can be adapted to call other API endpoints, such as submitting new indicators or retrieving threat details, by using different methods provided by the pulsedive client object. Refer to the Pulsedive API documentation for a comprehensive list of available methods and their parameters.

Community libraries

Beyond the official Python SDK, the Pulsedive API's RESTful nature encourages the development of community-contributed libraries and integrations in various programming languages and platforms. These community efforts often arise from specific project needs or from developers seeking to integrate Pulsedive into their preferred tech stacks where an official SDK might not exist. Community libraries can offer different levels of abstraction and may focus on specific use cases, such as data ingestion for particular SIEMs or custom reporting tools.

While official support is not guaranteed for community libraries, they can provide valuable starting points and demonstrate diverse approaches to interacting with the Pulsedive API. Developers interested in contributing or finding such libraries typically look to:

  • GitHub: A primary repository for open-source projects, where developers share public codebases. Searching for "Pulsedive API" or "Pulsedive client" can reveal community efforts.
  • Security Community Forums: Discussions within cybersecurity groups or threat intelligence communities often highlight useful tools and integrations.
  • Pulsedive Community Resources: The official Pulsedive website or documentation may occasionally link to notable community projects, though this is less common for actively maintained lists.

When using community-contributed libraries, it is essential to:

  • Review the Source Code: Understand how the library interacts with the API, handles authentication, and processes data.
  • Check for Active Maintenance: Libraries that are regularly updated are more likely to be compatible with the latest API versions and address security vulnerabilities.
  • Evaluate Documentation: Good documentation helps in understanding how to use the library effectively and troubleshoot issues.
  • Consider Licensing: Be aware of the open-source license under which the library is distributed.

Examples of potential community contributions (though specific examples might vary over time and require validation) could include:

  • GoLang Client: A lightweight client for Go applications for high-performance API calls.
  • Node.js Wrapper: A JavaScript/TypeScript wrapper for backend applications built with Node.js.
  • PowerShell Module: Scripts or modules for integrating with Windows environments and automation.

Developers who create their own API clients or integrations are encouraged to share them with the wider community, fostering a collaborative ecosystem around threat intelligence. For detailed API specifications to build custom clients, refer to the Pulsedive API reference.