{"id":13668714,"url":"https://github.com/spiffe/spiffe-helper","last_synced_at":"2025-04-04T22:05:17.964Z","repository":{"id":25814602,"uuid":"105961346","full_name":"spiffe/spiffe-helper","owner":"spiffe","description":"The SPIFFE Helper is a tool that can be used to retrieve and manage SVIDs on behalf of a workload","archived":false,"fork":false,"pushed_at":"2024-10-18T05:47:27.000Z","size":347,"stargazers_count":45,"open_issues_count":27,"forks_count":40,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-10-18T15:47:09.167Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/spiffe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-06T02:43:58.000Z","updated_at":"2024-10-18T05:11:07.000Z","dependencies_parsed_at":"2023-12-13T00:23:52.575Z","dependency_job_id":"0eb0e776-4a8b-4468-a613-e5ae5495a9fe","html_url":"https://github.com/spiffe/spiffe-helper","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspiffe-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspiffe-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspiffe-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspiffe-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spiffe","download_url":"https://codeload.github.com/spiffe/spiffe-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256110,"owners_count":20909240,"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","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":"2024-08-02T08:00:47.764Z","updated_at":"2025-04-04T22:05:17.946Z","avatar_url":"https://github.com/spiffe.png","language":"Go","funding_links":[],"categories":["Utils","Go"],"sub_categories":["SDK"],"readme":"\u003e # Help improve SPIFFE Helper\n\u003e\n\u003e Fill out this [questionnaire](https://docs.google.com/forms/d/1MwHyAiLXnGuUpymwBCfBJei25lur2jaD-056L5Hp1Js) so we can learn more about your use case.\n\n# SPIFFE Helper\n\nThe SPIFFE Helper is a simple utility for fetching X.509 SVID certificates from the SPIFFE Workload API, launch a process that makes use of the certificates and continuously get new certificates before they expire. The launched process is signaled to reload the certificates when is needed.\n\n## Usage\n`$ spiffe-helper -config \u003cconfig_file\u003e`\n\n`\u003cconfig_file\u003e`: file path to the configuration file.\n\nIf `-config` is not specified, the default value `helper.conf` is assumed. \n\nCLI options:\n\n | Flag name                       | Description                                                         |\n |---------------------------------|---------------------------------------------------------------------|\n | `-config`                       | Path to the configuration file                                      |\n | `-help`                         | Print interactive help                                              |\n | `-daemon-mode={true\\|false}`    | Boolean true or false. Overrides `daemon_mode` in the config file.  |\n\n## Configuration\n\nThe configuration file is an [HCL](https://github.com/hashicorp/hcl) formatted file that defines the following configurations:\n\n | Configuration                 | Description                                                                                                                       | Example Value                                                                                                                                                        |\n |-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n | `agent_address`               | Socket address of SPIRE Agent.                                                                                                    | `\"/tmp/agent.sock\"`                                                                                                                                                  |\n | `cmd`                         | The path to the process to launch and monitor and signal for certificate renewals. Ignored if `daemon_mode=false`                 | `\"ghostunnel\"`                                                                                                                                                       |\n | `cmd_args`                    | The arguments of the process to launch. Split by spaces into an argument vector.                                                  | `\"server --listen localhost:8002 --target localhost:8001--keystore certs/svid_key.pem --cacert certs/svid_bundle.pem --allow-uri-san spiffe://example.org/Database\"` |\n | `pid_file_name`               | Path to a file containing a process ID to signal when certificates are renewed. Not required when using 'cmd'.                    | `\"/var/run/ghostunnel.pid\"`                                                                                                                                          |\n | `cert_dir`                    | Directory name to store the fetched certificates. This directory must be created previously.                                      | `\"certs\"`                                                                                                                                                            |\n | `daemon_mode`                 | Toggle running as a daemon, keeping X.509 and JWT up to date; or just fetch X.509 and JWT and exit 0. Does not background itself. | `true`                                                                                                                                                               |\n | `add_intermediates_to_bundle` | Add intermediate certificates into Bundle file instead of SVID file.                                                              | `true`                                                                                                                                                               |\n | `renew_signal`                | The signal that the process to be launched expects to reload the certificates. It is not supported on Windows.                    | `\"SIGUSR1\"`                                                                                                                                                          |\n | `svid_file_name`              | File name to be used to store the X.509 SVID public certificate in PEM format.                                                    | `\"svid.pem\"`                                                                                                                                                         |\n | `svid_key_file_name`          | File name to be used to store the X.509 SVID private key and public certificate in PEM format.                                    | `\"svid_key.pem\"`                                                                                                                                                     |\n | `svid_bundle_file_name`       | File name to be used to store the X.509 SVID Bundle in PEM format.                                                                | `\"svid_bundle.pem\"`                                                                                                                                                  |\n | `jwt_svids`                   | An array with the audience, optional extra audiences array, and file name to store the JWT SVIDs. File is Base64-encoded string). | `[{jwt_audience=\"your-audience\", jwt_extra_audiences=[\"your-extra-audience-1\", \"your-extra-audience-2\"], jwt_svid_file_name=\"jwt_svid.token\"}]`                      |\n | `jwt_bundle_file_name`        | File name to be used to store JWT Bundle in JSON format.                                                                          | `\"jwt_bundle.json\"`                                                                                                                                                  |\n | `include_federated_domains`   | Include trust domains from federated servers in the CA bundle.                                                                    | `true`                                                                                                                                                               |\n | `cert_file_mode`              | The octal file mode to use when saving the X.509 public certificate file.                                                         | `0644`                                                                                                                                                               |\n | `key_file_mode`               | The octal file mode to use when saving the X.509 private key file.                                                                | `0600`                                                                                                                                                               |\n | `jwt_bundle_file_mode`        | The octal file mode to use when saving a JWT Bundle file.                                                                         | `0600`                                                                                                                                                               |\n | `jwt_svid_file_mode`          | The octal file mode to use when saving a JWT SVID file.                                                                           | `0600`                                                                                                                                                               |\n | `hint`                        | Hint to use to pick the SPIFFE ID.                                                                                                | ``                                                                                                                                                                   |\n\n**Notes**:\n\n* If `cmd` is specified, spiffe-helper will connect its `stdin`, `stdout` and\n  `stderr` to that of the command it invokes. If this is not desired, close\n  these file descriptors before invoking spiffe-helper.\n\n### Health Checks Configuration\n\nSPIFFE Helper can expose and endpoint that can be used for health checking\n\n | Configuration                    | Description                                                                                                          | Example Value |\n |----------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------|\n | `health_checks.listener_enabled` | Whether to start an HTTP server at the configured endpoint for the daemon health. Doesn't apply for non-daemon mode. | `false`       |\n | `health_checks.bind_port`        | The port to run the HTTP health server.                                                                              | `8081`        |\n | `health_checks.liveness_path`    | The URL path for the liveness health check                                                                           | `/live`       |\n | `health_checks.readiness_path`   | The URL path for the readiness health check                                                                          | `/ready`      |\n\n### Operating modes and configuration details\n\nspiffe-helper has two primary operating modes - \"daemon mode\" (the default),\nwhere it runs continuously and manages the certificates, and \"non-daemon mode\",\nwhere it fetches the certificates once and exits.\n\nThe helper can be used in several ways, as detailed below:\n\n* Signal an external process when the certificates are renewed.\n* Run a command that reloads an external process when the certificates are renewed.\n* Run a command that uses the certificates, and signal it when they are renewed\n  (not recommended)\n* Fetch the certificates once and exit.\n\nNote that \"daemon mode\" does not actually detach itself from the controlling\nprocess and background itself like a unix \"daemon\". It just keeps running until\nterminated by a signal or a fatal error.\n\n`spiffe-helper` does not have all the features of a proper process supervisor,\nso it's usually best to let a dedicated process supervisor like systemd manage\nthe process that uses the certificates. Use `spiffe-helper` to fetch and renew\nthe certificates and wake the external process via `cmd` or `pid_file_name`\nwhen the certificates are reloaded.\n\n#### Use in daemon-mode with file watcher\n\nIf the process using the certificates can watch the on-disk files for changes,\nspiffe-helper can be run in `daemon_mode` with no `cmd` or `pid_file_name`. It\nwill fetch and renew the certificates, overwrite them on disk, and the process\nwill pick up the changes.\n\nThis approach is recommended where possible.\n\n#### Use in daemon-mode with `cmd` to run a process or a reload command\n\n`cmd` and `cmd_args` are used in `daemon_mode` to run a command whenever the\ncertificates are renewed. This can be a long-lived process that uses the\ncertificates, or a short-lived command that signals a reload mechanism\nfor an externally-managed process.\n\n:warning: **cmd_args is not parsed according to shell-like rules**. The\n`cmd_args` will be split into individual arguments using space separation\nunless the argument is enclosed in double quotes, which are consumed. Double\nquotes must be backslash escaped in the hcl string. For example:\n\n```hcl\ncmd_args = \"\\\"this is one argument\\\"\"\n```\n\nDouble quotes within the argument string must be escaped by doubling them so\nthey are not interpreted as argument delimiters. E.g.:\n\n```hcl\ncmd_args = \"\\\"this is a single argument with ONE double-quote \\\"\\\" in it\\\"\"\n```\n\nSingle quotes are NOT respected for argument quoting, and do not protect double\nquotes. For example:\n\n```hcl\ncmd = \"sh\"\ncmd_args = \"-c 'echo hello world'\"\n```\n\nwill run `sh` with the argument-vector [\"-c\", \"'echo\", \"hello\", \"world'\"], not\n[\"-c\", \"echo hello world\"], which will fail with `Syntax error: Unterminated\nquoted string`.\n\n`cmd_args` is *not* subject to shell metacharacter expansion or interpretation.\nIf you need to use shell features, you must invoke a shell explicitly, e.g.\n`cmd = \"/bin/sh\"` and `cmd_args = \"-c \\\"echo hello\\\"\"`. Be careful with shell\ninvocations, as they can introduce security vulnerabilities and should be\navoided where possible.\n\nThe command's stdout and stderr will be attached to spiffe-helper's stdout\nand stderr. Its stdin will be closed.\n\nThe process specified by `cmd` and `cmd_args` will not be launched for the\nfirst time until the certificates are fetched successfully.\n\n`spiffe-helper` continues running if the process created by `cmd` exits. The\nprocess is not re-launched immediately if it exits.\n\nIf the process is still running next time the certs are renewed,\n`spiffe-helper` will signal it with `renew_signal`. If it has exited,\n`spiffe-helper` will re-launch it instead. This can be used to manage\ncertificate reloading in externally-managed processes that do not support\nreloading certificates with a signal.\n\n#### Use in daemon-mode with `pid_file_name` to signal an externally-managed process\n\nIf running in `daemon_mode` with `pid_file_name` set, the pid in\n`pid_file_name` is sent the signal `renew_signal` to reload the certificates\nwhen they are renewed.\n\n`pid_file_name` is re-read every time the process is to be signaled, so it can\nbe updated with a new pid if the process changes.\n\nAn error will be logged if the pid file cannot be opened, read, or the value\nparsed, and the attempt to signal the process will be skipped. The process will\nstill be signalled next time the certificates are renewed.\n\n#### Combining `cmd` and `pid_file_name`\n\nBoth `cmd` and `pid_file_name` can be used at the same time. `spiffe-helper` will\nboth run the specified command and signal the process in the pid file. This can be\nuseful to use `cmd` to start the process to be managed, and `pid_file_name` to signal\na reload mechanism that is not signal-based.\n\n#### Use in one-shot non-daemon mode\n\nIf `daemon_mode` is false, `spiffe-helper` will fetch the certificates once and\nexit. This can be useful for one-shot scripts or for use in a process supervisor\nthat does not require a long-lived process.\n\n`cmd` and `pid_file_name` are ignored in non-daemon mode. No command will be\nrun and no signals will be sent. They may be disallowed in future.\n\n`spiffe-helper` cannot be used as a transparent wrapper around another\ncommand because it does not forward stdin, signals, file descriptors, exit\nwhen the child process exits, or return the managed process's exit code as\nits own exit code. Instead, consider running the other process separately,\nunder the control of a proper process supervisor like systemd, and signaling\nit via `pid_file_name`.\n\n:warning: A future release may support running a command and/or signalling an\nexternal process in non-daemon mode, so it is recommended to leave `cmd`,\n`renew_signal` and `pid_file_name` blank if `daemon_mode` is false.\n\n### Configuration example\n```\nagent_address = \"/tmp/spire-agent/public/api.sock\"\ncmd = \"ghostunnel\"\ncmd_args = \"server --listen localhost:8002 --target localhost:8001 --keystore certs/svid_key.pem --cacert certs/svid_bundle.pem --allow-uri-san spiffe://example.org/Database\"\ncert_dir = \"certs\"\nrenew_signal = \"SIGUSR1\"\nsvid_file_name = \"svid.pem\"\nsvid_key_file_name = \"svid_key.pem\"\nsvid_bundle_file_name = \"svid_bundle.pem\"\njwt_svids = [{jwt_audience=\"your-audience\",jwt_extra_audiences=[\"your-extra-audience-1\", \"your-extra-audience-2\"], jwt_svid_file_name=\"jwt_svid.token\"}]\njwt_bundle_file_name = \"bundle.json\"\ncert_file_mode = 0444\nkey_file_mode = 0444\njwt_bundle_file_mode = 0444\njwt_svid_file_mode = 0444\n```\n\n### Windows example\n```\nagent_address = \"spire-agent\\\\public\\\\api\"\ncert_dir = \"certs\"\nsvid_file_name = \"svid.pem\"\nsvid_key_file_name = \"svid_key.pem\"\nsvid_bundle_file_name = \"svid_bundle.pem\"\njwt_svids = [{jwt_audience=\"your-audience\",jwt_extra_audiences=[\"your-extra-audience-1\", \"your-extra-audience-2\"], jwt_svid_file_name=\"jwt_svid.token\"}]\njwt_bundle_file_name = \"bundle.json\"\n```\n\n## Development and testing\n\nThis is a pretty straightforward Go project. You can use the standard Go tools\nto build and test it.\n\nPlease run the tests for Windows for your PRs. `wine` is sufficient if you\ndon't have a convenient Windows machine or VM, and you don't need the Windows\nGo SDK to cross-compile the test suite and run it. Install `wine` with\n`sudo apt-get install wine` or similar, then run the tests with `make test-wine`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Fspiffe-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspiffe%2Fspiffe-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Fspiffe-helper/lists"}