Censys

---
name: censys
description: "Expert agent for Censys ASM and Censys Search. Covers internet-wide scanning, certificate transparency, Censys ASM platform, risk scoring, exposure discovery, and the Censys Search API for threat hunting and security research. WHEN: \"Censys\", \"Censys ASM\", \"Censys Search\", \"internet scanning\", \"certificate transparency\", \"Censys API\", \"internet-wide scan\"."
license: MIT
---

# Censys

This skill covers Censys -- both Censys ASM (Attack Surface Management) and Censys Search (internet-wide scanning and security research platform). It has expertise in Censys's internet scanning infrastructure, certificate transparency analysis, ASM asset discovery and risk scoring, the Censys Search query language, and the Censys API for programmatic access to internet scan data.

## How to Approach Tasks

1. **Classify** the request:
   - **Censys ASM** -- Enterprise EASM product: asset discovery, risk management, exposure monitoring
   - **Censys Search** -- Public/research platform: internet-wide scanning, host enumeration, threat hunting
   - **API usage** -- Programmatic access for custom integrations, threat hunting automation
   - **Certificate analysis** -- TLS certificate research, subdomain discovery, cert transparency

2. **Distinguish ASM vs. Search:**
   - **Censys Search** (`search.censys.io`): Public platform; query internet scan data; used for research, threat hunting, security assessments
   - **Censys ASM**: Enterprise product; continuous monitoring of your organization's assets; EASM workflows

## Censys Internet Scanning Infrastructure

### How Censys Scans the Internet

Censys independently scans the entire internet (IPv4 space + IPv6 sampling) using:

**ZMap and ZGrab (open source tools, developed at Censys):**
- **ZMap:** High-speed network scanner (can scan entire IPv4 space in ~45 minutes)
- **ZGrab:** Application layer banner grabbing (identifies service versions)

**What Censys indexes:**
- All IPv4 addresses (4.3 billion)
- Open ports and services on each IP
- Service banners and protocol responses
- TLS/SSL certificates (from HTTPS, SMTPS, IMAPS, etc.)
- HTTP/HTTPS response data (headers, page content, title)
- DNS data
- Software versions and technology fingerprints

**Scan frequency:** Most common ports re-scanned daily; full port scans on longer cycles.

**Certificate Transparency Logs:**
- Censys monitors CT logs (all publicly trusted TLS certificates)
- Enables subdomain discovery via certificate SANs
- Tracks certificate issuance, expiry, and revocation
- Provides historical certificate data

## Censys Search

### Censys Search Interface

**URL:** https://search.censys.io

**Datasets:**
- **Hosts** (`hosts.censys.io`): Search internet-exposed hosts by IP, service, certificate, and more
- **Certificates** (`search.censys.io/certificates`): Search TLS certificates by domain, organization, issuer

### Censys Query Language (CQL)

Censys uses structured search syntax for filtering:

**Host search examples:**
```
# Find hosts with Elasticsearch open to internet (default port, no auth)
services.port=9200 AND services.service_name=ELASTICSEARCH

# Find specific software version (Apache 2.4.49 -- CVE-2021-41773)
services.http.response.headers.server="Apache/2.4.49"

# Find RDP exposed globally
services.port=3389 AND services.service_name=RDP

# Find exposed Kubernetes API servers
services.port=6443 AND services.service_name=KUBERNETES

# Find self-signed certificates on HTTPS
services.tls.certificate.parsed.issuer.common_name:
  services.tls.certificate.parsed.subject.common_name

# Find expired TLS certificates
services.tls.certificate.parsed.validity.end:[* TO 2024-01-01]

# Find hosts with specific certificate (by org name)
services.tls.certificate.parsed.subject.organization="ACME Corp"

# Find hosts running Cobalt Strike (known C2 fingerprint)
services.tls.certificate.parsed.subject.common_name="Major Cobalt Strike"

# Find Jenkins instances
services.http.response.html_title="Dashboard [Jenkins]"

# Find phpmyadmin instances
services.http.response.html_title="phpMyAdmin"
```

**Certificate search examples:**
```
# Find all certificates for a domain
parsed.names: company.com

# Find certificates with specific subdomain
parsed.names: *.dev.company.com

# Find wildcard certificates for org
parsed.subject.organization: "ACME Corp" AND parsed.names: "*.*"

# Find recently issued certificates (last 30 days)
parsed.validity.start:[2024-12-01 TO *]
AND parsed.subject.organization: "ACME Corp"

# Find certificates about to expire
parsed.validity.end:[2024-12-01 TO 2025-01-01]
AND parsed.subject.organization: "ACME Corp"
```

### Practical Security Research Use Cases

**1. Reconnaissance against your own infrastructure:**
```
# Find all ACME Corp internet-exposed hosts
services.tls.certificate.parsed.subject.organization="ACME Corp"
```

**2. Find shadow IT / forgotten systems:**
```
# Services with company SSL cert but not in known IP range
services.tls.certificate.parsed.subject.organization="ACME Corp"
AND NOT ip:[198.51.100.0/24]
```

**3. Track vulnerability exposure after CVE announcement:**
```
# After Log4Shell: How many Log4j-affected systems exposed?
services.software.product=log4j AND services.software.version:[2.0 TO 2.14.1]
```

**4. Monitor for new exposed services:**
Use Censys ASM or the API to get alerts when new hosts matching your seeds appear.

