[v3] security-manual: Add information about how security is handled in builds

We have no information about how security is handled within the builds
themselves. Start to document this.

[YOCTO #16102]

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../build-process-security.rst                | 49 +++++++++++++++++++
 documentation/security-manual/index.rst       |  1 +
 2 files changed, 50 insertions(+)
 create mode 100644 documentation/security-manual/build-process-security.rst

Hi Richard,

On 8/11/26 11:02 AM, Richard Purdie via lists.yoctoproject.org wrote:
> We have no information about how security is handled within the builds
> themselves. Start to document this.
> 
> [YOCTO #16102]
> 
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>   .../build-process-security.rst                | 49 +++++++++++++++++++
>   documentation/security-manual/index.rst       |  1 +
>   2 files changed, 50 insertions(+)
>   create mode 100644 documentation/security-manual/build-process-security.rst
> 
> diff --git a/documentation/security-manual/build-process-security.rst b/documentation/security-manual/build-process-security.rst
> new file mode 100644
> index 000000000..dfc13235c
> --- /dev/null
> +++ b/documentation/security-manual/build-process-security.rst
> @@ -0,0 +1,49 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +**********************
> +Build Process Security
> +**********************
> +
> +The :term:`OpenEmbedded Build System` is used to run the builds and careful
> +consideration has gone into how it does this with the aim of being both secure
> +and reproducible. Like any system, it does need to be used carefully and in
> +keeping with the design for that to be true. Users of the system should
> +consider that:
> +
> +-  The builds generally aim for any input into the build process being verified in
> +   some form. For source code tarballs, these would have a checksum. Git source
> +   trees would have a specific git revision. Metadata would also usually be
> +   under source control and also have revisions.
> +
> +   See the
> +   :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching` section
> +   of the BitBake User Manual for more information.
> +
> +-  Some elements that can influence the build are not verified. It is assumed
> +   that the operating system running the system is secure and of a known setup and
> +   version. The system goes to significant lengths to isolate against host
> +   contamination of the output but it is certainly possible, especially maliciously.
> +
> +   See the :ref:`system-requirements-supported-distros` section of the Yocto
> +   Project Reference Manual for more information on supported host distributions.
> +
> +-  The builds assume :term:`DL_DIR` is a safe location. Once download artefacts enter
> +   that location they are not repeatedly re-verified. A user could edit the git trees or
> +   tarballs there in ways the build might not detect.
> +
> +-  The builds assume sstate objects from :term:`SSTATE_DIR` or from a configured sstate mirror
> +   are safe (with :doc:`signature checks </security-manual/sstate-signing>` if configured).
> +
> +-  The core build tool, :term:`BitBake`, is a execution engine and will execute code both

s/a/an/

> +   during builds and when parsing recipes. This is not a security issue, it is an
> +   essential part of it's function and purpose.

s/it's/its/

> +
> +-  :term:`OpenEmbedded-Core (OE-Core)` is well tested for reproducibility issues but other
> +   layers and their recipes and code may not be as well tested. Those reproducibility tests
> +   are available for others to run against their own layers and code.
> +

Would be nice to have a link to those reproducibility tests (or if we 
have documentation for those, that) so we remove friction for layers to 
figure out how to do them.

With the typos fixed:

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

On Tue, 2026-08-11 at 11:08 +0200, Quentin Schulz wrote:
> On 8/11/26 11:02 AM, Richard Purdie via lists.yoctoproject.org wrote:
> 
> > +
> > +-  :term:`OpenEmbedded-Core (OE-Core)` is well tested for reproducibility issues but other
> > +   layers and their recipes and code may not be as well tested. Those reproducibility tests
> > +   are available for others to run against their own layers and code.
> > +
> 
> Would be nice to have a link to those reproducibility tests (or if we
> have documentation for those, that) so we remove friction for layers to 
> figure out how to do them.

It would. I was going to say it is a bit more involved however it would
be good for someone to document it so let me at least write down that
bit in the hope someone can sort the markup/docs entry for it.

To test a layer's reproducibility, you would setup a build with
OE-Core with the addition of the layer you want to test. You'd use a
configuration along the lines of:

EXCLUDE_FROM_WORLD:layer-core = '1'
EXCLUDE_FROM_WORLD:layer-yocto = '1'
EXCLUDE_FROM_WORLD:layer-yoctobsp = '1'
EXCLUDE_FROM_WORLD:layer-selftest = '1'
OEQA_REPRODUCIBLE_TEST_TARGET = 'world'

which would setup the reproducibility target as 'world' but then only
include the additional layer in the world build.

You could then run the reproducibility test as:

OEQA_DEBUGGING_SAVED_OUTPUT=/place/to/save/failing-output oe-selftest -r reproducible

where differences would be stored in /place/to/save/failing-output for
debugging, which is handy in CI.

Cheers,

Richard