d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
# Symbol Bundle Guide
|
|
|
|
This guide explains how to package, validate, and distribute symbol bundles that comply with `SYMBOL_MANIFEST/v1`.
|
|
|
|
## 1. Packaging steps
|
|
1. Gather debug artifacts (ELF `.debug`, PDB, dSYM) for the target release.
|
|
2. Compute `sha256` for each file and record size/arch/format.
|
|
3. Build `manifest.json` as per `SYMBOL_MANIFEST_v1.md`; sort entries by `build_id`, then `file`.
|
|
4. Write `manifest.json.sha256` with the hex digest of `manifest.json`.
|
|
5. Create a deterministic tarball:
|
|
- POSIX ustar
|
|
- Sorted file order
|
|
- `mtime=0`, `uid=gid=0`, `uname=guname=root`
|
|
- Compression: gzip `-n` to avoid timestamps
|
|
6. Optional: wrap as OCI artifact with media type `application/vnd.stella.symbols.manifest.v1+json`.
|
|
|
|
## 2. Validation checklist
|
|
- [ ] `manifest.json` hashes to `manifest.json.sha256`.
|
|
- [ ] Each file hash matches manifest entry.
|
|
- [ ] Build-id path structure is correct (ELF `.build-id/aa/<rest>.debug`).
|
|
- [ ] Tenant in manifest matches upload tenant.
|
|
- [ ] Tarball ordering is lexicographic and mtimes are zeroed.
|
|
|
|
## 3. Ingestion (API)
|
|
- POST the tar/OCI blob to `/api/v1/symbols/ingest` with header `X-Stella-Tenant`.
|
|
- Server recomputes digests; rejects mismatches or tenant mismatch.
|
|
- Optional DSSE attestation digest recorded in manifest for downstream verification.
|
|
|
|
## 4. Reachability integration
|
|
- Scanner attaches `build_id` and source image digest to reachability edges; Graph API can fetch symbol manifests to render function names in overlays.
|
|
- When symbols are missing, UI shows “symbol lookup unavailable” badge; import the matching manifest to enable function-level overlays.
|
|
|
|
## 5. Offline kits
|
|
- Place `symbols/` directory (manifest + files) at the kit root; include tarball and manifest digest.
|
|
- `debug-manifest.json` in Offline Kit should link to symbol manifest for cross-reference.
|
|
|
|
## 6. Tenant controls & audit
|
|
- Symbol server enforces tenant; exports are tagged with tenant in manifest and tar annotations.
|
|
- Emit Timeline events on ingest with bundle digest and tenant; attach DSSE attestation if present.
|