category: Network Security
provider: Microsoft
sectionorder:
- Connect
- Collect
commonfields:
  id: Microsoft 365 Defender
  version: -1
configuration:
- additionalinfo: |-
    The United States: api-us.security.microsoft.com
    Europe: api-eu.security.microsoft.com
    The United Kingdom: api-uk.security.microsoft.co
  defaultvalue: https://api.security.microsoft.com
  display: Endpoint URI
  name: base_url
  required: true
  type: 0
  section: Connect
- name: creds_client_id
  type: 9
  displaypassword: ID or Client ID
  hiddenusername: true
  section: Connect
  required: false
- name: creds_tenant_id
  type: 9
  displaypassword: Token or Tenant ID
  hiddenusername: true
  section: Connect
  required: false
- additionalinfo: The API key to use to connect.
  defaultvalue: 9093c354-630a-47f1-b087-6768eb9427e6
  display: Application ID
  name: _app_id
  type: 0
  section: Connect
  hidden: true
  required: false
- additionalinfo: Use a self-deployed Azure application and authenticate using the Client Credentials flow.
  display: Use Client Credentials Authorization Flow
  name: client_credentials
  type: 8
  section: Connect
  required: false
- display: Tenant ID (for Client Credentials mode)
  name: _tenant_id
  type: 0
  section: Connect
  hidden: true
  required: false
- display: Client Secret (for Client Credentials mode)
  hiddenusername: true
  name: credentials
  type: 9
  section: Connect
  displaypassword: Client Secret
  required: false
- additionalinfo: Used for certificate authentication. As appears in the "Certificates & secrets" page of the app.
  display: Certificate Thumbprint
  name: creds_certificate
  type: 9
  displaypassword: Private Key
  section: Connect
  advanced: true
  required: false
- additionalinfo: Used for certificate authentication. As appears in the "Certificates & secrets" page of the app.
  display: Certificate Thumbprint
  name: certificate_thumbprint
  type: 4
  section: Connect
  advanced: true
  hidden: true
  required: false
- additionalinfo: Used for certificate authentication. The private key of the registered certificate.
  display: Private Key
  name: private_key
  type: 14
  section: Connect
  advanced: true
  hidden: true
  required: false
- additionalinfo: Relevant only if the integration is running on Azure VM. If selected, authenticates based on the value provided for the Azure Managed Identities Client ID field. If no value is provided for the Azure Managed Identities Client ID field, authenticates based on the System Assigned Managed Identity. For additional information, see the Help tab.
  display: Use Azure Managed Identities
  name: use_managed_identities
  type: 8
  section: Connect
  advanced: true
  required: false
- additionalinfo: The Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.
  displaypassword: Azure Managed Identities Client ID
  name: managed_identities_client_id
  hiddenusername: true
  type: 9
  section: Connect
  advanced: true
  required: false
- defaultvalue: 12 hours
  display: First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
  name: first_fetch
  type: 0
  section: Collect
  required: false
- additionalinfo: The time limit in seconds for fetch incidents to run. Leave this empty to cancel the timeout limit.
  defaultvalue: '30'
  display: Fetch incidents timeout
  name: fetch_timeout
  type: 0
  section: Collect
  advanced: true
  required: false
- additionalinfo: Due to API limitations, the maximum is 100.
  defaultvalue: '10'
  display: Number of incidents for each fetch.
  name: max_fetch
  type: 0
  section: Collect
  required: false
  supportedModules:
  - agentix
  - xsiam
- defaultvalue: Microsoft 365 Defender Incident
  display: Incident type
  name: incidentType
  type: 13
  section: Connect
  required: false
  supportedModules:
  - agentix
  - xsiam
- display: Fetch incidents
  name: isFetch
  type: 8
  section: Collect
  required: false
  supportedModules:
  - agentix
  - xsiam
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Use system proxy settings
  name: proxy
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Application ID (Deprecated)
  hidden: true
  name: app_id
  type: 4
  section: Connect
  advanced: true
  required: false
