TgWitness / Documentation

Repository / docs/TRUST.md

Independent verification

TgWitness / Documentation · Evidence and verification

Evidence & verification

Security policy

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.tlogEntries has 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-sarif artifact.

  • Dependencies. sbom.spdx.json combines what Syft finds with the exact Python versions from deploy/requirements.lock, deploy/build.lock and deploy/constraints-mcp.txt. The workflow fails on missing, extra or mismatched packages.

    Verify the SBOM signature with the release command above (sbom.spdx.json as 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-runners
    

    Then 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.