Documentatie / Agents en scanners

Windows-agent installeren

Kies zelf tussen een losse EXE, automatisch starten of een SBOM zonder agent; kies daarna statisch token of mTLS.

Wat je nodig hebt

  • Windows x86-64 met actieve Microsoft-beveiligingsupdates
  • Een account met rechten op de gekozen bronnen
  • Een agenttoken; voor mTLS ook een goedgekeurd clientcertificaat
  1. 1

    Uitvoering: kies eenmalige of automatische start

    Kies eerst: eenmalig uitvoeren met de losse binary, automatisch starten met de beheerde installatie, of zonder agent een eigen CycloneDX-SBOM naar de ingest-API sturen. Voor een beheerde installatie is een configuratiebestand nodig. Kies daarna tussen een statisch agenttoken en mTLS-bootstrap; beide routes zijn ondersteund. De Windows-host-collector leest OS/build, geregistreerde software, QFE en gedeelde .NET-runtimes. Voor applicatiemappen gebruik je aanvullend filesystem met Syft.

  2. 2

    Downloaden

    Kies de losse EXE voor een eenmalige run of de complete ZIP voor een beheerde opstarttaak. Bewaar het gekozen bestand in de aparte voorbereidingsmap %ProgramData%\WatchTower\agent-setup; die map is niet de uiteindelijke installatiemap. De installer moet de bestanden vanuit deze map naar de beschermde agentmap kunnen kopiëren. De ZIP heeft een aparte SHA-256-checksum; de EXE staat met SHA-256 en Ed25519-handtekening in de ondertekende releasecatalogus.

    Via CMD

    Open CMD als administrator. Deze route downloadt de complete ZIP naar de voorbereidingsmap. Vergelijk de checksum uit het .sha256-bestand met certutil. Pak bij overeenkomst de ZIP via Verkenner met rechtsklik → Alles uitpakken uit naar precies dezelfde map; de EXE en agent.example.json moeten daar direct naast elkaar staan. ProgramData is verborgen: plak het pad in de adresbalk.

    set "WORK=%ProgramData%\WatchTower\agent-setup"
    mkdir "%WORK%" 2>nul
    icacls "%WORK%" /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F"
    if errorlevel 1 exit /b 1
    cd /d "%WORK%"
    curl.exe -fL -o watchtower-agent.zip https://stackportrait.com/downloads/agent/current/watchtower-agent-windows-amd64-package.zip || exit /b 1
    curl.exe -fL -o watchtower-agent.zip.sha256 https://stackportrait.com/downloads/agent/current/watchtower-agent-windows-amd64-package.zip.sha256 || exit /b 1
    type watchtower-agent.zip.sha256
    certutil -hashfile watchtower-agent.zip SHA256
    

    Via de browser

    Maak eerst met het CMD-blok hieronder de beschermde voorbereidingsmap. Download de EXE of ZIP plus de bijbehorende checksum met de browser naar Downloads. Verplaats deze bestanden via Verkenner naar %ProgramData%\WatchTower\agent-setup en bevestig de Windows-beheerdersvraag. Vergelijk de twee hashwaarden; pak alleen de geverifieerde ZIP met rechtsklik → Alles uitpakken uit naar precies diezelfde map. De EXE, helpers en agent.example.json moeten dan direct naast elkaar staan. De losse EXE heeft geen voorbeeldbestand: gebruik in Configureren het JSON-voorbeeld op deze pagina.

    set "WORK=%ProgramData%\WatchTower\agent-setup"
    mkdir "%WORK%" 2>nul
    icacls "%WORK%" /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F"
    if errorlevel 1 exit /b 1
    

    Na het verplaatsen: vergelijk de checksum vóór het uitpakken

    cd /d "%ProgramData%\WatchTower\agent-setup"
    if exist watchtower-agent-windows-amd64-package.zip.sha256 type watchtower-agent-windows-amd64-package.zip.sha256
    if exist watchtower-agent-windows-amd64-package.zip certutil -hashfile watchtower-agent-windows-amd64-package.zip SHA256
    if exist watchtower-agent-windows-amd64.exe.sha256 type watchtower-agent-windows-amd64.exe.sha256
    if exist watchtower-agent-windows-amd64.exe certutil -hashfile watchtower-agent-windows-amd64.exe SHA256
    

    Via PowerShell

    Gebruik Windows PowerShell 5.1 of PowerShell 7 als administrator. Deze route downloadt en pakt de complete ZIP uit in de voorbereidingsmap; controleer daarna dat de EXE en agent.example.json daar direct naast elkaar staan. -UseBasicParsing voorkomt op Windows PowerShell 5.1 de waarschuwing over webscripts.

    $work = Join-Path $env:ProgramData 'WatchTower\agent-setup'
    New-Item -ItemType Directory -Force $work | Out-Null
    & icacls.exe $work /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw 'Voorbereidingsmap kon niet worden afgeschermd.' }
    Set-Location $work
    $package = 'https://stackportrait.com/downloads/agent/current/watchtower-agent-windows-amd64-package.zip'
    $checksum = "$package.sha256"
    Invoke-WebRequest -UseBasicParsing -ErrorAction Stop $package -OutFile .\watchtower-agent.zip
    $expected = (Invoke-WebRequest -UseBasicParsing -ErrorAction Stop $checksum).Content.Trim().Split()[0]
    if ($expected -notmatch '^[a-fA-F0-9]{64}$' -or (Get-FileHash .\watchtower-agent.zip -Algorithm SHA256).Hash -ne $expected) { throw 'Checksum klopt niet; gebruik de ZIP niet.' }
    Expand-Archive -LiteralPath .\watchtower-agent.zip -DestinationPath $work -Force -ErrorAction Stop
    if (-not (Test-Path .\watchtower-agent-windows-amd64.exe) -or -not (Test-Path .\agent.example.json)) { throw 'Het uitgepakte agentpakket is onvolledig.' }
    'Download, checksum en uitpakken zijn in orde.'
    
  3. 3

    Authenticatie: kies je ingestmethode

    Kies één ingestmethode. Beide worden ondersteund: een statisch agenttoken voor inventaris en heartbeat, of mTLS met een goedgekeurd clientcertificaat en bootstrap-token voor certificaatgebonden sessies. De overige installatie-instructies zijn gelijk.

    Statisch agenttoken

    Maak onder Verzameling → Inrichting → Ingest-tokens het preset “Agent · bestaand statisch token” aan. Dit token mag inventaris en heartbeats publiceren totdat je het intrekt. Bewaar het alleen in een afgeschermd agent.json; de bron geldt niet als mTLS-geverifieerd. Gebruik voor releasebevestiging die mTLS vereist de andere route.

    mTLS met clientcertificaat

    Kies “Agent · mTLS bootstrap” als je clientcertificaat en kortlevende agentsessie wilt gebruiken. Maak de sleutel en CSR met dezelfde agent-ID als in agent.json. Als OpenSSL is geïnstalleerd en in PATH staat, kun je de korte CMD-route gebruiken. Zonder OpenSSL open je de ingebouwde Windows PowerShell-route hieronder. Bewaar de bestanden onder %ProgramData%\WatchTower\agents\agent\certs, upload alleen client.csr en sla de uitgegeven client-chain.crt in dezelfde map op. Deel client.key nooit en overschrijf bestaande bestanden niet. Beheer bij zelf geïnstalleerde agents ook de certificaatvernieuwing .

    Toon CMD-opdrachten voor sleutel en CSR (met OpenSSL)
    set "AGENT_ID=windows-lab-01"
    set "CERT_DIR=%ProgramData%\WatchTower\agents\agent\certs"
    mkdir "%CERT_DIR%" 2>nul
    if exist "%CERT_DIR%\client.key" exit /b 1
    if exist "%CERT_DIR%\client.csr" exit /b 1
    where openssl
    if errorlevel 1 exit /b 1
    icacls "%CERT_DIR%" /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-19:(OI)(CI)RX"
    if errorlevel 1 exit /b 1
    openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 -out "%CERT_DIR%\client.key"
    if errorlevel 1 exit /b 1
    openssl req -new -sha256 -key "%CERT_DIR%\client.key" -out "%CERT_DIR%\client.csr" -subj "/C=NL/O=Revolted/OU=CVE Watchtower Agent/CN=%AGENT_ID%"
    if errorlevel 1 exit /b 1
    openssl req -in "%CERT_DIR%\client.csr" -verify -noout
    if errorlevel 1 exit /b 1
    echo CSR gereed. Upload alleen client.csr; deel client.key niet.
    
    Toon Windows PowerShell-opdrachten voor sleutel en CSR (zonder OpenSSL)
    $ErrorActionPreference = 'Stop'
    $agentId = 'windows-lab-01' # kies je eigen stabiele agent-ID
    if ($agentId -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]{1,79}$') { throw 'Ongeldige agent-ID.' }
    $certDir = Join-Path $env:ProgramData "WatchTower\agents\agent\certs"
    New-Item -ItemType Directory -Force -Path $certDir | Out-Null
    & icacls.exe $certDir /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-19:(OI)(CI)RX' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw 'Certificaatmap kon niet worden afgeschermd.' }
    $keyPath = Join-Path $certDir 'client.key'
    $csrPath = Join-Path $certDir 'client.csr'
    if ((Test-Path $keyPath) -or (Test-Path $csrPath)) { throw 'Sleutel of CSR bestaat al; overschrijf die niet.' }
    function ConvertTo-Pem($label, [byte[]]$bytes) {
        $base64 = [Convert]::ToBase64String($bytes)
        $lines = for ($i = 0; $i -lt $base64.Length; $i += 64) { $base64.Substring($i, [Math]::Min(64, $base64.Length - $i)) }
        "-----BEGIN $label-----`n$($lines -join "`n")`n-----END $label-----`n"
    }
    $options = [System.Security.Cryptography.CngKeyCreationParameters]::new()
    $options.ExportPolicy = [System.Security.Cryptography.CngExportPolicies]::AllowPlaintextExport
    $keyName = 'WatchTower-csr-' + [Guid]::NewGuid().ToString('N')
    $cng = [System.Security.Cryptography.CngKey]::Create([System.Security.Cryptography.CngAlgorithm]::ECDsaP256, $keyName, $options)
    $key = $null
    try {
        $key = [System.Security.Cryptography.ECDsaCng]::new($cng)
        $request = [System.Security.Cryptography.X509Certificates.CertificateRequest]::new("CN=$agentId,OU=CVE Watchtower Agent,O=Revolted,C=NL", $key, [System.Security.Cryptography.HashAlgorithmName]::SHA256)
        $utf8 = [System.Text.UTF8Encoding]::new($false)
        $keyDer = $cng.Export([System.Security.Cryptography.CngKeyBlobFormat]::Pkcs8PrivateBlob)
        $csrDer = $request.CreateSigningRequest()
        [System.IO.File]::WriteAllText($keyPath, (ConvertTo-Pem 'PRIVATE KEY' $keyDer), $utf8)
        [System.IO.File]::WriteAllText($csrPath, (ConvertTo-Pem 'CERTIFICATE REQUEST' $csrDer), $utf8)
        & certutil.exe -dump $csrPath > $null
        if ($LASTEXITCODE -ne 0) { throw 'De CSR is ongeldig.' }
        Write-Host "CSR gereed: $csrPath (client.key blijft op deze host)"
    } catch {
        Remove-Item $keyPath, $csrPath -ErrorAction SilentlyContinue
        throw
    } finally {
        if ($key) { $key.Dispose() }
        $cng.Delete() # alleen de tijdelijke CNG-kopie; client.key blijft op schijf
    }
    
  4. 4

    Configureren: maak agent.json

    Bij de ZIP: controleer dat het pakket na de uitpakstap direct de EXE en het voorbeeldbestand bevat in %ProgramData%\WatchTower\agent-setup. Kopieer agent.example.json naar agent.json en open de kopie in Kladblok. Bij de losse EXE ontbreekt het voorbeeldbestand: maak agent.json in dezelfde map en plak het volledige JSON-voorbeeld hieronder. Vervang url, token, agentId, hostname, asset en environment. Geef de windows-host collector dezelfde asset en environment; verwijder syft als je alleen deze collector gebruikt. Sla op en sluit Kladblok.

    De installer bewaart de actieve configuratie en spool onder C:\ProgramData\WatchTower\agents\agent. Dat is een afgeschermde machinebrede map. Plak %ProgramData%\WatchTower in de adresbalk van Verkenner om de verborgen map te openen. Een wifi- of LAN-adres is niet nodig; de agent maakt zelf een uitgaande HTTPS-verbinding.

    Gebruik je mTLS? Voeg dan clientCertificate en clientKey toe met de absolute paden naar C:\ProgramData\WatchTower\agents\agent\certs\client-chain.crt en C:\ProgramData\WatchTower\agents\agent\certs\client.key. Het voorbeeld hieronder toont de volledige mTLS-configuratie; bij een statisch token laat je die twee velden weg. De volgende installatiestap controleert agent.json voordat de agent start.

    {
      "url": "https://stackportrait.com",
      "token": "<mTLS-bootstrap-token: alleen lokaal invullen>",
      "agentId": "windows-lab-01",
      "hostname": "windows-lab-01",
      "asset": "windows-lab-01-host",
      "environment": "acceptance",
      "spoolDirectory": "C:\\ProgramData\\WatchTower\\agents\\agent\\data\\spool",
      "clientCertificate": "C:\\ProgramData\\WatchTower\\agents\\agent\\certs\\client-chain.crt",
      "clientKey": "C:\\ProgramData\\WatchTower\\agents\\agent\\certs\\client.key",
      "collectors": [{"type":"windows-host","name":"host-packages","asset":"windows-lab-01-host","environment":"acceptance"}]
    }
    
    Toon CMD-stappen voor agent.json
    cd /d "%ProgramData%\WatchTower\agent-setup"
    if exist agent.example.json if not exist agent.json copy agent.example.json agent.json
    notepad agent.json
    
    Toon PowerShell-stappen voor agent.json
    Set-Location (Join-Path $env:ProgramData 'WatchTower\agent-setup')
    if ((Test-Path .\agent.example.json) -and -not (Test-Path .\agent.json)) { Copy-Item -LiteralPath .\agent.example.json -Destination .\agent.json -ErrorAction Stop }
    notepad.exe .\agent.json
    
  5. 5

    Installeren: start eenmalig of automatisch

    Voor een proef voer je de EXE uit vanuit de voorbereidingsmap %ProgramData%\WatchTower\agent-setup. Voor automatisch starten is het complete ZIP-pakket met helpers nodig; de losse EXE kan alleen eenmalig draaien. Open Administrator-PowerShell en gebruik -install-as-service; dit maakt een Windows Scheduled Task onder LocalService, geen Windows-service. De installer kopieert de binary, helpers en agent.json naar C:\ProgramData\WatchTower\agents\agent. De taak heet bij agent.json WatchTowerAgent-agent.

    Set-Location (Join-Path $env:ProgramData 'WatchTower\agent-setup')
    .\watchtower-agent-windows-amd64.exe -config .\agent.json -check-config
    if ($LASTEXITCODE -ne 0) { throw 'Configuratie ongeldig; start de agent niet.' }
    .\watchtower-agent-windows-amd64.exe -config .\agent.json -once
    
    Toon automatische installatie vanuit de ZIP
    Set-Location (Join-Path $env:ProgramData 'WatchTower\agent-setup')
    # Open PowerShell als administrator; agent.json staat in deze map.
    .\watchtower-agent-windows-amd64.exe -config .\agent.json -install-as-service
    
  6. 6

    Controleren: taak en ontvangst

    Controleer eerst de lokale configuratie, voer een enkele scan uit en kijk daarna in Verzameling → Agents naar heartbeat en collectorstatus. Controleer in Omgeving → Assets of de juiste asset en componenten zijn ontvangen. Een actieve taak of service bewijst op zichzelf geen serverontvangst. De taakstatus kun je met Get-ScheduledTask -TaskName WatchTowerAgent-agent zien; een fout in ontvangst lees je in de agentlog. Deel geen token, private key of volledige config.

  7. 7

    Beheren: updates, herstel en grenzen

    De ZIP bevat manage-windows.ps1 voor Status, Upgrade, Rollback en Uninstall. Gebruik bij een handmatige route de versie en EXE-hash van de actuele ondertekende catalogus; geef altijd InstallRoot C:\ProgramData\WatchTower\agents\agent en TaskName WatchTowerAgent-agent mee. Bij een door jezelf beheerde mTLS-agent moet je het 30 dagen geldige certificaat tijdig vernieuwen. Niet-geladen gebruikersprofielen, portable programma’s en updates buiten QFE blijven buiten de Windows-hostwaarneming.

    Toon handmatige installatie en status
    # Vanuit de uitgepakte ZIP in Administrator PowerShell, na het maken van agent.json:
    .\manage-windows.ps1 -Action Install `
      -BinaryPath .\watchtower-agent-windows-amd64.exe -ConfigPath .\agent.json `
      -Version '<versie uit ondertekende catalogus>' `
      -ExpectedSha256 '<EXE SHA-256 uit ondertekende catalogus>' `
      -UpdaterPath .\watchtower-agent-win-updater.exe `
      -SupervisorPath .\watchtower-agent-supervisor.exe `
      -InstallRoot "$env:ProgramData\WatchTower\agents\agent" -TaskName WatchTowerAgent-agent
    .\manage-windows.ps1 -Action Status -InstallRoot "$env:ProgramData\WatchTower\agents\agent" -TaskName WatchTowerAgent-agent
    

Agent aantoonbaar aangesloten

Controleer heartbeat, collectorresultaat en de ontvangen componenten. Voor een native Windows-acceptatie blijft de eigen hostproef nodig.

Open Watchtower