Run and Upgrade AzureHound (Windows, Docker, or Kubernetes)

  • Updated

This article applies to BHE

You will need your AzureHound configuration file from Create an AzureHound Configuration prior to beginning this process.

Windows

Run AzureHound on Windows

This shows how to install AzureHound as a service. Many organizations choose to run AzureHound alongside SharpHound from the same system. These services can live alongside each other and will not conflict.

Organizations who wish to run multiple AzureHound collectors on the same server, for example, because of multiple Azure tenants, must install AzureHound as Scheduled Tasks instead of Windows Services. See Setting up multiple AzureHound collectors on the same server with scheduled tasks.

After completing Create an AzureHound Configuration, test your new AzureHound configuration:

  1. Run “azurehound.exe start” on the command line from the directory you installed AzureHound in. the command line will show "Waiting for jobs..." if no collection schedule is configured on the client.

  2. While the command prompt is open and the client waits for jobs, perform an On Demand Scan test run from the BloodHound Enterprise tenant's client table.
    • The AzureHound Enterprise will show Status: Ready, and Last Checkin: n seconds ago
    • Click on the burger menu and select On Demand Scan
  3. In the On Demand Scan window, select RUN
  4. Back on the server, the command line will output data
    1. If successful, it will show "Collection completed successfully"
    2. If unsuccessful, check the AzureHound log generated next to the binary or contact your BloodHound Enterprise Technical Account Manager for support.

Once a test collection is complete without errors create a collection schedule for the client, see Create a data collection schedule.

Next, install AzureHound as a service so that the collector process can run continuously:

  1. Create the directory from where the AzureHound service will run.
    • NB: We recommend creating "C:\Program Files\AzureHound Enterprise" to increase security, as the Program Files directory is write-protected from non-administrative users. 
      New-Item 'C:\Program Files\AzureHound Enterprise' -ItemType Directory
  2. Move "azurehound.exe" into the created directory
  3. Open a command line as a local administrator, navigate to the created directory, and run “azurehound.exe install”
  4. Hit Enter, or type 'y', to use previously tested configuration settings

    • AzureHound will copy the configuration settings in your user profile to "C:\ProgramData\AzureHound\config.json", this is a hardcoded configuration file location
  5. If using certificate authentication:
    1. Copy the certificate and key file created in your user profile to a more central location, for example next to the configuration settings in "C:\ProgramData\azurehound"
      Move-Item "$env:USERPROFILE\.config\azurehound\*.pem" "C:\ProgramData\azurehound\"
    2. Update the configuration file "C:\ProgramData\AzureHound\config.json" to point to the new certificate and key file locations
  6. Open the Services Management interface from the Start menu, locate the "AzureHound" service, and start it.
  7. In BloodHound Enterprise's Manage Clients UI, the client will show Status: Ready, and Last Checkin: n seconds ago

Upgrade AzureHound on Windows

Upgrading AzureHound is done by replacing the previous service binary.

  1. Log into your BloodHound Enterprise tenant.
  2. Click ⚙️ → Download Collectors
  3. Download AzureHound Enterprise by clicking the button DOWNLOAD AZUREHOUND vX.X.X (.ZIP)

  4. Extract the contents of the zip archive and locate the binary suitable for your system's architecture
  5. Log into the server running your AzureHound service
  6. Click “Start” and then locate the “Services” application or run "services.msc"
  7. Locate the AzureHound service and open its properties
  8. From the service properties window, stop AzureHound by clicking Stop
  9. Replace the existing "azurehound.exe" binary seen in "Path to executable" with the newly downloaded one
  10. From the service properties window, start AzureHound by clicking Start

Docker

Run AzureHound on Docker

  1. A sample docker-compose.yaml file is attached to this article here.
  2. Integrate the appropriate structure into your existing configuration or utilize it as a new configuration in Docker, moving the associated config.json, cert.pem, and key.pem files to the appropriate location, and updating config.json according to your assigned values.
  3. In your docker directory, run: 
    docker-compose pull && docker-compose up -d
  4. Review the container logs and BloodHound Enterprise user interface to verify that AzureHound has successfully connected.

Upgrade AzureHound on Docker

  1. In your docker directory, run: 
    docker-compose pull && docker-compose up -d
  2. Review the container logs and BloodHound Enterprise user interface to verify that AzureHound has successfully connected.

Kubernetes

Run AzureHound on Kubernetes

  1. Create TLS secret for certificate and key using 
    kubectl create secret tls azurehound-tls --cert=<path to cert> --key=<path to key>”
  2. Create a generic secret, either:
    1. No passphrase: 
      kubectl create secret generic azurehound-secret --from-literal tokenId=<bloodhound enterprise token id> --from-literal token=<bloodhound enterprise token>
    2. Private key has passphrase: 
      kubectl create secret generic azurehound-secret --from-literal tokenId=<bloodhound enterprise token id> --from-literal token=<bloodhound enterprise token> --from-literal keypass=<private key passphrase>
  3. A sample deployment.yaml file is attached to this article here.
  4. Edit the provided deployment.yaml file. Read comments and replace instances of [ INSERT HERE ] with appropriate values
  5. Deploy AzureHound on k8s: 
    kubectl apply -f deployment.yaml
  6. Review the container logs and BloodHound Enterprise user interface to verify that AzureHound has successfully connected.

Upgrade AzureHound on Kubernetes

  1. On your Kubernetes cluster, run: 
    kubectl rollout restart deployment/azurehound-deployment
  2. Review the container logs and BloodHound Enterprise user interface to verify that AzureHound has successfully connected.