GreyNoise SDKs & Libraries: Official & Community Integrations

SDKs overview

GreyNoise provides Software Development Kits (SDKs) and libraries to facilitate programmatic interaction with its threat intelligence platform. These tools enable developers to integrate GreyNoise data, such as IP context and attack classification, directly into custom applications, security tools, and automated workflows. The primary goal of these SDKs is to abstract the underlying HTTP API calls, offering language-specific methods and data structures that simplify querying and parsing responses. This approach aims to reduce development time and potential errors when building integrations that leverage GreyNoise's insights into internet scanning activity and opportunistic attacks.

The official SDKs are designed to offer a consistent and idiomatic interface for accessing GreyNoise's various endpoints, including those for IP lookup, query execution, and specialized data feeds. By providing pre-built functions for common operations, developers can focus on utilizing the threat intelligence data rather than managing API request formatting, authentication, and response parsing. The availability of a Community tier with API access allows developers to experiment with the SDKs and integrate limited GreyNoise data into their projects without an initial financial commitment.

Official SDKs by language

GreyNoise maintains official SDKs for popular programming languages, ensuring direct support and compatibility with the latest API features. These SDKs are developed and maintained by GreyNoise to provide reliable and up-to-date access to the platform's capabilities. The current official SDKs focus on Python and Go, reflecting their prevalence in security operations, data analysis, and backend development environments.

Each official SDK is documented with specific usage examples and API method references on the GreyNoise documentation portal. These resources detail how to initialize clients, perform queries, and interpret the structured responses, aligning with best practices for API client development. Developers are encouraged to refer to the GreyNoise API reference for comprehensive details on available endpoints and data models that the SDKs abstract.

Installation

Installing the GreyNoise SDKs is typically performed using the standard package management tools for each respective language. The process is designed to be straightforward, allowing developers to quickly set up their development environment for GreyNoise integration.

Python SDK Installation

To install the official GreyNoise Python SDK, use pip, the Python package installer. This command fetches the latest version of the greynoise package from the Python Package Index (PyPI) and installs it into your environment.

pip install greynoise

It is recommended to use a Python virtual environment to manage project dependencies and avoid conflicts with system-wide packages. After installation, the SDK can be imported and used in Python scripts.

Go SDK Installation

For the GreyNoise Go SDK, use the go get command to download and install the package. This command retrieves the source code from the specified Git repository and compiles it, making it available for use in Go projects.

go get github.com/GreyNoise-Intelligence/go-greynoise

After executing this command, the go-greynoise package will be available in your Go module path, ready to be imported into your Go source files. Go modules are the standard way to manage dependencies in Go projects, as described in the official Go documentation on managing dependencies.

Quickstart example

The following quickstart examples demonstrate basic usage of the GreyNoise SDKs to query an IP address. These examples assume you have already installed the respective SDK and have a GreyNoise API key available. An API key is required for authentication with the GreyNoise API, which can be obtained from your GreyNoise account settings.

Python Quickstart

This Python example shows how to initialize the GreyNoise client and query a specific IP address to check its classification.

import os
import greynoise

# Replace with your GreyNoise API key or set as environment variable GN_API_KEY
api_key = os.environ.get("GN_API_KEY", "YOUR_GREYNOISE_API_KEY")

if api_key == "YOUR_GREYNOISE_API_KEY":
    print("Please set the GN_API_KEY environment variable or replace the placeholder.")
    exit(1)

# Initialize the GreyNoise API client
api_client = greynoise.GreyNoise(api_key=api_key)

ip_address = "8.8.8.8" # Example IP address (Google DNS)

try:
    # Query the IP address
    riot_check = api_client.riot(ip_address)
    ip_lookup = api_client.ip(ip_address)

    print(f"--- GreyNoise Lookup for {ip_address} ---")
    print(f"RIoT Classification: {riot_check}")
    if ip_lookup:
        print(f"Classification: {ip_lookup['classification']['classification']}")
        print(f"Actor: {ip_lookup['classification']['actor']}")
        print(f"Tags: {', '.join(ip_lookup['tags'])}")
        print(f"Description: {ip_lookup['description']}")
    else:
        print("No detailed GreyNoise data found for this IP.")

except greynoise.exceptions.APIError as e:
    print(f"Error querying GreyNoise: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Go Quickstart

This Go example demonstrates how to use the go-greynoise SDK to perform an IP lookup. Ensure your GN_API_KEY environment variable is set or replace the placeholder.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	greynoise "github.com/GreyNoise-Intelligence/go-greynoise"
)

func main() {
	apiKey := os.Getenv("GN_API_KEY")
	if apiKey == "" {
		log.Fatal("GN_API_KEY environment variable not set. Please set your GreyNoise API key.")
	}

	client := greynoise.NewClient(apiKey)

	ipAddress := "8.8.8.8" // Example IP address (Google DNS)

	ctx := context.Background()

	// Perform an IP lookup
	ipLookup, _, err := client.IP.Lookup(ctx, ipAddress)
	if err != nil {
		log.Fatalf("Error looking up IP %s: %v", ipAddress, err)
	}

	fmt.Printf("--- GreyNoise Lookup for %s ---\n", ipAddress)
	if ipLookup.Classification != nil {
		fmt.Printf("Classification: %s\n", ipLookup.Classification.Classification)
		fmt.Printf("Actor: %s\n", ipLookup.Classification.Actor)
		fmt.Printf("Tags: %v\n", ipLookup.Tags)
		fmt.Printf("Description: %s\n", ipLookup.Description)
	} else {
		fmt.Printf("No detailed GreyNoise data found for this IP.\n")
	}

	// Check RIoT classification
	riotCheck, _, err := client.IP.Riot(ctx, ipAddress)
	if err != nil {
		log.Fatalf("Error checking RIoT for IP %s: %v", ipAddress, err)
	}
	fmt.Printf("RIoT Classification: %v\n", riotCheck.Riot)
}

Community libraries

In addition to the official SDKs, the GreyNoise API can be integrated using community-contributed libraries or by directly interacting with the RESTful API via standard HTTP client libraries available in most programming languages. While official SDKs offer direct support, community libraries can sometimes provide integrations for other languages or frameworks that GreyNoise does not officially support.

Developers looking for community contributions should typically search repositories like GitHub for projects tagged with "greynoise" or "threat intelligence" combined with their preferred language. These might include wrappers for languages such as Node.js, Ruby, or PowerShell. When using community-contdeveloped libraries, it is important to review their maintenance status, documentation, and the reputation of their contributors, as they may not offer the same level of support or guarantee of compatibility as official SDKs.

For direct API interaction, developers can use any HTTP client library to send requests to the GreyNoise API endpoints. This approach requires manual handling of API key authentication (typically via an Authorization header), request body construction (often JSON), and response parsing. This method offers the most flexibility for languages without dedicated SDKs, but it also places a greater burden on the developer to correctly implement all aspects of the API interaction. Tools like cURL are often used for initial testing and understanding of the API's behavior before implementing a custom client.