discovered 30 Mar 2026

censys-subdomain-finder

Python ★ 837 via github-topic

AI Summary: The Censys Subdomain Finder is a command-line tool designed to enumerate subdomains associated with a specified domain using Certificate Transparency logs from Censys. It retrieves subdomains that have ever been issued an SSL certificate by a public Certificate Authority, offering features such as output to a text file and support for API authentication. Notably, users must set up an account with Censys to access the API, as free accounts will face limitations beginning in late 2024.

README

Censys subdomain finder

Important note: As of late 2024, Censys does not provide API access to free accounts anymore.

This is a tool to enumerate subdomains using the Certificate Transparency logs stored in Censys Search. It should return any subdomain who has ever been issued a SSL certificate by a public CA.

See it in action:

$ python censys-subdomain-finder.py github.com

[*] Searching Censys for subdomains of github.com
[*] Found 42 unique subdomains of github.com in ~1.7 seconds

  - hq.github.com
  - talks.github.com
  - cla.github.com
  - github.com
  - cloud.github.com
  - enterprise.github.com
  - help.github.com
  - collector-cdn.github.com
  - central.github.com
  - smtp.github.com
  - cas.octodemo.github.com
  - schrauger.github.com
  - jobs.github.com
  - classroom.github.com
  - dodgeball.github.com
  - visualstudio.github.com
  - branch.github.com
  - www.github.com
  - edu.github.com
  - education.github.com
  - import.github.com
  - styleguide.github.com
  - community.github.com
  - server.github.com
  - mac-installer.github.com
  - registry.github.com
  - f.cloud.github.com
  - offer.github.com
  - helpnext.github.com
  - foo.github.com
  - porter.github.com
  - id.github.com
  - atom-installer.github.com
  - review-lab.github.com
  - vpn-ca.iad.github.com
  - maintainers.github.com
  - raw.github.com
  - status.github.com
  - camo.github.com
  - support.enterprise.github.com
  - stg.github.com
  - rs.github.com

Setup

Register an account (free) on https://search.censys.io/register
Browse to https://search.censys.io/account, and set two environment variables with your API ID and API secret:
```
export CENSYS_API_ID=...
export CENSYS_API_SECRET=...
```
Alternatively, you can use a .env file to store these values for persistence across uses:
```
cp .env.template .env
```
Then edit the .env file and set the values for CENSYS_API_ID and CENSYS_API_SECRET.

Clone the repository:

git clone https://github.com/christophetd/censys-subdomain-finder.git

Install the dependencies in a virtualenv:

cd censys-subdomain-finder
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Usage

Sample usage:

python censys-subdomain-finder.py example.com

Output the list of subdomains to a text file:

python censys-subdomain-finder.py example.com -o subdomains.txt

usage: censys-subdomain-finder.py [-h] [-o OUTPUT_FILE]
                                  [--censys-api-id CENSYS_API_ID]
                                  [--censys-api-secret CENSYS_API_SECRET]
                                  domain

positional arguments:
  domain                The domain to scan

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT_FILE, --output OUTPUT_FILE
                        A file to output the list of subdomains to (default:
                        None)
  --censys-api-id CENSYS_API_ID
                        Censys API ID. Can also be defined using the
                        CENSYS_API_ID environment variable (default: None)
  --censys-api-secret CENSYS_API_SECRET
                        Censys API secret. Can also be defined using the
                        CENSYS_API_SECRET environment variable (default: None)

Compatibility

Should run on Python 3.7+.

Notes

The Censys API has a limit rate of 120 queries per 5 minutes window. Each invocation of this tool makes exactly one API call to Censys.

Feel free to open an issue or to tweet @christophetd for suggestions or remarks.