API
Symbols and functions
Attach a .map or .pdb to a binary, and list the functions GuardPkg found in it.
Every binary you upload is analysed: GuardPkg finds its functions and records the facts about the image. Without symbols, functions come from the image itself (its exception directory, exports and entry point) and have no names. Attach the linker map or PDB from the same build and they get names, and leaf functions that have no exception data are found too.
Names are what make settings reusable across builds. A function's address changes every time you rebuild, but its name usually doesn't.
Attach symbol files#
Send them with the binary, in form fields named symbols:
curl -H "Authorization: Bearer $GUARDPKG_KEY" \
-F file=@build/app.exe -F symbols=@build/app.map \
"$GUARDPKG_URL/api/v1/binaries"
Or add them to a binary you've already uploaded:
POST /api/v1/binaries/{id}/symbols
Content-Type: multipart/form-data
curl -H "Authorization: Bearer $GUARDPKG_KEY" -F symbols=@build/app.pdb \
"$GUARDPKG_URL/api/v1/binaries/$BINARY_ID/symbols"
Response: 200 OK with the binary object, including its
symbols.
- A binary has at most one
.mapand one.pdb. Uploading another of the same kind replaces the old one. - The kind is worked out from the file's content, not its name. Anything that isn't a linker map
or a PDB is rejected with
422. - Each file can be up to 64 MB.
- Symbol files are deleted with their binary, when you delete it or when it expires.
Adding or removing a symbol file starts a new analysis.
PDBs are accepted and stored, but not read yet: they show as not used. Use the
.mapfor now (the MSVC linker writes one with/MAP).
Remove a symbol file#
DELETE /api/v1/binaries/{id}/symbols/{kind}
kind is map or pdb. Returns 204 No Content, or 404 if the binary has none of that kind.
Analysis#
The binary object carries the state of its latest analysis:
"analysis": {
"status": "ready",
"error": null,
"analyzed_at": "2026-11-03T04:42:20Z",
"functions": 96,
"named_functions": 96,
"fragments": 11,
"image": { "entry": "0xCDB0", "pdb": { "guid": "3A920A1A-…", "age": 1 }, … }
},
"symbols": [
{ "kind": "map", "name": "app.map", "size": 51130, "sha256": "…",
"used": true, "symbols": 431, "problem": null }
]
status |
Meaning |
|---|---|
pending |
Analysis is queued or running. It usually takes a few seconds. |
ready |
Done; the function list is available. |
failed |
The binary couldn't be analysed. error says why. |
functionscounts every function found.named_functionscounts those a symbol file or the export table names.fragmentscounts chained exception records, which belong to a function and aren't listed on their own.image(only when you get a single binary) is what the analysis read from the headers, including the PDB the linker recorded: a PDB matches the binary when its GUID and age are these.- For each symbol file,
usedsays whether its names were applied. When it'sfalse,problemsays why. Usually the file comes from a different build: a map is matched to the binary by its link timestamp.
Poll GET /api/v1/binaries/{id} until status isn't pending.
List functions#
GET /api/v1/binaries/{id}/functions?q=Aes256*&after=0x1000&limit=1000
| Parameter | Description |
|---|---|
q |
Optional search, case-insensitive, over the name, undecorated name and export name. Text matches anywhere in a name (Sha256 finds HmacSha256Init). With a * it matches whole names instead: Aes256*, *Block, Crypto::*. * is the only wildcard; ?, _ and % match themselves. An address such as 0x1620 also finds the function there. |
after |
Optional: only functions above this RVA, in hex. Use the previous page's next_after. |
limit |
Optional, default 1000, at most 5000. |
{
"functions": [
{ "rva": "0x1620", "size": 971, "name": "Aes256EncryptBlock", "display": null,
"export": null, "sources": ["pdata", "map"] },
{ "rva": "0xCB40", "size": 182, "name": "?pre_c_initialization@@YAHXZ",
"display": "int pre_c_initialization(void)", "export": null, "sources": ["pdata", "map"] }
],
"total": 96,
"next_after": "0xCB40"
}
Functions are sorted by RVA. total counts every function that matches q (every function
without it), on every page. next_after is null on the last page.
| Field | Description |
|---|---|
rva |
Address relative to the image base, in hex. |
size |
Size in bytes. 0 when nothing gives an extent, such as a leaf function known only from the map. |
name |
The name from the symbol file, decorated as the linker wrote it. |
display |
The undecorated name, when it differs from name. |
export |
The export name, if the function is exported. |
sources |
Where it was found: pdata, export, entry, map. |
While the analysis is pending this returns 409; if it failed, 422 with the reason.