Censys SDKs & Libraries: Python, Go, and Community Tools

SDKs overview

Censys provides Software Development Kits (SDKs) and client libraries to facilitate programmatic interaction with its Censys API. These SDKs abstract the underlying HTTP requests, authentication, and response parsing, allowing developers to integrate Censys data and capabilities directly into their applications using familiar programming language constructs. The primary benefit of using an SDK is to reduce the boilerplate code required for API interaction, enhance type safety, and provide an idiomatic interface consistent with the chosen language's conventions. This approach streamlines the development of custom security tools, automation scripts, and integrations with existing security workflows.

Censys's API enables access to its extensive dataset of internet-wide scan information, including host data, service banners, and certificate details. It also supports managing external attack surfaces through its Attack Surface Management (ASM) product. By offering SDKs in popular languages like Python and Go, Censys aims to support a broad range of use cases, from individual researchers performing vulnerability analysis to enterprises automating their external asset discovery and monitoring processes.

Official SDKs by language

Censys maintains official SDKs for Python and Go, which are designed to provide comprehensive coverage of the Censys API. These SDKs are actively developed and supported by Censys, ensuring compatibility with the latest API versions and features. They are the recommended tools for developers building applications that interact with Censys services.

Installation

Installing the official Censys SDKs is performed using standard package managers for each respective language. Prior to installation, ensure that you have the appropriate language runtime and package manager installed on your system. For authentication, both SDKs typically require a Censys API ID and Secret, which can be obtained from your Censys account settings.

Python SDK

The Python SDK is distributed via PyPI (Python Package Index). Installation is straightforward using pip:

pip install censys

After installation, you can configure your API credentials. It is recommended to set them as environment variables (CENSYS_API_ID and CENSYS_API_SECRET) or pass them directly when initializing the client.

Go SDK

The Go SDK is available on GitHub and can be installed using Go's module system:

go get github.com/censys/censys-go/v2

Similar to the Python SDK, API credentials for the Go SDK can be configured via environment variables or explicitly provided during client instantiation.

Quickstart example

The following examples demonstrate basic usage of the Python and Go SDKs to perform a simple search query against the Censys Search API. These snippets illustrate how to authenticate, make a request, and process the results.

Python Quickstart

This example performs a search for hosts with an open port 80 and retrieves the first page of results. Ensure your CENSYS_API_ID and CENSYS_API_SECRET environment variables are set.

import os
from censys.search import CensysHosts

# Initialize the CensysHosts client
# API_ID and API_SECRET are automatically loaded from environment variables
# CENSYS_API_ID and CENSYS_API_SECRET if not explicitly passed.
hosts = CensysHosts()

try:
    # Perform a search for hosts with open port 80
    query = "services.port: 80"
    print(f"Searching for: {query}")
    search_results = hosts.search(query, pages=-1) # -1 for all pages, or specify a number

    # Iterate through the results
    count = 0
    for host in search_results:
        print(f"  IP: {host['ip']} | Updated At: {host['last_updated']}")
        count += 1
        if count >= 5: # Limit output for quickstart
            break

    if count == 0:
        print("No results found for the query.")

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

Go Quickstart

This Go example performs a similar search for hosts with an open port 80. Ensure your CENSYS_API_ID and CENSYS_API_SECRET environment variables are set.

package main

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

	"github.com/censys/censys-go/v2/censys"
	"github.com/censys/censys-go/v2/censys/hosts"
)

func main() {
	// Initialize the Censys client
	// API_ID and API_SECRET are automatically loaded from environment variables
	// CENSYS_API_ID and CENSYS_API_SECRET if not explicitly passed.
	client, err := censys.NewClient(nil)
	if err != nil {
		log.Fatalf("Failed to create Censys client: %v", err)
	}

	// Perform a search for hosts with open port 80
	query := "services.port: 80"
	fmt.Printf("Searching for: %s\n", query)

	hostSearchService := hosts.NewService(client)
	searchReq := &hosts.SearchQuery{
		Query: query,
		Fields: []string{"ip", "last_updated"}, // Specify fields to retrieve
	}

	ctx := context.Background()
	searchRes, _, err := hostSearchService.Search(ctx, searchReq)
	if err != nil {
		log.Fatalf("Search failed: %v", err)
	}

	// Iterate through the results
	count := 0
	for _, host := range searchRes.Result.Hits {
		fmt.Printf("  IP: %s | Updated At: %s\n", host.IP, host.LastUpdated)
		count++
		if count >= 5 { // Limit output for quickstart
			break
		}
	}

	if count == 0 {
		fmt.Println("No results found for the query.")
	}
}

Community libraries

While Censys provides official SDKs, the broader developer community may also contribute libraries or tools that interact with the Censys API. These community-driven projects can offer alternative language bindings, specialized utilities, or integrations with other platforms. Developers considering community libraries should evaluate their maintenance status, documentation, and compatibility with the latest Censys API specifications.

For example, projects on platforms like GitHub might offer clients in languages not officially supported by Censys, or provide command-line tools built on top of the official SDKs. It is important to verify the source and security practices of any third-party library before integrating it into a production environment. The User-Agent header, as defined by the IETF in RFC 7231 Section 5.5.3, is often used by API providers to track client usage and can be a useful identifier for community tools.

Developers are encouraged to check the official Censys documentation and community forums for any recommended or notable third-party integrations.