User Guide
Synapse-Censys User Guide
Synapse-Censys adds new Storm commands to allow you to query the Censys API using your existing API key.
Getting Started
Check with your Admin to enable permissions and find out if you need a personal API key.
Censys APIs
Synapse-Censys offers support for the Censys Platform API and the Censys Legacy API. The Censys Legacy API is tentatively scheduled to be decommissioned around December 15, 2025. Synapse-Censys will support the Censys Legacy API until it is fully decommissioned. New users of this Power-Up are encouraged to work with the Censys Platform commands instead of the Legacy commands. The list of commands by API is shown below.
Censys Platform API Commands
censys.config.addcensys.config.delcensys.config.listcensys.config.showcensys.config.updatecensys.config.migratecensys.platform.certs.downloadcensys.platform.certs.enrichcensys.platform.certs.observationscensys.platform.hosts.enrichcensys.platform.hosts.historycensys.platform.search
Censys Legacy API Commands
censys.setup.apikeycensys.setup.tagprefixcensys.apiinfocensys.certs.enrichcensys.certs.observationscensys.certs.searchcensys.certs.subdomainscensys.hosts.certscensys.hosts.domaincensys.hosts.enrichcensys.hosts.historycensys.hosts.namescensys.hosts.search
Examples
Setting your personal API key
To set-up a personal use API key:
> censys.config.add --scope self mycensys myapikey myorgid
Synapse-Censys config "mycensys" added
Use censys.platform.search to discover hosts and certificates
The censys.platform.search command can be used to discover hosts
and populate inet:flow nodes:
> censys.platform.search "packages.vertex.link" --yield | limit 4
inet:flow=bb330296814d81cd1bb12f0227d20d55
.created = 2025/10/30 12:07:42.949
.seen = ('2025/09/23 13:43:30.000', '2025/09/23 13:43:30.001')
:dst = tcp://138.197.35.191:22
:dst:cpes = ['cpe:2.3:a:openbsd:openssh:9.6p1:*:*:*:*:*:*:*']
:dst:handshake = SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.11
:dst:ipv4 = 138.197.35.191
:dst:port = 22
:dst:proto = tcp
:dst:softnames = ['openssh']
:dst:ssh:key = f8777c2a04efc01bde923374d231b679
:time = 2025/09/23 13:43:30.000
inet:flow=f1b417f36b918129721a6568913c1c09
.created = 2025/10/30 12:07:42.973
.seen = ('2025/09/24 03:43:28.000', '2025/09/24 03:43:28.001')
:dst = tcp://138.197.35.191:443
:dst:handshake = HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Date: <REDACTED>
X-Content-Type-Options: nosniff
Etag: "e3cacf0b0e4eb603dcbbd75e2870bfc063043b83"
Content-Length: 2611
Set-Cookie: _xsrf=2|57a7469b|b4d0dd58dbbcfe6ac6ff45dfaf06f7b7|1758685408; Path=/
:dst:ipv4 = 138.197.35.191
:dst:port = 443
:dst:proto = tcp
:time = 2025/09/24 03:43:28.000
crypto:x509:cert=a2ee3f887a53ef8f42169b95106498b9
.created = 2025/10/30 12:07:43.028
.seen = ('2025/04/04 13:14:18.000', '2025/07/04 22:38:28.001')
:file = sha256:00f8874fa5ddf6262492863687b569059c5e0c2c29ca0c2d52435d809b1387f5
:identities:fqdns = ['packages.vertex.link']
:issuer = C=US, O=Let's Encrypt, CN=E6
:md5 = b494cb7570f4cc202a3fc5ffbb7a4a01
:serial = 000005b292baa3f511f178eaa524410cc141f4dc
:sha1 = ec856f825c73edd481a210e11492ba4d7ade185f
:sha256 = 00f8874fa5ddf6262492863687b569059c5e0c2c29ca0c2d52435d809b1387f5
:subject = CN=packages.vertex.link
:validity:notafter = 2025/07/03 12:11:21.000
:validity:notbefore = 2025/04/04 12:11:22.000
crypto:x509:cert=579fbe1131d7870ce590d6711485ecc1
.created = 2025/10/30 12:07:42.968
.seen = ('2025/09/05 13:08:45.000', '2025/09/24 03:43:28.001')
:algo = 1.2.840.10045.4.3.3
:file = sha256:4f87d55e5a8be2c65fb5f29d61466c0532609b1bfe28102b910f03d320a4cbf3
:identities:fqdns = ['packages.vertex.link']
:issuer = C=US, O=Let's Encrypt, CN=E8
:md5 = 98a24c846c5f91d34396b9b2da4f7d31
:serial = 000006e4648c710905d9d82888ac077914700253
:sha1 = 828dc16683b153909023574789122a7bdced9035
:sha256 = 4f87d55e5a8be2c65fb5f29d61466c0532609b1bfe28102b910f03d320a4cbf3
:signature = 3065023100826cd816ad170417b3600daf67b0301abe8875a5012dba37e50f3c45e980ee8b639f8fe22c3308db78cfe7bd876d4c960230322e5d6b1dc988e20d2a1afd36c7c2c380eaa95c6defef5d474005322b018ee29c00a849c08796c63507a7e1d40c8dc8
:subject = CN=packages.vertex.link
:validity:notafter = 2025/12/04 12:05:09.000
:validity:notbefore = 2025/09/05 12:05:10.000
:version = v3
This will also populate an it:exec:query node to represent the search
query syntax:
> it:exec:query:text~=vertex +{ <(seen)- meta:source:type=synapse.censys }
it:exec:query=2d878eee3c86eeef6fb799060ac183cb
.created = 2025/10/30 12:07:42.904
:api:url = https://api.platform.censys.io/v3/global/search/query
:language = censys query language (cenql)
:synuser = root
:text = packages.vertex.link
:time = 2025/10/30 12:07:42.904
The it:exec:query node will also be linked to the resulting inet:flow and crypto:x509:cert nodes
via -(found)> lightweight edge:
> it:exec:query:text~=vertex -(found)> (inet:flow, crypto:x509:cert) | limit 2
inet:flow=f1b417f36b918129721a6568913c1c09
.created = 2025/10/30 12:07:42.973
.seen = ('2025/09/24 03:43:28.000', '2025/09/24 03:43:28.001')
:dst = tcp://138.197.35.191:443
:dst:handshake = HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Date: <REDACTED>
X-Content-Type-Options: nosniff
Etag: "e3cacf0b0e4eb603dcbbd75e2870bfc063043b83"
Content-Length: 2611
Set-Cookie: _xsrf=2|57a7469b|b4d0dd58dbbcfe6ac6ff45dfaf06f7b7|1758685408; Path=/
:dst:ipv4 = 138.197.35.191
:dst:port = 443
:dst:proto = tcp
:time = 2025/09/24 03:43:28.000
crypto:x509:cert=a2ee3f887a53ef8f42169b95106498b9
.created = 2025/10/30 12:07:43.028
.seen = ('2025/04/04 13:14:18.000', '2025/07/04 22:38:28.001')
:file = sha256:00f8874fa5ddf6262492863687b569059c5e0c2c29ca0c2d52435d809b1387f5
:identities:fqdns = ['packages.vertex.link']
:issuer = C=US, O=Let's Encrypt, CN=E6
:md5 = b494cb7570f4cc202a3fc5ffbb7a4a01
:serial = 000005b292baa3f511f178eaa524410cc141f4dc
:sha1 = ec856f825c73edd481a210e11492ba4d7ade185f
:sha256 = 00f8874fa5ddf6262492863687b569059c5e0c2c29ca0c2d52435d809b1387f5
:subject = CN=packages.vertex.link
:validity:notafter = 2025/07/03 12:11:21.000
:validity:notbefore = 2025/04/04 12:11:22.000
For query syntax details, see the Censys Query Language.
Use censys.platform.search to discover subdomains for an FQDN using the Censys cert names field
> censys.platform.search "cert.names: vertex.link" --yield | -> inet:fqdn | limit 4
inet:fqdn=packages.vertex.link
.created = 2025/10/30 12:07:42.928
:domain = vertex.link
:host = packages
:issuffix = false
:iszone = false
:zone = vertex.link
inet:fqdn=swarm.do.vertex.link
.created = 2025/10/30 12:07:43.114
:domain = do.vertex.link
:host = swarm
:issuffix = false
:iszone = false
:zone = vertex.link
inet:fqdn=feeds01.vertex.link
.created = 2025/10/30 12:07:43.125
:domain = vertex.link
:host = feeds01
:issuffix = false
:iszone = false
:zone = vertex.link
inet:fqdn=enterprise.docs.vertex.link
.created = 2025/10/30 12:07:43.134
:domain = docs.vertex.link
:host = enterprise
:issuffix = false
:iszone = false
:zone = vertex.link
Use censys.platform.search to search hosts by an FQDN
> censys.platform.search "host.dns.names: vertex.link" --yield | limit 4
inet:flow=80e04813be0b4e93720396a57c19ea40
.created = 2025/10/30 12:07:43.702
.seen = ('2025/09/24 13:46:58.000', '2025/09/24 13:46:58.001')
:dst = tcp://[2606:4700::6812:1a3]:80
:dst:cpes = ['cpe:2.3:a:cloudflare:cloudflare_load_balancer:*:*:*:*:*:*:*:*', 'cpe:2.3:a:cloudflare:waf:*:*:*:*:*:*:*:*']
:dst:handshake = HTTP/1.1 403 Forbidden
Date: <REDACTED>
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: close
X-Frame-Options: SAMEORIGIN
Referrer-Policy: same-origin
Cache-Control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Expires: Thu, 01 Jan 1970 00:00:01 GMT
Vary: Accept-Encoding
Server: cloudflare
CF-RAY: 9842bb296e87852d-HKG
Content-Encoding: gzip
:dst:ipv6 = 2606:4700::6812:1a3
:dst:port = 80
:dst:proto = tcp
:dst:softnames = ['cloudflare_load_balancer', 'waf']
:time = 2025/09/24 13:46:58.000
inet:flow=d0b9bca67061b8878d6d2458e7939ca5
.created = 2025/10/30 12:07:43.752
.seen = ('2025/09/24 13:39:46.000', '2025/09/24 13:39:46.001')
:dst = tcp://[2606:4700::6812:1a3]:443
:dst:handshake = HTTP/1.1 400 Bad Request
Server: cloudflare
Date: Wed, 24 Sep 2025 13:39:52 GMT
Content-Type: text/html
Content-Length: 253
Connection: close
CF-RAY: -
<html>
<head><title>400 The plain HTTP request was sent to HTTPS port</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<center>The plain HTTP request was sent to HTTPS port</center>
<hr><center>cloudflare</center>
</body>
</html>
:dst:ipv6 = 2606:4700::6812:1a3
:dst:port = 443
:dst:proto = tcp
:time = 2025/09/24 13:39:46.000
inet:flow=fd7127f8899744821486c10f15fabaa2
.created = 2025/10/30 12:07:43.790
.seen = ('2025/09/24 06:42:55.000', '2025/09/24 06:42:55.001')
:dst = tcp://157.245.248.76:22
:dst:cpes = ['cpe:2.3:a:openbsd:openssh:9.0p1:*:*:*:*:*:*:*']
:dst:handshake = SSH-2.0-OpenSSH_9.0p1 Ubuntu-1ubuntu7.1
:dst:ipv4 = 157.245.248.76
:dst:port = 22
:dst:proto = tcp
:dst:softnames = ['openssh']
:dst:ssh:key = 551929a5e3226f567036a0625822f086
:time = 2025/09/24 06:42:55.000
inet:flow=8541ce487c8d53a39a5e3683b7950678
.created = 2025/10/30 12:07:43.806
.seen = ('2025/09/24 01:19:20.000', '2025/09/24 01:19:20.001')
:dst = tcp://157.245.248.76:8080
:dst:handshake = HTTP/1.1 302
Location: https://157.245.248.76:8443/
Content-Length: 0
Date: <REDACTED>
:dst:ipv4 = 157.245.248.76
:dst:port = 8080
:dst:proto = tcp
:time = 2025/09/24 01:19:20.000
Use of meta:source nodes
Synapse-Censys uses a meta:source node and -(seen)> light
weight edges to track nodes observed from the Censys API.
> meta:source=056c3c0aeea99449d7edbfad4537cf9f
meta:source=056c3c0aeea99449d7edbfad4537cf9f
.created = 2025/10/30 12:07:42.603
:name = censys api
:type = synapse.censys
Storm can be used to filter nodes to include/exclude nodes which have been observed by Synapse-Censys. The following example shows how to filter the results of a query to include only results observed by Synapse-Censys:
> inet:ipv4:loc=us +{ <(seen)- meta:source:type=synapse.censys }
inet:ipv4=157.245.248.76
.created = 2025/10/30 12:07:43.761
:asn = 14061
:latlong = 40.80427,-74.01208
:loc = us
:type = unicast
inet:ipv4=138.197.35.191
.created = 2025/10/30 12:07:42.918
:asn = 14061
:latlong = 40.8344,-74.1377
:loc = us
:type = unicast