Documentatie / Agents en scanners

WatchTower CLI voor je software

Gebruik de vooraf gebouwde CLI om Docker-images, Node.js-, PHP- en andere softwarebronnen vanuit terminal of CI te controleren.

Wat je nodig hebt

  • CLI-releasebinary voor jouw OS/architectuur
  • Een workspace-token met scope cli:scan
  • Syft voor image- en directoryscans
  • Docker voor image-, container- en Dockerfile-scans
  1. 1

    Downloaden: kies de binary voor je OS

    Go is niet nodig om een gepubliceerde CLI-binary uit te voeren. De huidige CLI-release bevat macOS arm64/amd64, Linux arm64/amd64 en Windows amd64. De current-downloadlink verwijst door naar een vaste release-URL. De ondertekende catalogus op https://stackportrait.com/downloads/agent/manifest.json bevat SHA-256 en Ed25519-handtekeningen voor elk CLI-artifact. Alleen expliciet onderhouden oudere CLI-releases voor nog ondersteunde OS-versies staan op de per-OS-overzichtspagina.

  2. 2

    macOS

    Apple Silicon gebruikt watchtower-cli-darwin-arm64; Intel gebruikt watchtower-cli-darwin-amd64. Syft is vereist voor image- en directoryscans. Installeer Syft via Homebrew; Docker Desktop is alleen nodig voor Docker-bronnen. Download daarna de binary voor jouw architectuur en controleer de versie.

    brew tap anchore/syft && brew install syft
    # Apple Silicon; kies darwin-amd64 voor een Intel-Mac:
    curl -fSLo watchtower-cli https://stackportrait.com/downloads/cli/current/watchtower-cli-darwin-arm64
    chmod 0755 watchtower-cli
    ./watchtower-cli --version
    
  3. 3

    Linux

    Kies watchtower-cli-linux-amd64 voor x86-64 of watchtower-cli-linux-arm64 voor ARM64. Syft kan via de officiële Anchore-installer worden geïnstalleerd. Docker Engine is optioneel voor image- en containerbronnen.

    curl -sSfL https://get.anchore.io/syft | sudo sh -s -- -b /usr/local/bin
    # Kies linux-arm64 op een ARM64-systeem:
    curl -fSLo watchtower-cli https://stackportrait.com/downloads/cli/current/watchtower-cli-linux-amd64
    chmod 0755 watchtower-cli
    ./watchtower-cli --version
    
  4. 4

    Windows

    De Windows-binary heet watchtower-cli-windows-amd64.exe. Installeer Syft met WinGet. Docker Desktop is optioneel en alleen nodig voor Docker-bronnen. Download de binary uit de ondertekende CLI-release.

    winget install Anchore.Syft
    Invoke-WebRequest -Uri https://stackportrait.com/downloads/cli/current/watchtower-cli-windows-amd64.exe -OutFile watchtower-cli.exe
    .\watchtower-cli.exe --version
    
  5. 5

    Configuratiebestand: stel standaardwaarden in

    Zonder --config leest de CLI een JSON-bestand per gebruiker: macOS ~/Library/Application Support/WatchTower/watchtower-cli.json; Linux $XDG_CONFIG_HOME/watchtower-cli/config.json (standaard ~/.config/watchtower-cli/config.json); Windows %APPDATA%/WatchTower/watchtower-cli.json. tokenFile kan relatief aan dat bestand zijn. Bewaar het token zelf apart met Unix-rechten 0600 of een beperkte Windows-ACL. Onbekende keys worden geweigerd; flags op de commandoregel overschrijven configwaarden. WATCHTOWER_CLI_TOKEN overschrijft tokenFile.

    JSON-keyWanneer / standaardBetekenis
    serveroptioneel; standaard https://stackportrait.comHTTPS-origin; HTTP is alleen toegestaan op literal loopback met allowLocalHttp.
    tokenFileoptioneelTokenbestand; relatief pad is ten opzichte van de configmap.
    projectoptioneelProjectslug binnen de tokenworkspace.
    environmentoptioneelOmgevingslabel voor de scan.
    failOnstandaard highErnstgrens: none, low, medium, high of critical.
    formatstandaard texttext of json.
    timeoutstandaard 10m; maximum 1hTotale scantimeout, bijvoorbeeld 15m.
    syftstandaard syftSyft executable of volledig pad.
    allowLocalHttpstandaard falseSta HTTP alleen naar 127.0.0.1 of ::1 toe.
    scan.typevereist als de scanopdracht geen type heeftimage, container, directory, sbom of dockerfile.
    scan.refimage/containerImage-tag/digest of containernaam.
    scan.pathdirectory/sbom/dockerfilePad naar map, SBOM of Dockerfile.
    scan.contextdockerfile; standaard .Docker buildcontext.
    {
      "server": "https://stackportrait.com",
      "tokenFile": "watchtower.token",
      "project": "mijn-project",
      "environment": "staging",
      "failOn": "high",
      "format": "json",
      "timeout": "15m",
      "syft": "syft",
      "allowLocalHttp": false,
      "scan": {"type": "image", "ref": "registry.example/app@sha256:...", "path": "", "context": "."}
    }
    watchtower-cli config path
    watchtower-cli scan
    watchtower-cli scan image --ref app:nieuw --fail-on critical
    
  6. 6

    Voorbeelden per bron: scan een bron

    Syft leest package-metadata, lockfiles en geïnstalleerde packages; de CLI voert applicatiecode niet uit. Voor Node.js gebruik je bijvoorbeeld een projectmap met package-lock.json, pnpm-lock.yaml, yarn.lock of node_modules. Voor PHP gebruik je composer.lock of vendor/. Een image-scan leest de inhoud van die image. Een containercheck scant de image-ID, niet de schrijfbare laag of volumes. Dockerfile-modus voert expliciet docker build uit.

    watchtower-cli scan image --ref 'registry.example/team/node-api@sha256:...' --environment staging --fail-on high
    watchtower-cli scan directory --path ./node-api --format json
    watchtower-cli scan directory --path ./php-api --fail-on high
    watchtower-cli scan directory --path ./python-service
    watchtower-cli scan directory --path ./java-service
    watchtower-cli scan sbom --path build.cdx.json --format json
    watchtower-cli scan container --ref node-api --fail-on critical
    watchtower-cli scan dockerfile --path ./Dockerfile --context . --fail-on high
    
  7. 7

    Exitcodes en dekking: lees het resultaat

    Maak onder Verzameling → Inrichting → Ingest-tokens een token met het gebruik CLI · eenmalige scan; dit krijgt scope cli:scan. Bewaar het als secret of in een beschermd tokenbestand, nooit in argumenten of Git. Exitcode 0 betekent geen bevinding boven de gekozen drempel bij volledige beoordeling; 1 betekent een bevinding boven de drempel; 2 is een scan/API-fout; 3 is onvolledige dekking of ernstduiding. Controleer unknownCount, unratedFindingCount en coverageIssues in JSON.

Resultaat met expliciete bewijsgrenzen

Bewaar scan-ID en SBOM-hash bij de build. Een onbekende versie, ontbrekende identiteit of advisory zonder ernst maakt de drempeluitkomst onbeslist; nul bevindingen bewijst geen volledige veiligheid.

Open Watchtower