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

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

[Richard Purdie]

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

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

diff --git a/documentation/security-manual/build-security.rst b/documentation/security-manual/build-security.rst
new file mode 100644
index 000000000..5f15d5f64
--- /dev/null
+++ b/documentation/security-manual/build-security.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+**************
+Build Security
+**************
+
+OpenEmbedded 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.
+
+-  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 signififant lengths to isolate against host
+   contamination of the output but it is certainly possible, especially malicously.
+
+-  The builds assume DL_DIR is a safe location. Once things enter that location
+   there 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 things from SSTATE_DIR or from a configured sstate mirror
+   are safe (with signature checks if configured).
+
+-  The core build tool, BitBake is a execution engine and will execute code both
+   during builds and when parsing recipes. This is not a security issue, it is an
+   essential part of it's function and purpose.
+
+-  OE-Core is well tested for reproducibility issues but other layers and their
+   recipes and code may not be as well tested. Those reproducilbity tests are
+   available for others to run against their own layers and code.
+
+-  The builds combine many different software components and we take it on trust
+   that there aren't issues in those code bases. We'd recommend build environments
+   being setup in such a way that if such an issue were ever discovered, which at
+   some point could happen, the build environments themselves could be simply
+   destroyed and rebuilt cleanly, i.e. they're disposable.
diff --git a/documentation/security-manual/index.rst b/documentation/security-manual/index.rst
index a767cd9c6..328265be2 100644
--- a/documentation/security-manual/index.rst
+++ b/documentation/security-manual/index.rst
@@ -11,6 +11,7 @@ Yocto Project Security Manual
    :numbered:
 
    intro
+   build-security
    securing-images
    vulnerabilities
    read-only-rootfs

Re: [docs] [PATCH] security-manual: Add information about how security is handled in builds

[Antonin Godard]

Hi,

On Fri Aug 7, 2026 at 6:43 PM CEST, Richard Purdie via lists.yoctoproject.org wrote:
> We have no information about how security is handled within the builds
> themselves. Start to document this.
>
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>  .../security-manual/build-security.rst        | 41 +++++++++++++++++++
>  documentation/security-manual/index.rst       |  1 +
>  2 files changed, 42 insertions(+)
>  create mode 100644 documentation/security-manual/build-security.rst
>
> diff --git a/documentation/security-manual/build-security.rst b/documentation/security-manual/build-security.rst
> new file mode 100644
> index 000000000..5f15d5f64
> --- /dev/null
> +++ b/documentation/security-manual/build-security.rst
> @@ -0,0 +1,41 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +**************
> +Build Security

I suggest renaming it to "OpenEmbedded Build System Security", as "Build" alone
could be interpreted in many different ways, including builds for specific
software components, etc.

> +**************
> +
> +OpenEmbedded is used to run the builds and careful consideration has gone into

When you say "OpenEmbedded" I guess you mean the community? Or the build system?

We have a :term:`OpenEmbedded Build System` that could be used here if relevant.

> +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.

Add a link to our fetching documentation here?

