> ## Documentation Index
> Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SharpHound Enterprise Local Configuration

<img noZoom src="https://mintcdn.com/specterops/tTIczgde9H07oLXf/assets/enterprise-edition-pill-tag.svg?fit=max&auto=format&n=tTIczgde9H07oLXf&q=85&s=b682a26b342bde12302ec829e265bdb6" alt="Applies to BloodHound Enterprise only" width="225" height="45" data-path="assets/enterprise-edition-pill-tag.svg" />

SharpHound Enterprise stores its local configuration in two files:

| **File**        | **Purpose**                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `settings.json` | Defines how the service behaves, including settings for connecting to the BloodHound Enterprise tenant, Active Directory, and logs. |
| `auth.json`     | Defines the credentials the service uses to authenticate to the BloodHound Enterprise API.                                          |

<Note>
  When using Integrated Windows Authentication (IWA), the `auth.json` file is not used; all authentication information is provided in `settings.json` instead.
</Note>

You can find the file paths for each configuration file and logs in the table below. `%AppData%` is the directory of the service account: `C:\\Users\\SERVICE_ACCOUNT$\\AppData\\Roaming`.

| **SharpHound File** | **Default Path (v2.5.8+)  <br />**                    | **Default Path (\<= v2.5.8)  <br />**                 |
| ------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| Configuration File  | `%AppData%\\BloodHoundEnterprise\\settings.json`      | `C:\\Program Files (x86)\\SHService\\settings.json`   |
| Authentication File | `%AppData%\\BloodHoundEnterprise\\auth.json`          | `C:\\Program Files (x86)\\SHService\\auth.json`       |
| Active Logs         | `%AppData%\\BloodHoundEnterprise\\*.log`              | `%AppData%\\BloodHoundEnterprise\\*.log`              |
| Archived Logs       | `%AppData%\\BloodHoundEnterprise\\log_archive\\*.zip` | `%AppData%\\BloodHoundEnterprise\\log_archive\\*.zip` |

## Configure SharpHound Settings

To modify any settings in your SharpHound configuration, you must stop the SharpHound service. The process to modify SharpHound's configuration files is as follows:

1. Stop the SharpHound Enterprise service: "SharpHound Delegator"

2. Edit and save one of the configuration files as an Administrator:

   * `settings.json`
   * `auth.json`

3. Start the SharpHound Enterprise service: "SharpHound Delegator"

## settings.json

The `settings.json` file is a plaintext JSON file that defines information about how the service behaves, such as settings for connecting to the BloodHound Enterprise tenant, connecting to Active Directory, and writing logs.

```json title="settings.json" icon="file-brackets-curly" theme={null}
{
  "RestEndpoint": "CODENAME.bloodhoundenterprise.io",
  "RestPort": 443,
  "SSL": true,
  "CurrentJob": null,
  "LogLevel": "Information",
  "EnumerationLogLevel": "Information",
  "TempDirectory": "C:\\Users\\gmsa_SHS$\\AppData\\Roaming\\BloodHoundEnterprise",
  "Proxy": null,
  "ComputerPasswordResetWindow": 60,
  "ForceLDAPKerberosAuth": true,
  "PortCheckTimeout": 10000,
  "LDAPSSLPort": 636,
  "LDAPPort": 389,
  "ForceLDAPSSL": false,
  "NumWorkers": 50,
  "PartitionLDAPQueries": true,
  "Version": "2.5.9.0"
}
```

### Integrated Windows Authentication (IWA)

If using IWA instead of API tokens, you must include IWA-specific configuration fields in your `settings.json` file. These fields are required to enable SharpHound to authenticate using the service account's Windows credentials via Active Directory Federation Services (ADFS).

```json title="settings.json" icon="file-brackets-curly" theme={null}
{
... (other settings) ...
  "ProviderWellKnown": "https://adfs.example.com/.well-known/openid-configuration",
  "ClientId": "12345678-1234-1234-1234-123456789012",
  "Resource": "https://your-tenant.bloodhound.com",
  "UseIntegratedWindowsAuthForADFS": true,
}
```

<Tip>
  When using this configuration, do not include an `auth.json` file. The authentication credentials will be handled through ADFS using the service account's Windows identity.
