Install and Upgrade SharpHound Enterprise

  • Updated

This article applies to BHE

Install SharpHound Enterprise

  1. Log into your BloodHound Enterprise tenant. Your account team will provide you with the URL with a domain in the format of CODENAME.bloodhoundenterprise.io.
  2. Click on the gear icon in the top right corner, followed by “Download Collectors”.
    mceclip0.png
  3. On the SharpHound version marked “Latest,” click “Download SharpHound vX.X.X (.zip)".
    mceclip2.png
  4. Log into your SharpHound server.
  5. Validate that your SharpHound service account is a member of the local Administrators group.
  6. Extract the contents of the zip archive on your SharpHound Server.
  7. Double-click on "SHSetup.exe".
  8. If you are running Microsoft Defender, SmartScreen may display a warning. If not, skip to step 3, otherwise:
    1. Click “More info".
      mceclip3.png
    2. Validate the publisher shows “Specter Ops, Inc.”, then click “Run anyway".
      mceclip4.png
  9. Click “Yes” on the User Account Control dialog box if it appears.
  10. Choose where to install the service and click “Next".
    mceclip5.png
  11. Click “Install".
    mceclip6.png
  12. Provide credentials for your SharpHound service account.

    Provide the username in the format: DOMAIN\username

    Note: If using a gMSA, as per our SharpHound Service Hardening Guidelines, you must provide the credentials for a user account with local administrator access to the system, then post-installation, change the service to run as the gMSA, see Add the gMSA to the SharpHound Enterprise service. 

    Click “OK".
    mceclip7.png
  13. Check the “Edit Settings” box and click “Finish".
    mceclip8.png
  14. If prompted to choose an application to open the file, select Notepad.

  15. Notepad will open the settings.json file located within the installation directory chosen previously (by default, C:\Program Files (x86)\SHService\).

    Modify the "RestEndpoint" value to represent the domain provided by your account team. The domain will follow the format of CODENAME.bloodhoundenterprise.io.

    If your organization utilizes an explicit HTTP proxy, specify the URL of the proxy in the "Proxy" field, surrounded by double quotation marks, as seen in the RestEndpoint value below.

    For complete documentation on the fields and values in settings.json, see SharpHound Configuration.
    mceclip0.png
  16. Click “File,” then “Save,” but do not close Notepad.

    Note: if you do close Notepad, click “Start,” then find the Notepad application, right-click on it, and choose “Run as administrator”. Windows requires elevated access to modify the contents of the Program Files (x86) directory.
  17. Click “File,” then “Open".
  18. In the bottom-right corner of the “Open” dialog, change the dropdown to say “All Files (*.*)”.
    mceclip1.png
  19. Navigate to your installation directory (by default, C:\Program Files (x86)\SHService\) and open the file “auth.json".
    mceclip2.png
  20. Create a SharpHound collector client by following Create a BloodHound Enterprise collector client. Continue to the next step when you have the Client Token Info / Token ID and Token.
  21. Return to your Notepad window within your SharpHound server session, highlight the entire file contents, and paste in the JSON Client Token Info copied from the BloodHound Enterprise UI when creating the new client.
    mceclip8.png
  22. Click “File,” then “Save,” and exit Notepad.

    Note: If doing so prompts you with the “Save as…” dialog, close Notepad, and return to the step where you opened auth.json again, making sure to run Notepad as an administrator as specified.
  23. Click “Start” and then locate the “Services” application or run msc.
    mceclip9.png
  24. Locate the “SharpHound Delegator” service and click the “Start” button.

    Note: If you intend to utilize a GMSA for this service, open the service properties and set the GMSA in the Logon tab before starting the service.

    Common problems:
    I don't see the SHDelegator Service
    The SharpHound Delegator Service won't start
  25. Return to the BloodHound Enterprise UI. You should see your client showing 🟢 Ready

    mceclip10.png

  26. Configure a collection schedule for the client, see Create a data collection schedule.

Upgrade SharpHound Enterprise

  1. Log into your BloodHound Enterprise tenant. Your account team will provide you with the URL with a domain in the format of CODENAME.bloodhoundenterprise.io.
  2. Click on the gear icon in the top right corner, followed by “Download Collectors".
    mceclip0.png
  3. On the SharpHound version marked “Latest,” click “Download SharpHound vX.X.X (.zip)".
    mceclip2.png
  4. Log into your SharpHound server.
  5. Validate that your SharpHound service account is a member of the local Administrators group.
  6. Extract the contents of the zip archive on your SharpHound Server.
  7. Double-click on "SHSetup.exe".
  8. You may uncheck the “Edit Settings” box and click “Finish".
  9. Click “Start” and then locate the “Services” application or run msc.
    mceclip9.png
  10. Locate the “SharpHound Delegator” service and click the “Start” button.

Common installation issues

I don't see the SHDelegator Service

Most frequently, this is the result of one of two issues:

  1. The service account was not added as a local Administrator before installation.
  2. The password was entered into the credential window incorrectly.

The installation log may be of help in troubleshooting, and can be found in the file InstallUtil.Install.Log in the in the installation directory, the default location is "C:\Program Files (x86)\SHService\InstallUtil.Install.Log".

The SharpHound Delegator Service won't start

  1. Check if the "TempDirectory" key in settings.json is null or if it is set to a directory in AppData. The settings file is in the installation directory, the default location is "C:\Program Files (x86)\SHService\settings.json".
  2. If it is null, the service account has not been granted local Administrator privileges. Add the service account to the local Administrators group and restart the service.
  3. If the value is set to a directory in AppData, navigate to that directory and look for service.log and review the message for errors. Common issues include:
    • RestEndpoint cannot be resolved
      • Validate that you properly configured the RestEndpoint value to match the CODENAME.bloodhoundenterprise.io domain of your BloodHound Enterprise tenant.
      • Validate that you can resolve the domain from the host using the command prompt.
    • RestEndpoint cannot be reached (timeout, connection rejected, etc)
      • Validate that firewall exclusions to your domain have been created appropriately
      • If you need an explicit proxy, configure it within settings.json