DOCSEARCHbyAlgolia
Submit Docs

censys-python

repository·main·Indexed 19 days ago

https://github.com/censys/censys-python

A lightweight Python 3.8+ API wrapper and CLI for Censys APIs (censys.io). It enables users to search Censys data, perform bulk certificate lookups, download bulk data, and manage assets and events in Censys Attack Surface Management (ASM). The library provides specialized clients including SearchClient, CensysHosts, CensysCerts, and AsmClient.

Tokens
31.8K
Snippets
63
Records
100
Agent score
66%

What's inside censys-python

  1. Available Search and ASM usage examples

    main

    The repository contains several specialized scripts demonstrating common tasks. You can find them in the examples/ directory:

    Search Tasks

    • Hosts: Viewing individual hosts, searching hosts, aggregating host data, bulk viewing, metadata retrieval, viewing host events, host names, and host diffs.
    • Certificates: Viewing certificates, searching certificates, and reporting certificates.

    ASM Tasks

    • Cloud host counts, host risks, domain/subdomain retrieval, and bulk seed addition from CSV.

  2. Explore the censys.search package API versions

    main

    The censys.search package provides access to Censys search capabilities through two distinct API versions. Depending on your requirements and the specific endpoints you need to access, you should use either the v1 or v2 submodules:

    • censys.search.v1: Access to the first version of the Censys Search API.
    • censys.search.v2: Access to the second version of the Censys Search API.

    Refer to the specific submodule documentation to determine which version supports the queries and data structures you require.

  3. How Censys Search API v2 works

    main

    The Censys Search API v2 provides access to Censys resources through three primary functional endpoints:

    1. search: Performs searches against an index (like Hosts) using the same syntax as the Censys web app.
    2. view: Retrieves structured data for a specific resource using its natural ID.
    3. aggregate: Provides an aggregated view of resources based on specific attributes, similar to the Report Builder in the web app.

    To use these, you must initialize a Python class object for the specific resource index you are targeting.

  4. How the Censys ASM API clients work

    main

    The Censys ASM API provides programmatic access to several endpoints. You can interact with these endpoints in two ways:

    1. Individual Resource Classes: Initialize specific classes for each resource type (e.g., Seeds, Assets, Logbook, Risks, InventorySearch, SavedQueries).
    2. AsmClient: Initialize a single AsmClient object which wraps all individual API clients into one object for ease of use.

    Available resource types include:

    • seeds: Programmatic management of seeds.
    • assets: Data for hosts, certificates, domains, etc., including tag and comment management.
    • logbook: Logbook events with filtering capabilities.
    • risks: Risk data for hosts, certificates, and domains.
    • inventory: Search for assets based on various criteria.
    • web_entities: Web entities instances and management.
    • saved_queries: Management of saved queries.
    from censys.asm import AsmClient

# Using the unified client
client = AsmClient()
client.seeds.get_seeds()
client.domains.get_assets()
client.logbook.get_events()

  5. Set up the development environment

    main

    To contribute to the censys-python repository, clone the source code and install the project dependencies using poetry.

    1. Clone the repository using your preferred method (SSH, HTTPS, or GitHub CLI).
    2. Navigate to the project directory.
    3. Run poetry install to set up the environment and install all necessary dependencies.
    # Clone the repository
git clone https://github.com/censys/censys-python.git

# Install dependencies
cd censys-python/
poetry install

  6. Configure the Censys CLI

    main

    Before using the CLI, you must configure your credentials using the censys config command.

    By default, the configuration file is stored at ~/.config/censys/censys.cfg. You can override this location by setting the CENSYS_CONFIG_PATH environment variable.

    To enable tab completion for the CLI (including autocomplete for field names in the search command), add the following line to your shell configuration file (e.g., ~/.bashrc or ~/.zshrc):

    # Configure credentials
censys config

# Change config location
export CENSYS_CONFIG_PATH=/path/to/config/file

# Enable tab completion
eval "$(register-python-argcomplete censys)"

  7. Install the Censys Python Library

    main

    You can install the censys library using pip. It requires Python 3.8 or higher.

    To install:

    pip install censys

    To upgrade to the latest version:

    pip install --upgrade censys

    If you are developing locally using poetry, you can install dependencies by cloning the repository and running:

    git clone https://github.com/censys/censys-python.git
cd censys-python/
poetry install
    pip install censys

  9. Retrieve account information and quota using CensysHosts

    main

    The censys.search.v2.CensysHosts class allows you to interact with account-level information, including general account data and current query quotas.

    from censys.search import CensysHosts

c = CensysHosts()

# Gets account data
account = c.account()
print(account)

# Gets account quota
quota = c.quota()
print(quota)

  10. Initialize Censys resource indices

    main

    Python class objects must be initialized for each specific resource index you wish to interact with. The two main indices are:

    • CensysHosts: For interacting with the Hosts index.
    • CensysCerts: For interacting with the Certificates index.
    from censys.search import CensysHosts, CensysCerts

hosts_client = CensysHosts()
certs_client = CensysCerts()

  12. Configure proxies for CensysHosts

    main

    When initializing a CensysHosts instance, you can provide a proxies dictionary to route your requests through a proxy server. The dictionary should follow the standard requests library format.

    Important Note: HTTP proxies will be ignored; you must provide an https proxy configuration to ensure it is used.

    from censys.search import CensysHosts

proxies = {
    "https": "http://10.10.1.10:1080",
}

c = CensysHosts(proxies=proxies)

c.account()