</Tip>

See the following reference to learn more about the supported fields in the `settings.json` file:

<ResponseField name="RestEndpoint" type="string">
  Your tenant domain, as provided by your account team. Enter the domain only and do not include URI information such as `https://`.

  **Default value:** `CODENAME.bloodhoundenterprise.io`

  **Example value:** `demo.bloodhoundenterprise.io`
</ResponseField>

<ResponseField name="RestPort" type="integer">
  TCP port on which the BloodHound Enterprise API runs.

  **Default value:** `443`

  **Example value:** `443`
</ResponseField>

<ResponseField name="SSL" type="boolean">
  Specifies whether SSL is enabled for the API connection.

  **Default value:** `True`

  **Example value:** `True`
</ResponseField>

<ResponseField name="Proxy" type="string | null">
  HTTP proxy URL, if your environment requires one.

  **Default value:** `null`

  **Example value:** `proxy.acme.com:8080`
</ResponseField>

<ResponseField name="CurrentJob" type="array | null">
  SharpHound uses this field to track the currently running task. When no task is running, the value is `null`.

  **Default value:** Do not modify this value.

  **Example value:** Do not modify this value.
</ResponseField>

<ResponseField name="LogLevel" type="string">
  Logging verbosity level for the service itself. These logs appear in `service.log` within the configured `TempDirectory` location.

  Supported values, from most to least verbose:

  * `Trace`
  * `Debug`
  * `Information`
  * `Warning`
  * `Error`
  * `Critical`
  * `None`

  **Default value:** `Information`

  **Example value:** `Trace`
</ResponseField>

<ResponseField name="EnumerationLogLevel" type="string">
  Logging verbosity level used during collection jobs.

  Supported values, from most to least verbose:

  * `Trace`
  * `Debug`
  * `Information`
  * `Warning`
  * `Error`
  * `Critical`
  * `None`

  **Default value:** `Information`

  **Example value:** `Trace`
</ResponseField>

<ResponseField name="TempDirectory" type="string | null">
  Directory in which SharpHound stores logs and temporary files. If this value is `null` when the service starts, SharpHound uses the `%APPDATA%\\BloodHoundEnterprise\\` directory for the service user.

  Logs are retained for 14 days. Escape backslashes for valid JSON formatting by using double backslashes.

  **Default value:** `null`

  **Example value:** `C:\\Users\\SERVICE_USER$\\AppData\\Roaming\\BloodHoundEnterprise\\`
</ResponseField>

<ResponseField name="Version" type="string">
  Current SharpHound Enterprise version.

  **Default value:** Do not modify this value.

  **Example value:** Do not modify this value.
</ResponseField>

<ResponseField name="ComputerPasswordResetWindow" type="integer">
  Excludes computer objects from local collections if they have not rotated their password with the domain within this many days. By default, Active Directory computers rotate their passwords every 30 days.

  Minimum value: `7`

  This Windows setting controls how often the computer [rotates its password](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/domain-member-maximum-machine-account-password-age). You can also [prevent password rotation](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/domain-member-disable-machine-account-password-changes) entirely through Windows policy.

  **Default value:** `60`

  **Example value:** `365`
</ResponseField>

<ResponseField name="PortCheckTimeout" type="integer">
  Time, in milliseconds, that SharpHound waits for a response on TCP port `445` before considering the system unavailable.

  Minimum value: `200`

  Requires SharpHound Enterprise `v2.2.1+`.

  **Default value:** `10000`

  **Example value:** `15000`
</ResponseField>

<ResponseField name="NumWorkers" type="integer">
  Number of concurrent threads that perform privileged collection.

  Minimum value: `10`

  Maximum value: `100`

  Requires SharpHound Enterprise `v2.2.1+`.

  **Default value:** `50`

  **Example value:** `50`
</ResponseField>

<ResponseField name="PartitionLDAPQueries" type="boolean">
  Specifies whether SharpHound splits LDAP queries into multiple parts. Use this setting when you query very large domains.

  **Default value:** `True`

  **Example value:** `True`
</ResponseField>

