Bind secrets to their playbooks
Secrets are proving less useful than originally hoped because they
can not be effectively used in any jobs with untrusted children.
This change binds the secrets to the playbooks which use them, so
that child jobs are unable to access the secrets. This allows us
to create jobs with pre/post playbooks which use secrets which
are suitable for other jobs to inherit from.
Change-Id: I67dd12563f3abd242d6356675afed1de0cb144cf
diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index b2e4be2..0eb7bc7 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -187,14 +187,14 @@
.. attr:: allow-secrets
:default: false
- This is a boolean which can be used to prevent jobs which
- require secrets from running in this pipeline. Some pipelines
- run on proposed changes and therefore execute code which has not
- yet been reviewed. In such a case, allowing a job to use a
- secret could result in that secret being exposed. The default
- is ``false``, meaning that in order to run jobs with secrets,
- this must be explicitly enabled on each Pipeline where that is
- safe.
+ This is a boolean which can be used to prevent jobs which use
+ secrets in the untrusted security context from running in this
+ pipeline. Some pipelines run on proposed changes and therefore
+ execute code which has not yet been reviewed. In such a case,
+ allowing a job to use a secret could result in that secret being
+ exposed. The default is ``false``, meaning that in order to run
+ jobs which use secrets in the untrusted security context, this
+ must be explicitly enabled on each Pipeline where that is safe.
For more information, see :ref:`secret`.
@@ -672,19 +672,6 @@
Authentication information to be made available to the job.
This is a dictionary with two potential keys:
- .. attr:: inherit
- :default: false
-
- A boolean indicating that the authentication information
- referenced by this job should be able to be inherited by
- child jobs. Normally when a job inherits from another job,
- the auth section is not included. This permits jobs to
- inherit the same basic structure and playbook, but ensures
- that secret information is unable to be exposed by a child
- job which may alter the job's behavior. If it is safe for
- the contents of the authentication section to be used by
- child jobs, set this to ``true``.
-
.. attr:: secrets
A list of secrets which may be used by the job. A
@@ -907,6 +894,16 @@
it should be able to run this job, then it must be explicitly
listed. By default, all projects may use the job.
+ .. attr:: untrusted-secrets
+
+ A boolean value which indicates that this job should not be used
+ in a pipeline where allow-secrets is ``false``. This is
+ automatically set to ``true`` if this job is defined in a
+ :term:`untrusted-project`. It may be explicitly set to obtain
+ the same behavior for jobs defined in :term:`config projects
+ <config-project>`. Once this is set to ``true`` anywhere in the
+ inheritance hierarchy for a job, it will remain set for all
+ child jobs and variants (it can not be set to ``false``).
.. _project:
@@ -1062,22 +1059,34 @@
A Secret may only be used by jobs defined within the same project. To
use a secret, a :ref:`job` must specify the secret within its `auth`
-section. To protect against jobs in other repositories declaring a
-job with a secret as a parent and then exposing that secret, jobs
-which inherit from a job with secrets will not inherit the secrets
-themselves. To alter that behavior, see the `inherit` job attribute.
-Further, jobs which do not permit children to inherit secrets (the
-default) are also automatically marked `final`, meaning that their
-execution related attributes may not be changed in a project-pipeline
-stanza. This is to protect against a job with secrets defined in one
-project being used by another project in a way which might expose the
-secrets. If a job with secrets is unsafe to be used by other
-projects, the `allowed-projects` job attribute can be used to restrict
-the projects which can invoke that job. Finally, pipelines which are
-used to execute proposed but unreviewed changes can set the
-`allow-secrets` attribute to indicate that they should not supply
-secrets at all in order to protect against someone proposing a change
-which exposes a secret.
+section. Secrets are bound to the playbooks associated with the
+specific job definition where they were declared. Additional pre or
+post playbooks which appear in child jobs will not have access to the
+secrets, nor will playbooks which override the main playbook (if any)
+of the job which declared the secret. This protects against jobs in
+other repositories declaring a job with a secret as a parent and then
+exposing that secret.
+
+It is possible to use secrets for jobs defined in :term:`config
+projects <config-project>` as well as :term:`untrusted projects
+<untrusted-project>`, however their use differs slightly. Because
+playbooks in a config project which use secrets run in the
+:term:`trusted execution context` where proposed changes are not used
+in executing jobs, it is safe for those secrets to be used in all
+types of pipelines. However, because playbooks defined in an
+untrusted project are run in the :term:`untrusted execution context`
+where proposed changes are used in job execution, it is dangerous to
+allow those secrets to be used in pipelines which are used to execute
+proposed but unreviewed changes. By default, pipelines will refuse to
+run jobs which have playbooks that use secrets in the untrusted
+execution context to protect against someone proposing a change which
+exposes a secret. To permit this (for instance, in a pipeline which
+only runs after code review), the :attr:`pipeline.allow-secrets`
+attribute may be set.
+
+If a job with secrets is unsafe to be used by other projects, the
+`allowed-projects` job attribute can be used to restrict the projects
+which can invoke that job.
.. attr:: secret
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index 7f1c3cb..5f36c30 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -121,6 +121,9 @@
{{ credentials.username }} {{ credentials.password }}
+Secrets are only available to playbooks associated with the job
+definition which uses the secret; they are not available to playbooks
+associated with child jobs or job variants.
Zuul Variables
~~~~~~~~~~~~~~