{"id":19142298,"url":"https://github.com/martinbaillie/vaultsign","last_synced_at":"2025-07-29T12:11:22.569Z","repository":{"id":38022477,"uuid":"300814624","full_name":"martinbaillie/vaultsign","owner":"martinbaillie","description":"Sign/verify git commits using HashiCorp Vault.","archived":false,"fork":false,"pushed_at":"2023-03-11T14:06:42.000Z","size":54,"stargazers_count":27,"open_issues_count":12,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-06T23:50:02.406Z","etag":null,"topics":["git","gpg","hashicorp","supplychain","vault"],"latest_commit_sha":null,"homepage":"https://martin.baillie.id/wrote/git-signature-operations-via-hashicorp-vault/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martinbaillie.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-10-03T06:41:34.000Z","updated_at":"2025-05-01T14:45:21.000Z","dependencies_parsed_at":"2024-11-09T07:40:06.119Z","dependency_job_id":null,"html_url":"https://github.com/martinbaillie/vaultsign","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/martinbaillie/vaultsign","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinbaillie%2Fvaultsign","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinbaillie%2Fvaultsign/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinbaillie%2Fvaultsign/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinbaillie%2Fvaultsign/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martinbaillie","download_url":"https://codeload.github.com/martinbaillie/vaultsign/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinbaillie%2Fvaultsign/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267684823,"owners_count":24127697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["git","gpg","hashicorp","supplychain","vault"],"created_at":"2024-11-09T07:26:45.577Z","updated_at":"2025-07-29T12:11:22.479Z","avatar_url":"https://github.com/martinbaillie.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"* vaultsign [[https://github.com/martinbaillie/vaultsign/actions?query=workflow%3Atests][https://github.com/martinbaillie/vaultsign/workflows/tests/badge.svg]] :TOC_2:noexport:\n- [[#about][About]]\n  - [[#how][How?]]\n  - [[#why][Why?]]\n- [[#usage][Usage]]\n  - [[#example][Example]]\n- [[#install][Install]]\n  - [[#download][Download]]\n  - [[#build][Build]]\n- [[#github-verification][GitHub Verification]]\n\n* About\n=vaultsign= is a small CLI that can be used to sign (and verify) =git= commits\nand tags using HashiCorp's [[https://www.vaultproject.io/][Vault]].\n\nIt works both with the out-of-the-box [[https://www.vaultproject.io/docs/secrets/transit][transit backend]] and LeSuisse's [[https://github.com/LeSuisse/vault-gpg-plugin][GPG plugin]].\n#+BEGIN_QUOTE\nNOTE: You will want the latter for those GitHub :heavy_check_mark: verified [[#github-verification][feels]].\n#+END_QUOTE\n\n** How?\n=vaultsign= implements just enough of the GPG CLI interface and status protocol\nto proxy the =git= originating sign and verify requests onwards to your\nspecified Vault backend endpoint.\n\n** Why?\nVault's signature related backends are useful for realising code provenance in\nregulated and other high security environments.\n\nYou might, for example, build and sign software binaries using CI and Vault\ninfrastructure you control, then store them in an artefact repository (such as\nGitHub's Releases), and later verify those binaries again with Vault during\ndeployment to cryptographically prove they were built on your terms without\ntampering.\n\nThis works well for deployable artefacts like binaries but gets a little more\nawkward when some of related deployment collateral is say, IaC files (such as\nTerraform) living on a VCS branch or tag.\n\nOne option here is to tarball up this deployment collateral and\nsign/store/verify that.\n\nAnother is to make use of =vaultsign=.\n\nWith it, the CI process can sign a =git= commit or, more commonly, a release tag\nat the same time as it signs the just-cut binaries. Subsequently, they can all\nbe verified together during a deployment.\n\nDoing all of this in your CI/CD infrastructure with Vault removes much of the\nneed to deal with individual employee GPG keys or X.509 certificates (for\nS/Mime) to achieve code provenance at the VCS level.\n\n* Usage\nThere is a built-in help that you may find useful:\n#+BEGIN_SRC shell :exports both :results verbatim replace\nvaultsign --help\n#+END_SRC\n\n#+RESULTS:\n#+begin_example\nvaultsign 1.0.0\nMartin Baillie \u003cmartin@baillie.email\u003e\nSign/verify git commits using HashiCorp Vault.\n\nUSAGE:\n    vaultsign [FLAGS] [OPTIONS] \u003c--sign|--verify\u003e [FILE]...\n\nFLAGS:\n    -a, --armor          Create ASCII armored output\n    -b, --detach-sign    Make a detached signature\n    -h, --help           Prints help information\n    -s, --sign           Make a signature\n    -V, --version        Prints version information\n    -v, --verify         Verify a signature\n\nOPTIONS:\n        --keyid-format \u003ckeyid_format\u003e           Select how to display key IDs [possible values: long]\n    -u, --local-user \u003clocal_user\u003e               USER-ID to sign or decrypt\n        --status-fd \u003cstatus_fd\u003e                 Write special status strings to the file descriptor n. [possible values:\n                                                1, 2]\n        --vault_addr \u003cvault_addr\u003e               Vault address to use for sign and verify actions [env: VAULT_ADDR]\n                                                [default: http://127.0.0.1:8200]\n        --vault_sign_path \u003cvault_sig_path\u003e      The Vault path to use for sign actions [env: VAULT_SIGN_PATH]  [default:\n                                                transit/sign/test/sha2-256]\n        --vault_verify_path \u003cvault_ver_path\u003e    The Vault path to use for verify actions [env: VAULT_VERIFY_PATH]\n                                                [default: transit/verify/test]\n\nARGS:\n    \u003cFILE\u003e...\n\nNOTE:\n    The vaultsign CLI implements just enough of the full GPG CLI interface\n    for happy-path git sign and verify operations to function correctly.\n#+end_example\n\nMostly, though, you just need to tell your =git= CLI to use =vaultsign=:\n#+BEGIN_SRC shell\ngit config --local gpg.program /path/to/vaultsign\n#+END_SRC\n\nAnd set some Vault related environment variables:\n#+BEGIN_SRC shell\n# The location of your Vault. Mandatory always.\nexport VAULT_ADDR=https://vault.your.corp:8200\n\n# The signing backend endpoint (transit or gpg) and optionally hashing function\n# to use. Mandatory for signing.\nexport VAULT_SIGN_PATH=transit/sign/test/sha2-256\nexport VAULT_SIGN_PATH=gpg/sign/test/sha2-256\n\n# The verify backend endpoint (transit or gpg). Mandatory for verifying.\nexport VAULT_VERIFY_PATH=transit/verify/test\nexport VAULT_VERIFY_PATH=gpg/verify/test\n\n# The SNI to present during the TLS handshake (if different from the Vault HTTP\n# host name). Useful when your Vault is exposed through an AWS private link for\n# example. Optional.\nexport VAULT_TLS_SERVER_NAME=hostname.to.use.for.sni.com\n#+END_SRC\n\n#+BEGIN_QUOTE\nNOTE: =vaultsign= will discover an existing Vault token from either the\nenvironment or the home directory using HashiCorp's established naming\n(=VAULT_TOKEN=) and path (=~/.vault-token=). The environment takes precedence\nhere.\n#+END_QUOTE\n\n** Example\n#+BEGIN_SRC shell\n# Login to your vault.\nexport VAULT_ADDR=http://127.0.0.1:8200\nvault login\n\n# Tell git to use vaultsign.\ngit config --local gpg.program /path/to/vaultsign\n\n# Sign a commit and tag.\nexport VAULT_SIGN_PATH=transit/sign/test/sha2-256\ngit commit -m \"test signed commit\" -S\ngit tag -m \"test signed tag\" -s test\n\n# Verify the same commit and tag.\nexport VAULT_VERIFY_PATH=transit/verify/test\ngit verify-commit HEAD\ngit log -1 --show-signature\ngit verify-tag test\n#+END_SRC\n\n* Install\nYou can either download a signed static binary release or compile from source for your target\narchitecture.\n** Download\nAlways download and verify the latest stable release from the GitHub [[https://github.com/martinbaillie/vaultsign/releases/][releases]]\nsection.\n*** Verify\n#+BEGIN_SRC shell\n# Import my key.\ncurl -sS https://github.com/martinbaillie.gpg | gpg --import -\n\n# Verify the authenticity.\ngpg --verify SHA256SUMS.sig SHA256SUMS\n\n# Verify the integrity.\nshasum -a 256 -c SHA256SUMS\n#+END_SRC\n** Build\nIf you are a [[https://nixos.org/][Nix]] user then you can take advantage of the [[shell.nix][shell.nix]] to provide\na functional development environment for compilation and tests.\n#+BEGIN_SRC shell\nnix-shell --pure --run \"make release\"\n#+END_SRC\n\nOtherwise, any sufficiently modern Rust toolchain should be able to compile =vaultsign=.\n\n#+BEGIN_QUOTE\nNOTE: regarding OpenSSL.\n\nIf you are compiling from source, =vaultsign= links against your system's native OpenSSL distribution. Ensure you have the dependencies listed in [[shell.nix][shell.nix]].\n\nIf you are using the pre-compiled Darwin version from the [[https://github.com/martinbaillie/vaultsign/releases/][releases]] section then it is not static so ensure you have OpenSSL version 1.1 installed.\n#+END_QUOTE\n* GitHub Verification\nIf you want that coveted GitHub green verified tick for your Vault-signed\ncommits and tags then you must use LeSuisse's [[https://github.com/LeSuisse/vault-gpg-plugin][GPG plugin]] in Vault. GitHub does\nnot know how to verify Vault transit backend signatures.\n\nWith that done, you just have to ensure the GPG key email and VCS author email\nmatch, i.e.:\n- GPG Private key generated/imported in Vault has a real name and email (see\n  [[https://github.com/LeSuisse/vault-gpg-plugin/blob/master/docs/http-api.md#create-key][here]]).\n- GPG Public key is added to the GitHub user doing the VCS operation, with those\n  same details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinbaillie%2Fvaultsign","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartinbaillie%2Fvaultsign","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinbaillie%2Fvaultsign/lists"}