## Censys ASM (Enterprise)

### What Censys ASM Provides

Censys ASM is the commercial EASM product built on Censys's internet scanning infrastructure.

**Core capabilities:**
- **Automated asset discovery:** Uses Censys scan data + certificate transparency to discover your external assets
- **Continuous monitoring:** Daily refresh; alerts on new assets and exposure changes
- **Risk scoring:** Each asset and finding scored by severity
- **Exposure inventory:** All internet-facing assets in a managed inventory
- **Integration:** API, webhooks, Splunk, ServiceNow

### ASM Onboarding

1. Sign up for Censys ASM (paid enterprise product)
2. Provide seeds:
   - Domains (company.com, subsidiaries)
   - IP ranges (owned CIDR blocks)
   - ASNs (BGP autonomous system numbers)
3. Censys queries its internet database against seeds
4. Initial results typically available within 4-8 hours

### ASM Asset States

- **Confirmed:** Validated as belonging to your organization
- **Candidate:** Discovered but pending attribution review
- **Dismissed:** Not your asset

### Risk Scoring in Censys ASM

Findings scored by:
- **Severity:** Critical, High, Medium, Low, Info
- **Exposure type:** Open management port, outdated software, expired certificate, public cloud misconfiguration
- **CVSS + exploit data:** CVE severity combined with known exploitation
- **Asset importance:** Internet-facing production vs. development

**Finding categories:**
- Open risk ports (RDP, SSH, telnet, database ports)
- Certificate issues (expired, expiring, self-signed, weak cipher)
- Known vulnerabilities (CVEs on detected software versions)
- Software EoL (End-of-Life software versions)
- Misconfigured cloud storage (public S3, Blob)

## Censys API

The Censys API provides programmatic access to internet scan data.

**Authentication:** API ID + API Secret (from search.censys.io account)

**Python library:** `pip install censys`

### Search API Examples

```python
from censys.search import CensysHosts, CensysCertificates

# Initialize with API credentials
h = CensysHosts()
c = CensysCertificates()

# Search for exposed Elasticsearch instances
query = "services.port=9200 AND services.service_name=ELASTICSEARCH"
for page in h.search(query, per_page=100):
    for host in page:
        print(f"IP: {host['ip']}, Services: {[s['port'] for s in host.get('services', [])]}")

# Search certificates for a domain
cert_query = "parsed.names: *.company.com"
for cert in c.search(cert_query, fields=["parsed.subject_dn", "parsed.names", 
                                          "parsed.validity.end"]):
    print(f"Subject: {cert.get('parsed.subject_dn')}")
    print(f"Names: {cert.get('parsed.names')}")
    print(f"Expires: {cert.get('parsed.validity.end')}")
```

**Host details lookup:**
```python
from censys.search import CensysHosts

h = CensysHosts()

# Get full details for a specific host
host = h.view("1.2.3.4")
print(f"IP: {host['ip']}")
for service in host.get('services', []):
    print(f"  Port {service['port']}: {service.get('service_name', 'unknown')}")
    if 'tls' in service:
        cert = service['tls']['certificate']['parsed']
        print(f"  TLS CN: {cert['subject'].get('common_name', '')}")
        print(f"  Expires: {cert['validity']['end']}")
```

**Aggregate/facets for scale:**
```python
# Count exposed RDP by country
results = h.aggregate(
    query="services.port=3389",
    field="location.country_code",
    num_buckets=10
)
for bucket in results['buckets']:
    print(f"{bucket['key']}: {bucket['count']:,} hosts")
```

### ASM API

```python
import requests

BASE_URL = "https://app.censys.io/api/v2"
headers = {
    "Censys-Api-Id": "YOUR_API_ID",
    "Censys-Api-Secret": "YOUR_API_SECRET"
}

# List all confirmed ASM assets
response = requests.get(
    f"{BASE_URL}/assets/asm/hosts",
    headers=headers,
    params={"filter": "status=CONFIRMED", "pageSize": 100}
)

for asset in response.json().get("assets", []):
    print(f"IP: {asset['ip']}, Risk Score: {asset.get('riskScore', 'N/A')}")
```

## Censys for Threat Hunting

Censys Search is widely used by threat hunters and incident responders:

**Finding attacker infrastructure:**
```
# Find Cobalt Strike team servers (known certificate fingerprint)
services.tls.certificate.parsed.subject.common_name=
  "Major Cobalt Strike" AND 
services.port=443

# Find Metasploit listeners (default cert)
services.tls.certificate.parsed.issuer.common_name="MetasploitSelfSignedCA"

# Find C2 infrastructure with known JA3S fingerprints
# (JA3S fingerprints specific malware families' TLS servers)
services.tls.ja3s=MALWARE_JA3S_HASH
```

**Vulnerability exposure research:**
```
# After a major vulnerability -- find exposed vulnerable systems globally
# (For patching prioritization or threat intelligence research)
services.http.response.headers.server="nginx/1.22.0"
# Cross-ref with CVEs affecting nginx 1.22.0
```

**Brand protection / phishing detection:**
```
# Find recently issued certs with company name in subject
parsed.subject.organization: "ACME Corp" AND
parsed.validity.start:[* TO 2025-01-01] AND
NOT parsed.issuer.organization: "ACME Corp"
```