{"id":19963675,"url":"https://github.com/cyberark/summon","last_synced_at":"2025-05-13T23:05:35.193Z","repository":{"id":31997957,"uuid":"35568823","full_name":"cyberark/summon","owner":"cyberark","description":"CLI that provides on-demand secrets access for common DevOps tools","archived":false,"fork":false,"pushed_at":"2025-04-01T20:01:16.000Z","size":1507,"stargazers_count":724,"open_issues_count":10,"forks_count":64,"subscribers_count":39,"default_branch":"main","last_synced_at":"2025-04-10T12:40:32.848Z","etag":null,"topics":["command-line-tool","conjbot-notify","conjur-community-team","golang","secret-distribution","summon"],"latest_commit_sha":null,"homepage":"https://cyberark.github.io/summon","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyberark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-13T19:05:03.000Z","updated_at":"2025-04-04T16:47:43.000Z","dependencies_parsed_at":"2024-08-16T20:28:02.062Z","dependency_job_id":"ab18b09f-f4dd-4648-9b29-8dd1fb8af4f7","html_url":"https://github.com/cyberark/summon","commit_stats":{"total_commits":322,"total_committers":38,"mean_commits":8.473684210526315,"dds":0.6273291925465838,"last_synced_commit":"585c066d88a9ce65dabf9467a03db206d859e010"},"previous_names":["conjurinc/cauldron","conjurinc/summon"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fsummon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fsummon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fsummon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberark%2Fsummon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyberark","download_url":"https://codeload.github.com/cyberark/summon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254040697,"owners_count":22004594,"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":["command-line-tool","conjbot-notify","conjur-community-team","golang","secret-distribution","summon"],"created_at":"2024-11-13T02:16:45.974Z","updated_at":"2025-05-13T23:05:30.166Z","avatar_url":"https://github.com/cyberark.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# summon\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://cyberark.github.io/summon\"\u003e\n    \u003cimg src=\"https://cyberark.github.io/summon/images/logo.png\" height=\"200\"/\u003e\u003cbr\u003e\n    cyberark.github.io/summon\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![GitHub release](https://img.shields.io/github/release/cyberark/summon.svg)](https://github.com/cyberark/summon/releases/latest)\n\n[![Github commits (since latest release)](https://img.shields.io/github/commits-since/cyberark/summon/latest.svg)](https://github.com/cyberark/summon/commits/main)\n\n---\n\n`summon` is a command-line tool to make working with secrets easier.\n\nIt provides an interface for\n\n* Reading a `secrets.yml` file\n* Fetching secrets from a trusted store\n* Exporting secret values to a sub-process environment\n\n## Install\n\nNote installing `summon` alone is not sufficient; you need to also install\na [provider of your choice](http://cyberark.github.io/summon/#providers) before it's ready for use.\n\nPre-built binaries and packages are available from GitHub releases\n[here](https://github.com/cyberark/summon/releases).\n\n### Using Summon with Conjur Open Source \n\nAre you using this project with [Conjur Open Source](https://github.com/cyberark/conjur)? Then we \n**strongly** recommend choosing the version of this project to use from the latest [Conjur OSS \nsuite release](https://docs.conjur.org/Latest/en/Content/Overview/Conjur-OSS-Suite-Overview.html). \nConjur maintainers perform additional testing on the suite release versions to ensure \ncompatibility. When possible, upgrade your Conjur version to match the \n[latest suite release](https://docs.conjur.org/Latest/en/Content/ReleaseNotes/ConjurOSS-suite-RN.htm); \nwhen using integrations, choose the latest suite release that matches your Conjur version. For any \nquestions, please contact us on [Discourse](https://discuss.cyberarkcommons.org/c/conjur/5).\n\n### Homebrew\n\n```\nbrew tap cyberark/tools\nbrew install summon\n```\n\n### Linux (Debian and Red Hat flavors)\n\n`deb` and `rpm` files are attached to new releases.\nThese can be installed with `dpkg -i summon_v*.deb` and\n`rpm -ivh summon_v*.rpm`, respectively.\n\n### Auto Install\n\n**Note** Check the\n[release notes](https://github.com/cyberark/summon/releases) and select an\nappropriate release to ensure support for your version of Conjur.\n\nUse the auto-install script. This will install the latest version of summon.\nThe script requires sudo to place summon in `/usr/local/bin`.\n\n```\ncurl -sSL https://raw.githubusercontent.com/cyberark/summon/main/install.sh | bash\n```\n\n### Manual Install\nOtherwise, download the [latest release](https://github.com/cyberark/summon/releases) and extract it to `/usr/local/bin/summon`.\n\n## Usage\n\nBy default, summon will look for `secrets.yml` in the directory it is\ncalled from and export the secret values to the environment of the command it wraps.\n\n*Example*\n\nYou want to run a script that requires AWS keys to list your EC2 instances.\n\nDefine your keys in a `secrets.yml` file\n\n```yml\nAWS_ACCESS_KEY_ID: !var aws/iam/user/robot/access_key_id\nAWS_SECRET_ACCESS_KEY: !var aws/iam/user/robot/secret_access_key\n```\n\nThe script uses the Python library [boto](https://pypi.python.org/pypi/boto), which looks for `AWS_ACCESS_KEY_ID`\nand `AWS_SECRET_ACCESS_KEY` in the environment.\n\n```python\nimport boto\nbotoEC2 = boto.connect_ec2()\nprint(botoEC2.get_all_instances())\n```\n\nWrap the Python script in summon:\n\n```\nsummon python listEC2.py\n```\n\n`python listEC2.py` is the command that summon wraps. Once the Python program exits,\nthe secrets stored in temp files and in the Python process environment are gone.\n\n### `secrets.yml` Flags\n\nCurrently, you can define how the value of a variable will be processed using YAML tags. Multiple\ntags can be defined per variable by spearating them with `:`. By default, values are resolved\nas literal values.\n- `!file`: Resolves the variable value, places it into a tempfile, and returns the path to that\nfile.\n- `!var`: Resolves the value as a variable ID from the provider.\n- `!str`: Resolves the value as a literal (default).\n- `!default='\u003cvalue\u003e'`: If the value resolution returns an empty string, use this literal value\ninstead for it.\n\n**Examples**\n```yaml\n# Resolved summon-env string (eg. `production/sentry/api_key`) is sent to the provider\n# and the value returned is saved in the variable.\nAPI_KEY: !var $env/sentry/api_key\n\n# Resolved summon-env string (eg. `production/aws/ec2/private_key`) is sent to the provider.\n# The returned value is put into a tempfile and the path for that file is saved in the\n# variable.\nAPI_KEY_PATH: !file:var $env/aws/ec2/private_key\n\n# Literal value `my content` is saved into a tempfile and the path for that file is saved\n# in the variable.\nSECRET_DATA: !file my content\n\n# Resolved summon-env string (eg. `production/sentry/api_user`) is sent to the provider.\n# The returned value is put into a tempfile. If the value from the provider is an empty\n# string then the default value (`admin`) is put into that tempfile. The path to that\n# tempfile is saved in the variable.\nAPI_USER: !var:default='admin':file $env/sentry/api_user\n```\n\n### Default values\n\nDefault values can be set by using the `default='yourdefaultvalue'` as an addtional tag on the variable:\n```yaml\nVARIABLE_WITH_DEFAULT: !var:default='defaultvalue' path/to/variable\n```\n\n### Flags\n\n`summon` supports a number of flags.\n\n* `-p, --provider \u003cpath-to-provider\u003e` specify the path to the\n[provider](provider/README.md) summon should use.\n\n    If you do not provide Summon with the full path to the provider, Summon will look for providers in the following order:\n    * Environment Variable: `SUMMON_PROVIDER_PATH`\n    * `/usr/local/lib/summon` on Linux / Mac\n    * `%ProgramW6432%\\Cyberark Conjur\\Summon\\Providers` on Windows.\n    * `${summon binary dir}/Providers` For portable installation\n    * `${summon binary dir}/../lib/summon` For homebrew installations\n\n* `-f \u003cpath\u003e` specify a location to a secrets.yml file, default 'secrets.yml' in current directory.\n\n* `--up` searches for secrets.yml going up, starting from the current working\n  directory.\n\n    Stops at the first file found or when the root of the current file system is\n    reached. This allows to be at any directory depth in a project and simply do\n    `summon -u \u003ccommand\u003e`.\n\n* `-D 'var=value'` causes substitution of `value` to `$var`.\n\n    You can use the same secrets.yml file for different environments, using `-D` to\n    substitute variables. This flag can be used multiple times.\n\n    *Example*\n\n    ```\n    summon -D ENV=production --yaml 'SQL_PASSWORD: !var env/$ENV/db-password' deploy.sh\n    ```\n\n* `--yaml \u003cYAML-string\u003e` Passes secrets.yml as a literal string.\n\n    This flag is used to pass a literal YAML string to the provider in place\n    of the `secrets.yml` file (see example above).\n\n* `-i, --ignore \u003cpath-to-provider\u003e` A secret path for which to ignore provider\nerrors.\n\n    This flag can be useful for when you have secrets that you don't need access to for development. For example API keys for monitoring tools. This flag can be used multiple times.\n\n* `-I, --ignore-all` A boolean to ignore any missing secret paths.\n\n    This flag can be useful when the underlying system that's going to be using the values implements defaults. For example, when using summon as a bridge to [confd](https://github.com/kelseyhightower/confd).\n\n* `-V, --all-provider-versions` List of all of the providers in the default\n    path and their versions (if they have the --version tag).\n* `-v, --version` Print the Summon version.\n\n* `-e, --environment` Specify section (environment) to parse from secret YAML.\n\n    This flag specifies which specific environment/section to parse from the secrets YAML file (or string). In addition, it will also enable the usage of a `common` (or `default`) section which will be inherited by other sections/environments. In other words, if your `secrets.yaml` looks something like this:\n\n```yaml\ncommon:\n  DB_USER: db-user\n  DB_NAME: db-name\n  DB_HOST: db-host.example.com\n\nstaging:\n  DB_PASS: some_password\n\nproduction:\n  DB_PASS: other_password\n```\n\nDoing something along the lines of: `summon -f secrets.yaml -e staging printenv | grep DB_`, `summon` will populate `DB_USER`, `DB_NAME`, `DB_HOST` with values from `common` and set `DB_PASS` to `some_password`.\n\nNote: `default` is an alias for `common` section. You can use either one.\n\n* `-h` View help and all flags.\n\n### env-file\n\nUsing Docker? When you run summon it also exports the variables and values from secrets.yml in `VAR=VAL` format to a memory-mapped file, its path made available as `@SUMMONENVFILE`.\n\nYou can then pass secrets to your container using Docker's `--env-file` flag like so:\n\n```sh\nsummon docker run --env-file @SUMMONENVFILE myorg/myimage\n```\n\nThis file is created on demand - only when `@SUMMONENVFILE` appears in the\narguments of the command summon is wrapping. This feature is not Docker-specific; if you have another tools that reads variables in `VAR=VAL` format\nyou can use `@SUMMONENVFILE` just the same.\n\n## Fixed tempfile name\n\nThere are times when you would like to have certain secrets values available at\nfixed locations, e.g. `/etc/ssl/cert.pem` for an SSL certificate. This can be\naccomplished by using symbolic links as described in the\n[symbolic link example](examples/symlinks/README.md).\n\n## Provider interactive mode\n\nWhen available, Summon uses the provider's stream mode to retrieve secrets. Whereas the legacy mode required\na new process to be created for each secret retrieval, the stream mode can fetch multiple secrets in a single\nprocess and allows providers to implement token caching.\n\nIf the provider does not support stream mode, Summon uses the legacy mode.\n\n## Contributing\n\nFor more info on contributing, please see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Troubleshooting\n\nFor assistance with some issues encountered when first using Summon, please refer to the\n[troubleshooting guide](CONTRIBUTING.md#Troubleshooting) in \n[CONTRIBUTING.md](CONTRIBUTING.md).\n\nCan't find your problem in the troubleshooting guide? [File an issue](https://github.com/cyberark/summon/issues/new/choose)\nor [ask us on Discourse](https://discuss.cyberarkcommons.org/c/summon/30).\n\n## License\n\nCopyright (c) 2020 CyberArk Software Ltd. All rights reserved.\n\nSummon is available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberark%2Fsummon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyberark%2Fsummon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberark%2Fsummon/lists"}