{"id":36892354,"url":"https://github.com/transparency-dev/armored-witness","last_synced_at":"2026-01-12T15:38:39.514Z","repository":{"id":189161110,"uuid":"680159407","full_name":"transparency-dev/armored-witness","owner":"transparency-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-15T14:44:38.000Z","size":875,"stargazers_count":29,"open_issues_count":3,"forks_count":11,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-12-18T18:52:30.746Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transparency-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-18T13:37:35.000Z","updated_at":"2025-12-15T14:49:23.000Z","dependencies_parsed_at":"2023-12-19T02:48:54.136Z","dependency_job_id":"939a645b-1b6a-43fd-8460-34876adf978c","html_url":"https://github.com/transparency-dev/armored-witness","commit_stats":null,"previous_names":["transparency-dev/armored-witness"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/transparency-dev/armored-witness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transparency-dev%2Farmored-witness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transparency-dev%2Farmored-witness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transparency-dev%2Farmored-witness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transparency-dev%2Farmored-witness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transparency-dev","download_url":"https://codeload.github.com/transparency-dev/armored-witness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transparency-dev%2Farmored-witness/sbom","scorecard":{"id":978971,"data":{"date":"2024-08-24T06:26:26Z","repo":{"name":"github.com/transparency-dev/armored-witness","commit":"d7c18350f3785502dd6476e666f1bb3c457936af"},"scorecard":{"version":"v5.0.0","commit":"ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4"},"score":7.8,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#binary-artifacts"}},{"name":"Branch-Protection","score":4,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Info: 'branch protection settings apply to administrators' is required to merge on branch 'main'","Warn: 'stale review dismissal' is disable on branch 'main'","Warn: required approving review count is 1 on branch 'main'","Warn: codeowners review is not required on branch 'main'","Warn: 'last push approval' is disable on branch 'main'","Warn: 'up-to-date branches' is disable on branch 'main'","Info: status check found to merge onto on branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#branch-protection"}},{"name":"CI-Tests","score":10,"reason":"30 out of 30 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#ci-tests"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#cii-best-practices"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#code-review"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: google contributor org/company found, "],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#contributors"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dangerous-workflow"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dependency-update-tool"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#license"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":6,"reason":"dependency not pinned by hash detected -- score normalized to 6","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/transparency-dev/armored-witness/codeql.yml/main?enable=pin","Warn: containerImage not pinned by hash: cmd/verify_build/Dockerfile:6","Warn: containerImage not pinned by hash: cmd/verify_build/Dockerfile:29: pin your Docker image by updating ubuntu:22.04 to ubuntu:22.04@sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658","Info:  11 out of  12 GitHub-owned GitHubAction dependencies pinned","Info:   3 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   2 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":10,"reason":"SAST tool is run on all commits","details":["Info: SAST configuration detected: CodeQL","Info: all commits (30) are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#sast"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#signed-releases"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:31","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:32","Info: topLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:24","Info: topLevel 'contents' permission set to 'read': .github/workflows/go_test.yml:4","Info: topLevel 'contents' permission set to 'read': .github/workflows/golangci-lint.yml:6","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:18","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#token-permissions"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-27T19:55:07.432Z","repository_id":189161110,"created_at":"2025-08-27T19:55:07.433Z","updated_at":"2025-08-27T19:55:07.433Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28341136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T15:38:39.447Z","updated_at":"2026-01-12T15:38:39.501Z","avatar_url":"https://github.com/transparency-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ArmoredWitness\n\nThe ArmoredWitness project is intended to kick-start a cross-ecosystem witness network, providing split-view attack prevention to a growing set of transparency-enabled ecosystems.\n\n## Background\n\nTransparency systems work by ensuring that all actors in a given ecosystem see the same append-only list of data, typically stored in [verifiable logs](https://transparency.dev/verifiable-data-structures/). This allows folks relying on this data to be confident that even if they are unable to determine the correctness of the data themselves, it is visible to others who _can_ verify it and call out badness.\n\nIf a malicious log is able to present inconsistent views of itself to different roles, then such badness can go undetected.\n\nWitnessing is a solution to this \"split-view\" attack: well-known identities verify the append-only property of a given log, countersigning only those checkpoints (commitments to the state of a log) that were verified to be consistent with all earlier checkpoints the witness has seen. These counter-signed checkpoints are made available, enabling 3rd parties to be sure that transparency logs are not targetting them with a split-view.\n\nA deeper dive into witnessing is provided in the [Think local, act global: Gossip and Client Audits in Verifiable Data Structures](https://arxiv.org/pdf/2011.04551.pdf) paper.\n\n## Goals\n\nBy building these devices, and asking a number of folks around the world to be _custodians_ of them, we aim to:\n\n* **Help transparency-enabled ecosystems further tighten their security properties.** \\\nBy providing a lightweight network which is compatible with ecosystems using a [common checkpoint format](https://github.com/transparency-dev/formats/tree/main/log), we can help reduce the trust being placed in log operators.  \\\nExisting compatible ecosystems include: Go's sum DB, Sigstore, Pixel Binary Transparency, LVFS, SigSum, ArmoryDrive.\n* **Ensure the ArmoredWitness device is as low-touch and maintenance-free as possible.** \\\nWe don't want to ask anyone to be a full-time system administrator for these devices, they should be as \"plug-in and go\" as possible.\n* **Bootstrap a diverse witnessing ecosystem** \\\nEncourage others to participate, learn with us, and potentially even go on to develop their own witness protocols and networks, ideally in such a way that interoperability remains possible and enables greater diversification of reputational trust.\n* **Show how to apply firmware transparency** \\\nAll of the firmware running on the device is logged in publicly auditable transparency logs; all tooling\n(including the [provisioning](cmd/provision), on-device self-update, [build-reproducibility verifier](cmd/verify_build/), and the end-user [device integrity checking tool](cmd/verify)) integrate with the transparency log to ensure everything is discoverable and auditable. See the [Transparency](#transparency) section below.\n\n## Device\n\nThe ArmoredWitness device is a small networked device based on the [USB armory](https://github.com/usbarmory/usbarmory/wiki), adding an RJ45 LAN port which supports PoE, and running an open-source implementation of a witness configured to support a growing number of transparency-enabled ecosystems.\nWe're making a small number of these devices, and plan to distribute them to folks who are passionate about one or more of the witnessed ecosystems.\nOnce provisioned, the ArmoredWitness devices will only run the ArmoredWitness firmware, so will not be repurposable for other use cases.\n\n![alt_text](images/armored-witness-render.png \"ArmoredWitness case render\")\n\nLike the USB armory, the new device is an opensource hardware design too, more info is available [here](https://github.com/usbarmory/usbarmory/wiki/Mk-II-LAN).\n\nThe hardware provides a number of interesting security features which we use in the design:\n\n* Bus encryption engine: provides on-the-fly encryption of DRAM contents,\n* Cryptographic accelerator and assurance module: hardware support for encryption and hashing, PRNG, etc.,\n* Replay protected memory block: replay protected, authenticated non-volatile storage,\n* High Assurance Boot: \"Secure Boot\", allows the SoC to cryptographically authenticate the bootloader,\n\n## Software\n\nThe firmware for the ArmoredWitness is all written in Go, and compiled with [TamaGo](https://github.com/usbarmory/tamago) into a bare-metal executable. This enables us to take advantage of Go's memory safety and excellent standard library, and avoid needing to take a dependency on any traditional generic bootloader/kernel/OS combinations, considerably reducing the surface area of the codebase.\n\nThere are 3 main parts to the ArmoredWitness firmware stack:\n\n* [Bootloader](https://github.com/transparency-dev/armored-witness-boot) \\\nA very simple TamaGo unikernel which loads the OS from MMC, verifies it, and finally boots it.\n* [Trusted OS](https://github.com/transparency-dev/armored-witness-os) \\\nThe OS is a TamaGo unikernel which is primarily concerned with:\n  * Managing the device hardware (Ethernet, storage, LEDs, etc.),\n  * Loading and verifying the Applet from MMC, and executing it inside a TEE,\n  * Providing an RPC-like syscall interface to the Applet.\n* [Witness Applet](https://github.com/transparency-dev/armored-witness-applet)  \\\nThe Trusted Applet is where the witness itself lives. \\\nIn addition to running the witness code, the applet also handles the TCP/IP side of networking (using RPC to send/receive packets).\n\nAlong with other ancillary parts:\n\n* Tooling \\\nThis repo contains some tooling to help provision the factory-fresh devices into ArmoredWitness devices.\n* Recovery Image \\\n\u003chttps://github.com/usbarmory/armory-ums\u003e\n\n### Build and release\n\nEach of the four firmware components listed above are built and released by a staticly-configured pipeline, and ultimately make their way into a public Firmware Transparency log.\n\nThe [deployment/build_and_release](deployment/build_and_release) directory contains Terraform configs to define Cloud Build triggers which build and release the firmware and recovery image.\n\nThe CI workflow triggers on every commit:\n\n 1. Every commit to `main` that changes the firmware will cause a new build of the OS and/or Applet firmware\n 1. These builds are committed to in the [CI Log](https://api.transparency.dev/armored-witness-firmware/ci/log/4/) ([checkpoint](https://api.transparency.dev/armored-witness-firmware/ci/log/4/checkpoint))\n   - The log only contains the metadata, the actual firmware will be uploaded the the [CI FW CAS](https://api.transparency.dev/armored-witness-firmware/ci/artefacts/4/)\n 1. Provisioned CI Armored Witness devices will automatically update themselves based on this log being updated\n\nThe prod workflow is separate, but very similar in approach:\n\n 1. Builds are triggered when a new release tag is added to the repo, this causes a new OS and/or Applet firmware image to be built, but the build is configured to embed production public keys, log metadata, etc.\n 1. Metadata about prod builds are committed-to in the [Prod Log](https://api.transparency.dev/armored-witness-firmware/prod/log/1/) ([checkpoint](https://api.transparency.dev/armored-witness-firmware/prod/log/1/checkpoint)), with the firmware itself hosted in the [Prod FW CAS](https://api.transparency.dev/armored-witness-firmware/prod/artefacts/1/)\n 1. Provisioned production Armored Witness devices automatically update themselves based on new entries appearing in the production FT log\n\n### Transparency\n\nGiven how important the role of witnessing is to the security properties of transparency-enabled ecosystem, it's also important that the operation of the witnesses, and therefore the software running on the devices, is as open to inspection and verification as possible.\n\nWe have embodied this principle into the design of the ArmoredWitness firmware and tooling:\n\n* All firmware is opensource, written in TamaGo, and is build-reproducible from source.\n* All firmware is logged to a Firmware Transparency (FT) log at build and release time, powered by [GCP serverless functions](https://github.com/transparency-dev/serverless-log/tree/main/experimental/gcp-log).\n* The [`provision`](cmd/provision/) tool will only use firmware artefacts discovered in the FT log in order to program devices.\n* The on-device self-update process requires that updated firmware is hosted in the FT log.\n* The boot \"chain of trust\" requires valid \"off-line FT proof bundles\" to be present alongside the firmware at boot time:\n  * The bootloader verifies signatures and FT proofs for the secure monitor (\"OS\"), and only launches it if they succeed.\n  * The secure monitor (\"OS\") verifies signatures and FT proofs for the witness applet, and only launches it if they succeed.\n* The [`verify`](cmd/verify) tool can be used to inspect the device, extract the firmware components from it, and verify that they are present in the FT log.\n* The [`verify_build`](cmd/verify_build) command continuously monitors the contents of the FT log, and tests that every logged firmware is indeed reproducibly built.\n\nMore detail is available in the [docs/transparency.md](/docs/transparency.md) page.\n\n### Claimant Model\n\n| Role         | Description |\n| -----------  | ----------- |\n| **Claimant** | Transparency.dev team |\n| **Claim**    | \u003col\u003e\u003cli\u003eThe digest of the firmware or tool is derived from the source Github repositories ([bootloader](https://github.com/transparency-dev/armored-witness-boot), [Trusted OS](https://github.com/transparency-dev/armored-witness-os), [Witness Applet](https://github.com/transparency-dev/armored-witness-applet), [recovery](https://github.com/transparency-dev/armored-witness-boot/tree/main/recovery)), and is reproducible.\u003c/li\u003e\u003cli\u003eThe firmware is issued by the Transparency.dev team.\u003c/li\u003e\u003c/ol\u003e |\n| **Believer** | The [provision](https://github.com/transparency-dev/armored-witness/tree/main/cmd/provision) and [verify](https://github.com/transparency-dev/armored-witness/tree/main/cmd/verify) tools. |\n| **Verifier** | \u003col\u003e\u003cli\u003eFor Claim #1: third party auditing the Transparency.dev team\u003c/li\u003e\u003cli\u003eFor Claim #2: the Transparency.dev team\u003c/li\u003e\u003c/ol\u003e |\n| **Arbiter**  | Log ecosystem participants and reliers |\n\nThe **Statement** is defined in\n[https://github.com/transparency-dev/armored-witness-common/tree/main/release/firmware/ftlog/log_entries.go](https://github.com/transparency-dev/armored-witness-common/tree/main/release/firmware/ftlog/log_entries.go).\nAn example is available at\n[https://github.com/transparency-dev/armored-witness-common/tree/main/release/firmware/ftlog//example_firmware_release.json](https://github.com/transparency-dev/armored-witness-common/tree/main/release/firmware/ftlog//example_firmware_release.json).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransparency-dev%2Farmored-witness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransparency-dev%2Farmored-witness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransparency-dev%2Farmored-witness/lists"}