Getting started / Quickstart

Getting started

Quickstart

Upload a binary, protect it and download the result from the command line.

GuardPkg protects x86-64 Windows executables (PE32+): you upload a binary, run a job with the settings you want, and download the protected output. Everything in the dashboard can also be done with the HTTP API, which is what this page uses.

Before you start#

You need:

  • An account. GuardPkg is invite-only during the alpha.
  • An API key. Create one under API keys in the dashboard; it's shown only once.
  • curl, and jq for the polling example.

Set two environment variables so the examples below can be pasted as they are:

bash
export GUARDPKG_URL="https://guardpkg.example"   # your GuardPkg address
export GUARDPKG_KEY="gp_…"                        # the key you created

Check that the key works:

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" "$GUARDPKG_URL/api/v1/whoami"
json
{"key_id": "01a19951-b051-78dc-bdfe-10dc21fedf29", "key_name": "ci-release", "org_id": "01a19951-b020-7d74-a326-d5f7af05b789"}

1. Upload the binary#

Send the file as multipart/form-data in a field named file:

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" \
     -F file=@build/app.exe \
     "$GUARDPKG_URL/api/v1/binaries"

The response describes what was found in the file. Keep binary.id:

json
{
  "binary": {
    "id": "01a19951-b0aa-7e58-ad41-ebd534d7a436",
    "name": "app.exe",
    "sha256": "da5807bb0997cc6b5132950ec87eda2b33b1ac4533cf1f7a22a6f3b576ed7c5b",
    "size": 200704,
    "expires_at": "2026-11-08T22:53:50Z",
    …
  },
  "duplicate": false,
  "warnings": []
}

Uploading the same bytes again returns the existing binary with "duplicate": true, so it's safe to upload on every build.

2. Start a job#

With no settings, the job uses the tool's defaults:

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" \
     -d '{"binary_id": "01a19951-b0aa-7e58-ad41-ebd534d7a436"}' \
     "$GUARDPKG_URL/api/v1/jobs"

To choose settings, pass a saved profile ("profile_id") or the settings themselves; see Jobs. The response contains the new job, with "status": "queued".

3. Wait for it to finish#

Poll the job until its status is no longer queued or running:

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" "$GUARDPKG_URL/api/v1/jobs/$JOB_ID"

A finished job has a status of succeeded, failed or canceled, and diagnostic_counts says how many errors, warnings and notes the engine reported.

4. Download the output#

bash
curl -H "Authorization: Bearer $GUARDPKG_KEY" -OJ "$GUARDPKG_URL/api/v1/jobs/$JOB_ID/output"

-OJ saves the file under the name the server suggests, for example app.protected.exe.

All together#

A script you can drop into a release pipeline. It fails the build if the job fails or if any function couldn't be protected:

bash
#!/usr/bin/env bash
set -euo pipefail
api() { curl -fsS -H "Authorization: Bearer $GUARDPKG_KEY" "$@"; }

BIN=$(api -F file=@build/app.exe "$GUARDPKG_URL/api/v1/binaries" | jq -r .binary.id)
JOB=$(api -d "{\"binary_id\":\"$BIN\"}" "$GUARDPKG_URL/api/v1/jobs" | jq -r .job.id)

while :; do
  JSON=$(api "$GUARDPKG_URL/api/v1/jobs/$JOB")
  STATUS=$(jq -r .status <<<"$JSON")
  [[ $STATUS == queued || $STATUS == running ]] || break
  sleep 3
done

if [[ $STATUS != succeeded ]]; then
  echo "job $STATUS: $(jq -r .error <<<"$JSON")" >&2
  exit 1
fi
if (( $(jq .diagnostic_counts.error <<<"$JSON") > 0 )); then
  api "$GUARDPKG_URL/api/v1/jobs/$JOB/diagnostics?severity=error" | jq -r '.diagnostics[] | "\(.code) \(.function_name // "") \(.message)"' >&2
  exit 1
fi
api -o build/app.protected.exe "$GUARDPKG_URL/api/v1/jobs/$JOB/output"

The same in PowerShell, for Windows build agents:

powershell
$ErrorActionPreference = "Stop"
$h = @{ Authorization = "Bearer $env:GUARDPKG_KEY" }
$base = "$env:GUARDPKG_URL/api/v1"

$bin = Invoke-RestMethod -Method Post -Headers $h -Uri "$base/binaries" -Form @{ file = Get-Item build\app.exe }
$job = Invoke-RestMethod -Method Post -Headers $h -Uri "$base/jobs" -ContentType application/json `
         -Body (@{ binary_id = $bin.binary.id } | ConvertTo-Json)

do {
  Start-Sleep -Seconds 3
  $j = Invoke-RestMethod -Headers $h -Uri "$base/jobs/$($job.job.id)"
} while ($j.status -in "queued", "running")

if ($j.status -ne "succeeded") { throw "job $($j.status): $($j.error)" }
Invoke-WebRequest -Headers $h -Uri "$base/jobs/$($j.id)/output" -OutFile build\app.protected.exe

Invoke-RestMethod -Form needs PowerShell 7 or later.