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

This article applies to BHE

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

Windows

Install AzureHound Enterprise on Windows

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

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

  1. Follow the article Create an AzureHound Configuration to create a configuration file.

  2. Create a directory for the AzureHound service binary. We recommend using "C:\Program Files\AzureHound Enterprise" as the Program Files directory is write-protected from non-administrative users.
    New-Item 'C:\Program Files\AzureHound Enterprise' -ItemType Directory
  3. Move "azurehound.exe" into the created directory
  4. Open a command line as a local administrator, navigate to the created directory, and run: 
    azurehound.exe install
  5. Hit Enter, or type 'y', to use the previously created configuration file.
    • AzureHound will copy the configuration settings in your user profile to "C:\ProgramData\AzureHound\config.json", this is a hardcoded configuration file location
  6. If using certificate authentication:
    • 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\"
    • Edit the configuration file in "C:\ProgramData\AzureHound\config.json" and change the "cert" and "key" values to the new certificate and key file locations.
  7. Start the "AzureHound" service:
  8. If configured correctly, the collector client in BloodHound Enterprise will show "Status: Ready", and "Last Checkin: a few seconds ago"

Upgrade AzureHound Enterprise on Windows

Upgrading AzureHound Enterprise 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

Single run of AzureHound Enterprise on Windows

Instead of installing AzureHound as a service, it is also possible to run AzureHound a single time which runs until the command line is closed or the user logs off. This is often used in troubleshooting scenarios.

  1. Follow the article Create an AzureHound Configuration to create a configuration file.
  2. Open a command line as a local administrator, navigate to the directory containing AzureHound Enterprise, and run: 
    azurehound.exe start
  3. If the connection to BloodHound Enterprise is successful, the program will output "Waiting for jobs...".
    • In BloodHound Enterprise, the AzureHound collector client will now show "Status: Ready", and "Last Checkin: a few seconds ago"
  4. If needing to test AzureHound's connectitity to Azure; keep the command prompt open and follow Run an On Demand Scan
  5. When started and AzureHound has fetched the job, the command line will output data while the collection is running.
    • If successful, the final message will be "Collection completed successfully"
    • If unsuccessful, check the log for errors, or check the AzureHound log generated next to the binary, or contact the BloodHound Enterprise team for support.

Docker

Run AzureHound Enterprise on Docker

  1. Use the attached sample file: docker-compose.yaml
  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 Enterprise 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 Enterprise 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. Choose between:
    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 Enterprise 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.

Updated