Package Documentation
Storm Package: synapse-censys
The following Commands are available from this package. This documentation is generated for version 7.1.0 of the package.
Storm Commands
This package implements the following Storm Commands.
censys.apiinfo
Display Censys API info for the Legacy API key.
Usage: censys.apiinfo [options]
Options:
--help : Display the command usage.
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
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.
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
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)
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
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.
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
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.
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.
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.
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.
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)
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.
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.
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
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)
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.
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.
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"
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.
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
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.
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
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.
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
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.
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
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.
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
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.
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
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.
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"
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.
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)
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.
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"
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.
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.
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.
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.
Usage: censys.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
Storm Modules
This package does not export any Storm APIs.