URLhaus SDKs & Libraries: Python, Go, PHP, & Community Tools

SDKs overview

URLhaus offers an API that allows developers to programmatically interact with its database of malicious URLs. This interaction includes submitting URLs for analysis, querying the status of existing URLs, and retrieving detailed information about identified threats. While URLhaus maintains official SDKs for specific programming languages, the straightforward nature of its RESTful API enables integration from virtually any environment capable of making HTTP requests. The API is designed to provide access to URLhaus's extensive threat intelligence for applications requiring real-time URL verification or bulk data processing for security research.

The URLhaus API facilitates tasks such as identifying phishing sites, malware distribution points, and other types of malicious URLs. Developers can use the API to enhance security solutions, implement automated threat detection systems, or conduct security research by accessing a continuously updated dataset of known threats. The API is rate-limited to ensure fair usage across all users, with specific headers provided in responses to help monitor current usage against established limits. More details on rate limits and API usage are available in the URLhaus API documentation.

Official SDKs by language

URLhaus provides official SDKs to simplify integration with its API for several popular programming languages. These SDKs typically handle API request construction, response parsing, and error handling, allowing developers to focus on application logic rather than low-level API communication. The official SDKs are maintained by the URLhaus project and are recommended for developers working in the respective languages for stability and feature completeness.

Installation

To begin using the URLhaus API, you can install the official SDKs or integrate directly via HTTP requests. The installation process varies by language and package manager.

Python

The Python SDK can be installed using pip, the Python package installer. This command adds the urlhaus package to your Python environment, making its functions available for use.

pip install urlhaus

Go

For Go projects, the SDK is fetched using the go get command, which downloads the module into your Go workspace.

go get github.com/urlhaus/urlhaus-go

PHP

PHP projects typically use Composer for dependency management. The URLhaus PHP SDK can be added to your project's composer.json and installed via Composer.

composer require urlhaus/urlhaus-php

Quickstart example

This quickstart demonstrates how to check the status of a URL using the Python SDK. This is a common operation to determine if a URL is known to URLhaus and if it is reported as malicious.

Python Quickstart

The following Python code snippet shows how to instantiate the URLhaus client and perform a lookup for a specific URL. The response will indicate whether the URL is listed as malicious, clean, or if no information is available.

from urlhaus import Urlhaus

# Initialize the URLhaus client
client = Urlhaus()

# Define the URL to check
url_to_check = "http://example-malicious.com/payload.exe"

# Perform a URL lookup
response = client.lookup_url(url_to_check)

# Print the results
if response and response['query_status'] == 'ok':
    print(f"URL: {response['url']}")
    print(f"Status: {response['url_status']}")
    if response['url_status'] == 'online':
        print(f"Threat: {response['threat']}")
        print(f"Tags: {', '.join(response['tags']) if response['tags'] else 'None'}")
else:
    print(f"Error or URL not found: {response.get('query_status', 'Unknown error')}")

This example queries the URLhaus database for a given URL. The lookup_url method returns a dictionary containing details such as the URL's status (e.g., 'online', 'offline'), the detected threat type (e.g., 'malware'), and any associated tags. This information is crucial for security applications that need to validate URLs against known threats.

Go Quickstart

For Go developers, the process is similar. The urlhaus-go library provides functions to interact with the API.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/urlhaus/urlhaus-go"
)

func main() {
	client := urlhaus.NewClient(nil)

	urlToCheck := "http://example-phishing.com/login.html"
	
	lookupResponse, err := client.URL.Lookup(context.Background(), urlToCheck)
	if err != nil {
		log.Fatalf("Error looking up URL: %v", err)
	}

	if lookupResponse.QueryStatus == "ok" {
		fmt.Printf("URL: %s\n", lookupResponse.URL)
		fmt.Printf("Status: %s\n", lookupResponse.URLStatus)
		if lookupResponse.URLStatus == "online" {
			fmt.Printf("Threat: %s\n", lookupResponse.Threat)
			fmt.Printf("Tags: %v\n", lookupResponse.Tags)
		}
	} else {
		fmt.Printf("Error or URL not found: %s\n", lookupResponse.QueryStatus)
	}
}

PHP Quickstart

PHP users can leverage the urlhaus-php package within their web applications or scripts.

<?php

require 'vendor/autoload.php';

use Urlhaus\Urlhaus;

$client = new Urlhaus();

$urlToCheck = "http://example-malware-dropper.net/download.zip";

try {
    $response = $client->lookupUrl($urlToCheck);

    if ($response->queryStatus === 'ok') {
        echo "URL: " . $response->url . "\n";
        echo "Status: " . $response->urlStatus . "\n";
        if ($response->urlStatus === 'online') {
            echo "Threat: " . $response->threat . "\n";
            echo "Tags: " . implode(', ', $response->tags) . "\n";
        }
    } else {
        echo "Error or URL not found: " . $response->queryStatus . "\n";
    }
} catch (\Exception $e) {
    echo "An error occurred: " . $e->getMessage() . "\n";
}

?>

Community libraries

Beyond the official SDKs, the URLhaus community has developed various libraries and tools to integrate with the API. These community-driven projects often cater to specific use cases, provide bindings for additional programming languages, or offer command-line interfaces for quick lookups. While not officially supported by URLhaus, these libraries can be valuable resources for developers seeking alternatives or specialized functionalities.

Examples of community contributions include wrappers for languages like Ruby or Node.js, and integrations with security orchestration and automated response (SOAR) platforms. When using community-developed libraries, it is advisable to review their source code and ensure they align with your project's security and reliability requirements. Developers can often find these projects on platforms like GitHub by searching for "urlhaus api" or "urlhaus client" in their preferred language. For instance, a search on GitHub for URLhaus Python projects might reveal additional community contributions.

The URLhaus API's design, which adheres to standard HTTP methods and JSON responses, makes it accessible for developers to create their own clients if an official or community library is not available for their specific environment. Understanding the HTTP/1.1 Semantics and Content specification can be beneficial for those building custom integrations.