Windows.Utils.DefenderExclusion

Adds a Microsoft Defender real-time scanning process exclusion for Velociraptor.

Generally you should not need to use this unless Defender is interfering with your collections. This may happen if the collection uses tools or associated files that trigger Microsoft Defender detections.

Some initial info is also gathered to aid with troubleshooting.

The exclusion is checked every minute by default and reapplied if necessary.

As a side-effect the exclusion also makes some collection operations faster, particularly those that are filesystem-intensive and that use the OS ‘file’ accessor.

Notes

  • Exclusions do apply to some Microsoft Defender for Endpoint capabilities, such as attack surface reduction rules.
  • Exclusions do apply to potentially unwanted apps (PUA) detections as well.
  • Exclusions do apply to some ASR rule exclusions. See Attack surface reduction rules reference - Microsoft Defender Antivirus exclusions and ASR rules .
  • Excluded files can still trigger Endpoint Detection and Response (EDR) alerts and other detections. To exclude files broadly, add them to the Microsoft Defender for Endpoint custom indicators.
  • See References below to learn more about Defender exclusions in general.

A more compact version of this artifact is listed below which can be included in the client configuration, as shown, and run with the Client.additional_event_artifacts setting. This will run the artifact as an event artifact as long as the client is running, starting even before enrollment. This may be useful if there are specific clients where Defender is causing problems.

autoexec:
  artifact_definitions:
  - name: Windows.Utils.DefenderExclusionCompact
    precondition: SELECT OS From info() where OS = "windows"
    parameters:
      - name: CmdApply
        default: "powershell.exe -ExecutionPolicy Unrestricted -encodedCommand"
    sources:
      - query: |
          LET schedule = SELECT * FROM clock(period=60)
          LET HostInfo <= SELECT * FROM info()
          SELECT {
                   SELECT *
                   FROM execve(
                     argv=[commandline_split(command=CmdApply) + base64encode(
                       string=utf16_encode(
                         string=format(
                           format='Add-MpPreference -ExclusionProcess "%v"',
                           args=HostInfo[0].Exe)))])
                   WHERE log(
                     message="Applied process exclusion: %v",
                     args=HostInfo[0].Exe,
                     level="INFO")
                 }
          FROM schedule
 Client:
   additional_event_artifacts:
   - Windows.Utils.DefenderExclusionCompact

name: Windows.Utils.DefenderExclusion
description: |
   Adds a Microsoft Defender real-time scanning process exclusion for Velociraptor.
   
   Generally you should not need to use this unless Defender is interfering
   with your collections.
   This may happen if the collection uses tools or associated files that
   trigger Microsoft Defender detections.
   
   Some initial info is also gathered to aid with troubleshooting.
   
   The exclusion is checked every minute by default and reapplied if necessary.
   
   As a side-effect the exclusion also makes some collection operations faster,
   particularly those that are filesystem-intensive and that use the OS 'file'
   accessor.
   
   ### Notes
   
   - Exclusions *do* apply to some Microsoft Defender for Endpoint capabilities,
   such as attack surface reduction rules.
   - Exclusions *do* apply to potentially unwanted apps (PUA) detections as well.
   - Exclusions *do* apply to some ASR rule exclusions. See [Attack surface
   reduction rules reference - Microsoft Defender Antivirus exclusions and ASR
   rules](https://learn.microsoft.com/en-us/defender-endpoint/attack-surface-reduction-rules-reference#microsoft-defender-antivirus-exclusions-and-asr-rules).
   - Excluded files can still trigger Endpoint Detection and Response (EDR)
   alerts and other detections. To exclude files broadly, add them to the
   Microsoft Defender for Endpoint custom indicators.
   - See References below to learn more about Defender exclusions in general.
   
   A more compact version of this artifact is listed below which can be included
   in the client configuration, as shown, and run with the
   `Client.additional_event_artifacts` setting. This will run the artifact
   as an event artifact as long as the client is running, starting even before
   enrollment. This may be useful if there are specific clients where Defender
   is causing problems.
   
   ```yaml
   autoexec:
     artifact_definitions:
     - name: Windows.Utils.DefenderExclusionCompact
       precondition: SELECT OS From info() where OS = "windows"
       parameters:
         - name: CmdApply
           default: "powershell.exe -ExecutionPolicy Unrestricted -encodedCommand"
       sources:
         - query: |
             LET schedule = SELECT * FROM clock(period=60)
             LET HostInfo <= SELECT * FROM info()
             SELECT {
                      SELECT *
                      FROM execve(
                        argv=[commandline_split(command=CmdApply) + base64encode(
                          string=utf16_encode(
                            string=format(
                              format='Add-MpPreference -ExclusionProcess "%v"',
                              args=HostInfo[0].Exe)))])
                      WHERE log(
                        message="Applied process exclusion: %v",
                        args=HostInfo[0].Exe,
                        level="INFO")
                    }
             FROM schedule
    Client:
      additional_event_artifacts:
      - Windows.Utils.DefenderExclusionCompact
    ```

reference:
  - https://learn.microsoft.com/en-us/defender-endpoint/defender-endpoint-antivirus-exclusions
  - https://learn.microsoft.com/en-us/previous-versions/windows/desktop/defender/add-msft-mppreference
  - https://learn.microsoft.com/en-us/defender-endpoint/configure-local-policy-overrides-microsoft-defender-antivirus
  - https://cloudbrothers.info/en/guide-to-defender-exclusions/

type: CLIENT_EVENT

required_permissions:
  - EXECVE

precondition: SELECT OS From info() where OS = "windows"

parameters:

   - name: CmdApply
     default: "powershell.exe -ExecutionPolicy Unrestricted -encodedCommand"

sources:

  - name: InitialExclusions
    query: |
      LET MpPreference <= SELECT *
                          FROM wmi(query='SELECT * FROM MSFT_MpPreference',
                                   namespace='root/microsoft/windows/defender')
      
      SELECT * FROM column_filter(query=MpPreference, include="Exclusion")

  - name: ApplyExclusion
    query: |
      -- Check on a schedule that the exclusion is still being applied
      LET schedule = SELECT * FROM clock(period=60)

      -- Get the Velociraptor exe location
      LET HostInfo <= SELECT * FROM info()

      -- Checking is not really necessary because adding exclusions is an
      -- idempotent operation but it's useful to see it in the log
      LET ExclusionCheck(VelociExe) =
                SELECT ExclusionProcess
                FROM wmi(query='SELECT * FROM MSFT_MpPreference', namespace='root/microsoft/windows/defender')
                WHERE VelociExe IN ExclusionProcess
                AND log(message="WMI check: %v is excluded", args=ExclusionProcess, dedup=-1, level="INFO")
      
      LET ExclusionApply(VelociExe) =
                SELECT *
                FROM execve(argv=[commandline_split(command=CmdApply) + base64encode(string=utf16_encode(
                        string=format(format='Add-MpPreference -ExclusionProcess "%v"',args=VelociExe)))])
                WHERE log(message="Applied process exclusion: %v", args=VelociExe, dedup=-1, level="INFO")

      SELECT if(condition= NOT ExclusionCheck(VelociExe=HostInfo[0].Exe),
             then={ SELECT ExclusionApply(VelociExe=HostInfo[0].Exe) FROM scope() })
      FROM schedule