diff --git a/docs/threatmanager/3.1/install/appsettings.md b/docs/threatmanager/3.1/install/appsettings.md new file mode 100644 index 0000000000..a2a0bc5e9b --- /dev/null +++ b/docs/threatmanager/3.1/install/appsettings.md @@ -0,0 +1,72 @@ +--- +title: "Modify Service Configuration Settings" +description: "Modify Service Configuration Settings" +sidebar_position: 45 +--- + +# Modify Service Configuration Settings + +Threat Manager services are configured through JSON configuration files. Each service reads its +settings at startup from `appsettings.json` in the service's installation directory. + +## Configuration Files + +Each service ships with an `appsettings.default.json` file that contains the default settings used +when no override is present. Every upgrade replaces this file, so don't edit it +directly. Use it as a reference to see what settings are available for a given service. + +To override settings for a service, create an `appsettings.json` file in the same directory. The +installer doesn't create this file — you must create it yourself. Settings in `appsettings.json` +take precedence over those in `appsettings.default.json`. + +The following services support configuration overrides via `appsettings.json`: + +| Service | Configuration directory | +|---|---| +| Action Service | `C:\Program Files\STEALTHbits\StealthDEFEND\ActionService\` | +| Active Directory Service | `C:\Program Files\STEALTHbits\StealthDEFEND\ActiveDirectoryService\` | +| Azure Service | `C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\` | +| Email Service | `C:\Program Files\STEALTHbits\StealthDEFEND\EmailService\` | +| Event Message Service | `C:\Program Files\STEALTHbits\StealthDEFEND\EventMessageService\` | +| Integration Service | `C:\Program Files\STEALTHbits\StealthDEFEND\IntegrationService\` | +| Job Service | `C:\Program Files\STEALTHbits\StealthDEFEND\JobService\` | +| License Service | `C:\Program Files\STEALTHbits\StealthDEFEND\LicenseService\` | +| SIEM Service | `C:\Program Files\STEALTHbits\StealthDEFEND\SiemService\` | +| Web Service | `C:\Program Files\STEALTHbits\StealthDEFEND\RestServer\` | + +## Override Specific Settings + +Only include the settings you want to change in `appsettings.json`. Don't copy the entire contents +of `appsettings.default.json` into `appsettings.json`. Copying all defaults prevents Threat Manager +upgrades from applying updated default values for settings you haven't intentionally changed. + +For example, to override a single setting for the Azure Service, create +`C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json` with only the section +containing that setting: + +```json +{ + "Proxy": { + "Enabled": true, + "Address": "http://proxy.contoso.com:8080" + } +} +``` + +Settings not present in `appsettings.json` continue to use the values from +`appsettings.default.json`. + +## Apply Configuration Changes + +Changes to `appsettings.json` don't take effect until you restart the service. To restart a +service, open the Windows Services management console (`services.msc`), locate the service by name, +and select **Restart**. + +## Troubleshooting + +If a service fails to start after editing `appsettings.json`, the most common cause is a JSON +formatting error. Verify the file contains valid JSON before restarting the service. Common mistakes +include missing or extra commas, mismatched braces, and unquoted property names. + +You can validate the file using any JSON validator, or open it in an editor with JSON syntax +checking such as Visual Studio Code. diff --git a/docs/threatmanager/3.1/install/proxy.md b/docs/threatmanager/3.1/install/proxy.md new file mode 100644 index 0000000000..c06b549b82 --- /dev/null +++ b/docs/threatmanager/3.1/install/proxy.md @@ -0,0 +1,83 @@ +--- +title: "Configure a Proxy for Azure and Entra ID Connections" +description: "Configure a Proxy for Azure and Entra ID Connections" +sidebar_position: 50 +--- + +# Configure a Proxy for Azure and Entra ID Connections + +Netwrix Threat Manager's Azure Service connects to Azure and Microsoft Entra ID to sync data. If +your environment requires outbound connections to go through a proxy server, configure the proxy +settings in the Azure Service configuration file. + +## Configuration File + +The proxy is configured in the Azure Service `appsettings.json` file on the Threat Manager server: + +**C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json** + +:::warning +Before editing configuration files, review the [Modify Service Configuration Settings](/docs/threatmanager/3.1/install/appsettings.md) topic for important guidance on the correct approach. +::: + +## Proxy Settings + +Add or update the `Proxy` section in `appsettings.json`: + +```json +{ + "Proxy": { + "Enabled": true, + "Address": "http://proxy.contoso.com:8080", + "BypassProxyOnLocal": null, + "UseDefaultCredentials": null, + "PreAuthenticate": null, + "CredentialProfileId": null + } +} +``` + +The following table describes each setting. + +| Property | Config Key | Type | Description | +|---|---|---|---| +| Enabled | `Proxy:Enabled` | bool | Whether the proxy is active. If `false`, the service ignores all other settings and connects directly. | +| Address | `Proxy:Address` | string | The proxy server URL, e.g. `http://proxy.contoso.com:8080`. Required when `Enabled` is `true`. | +| BypassProxyOnLocal | `Proxy:BypassProxyOnLocal` | bool | Whether to skip the proxy for local and intranet addresses. | +| UseDefaultCredentials | `Proxy:UseDefaultCredentials` | bool | Whether to authenticate to the proxy using the Windows identity of the service account. Suitable for NTLM/Kerberos-authenticated proxies. | +| PreAuthenticate | `Proxy:PreAuthenticate` | bool | Whether to send proxy credentials on the first request rather than waiting for a 407 challenge. Can improve performance on authenticated proxies. | +| CredentialProfileId | `Proxy:CredentialProfileId` | long | ID of a credential profile to use for proxy authentication. Used instead of `UseDefaultCredentials` when the proxy requires an explicit username and password. See the [Credential Profile Page](/docs/threatmanager/3.1/administration/configuration/integrations/credentialprofile.md) topic for information on creating credential profiles. | + +## Configure the Proxy + +**Step 1 –** Open the Azure Service configuration file on the Threat Manager server: + +**C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json** + +**Step 2 –** Locate the `Proxy` section. If it doesn't exist, add it as shown in the preceding example. + +**Step 3 –** Set `Enabled` to `true`. + +**Step 4 –** Set `Address` to the URL of your proxy server, e.g. `http://proxy.contoso.com:8080`. + +**Step 5 –** Configure authentication for the proxy using one of the following options: + +- **Windows identity (NTLM/Kerberos)** — Set `UseDefaultCredentials` to `true`. The service + authenticates to the proxy using the Windows identity of the account running the Azure Service. +- **Explicit credentials** — Set `CredentialProfileId` to the ID of a credential profile stored in + Threat Manager. See the + [Credential Profile Page](/docs/threatmanager/3.1/administration/configuration/integrations/credentialprofile.md) + topic for information on creating credential profiles. +- **No authentication** — Leave both `UseDefaultCredentials` and `CredentialProfileId` as `null` + for unauthenticated proxies. + +**Step 6 –** Optionally, set `BypassProxyOnLocal` to `true` to bypass the proxy for local and +intranet addresses. + +**Step 7 –** Optionally, set `PreAuthenticate` to `true` to send proxy credentials on the first +request and avoid the 407 challenge round-trip. Use this only if your proxy supports +pre-authentication. + +**Step 8 –** Save the configuration file. + +**Step 9 –** Restart the Netwrix Threat Manager Azure Service for the changes to take effect. diff --git a/docs/threatmanager/3.1/install/secure.md b/docs/threatmanager/3.1/install/secure.md index ff9340d99b..46560b3d0f 100644 --- a/docs/threatmanager/3.1/install/secure.md +++ b/docs/threatmanager/3.1/install/secure.md @@ -6,6 +6,10 @@ sidebar_position: 40 # Secure the Threat Manager Console +:::warning +Before editing configuration files, review the [Modify Service Configuration Settings](/docs/threatmanager/3.1/install/appsettings.md) topic for important guidance on the correct approach. +::: + To support HTTPS, do the following: - Import an SSL certificate to the server diff --git a/docs/threatmanager/3.2/install/appsettings.md b/docs/threatmanager/3.2/install/appsettings.md new file mode 100644 index 0000000000..a2a0bc5e9b --- /dev/null +++ b/docs/threatmanager/3.2/install/appsettings.md @@ -0,0 +1,72 @@ +--- +title: "Modify Service Configuration Settings" +description: "Modify Service Configuration Settings" +sidebar_position: 45 +--- + +# Modify Service Configuration Settings + +Threat Manager services are configured through JSON configuration files. Each service reads its +settings at startup from `appsettings.json` in the service's installation directory. + +## Configuration Files + +Each service ships with an `appsettings.default.json` file that contains the default settings used +when no override is present. Every upgrade replaces this file, so don't edit it +directly. Use it as a reference to see what settings are available for a given service. + +To override settings for a service, create an `appsettings.json` file in the same directory. The +installer doesn't create this file — you must create it yourself. Settings in `appsettings.json` +take precedence over those in `appsettings.default.json`. + +The following services support configuration overrides via `appsettings.json`: + +| Service | Configuration directory | +|---|---| +| Action Service | `C:\Program Files\STEALTHbits\StealthDEFEND\ActionService\` | +| Active Directory Service | `C:\Program Files\STEALTHbits\StealthDEFEND\ActiveDirectoryService\` | +| Azure Service | `C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\` | +| Email Service | `C:\Program Files\STEALTHbits\StealthDEFEND\EmailService\` | +| Event Message Service | `C:\Program Files\STEALTHbits\StealthDEFEND\EventMessageService\` | +| Integration Service | `C:\Program Files\STEALTHbits\StealthDEFEND\IntegrationService\` | +| Job Service | `C:\Program Files\STEALTHbits\StealthDEFEND\JobService\` | +| License Service | `C:\Program Files\STEALTHbits\StealthDEFEND\LicenseService\` | +| SIEM Service | `C:\Program Files\STEALTHbits\StealthDEFEND\SiemService\` | +| Web Service | `C:\Program Files\STEALTHbits\StealthDEFEND\RestServer\` | + +## Override Specific Settings + +Only include the settings you want to change in `appsettings.json`. Don't copy the entire contents +of `appsettings.default.json` into `appsettings.json`. Copying all defaults prevents Threat Manager +upgrades from applying updated default values for settings you haven't intentionally changed. + +For example, to override a single setting for the Azure Service, create +`C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json` with only the section +containing that setting: + +```json +{ + "Proxy": { + "Enabled": true, + "Address": "http://proxy.contoso.com:8080" + } +} +``` + +Settings not present in `appsettings.json` continue to use the values from +`appsettings.default.json`. + +## Apply Configuration Changes + +Changes to `appsettings.json` don't take effect until you restart the service. To restart a +service, open the Windows Services management console (`services.msc`), locate the service by name, +and select **Restart**. + +## Troubleshooting + +If a service fails to start after editing `appsettings.json`, the most common cause is a JSON +formatting error. Verify the file contains valid JSON before restarting the service. Common mistakes +include missing or extra commas, mismatched braces, and unquoted property names. + +You can validate the file using any JSON validator, or open it in an editor with JSON syntax +checking such as Visual Studio Code. diff --git a/docs/threatmanager/3.2/install/proxy.md b/docs/threatmanager/3.2/install/proxy.md new file mode 100644 index 0000000000..1ff9c8c5e7 --- /dev/null +++ b/docs/threatmanager/3.2/install/proxy.md @@ -0,0 +1,83 @@ +--- +title: "Configure a Proxy for Azure and Entra ID Connections" +description: "Configure a Proxy for Azure and Entra ID Connections" +sidebar_position: 50 +--- + +# Configure a Proxy for Azure and Entra ID Connections + +Netwrix Threat Manager's Azure Service connects to Azure and Microsoft Entra ID to sync data. If +your environment requires outbound connections to go through a proxy server, configure the proxy +settings in the Azure Service configuration file. + +## Configuration File + +The proxy is configured in the Azure Service `appsettings.json` file on the Threat Manager server: + +**C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json** + +:::warning +Before editing configuration files, review the [Modify Service Configuration Settings](/docs/threatmanager/3.2/install/appsettings.md) topic for important guidance on the correct approach. +::: + +## Proxy Settings + +Add or update the `Proxy` section in `appsettings.json`: + +```json +{ + "Proxy": { + "Enabled": true, + "Address": "http://proxy.contoso.com:8080", + "BypassProxyOnLocal": null, + "UseDefaultCredentials": null, + "PreAuthenticate": null, + "CredentialProfileId": null + } +} +``` + +The following table describes each setting. + +| Property | Config Key | Type | Description | +|---|---|---|---| +| Enabled | `Proxy:Enabled` | bool | Whether the proxy is active. If `false`, the service ignores all other settings and connects directly. | +| Address | `Proxy:Address` | string | The proxy server URL, e.g. `http://proxy.contoso.com:8080`. Required when `Enabled` is `true`. | +| BypassProxyOnLocal | `Proxy:BypassProxyOnLocal` | bool | Whether to skip the proxy for local and intranet addresses. | +| UseDefaultCredentials | `Proxy:UseDefaultCredentials` | bool | Whether to authenticate to the proxy using the Windows identity of the service account. Suitable for NTLM/Kerberos-authenticated proxies. | +| PreAuthenticate | `Proxy:PreAuthenticate` | bool | Whether to send proxy credentials on the first request rather than waiting for a 407 challenge. Can improve performance on authenticated proxies. | +| CredentialProfileId | `Proxy:CredentialProfileId` | long | ID of a credential profile to use for proxy authentication. Used instead of `UseDefaultCredentials` when the proxy requires an explicit username and password. See the [Credential Profile Page](/docs/threatmanager/3.2/administration/configuration/integrations/credentialprofile.md) topic for information on creating credential profiles. | + +## Configure the Proxy + +**Step 1 –** Open the Azure Service configuration file on the Threat Manager server: + +**C:\Program Files\STEALTHbits\StealthDEFEND\AzureService\appsettings.json** + +**Step 2 –** Locate the `Proxy` section. If it doesn't exist, add it as shown in the preceding example. + +**Step 3 –** Set `Enabled` to `true`. + +**Step 4 –** Set `Address` to the URL of your proxy server, e.g. `http://proxy.contoso.com:8080`. + +**Step 5 –** Configure authentication for the proxy using one of the following options: + +- **Windows identity (NTLM/Kerberos)** — Set `UseDefaultCredentials` to `true`. The service + authenticates to the proxy using the Windows identity of the account running the Azure Service. +- **Explicit credentials** — Set `CredentialProfileId` to the ID of a credential profile stored in + Threat Manager. See the + [Credential Profile Page](/docs/threatmanager/3.2/administration/configuration/integrations/credentialprofile.md) + topic for information on creating credential profiles. +- **No authentication** — Leave both `UseDefaultCredentials` and `CredentialProfileId` as `null` + for unauthenticated proxies. + +**Step 6 –** Optionally, set `BypassProxyOnLocal` to `true` to bypass the proxy for local and +intranet addresses. + +**Step 7 –** Optionally, set `PreAuthenticate` to `true` to send proxy credentials on the first +request and avoid the 407 challenge round-trip. Use this only if your proxy supports +pre-authentication. + +**Step 8 –** Save the configuration file. + +**Step 9 –** Restart the Netwrix Threat Manager Azure Service for the changes to take effect. diff --git a/docs/threatmanager/3.2/install/secure.md b/docs/threatmanager/3.2/install/secure.md index 3eecfaa466..7b6a772f28 100644 --- a/docs/threatmanager/3.2/install/secure.md +++ b/docs/threatmanager/3.2/install/secure.md @@ -6,6 +6,10 @@ sidebar_position: 40 # Secure the Threat Manager Console +:::warning +Before editing configuration files, review the [Modify Service Configuration Settings](/docs/threatmanager/3.2/install/appsettings.md) topic for important guidance on the correct approach. +::: + To support HTTPS, do the following: - Import an SSL certificate to the server @@ -28,7 +32,7 @@ editing the configuration files discussed in this topic. ::: -**Step 2 –**   Copy the thumbprint of the certificate as you will need to use it while editing +**Step 2 –**   Copy the thumbprint of the certificate, as you need it while editing the configuration files. ## Web Service Configuration File @@ -143,8 +147,8 @@ Found cert with subject % and thumbprint 12345ABCDEF54AED1DB59C349CA4D514628DB4D ## Re-register the Action Service -While not always necessary it is a good practice to also re-register the Action Service whenever -changing the certificate in use. +Re-registering the Action Service whenever you change the certificate in use is good practice, +though not always necessary. **Step 1 –** Open an administrative command prompt.