Exchange (nxlog-xchg)

This add-on is available for purchase. For more information, please contact us.

Microsoft Exchange provides two types of audit logs: administrator audit logging and mailbox audit logging. The nxlog-xchg add-on can be used to retrieve both administrator audit logs as well as mailbox audit logs. These logs include actions taken by users or administrators who make changes in the organization, mailbox actions, and mailbox logins including access by users other than the mailbox owner. For more information, see the Administrator audit logging in Exchange 2016 and Mailbox audit logging in Exchange 2016 articles in the Microsoft TechNet documentation.

The nxlog-xchg add-on periodically queries an Exchange server via Windows Remote Management (WinRM) and writes the result to standard output in JSON format for further processing by NXLog. The add-on is executed by NXLog via the im_exec module, and may be configured on either the Exchange server itself or on another system.

The required steps may vary from those provided below based on the organization and domain topology along with the configuration used.

Requirements

Server side requirements include:

Microsoft Exchange Server 2010 SP1+, 2013, 2016 or 2019;
Windows Remote Management (WinRM) with HTTPS listener;
an Active Directory user that can log in through WinRM to the Windows server running Exchange; and
an Active Directory user with the Audit Logs role.

Client side requirements are:

Windows 2008 or later and
a user with permission to install software.

The server and client can reside on the same machine.

Exchange Server setup

Create the Active Directory users specified in Requirements above. See Exchange Server permissions and View-Only Audit Logs role on Microsoft Docs.

WinRM remote login is only allowed for users in the local Administrator group, or Domain Administrator group. The user created for login via WinRM must be a member of one of these groups.

Windows Remote Management (WinRM) will accept the connections from nxlog-xchg. By default, WinRM will listen on TCP port 5985 for HTTP (insecure) requests. WinRM should be configured to listen for secure connections on TCP/5986. Check if it is configured:
```
PS> Get-ChildItem -Path WSMAN:\Localhost\listener | Where-Object { (Get-Item "$($_.PSPath)\Transport").Value -eq "HTTPS" -and (Get-Item "$($_.PSPath)\Address").Value -eq "*" }
```
If the command above does not return any results, then on the Exchange server, from an elevated command line (cmd), run the following command to enable WinRM HTTPS transport.
```
> winrm quickconfig -transport:https
```
If there is an error message about the system not having an appropriate (server authentication) certificate, issue one for the server or create a self-signed one. To create a self signed certificate, open a Powershell window and run these commands.
```
PS> New-SelfSignedCertificate -CertStoreLocation Cert:\LocalMachine\My -DnsName "hostname-of-my-server"
```

After the certificate has been prepared, open a PowerShell window and run:

PS> Get-ChildItem -Path cert:\LocalMachine\My

Choose the certificate and run:

PS> $cert=Get-ChildItem -Path cert:\LocalMachine\My\YOURCERTIFICATE_THUMBPRINT
PS> New-Item -Path WSMAN:\Localhost\listener -Transport HTTPS -Address * -CertificateThumbPrint $cert.ThumbPrint -Force
PS> Enable-PSRemoting -SkipNetworkProfileCheck -Force

After this it should not be necessary to run the quick config for WinRM and the HTTP listener can be removed (assuming it is no longer needed otherwise).
```
PS> Get-ChildItem WSMan:\Localhost\listener | Where -Property Keys -eq "Transport=HTTP" | Remove-Item -Recurse
```
The "Audit Logs" role most be added to the Active Directory user to access the "Search-AdminAuditLog" and "Search-MailboxAuditLog" Exchange cmdlets.
```
PS> New-ManagementRoleAssignment -Name nxlog-xchg-mr -Role "Audit Logs" -User "Active Directory User Name"
```
Administrator audit logging is enabled by default. Verify by running et-AdminAuditLogConfig | FL AdminAuditLogEnabled. See Manage administrator audit logging for more details.
Mailbox audit logging can be enabled on a per user basis, using the Exchange Management shell. nxlog-xchg respects the options configured in the Exchange server. To enable mailbox audit logging for a single user, open an Exchange Management Shell and run:
```
PS> Set-Mailbox -Identity "Ben Smith" -AuditEnabled $true
```
To enable audit logging for all user mailboxes in the organization, run:
```
PS> Get-Mailbox -ResultSize Unlimited -Filter {RecipientTypeDetails -eq "UserMailbox"} | Set-Mailbox -AuditEnabled $true
```
For more information about mailbox audit logging (including more logging options), see Enable or disable mailbox audit logging for a mailbox on Microsoft Docs.

