Package Documentation
Storm Package: synapse-microsoft-defender
The following Commands are available from this package. This documentation is generated for version 0.6.0 of the package.
Storm Commands
This package implements the following Storm Commands.
microsoft.defender.365.alerts
Retrieve alerts from the Microsoft Defender 365 API.
This command retrieves alerts matching the specified filters
and creates risk:alert nodes to represent them. Alert evidence
is also ingested, and will have a -(refs)> edge to the risk:alert.
The --updated and --created options are parsed as ival types,
and therefore single values and relative times are valid inputs.
Examples:
// Ingest an alert by id
microsoft.defender.365.alerts --id 123 --yield
// Ingest alerts created on or after 2023-11-06
microsoft.defender.365.alerts --created (2023-11-06, now)
// Also create a proj:ticket node to track work being done on the alert
microsoft.defender.365.alerts --create-ticket
Usage: microsoft.defender.365.alerts [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.
--create-ticket : Create a proj:ticket to track work being done on the risk:alert.
--id <id> : Filter by the alert ID.
--created <created> : Filter alerts for createdDateTime within the specified time interval.
--updated <updated> : Filter alerts for lastUpdateDateTime within the specified time interval.
--assignee <assignee> : Filter alerts for assignedTo equal to the specified value.
--status <status> : Filter alerts for status equal to the specified value. (choices: new, inProgress,
resolved)
--severity <severity> : Filter alerts for severity equal to the specified value. (choices: unknown,
informational, low, medium, high)
--source <source> : Filter alerts for serviceSource equal to the specified value.
microsoft.defender.365.incidents
Retrieve incidents from the Microsoft Defender 365 API.
This command retrieves incidents matching the specified filters,
and creates risk:attack nodes to represent them. Associated alerts
are also ingested, and will have the :attack property set to the
parent risk:attack node.
The --updated and --created options are parsed as ival types,
and therefore single values and relative times are valid inputs.
Examples:
// Ingest an incident by id
microsoft.defender.365.incidents --id 123 --yield
// Ingest incidents created on or after 2023-11-06
microsoft.defender.365.incidents --created (2023-11-06, now)
// Also create a proj:ticket to represent the incident
microsoft.defender.365.incidents --create-ticket
Usage: microsoft.defender.365.incidents [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.
--create-ticket : Create a proj:ticket to track work on the linked risk:attack.
--id <id> : Filter by the incident ID.
--created <created> : Filter incidents for createdDateTime within the specified time interval.
--updated <updated> : Filter incidents for lastUpdateDateTime within the specified time interval.
--assignee <assignee> : Filter incidents for assignedTo equal to the specified value.
--status <status> : Filter incidents for status equal to the specified value. (choices: active, inProgress,
resolved, redirected, awaitingAction)
--severity <severity> : Filter incidents for severity equal to the specified value. (choices: unknown,
informational, low, medium, high)
microsoft.defender.365.setup.client
Manage the Microsoft Defender 365 API client configuration.
Examples
// Set a global Microsoft Defender 365 API client
microsoft.defender.365.setup.client tenantId00 clientId00 secret00
// Set a Microsoft Defender 365 API client for the current user
microsoft.defender.365.setup.client --self tenantId00 clientId00 secret00
// Display the API client scope of the current configuration.
microsoft.defender.365.setup.client --show-scope
// Display the current API client configuration
microsoft.defender.365.setup.client --show-client
// Remove the current global API client configuration
microsoft.defender.365.setup.client --remove
// Remove the per-user API client configuration for the current user
microsoft.defender.365.setup.client --self --remove
Usage: microsoft.defender.365.setup.client [options] <tenant> <client> <secret>
Options:
--help : Display the command usage.
--self : Set or remove the configuration for the current user. If not used, it is set globally.
--show-scope : Display the API configuration scope in use (global vs self).
--show-client : Display the API client configuration (requires admin perms or a "self" scope
configuration).
--remove : Remove the configured API client. May be used with --self.
Arguments:
[tenant] : The tenant ID.
[client] : The client ID.
[secret] : The client secret value.
microsoft.defender.365.setup.tagprefix
Set the tag prefix used when recording Microsoft Defender 365 data as tags.
A tag prefix is not set by default, and therefore no Microsoft Defender 365
tags will be added to nodes by default.
Any tags provided by the Microsoft Defender 365 API will be added within the given namespace.
For example, the item "foo" would result in "#rep.microsoft.defender.365.foo". Any
characters incompatible with tag names are replaced with "_".
Usage: microsoft.defender.365.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
microsoft.defender.endpoint.alerts
Retrieve alerts from the Microsoft Defender for Endpoint API.
This command retrieves alerts matching the specified filters
and creates risk:alert nodes to represent them. Alert evidence is also
ingested, and will have a -(refs)> edge to the risk:alert.
The --updated and --created options are parsed as ival types,
and therefore single values and relative times are valid inputs.
Examples:
// Ingest an alert by id
microsoft.defender.endpoint.alerts --id 123 --yield
// Ingest alerts created on or after 2023-11-06
microsoft.defender.endpoint.alerts --created (2023-11-06, now)
// Also create a proj:ticket node to track work being done on the alert
microsoft.defender.endpoint.alerts --create-ticket
Usage: microsoft.defender.endpoint.alerts [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.
--create-ticket : Create a proj:ticket that references the risk:alert.
--id <id> : Filter by the alert ID.
--created <created> : Filter incidents for alertCreationTime within the specified time interval.
--updated <updated> : Filter incidents for lastUpdateTime within the specified time interval.
--assignee <assignee> : Filter alerts for assignedTo equal to the specified value.
--status <status> : Filter alerts for status equal to the specified value. (choices: Unknown, New,
InProgress, Resolved)
--severity <severity> : Filter alerts for severity equal to the specified value. (choices: UnSpecified,
Informational, Low, Medium, High)
microsoft.defender.endpoint.setup.client
Manage the Microsoft Defender for Endpoint API client configuration.
Examples
// Set a global Microsoft Defender for Endpoint API client
microsoft.defender.endpoint.setup.client tenantId00 clientId00 secret00
// Set a Microsoft Defender for Endpoint API client for the current user
microsoft.defender.endpoint.setup.client --self tenantId00 clientId00 secret00
// Display the API client scope of the current configuration
microsoft.defender.endpoint.setup.client --show-scope
// Display the current API client configuration
microsoft.defender.endpoint.setup.client --show-client
// Remove the current global API client configuration
microsoft.defender.endpoint.setup.client --remove
// Remove the per-user API client configuration for the current user
microsoft.defender.endpoint.setup.client --self --remove
Usage: microsoft.defender.endpoint.setup.client [options] <tenant> <client> <secret>
Options:
--help : Display the command usage.
--self : Set or remove the configuration for the current user. If not used, it is set globally.
--show-scope : Display the API configuration scope in use (global vs self).
--show-client : Display the API client configuration (requires admin perms or a "self" scope
configuration).
--remove : Remove the configured API client. May be used with --self.
Arguments:
[tenant] : The tenant ID.
[client] : The client ID.
[secret] : The client secret value.
microsoft.defender.ti.articles
Get articles from Microsoft Defender TI.
If --id is specified, this command queries the /security/threatIntelligence/articles/{id} endpoint.
Otherwise, the /security/threatIntelligence/articles endpoint is queried with the optional query string.
If a query string is provided this command will also create an
it:exec:query node to represent the query syntax
and link resulting nodes to it via -(found)> edges.
For each result a media:news node is created, which will have a -(refs)> edge
to indicators retrieved from the /security/threatIntelligence/articles/{id}/indicators endpoint.
Examples:
// Get an article by id and yield the media:news node
microsoft.defender.ti.articles --id 1bebd94c --yield
// Get articles by a query string
microsoft.defender.ti.articles --query phishing
// Get all articles
microsoft.defender.ti.articles --yield
Usage: microsoft.defender.ti.articles [options]
Options:
--help : Display the command usage.
--id <id> : Retrieve an article by id.
--query <query> : An optional query string.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.pdns
Get passive DNS information from Microsoft Defender TI.
This command takes inet:ipv4, inet:ipv6, or inet:fqdn nodes as input and queries the
/security/threatIntelligence/hosts/{input}/passiveDns endpoint.
The results are used to create inet:dns:* nodes, with their .seen property
set to the first/last seen times provided in the response.
Examples:
// Get pDNS information about an IP
inet:ipv4=129.186.1.100 | microsoft.defender.ti.pdns
// Get pDNS information about a domain and yield the created nodes
inet:fqdn=foo.com | microsoft.defender.ti.pdns --yield
Usage: microsoft.defender.ti.pdns [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.profiles
Retrieve and ingest intel profiles from Microsoft Defender TI.
If this command is run with no arguments, a full sync of all threat actor and tool profiles will be performed. An
example of running a full sync via cron job can be seen below.
If --id is specified, this command queries the /security/threatIntelligence/intelProfiles/{id} endpoint.
Otherwise, the /security/threatIntelligence/intelProfiles endpoint is queried with the optional query string.
If a query string is provided this command will also create an it:exec:query node to represent the query syntax
and link resulting nodes to it via -(found)> edges.
For each result, a risk:threat node is created for actors and a risk:tool:software node is created for tools.
Both node types indicators will be retrieved from the /security/threatIntelligence/intelProfiles/{id}/indicators
endpoint and tagged with the same tag that is specified in the risk:threat:tag or risk:tool:software:tag property.
If the :tag property doesn't already exist, a tag will be automatically generated.
Both node types will also have -(refs)> edges to any nodes scraped from the :desc property
Examples:
// Get all intel profiles
microsoft.defender.ti.profiles --yield
// Get an actor intel profile by id and yield the risk:threat node
microsoft.defender.ti.profiles --id 9b01de37bf66d1760954a16dc2b52fed2a7bd4e093dfc8a4905e108e4843da80 --yield
// Get a tool intel profile by id and yield the risk:tool:software node
microsoft.defender.ti.profiles --id 0116783ab9da099992ec014985d7c56bfe2d8c360c6e7dd6cd39c8d65553ab68 --yield
// Get intel profiles by a query string
microsoft.defender.ti.profiles --query "aqua blizzard"
// Get intel profiles by a query string without retrieving the associated indicators
microsoft.defender.ti.profiles --query "cinnamon tempest" --no-indicators
// Create a cron job to periodically sync all profiles
cron.add --day +1 { microsoft.defender.ti.profiles }
Usage: microsoft.defender.ti.profiles [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.
--id <id> : Retrieve an intel profile by id.
--query <query> : An optional query string.
--no-indicators : Do not retrieve linked indicators.
microsoft.defender.ti.reputation
Enrich an FQDN with reputation data from Microsoft Defender TI.
This command takes inet:fqdn nodes as input and queries the
/security/threatIntelligence/hosts/{fqdn}/reputation endpoint.
The results are used to add :_microsoft:reputation and a classification
tag to the inbound FQDN. Matching rules are recorded via
meta:rule -(matches)> inet:fqdn.
Examples:
// Enrich an FQDN
inet:fqdn=vertex.link | microsoft.defender.ti.reputation
// Enrich an FQDN and pivot to the matching rules
inet:fqdn=vertex.link | microsoft.defender.ti.reputation | <(matches)- meta:rule
Usage: microsoft.defender.ti.reputation [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
microsoft.defender.ti.services
Get exposed service details from Microsoft Defender TI.
This command takes inet:ipv4 or inet:ipv6 nodes as input for queries to the
/security/threatIntelligence/hosts/{input}/ports endpoint.
Examples:
// Search for exposed service details by IPv4 and yield inet:flow nodes
inet:ipv4=8.8.8.8 | microsoft.defender.ti.services --yield
Usage: microsoft.defender.ti.services [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.setup.client
Manage the Microsoft Defender Threat Intelligence (TI) API client configuration.
Examples
// Set a global Microsoft Defender TI API client
microsoft.defender.ti.setup.client tenantId00 clientId00 secret00
// Set a Microsoft Defender TI API client for the current user
microsoft.defender.ti.setup.client --self tenantId00 clientId00 secret00
// Display the API client scope of the current configuration
microsoft.defender.ti.setup.client --show-scope
// Display the current API client configuration.
microsoft.defender.ti.setup.client --show-client
// Remove the current global API client configuration.
microsoft.defender.ti.setup.client --remove
// Remove the per-user API client configuration for the current user.
microsoft.defender.ti.setup.client --self --remove
Usage: microsoft.defender.ti.setup.client [options] <tenant> <client> <secret>
Options:
--help : Display the command usage.
--self : Set or remove the configuration for the current user. If not used, it is set globally.
--show-scope : Display the API configuration scope in use (global vs self).
--show-client : Display the API client configuration (requires admin perms or a "self" scope
configuration).
--remove : Remove the configured API client. May be used with --self.
Arguments:
[tenant] : The tenant ID.
[client] : The client ID.
[secret] : The client secret value.
microsoft.defender.ti.setup.tagprefix
Set the tag prefix used when recording Microsoft Defender Threat Intelligence data as tags.
By default the tag prefix "rep.microsoft" will be used.
Any tags provided by the Microsoft Defender TI API will be added within the given namespace.
For example, the item "foo" would result in "#rep.microsoft.foo". Any
characters incompatible with tag names are replaced with "_".
Usage: microsoft.defender.ti.setup.tagprefix [options] <tagname>
Options:
--help : Display the command usage.
Arguments:
<tagname> : The tag prefix to use.
microsoft.defender.ti.ssl.hosts
Get SSL certificates for a host from Microsoft Defender TI.
This command takes inet:ipv4 or inet:ipv6 nodes as input for queries to the
/security/threatIntelligence/hosts/{input}/sslCertificates endpoint.
If an inet:server or inet:ssl:cert node is provided as input this command
will pivot to the inet:ipv4 or inet:ipv6 to generate the query.
Examples:
// Get certificates for an IPv4 and yield inet:ssl:cert nodes
inet:ipv4=8.8.8.8 | microsoft.defender.ti.ssl.hosts --yield
Usage: microsoft.defender.ti.ssl.hosts [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.ssl.search
Search for SSL certificates from Microsoft Defender TI.
This command takes a hash:sha1 or query string as input for queries to the
/security/threatIntelligence/sslCertificates endpoint.
If a query string is provided this command will also create an
it:exec:query node to represent the query syntax
and link resulting nodes to it via -(found)> edges.
For details on the query string please see:
https://learn.microsoft.com/en-us/graph/api/security-threatintelligence-list-sslcertificates
Examples:
// Query by SHA-1 and yield crypto:x509:cert nodes
hash:sha1#foo | microsoft.defender.ti.ssl.search --yield
// Specify a query string
microsoft.defender.ti.ssl.search "issuer/commonName:Contoso"
Usage: microsoft.defender.ti.ssl.search [options] <query>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
Arguments:
[query] : The search query string.
microsoft.defender.ti.subdomains
Get subdomains from Microsoft Defender TI.
This command takes inet:fqdn nodes as input and queries the
/security/threatIntelligence/hosts/{fqdn}/subdomains endpoint.
The results are used to create inet:fqdn nodes for each subdomain returned.
Wildcards are stripped before creating for the FQDN,
e.g. "*.foo.bar.com" will be added as "foo.bar.com".
Examples:
// Get subdomains for an FQDN and yield the created nodes
inet:fqdn=vertex.link | microsoft.defender.ti.subdomains --yield
Usage: microsoft.defender.ti.subdomains [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.whois
Get WHOIS information from Microsoft Defender TI.
This command takes inet:fqdn or inet:ipv4 nodes as input and queries the
/security/threatIntelligence/hosts/{value}/whois endpoint.
If an inet:fqdn is provided 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.
If an inet:ipv4 is provided the results are used to create inet:whois:iprec nodes
representing the WHOIS records, as well as inet:whois:ipcontact nodes for contacts
associated with the record. Since the records are not parsed in the response a unique
inet:whois:iprec is created for each IPv4.
Examples:
// Get WHOIS information for an FQDN and yield the created node
inet:fqdn=vertex.link | microsoft.defender.ti.whois --yield
Usage: microsoft.defender.ti.whois [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
microsoft.defender.ti.whois.history
Get WHOIS history information from Microsoft Defender TI.
This command takes inet:fqdn or inet:ipv4 nodes as input and queries the
/security/threatIntelligence/hosts/{value}/whois/history endpoint.
If an inet:fqdn is provided 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.
If an inet:ipv4 is provided the results are used to create inet:whois:iprec nodes
representing the WHOIS records, as well as inet:whois:ipcontact nodes for contacts
associated with the record. Since the records are not parsed in the response a unique
inet:whois:iprec is created for each IPv4.
Examples:
// Get WHOIS history for an FQDN and yield the created nodes
inet:fqdn=vertex.link | microsoft.defender.ti.whois.history --yield
Usage: microsoft.defender.ti.whois.history [options]
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--yield : Yield the newly created nodes.
--size <size> : Limit the number of results ingested to the given size (per-node).
microsoft.defender.ti.whois.search
Search WHOIS information from Microsoft Defender TI.
This command takes a query string as input and queries the
/security/threatIntelligence/whoisRecords endpoint.
For details on the query string please see:
https://learn.microsoft.com/en-us/graph/api/security-threatintelligence-list-whoisrecords
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 WHOIS data for a technical contact city and yield the created nodes
microsoft.defender.ti.whois.search "technical/address/city:pasadena" --yield
Usage: microsoft.defender.ti.whois.search [options] <query>
Options:
--help : Display the command usage.
--debug : Show verbose debug output.
--size <size> : Limit the number of results ingested to the given size (per-node).
--yield : Yield the newly created nodes.
Arguments:
<query> : The search query string.
Storm Modules
This package does not export any Storm APIs.