Package Documentation
Storm Package: synapse-passivetotal
The following Commands are available from this package. This documentation is generated for version 3.15.0 of the package.
Storm Commands
This package implements the following Storm Commands.
passivetotal.articles
Ingest articles from the PassiveTotal API.
This command will yield media:news nodes with indicators linked
by -(refs)> lightweight edges.
Articles can be retrieved by a timebox or by the article short guid.
The --since-last option can be used to set up a cron job that will automatically increment
the min-time with a globally stored value. Only a single cron job using --since-last
should be implemented to ensure that results are contiguous in the view it is running.
The first time --since-last is used the --min-time argument will define the starting point,
otherwise the --min-time argument is ignored when --since-last is specified.
Examples:
// Retrieve articles published within the last 7 days
passivetotal.articles --min-time "-7day"
// Limit the number of results to ingest and yield the media:news nodes
passivetotal.articles --min-time "-7day" --size 10 --yield
// Ingest an article by guid and yield the created media:news node
passivetotal.articles 6d9ea368 --yield
// Create a cron job to ingest new results every day
cron.add --name passivetotal.articles --hour 3 { passivetotal.articles --since-last }
Usage: passivetotal.articles [options] <guid>
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.
--min-time <min_time> : Filter by articles created after a specific time. (default: -24hours)
--since-last : Retrieve results since the last run of the command with --since-last specified.
Arguments:
[guid] : The report guid (e.g. 6d9ea368)
passivetotal.articles.search
Search for PassiveTotal articles related to an indicator value.
This command takes an indicator value to search for and queries the
https://api.passivetotal.org/v2/articles/indicator endpoint to retrieve
matching articles.
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 articles containing a specific domain
passivetotal.articles.search zoomofferblackfriday.com
// Search for articles using a node property
file:bytes#myfile | passivetotal.articles.search :name
Usage: passivetotal.articles.search [options] <query>
Options:
--help : Display the command usage.
--type <type> : Specify an indicator type to filter by.
--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.
Arguments:
<query> : Indicator value to search for in articles.
passivetotal.comp.addr
Search for IP addresses by component name from PassiveTotal.
NOTE: This command will iteratively fetch pages and yield nodes,
with each page incurring a PassiveTotal API call. Pages typically
contain 2,000 results.
This command accepts a component name for queries to the
https://api.passivetotal.org/v2/components/{name}/addresses endpoint.
The results are used to create inet:ipv4 nodes (and inet:server nodes if category=server),
which are tagged with the following scheme:
#passivetotal.rep.category.{category}.{label}
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: The --category option is case-sensitive in PassiveTotal.
Examples:
// Basic search (fetch all results, possibly millions)
passivetotal.comp.addr apache
// Filter by category (limit results)
passivetotal.comp.addr apache --category Server --yield | limit 4000
// Use options to alter result order
passivetotal.comp.addr apache --sort firstSeen --order asc
// Filter returned results by a timebox
passivetotal.comp.addr apache --time ("-7days", "now")
Usage: passivetotal.comp.addr [options] <name>
Options:
--help : Display the command usage.
--version <version> : An optional version to search for.
--category <category> : An optional component category to search for.
--sort <sort> : Sort by firstSeen or lastSeen. (default: lastSeen)
--order <order> : Order results by asc or desc. (default: desc)
--no-tags : Do not add PassiveTotal tags to created nodes.
--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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
Arguments:
<name> : The component name to search for.
passivetotal.comp.host
Search for hosts by component name from PassiveTotal.
NOTE: This command will iteratively fetch pages and yield nodes,
with each page incurring a PassiveTotal API call. Pages typically
contain 2,000 results.
This command accepts a component name for queries to the
https://api.passivetotal.org/v2/components/{name}/hosts endpoint.
The results are used to create one of the following nodes depending on format (in try order):
inet:ipv4, inet:ipv6, inet:fqdn, it:hostname
Nodes are tagged with the following scheme:
#passivetotal.rep.category.{category}.{label}
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: The --category option is case-sensitive in PassiveTotal.
Examples:
// Basic search (fetch all results, possibly millions)
passivetotal.comp.host apache
// Filter by category (limit results)
passivetotal.comp.host apache --category Server --yield | limit 4000
// Use options to alter result order
passivetotal.comp.host apache --sort firstSeen --order asc
// Filter returned results by a timebox
passivetotal.comp.host apache --time ("-7days", "now")
Usage: passivetotal.comp.host [options] <name>
Options:
--help : Display the command usage.
--version <version> : An optional version to search for.
--category <category> : An optional component category to search for.
--sort <sort> : Sort by firstSeen or lastSeen. (default: lastSeen)
--order <order> : Order results by asc or desc. (default: desc)
--no-tags : Do not add PassiveTotal tags to created nodes.
--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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
Arguments:
<name> : The component name to search for.
passivetotal.enrich
Get enrichment data from PassiveTotal.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input and
enriches them via the https://api.passivetotal.org/v2/enrichment endpoint.
Input nodes may receive the following tags depending on the results from PassiveTotal:
- #rep.pt.class.{classification}
- #rep.pt.sinkhole
- #rep.pt.evercompromised
- #rep.pt.dynamicdns
inet:fqdn nodes will be created for any subdomains returned by the API.
Examples:
// Enrich an inet:ipv4 node
inet:ipv4=129.186.1.100 | passivetotal.enrich
// Enrich an inet:fqdn node and yield inet:fqdn subdomains
inet:fqdn=foo.com | passivetotal.enrich --yield
// Enrich an inet:ipv4 node and pivot to the CIDR4
inet:ipv4=129.186.1.100 | passivetotal.enrich | <(hasip)- inet:cidr4
Usage: passivetotal.enrich [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.
--no-tags : Construct nodes but do not record tags returned by the PassiveTotal API.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.limits
Get the current PassiveTotal query limits.
Usage: passivetotal.limits [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
passivetotal.malware
Get malware data from PassiveTotal.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input for queries
to the https://api.passivetotal.org/v2/enrichment/malware endpoint.
The results are used to create inet:search:result nodes, with a 'refs' light edge to the
hash:md5 node of the malware sample. The created inet:search:result node will have its
.seen property set to collection date returned by the API.
Examples:
// Query malware data for an IP
inet:ipv4=129.186.1.100 | passivetotal.malware
// Query malware data for a domain and yield the inet:search:result nodes created
inet:fqdn=foo.com | passivetotal.malware --yield
// Pivot to created hash:md5 nodes
inet:fqdn=foo.com | passivetotal.malware --yield | -(refs)> hash:md5
// Filter returned results by a timebox
inet:fqdn=foo.com | passivetotal.malware --time ("-7days", "now")
Usage: passivetotal.malware [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
passivetotal.osint
Get OSINT data from PassiveTotal.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input for queries
to the https://api.passivetotal.org/v2/enrichment/osint endpoint.
This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
If an inbound node is provided to perform the search, a -(refs)> light
to the inbound node will be added as well.
Examples:
// Query osint data for an IP and yield inet:search:result nodes
inet:ipv4=129.186.1.100 | passivetotal.osint --yield
// Do not add PassiveTotal tags
inet:ipv4=129.186.1.100 | passivetotal.osint --no-tags
// Query osint data for a domain and yield the inet:search:result nodes created
inet:fqdn=foo.com | passivetotal.osint --yield
Usage: passivetotal.osint [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.
--no-tags : Construct nodes but do not record tags returned by the PassiveTotal API.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.pdns
Get passive DNS information from PassiveTotal.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input and queries the
https://api.passivetotal.org/v2/dns/passive endpoint to retrieve passive
DNS information from active account sources.
The results are used to create inet:dns:a and inet:dns:aaaa nodes, with their .seen property
set to the first/last seen times provided by PassiveTotal.
Examples:
// Get pDNS information about an IP
inet:ipv4=129.186.1.100 | passivetotal.pdns
// Get pDNS information about a domain and yield the created nodes
inet:fqdn=foo.com | passivetotal.pdns --yield
// Include timebox in PassiveTotal query to filter results
inet:fqdn=foo.com | passivetotal.pdns --time ("-7days", "now")
Usage: passivetotal.pdns [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
passivetotal.services
Retrieve exposed service details from PassiveTotal.
This command takes inet:ipv4 or inet:ipv6 nodes as input for queries to the
https://api.passivetotal/v2/services endpoint.
Examples:
// Search for exposed service details by IPv4 and yield inet:flow nodes
inet:ipv4=5.53.124.235 | passivetotal.services --yield
Usage: passivetotal.services [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.setup.apikey
Set the PassiveTotal API key and user.
Usage: passivetotal.setup.apikey [options] <apiuser> <apikey>
Options:
--help : Display the command usage.
--self : Set the key as a user variable. If not used, the key is set globally.
Arguments:
<apiuser> : The PassiveTotal API user name.
<apikey> : The PassiveTotal API key string.
passivetotal.setup.tagprefix
Set the tag prefix used when recording PassiveTotal tags.
The default tag prefix is "rep.pt" if not specified.
Any tags provided by a PassiveTotal API will be added within the given namespace.
For example, the PassiveTotal tag "foo" would result in "#rep.pt.foo". Any
characters incompatible with tag names are replaced with "_".
Usage: passivetotal.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
passivetotal.ssl.get
Get an SSL certificate from Passivetotal.
This command takes hash:sha1 nodes as input for queries to the
https://api.passivetotal.org/v2/ssl-certificate endpoint.
The results are used to create crypto:x509:cert nodes.
Examples:
// Get a certificate by SHA-1
hash:sha1#my.hash | passivetotal.ssl.get
// Yield created crypto:x509:cert nodes
hash:sha1#my.hash | passivetotal.ssl.get --yield
Usage: passivetotal.ssl.get [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.ssl.history
Get SSL certificate history from PassiveTotal.
This command accepts nodes as input for queries to the
https://api.passivetotal.org/v2/ssl-certificate/history endpoint.
The IP address is used for the query for the following inbound nodes:
inet:ipv4, inet:server, inet:ssl:cert
The SHA-1 is used for the query for the following inbound nodes:
file:bytes, crypto:x509:cert, hash:sha1
The results are used to create inet:ssl:cert nodes and update the .seen property on related nodes.
Examples:
// Search by inbound node
inet:ipv4#my.ip | passivetotal.ssl.history
// Output created inet:ssl:cert nodes
inet:ipv4#my.ip | passivetotal.ssl.history --yield
// Filter returned results by a timebox
inet:ipv4#my.ip | passivetotal.ssl.history --time ("-7days", "now")
Usage: passivetotal.ssl.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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
passivetotal.ssl.hosts
Search for hosts by SSL certificate.
This command takes crypto:x509:cert, file:bytes, hash:sha1, or inet:ssl:cert
nodes as input and queries the https://api.riskiq.net/v1/ssl/host endpoint
to get hosts associated with the sha1 hash.
Examples:
// Get hosts associated with a certificate by hash:sha1
hash:sha1=0628e1d26588becd29b7403e7a2693294ebb2b64 | passivetotal.ssl.hosts
Usage: passivetotal.ssl.hosts [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.ssl.keyword
Search for SSL certificate SHA-1s from PassiveTotal.
This command accepts a query keyword for queries to the
https://api.passivetotal.org/v2/ssl-certificate/search/keyword endpoint.
The results are used to create hash:sha1 nodes.
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: Only SHA-1 / certificate matches are supported.
Examples:
// Search by keyword and output hash:sha1 nodes
passivetotal.ssl.keyword sinkole --yield
Usage: passivetotal.ssl.keyword [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 (per-node).
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
Arguments:
<query> : The keyword by which to search.
passivetotal.ssl.search
Search for SSL certificates from PassiveTotal.
This command accepts a keyword and query string for queries to the
https://api.passivetotal.org/v2/ssl-certificate/search endpoint.
Accepted keywords are documented at
https://api.passivetotal.org/index.html#api-SSL_Certificates-GetV2SslCertificateSearch.
The results are used to create crypto:x509:cert nodes.
This command will also create an it:exec:query node to represent the
query syntax (with the :text prop formatted as field=query) and link
resulting nodes to it via -(found)> edges.
Examples:
// Search by field and query string, and output created crypto:x509:cert nodes
passivetotal.ssl.search issuerCommonName "Symantec Class 3 EV SSL CA - G3" --yield
// Filter returned results by a timebox
passivetotal.ssl.search issuerCommonName "Symantec Class 3 EV SSL CA - G3" --time ("-7days", "now")
Usage: passivetotal.ssl.search [options] <field> <query>
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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
Arguments:
<field> : The field by which to search.
<query> : The field value by which to search.
passivetotal.subdomains
Get subdomains data from PassiveTotal.
This command takes inet:fqdn nodes as input for queries to the
https://api.passivetotal.org/v2/enrichment/subdomains endpoint.
The results are used to create inet:fqdn nodes for each subdomain returned.
Examples:
// Get subdomains for a domain
inet:fqdn=passivetotal.org | passivetotal.subdomains
// Yield discovered subdomains
inet:fqdn=passivetotal.org | passivetotal.subdomains --yield
Usage: passivetotal.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 (per-node).
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.tracker.addr
Search for addresses by tracker value.
This command accepts a tracker value or JARM node for queries to the
https://api.passivetotal.org/v2/trackers/{value}/addresses endpoint.
If the returned tracker type is JarmHash an inet:ssl:jarmsample
node will also be created.
This command will also create an it:exec:query node to represent the
query syntax and link resulting nodes to it via -(found)> edges.
If an inbound node is provided to perform the search, a -(refs)> light
to the inbound node will be added as well.
Examples:
// Basic search
passivetotal.tracker.addr ua-123456
// Search by a specific tracker type
passivetotal.tracker.addr ua-123456 --type GoogleAnalyticsTrackingId
// Search by a JARM hash and yield the IP nodes
inet:ssl:jarmhash#mysample | passivetotal.tracker.addr --yield
Usage: passivetotal.tracker.addr [options] <value>
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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--type <type> : Type of trackers to retrieve.
Arguments:
[value] : The tracker value to search for.
passivetotal.tracker.host
Search for hosts by tracker value.
This command accepts a tracker value for queries to the
https://api.passivetotal.org/v2/trackers/{value}/hosts endpoint.
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:
// Basic search
passivetotal.tracker.host ua-123456
// Search by a specific tracker type
passivetotal.tracker.host ua-123456 --type GoogleAnalyticsTrackingId
Usage: passivetotal.tracker.host [options] <value>
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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--type <type> : Type of trackers to retrieve.
Arguments:
<value> : The tracker value to search for.
passivetotal.trackers
Get tracker data from PassiveTotal.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input for queries
to the https://api.passivetotal.org/v2/host-attributes/trackers endpoint.
If the tracker result is a JARM hash then an inet:ssl:jarmsample node is
created and returned.
Otherwise, each result returned creates:
- inet:url node for the host (https://{hostname})
- file:bytes node with a guid generated from the url and the first seen time
($lib.guid(url, firstSeen))
- inet:urlfile of the inet:url and file:bytes created
- 'refs' light edge from the inet:urlfile to an inet:web:acct node for the
account associated with the tracker
Examples:
// Query trackers data for a domain
inet:fqdn=passivetotal.com | passivetotal.trackers
// Query trackers data for a domain and yield the nodes created
inet:fqdn=reddit.com | passivetotal.trackers --yield
// Filter returned results by a timebox
inet:fqdn=reddit.com | passivetotal.trackers --time ("-7days", "now")
Usage: passivetotal.trackers [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--time <time> : Filter by results within a specific time interval.
passivetotal.whois
Query WHOIS information by domain from PassiveTotal.
This command takes inet:fqdn nodes as input and queries the
https://api.passivetotal.org/v2/whois endpoint to retrieve WHOIS information.
The results are used to create inet:whois:rec nodes representing the
WHOIS records, as well as inet:whois:contact nodes for the contacts
associated with the record.
The --history argument may be specified to also retrieve historical WHOIS
results. Using this requires a PassiveTotal API key with Enterprise
access, otherwise the API will return a single current result as normal.
Examples:
// Get WHOIS information about a domain and yield the created nodes
inet:fqdn=foo.com | passivetotal.whois --yield
// Get WHOIS information about a domain including historical results
inet:fqdn=foo.com | passivetotal.whois --history
Usage: passivetotal.whois [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).
--history : Include historical results in the WHOIS records returned.
--yield : Yield the newly created nodes.
--asof <asof> : This argument is deprecated and no longer has any effect.
passivetotal.whois.keyword
Query WHOIS information by domain from PassiveTotal.
This command takes a keyword argument as input and queries the
https://api.passivetotal.org/v2/whois/keyword endpoint to retrieve WHOIS
information.
The results are used to create inet:fqdn nodes.
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 WHOIS information matching a keyword and yield the created nodes
passivetotal.whois.keyword "tony stark" --yield
// Search for WHOIS information using an org name as the keyword
ou:org#myorg | passivetotal.whois.keyword :name
Usage: passivetotal.whois.keyword [options] <keyword>
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.
--asof <asof> : This argument is deprecated and no longer has any effect.
Arguments:
<keyword> : A keyword to search for.
passivetotal.whois.search
Query WHOIS information by domain from PassiveTotal.
By default, this command takes nodes as input to construct a query for the
https://api.passivetotal.org/v2/whois/search endpoint to retrieve WHOIS
information. To specify a raw case-sensitive text string to search for,
a --text argument may be provided in "field=query" format.
The results are used to create inet:whois:rec nodes representing the
WHOIS records, as well as inet:whois:contact nodes for the contacts
associated with the record.
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 WHOIS information matching a domain and yield the created nodes
inet:fqdn=foo.com | passivetotal.whois.search --yield
// Search for WHOIS information matching an org
ou:org#myorg | passivetotal.whois.search
// Search for WHOIS information matching a case-sensitive name
passivetotal.whois.search --text "George Washington"
Usage: passivetotal.whois.search [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.
--asof <asof> : This argument is deprecated and no longer has any effect.
--text <text> : Search using a raw text string rather than using inbound nodes.
Storm Modules
This package does not export any Storm APIs.