nxlog-xchg (client) setup

The nxlog-xchg utility can be configured either by arguments on the command line or by a configuration file. The command line arguments use the same names as in the configuration file. Three arguments are offered by nxlog-xchg in addition to those in the configuration file:

--debug: set debug verbosity, 0-3 (0 = none/default, 3 = verbose)
-c, --config: set the configuration file path
--version: show the version of the nxlog-xchg utility

Sample command line arguments

nxlog-xchg.exe --Url https://exchange01.corp.local:5986/wsman --User winrmuser
               --Password winrmuser_password --HostURI http://exchange01.corp.local/powershell
               --ExchangeUser exuser@local --ExchangePassword exuser_password

Sample nxlog-xchg configuration

[Nxlog]
SavePos=TRUE
PollInterval=30

[WinRM]
Url=https://host.yourdomain.com:5986/wsman
User=winrmuser@yourdomain.com
Password=winrmuser_password
CheckCertificate=TRUE

[Exchange]
HostFQDN=exchange.yourdomain.com
ExchangeUser=ex_user@yourdomain.com
ExchangePassword=exuser_password
ExchangeAuth=KERBEROS

[Options]
SearchAdminLog=TRUE
SearchMailboxLog=TRUE
ResultSize=5000

The following directives are available for configuring nxlog-xchg.

NXLog section:

SavePos: This optional boolean directive specifies whether the last record number should be saved when nxlog-xchg exits. The default is TRUE.
PollInterval: This optional directive specifies the time (in seconds) between polls. Valid values are 3-3600; the default is 30 seconds.

WinRM section:

Url: This specifies the URL of the WinRM listener (for example, https://exchangeserver.mydomain.com:5986/wsman).
User: This specifies the user that has permission to log on to the Exchange Server system.
Password: This should be set to the password of the user defined in User above.
Auth: The authentication method to use when establishing a WinRM connection (KERBEROS or NTLM). NTLM is the default authentication method used if this is not set.
CheckCertificate: This optional boolean directive specifies whether the server certificate should be verified. The default is TRUE (the certificate is validated).

Exchange section:

HostURI: This sets the full URI to use for the remote PowerShell connection (for example, http://name.domain.tld/PowerShell/).
ExchangeUser: This specifies the user that has permission to query the Exchange Server.
ExchangePassword: This should be set to the password of the user defined in ExchangeUser above.
ExchangeAuth: The authentication method to use when establishing a connection to PowerShell on the Exchange server (KERBEROS or NTLM). Kerberos is the default is authentication method used if this is not set.

Options section:

QueryAdminLog: This optional boolean directive specifies whether the administrator audit log should be queried. The default is TRUE (the administrator audit log is queried).
QueryMailboxLog: This optional boolean directive specifies whether the mailbox audit log should be queried. The default is TRUE (the mailbox audit log is queried).
ResultSize: This optional directive specifies the maximum number of log entries to retrieve. The default is 5000 entries.

Using nxlog-xchg in an NXLog configuration

Including nxlog-xchg in a working NXLog installation is quite simple: just configure an Input block using the im_exec module and specify nxlog-xchg.exe as the external program. With this Input block defined, the received logs can be routed as necessary.

Example 1. Writing Exchange logs to a file

This configuration uses the im_exec module to receive logs from nxlog-xchg, and writes them to file locally with om_file.

nxlog.conf

<Input in>
    Module  im_exec
    Command 'C:\Program Files (x86)\nxlog-exchange\nxlog-xchg.exe'
    Arg     -c
    Arg     C:\Program Files (x86)\nxlog-xchg\nxlog-xchg.cfg
</Input>

<Output out>
    Module  om_file
    File    "C:\\logs\\exchange_audit_log.txt"
</Output>

<Route ex>
    Path    in => out
</Route>

Performance

It is important to configure nxlog-xchg so the server is not polled too frequently (running nxlog-xchg too often) or infrequently (requiring the collection of a very large result set). If PollInterval is properly adjusted, there should not be any performance issue.

Troubleshooting

Nxlog-xchg does not launch from NXLog

Make sure the quotations in the im_exec block are correct. This can be tested by placing a simple batch script (containing echo "Hello world", for example) into the same directory as nxlog-xchg.exe and calling that batch file from im_exec.

No events received

If no events are being received, make sure the relevant logging is enabled in Exchange. For admin audit logging run:

PS> Get-AdminAuditLogConfig | fl _log_