Package Documentation
Storm Package: synapse-domaintools
The following Commands are available from this package. This documentation is generated for version 1.0.0 of the package.
Storm Commands
This package implements the following Storm Commands.
domaintools.config.add
Add a Synapse-DomainTools configuration.
A configuration holds DomainTools API credentials (--apiuser and --apikey), a
Farsight DNSDB API key (--farsight-apikey), or both.
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.
When the proxy is set to a URL, the proxy-user and proxy-passwd arguments may
be used to authenticate to it. They must be URL safe; see $lib.inet.http.urlencode.
The password is stored in the configuration secrets, so it is only visible to
users with edit access to the configuration. Any stored credentials are removed
if the proxy is later set to true or false.
Examples:
// Add a global configuration with DomainTools and Farsight API keys
domaintools.config.add global_config --apiuser user1234 --apikey apikey1234 --farsight-apikey fskey1234
// Add a configuration for the current user with only a Farsight API key
domaintools.config.add --scope self my_config --farsight-apikey fskey5678
Endpoints:
(user-configured base URL)
/lookup/rate_limit : Get the Farsight DNSDB query limits. Also used to validate the API key.
https://api.domaintools.com
/v1/account : Get the DomainTools account query limits. Also used to validate the API key.
Usage: domaintools.config.add [options] <name>
Options:
--help : Display the command usage.
--apiuser <apiuser> : The DomainTools API user.
--apikey <apikey> : The DomainTools API key.
--farsight-apikey <farsight_apikey>: The Farsight DNSDB API key.
--farsight-url <farsight_url>: The Farsight DNSDB API URL. (default: https://api.dnsdb.info)
--ssl-noverify : Do not perform SSL/TLS verification.
--proxy <proxy> : Configure the proxy usage. (default: True)
--proxy-user <proxy_user> : The username to authenticate to the proxy with.
--proxy-passwd <proxy_passwd>: The password to authenticate to the proxy with.
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from DomainTools. (default: rep.domaintools)
--scope <scope> : Set the scope on the configuration. A "self" config belongs to the user
who created it, and is stored and listed with the scope "user".
(default: global, choices: global, self, unscoped)
--no-check-apikey : Do not perform API key validation with DomainTools and Farsight.
Arguments:
<name> : A unique name for the configuration.
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.config.del
Delete a Synapse-DomainTools configuration.
Examples:
// Delete the "fooconfig" configuration
domaintools.config.del fooconfig
Usage: domaintools.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.domaintools.adminpower-ups.domaintools.user
domaintools.config.list
Display the list of Synapse-DomainTools configurations you have access to.
Usage: domaintools.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.domaintools.adminpower-ups.domaintools.user
domaintools.config.migrate
Update options for every Synapse-DomainTools configuration at once.
Requires admin permission on the Synapse-DomainTools power-up.
API key validation is skipped when running this command.
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.
When the proxy is set to a URL, the proxy-user and proxy-passwd arguments may
be used to authenticate to it. They must be URL safe; see $lib.inet.http.urlencode.
The password is stored in the configuration secrets, so it is only visible to
users with edit access to the configuration. Any stored credentials are removed
if the proxy is later set to true or false.
Examples:
// Migrate the tag prefix for all configurations
domaintools.config.migrate --tag-prefix my.tagpref
Usage: domaintools.config.migrate [options]
Options:
--help : Display the command usage.
--farsight-url <farsight_url>: The Farsight DNSDB API URL. (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)
--proxy-user <proxy_user> : The username to authenticate to the proxy with. (default: None)
--proxy-passwd <proxy_passwd>: The password to authenticate to the proxy with. (default: None)
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from DomainTools. (default: None)
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.admin
domaintools.config.show
Show the details of a configuration.
Examples:
// Show the in-use configuration for the current user
domaintools.config.show
// Show a configuration by name
domaintools.config.show myconfig
Usage: domaintools.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.domaintools.adminpower-ups.domaintools.user
domaintools.config.update
Update the configuration of a defined Synapse-DomainTools configuration.
An API key may be removed by setting it to an empty string. The DomainTools
API user and key must be set or removed together, and a configuration must
keep a DomainTools API key or a Farsight API key.
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.
When the proxy is set to a URL, the proxy-user and proxy-passwd arguments may
be used to authenticate to it. They must be URL safe; see $lib.inet.http.urlencode.
The password is stored in the configuration secrets, so it is only visible to
users with edit access to the configuration. Any stored credentials are removed
if the proxy is later set to true or false.
Examples:
// Set the permission level for user "myuser" to "admin" on the "fooconfig"
// configuration
domaintools.config.update fooconfig --perm user myuser admin
// Set the permission level for the "all" role to "deny" on the
// "fooconfig" configuration
domaintools.config.update fooconfig --perm role all deny
// Add a Farsight API key to the "fooconfig" configuration
domaintools.config.update fooconfig --farsight-apikey fskey1234
// Remove the Farsight API key from the "fooconfig" configuration
domaintools.config.update fooconfig --farsight-apikey ""
// Do not verify the SSL certificate when connecting to "fooconfig"
domaintools.config.update fooconfig --ssl-verify (false)
// Change the name of the "fooconfig" configuration to "barconfig"
domaintools.config.update fooconfig --name barconfig
Endpoints:
(user-configured base URL)
/lookup/rate_limit : Get the Farsight DNSDB query limits. Also used to validate the API key.
https://api.domaintools.com
/v1/account : Get the DomainTools account query limits. Also used to validate the API key.
Usage: domaintools.config.update [options] <config>
Options:
--help : Display the command usage.
--apiuser <apiuser> : The DomainTools API user. (default: None)
--apikey <apikey> : The DomainTools API key. (default: None)
--farsight-apikey <farsight_apikey>: The Farsight DNSDB API key. (default: None)
--farsight-url <farsight_url>: The Farsight DNSDB API URL. (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 name, or (null) to remove the
permission, which falls back to the config default.
(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)
--proxy-user <proxy_user> : The username to authenticate to the proxy with. (default: None)
--proxy-passwd <proxy_passwd>: The password to authenticate to the proxy with. (default: None)
--tag-prefix <tag_prefix> : The tag prefix to use when recording data from DomainTools. (default: None)
--name <name> : Rename the configuration. (default: None)
--no-check-apikey : Do not perform API key validation with DomainTools and Farsight.
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.domaintools.adminpower-ups.domaintools.user
domaintools.hosting.history
Query the DomainTools API for hosting history data.
This command takes inet:fqdn nodes as input to query the DomainTools
hosting history API.
Examples:
// Get hosting history for an inet:fqdn node
inet:fqdn=vertex.link | domaintools.hosting.history
Endpoints:
https://api.domaintools.com
/v1/{fqdn}/hosting-history/: Get the hosting history of a domain.
Usage: domaintools.hosting.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
Inputs:
inet:fqdn : inet:fqdn nodes
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.iris.detect
Retrieve domains from the Iris Detect API.
This command will first retrieve the list of monitors from the
"iris-detect/monitors/" endpoint and create "meta:rule" nodes to represent
the currently configured monitor rules. Once the rules are populated,
the command will retrieve domains and link them to the monitor that matched
them using "meta:rule -(matches)> inet:fqdn" edges. The "--no-monitors"
option may be used to disable creating the "meta:rule" nodes and edges.
By default this command will retrieve newly discovered domains from the
"iris-detect/domains/new/" endpoint. To retrieve watched domains from
the "iris-detect/domains/watched/" endpoint, specify "--type watched".
Examples:
// Ingest newly discovered domains
domaintools.iris.detect
// Ingest watched domains and do not link associated monitors.
domaintools.iris.detect --type watched --no-monitors
// Create a cron job to ingest newly discovered domains every day
cron.add --name "DomainTools Iris Detect New Domains Feed" --hour 3
{ domaintools.iris.detect }
Endpoints:
https://api.domaintools.com
/v1/iris-detect/monitors/ : List the Iris Detect monitors.
/v1/iris-detect/domains/{type}/: List new or watched domains from Iris Detect.
Usage: domaintools.iris.detect [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
--no-monitors : Skip creating nodes/edges to represent the monitors that matched domain results.
--type <type> : Specify whether 'new' or 'watched' domains should be retrieved. (default: new)
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.iris.enrich
Enrich domains using the Iris Enrich API.
This command takes inet:fqdn nodes as input to query the DomainTools
Iris Enrich API. The Iris Enrich API is optimized for fast responses and high volume
lookups, so it does not offer most of the search parameters available in the
Iris Investigate API.
Examples:
// Enrich an inet:fqdn node
inet:fqdn=vertex.link | domaintools.iris.enrich
Endpoints:
https://api.domaintools.com
/v1/iris-enrich/ : Enrich domains with Iris data.
Usage: domaintools.iris.enrich [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--yield : Yield the newly created nodes.
--batch-size <batch_size> : Specify the number of domains to submit in each query to the API (max 100). (default:
100)
Inputs:
inet:fqdn : inet:fqdn nodes
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.iris.investigate
Search for domain information using the Iris Investigate API.
This command takes a domain name or a set of search parameters to query
the API for matching domains. When specifying a command argument,
a node may be passed as the value which will use the string representation
of the node's primary property as the search value.
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:
// Search for a domain name
domaintools.iris.investigate --domain vertex.link
// Search using filters
domaintools.iris.investigate --mailserver-domain vertex.link
// Search for multiple domain names
domaintools.iris.investigate --domain (vertex.link, domaintools.net)
Endpoints:
https://api.domaintools.com
/v1/iris-investigate/ : Search for domains with Iris Investigate.
Usage: domaintools.iris.investigate [options]
Options:
--help : Display the command usage.
--domain <domain> : Domain or list of domains to investigate.
--ip <ip> : IPv4 address the registered domain was last known to point to during an active DNS
check.
--email <email> : Email address from the most recently available Whois record, DNS SOA record or SSL
certificate.
--email-domain <email_domain>: Only the domain portion of a Whois or DNS SOA email address.
--nameserver-host <nameserver_host>: Fully-qualified host name of the name server.
--nameserver-domain <nameserver_domain>: Registered domain portion of the name server.
--nameserver-ip <nameserver_ip>: IP address of the name server.
--registrar <registrar> : Exact match to the Whois registrar field.
--registrant <registrant> : Exact match to the Whois registrant field.
--registrant-org <registrant_org>: Exact match to the Whois registrant organization field.
--mailserver-host <mailserver_host>: Fully-qualified host name of the mail server (mx.domaintools.net) Reverse MX.
--mailserver-domain <mailserver_domain>: Only the registered domain portion of the mail server (domaintools.net).
--mailserver-ip <mailserver_ip>: IP address of the mail server.
--redirect-domain <redirect_domain>: Find domains observed to redirect to another domain name.
--ssl-hash <ssl_hash> : SSL certificate SHA-1 hash.
--ssl-org <ssl_org> : Exact match to the organization name on the SSL certificate.
--ssl-subject <ssl_subject> : Subject field from the SSL certificate.
--ssl-email <ssl_email> : Email address from the SSL certificate.
--google-analytics <google_analytics>: Domains with a Google Analytics tracking code.
--adsense <adsense> : Domains with a Google AdSense tracking code.
--search-hash <search_hash> : Encoded search from the Iris UI.
--tld <tld> : Limit results to only include domains in a specific top-level domain.
--create-date <create_date> : Only include domains created on a specific date.
--expiration-date <expiration_date>: Only include domains expiring on a specific date.
--data-updated-after <data_updated_after>: Iris records that were updated on or after midnight on this date. Must be paired with
another parameter.
--active <active> : Set to true to only return domains that have either an entry in the global DNS system,
OR are listed as registered by the registry. Set to false to only return domains that do
not have an entry in the global DNS system AND are not listed as registered by the
registry.
--tagged-with-any <tagged_with_any>: Iris Investigate tag or tags. Returns domains tagged with any of the tags.
--tagged-with-all <tagged_with_all>: Iris Investigate tag or tags. Returns domains tagged with all of the tags.
--not-tagged-with-any <not_tagged_with_any>: Iris Investigate tag or tags. Excludes domains tagged with any of the tags.
--not-tagged-with-all <not_tagged_with_all>: Iris Investigate tag or tags. Excludes domains tagged with all of the tags.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of results ingested to the given size.
--yield : Yield the newly created nodes.
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.limits
Get the current DomainTools query limits.
Endpoints:
(user-configured base URL)
/lookup/rate_limit : Get the Farsight DNSDB query limits. Also used to validate the API key.
https://api.domaintools.com
/v1/account : Get the DomainTools account query limits. Also used to validate the API key.
Usage: domaintools.limits [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.pdns
Query the DomainTools Farsight DNSDB API for passive DNS data.
This command takes inet:fqdn, inet:ipv4, inet:ipv6, inet:cidr4, or inet:cidr6
nodes as input to query the DomainTools Farsight DNSDB API. The --domain or
--ip arguments may also be used to specify the value to search for. By
default, queries for domains will perform rrset lookups. To instead perform an
rdata lookup for a domain, the --rdata argument may be specified. IP queries will
always perform rdata lookups.
When specifying an RRtype to search for, ANY (the default) will match any RRtype
except the DNSSEC-related RRtypes: DS, RRSIG, NSEC, DNSKEY, NSEC3, NSEC3PARAM, DLV,
CDS, CDNSKEY, and TA. The pseudo-mnemonic ANY-DNSSEC can be used which will return
only those records matching the aforementioned RRtypes.
Note: For limitations on the --domain-regex argument, see the domaintools.pdns.search
command.
Examples:
// Perform an rrset query for a domain
inet:fqdn=vertex.link | domaintools.pdns
// Perform an rdata query for a domain
inet:fqdn=vertex.link | domaintools.pdns --rdata
// Perform an rdata query for an IP
inet:ipv4=104.244.13.104 | domaintools.pdns
// Perform a regular expression search for a domain
domaintools.pdns --domain-regex ".*\.vertex\.link.$" --rrtype A --size 5 --yield
Endpoints:
(user-configured base URL)
/dnsdb/v2/lookup/{ltype}/{vtype}/{value}: Look up Farsight DNSDB passive DNS records.
/dnsdb/v2/regex/{ltype}/{value}: Search Farsight DNSDB passive DNS records with a regular expression.
Usage: domaintools.pdns [options]
Options:
--help : Display the command usage.
--domain <domain> : Domain name with optional leading or trailing asterisk and label separator (*. or .*).
--ip <ip> : An IPv4 or IPv6 single address, with a prefix length, or range to search for.
--rdata : For a domain, perform an rdata lookup instead of an rrset lookup. Does not apply to ip
queries.
--rrtype <rrtype> : Specify an RRtype to search for. (default: ANY)
--domain-regex <domain_regex>: Perform a regular expression search for a domain.
--bailiwick <bailiwick> : Specify a bailiwick to filter on. Does not apply to rdata queries.
--no-aggr : Disable rrset aggregation.
--time-first-before <time_first_before>: Search for results where the DNS record was first observed before the specified time.
--time-first-after <time_first_after>: Search for results where the DNS record was first observed after the specified time.
--time-last-before <time_last_before>: Search for results where the DNS record was last observed before the specified time.
--time-last-after <time_last_after>: Search for results where the DNS record was last observed after the specified time.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of records ingested to the given size.
--yield : Yield the newly created nodes.
Inputs:
inet:cidr4 : inet:cidr4 nodes
inet:cidr6 : inet:cidr6 nodes
inet:fqdn : inet:fqdn nodes
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.domaintools.adminpower-ups.domaintools.user
domaintools.pdns.search
Search the DomainTools Farsight DNSDB API for passive DNS data
using the Flexible Search API, or regular expression search.
This command takes a regular expression string as input to query the
DomainTools Farsight DNSDB API. This command will create inet:fqdn nodes
for each domain that matches the regular expression.
Notes:
- IPv4 and IPv6 PTR records are filtered out of the Flexible Search data set.
This means reverse lookups via in-addr.arpa records will return no
records, even if those records are found in the DNSDB database.
- DNSSEC records are not searchable nor returned with Flexible Search.
- Glob search is not supported.
- The DNSDB Farsight Compatible Regular Expressions (FCRE) Reference Guide
can be found in the user guide.
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:
// Perform a regular expression search for a domain
domaintools.pdns.search --size 5 --yield ".*\.vertex\.link.$"
Endpoints:
(user-configured base URL)
/dnsdb/v2/regex/{ltype}/{value}: Search Farsight DNSDB passive DNS records with a regular expression.
Usage: domaintools.pdns.search [options] <regex>
Options:
--help : Display the command usage.
--rdata : Perform an rdata lookup instead of an rrnames lookup.
--rrtype <rrtype> : Specify an RRtype to search for. (default: ANY)
--time-first-before <time_first_before>: Search for results where the DNS record was first observed before the specified time.
--time-first-after <time_first_after>: Search for results where the DNS record was first observed after the specified time.
--time-last-before <time_last_before>: Search for results where the DNS record was last observed before the specified time.
--time-last-after <time_last_after>: Search for results where the DNS record was last observed after the specified time.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of records ingested to the given size.
--yield : Yield the newly created nodes.
Arguments:
<regex> : Perform a regular expression search.
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
domaintools.whois.history
Query the DomainTools API for Whois history data.
This command takes inet:fqdn nodes as input to query the DomainTools
Whois history API.
Examples:
// Get Whois history for an inet:fqdn node
inet:fqdn=vertex.link | domaintools.whois.history
Endpoints:
https://api.domaintools.com
/v1/{fqdn}/whois/history/ : Get the Whois history of a domain.
Usage: domaintools.whois.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--config <config> : Override the default config with the provided name.
--size <size> : Limit the number of results ingested to the given size.
--sort <sort> : Sort the records returned in either ascending or descending order. (default: date_desc,
choices: date_desc, date_asc)
--yield : Yield the newly created nodes.
Inputs:
inet:fqdn : inet:fqdn nodes
The command is accessible to users with one or more of the following permissions:
power-ups.domaintools.adminpower-ups.domaintools.user
Storm Modules
This package does not export any Storm APIs.