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, andjqfor the polling example.
Set two environment variables so the examples below can be pasted as they are:
export GUARDPKG_URL="https://guardpkg.example" # your GuardPkg address
export GUARDPKG_KEY="gp_…" # the key you created
Check that the key works:
curl -H "Authorization: Bearer $GUARDPKG_KEY" "$GUARDPKG_URL/api/v1/whoami"
{"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:
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:
{
"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:
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:
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#
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:
#!/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:
$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.