API / Binaries

API

Binaries

Uploading, listing, downloading and deleting binaries.

A binary is a file you've uploaded. Jobs run on binaries; one binary can have any number of jobs with different settings.

Upload#

http
POST /api/v1/binaries
Content-Type: multipart/form-data

Send the file in a form field named file:

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

You can send the binary's .map or .pdb in the same request, in fields named symbols; see Symbols and functions.

GuardPkg accepts PE32+ files (64-bit Windows executables and DLLs for x86-64) up to 50 MB. The file is checked on arrival: anything that isn't a well-formed PE32+ image is rejected with 422 and a message saying why.

Response: 201 Created for a new binary, or 200 OK if your organization already has a binary with the same bytes. In that case you get the existing one back with "duplicate": true, under the name it was first uploaded with.

json
{
  "binary": { "id": "01a19951-b0aa-7e58-ad41-ebd534d7a436", "name": "app.exe", … },
  "duplicate": false,
  "warnings": ["16 bytes of overlay data after the last section."]
}

warnings lists things worth knowing that don't stop the file being used, such as overlay data, a stripped relocation table, or an Authenticode signature (protection invalidates it, so re-sign the output).

The binary object#

Field Type Description
id string Use this to start jobs.
name string The file name it was uploaded with.
sha256 string Hex SHA-256 of the file.
size integer Size in bytes.
format, arch string Always pe and x86_64 today.
created_at string When it was uploaded (RFC 3339, UTC).
expires_at string or null When the file will be deleted; see Retention.
metadata object What was found in the file, below.
analysis object The function analysis: status, counts and, for a single binary, image facts. See Analysis.
symbols array Its symbol files. Only included when you get a single binary.

metadata contains kind (exe or dll), machine, subsystem, image_base, entry_point_rva, size_of_image, timestamp, signed, imports (DLL names), sections (name, addresses, sizes and characteristics of each) and warnings.

List#

http
GET /api/v1/binaries

Returns {"binaries": [ … ]}, newest first, without symbols or analysis.image. Deleted and expired binaries aren't listed.

Get one#

http
GET /api/v1/binaries/{id}

Returns the binary object, or 404 if it doesn't exist, belongs to another organization, or has been deleted.

Download#

http
GET /api/v1/binaries/{id}/download

Returns the original file you uploaded.

Delete#

http
DELETE /api/v1/binaries/{id}

Deletes the file and its symbol files immediately and returns 204 No Content. Jobs that ran on it stay in your history, but their binary shows as deleted. Binaries are also deleted automatically when they expire.