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#
POST /api/v1/binaries
Content-Type: multipart/form-data
Send the file in a form field named file:
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.
{
"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#
GET /api/v1/binaries
Returns {"binaries": [ … ]}, newest first, without symbols or analysis.image. Deleted and expired binaries aren't listed.
Get one#
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#
GET /api/v1/binaries/{id}/download
Returns the original file you uploaded.
Delete#
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.