Package Documentation

Storm Package: synapse-microsoft-defender

The following Commands are available from this package. This documentation is generated for version 0.5.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.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.