Censys Python SDK

2.2.19 verified Mon Apr 27 auth: no python

An easy-to-use and lightweight API wrapper for Censys APIs (censys.io). Current version 2.2.19, supports Python 3.8+. Released roughly monthly.

pip install censys

Common errors

error ModuleNotFoundError: No module named 'censys.asm.asm' ↓

cause Import path changed in v2.2.x; the old subpackage was flattened.

fix

Change import to: from censys.asm import CensysAsm

error censys.exceptions.CensysUnauthorizedException: Unauthorized ↓

cause Invalid or missing API credentials.

fix

Set CENSYS_API_ID and CENSYS_API_SECRET environment variables correctly, or pass api_id and api_secret to the constructor.

error TypeError: 'SearchResult' object is not iterable ↓

cause Trying to iterate over the SearchResult object directly instead of calling it.

fix

Call the object: results = c.hosts.search(...); for host in results(): ...

Warnings

deprecated The v1 Search API (CensysCertificates, CensysIPv4) is deprecated since v2.2.18. Use the v2 Search API (CensysSearch) instead. ↓

fix Replace imports: from censys.certificates import CensysCertificates → from censys.search import CensysSearch. See migration guide.

breaking The CensysAsm class moved from censys.asm.asm to censys.asm in v2.2.x. Old import path breaks. ↓

fix Use 'from censys.asm import CensysAsm' instead of 'from censys.asm.asm import CensysAsm'.

gotcha Credentials must be set via environment variables (CENSYS_API_ID, CENSYS_API_SECRET) or passed directly. If both are missing, initialization fails silently. ↓

fix Always set API_ID and API_SECRET before creating any client.

gotcha Search results are lazy and require iteration. The search() method returns a generator; if you don't iterate, no API call is made. ↓

fix Always iterate over results: for result in search_results(): ...

Imports

CensysAsm
wrong
```
from censys import CensysAsm
```
correct
```
from censys.asm import CensysAsm
```
CensysAsm is in the censys.asm submodule, not top-level.

CensysSearch

wrong

from censys import CensysSearch

correct

from censys.search import CensysSearch

CensysSearch is in the censys.search submodule.

CensysCertificates
wrong
```
from censys import CensysCertificates
```
correct
```
from censys.certificates import CensysCertificates
```
CensysCertificates is in the censys.certificates submodule. Deprecated in v2.2.18.
CensysIPv4
wrong
```
from censys import CensysIPv4
```
correct
```
from censys.ipv4 import CensysIPv4
```
CensysIPv4 is in the censys.ipv4 submodule. Deprecated in v2.2.18.

Quickstart

Initialize CensysSearch and CensysAsm with credentials and perform basic queries.

from censys.search import CensysSearch
from censys.asm import CensysAsm

# Initialize with credentials (set via env or directly)
api_id = os.environ.get('CENSYS_API_ID', '')
api_secret = os.environ.get('CENSYS_API_SECRET', '')
c = CensysSearch(api_id=api_id, api_secret=api_secret)

# Search for hosts
results = c.hosts.search("services.service_name: HTTP", per_page=1)
for host in results():
    print(host)

# Use ASM
asm = CensysAsm(api_id=api_id, api_secret=api_secret)
seeds = asm.seeds.list()
print(seeds)