GitHub Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Integration module provides the necessary mechanisms to verify the provenance of code running within secure enclaves. By interfacing with GitHub's APIs and attestation proxies, the system retrieves release tags, source digests, and Sigstore attestation bundles. This allows the verifier to establish a cryptographic link between the running enclave and a specific version of the source code hosted on GitHub.
This integration is a critical component of the Remote Attestation flow, as it provides the "source" measurements used to validate the "runtime" measurements provided by the enclave hardware.
Sources: README.md:12-21, github/github.go:7-10, examples/verifier/main.go:50-76
Architecture and Data Flow
The GitHub integration relies on a set of proxy services to interact with GitHub resources. These proxies facilitate the retrieval of repository metadata and Sigstore-signed attestations without requiring direct, authenticated access to the GitHub API in all environments.
The flow typically begins by identifying the latest release or a specific tag for a given repository. Once a tag is identified, the system fetches a corresponding digest (hash) for the build artifact. This digest is then used to locate the Sigstore attestation bundle, which contains the proof of code provenance.
Data Retrieval Flow
The following diagram illustrates the sequence of operations used to retrieve code provenance data:
Key Components and Functions
Repository Metadata Retrieval
The integration utilizes the github package to resolve repository states. It primarily interacts with api-github-proxy.tinfoil.sh to avoid direct dependency on GitHub's rate limits or complex auth in restricted environments.
| Function | Description | Source |
|---|---|---|
FetchLatestTag | Retrieves the latest release tag name for a specified repository. | github/github.go:12 |
FetchDigest | Downloads the tinfoil.hash file from a specific release tag to obtain the build digest. | github/github.go:29 |
FetchLatestDigest | A convenience wrapper that orchestrates fetching the latest tag and then its digest. | github/github.go:41 |
Sources: github/github.go:12-51
Sigstore Attestation Retrieval
Once the build digest is known, the verifier must retrieve the cryptographic proof that the digest corresponds to a specific source repository and workflow.
| Function | Description | Source |
|---|---|---|
FetchAttestationBundle | Queries the gh-attestation-proxy.tinfoil.sh using the repository name and SHA256 digest to retrieve the Sigstore bundle. | github/github.go:54 |
Sources: github/github.go:54-72
Implementation Details
Attestation Proxy Integration
The FetchAttestationBundle function constructs a specific URL pattern to query the attestation proxy. The response is expected to contain a list of attestations, each including a bundle field which is a json.RawMessage.
url := "https://gh-attestation-proxy.tinfoil.sh/repos/" + repo + "/attestations/sha256:" + digest
Sources: github/github.go:55, wasm/main.go:42-45
Integration in WASM Environments
In WebAssembly environments, the GitHub integration is exposed via the verifyCode function. This function allows browser-based clients to trigger the full retrieval and verification flow for a specific repository and digest. It uses the util.Get helper, which wraps the native JavaScript fetch API to handle requests.
Sources: wasm/main.go:34-80, util/fetch_wasm.go:11-30
Usage Example (CLI)
The verifier example demonstrates how to use the GitHub package to prepare measurements for comparison against an enclave:
log.With("repo", *repo).Info("Fetching latest release")
digest, err := github.FetchLatestDigest(*repo)
log.With("repo", *repo, "digest", digest).Info("Fetching attestation bundle")
sigstoreBundle, err := github.FetchAttestationBundle(*repo, digest)
log.Info("Verifying source attestation")
codeMeasurements, err = sigstoreClient.VerifyAttestation(sigstoreBundle, digest, *repo)
Sources: examples/verifier/main.go:55-76
Summary
The GitHub Integration module is the bridge between the Tinfoil Verifier and the source code's supply chain. By automating the retrieval of release metadata and Sigstore bundles through specialized proxies, it enables the verifier to perform a comparison between what is physically running in an enclave and the verified build artifacts produced by a trusted GitHub workflow.