- display: Tenant ID (for Client Credentials mode) (Deprecated)
  hidden: true
  name: tenant_id
  type: 4
  section: Connect
  advanced: true
  required: false
- display: Client Secret (for Client Credentials mode) (Deprecated)
  hidden: true
  name: enc_key
  type: 4
  section: Connect
  advanced: true
  required: false
- defaultvalue: '1'
  display: Incidents Fetch Interval
  name: incidentFetchInterval
  type: 19
  section: Connect
  advanced: true
  required: false
  supportedModules:
  - agentix
  - xsiam
- additionalinfo: 'Choose the direction to mirror the incident: Incoming (from Microsoft 365 Defender to Cortex XSOAR), Outgoing (from Cortex XSOAR to  Microsoft 365 Defender), or Incoming and Outgoing (from/to Cortex XSOAR and  Microsoft 365 Defender).'
  defaultvalue: None
  display: Incident Mirroring Direction
  name: mirror_direction
  options:
  - None
  - Incoming
  - Outgoing
  - Incoming And Outgoing
  type: 15
  section: Collect
  hidden:
  - marketplacev2
  - platform
  required: false
- additionalinfo: Incoming Mirroring - when selected, closing the Microsoft 365 Defender incident is mirrored in Cortex XSOAR.
  defaultvalue: 'false'
  display: Close Mirrored Cortex XSOAR Incidents
  name: close_incident
  type: 8
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- display: Enable custom XSOAR to Defender Close Reason
  name: custom_xsoar_to_defender_close_reason
  defaultvalue: "false"
  type: 8
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- display: Enable custom Defender to XSOAR Close Reason
  name: custom_defender_to_xsoar_close_reason
  defaultvalue: "false"
  type: 8
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- additionalinfo: Outgoing Mirroring - when selected, closing the Cortex XSOAR incident is mirrored in Microsoft 365 Defender.
  defaultvalue: 'false'
  display: Close Mirrored Microsoft 365 Defender Incidents
  name: close_out
  type: 8
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- additionalinfo: Choose a tag to add to an entry to mirror it as a comment into Microsoft 365 Defender.
  defaultvalue: CommentToMicrosoft365Defender
  display: Comment Entry Tag To Microsoft 365 Defender
  name: comment_tag
  type: 0
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- additionalinfo: Choose a tag to add to an entry to mirror it as a comment from Microsoft 365 Defender.
  defaultvalue: CommentFromMicrosoft365Defender
  display: Comment Entry Tag From Microsoft 365 Defender
  name: comment_tag_from_microsoft365defender
  type: 0
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
- additionalinfo: 'Define how to close the mirrored incidents from Cortex XSOAR into Defender with a custom close reason mapping. Enter a comma-separated list of close reasons (acceptable format {Cortex XSOAR close reason}={Defender close reason}) to override the default close reason mapping defined by Cortex XSOAR. Note that the mapping must be configured accordingly with the existing close reasons in Cortex XSOAR and Defender. Not following this format will result in closing the incident with a default close reason. Example: "True Positive=TruePositive-Other,False Positive=FalsePositive-Other". Refer to ../README.md for possible close-reasons - `Defender Incident Mirroring`.'
  name: custom_xsoar_to_defender_close_reason_mapping
  type: 0
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
  display: Custom close-reason mapping (XSOAR -> Defender mirrored incident)
- additionalinfo: 'Define how to close the mirrored incidents from Defender into Cortex XSOAR with a custom close reason mapping. Enter a comma-separated list of close reasons (acceptable format {Defender close reason}={Cortex XSOAR close reason}) to override the default close reason mapping defined by Cortex XSOAR. Note that the mapping must be configured accordingly with the existing close reasons in Cortex XSOAR and Defender. Not following this format will result in closing the incident with a default close reason. Example: “Known Issue=Resolved, Duplicate Incident=Other". Refer to ../README.md for possible close-reasons - `Defender Incident Mirroring`.'
  name: custom_defender_to_xsoar_close_reason_mapping
  type: 0
  section: Collect
  advanced: true
  hidden:
  - marketplacev2
  - platform
  required: false
  display: Custom close-reason mapping (Defender -> XSOAR mirrored incident)
