API / Symbols and functions

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:

bash
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:

http
POST /api/v1/binaries/{id}/symbols
Content-Type: multipart/form-data
bash
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 .map and 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 .map for now (the MSVC linker writes one with /MAP).

Remove a symbol file#

http
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:

json
"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.
  • functions counts every function found. named_functions counts those a symbol file or the export table names. fragments counts 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, used says whether its names were applied. When it's false, problem says 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#

http
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.
json
{
  "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.