lookup-censys
Skill35 starsChanged 48 days agoMITView on GitHub
Use when you need deep host + certificate reconnaissance for an IP or need to run a Censys search query. Returns services, TLS certificates, ASN, and location. Free tier is severely limited (250 queries/month) — use sparingly. Retrieval only.
In this repository79 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- abuseipdb-apiSkill
- achSkill
- campaign-trackingSkill
- carding-financial-fraudSkill
- censys-apiSkill
- china-cyber-espionageSkill
- claim-extractionSkill
- confidence-levelsSkill
- control-coverage-mappingSkill
- crowdstrike-apiSkill
- cti-hyperloopSkill
- cti-orchestratorSkill
- cti-setupSkill
- darkweb-collectionSkill
- devils-advocacySkill
- domain-investigationSkill
- dprk-cyber-espionageSkill
- feedback-loopsSkill
- greynoise-apiSkill
- hacktivismSkill
- hash-investigationSkill
- horizon-scanningSkill
- indicator-pivotingSkill
- infostealersSkill
- initial-access-brokersSkill
- intelligence-sharingSkill
- intelligence-writingSkill
- ioc-enrichment-workflowSkill
- ioc-exportSkill
- ip-investigationSkill
- iran-cyber-espionageSkill
- key-assumptions-checkSkill
- kql-writingSkill
- likelihood-languageSkill
- lookup-abuseipdbSkill
- lookup-crowdstrikeSkill
- lookup-greynoiseSkill
- lookup-liberty91Skill
- lookup-mispSkill
- lookup-openctiSkill
- lookup-otxSkill
- lookup-ransomwareliveSkill
- lookup-reversinglabsSkill
- lookup-sentinelSkill
- lookup-shodanSkill
- lookup-urlscanSkill
- lookup-virustotalSkill
- malware-analysisSkill
- maturity-assessmentSkill
- mitre-attackSkill
- osint-methodologySkill
- otx-apiSkill
- phishing-social-engineeringSkill
- pir-managementSkill
- quality-controlSkill
- quality-of-information-checkSkill
- ransomware-ecosystemSkill
- reversinglabs-apiSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 151
Default rating for downstream /score-source: A2 (completely reliable, probably true).
- Distinctive: line 155
Quota conservation is critical: Before invoking, consider whether Shodan can answer the question first.
- Distinctive: line 172
Search syntax: https://search.censys.io/search/language
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
lookup-censys
Queries Censys for host and certificate reconnaissance on IPs, or runs a Censys Search query. Retrieval only. Quota-aware — free tier is 250 queries/month.
When to invoke
- Shodan wasn't sufficient and deeper host data is needed
- TLS certificate pivoting (find other hosts sharing a cert)
- Specific Censys Search query required
Do NOT invoke for:
- Bulk enrichment (will exhaust quota)
- IPs you can get from Shodan first
How to invoke
Two CLIs are provided. Pick by capability needed.
Auth note: Censys migrated to a single Personal Access Token (PAT) on the new Platform. The Node CLI uses the legacy Search API (HTTP Basic Auth with
CENSYS_API_ID+CENSYS_API_SECRET); the Python CLI uses the new Platform API (Bearer auth withCENSYS_PAT). New accounts get a PAT — use the Python CLI. Old accounts may still have working legacy credentials and can use either.
Basic host + search — Node CLI (legacy Search API)
node tools/clis/censys.js ip <ip>
node tools/clis/censys.js search "<query>" # Censys Search syntaxRequires CENSYS_API_ID + CENSYS_API_SECRET (legacy). Hits hosts/{ip} or hosts/search.
Full Platform surface — Python CLI (new Censys Platform SDK)
python3 tools/clis/censys.py host <ip> [--at-time ISO8601]
python3 tools/clis/censys.py timeline <ip> --start ISO8601 --end ISO8601
python3 tools/clis/censys.py services <ip>
python3 tools/clis/censys.py search "<query>" [--page-size N] [--page-token TOKEN] [--fields F1,F2]
python3 tools/clis/censys.py aggregate "<query>" --field FIELD [--buckets N] [--filter-by-query]
python3 tools/clis/censys.py certs view <cert_id>
python3 tools/clis/censys.py certs list <id1,id2,...>Requires CENSYS_PAT (new). Self-bootstraps a private venv at tools/clis/.venv-censys/ on first run (installs censys-platform).
Capabilities the Node CLI doesn't have, ordered by CTI value:
- Aggregate — the unsung hero. Aggregations are free (do not consume query credits) and let you ask "how many hosts in this query break down by country / port / ASN / product?" in a single call. Use this BEFORE a search to scope the result set without spending credits.
- Host timeline — the activity history of a single IP between two timestamps. New in Platform.
- At-time host view — see what a host looked like at a past timestamp (Platform-only).
- Service listing — enumerate just the services on a host without the full record.
- Certificate view by ID + certificate list (bulk) — pull cert detail or batch fetch.
- Cursor-based pagination —
--page-tokenfor traversing large result sets.
Examples:
# Free aggregation: count hosts running Cobalt Strike by country (no credits)
python3 tools/clis/censys.py aggregate \
'services.product: "Cobalt Strike Team Server"' \
--field location.country_code
# Free aggregation: ASN distribution of a JARM-fingerprinted cluster
python3 tools/clis/censys.py aggregate \
'services.tls.jarm.fingerprint: "1234567890abcdef..."' \
--field autonomous_system.asn --buckets 50
# What was this IP doing two weeks ago? (Platform-only)
python3 tools/clis/censys.py host 185.220.101.45 \
--at-time 2026-04-12T00:00:00Z
# Daily activity timeline for an IP
python3 tools/clis/censys.py timeline 185.220.101.45 \
--start 2026-04-01T00:00:00Z --end 2026-04-26T00:00:00Z
# Certificate view by ID (the SHA-256 fingerprint)
python3 tools/clis/censys.py certs view 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
# Search hosts and only return specific fields (saves payload)
python3 tools/clis/censys.py search \
'services.tls.certificates.leaf_data.subject.common_name: "*.badcorp.example"' \
--fields ip,location.country_code,services.portBoth CLIs accept --dry-run. Python CLI exits code 2 if CENSYS_PAT is unset; Node CLI exits code 2 if either of the legacy variables is unset. Report missing credentials; do not fabricate.
Free tier reality check (Platform API)
The new Censys Platform tightened free-tier API access. As of 2026, free Community accounts can call these endpoints only:
host— view host detail by IP ✓services— list services on a host ✓timeline— host activity timeline between two timestamps ✓certs view— certificate by ID ✓
These are restricted on free tier (return 403 "endpoint requires organization ID"):
search— paid plan with organization requiredaggregate— paid plan only (no longer free as it was on the legacy API)certs list— likely same restriction
For search / aggregation / pivoting on a free account, use the Censys web UI at https://platform.censys.io/. The web UI has full access; API access for those endpoints is a paid feature.
For CLI use on free tier, the Python CLI is still useful for per-IP enrichment (host, services, timeline) but won't replace the legacy Search API's free aggregations. If you have a legacy account with CENSYS_API_ID + CENSYS_API_SECRET, the Node CLI may give you better free-tier reach for now.
Credits (free tier)
Each per-IP call on a free account counts against the 250 queries/month quota. Be deliberate.
When to use Censys vs Shodan
For bulk infrastructure mapping, prefer Shodan — its free-membership tier ($49 one-time) gives you proper search access, and count is free. Reserve Censys for high-fidelity per-IP enrichment of indicators you've already found elsewhere.
Response format
source: censys
indicator: <IP or search query>
query_time: <ISO8601>
services:
- port: <port>
service: <name>
banner: <truncated>
certificates:
- subject_cn: <common name>
issuer: <issuer>
sha256: <fingerprint>
autonomous_system:
asn: <number>
name: <name>
location:
country: <country>
city: <city>
last_updated: <date>Rate limits
Free tier: 250 queries/month (very limited). Research tier: 10k/month. Paid: unlimited.
Source reliability (Admiralty default)
Default rating for downstream /score-source: A2 (completely reliable, probably true). Censys is an authoritative internet-scan dataset with strong data hygiene.
Operational notes
- Quota conservation is critical. Before invoking, consider whether Shodan can answer the question first.
- For certificate pivoting specifically, Censys is often the right first call — Shodan has weaker cert data.
- Uses HTTP Basic Auth with
$CENSYS_API_IDand$CENSYS_API_SECRET.
Related skills
/lookup-shodan— lighter-weight alternative with higher rate limits/lookup-virustotal— reputation, not reconnaissance/ip-investigation
See also
- Integration setup:
tools/integrations/censys.md - Node CLI source:
tools/clis/censys.js - Python CLI source:
tools/clis/censys.py - Official Python SDK: https://github.com/censys/censys-sdk-python
- API docs: https://docs.censys.com/reference/get-started
- Search syntax: https://search.censys.io/search/language
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

