Repository / docs/TRUST.md
Independent verification
TgWitness / Documentation · Evidence and verification
Check the exact file you received against its public workflow and source commit. GitHub's hosted runners, OIDC and Sigstore supply the provenance records; your verification policy picks the workflow and code revisions you trust.
For a Telegram archive, start with sealed evidence, or the signed journal guide for a local workspace. For a TgWitness release, follow the source-archive steps below.
Release source archive#
Get a recent GitHub CLI. From the
release download TgWitness-<ver>.zip, .zip.sha256, sbom.spdx.json,
provenance.sigstore.json and sbom.sigstore.json. The ZIP is built by
tools/build_source.py on GitHub-hosted Ubuntu (it's separate from the older
*-source.zip asset).
Pick the full commit SHA you reviewed, look at .github/workflows/provenance.yml, its
pinned actions and tools/build_source.py at that commit. Don't take the SHA from an
untrusted archive and don't assume tags never move. Then:
VERSION='<ver>'
COMMIT='<reviewed-release-commit>'
gh attestation verify "TgWitness-${VERSION}.zip" \
--repo phishdestroy/TgWitness \
--signer-workflow phishdestroy/TgWitness/.github/workflows/provenance.yml \
--signer-digest "$COMMIT" --source-digest "$COMMIT" \
--source-ref "refs/tags/v${VERSION}" --deny-self-hosted-runners
This checks the file digest, the SLSA provenance signature, repository, workflow
revision, source commit/ref and that a hosted runner built it. A checksum alone says
nothing about who built the file. Run it again on .zip.sha256. For saved bundles add
--bundle provenance.sigstore.json; for offline checks fetch trusted roots beforehand.
Commits were squashed on 3 November 2026. Tags now point to commits with the same
files, but attestations of earlier releases name the original commits, which are still
reachable on GitHub. Use these as COMMIT:
| Release | Attested commit |
|---|---|
| 0.8.1 | 5ad1569e0b5bc8fce6920b5439eb3e35418a2193 |
| 0.8.0 | 204e31bd294534574a9ef9428f24a38c81b57e6b |
| 0.7.1 | 99225f985701b0cdccb333d947c6bb9bad8673aa |
Rebuilding the source ZIP#
python tools/build_source.py sorts entries and fixes timestamps, permissions and
compression, so the same input bytes and Python/zlib give the same ZIP. The 1980
timestamp is just a neutral value. To compare with a hosted ZIP, build from the reviewed
commit in a clean checkout with the same line-ending settings and toolchain, then compare
SHA-256. Line endings and compressor versions can change the result.
Sealed evidence#
After decrypting the handoff from SEALED-ACTIONS, verify
evidence.zip against your fork (OWNER/TgWitness):
gh attestation verify evidence.zip --bundle attestation.jsonl \
--repo OWNER/TgWitness \
--signer-workflow phishdestroy/TgWitness/.github/workflows/sealed-collector.yml \
--signer-digest c292ca0af97e3a4a0a2edd7f7eb00b21876afb57 \
--deny-self-hosted-runners
Review the pinned collector workflow,
which checks out collector commit f5c131ec4c5aad1b603617aa259a689f641b30dc. The reviewed workflow and
collector pairs are listed in tgwitness/sealed_policy.json; use the
pair that your fork's caller workflow pins.
For journal, attachment, policy and coverage checks also run the verifier from an
installation you trust:
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness
Public records and SBOM#
-
Transparency log. The attestation step's Actions summary links to Rekor; the bundle's
verificationMaterial.tlogEntrieshas the log entry and inclusion proof. Browse it on Sigstore search. A log entry timestamps a commitment, not Telegram messages (Rekor). -
Scorecard. OpenSSF Scorecard report, runs every Monday and on pushes to
main. Look at the date, commit and findings along with the score. -
Workflow audit. workflow-audit.yml runs zizmor on workflow changes and every Monday, results in the
workflow-audit-sarifartifact. -
Dependencies.
sbom.spdx.jsoncombines what Syft finds with the exact Python versions fromdeploy/requirements.lock,deploy/build.lockanddeploy/constraints-mcp.txt. The workflow fails on missing, extra or mismatched packages.Verify the SBOM signature with the release command above (
sbom.spdx.jsonas the file), and its binding to the source ZIP:gh attestation verify "TgWitness-${VERSION}.zip" \ --bundle sbom.sigstore.json \ --predicate-type https://spdx.dev/Document/v2.3 \ --repo phishdestroy/TgWitness \ --signer-workflow phishdestroy/TgWitness/.github/workflows/provenance.yml \ --signer-digest "$COMMIT" --source-digest "$COMMIT" \ --source-ref "refs/tags/v${VERSION}" --deny-self-hosted-runnersThen scan it locally:
grype sbom:sbom.spdx.json
Verification scope#
Release attestation binds the named download and its digest to the recorded build workflow and source revision. Check the attestation supplied for the exact artifact being installed; other package formats have their own publication and verification paths.
The SBOM describes the declared package versions, while a scan evaluates those versions against its vulnerability database. Evidence archives are checked separately with the verification procedure for their collection mode.