description: Microsoft 365 Defender is a unified pre- and post-breach enterprise defense suite that natively coordinates detection, prevention, investigation, and response across endpoints, identities, email, and applications to provide integrated protection against sophisticated attacks.
display: Microsoft 365 Defender
name: Microsoft 365 Defender
script:
  commands:
  - arguments: []
    description: Run this command to start the authorization process and follow the instructions in the command results. (for device-code mode).
    name: microsoft-365-defender-auth-start
  - arguments: []
    description: Run this command to complete the authorization process. Should be used after running the microsoft-365-defender-auth-start command. (for device-code mode).
    name: microsoft-365-defender-auth-complete
  - arguments: []
    description: Run this command if for some reason you need to rerun the authentication process.
    name: microsoft-365-defender-auth-reset
  - arguments: []
    description: Tests the connectivity to the Microsoft 365 Defender.
    name: microsoft-365-defender-auth-test
  - arguments:
    - auto: PREDEFINED
      description: Categorize incidents (as Active, Resolved, or Redirected).
      name: status
      predefined:
      - Active
      - Resolved
      - Redirected
    - description: Owner of the incident.
      name: assigned_to
    - defaultValue: '100'
      description: Number of incidents in the list. Maximum is 100.
      name: limit
    - description: Number of entries to skip.
      name: offset
    - defaultValue: '30'
      description: The time limit in seconds for the http request to run.
      name: timeout
    - description: 'Filter incidents using odata query: https://docs.microsoft.com/en-us/microsoft-365/security/defender/api-list-incidents?view=o365-worldwide. Example: `{"$filter":"lastUpdateTime gt 2022-08-29T06:00:00.29Z"}`.'
      name: odata
    description: Get the most recent incidents.
    name: microsoft-365-defender-incidents-list
    outputs:
    - contextPath: Microsoft365Defender.Incident.incidentId
      description: Incident's ID.
      type: Number
    - contextPath: Microsoft365Defender.Incident.redirectIncidentId
      description: Only populated in case an incident is grouped together with another incident, as part of the incident processing logic.
      type: Unknown
    - contextPath: Microsoft365Defender.Incident.incidentName
      description: The name of the incident.
      type: String
    - contextPath: Microsoft365Defender.Incident.createdTime
      description: The date and time (in UTC) the incident was created.
      type: Date
    - contextPath: Microsoft365Defender.Incident.lastUpdateTime
      description: The date and time (in UTC) the incident was last updated.
      type: Date
    - contextPath: Microsoft365Defender.Incident.assignedTo
      description: Owner of the incident.
      type: String
    - contextPath: Microsoft365Defender.Incident.classification
      description: 'Specification of the incident. Possible values are: Unknown, FalsePositive, and TruePositive.'
      type: String
    - contextPath: Microsoft365Defender.Incident.determination
      description: 'The determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.'
      type: String
    - contextPath: Microsoft365Defender.Incident.status
      description: 'The current status of the incident. Possible values are: Active, Resolved, and Redirected.'
      type: String
    - contextPath: Microsoft365Defender.Incident.severity
      description: 'Severity of the incident. Possible values are: UnSpecified, Informational, Low, Medium, and High.'
      type: String
    - contextPath: Microsoft365Defender.Incident.alerts
      description: List of alerts relevant for the incidents.
      type: Unknown
    - contextPath: Microsoft365Defender.Incident.tags
      description: List of custom tags associated with an incident, for example to flag a group of incidents with a common characteristic.
    - contextPath: Microsoft365Defender.Incident.comments
      description: List of comments created by secops when managing the incident, for example additional information about the classification selection.
  - arguments:
    - auto: PREDEFINED
      description: Categorize incidents (as Active, Resolved, or Redirected).
      name: status
      predefined:
      - Active
      - Resolved
      - Redirected
      - InProgress
    - description: Owner of the incident.
      name: assigned_to
    - description: Incident's ID.
      name: id
      required: true
    - auto: PREDEFINED
      description: The specification for the incident.
      name: classification
      predefined:
      - Unknown
      - FalsePositive
      - TruePositive
      - InformationalExpectedActivity
    - description: 'Determination of the incident. Must be used with the classification field. Possible values depend on the classification field: TruePositive - MultiStagedAttack, MaliciousUserActivity, Malware, Phishing, CompromisedAccount, UnwantedSoftware, Other (default), InformationalExpectedActivity- SecurityTesting, LineOfBusinessApplication, ConfirmedActivity, Other (default), FalsePositive - NotMalicious, NoEnoughDataToValidate, Other (default), Unknown - NotAvailable.'
      name: determination
      auto: PREDEFINED
      predefined:
      - MultiStagedAttack
      - MaliciousUserActivity
      - Malware
      - Phishing
      - CompromisedAccount
      - UnwantedSoftware
      - Other
      - SecurityTesting
      - LineOfBusinessApplication
      - ConfirmedActivity
      - NotMalicious
      - NoEnoughDataToValidate
      - NotAvailable
    - description: Comment to be added to the incident.
      name: comment
    - description: 'A comma-separated list of custom tags associated with an incident. For example: tag1,tag2,tag3.'
      isArray: true
      name: tags
    - defaultValue: '30'
      description: The time limit in seconds for the http request to run.
      name: timeout
    description: Update the incident with the given ID.
    name: microsoft-365-defender-incident-update
    outputs:
    - contextPath: Microsoft365Defender.Incident.incidentId
      description: Incident's ID.
      type: Number
    - contextPath: Microsoft365Defender.Incident.redirectIncidentId
      description: Only populated in case an incident is grouped together with another incident, as part of the incident processing logic.
      type: Unknown
    - contextPath: Microsoft365Defender.Incident.incidentName
      description: The name of the incident.
      type: String
    - contextPath: Microsoft365Defender.Incident.createdTime
      description: The date and time (in UTC) the incident was created.
      type: Date
    - contextPath: Microsoft365Defender.Incident.lastUpdateTime
      description: The date and time (in UTC) the incident was last updated.
      type: Date
    - contextPath: Microsoft365Defender.Incident.assignedTo
      description: Owner of the incident.
      type: String
    - contextPath: Microsoft365Defender.Incident.classification
      description: 'Specification of the incident. Possible values are: Unknown, FalsePositive, and TruePositive.'
      type: String
    - contextPath: Microsoft365Defender.Incident.determination
      description: 'The determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.'
      type: String
    - contextPath: Microsoft365Defender.Incident.severity
      description: 'Severity of the incident. Possible values are: UnSpecified, Informational, Low, Medium, and High.'
      type: String
    - contextPath: Microsoft365Defender.Incident.status
      description: 'The current status of the incident. Possible values are: Active, Resolved, and Redirected.'
      type: String
    - contextPath: Microsoft365Defender.Incident.alerts
      description: List of alerts relevant for the incidents.
      type: Unknown
    - contextPath: Microsoft365Defender.Incident.tags
      description: List of custom tags associated with an incident, for example to flag a group of incidents with a common characteristic.
    - contextPath: Microsoft365Defender.Incident.comments
      description: List of comments created by secops when managing the incident, for example additional information about the classification selection.
  - arguments:
    - description: Advanced hunting query.
      name: query
      required: true
    - defaultValue: '30'
      description: The time limit in seconds for the http request to run.
      name: timeout
    - defaultValue: '50'
      description: Number of entries.  Enter -1 for unlimited query.
      name: limit
      required: true
    description: 'Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. Details on how to write queries: https://docs.microsoft.com/en-us/microsoft-365/security/defender/advanced-hunting-query-language?view=o365-worldwide.'
    name: microsoft-365-defender-advanced-hunting
    outputs:
    - contextPath: Microsoft365Defender.Hunt.query
      description: The query used, also acted as a key.
      type: String
    - contextPath: Microsoft365Defender.Hunt.results
      description: The results of the query.
      type: Unknown
  - arguments:
    - description: Incident's ID.
      name: id
      required: true
    - defaultValue: '30'
      description: The time limit in seconds for the http request to run.
      name: timeout
    description: Gets the incident with the given ID.
    name: microsoft-365-defender-incident-get
    outputs:
    - contextPath: Microsoft365Defender.Incident.incidentId
      description: Incident's ID.
      type: number
    - contextPath: Microsoft365Defender.Incident.redirectIncidentId
      description: Only populated in case an incident is grouped together with another incident, as part of the incident processing logic.
    - contextPath: Microsoft365Defender.Incident.incidentName
      description: The name of the incident.
      type: string
    - contextPath: Microsoft365Defender.Incident.createdTime
      description: The date and time (in UTC) the incident was created.
      type: date
    - contextPath: Microsoft365Defender.Incident.tags
      description: List of custom tags associated with an incident, for example to flag a group of incidents with a common characteristic.
    - contextPath: Microsoft365Defender.Incident.lastUpdateTime
      description: The date and time (in UTC) the incident was last updated.
      type: date
    - contextPath: Microsoft365Defender.Incident.assignedTo
      description: 'Owner of the incident.'
      type: string
    - contextPath: Microsoft365Defender.Incident.classification
      description: 'Specification of the incident. Possible values are: Unknown, FalsePositive, and TruePositive.'
      type: string
    - contextPath: Microsoft365Defender.Incident.determination
      description: 'The determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.'
      type: string
    - contextPath: Microsoft365Defender.Incident.severity
      description: 'Severity of the incident. Possible values are: UnSpecified, Informational, Low, Medium, and High.'
      type: string
    - contextPath: Microsoft365Defender.Incident.status
      description: 'The current status of the incident. Possible values are: Active, Resolved, and Redirected.'
      type: string
    - contextPath: Microsoft365Defender.Incident.alerts
      description: List of alerts relevant for the incidents.
    - contextPath: Microsoft365Defender.Incident.tags
      description: List of custom tags associated with an incident, for example to flag a group of incidents with a common characteristic.
    - contextPath: Microsoft365Defender.Incident.comments
      description: List of comments created by secops when managing the incident, for example additional information about the classification selection.
  - arguments:
    - default: false
      description: Date string representing the local time. The incident is only returned if it was modified after the last update time.
      isArray: false
      name: lastUpdate
      required: false
      secret: false
    deprecated: false
    description: Get the list of incidents that were modified since the last update time. This method is used for debugging purposes. The get-modified-remote-data command is used as part of the Mirroring feature that was introduced in Cortex XSOAR version 6.1.
    execution: false
    name: get-modified-remote-data
  - arguments:
    - default: false
      description: The remote incident ID.
      isArray: false
      name: id
      required: true
      secret: false
    - default: false
      defaultValue: '0'
      description: The UTC timestamp in seconds of the last update. The incident is only updated if it was modified after the last update time.
      isArray: false
      name: lastUpdate
      required: false
      secret: false
    deprecated: false
    description: Get remote data from a remote incident. This method does not update the current incident, and should be used for debugging purposes only.
    execution: false
    name: get-remote-data
  - arguments: []
    deprecated: false
    description: Returns the list of fields to map in outgoing mirroring. This command is only used for debugging purposes.
    execution: false
    name: get-mapping-fields
  - arguments: []
    deprecated: false
    description: Updates the remote incident with local incident changes. This method is only used for debugging purposes and will not update the current incident.
    execution: false
    name: update-remote-system
  dockerimage: demisto/crypto:1.0.0.10120494
  isfetch: true
  ismappable: true
  isremotesyncin: true
  isremotesyncout: true
  script: ''
  subtype: python3
  type: python
fromversion: 5.5.0
tests:
- No tests
defaultmapperin: Microsoft 365 Defender - Incoming Mapper
defaultmapperout: Microsoft 365 Defender - Outgoing Mapper