censysCensys search engine for internet-connected hosts, TLS certificates, and web properties. Use when: certificate transparency monitoring, finding hosts by certificate fingerprint, alternative to Shodan for TLS/SSL analysis, discovering hosts running specific services, or tracking infrastructure changes via cert issuance.
Independent GitHub snapshot · Automated classification · Original documentation governs
Censys continuously scans the entire internet and indexes every reachable host, certificate, and web property with details about open ports, TLS/SSL certificates, service banners, and configurations. Censys is particularly strong for certificate-based discovery — it indexes certificate transparency logs and lets you pivot from certificate subject names to IP addresses and vice versa, which is excellent for finding unknown infrastructure tied to a target organization.
Censys retired its old Search v1/v2 API and the censys PyPI package in favor of the unified Censys Platform, queried with CenQL (Censys Query Language) through the censys-platform SDK or the censys search CLI. Authenticate with a Personal Access Token, not the old API ID/secret pair.
Requires: a Censys account and a Personal Access Token (create one from the Platform console under your user menu → API Access). Free accounts get a limited monthly search-credit allowance that Censys adjusts over time — check the current limits on your account's billing page rather than assuming a fixed number.
pip install censys-platform
export CENSYS_API_KEY="your-personal-access-token"
export CENSYS_ORGANIZATION_ID="your-organization-id" # shown on the Personal Access Tokens page
import os
from censys_platform import SDK
sdk = SDK(
organization_id=os.environ["CENSYS_ORGANIZATION_ID"],
personal_access_token=os.environ["CENSYS_API_KEY"],
)
SDK is also a context manager (with SDK(...) as sdk:), which closes the underlying HTTP session for you. Every method has an _async counterpart (sdk.global_data.search_async(...)) for use inside asyncio code.
CenQL queries start with a dataset prefix — host., cert., or webproperty. — and use = for an exact, case-sensitive match or : for a case-insensitive tokenized match.
def search_hosts(query, page_size=50, fields=None):
"""Search the Censys Platform for hosts matching a CenQL query."""
if fields is None:
fields = [
"host.ip",
"host.services.port",
"host.services.protocol",
"host.autonomous_system.name",
"host.location.country",
]
res = sdk.global_data.search(search_query_input_body={
"query": query,
"fields": fields,
"page_size": page_size,
})
for hit in res.result.hits:
print(hit)
return res
# Hosts serving a TLS cert naming a domain (any SAN)
search_hosts('host.services.cert.names = "beacontowersecurity.com"')
# Exposed Redis instances outside an internal range
search_hosts('host.services: (protocol = "REDIS") and not host.ip: "10.0.0.0/8"')
# Hosts in a specific organization's ASN, on port 443
search_hosts('host.autonomous_system.organization = "Beacon Tower Security" and host.services.port = 443')
host = sdk.global_data.get_host(host="203.0.113.42")
print(host.result.ip, host.result.autonomous_system, host.result.location)
cert = sdk.global_data.get_certificate(fingerprint="a1b2c3d4e5f6...")
print(cert.result.names, cert.result.issuer)
def find_hosts_by_domain_cert(domain):
"""Find hosts serving a TLS certificate that names this domain (any SAN)."""
res = sdk.global_data.search(search_query_input_body={
"query": f'host.services.cert.names = "{domain}"',
"fields": ["host.ip", "host.services.port", "host.services.cert.names",
"host.autonomous_system.name", "host.location.country"],
"page_size": 100,
})
for hit in res.result.hits:
print(hit)
return res
find_hosts_by_domain_cert("beacontowersecurity.com")
# Distribution of countries for hosts running nginx
agg = sdk.global_data.aggregate(
aggregation_input_body={
"query": 'host.services.endpoints.http.headers: (key = "Server" and value = "nginx")',
"field": "host.location.country",
"num_buckets": 15,
}
)
for bucket in agg.result.buckets:
print(bucket.key, bucket.count)
# The Platform CLI (cencli) mirrors the SDK for one-off lookups and scripting.
# It ships as a standalone binary, not a pip package.
brew install censys/tap/cencli
censys auth login
censys search 'host.services.cert.names = "beacontowersecurity.com"'
find_hosts_by_domain_cert("beacontowersecurity.com")
Result: prints each matching host's IP, open port, the certificate's subject/SAN names, issuer, ASN, and country — including boxes the security team never registered in DNS but that still present a valid cert for the domain (shadow IT).
agg = sdk.global_data.aggregate(
aggregation_input_body={
"query": 'host.services.endpoints.http.headers: (key = "Server" and value = "nginx") '
'and host.autonomous_system.asn = 16509',
"field": "host.location.country",
"num_buckets": 10,
}
)
for bucket in agg.result.buckets:
print(bucket.key, bucket.count)
Result: a ranked list of countries by nginx host count within ASN 16509, letting the reviewer spot an unexpected region before pulling the full per-host detail.
| Query | Description |
|---|---|
host.services.port = 443 | Hosts with port 443 open |
host.services: (protocol = "HTTP") | Hosts running HTTP |
host.services.cert.names = "beacontowersecurity.com" | Any TLS cert naming the domain |
cert.names: "beacontowersecurity.com" | Certificate records (not hosts) naming the domain |
host.autonomous_system.name = "AMAZON-02" | Hosts in a named ASN |
host.autonomous_system.asn = 16509 | Hosts in ASN 16509 |
host.location.country = "Germany" | Hosts in Germany |
host.ip: "198.51.100.0/24" | Hosts in a CIDR range |
webproperty.services.http.response.html_title: "Kibana" | Exposed Kibana instances |
from censys.search import CensysHosts or the old services.*: query syntax targets the discontinued Search v1/v2 API — migrate it to censys-platform and CenQL.