From d5f6e4cd34ba2550499876ed4c8988e183b3465c Mon Sep 17 00:00:00 2001 From: David Beitey Date: Fri, 15 Feb 2019 03:04:10 +0000 Subject: [PATCH 1/3] Add info on env variables for Formula Cookbook This explains the levels of environment variable filtering present in Homebrew, explaining how and why variables without a `HOMEBREW_` prefix or those which contain `TOKEN` etc are made unavailable to a Formula. --- docs/Formula-Cookbook.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 3923323613..52612c1408 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -696,6 +696,16 @@ Homebrew provides two formula DSL methods for launchd plist files: * [`plist_name`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_name-instance_method) will return e.g. `homebrew.mxcl.` * [`plist_path`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_path-instance_method) will return e.g. `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist` +### Using environment variables + +Homebrew has multiple levels of environment variable filtering which affects variables available to formulae. + +Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds ([ref](https://github.com/Homebrew/brew/issues/932)). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in the [`brew`](https://github.com/Homebrew/brew/blob/master/bin/brew) script. + +The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them ([ref](https://github.com/Homebrew/brew/pull/2524)). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`clear_sensitive_environment` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb). + +In summary, environment variables used by a formula need to conform to these filtering rules in order to be available. + ## Updating formulae Eventually a new version of the software will be released. In this case you should update the [`url`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#url-class_method) and [`sha256`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#sha256%3D-class_method). If a [`revision`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method) line exists outside any `bottle do` block *and* the new release is stable rather than devel, it should be removed. From a3a3e3b878e46e1f1c1e1225cc9588daa14e5c93 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sat, 16 Feb 2019 09:46:57 +0000 Subject: [PATCH 2/3] Formula Cookbook: env var docs tweaks. --- docs/Formula-Cookbook.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 52612c1408..8a6a2b22ea 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1,6 +1,6 @@ # Formula Cookbook -A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --debug --verbose `. Formulae use the [Formula API](https://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. +A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --drefebug --verbose `. Formulae use the [Formula API](https://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. ## Homebrew terminology @@ -700,9 +700,9 @@ Homebrew provides two formula DSL methods for launchd plist files: Homebrew has multiple levels of environment variable filtering which affects variables available to formulae. -Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds ([ref](https://github.com/Homebrew/brew/issues/932)). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in the [`brew`](https://github.com/Homebrew/brew/blob/master/bin/brew) script. +Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds (https://github.com/Homebrew/brew/issues/932). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in [`bin/brew`](https://github.com/Homebrew/brew/blob/master/bin/brew). -The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them ([ref](https://github.com/Homebrew/brew/pull/2524)). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`clear_sensitive_environment` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb). +The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them (https://github.com/Homebrew/brew/pull/2524). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`ENV.clear_sensitive_environment!` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb). In summary, environment variables used by a formula need to conform to these filtering rules in order to be available. From d415600e208f86b85647871f0179298bb236acb8 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Sat, 16 Feb 2019 09:50:18 +0000 Subject: [PATCH 3/3] Formula Cookbook: fix typo. --- docs/Formula-Cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 8a6a2b22ea..d5842e746d 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1,6 +1,6 @@ # Formula Cookbook -A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --drefebug --verbose `. Formulae use the [Formula API](https://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. +A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --debug --verbose `. Formulae use the [Formula API](https://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. ## Homebrew terminology