<ResponseField name="ForceLDAPKerberosAuth" type="boolean">
  Enforces Kerberos authentication when SharpHound queries LDAP servers. Disabling this setting may be required to collect across an External trust type. For more information, see [Cross-Trust Collection](/collect-data/enterprise-collection/cross-trust).

  When set to `False`, SharpHound auto-negotiates authentication to domain controllers and prefers Kerberos when it is available.

  **Default value:** `False`

  **Example value:** `True`
</ResponseField>

<ResponseField name="LDAPSSLPort" type="integer">
  TCP port used for LDAP over SSL collection.

  Requires SharpHound Enterprise `v2.2.1+`.

  **Default value:** `636`

  **Example value:** `636`
</ResponseField>

<ResponseField name="LDAPPort" type="integer">
  TCP port used for LDAP collection.

  **Default value:** `389`

  **Example value:** `389`
</ResponseField>

<ResponseField name="ForceLDAPSSL" type="boolean">
  Controls SharpHound's primary LDAP connection behavior.

  When set to `False`, SharpHound attempts LDAP over SSL first and can fall back to signed and sealed LDAP.

  When set to `True`, SharpHound is configured to use LDAPS for its base LDAP configuration where possible, but some ancillary directory-related operations may still use other negotiation or resolution paths.

  Do not use this setting as a guarantee that no TCP `389` traffic will occur in all scenarios.

  **Default value:** `False`

  **Example value:** `False`
</ResponseField>

<ResponseField name="ProviderWellKnown" type="string | null" pre={["IWA only"]}>
  ADFS well-known endpoint URL for Integrated Windows Authentication. This is typically the ADFS server address with `/.well-known/openid-configuration` appended. Required when `UseIntegratedWindowsAuthForADFS` is enabled.

  **Default value:** `null`

  **Example value:** `https://adfs.example.com/.well-known/openid-configuration`
</ResponseField>

<ResponseField name="ClientId" type="string | null" pre={["IWA only"]}>
  Client ID generated by BloodHound during collector client creation. SharpHound uses this value to identify itself to the ADFS server. Required when `UseIntegratedWindowsAuthForADFS` is enabled.

  **Default value:** `null`

  **Example value:** `12345678-1234-1234-1234-123456789012`
</ResponseField>

<ResponseField name="Resource" type="string | null" pre={["IWA only"]}>
  BloodHound Enterprise tenant URL used as the resource identifier for the ADFS application. Required when `UseIntegratedWindowsAuthForADFS` is enabled.

  **Default value:** `null`

  **Example value:** `https://your-tenant.bloodhoundenterprise.io`
</ResponseField>

<ResponseField name="UseIntegratedWindowsAuthForADFS" type="boolean" pre={["IWA only"]}>
  Enables Integrated Windows Authentication through ADFS. When set to `true`, SharpHound authenticates with the service account's Windows credentials against the configured ADFS server.

  When this setting is enabled, SharpHound does not use `auth.json`. You must also configure `ProviderWellKnown`, `ClientId`, and `Resource`.

  **Default value:** `False`

  **Example value:** `True`
</ResponseField>

## auth.json

The `auth.json` file is a plaintext JSON file that defines the credentials the service uses to authenticate to the BloodHound Enterprise API.

Creating a new client or rotating the credentials of an existing one will provide you with the complete JSON structure used for a SharpHound Enterprise client.

```json title="auth.json" icon="file-brackets-curly" theme={null}
{
"Token": "w4Tc+heVmaMTWgodlw0YlztaEGG53J/mwogiEZLvKE6WtylfYuoVEA==",
"TokenID": "0c6120ee-2fbe-478f-a864-2e264f9c16d2"
}
```

See the following reference to learn more about the supported fields in the `auth.json` file:

<ResponseField name="Token" type="string | null">
  Token SharpHound Enterprise uses to authenticate with the BloodHound Enterprise tenant.

  **Default value:** `null`

  **Example value:** `w4Tc+heVmaMTWgodlw0YlztaEGG53J/mwogiEZLvKE6WtylfYuoVEA==`
</ResponseField>

<ResponseField name="TokenID" type="string | null">
  Unique identifier for the token.

  **Default value:** `null`

  **Example value:** `0c6120ee-2fbe-478f-a864-2e264f9c16d2`
</ResponseField>