SDKs overview

URLScan.io offers developers tools to programmatically interact with its URL scanning and threat intelligence service. These tools include an official SDK for Python and a well-documented RESTful API. The SDKs and libraries are designed to simplify tasks such as submitting URLs for analysis, retrieving scan results, and accessing historical data, which are central to automated security workflows and research initiatives. The core functionality provided through the API and its SDK allows developers to integrate URLScan.io's capabilities directly into custom applications, security tools, or backend systems (URLScan.io API documentation).

The developer experience with URLScan.io is characterized by a straightforward API design, enabling efficient integration for a variety of use cases, from proactive threat hunting to incident response. The API is built to handle both synchronous submissions and asynchronous result retrieval, accommodating different operational requirements (URLScan.io developer documentation). Developers can choose to interact directly with the API using standard HTTP clients or leverage the official SDK for a more abstracted and language-idiomatic approach.

Official SDKs by language

URLScan.io maintains an official Software Development Kit (SDK) primarily for the Python programming language. This SDK encapsulates the HTTP requests and responses, providing a higher-level interface for interacting with the URLScan.io API. The official SDK is designed to streamline development by handling API authentication, request formatting, and response parsing, allowing developers to focus on integrating the service's functionality into their applications.

Official SDKs

Language Package Name Installation Command Maturity
Python urlscan pip install urlscan-py Stable

The Python SDK provides methods corresponding to the key API endpoints, such as submitting a URL for a scan, checking the status of a scan, and fetching detailed results. This approach reduces the boilerplate code typically required when interacting with REST APIs directly, enhancing developer productivity (URLScan.io API reference). The SDK typically follows semantic versioning, ensuring backward compatibility for most updates while clearly indicating breaking changes when necessary.

Installation

To use the official URLScan.io Python SDK, installation is managed through pip, the standard package installer for Python (Python Package Index documentation). Before installation, ensure you have Python 3.x and pip installed on your system.

Python SDK Installation

pip install urlscan-py

After successful installation, the urlscan package will be available in your Python environment. You can then import it into your scripts or applications to begin making API calls. It's often recommended to install Python packages within a virtual environment to manage dependencies effectively and avoid conflicts with other projects (Python venv module documentation).

To create and activate a virtual environment:

python3 -m venv myenv
source myenv/bin/activate  # On Linux/macOS
# myenv\Scripts\activate.bat  # On Windows

Then, install the SDK within this active virtual environment:

(myenv) pip install urlscan-py

Quickstart example

This quickstart example demonstrates how to use the official Python SDK to submit a URL for a public scan and retrieve its results. To run this example, you will need an API key from your URLScan.io account. API keys can be generated and managed through the user dashboard (URLScan.io API authentication guide).

First, ensure you have installed the urlscan-py package as described in the installation section.

import os
from urlscan import Urlscan

# Replace with your actual API key or set it as an environment variable
# It is recommended to use environment variables for API keys in production
api_key = os.getenv("URLSCAN_API_KEY", "YOUR_URLSCAN_API_KEY")

if api_key == "YOUR_URLSCAN_API_KEY":
    print("Warning: Please replace 'YOUR_URLSCAN_API_KEY' with your actual API key or set the URLSCAN_API_KEY environment variable.")
    exit()

# Initialize the Urlscan client
scanner = Urlscan(api_key)

# URL to scan
target_url = "https://example.com"

try:
    # Submit a public scan
    print(f"Submitting {target_url} for a public scan...")
    scan_submission = scanner.submit(url=target_url, public=True)

    if scan_submission:
        uuid = scan_submission.get("uuid")
        print(f"Scan submitted successfully. UUID: {uuid}")
        print(f"Results will be available at: https://urlscan.io/result/{uuid}/")

        # Optionally, wait for results (this can take a few seconds to minutes)
        # For production, consider implementing a webhook or a polling mechanism with backoff
        print("Waiting for scan results (this may take a moment)...")
        result = scanner.result(uuid)
        
        if result:
            print("Scan results retrieved:")
            print(f"  Verdict: {result.get('data', {}).get('verdicts', {}).get('overall', {}).get('score', 'N/A')}")
            print(f"  Screenshot: {result.get('task', {}).get('screenshotURL', 'N/A')}")
            print(f"  Redirected to: {result.get('data', {}).get('requests', [{}])[0].get('response', {}).get('url', 'N/A')}")
            # For more detailed data, inspect the 'result' dictionary
        else:
            print("Failed to retrieve scan results.")
    else:
        print("Failed to submit scan.")

except Exception as e:
    print(f"An error occurred: {e}")

This script first initializes the Urlscan client with your API key. It then submits https://example.com for a public scan. Upon successful submission, it retrieves a UUID (Universally Unique Identifier) for the scan. The script then proceeds to poll for the scan results, which might take some time depending on the target URL and system load. Finally, it prints a summary of the scan results, including the overall verdict and a link to the screenshot (URLScan.io scan submission API endpoint).

For more advanced usage, such as submitting private scans, specifying custom referrers, or using webhooks for result notification, consult the official URLScan.io API documentation and the Python SDK's specific function parameters (URLScan.io comprehensive API guide).

Community libraries

While URLScan.io provides an official Python SDK, the open nature of its API allows for the development of community-contributed libraries in other programming languages. These libraries are typically developed and maintained independently by developers who extend URLScan.io's reach to different ecosystems. Community libraries can offer bindings for languages like JavaScript, Go, Ruby, or PHP, enabling a broader range of applications and integrations beyond the officially supported Python SDK.

When considering a community library, it is advisable to review its documentation, community support, and recent activity to ensure it meets project requirements. Key factors to evaluate include:

  • Maintenance Status: Is the library actively maintained and updated to reflect changes in the URLScan.io API?
  • Feature Completeness: Does it support all the necessary API endpoints and features required for your use case?
  • Error Handling: How does the library manage API errors and network issues?
  • Authentication: Does it provide secure and convenient methods for API key management?
  • Community Reputation: Are there known issues or positive reports from other users?

Developers often publish these libraries on language-specific package managers (e.g., npm for JavaScript, RubyGems for Ruby) or on platforms like GitHub. While these libraries can significantly simplify integration in non-Python environments, they are not officially supported by URLScan.io. Users relying on community libraries should monitor the official URLScan.io documentation for API changes that might affect compatibility (URLScan.io API change log). For comprehensive API interaction, developers can always fall back to direct HTTP requests using popular libraries like requests in Python, axios in JavaScript, or fetch in Rust, adhering to the W3C principles of RESTful web services.