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.
Examples
Setting your personal API key
To set-up a personal use API key:
> censys.setup.apikey --self myapiid myapisecret
Setting Synapse-Censys API key for the current user.
Use censys.hosts.search to discover hosts
The censys.hosts.search command can be used to discover hosts
and populate inet:ipv4 (or inet:ipv6) nodes:
> censys.hosts.search "services.service_name: 'HTTP' AND services.service_name: 'Telnet'" --yield --size 2
inet:ipv4=1.0.70.70
.created = 2024/11/19 21:06:09.539
:asn = 18144
:latlong = 34.3978,132.4525
:loc = jp
:type = unicast
inet:ipv4=1.0.99.233
.created = 2024/11/19 21:06:10.170
:asn = 18144
:latlong = 35.4979,134.2309
:loc = jp
:type = unicast
This will also populate an it:exec:query node to represent the search
query syntax:
> it:exec:query:text~=Telnet +{ <(seen)- meta:source:name="censys api" }
it:exec:query=39042b4888f72d0ff9b30407a592d0bb
.created = 2024/11/19 21:06:09.406
:api:url = https://search.censys.io/api/v2/hosts/search
:language = censys
:text = services.service_name: 'HTTP' AND services.service_name: 'Telnet'
:time = 2024/11/19 21:06:09.363
The it:exec:query node will also be linked to the resulting inet:ipv4 nodes
via -(found)> light-weight edges:
> it:exec:query:text~=Telnet -(found)> inet:ipv4
inet:ipv4=1.0.99.233
.created = 2024/11/19 21:06:10.170
:asn = 18144
:latlong = 35.4979,134.2309
:loc = jp
:type = unicast
inet:ipv4=1.0.70.70
.created = 2024/11/19 21:06:09.539
:asn = 18144
:latlong = 34.3978,132.4525
:loc = jp
:type = unicast
An inet:server and inet:tls:servercert node will be created if possible.
To populate the inet:flow for this host use censys.hosts.enrich.
For query syntax details, see the Censys Hosts Search 2.0 Syntax.
Use censys.hosts.enrich to populate inet:flow nodes
The censys.hosts.enrich command can be used to populate inet:flow
nodes for a given inet:ipv4 or inet:ipv6 node.
> [ inet:ipv4=23.23.240.248 ] | censys.hosts.enrich --yield
inet:flow=352957b369423c675958f99adc516ed5
.created = 2024/11/19 21:06:11.115
.seen = ('2023/06/13 02:59:55.617', '2023/06/13 02:59:55.618')
:dst = tcp://23.23.240.248:22
:dst:cpes = ['cpe:2.3:a:openbsd:openssh:8.2:p1:*:*:*:*:*:*', 'cpe:2.3:o:canonical:ubuntu_linux:20.04:*:*:*:*:*:*:*']
:dst:handshake = SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.4
:dst:ipv4 = 23.23.240.248
:dst:port = 22
:dst:proto = tcp
:dst:softnames = ['linux', 'openssh']
:dst:ssh:key = 55bb1c3a71ae557b4f31679c14be645a
:time = 2023/06/13 02:59:55.617
inet:flow=778e18d64d17c5ab6250dc2c46992445
.created = 2024/11/19 21:06:11.527
.seen = ('2023/06/13 13:00:20.065', '2023/06/13 13:00:20.066')
:dst = tcp://23.23.240.248:80
:dst:cpes = ['cpe:2.3:a:f5:nginx:1.18.0:*:*:*:*:*:*:*']
:dst:handshake = HTTP/1.1 301 Moved Permanently
Server: nginx/1.18.0 (Ubuntu)
Date: <REDACTED>
Content-Type: text/html
Content-Length: 178
Connection: keep-alive
Location: https://23.23.240.248/
:dst:ipv4 = 23.23.240.248
:dst:port = 80
:dst:proto = tcp
:dst:softnames = ['nginx']
:time = 2023/06/13 13:00:20.065
inet:flow=cbe517faae0fddba377c44a46616555c
.created = 2024/11/19 21:06:12.779
.seen = ('2023/06/13 10:13:45.970', '2023/06/13 10:13:45.971')
:dst = tcp://23.23.240.248:443
:dst:cpes = ['cpe:2.3:a:f5:nginx:1.18.0:*:*:*:*:*:*:*']
:dst:handshake = HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: <REDACTED>
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
X-Frame-Options: sameorigin
Content-Security-Policy: default-src 'self' ; connect-src *; font-src 'self' data:; frame-src *; img-src * data: blob:; media-src * data:; script-src 'self' 'unsafe-eval' 'sha256-jqxtvDkBbRAl9Hpqv68WdNOieepg8tJSYu1xIy7zT34=' ; style-src 'self' 'unsafe-inline'
X-Instance-ID: WAjPdRysvty3n43it
Vary: Accept-Encoding
Content-Encoding: gzip
:dst:ipv4 = 23.23.240.248
:dst:port = 443
:dst:proto = tcp
:dst:softnames = ['nginx']
:time = 2023/06/13 10:13:45.970
inet:flow=3aafbf61112942199e75fb3da8e28d3e
.created = 2024/11/19 21:06:13.593
.seen = ('2023/06/12 21:35:53.688', '2023/06/12 21:35:53.689')
:dst = tcp://23.23.240.248:3000
:dst:handshake = HTTP/1.1 200 OK
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
X-Frame-Options: sameorigin
Content-Security-Policy: default-src 'self' ; connect-src *; font-src 'self' data:; frame-src *; img-src * data: blob:; media-src * data:; script-src 'self' 'unsafe-eval' 'sha256-jqxtvDkBbRAl9Hpqv68WdNOieepg8tJSYu1xIy7zT34=' ; style-src 'self' 'unsafe-inline'
X-Instance-ID: WAjPdRysvty3n43it
Content-Type: text/html; charset=utf-8
Vary: Accept-Encoding
Content-Encoding: gzip
Date: <REDACTED>
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
:dst:ipv4 = 23.23.240.248
:dst:port = 3000
:dst:proto = tcp
:time = 2023/06/12 21:35:53.688
If an HTTP request was made, an inet:http:request node will also be populated.
> inet:ipv4=23.23.240.248 -> inet:flow -> inet:http:request
inet:http:request=5862362d4dfdd3cfa7815a263ef1c954
.created = 2024/11/19 21:06:12.924
:flow = cbe517faae0fddba377c44a46616555c
:headers = [('user-agent', 'Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)'), ('accept', '*/*')]
:method = GET
:response:body = sha256:5c62f0a47be20fe127e73b0c7c86c019ef5a97e8ee5f62d0a17bff8d41d6505d
:response:code = 200
:response:headers = [('content-security-policy', "default-src 'self' ; connect-src *; font-src 'self' data:; frame-src *; img-src * data: blob:; media-src * data:; script-src 'self' 'unsafe-eval' 'sha256-jqxtvDkBbRAl9Hpqv68WdNOieepg8tJSYu1xIy7zT34=' ; style-src 'self' 'unsafe-inline'"), ('x-xss-protection', '1'), ('server', 'nginx/1.18.0 (Ubuntu)'), ('x-frame-options', 'sameorigin'), ('x-content-type-options', 'nosniff'), ('date', '<REDACTED>'), ('connection', 'keep-alive'), ('content-type', 'text/html; charset=utf-8'), ('x-instance-id', 'WAjPdRysvty3n43it'), ('vary', 'Accept-Encoding')]
:response:reason = OK
:time = 2023/06/13 10:13:45.970
inet:http:request=9e1f48262922a45ccb83c433b5ebb83b
.created = 2024/11/19 21:06:11.676
:flow = 778e18d64d17c5ab6250dc2c46992445
:headers = [('accept', '*/*'), ('user-agent', 'Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)')]
:method = GET
:response:body = sha256:2e04a18ff185ba5b16f762a0538339bc4049aceaef9738edd43af77d2ceb788b
:response:code = 301
:response:headers = [('content-type', 'text/html'), ('content-length', '178'), ('server', 'nginx/1.18.0 (Ubuntu)'), ('location', 'https://23.23.240.248/'), ('date', '<REDACTED>'), ('connection', 'keep-alive')]
:response:reason = Moved Permanently
:time = 2023/06/13 13:00:20.065
inet:http:request=1e4356ab464028b789886b9376244c5a
.created = 2024/11/19 21:06:13.625
:flow = 3aafbf61112942199e75fb3da8e28d3e
:headers = [('user-agent', 'Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)'), ('accept', '*/*')]
:method = GET
:response:body = sha256:5c62f0a47be20fe127e73b0c7c86c019ef5a97e8ee5f62d0a17bff8d41d6505d
:response:code = 200
:response:headers = [('x-instance-id', 'WAjPdRysvty3n43it'), ('content-type', 'text/html; charset=utf-8'), ('x-frame-options', 'sameorigin'), ('connection', 'keep-alive'), ('x-xss-protection', '1'), ('x-content-type-options', 'nosniff'), ('keep-alive', 'timeout=5'), ('content-security-policy', "default-src 'self' ; connect-src *; font-src 'self' data:; frame-src *; img-src * data: blob:; media-src * data:; script-src 'self' 'unsafe-eval' 'sha256-jqxtvDkBbRAl9Hpqv68WdNOieepg8tJSYu1xIy7zT34=' ; style-src 'self' 'unsafe-inline'"), ('date', '<REDACTED>'), ('vary', 'Accept-Encoding')]
:response:reason = OK
:time = 2023/06/12 21:35:53.688
JARM nodes will also be created if the data is available in the response.
> inet:ipv4=23.23.240.248 -> inet:server -> inet:ssl:jarmsample -> inet:ssl:jarmhash
inet:ssl:jarmhash=2ad2ad0002ad2ad0002ad2ad2ad2ade1a3c0d7ca6ad8388057924be83dfc6a
.created = 2024/11/19 21:06:12.702
.seen = ('2023/06/07 17:20:31.266', '2023/06/07 17:20:31.267')
:ciphers = 2ad2ad0002ad2ad0002ad2ad2ad2ad
:extensions = e1a3c0d7ca6ad8388057924be83dfc6a
A --time argument can also be provided to the censys.hosts.enrich command
to query historical data for a specific point in time.
> [ inet:ipv4=45.39.123.234 ] | censys.hosts.enrich --yield --time "2022-01-25 12:41:22"
inet:flow=3d23cecda0c7b1e8958d1758642226fe
.created = 2024/11/19 21:06:14.603
.seen = ('2022/01/24 17:22:19.529', '2022/01/24 17:22:19.530')
:dst = tcp://45.39.123.234:80
:dst:cpes = ['cpe:2.3:a:nginx:nginx:*:*:*:*:*:*:*:*']
:dst:handshake = HTTP/1.1 404 Not Found
Server: nginx
Content-Type: text/html
Date: <REDACTED>
Connection: keep-alive
Content-Length: 566
:dst:ipv4 = 45.39.123.234
:dst:port = 80
:dst:proto = tcp
:dst:softnames = ['nginx']
:time = 2022/01/24 17:22:19.529
Use censys.certs.search to discover certificate SHA-256s
The censys.certs.search command can be used to discover certificate SHA-256s.
A crypto:x509:cert node will be created with the minimal data available in the response.
> censys.certs.search "vertex.link and labels: trusted" --yield --size 2
crypto:x509:cert=5b18b6d6945693cd641dad09e7b0beec
.created = 2024/11/19 21:06:15.258
:file = sha256:28ba401b49158c8f34481c3a09dc9f343298cd18e02cad61c0f910d593bca641
:issuer = DC=com, DC=ccamatil, DC=aus, DC=com, DC=ccamatil, DC=aus, CN=CCA SHA2 Issuing CA Two
:sha256 = 28ba401b49158c8f34481c3a09dc9f343298cd18e02cad61c0f910d593bca641
:subject = C=AU, C=AU, C=AU, C=AU, C=AU, C=AU, C=AU, C=AU, C=AU, O=CCA, O=CCA, O=CCA, O=CCA, O=CCA, O=CCA, O=CCA, O=CCA, O=CCA, CN=ausemtest.ccamatil.com, CN=auscolltest.ccamatil.com, CN=qs0032.ccamatil.com, CN=qwfewm.aus.ccamatil.com, CN=qwfem.aus.ccamatil.com, CN=qwffes.aus.ccamatil.com, CN=qwftms.aus.ccamatil.com, CN=qwfasu01.aus.ccamatil.com, CN=ccaauwtstws06.aus.ccamatil.com, CN=qaw.aus.ccamatil.com, CN=qawcrm.aus.ccamatil.com, CN=qawecc.aus.ccamatil.com
:validity:notafter = 2019/07/28 05:41:31.000
:validity:notbefore = 2017/07/28 05:41:31.000
crypto:x509:cert=c992be9681f17241e0aa25e8a131fcd6
.created = 2024/11/19 21:06:15.319
:file = sha256:c236456c33e905903fdfabde89a8668839b1b95b87e0d45eb7e73bb8bfcbc3ea
:issuer = [email protected], C=AU, ST=Victoria, L=Melbourne, O=Identity\, Security and Access Governance, OU=Certificate Authority, CN=ISAG Intermediate CA, [email protected]
:sha256 = c236456c33e905903fdfabde89a8668839b1b95b87e0d45eb7e73bb8bfcbc3ea
:subject = businessCategory=Private Organization, jurisdictionCountry=AU, jurisdictionStateOrProvince=Victoria, jurisdictionLocality=Melbourne, [email protected], C=AU, C=AU, ST=Victoria, ST=Victoria, street=498 Bay St, businessCategory=Private Organization, jurisdictionCountry=AU, jurisdictionStateOrProvince=Victoria, jurisdictionLocality=Melbourne, serialNumber=69 556 822 118, C=AU, C=AU, ST=Victoria, ST=Victoria, L=Melbourne, O=Identity\, Security and Access Governance, OU=Secure Socket Layer, CN=*.isam.melbourne, [email protected]
:validity:notafter = 2019/11/17 05:58:38.000
:validity:notbefore = 2017/11/17 05:58:38.000
To retrieve and parse the full certificate, use censys.certs.enrich.
For query syntax details, see the Censys Certificates Search 2.0 Syntax.
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 = 2024/11/19 21:06:09.353
:name = censys api
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=jp +{ <(seen)- meta:source=056c3c0aeea99449d7edbfad4537cf9f }
inet:ipv4=1.0.99.233
.created = 2024/11/19 21:06:10.170
:asn = 18144
:latlong = 35.4979,134.2309
:loc = jp
:type = unicast
inet:ipv4=1.0.70.70
.created = 2024/11/19 21:06:09.539
:asn = 18144
:latlong = 34.3978,132.4525
:loc = jp
:type = unicast