"""
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 signififant lengths to isolate against host
> +   contamination of the output but it is certainly possible, especially malicously.

typo: maliciously

Link to our supported distros here?

"""
See the :ref:`system-requirements-supported-distros` section of the Yocto
Project Reference Manual for more information on supported host distributions.
"""

> +
> +-  The builds assume DL_DIR is a safe location. Once things enter that location

s/DL_DIR/:term:`DL_DIR`/

> +   there are not repeatedly re-verified. A user could edit the git trees or
> +   tarballs there in ways the build might not detect.

I guess this will be better detailed with
https://bugzilla.yoctoproject.org/show_bug.cgi?id=16102. Maybe the documentation
coming from this bug should be linked here then.

> +
> +-  The builds assume things from SSTATE_DIR or from a configured sstate mirror

s/SSTATE_DIR/:term:`SSTATE_DIR`/

s/sstate mirror/:doc:`sstate mirror </dev-manual/sstate-mirrors-setup>`

> +   are safe (with signature checks if configured).

s/signature checks/:doc:`signature checks </security-manual/sstate-signing>`/

> +-  The core build tool, BitBake is a execution engine and will execute code both

"""
The core build tool, :term:`BitBake`, ...
"""

> +   during builds and when parsing recipes. This is not a security issue, it is an
> +   essential part of it's function and purpose.
> +
> +-  OE-Core is well tested for reproducibility issues but other layers and their

s/OE-Core/:term:`OpenEmbedded-Core (OE-Core)`/

> +   recipes and code may not be as well tested. Those reproducilbity tests are

typo: reproducibility

> +   available for others to run against their own layers and code.
> +
> +-  The builds combine many different software components and we take it on trust
> +   that there aren't issues in those code bases. We'd recommend build environments
> +   being setup in such a way that if such an issue were ever discovered, which at
> +   some point could happen, the build environments themselves could be simply
> +   destroyed and rebuilt cleanly, i.e. they're disposable.
> diff --git a/documentation/security-manual/index.rst b/documentation/security-manual/index.rst
> index a767cd9c6..328265be2 100644
> --- a/documentation/security-manual/index.rst
> +++ b/documentation/security-manual/index.rst
> @@ -11,6 +11,7 @@ Yocto Project Security Manual
>     :numbered:
>  
>     intro
> +   build-security
>     securing-images
>     vulnerabilities
>     read-only-rootfs

Thanks,
Antonin

Re: [docs] [PATCH] security-manual: Add information about how security is handled in builds

[Richard Purdie]

On Tue, 2026-08-11 at 10:01 +0200, Antonin Godard wrote:
> On Fri Aug 7, 2026 at 6:43 PM CEST, Richard Purdie via lists.yoctoproject.org wrote:
> > We have no information about how security is handled within the builds
> > themselves. Start to document this.
> > 
> > Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> > ---
> >  .../security-manual/build-security.rst        | 41 +++++++++++++++++++
> >  documentation/security-manual/index.rst       |  1 +
> >  2 files changed, 42 insertions(+)
> >  create mode 100644 documentation/security-manual/build-security.rst
> > 
> > diff --git a/documentation/security-manual/build-security.rst b/documentation/security-manual/build-security.rst
> > new file mode 100644
> > index 000000000..5f15d5f64
> > --- /dev/null
> > +++ b/documentation/security-manual/build-security.rst
> > @@ -0,0 +1,41 @@
> > +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> > +
> > +**************
> > +Build Security
> 
> I suggest renaming it to "OpenEmbedded Build System Security", as "Build" alone
> could be interpreted in many different ways, including builds for specific
> software components, etc.

Perhaps "Build Process Security"? I think build system isn't quit the
right thing here.

> 
> > +**************
> > +
> > +OpenEmbedded is used to run the builds and careful consideration has gone into
> 
> When you say "OpenEmbedded" I guess you mean the community? Or the build system?
> 
> We have a :term:`OpenEmbedded Build System` that could be used here if relevant.

That seems like the right thing to use.

> > +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.
> 
> Add a link to our fetching documentation here?
> 
> """
> See the :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching` section
> of the BitBake User Manual for more information.
> """

Sure, I intended this as a first pass and figured it might need some
markup/tweaking. Sorry for the spelling :/.

> 
> > +
> > +-  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 signififant lengths to isolate against host
> > +   contamination of the output but it is certainly possible, especially malicously.
> 
> typo: maliciously
> 
> Link to our supported distros here?
> 
> """
> See the :ref:`system-requirements-supported-distros` section of the Yocto
> Project Reference Manual for more information on supported host distributions.
> """
> 
> > +
> > +-  The builds assume DL_DIR is a safe location. Once things enter that location
> 
> s/DL_DIR/:term:`DL_DIR`/
> 
> > +   there are not repeatedly re-verified. A user could edit the git trees or
> > +   tarballs there in ways the build might not detect.
> 
> I guess this will be better detailed with
> https://bugzilla.yoctoproject.org/show_bug.cgi?id=16102. Maybe the documentation
> coming from this bug should be linked here then.

This text was intended to help close 16102 :/. We've not managed to get
anyone else to provide such information. Certainly if any more is
forthcoming, this would be the place to add it. I did want to document
something before we close that bug though.

Cheers,

Richard

Re: [docs] [PATCH] security-manual: Add information about how security is handled in builds

[Antonin Godard]

Hi,

On Tue Aug 11, 2026 at 10:20 AM CEST, Richard Purdie wrote:
> On Tue, 2026-08-11 at 10:01 +0200, Antonin Godard wrote:
>> On Fri Aug 7, 2026 at 6:43 PM CEST, Richard Purdie via lists.yoctoproject.org wrote:
>> > We have no information about how security is handled within the builds
>> > themselves. Start to document this.
>> > 
>> > Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
>> > ---
>> >  .../security-manual/build-security.rst        | 41 +++++++++++++++++++
>> >  documentation/security-manual/index.rst       |  1 +
>> >  2 files changed, 42 insertions(+)
>> >  create mode 100644 documentation/security-manual/build-security.rst
>> > 
>> > diff --git a/documentation/security-manual/build-security.rst b/documentation/security-manual/build-security.rst
>> > new file mode 100644
>> > index 000000000..5f15d5f64
>> > --- /dev/null
>> > +++ b/documentation/security-manual/build-security.rst
>> > @@ -0,0 +1,41 @@
>> > +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
>> > +
>> > +**************
>> > +Build Security
>> 
>> I suggest renaming it to "OpenEmbedded Build System Security", as "Build" alone
>> could be interpreted in many different ways, including builds for specific
>> software components, etc.
>
> Perhaps "Build Process Security"? I think build system isn't quit the
> right thing here.

Works for me :)

>> 
>> > +**************
>> > +
>> > +OpenEmbedded is used to run the builds and careful consideration has gone into
>> 
>> When you say "OpenEmbedded" I guess you mean the community? Or the build system?
>> 
>> We have a :term:`OpenEmbedded Build System` that could be used here if relevant.
>
> That seems like the right thing to use.
>
>> > +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.
>> 
>> Add a link to our fetching documentation here?
>> 
>> """
>> See the :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching` section
>> of the BitBake User Manual for more information.
>> """
>
> Sure, I intended this as a first pass and figured it might need some
> markup/tweaking. Sorry for the spelling :/.

No problem :)

>> 
>> > +
>> > +-  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 signififant lengths to isolate against host
>> > +   contamination of the output but it is certainly possible, especially malicously.
>> 
>> typo: maliciously
>> 
>> Link to our supported distros here?
>> 
>> """
>> See the :ref:`system-requirements-supported-distros` section of the Yocto
>> Project Reference Manual for more information on supported host distributions.
>> """
>> 
>> > +
>> > +-  The builds assume DL_DIR is a safe location. Once things enter that location
>> 
>> s/DL_DIR/:term:`DL_DIR`/
>> 
>> > +   there are not repeatedly re-verified. A user could edit the git trees or
>> > +   tarballs there in ways the build might not detect.
>> 
>> I guess this will be better detailed with
>> https://bugzilla.yoctoproject.org/show_bug.cgi?id=16102. Maybe the documentation
>> coming from this bug should be linked here then.
>
> This text was intended to help close 16102 :/. We've not managed to get
> anyone else to provide such information. Certainly if any more is
> forthcoming, this would be the place to add it. I did want to document
> something before we close that bug though.

Ah I see, ok, I guess that's already something and if someone comes up with more
information about the subject then there's already a place in the docs where
that can be added.

Thanks,
Antonin