Package Documentation
Storm Package: synapse-mandiant
The following Commands are available from this package. This documentation is generated for version 3.3.0 of the package.
Storm Commands
This package implements the following Storm Commands.
mandiant.advantage.actors
Ingest threat actors from the Mandiant Advantage API.
This command will yield risk:threat nodes, with additional data linked
by -(targets)> and -(uses)> lightweight edges.
The following enrichments will also be run for each actor,
and optionally controlled via the specified opts key:
- history (opts key = "actors:history")
- indicators (opts key = "actors:indicators")
- reports (opts key = "actors:reports")
- MITRE ATT&CK techniques
The first time --since-last is used it will default to offset=0.
Examples:
// Ingest threat actor by name and yield risk:threat nodes
mandiant.advantage.actors apt1 --yield
// Ingest threat actor by an organization name
ou:org#foo | mandiant.advantage.actors
// Pivot through risk:threat merge history
risk:threat#foo | mandiant.advantage.actors --yield | tree { -> risk:threat:merged:isnow }
// Create a cron job to ingest new threat actors every day
cron.add --name mandiant.advantage.actors --hour 3 { mandiant.advantage.actors --since-last }
// Exclude "news analysis" reports from the ingest
mandiant.advantage.actors apt1 --excludes "news analysis"
// Disable parsing associated report PDFs using Synapse-FileParser
mandiant.advantage.actors apt1 --opts ({"reports:pdf:fileparser": false})
Usage: mandiant.advantage.actors [options] <name>
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.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--report-includes <report_includes> [<report_includes> ...]: Only include defined report types (case-insensitive). This option can be controlled
through the opts configuration.
--report-excludes <report_excludes> [<report_excludes> ...]: Exclude defined report types (case-insensitive). This option can be controlled through
the opts configuration.
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
Arguments:
[name] : An actor name (e.g. apt1)
mandiant.advantage.campaigns
Ingest campaigns from the Mandiant Advantage API.
This command will also ingest related reports, MITRE ATT&CK techniques, and indicators.
The campaign timeline is used to create a meta:timeline node for each campaign,
and meta:event nodes for each event within the timeline.
The following enrichments will also be run for each campaign,
and optionally controlled via the specified opts key:
- indicators (opts key = "campaigns:indicators")
- reports (opts key = "campaigns:reports")
- vulnerabilities (opts key = "campaigns:vulns")
- MITRE ATT&CK techniques
The first time --since-last is used it will default to "-24hours".
Examples:
// Ingest campaigns by the Mandiant ID and yield the ou:campaign node
mandiant.advantage.campaigns CAMP.22.063 --yield
// Exclude "news analysis" reports from the ingest
mandiant.advantage.campaigns CAMP.22.063 --yield --report-excludes "news analysis"
// Ingest campaigns updated within the last day
mandiant.advantage.campaigns --time ("-1day", "now")
// Create a cron job to ingest updated results every day
cron.add --name mandiant.advantage.campaigns --hour 3 { mandiant.advantage.campaigns--since-last }
// Disable parsing associated report PDFs using Synapse-FileParser
mandiant.advantage.campaigns CAMP.22.063 --yield --opts ({"reports:pdf:fileparser": false})
Usage: mandiant.advantage.campaigns [options] <id>
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.
--time <time> : Filter by results within a specific time interval.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--report-includes <report_includes> [<report_includes> ...]: Only include defined report types (case-insensitive).
--report-excludes <report_excludes> [<report_excludes> ...]: Exclude defined report types (case-insensitive).
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
Arguments:
[id] : The campaign id (e.g. CAMP.22.063)
mandiant.advantage.dtm.alerts
Ingest alerts from the Mandiant Advantage DTM API.
This command will yield risk:alert nodes, with additional links by -(refs)>
lightweight edges.
Alert monitors are also ingested as meta:rule nodes,
and reference the alert with a -(matches)> lightweight edge.
The name and description properties are scraped, and linked with -(refs)>
lightweight edges.
Similar domains returned by the domain discovery document will be related
using the risk:technique:masquerade node.
Filter options only apply if an alert ID is not provided.
If the --search option is used, an it:exec:query node will be created to represent
the query, and resulting nodes will be linked via -(found)> edges.
Examples:
// Ingest an alert by ID and yield the risk:alert node
mandiant.advantage.dtm.alerts cleinohb8t7l1i8b3s60 --yield
// Ingest alerts by type
mandiant.advantage.dtm.alerts --alert-type "Domain Discovery"
// Ingest alerts by time
mandiant.advantage.dtm.alerts --time (2023-11-10, now)
Usage: mandiant.advantage.dtm.alerts [options] <id>
Options:
--help : Display the command usage.
--monitor-id <monitor_id> : Filter alerts by monitor id.
--status <status> : Filter alerts by status. (choices: new, closed, read)
--alert-type <alert_type> : Filter alerts by type.
--search <search> : Search alert and trigger doc contents based on a Lucene query string.
--icscore <icscore> : Specify the minimum IC-Score to return in the results.
--time <time> : Filter by results updated within a specific time interval.
--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:
[id] : Retrieve alert by id.
mandiant.advantage.indicators
Query the Mandiant Advantage API to get details about indicators.
The primary property of the inbound node is used as the search value when
calling the Mandiant Advantage API, and therefore the results will include
additional indicators besides the one passed in.
If a file:bytes node is provided, the first populated hash property will be
used in the following order: SHA-256, SHA-1, MD5.
This command may enrich nodes with the following extended properties:
- _mandiant:iscore
- _mandiant:threat:score
- _mandiant:threat:confidence
- _mandiant:threat:severity
- _mandiant:threat:severity:reasons
MISP labels are applied using the configured tag prefix, e.g. #rep.mandiant.misp.sinkholes.
Category tags from third party sources are applied using the tag prefix and
"3p" namespacing (if the source is not Mandiant). For example, the third party source "phishtank"
would have a category tag #rep.mandiant.3p.phishtank.malware.
When nodes are provided as input this command will also create an it:exec:query node
to represent the query syntax and link resulting nodes to it via -(found)> edges.
The inbound node will have a <(refs)- edge from the it:exec:query node.
The first time --since-last is used it will default to "-24hours".
Examples:
// Retrieve indicators for an FQDN and yield the created nodes
inet:fqdn=myfqdn.com | mandiant.advantage.indicators --yield
// Filter results to a time window
inet:ipv4=8.8.8.8 | mandiant.advantage.indicators --time (2020-01-01, 2020-12-31)
// Ingest a feed of indicator contexts (timebox is required)
mandiant.advantage.indicators --time (-1day, now)
// Create a cron job to ingest new results every day
cron.add --name mandiant.advantage.indicators --hour 3 { mandiant.advantage.indicators --since-last }
Usage: mandiant.advantage.indicators [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.
--icscore <indicators:icscore>: Specify the minimum IC-Score to return in the results. This option can be controlled
through the opts configuration.
--threat-score <indicators:threat_score>: Specify the minimum Threat Score to return in the results (this option can be
controlled through the opts configuration).
--exclude-osint : Exclude OSINT indicators in the results (this option can be controlled through the opts
configuration).
--time <time> : Filter by results within a specific time interval.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
mandiant.advantage.malware
Ingest malware family information from the Mandiant Advantage API.
This command will yield risk:tool:software nodes, with additional data linked
by -(uses)> lightweight edges and nodes tagged with risk:tool:software:tag.
The following enrichments will also be run for each malware family,
and optionally controlled via the specified opts key:
- indicators (opts key = "malware:indicators")
- reports (opts key = "malware:reports")
- vulnerabilities (opts key = "malware:vulns")
The first time --since-last is used it will default to offset=0.
Examples:
// Ingest malware families by name and yield risk:tool:software nodes
mandiant.advantage.malware emotet --yield
// Ingest malware family by a software name
it:prod:softname#foo | mandiant.advantage.malware
// Ingest malware family by risk:tool:software:soft:name
risk:tool:software#foo | mandiant.advantage.malware
// Ingest all malware families
mandiant.advantage.malware --yield
// Exclude "news analysis" reports from the ingest
mandiant.advantage.malware --report-excludes "news analysis"
// Disable parsing associated report PDFs using Synapse-FileParser
mandiant.advantage.malware emotet --yield --opts ({"reports:pdf:fileparser": false})
Usage: mandiant.advantage.malware [options] <name>
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.
--report-includes <report_includes> [<report_includes> ...]: Only include defined report types (case-insensitive).
--report-excludes <report_excludes> [<report_excludes> ...]: Exclude defined report types (case-insensitive).
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
Arguments:
[name] : A malware family name (e.g. emotet)
mandiant.advantage.reports
Ingest reports from the Mandiant Advantage API.
This command will yield media:news nodes with additional data linked
by -(refs)> lightweight edges. Additional text detail may be populated
under the "mandiant:report:detail" node data key.
Reports can be retrieved by a timebox or by ID. If an ID is not provided,
a second API call will be made to ingest the full report for each item in the response.
The PDF version of the report will also be downloaded and parsed by Synapse-FileParser (if available).
The following enrichments will also be run for each report,
and optionally controlled via the specified opts key:
- indicators (opts key = "reports:indicators")
- vulnerabilities (opts key = "reports:vulns")
The first time --since-last is used it will default to "-24hours".
The --includes and --excludes args can be used to restrict ingest to certain report types.
These will not apply if a report id is provided as an argument, and only one of --includes
and --excludes can be specified.
Examples:
// Retrieve reports published within the last day
mandiant.advantage.reports --time ("-1day", "now")
// Limit the number of results to ingest and yield the media:news nodes
mandiant.advantage.reports --time ("-1day", "now") --size 10 --yield
// Ingest a report by id and yield the created media:news node
mandiant.advantage.reports 21-00026118 --yield
// Pivot to refs that were ingested from the report
mandiant.advantage.reports --size 10 --yield | -(refs)> *
// Create a cron job to ingest new results every day
cron.add --name mandiant.advantage.reports --hour 3 { mandiant.advantage.reports --since-last }
// Exclude "news analysis" reports from the ingest
mandiant.advantage.reports --size 10 --yield --excludes "news analysis"
// Change the default minimum threat score when ingesting associated indicators
mandiant.advantage.reports 21-00026118 --yield --opts ({"indicators:threat_score": 10})
// Disable parsing report PDFs using Synapse-FileParser
mandiant.advantage.reports 21-00026118 --opts ({"reports:pdf:fileparser": false})
Usage: mandiant.advantage.reports [options] <id>
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.
--time <time> : Filter by results within a specific time interval.
--includes <report_includes> [<report_includes> ...]: Only include defined report types (case-insensitive).
--excludes <report_excludes> [<report_excludes> ...]: Exclude defined report types (case-insensitive).
--include-actors : Ingest actors associated with the report.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
Arguments:
[id] : The report id (e.g. 21-00026118)
mandiant.advantage.setup.apikey
Manage the Mandiant Advantage API key.
Examples
// Set a global Mandiant Advantage API key
mandiant.advantage.setup.apikey abcd1234 secret1234
// Set a Mandiant Advantage API key for the current user
mandiant.advantage.setup.apikey --self abcd1234 secret1234
// Display the API key scope of the current key
mandiant.advantage.setup.apikey --show-scope
// Display the current API key.
mandiant.advantage.setup.apikey --show-apikey
// Remove the current global API key.
mandiant.advantage.setup.apikey --remove
// Remove the per-user API key for the current user.
mandiant.advantage.setup.apikey --self --remove
Usage: mandiant.advantage.setup.apikey [options] <apikey> <apisecret>
Options:
--help : Display the command usage.
--self : Set or remove the key as a user variable. If not used, the key is set globally.
--show-scope : Display the API key scope in use (global vs self).
--show-apikey : Display the API key value (requires admin perms or a "self" scope key).
--remove : Remove the configured API key. May be used with --self.
Arguments:
[apikey] : The API key string.
[apisecret] : The API key string.
mandiant.advantage.setup.tagprefix
Set the tag prefix used when recording Mandiant Advantage data as tags.
The default tag prefix is "rep.mandiant" if not specified.
Any tags provided by the Mandiant Advantage API will be added within the given namespace.
For example, the item "foo" would result in "#rep.mandiant.foo". Any
characters incompatible with tag names are replaced with "_".
Usage: mandiant.advantage.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
mandiant.advantage.vulns
Ingest vulnerabilities from the Mandiant Advantage API.
Vulnerabilities that do not have a valid CVE id
(e.g., those using the MVE-* format) will be skipped.
This command will yield risk:vuln nodes, with additional data linked
by <(refs)- lightweight edges.
risk:vuln:exploited will be set to True if exploitation_state=Confirmed
or the cisa_known_exploited field is populated. Likewise, risk:vuln:mitigated
will be set to True if available_mitigation is populated.
The following enrichments will also be run for each vulnerability,
and optionally controlled via the specified opts key:
- actors (opts key = "vulns:actors")
- malware (opts key = "vulns:malware")
- reports (opts key = "vulns:reports")
The first time --since-last is used it will default to "-24hours".
Examples:
// Ingest vulnerabilities by CVE id and yield the risk:vuln node
it:sec:cve=cve-2022-28267 | mandiant.advantage.vulns --yield
// Ingest vulnerabilities published within the last day
mandiant.advantage.vulns --time ("-1day", "now")
// Create a cron job to ingest new results every day
cron.add --name mandiant.advantage.vulns --hour 3 { mandiant.advantage.vulns --since-last }
// Exclude "news analysis" reports from the ingest
mandiant.advantage.vulns --time ("-1day", "now") --report-excludes "news analysis"
Usage: mandiant.advantage.vulns [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.
--time <time> : Filter by results within a specific time interval.
--since-last : Retrieve results since the last run of the command with --since-last specified.
--report-includes <report_includes> [<report_includes> ...]: Only include defined report types (case-insensitive).
--report-excludes <report_excludes> [<report_excludes> ...]: Exclude defined report types (case-insensitive).
--full : Enable all recursive ingests up to the depth limit.
--opts <opts> : An options dictionary to control ingest functionality.
--show-opts : Show the merged opts for this command and exit.
Storm Modules
This package does not export any Storm APIs.