Package Documentation
Storm Package: synapse-censys
The following Commands are available from this package. This documentation is generated for version 7.2.0 of the package.
Storm Commands
This package implements the following Storm Commands.
censys.apiinfo
Display Censys API info for the Legacy API key.
Deprecated: "censys.apiinfo" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.apiinfo [options]
Options:
--help : Display the command usage.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.certs.enrich
Ingest and parse the full cert from the Censys Legacy API.
If an inbound node does not pivot to a hash:sha256 it will be skipped.
Labels provided by the Censys API will be added as tags to the certificate
node.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.certs.enrich`` command instead.
Examples:
// Enrich a file:bytes node and yield the crypto:x509:cert node
file:bytes#myfile | censys.certs.enrich --yield
// Enrich a crypto:x509:cert node
crypto:x509:cert#mycert | censys.certs.enrich
Deprecated: "censys.certs.enrich" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.certs.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--time <time> : Get historical information about a host at a specific time.
Inputs:
crypto:x509:cert : crypto:x509:cert nodes
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:ssl:cert : inet:ssl:cert nodes
inet:tls:clientcert : inet:tls:clientcert nodes
inet:tls:servercert : inet:tls:servercert nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.certs.observations
Discover observations that detail all of the host services that ever presented this certificate.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.certs.observations`` command instead.
Examples:
// Run a text search for certificates and yield all observations for those certs
censys.certs.search "vertex.link" --yield | censys.certs.observations --yield
Deprecated: "censys.certs.observations" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.certs.observations [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
--observed-after <observed_after>: Specify the starting observation datetime. (default: None)
--observed-before <observed_before>: Specify the ending observation datetime. (default: None)
Inputs:
crypto:x509:cert : crypto:x509:cert nodes
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:ssl:cert : inet:ssl:cert nodes
inet:tls:clientcert : inet:tls:clientcert nodes
inet:tls:servercert : inet:tls:servercert nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.certs.search
Search for certs using the Censys V2 Search Language.
NOTE: This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.search`` command instead.
Examples:
// Run a full text search and yield a minimal crypto:x509:cert node
censys.certs.search "vertex.link" --yield
// Pipe results to enrich to ingest the full cert
censys.certs.search "vertex.link" --yield | censys.certs.enrich
Deprecated: "censys.certs.search" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.certs.search [options] <query>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
--servers : Yield inet:server nodes when the --yield option is specified.
--virtual <virtual> : Specify if virtual hosts should be included in search results. (default: None, choices:
include, only)
Arguments:
<query> : The query string.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.certs.subdomains
Discover subdomains for an FQDN using the Censys cert parsed names field.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.search`` command instead.
Examples:
// Yield disocvered inet:fqdn subdomains
[ inet:fqdn=vertex.link ] | censys.certs.subdomains --yield
Deprecated: "censys.certs.subdomains" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.certs.subdomains [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
--servers : Yield inet:server nodes when the --yield option is specified.
Inputs:
inet:fqdn : inet:fqdn nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.config.add
Add a Synapse-Censys configuration.
The proxy argument can be set to one of the following values:
true: Use the Cortex configured proxy if set.
false: Do not use the Cortex configured proxy if set.
<str>: A proxy URL to use.
Examples:
// Add a global configuration
censys.config.add global_config apikey1234 6de57b96-2042-408d-9435-2e72bd9c53cc
// Add a configuration for the current user
censys.config.add --scope self my_config apikey5678 6de57b96-2042-408d-9435-2e72bd9c53cc
Usage: censys.config.add [options] <name> <apikey> <organization-id>
Options:
--help : Display the command usage.
--ssl-noverify : Do not perform SSL/TLS verification.
--proxy <proxy> : Configure the proxy usage. (default: True)
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from Censys. (default: rep.censys)
--scope <scope> : Set the scope on the configuration. (default: global, choices: global, self, unscoped)
Arguments:
<name> : A unique name for the configuration.
<apikey> : The API key string.
<organization_id> : The organization ID string.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.config.del
Delete a Synapse-Censys configuration.
Examples:
// Delete the "fooconfig" configuration
censys.config.del fooconfig
Usage: censys.config.del [options] <name>
Options:
--help : Display the command usage.
Arguments:
<name> : The name of the configuration.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.config.list
Display the list of Synapse-Censys configurations you have access to.
Usage: censys.config.list [options]
Options:
--help : Display the command usage.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.config.migrate
Migrate options for all Synapse-Censys configurations.
The proxy argument can be set to one of the following values:
true: Use the Cortex configured proxy if set.
false: Do not use the Cortex configured proxy if set.
<str>: A proxy URL to use.
Examples:
// Migrate the tag prefix for all configurations
censys.config.migrate --tag-prefix my.tagpref
Usage: censys.config.migrate [options]
Options:
--help : Display the command usage.
--ssl-verify <ssl_verify> : Set whether to verify the SSL certificate of the server. (default: None)
--proxy <proxy> : Configure the proxy usage. (default: None)
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from Censys. (default: None)
--organization-id <organization_id>: The organization ID string. (default: None)
The command is accessible to users with one or more of the following permissions:
power-ups.censys.admin
censys.config.show
Show the details of a configuration.
Examples:
// Show the in-use configuration for the current user
censys.config.show
// Show a configuration by name
censys.config.show myconfig
Usage: censys.config.show [options] <name>
Options:
--help : Display the command usage.
Arguments:
[name] : The name of the configuration.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.config.update
Update the configuration of a defined Synapse-Censys configuration.
The proxy argument can be set to one of the following values:
true: Use the Cortex configured proxy if set.
false: Do not use the Cortex configured proxy if set.
<str>: A proxy URL to use.
Examples:
// Set the permission level for user "myuser" to "admin" on the "fooconfig"
// configuration
censys.config.update fooconfig --perm user myuser admin
// Set the permission level for the "all" role to "deny" on the
// "fooconfig" configuration
censys.config.update fooconfig --perm role all deny
// Do not verify the SSL certificate when connecting to "fooconfig"
censys.config.update fooconfig --ssl-verify (false)
// Change the name of the "fooconfig" configuration to "barconfig"
censys.config.update fooconfig --name barconfig
Usage: censys.config.update [options] <config>
Options:
--help : Display the command usage.
--apikey <apikey> : The API key string. (default: None)
--organization-id <organization_id>: The organization ID string. (default: None)
--perm <perm> : Set the permission level for a user or role on this configuration.
Arguments to this option are ``scope``, ``name``, ``level``:
<scope>: The scope for the permission, either "user" or "role".
<name>: The user/role name depending on scope.
<level>: The $lib.auth.easyperm.level, or None to remove the permission.
(default: None)
--ssl-verify <ssl_verify> : Set whether to verify the SSL certificate of the server. (default: None)
--proxy <proxy> : Configure the proxy usage. (default: None)
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from Censys. (default: None)
--name <name> : Rename the configuration. (default: None)
Arguments:
<config> : The name of the configuration to modify.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.hosts.certs
Ingest historical certificates for an IP address.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.hosts.enrich`` command instead.
Examples:
// Ingest certificates for an IP address
[ inet:ipv4=1.1.1.1 ] | censys.hosts.certs --yield
// Ingest certificates for an IP address from Jan 2022 to Dec 2023
[ inet:ipv4=1.1.1.1 ] | censys.hosts.certs --start 20220101 --end 20231231
Deprecated: "censys.hosts.certs" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.certs [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
--start <start> : Specify the starting datetime. (default: None)
--end <end> : Specify the ending datetime. (default: None)
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.hosts.domain
Full text search hosts by an FQDN using the Censys Legacy API.
Examples:
// Yield the IPv4 node
[ inet:fqdn=vertex.link ] | censys.hosts.domain --yield
// Pipe results to enrich to parse full host records
[ inet:fqdn=vertex.link ] | censys.hosts.domain --yield | censys.hosts.enrich
// Yield created inet:server nodes instead of inet:ipv4/inet:ipv6
[ inet:fqdn=vertex.link ] | censys.hosts.domain --yield --servers
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.search`` command instead.
Deprecated: "censys.hosts.domain" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.domain [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
--servers : Yield inet:server nodes when the --yield option is specified.
Inputs:
inet:fqdn : inet:fqdn nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.hosts.enrich
Enrich an IP node using the Censys Legacy API to get host data.
Host labels provided by the Censys Legacy API will be added as tags to the IP
node, and service labels will be added as tags to the ``inet:server``
nodes.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.hosts.enrich`` command instead.
Examples:
// Enrich an IPv4 and yield inet:flow nodes
inet:ipv4=1.1.1.1 | censys.hosts.enrich --yield
// Enrich an IPv4 with historical data
inet:ipv4=1.1.1.1 | censys.hosts.enrich --time "2021-01-01 15:00"
Deprecated: "censys.hosts.enrich" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--time <time> : Get historical information about a host at a specific time.
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.hosts.history
Ingest historical events about an IP address.
NOTE: The `--details` flag is only used when a "service_observed", "service_added_to_host", or
"service_enriched" event is encountered. This flag will cause an extra host lookup to happen
to get detailed host information at the time of the event. Be aware this flag may cause a
lot of additional queries - recommend using only with a very small time window
(`--start <time>` and `--end <time>`).
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.hosts.history`` command instead.
Examples:
// Get all history about an IP address
[ inet:ipv4=23.23.240.248 ] | censys.hosts.history --yield
// Get history about an IP address from Jan 2022 to Dec 2022
[ inet:ipv4=23.23.240.248 ] | censys.hosts.history --start 20220101 --end 20231231
Deprecated: "censys.hosts.history" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
--start <start> : Specify the starting datetime. (default: None)
--end <end> : Specify the ending datetime. (default: None)
--details : Perform the extra host lookup to get event details.
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.hosts.names
Ingest DNS names for an IP address.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.search`` command instead.
Examples:
// Get all known names for an IP address
[ inet:ipv4=23.23.240.248 ] | censys.hosts.names --yield
Deprecated: "censys.hosts.names" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.names [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.hosts.search
Search for hosts using the Censys V2 Search Language.
The command creates an ``it:exec:query`` node to represent the query
syntax and links resulting nodes to it via ``-(found)>`` edges.
NOTE: This command does not return host labels in the search results.
To get host labels, you must pipe the results to censys.hosts.enrich.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.platform.search`` command instead.
Examples:
// Run a full text search and yield the IPv4 node
censys.hosts.search "vertex.link" --yield
// Pipe results to enrich to parse full host records
censys.hosts.search "vertex.link" --yield | censys.hosts.enrich
// Yield created inet:server nodes instead of inet:ipv4/inet:ipv6
censys.hosts.search "vertex.link" --yield --servers
// Pipe results to enrich to parse host records and get labels
censys.hosts.search "labels: 'remote-access'" --yield | censys.hosts.enrich
Deprecated: "censys.hosts.search" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.hosts.search [options] <query>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
--servers : Yield inet:server nodes when the --yield option is specified.
--virtual <virtual> : Specify if virtual hosts should be included in search results. (default: None, choices:
include, only)
Arguments:
<query> : The query string.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.platform.certs.download
Download X509 certificate in PEM format.
If Synapse-Fileparser is available, also parse the PEM file and optionally
yield a crypto:x509:cert node.
Examples:
// Download and parse the PEM certificate associated with the lifted sha256 hashes
hash:sha256#myhash | censys.platform.certs.download --yield
Endpoints:
/global/asset/certificate/{sha256}/raw: Retrieve the raw PEM-encoded format of a certificate.
Usage: censys.platform.certs.download [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created crypto:x509:cert nodes.
--config <config> : Override the default config with the provided name.
Inputs:
crypto:x509:cert : crypto:x509:cert nodes
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:ssl:cert : inet:ssl:cert nodes
inet:tls:clientcert : inet:tls:clientcert nodes
inet:tls:servercert : inet:tls:servercert nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.platform.certs.enrich
Ingest and parse the full cert from the Censys API.
If an inbound node does not pivot to a hash:sha256 it will be skipped.
Labels provided by the Censys API will be added as tags to the certificate
node.
Examples:
// Enrich a file:bytes node and yield the crypto:x509:cert node
file:bytes#myfile | censys.platform.certs.enrich --yield
// Enrich a crypto:x509:cert node
crypto:x509:cert#mycert | censys.platform.certs.enrich
Endpoints:
/global/asset/certificate/{sha256}: Retrieve information about a certificate.
Usage: censys.platform.certs.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created crypto:x509:cert nodes.
--config <config> : Override the default config with the provided name.
Inputs:
crypto:x509:cert : crypto:x509:cert nodes
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:ssl:cert : inet:ssl:cert nodes
inet:tls:clientcert : inet:tls:clientcert nodes
inet:tls:servercert : inet:tls:servercert nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.platform.certs.observations
Discover observations that detail all of the host services that ever presented this certificate.
Examples:
// Run a text search for certificates and yield all observations for those certs
censys.platform.search "vertex.link" --yield | censys.platform.certs.observations --yield
Endpoints:
/threat-hunting/certificate/{sha256}/observations/hosts: Retrieve the historical observations of hosts associated with a certificate.
Usage: censys.platform.certs.observations [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created inet:flow nodes.
--start-time <start_time> : Only show ranges ending at or after this time. (default: None)
--end-time <end_time> : Only show ranges starting at or before this time. (default: None)
--config <config> : Override the default config with the provided name.
Inputs:
crypto:x509:cert : crypto:x509:cert nodes
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:ssl:cert : inet:ssl:cert nodes
inet:tls:clientcert : inet:tls:clientcert nodes
inet:tls:servercert : inet:tls:servercert nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.platform.hosts.enrich
Enrich an IP node using the Censys API to get host data.
Host labels provided by the Censys API will be added as tags to the IP
node, and service labels will be added as tags to the ``inet:flow``
nodes.
Examples:
// Enrich an IPv4 and yield inet:flow nodes
inet:ipv4=1.1.1.1 | censys.platform.hosts.enrich --yield
// Enrich an IPv4 with historical data
inet:ipv4=1.1.1.1 | censys.platform.hosts.enrich --time "2021-01-01 15:00"
Endpoints:
/global/asset/host/{ip} : Retrieve information about a host.
Usage: censys.platform.hosts.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--time <time> : Get historical information about a host at a specific time.
--yield : Yield the newly created inet:flow nodes.
--config <config> : Override the default config with the provided name.
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.platform.hosts.history
Ingest historical events about an IP address.
Examples:
// Get all history about an IP address
[ inet:ipv4=23.23.240.248 ] | censys.platform.hosts.history --yield
// Get history about an IP address from Jan 2022 to Dec 2022
[ inet:ipv4=23.23.240.248 ] | censys.platform.hosts.history --period (20220101, 20231231)
Endpoints:
/global/asset/host/{ip}/timeline: Retrieve event history for a host.
Usage: censys.platform.hosts.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
--period <period> : The range of host history events to retrieve. (default: ('-30days', 'now'))
--config <config> : Override the default config with the provided name.
Inputs:
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.platform.search
Search using the Censys Query Language.
NOTE - This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
Examples:
// Run a full text search and yield the nodes
censys.platform.search "vertex.link" --yield
// Discover subdomains for an FQDN using the Censys cert parsed names field.
censys.platform.search "cert.names: vertex.link"
// Search for hosts by domain name
censys.platform.search "host.dns.names: vertex.link"
Endpoints:
/global/search/query : Run a search query across Censys data.
Usage: censys.platform.search [options] <query>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created inet:flow/crypto:x509:cert nodes.
--config <config> : Override the default config with the provided name.
Arguments:
<query> : The query string.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.adminpower-ups.censys.user
censys.setup.apikey
Set the Censys Legacy API key.
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.config.add`` command to configure API keys.
Deprecated: "censys.setup.apikey" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.setup.apikey [options] <apiid> <secret>
Options:
--help : Display the command usage.
--self : Set the key as a user variable. If not used, the key is set globally.
Arguments:
<apiid> : The Censys Legacy API ID string.
<secret> : The Censys Legacy API secret string.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
censys.setup.tagprefix
Set the tag prefix used when recording Censys tags.
The default tag prefix is "rep.censys" if not specified.
All tags will be added within the given namespace. For example, the item
"foo" would result in "#rep.censys.foo". Any characters incompatible with
tag names are replaced with "_".
NOTE: This is a Censys Legacy API command. Censys Platform users should use the
``censys.config.add`` command to configure tag prefixes.
Deprecated: "censys.setup.tagprefix" is deprecated: This command relies on the Censys Legacy API.
Usage: censys.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
The command is accessible to users with one or more of the following permissions:
power-ups.censys.user
Storm Modules
This package does not export any Storm APIs.