Package Documentation
Storm Package: synapse-mandiant
The following Commands are available from this package. This documentation is generated for version 4.0.1 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})
Endpoints:
(user-configured base URL)
/v4/actor : Retrieve threat actors.
/v4/actor/{id} : Retrieve a threat actor.
/v4/actor/{id}/history : Retrieve the alias history of a threat actor.
/v4/actor/{id}/reports : Retrieve reports for a threat actor.
/v4/actor/{id}/attack-pattern: Retrieve MITRE ATT&CK mappings for a threat actor.
/v4/actor/{id}/indicators : Retrieve indicators for a threat actor.
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.
--config <config> : Override the default config with the provided name.
Arguments:
[name] : An actor name (e.g. apt1)
Inputs:
ou:name : ou:name nodes
ou:org : ou:org nodes
risk:threat : risk:threat nodes
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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})
Endpoints:
(user-configured base URL)
/v4/campaign : Retrieve campaigns.
/v4/campaign/{id} : Retrieve a campaign.
/v4/campaign/{id}/reports : Retrieve reports for a campaign.
/v4/campaign/{id}/attack-pattern: Retrieve MITRE ATT&CK mappings for a campaign.
/v4/campaign/{id}/indicators: Retrieve indicators for a campaign.
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.
--config <config> : Override the default config with the provided name.
Arguments:
[id] : The campaign id (e.g. CAMP.22.063)
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
mandiant.advantage.config.add
Add a Synapse-Mandiant 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
mandiant.advantage.config.add default mykeyid myapisecret
// Add a configuration for the current user
mandiant.advantage.config.add --scope self myconfig mykeyid myapisecret
Usage: mandiant.advantage.config.add [options] <name> <keyid> <apisecret>
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 Mandiant Advantage tags. (default: rep.mandiant)
--scope <scope> : Set the scope on the configuration. (default: global, choices: global, self, unscoped)
Arguments:
<name> : A unique name for the configuration.
<keyid> : The Mandiant Advantage API Key ID.
<apisecret> : The Mandiant Advantage API key secret string.
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
mandiant.advantage.config.del
Delete a Synapse-Mandiant configuration.
Examples:
// Delete the "myconfig" configuration
mandiant.advantage.config.del myconfig
Usage: mandiant.advantage.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.mandiant.advantage.adminpower-ups.mandiant.advantage.user
mandiant.advantage.config.list
Display the list of Synapse-Mandiant configurations you have access to.
Usage: mandiant.advantage.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.mandiant.advantage.adminpower-ups.mandiant.advantage.user
mandiant.advantage.config.migrate
Migrate options for all Synapse-Mandiant 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:
// Disable SSL verification for all configurations
mandiant.advantage.config.migrate --ssl-verify (false)
// Migrate the tag prefix for all configurations
mandiant.advantage.config.migrate --tag-prefix my.tagpref
Usage: mandiant.advantage.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 Mandiant Advantage tags. (default: None)
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.admin
mandiant.advantage.config.show
Show the details of a configuration.
Examples:
// Show the in-use configuration for the current user
mandiant.advantage.config.show
// Show a configuration by name
mandiant.advantage.config.show myconfig
Usage: mandiant.advantage.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.mandiant.advantage.adminpower-ups.mandiant.advantage.user
mandiant.advantage.config.update
Update the configuration of a defined Synapse-Mandiant 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 "myconfig"
// configuration
mandiant.advantage.config.update myconfig --perm user myuser admin
// Set the permission level for the "all" role to "deny" on the
// "myconfig" configuration
mandiant.advantage.config.update myconfig --perm role all deny
// Do not verify the SSL certificate when connecting to "myconfig"
mandiant.advantage.config.update myconfig --ssl-verify (false)
// Change the tag prefix used by the "myconfig" configuration
mandiant.advantage.config.update myconfig --tag-prefix my.prefix
// Change the name of the "myconfig" configuration to "otherconfig"
mandiant.advantage.config.update myconfig --name otherconfig
Usage: mandiant.advantage.config.update [options] <config>
Options:
--help : Display the command usage.
--keyid <keyid> : The Mandiant Advantage API Key ID. (default: None)
--apisecret <apisecret> : The Mandiant Advantage API key secret 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 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)
--tag-prefix <tag_prefix> : The tag prefix to use when recording Mandiant Advantage tags. (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.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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)
Endpoints:
(user-configured base URL)
/v4/dtm/alerts : Retrieve DTM alerts.
/v4/dtm/alerts/{id} : Retrieve a DTM alert.
/v4/dtm/monitors/{id} : Retrieve a DTM monitor.
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.
--config <config> : Override the default config with the provided name.
Arguments:
[id] : Retrieve alert by id.
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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 }
Endpoints:
(user-configured base URL)
/v4/indicator : Retrieve indicators.
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.
--config <config> : Override the default config with the provided name.
Inputs:
file:bytes : file:bytes nodes
hash:md5 : hash:md5 nodes
hash:sha1 : hash:sha1 nodes
hash:sha256 : hash:sha256 nodes
inet:email : inet:email nodes
inet:fqdn : inet:fqdn nodes
inet:ipv4 : inet:ipv4 nodes
inet:ipv6 : inet:ipv6 nodes
inet:url : inet:url nodes
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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})
Endpoints:
(user-configured base URL)
/v4/malware : Retrieve malware families.
/v4/malware/{id} : Retrieve a malware family.
/v4/malware/{id}/reports : Retrieve reports for a malware family.
/v4/malware/{id}/indicators: Retrieve indicators for a malware family.
/v4/malware/{id}/yara : Retrieve YARA rules for a malware family.
/v4/yara : Retrieve the next page of YARA rules.
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.
--config <config> : Override the default config with the provided name.
Arguments:
[name] : A malware family name (e.g. emotet)
Inputs:
it:prod:softname : it:prod:softname nodes
risk:tool:software : risk:tool:software nodes
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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})
Endpoints:
(user-configured base URL)
/v4/reports : Retrieve reports.
/v4/report/{id} : Retrieve a report by ID, including the report PDF.
/v4/report/{id}/indicators: Retrieve indicators for a report.
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.
--config <config> : Override the default config with the provided name.
Arguments:
[id] : The report id (e.g. 21-00026118)
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
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"
Endpoints:
(user-configured base URL)
/v4/vulnerability : Retrieve vulnerabilities.
/v4/vulnerability/{id} : Retrieve a vulnerability by CVE ID.
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.
--config <config> : Override the default config with the provided name.
Inputs:
it:sec:cve : it:sec:cve nodes
risk:vuln : risk:vuln nodes
The command is accessible to users with one or more of the following permissions:
power-ups.mandiant.advantage.adminpower-ups.mandiant.advantage.user
Storm Modules
This package does not export any Storm APIs.