Pular para conteúdo

Prática 14 - Licenças, SBOM e CVEs

Selecione o seu alvo

Clique em Build QEMU , conforme a orientação do instrutor. A escolha vale para todas as práticas do site e fica salva no seu navegador.

  • Diretório de build: ~/treinamento/yp/poky/build-qemu
  • Camada: ~/treinamento/yp/poky/meta-treinamento
  • TARGET: QEMU executando a imagem com runqemu


Todo produto com Linux embarcado precisa responder três perguntas: quais licenças estou distribuindo?, o que exatamente está dentro da imagem? e quais vulnerabilidades conhecidas afetam esses componentes?. O Yocto Project responde as três durante o build. Nesta prática vamos usar essas informações na imagem b2open-core-image.

O que será praticado:

  • Manifesto de licenças da imagem e textos de licença por receita.
  • Política de licenças com INCOMPATIBLE_LICENSE e INCOMPATIBLE_LICENSE_EXCEPTIONS.
  • Licenças dentro da imagem com COPY_LIC_MANIFEST e COPY_LIC_DIRS.
  • SBOM no formato SPDX, gerado automaticamente em todo build.
  • Verificação de CVEs com a classe cve-check e registro de decisões com CVE_STATUS.

Carregue o ambiente de build:

Executar no HOST
cd ~/treinamento/yp/poky/

source oe-init-build-env build-qemu


Parte 1 - Licenças da imagem

A cada imagem gerada, o BitBake grava um manifesto com o pacote, a versão, a receita e a licença de tudo o que foi instalado. Localize o manifesto da b2open-core-image:

Executar no HOST
find tmp/deploy/licenses -path '*b2open-core-image*' -name license.manifest

Saída esperada (semelhante a):

tmp/deploy/licenses/qemuarm/b2open-core-image-qemuarm.rootfs-<DATETIME>/license.manifest


Visualize o início do manifesto:

Executar no HOST
head -12 tmp/deploy/licenses/qemuarm/b2open-core-image-qemuarm.rootfs/license.manifest

Saída esperada (semelhante a):

PACKAGE NAME: alsa-conf
PACKAGE VERSION: 1.2.11
RECIPE NAME: alsa-lib
LICENSE: LGPL-2.1-only & GPL-2.0-or-later

PACKAGE NAME: alsa-lib
PACKAGE VERSION: 1.2.11
RECIPE NAME: alsa-lib
LICENSE: LGPL-2.1-only & GPL-2.0-or-later


Faça um resumo de quantos pacotes existem por licença:

Executar no HOST
grep "^LICENSE:" tmp/deploy/licenses/qemuarm/b2open-core-image-qemuarm.rootfs/license.manifest | sort | uniq -c | sort -rn


Além do manifesto, o texto de cada licença fica guardado por receita. Veja o exemplo do busybox:

Executar no HOST
ls $(find tmp/deploy/licenses -maxdepth 2 -type d -name busybox)

Saída esperada (semelhante a):

generic_bzip2-1.0.4  generic_GPL-2.0-only  LICENSE  recipeinfo


Parte 2 - Política de licenças

Muitos produtos não podem conter software GPL-3.0, por exemplo quando usam secure boot e não permitem que o usuário troque o software do equipamento. O Yocto Project permite bloquear licenças com a variável INCOMPATIBLE_LICENSE.

Vamos simular uma situação real: alguém adicionou o bash (licença GPL-3.0-or-later) na imagem, e a política do produto proíbe GPL-3.0.

Edite a receita da imagem meta-treinamento/recipes-core/images/b2open-core-image.bb e adicione no final:

1
2
3
IMAGE_INSTALL += "bash"

INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"

Note

Definida na receita da imagem, a variável INCOMPATIBLE_LICENSE verifica somente os pacotes que entram nesta imagem. Definida no local.conf ou na distro, ela vale para todas as receitas do build, e qualquer receita que dependa de algo GPL-3.0 deixa de compilar. Comece sempre pela imagem.


Gere a imagem:

Executar no HOST
bitbake b2open-core-image

O build falha na tarefa do_rootfs. Saída esperada (semelhante a):

ERROR: b2open-core-image-1.0-r0 do_rootfs: Package bash cannot be installed into the image because it has incompatible license(s): GPL-3.0-or-later

Se aparecer outro pacote no lugar do bash, a lógica é a mesma: ele tem uma licença bloqueada pela política.


Existem dois caminhos para resolver:

  1. Remover o pacote da imagem. É a solução correta quando o pacote não é necessário, como aqui, já que o busybox fornece o shell /bin/sh.
  2. Criar uma exceção documentada, quando o pacote é realmente necessário e a equipe jurídica aprovou.

Teste primeiro a exceção. Adicione na receita da imagem, abaixo do INCOMPATIBLE_LICENSE:

1
2
3
4
5
6
7
8
INCOMPATIBLE_LICENSE_EXCEPTIONS = " \
                                  bash:GPL-3.0-or-later \
                                  dosfstools:GPL-3.0-only \
                                  gdbm:GPL-3.0-only \
                                  gdbm-compat:GPL-3.0-only \
                                  kbd-keymaps-pine:GPL-3.0-or-later \
                                  readline:GPL-3.0-or-later \
                                  "


Gere a imagem novamente:

Executar no HOST
bitbake b2open-core-image

O build passa, mas registra um aviso para que a exceção nunca fique escondida. Saída esperada (semelhante a):

WARNING: b2open-core-image-1.0-r0 do_rootfs: QA Issue: Including bash with incompatible license(s) GPL-3.0-or-later into the image, because it has been allowed by exception list. [license-incompatible]


Agora aplique a solução definitiva: remova da receita da imagem as linhas IMAGE_INSTALL += "bash" e INCOMPATIBLE_LICENSE_EXCEPTIONS, mantendo o INCOMPATIBLE_LICENSE como política do produto.


Licenças dentro da imagem

Para cumprir as licenças, também é comum entregar os textos de licença junto com o produto. Adicione na receita da imagem:

COPY_LIC_MANIFEST = "1"
COPY_LIC_DIRS = "1"
  • COPY_LIC_MANIFEST: copia o license.manifest para dentro da imagem.
  • COPY_LIC_DIRS: copia também os textos de licença de cada pacote.


Gere a imagem, faça o boot no TARGET e confira:

Executar no HOST
bitbake b2open-core-image
Executar no TARGET
ls /usr/share/common-licenses/

head -8 /usr/share/common-licenses/license.manifest


Parte 3 - SBOM (Software Bill of Materials)

O SBOM é a "lista de ingredientes" do produto: nome, versão, licença e origem de cada componente, em um formato padrão. No Yocto Project ele é gerado em todo build pela classe create-spdx, que já vem habilitada por padrão, no formato SPDX.

Localize o SBOM da imagem:

Executar no HOST
ls -lh tmp/deploy/images/qemuarm/*.spdx.tar.zst


Extraia o SBOM em um diretório de trabalho:

Executar no HOST
mkdir -p ~/treinamento/sbom

tar --zstd -xf tmp/deploy/images/qemuarm/b2open-core-image-qemuarm.rootfs.spdx.tar.zst -C ~/treinamento/sbom

ls ~/treinamento/sbom | head -20

ls ~/treinamento/sbom | wc -l

O SBOM é um conjunto de documentos SPDX em JSON:

  • index.json: índice de todos os documentos.
  • recipe-<receita>.spdx.json: a receita, com fontes, patches e licença.
  • <pacote>.spdx.json: cada pacote instalado, com seus arquivos.
  • runtime-<pacote>.spdx.json: as dependências de execução de cada pacote.


Os arquivos são JSON compactos, com tudo em uma única linha. Para ler no terminal, use o formatador de JSON que já vem no Python (python3 -m json.tool), sem precisar criar nenhum script. Veja os dados principais da receita do busybox:

Executar no HOST
python3 -m json.tool ~/treinamento/sbom/recipe-busybox.spdx.json | grep -E '"(name|versionInfo|licenseDeclared|referenceLocator)"'

Saída esperada (semelhante a):

    "name": "recipe-busybox",
            "name": "busybox",
            "versionInfo": "1.36.1",
            "licenseDeclared": "GPL-2.0-only AND bzip2-1.0.4",
                    "referenceLocator": "cpe:2.3:a:busybox:busybox:1.36.1:*:*:*:*:*:*:*"

  • versionInfo e licenseDeclared: a versão e a licença declarada na receita.
  • referenceLocator: o identificador CPE do componente. É por esse identificador que as ferramentas cruzam o SBOM com os bancos de vulnerabilidades, como veremos na Parte 4.


Para navegar pelo documento completo, use o less (tecle / para buscar e q para sair):

Executar no HOST
python3 -m json.tool ~/treinamento/sbom/recipe-busybox.spdx.json | less

Tip

Para gerar os documentos SPDX já formatados (com quebras de linha e indentação), adicione SPDX_PRETTY = "1" no local.conf. Os arquivos ficam maiores, mas dá para ler direto no editor.

Note

O scarthgap gera SPDX 2.2. A partir do Yocto Project 6.0 (wrynose) é gerado somente SPDX 3.0. Ferramentas de mercado (Dependency-Track, por exemplo) leem esses arquivos para controlar os componentes do produto.


Parte 4 - Verificação de CVEs

A classe cve-check compara o nome e a versão de cada receita (o CPE visto na Parte 3) com o banco de vulnerabilidades do NIST (NVD) e gera um relatório por imagem.


Edite o conf/local.conf do build e adicione no final:

INHERIT += "cve-check"
CVE_DB_UPDATE_INTERVAL = "-1"

Banco de dados do NVD

Na primeira execução o BitBake baixa o banco do NVD, o que pode levar bastante tempo. No treinamento vamos baixar o banco pronto em downloads (DL_DIR/CVE_CHECK/). VERIFICAR COM O INSTRUTOR antes de executar esta parte.

Para usar o banco existente sem tentar atualizar, adicione no local.conf: CVE_DB_UPDATE_INTERVAL = "-1".


Baixando o bando de dados do NVD:

Executar no HOST
cd ~/treinamento/yp/poky/build-qemu/downloads

mkdir CVE_CHECK

cd CVE_CHECK

wget https://b2shared.us-southeast-1.linodeobjects.com/yp/nvdcve_2-2.db -O nvdcve_2-2.db


Gere a imagem:

Executar no HOST
cd ~/treinamento/yp/poky

source oe-init-build-env build-qemu

bitbake b2open-core-image


Download Lento do Banco de dados do NVD

O download lento ou travado no cve-update-nvd2-native (no Yocto/OpenEmbedded) acontece principalmente devido aos limites de taxa (rate limits) e à lentidão dos servidores da NIST/NVD.


Durante o build aparecem avisos para cada receita com CVEs em aberto. Ao final o BitBake mostra onde ficaram os relatórios. Saída esperada (semelhante a):

WARNING: busybox-1.36.1-r0 do_cve_check: Found unpatched CVE (CVE-AAAA-NNNNN ...), for more information check .../tmp/work/.../busybox/1.36.1/temp/cve.log
...
Image CVE report stored in: .../tmp/deploy/images/qemuarm/b2open-core-image-qemuarm.rootfs-20261020120000.cve
Image CVE JSON report stored in: .../tmp/deploy/images/qemuarm/b2open-core-image-qemuarm.rootfs-20261020120000.json


O relatório é gerado em dois formatos: .json, para ser lido por ferramentas, e .cve, em texto, para ser lido por pessoas. Vamos usar o de texto. Abra o relatório e veja como cada CVE é registrada (tecle / para buscar e q para sair):

Executar no HOST
less tmp/deploy/images/qemuarm/b2open-core-image-qemuarm.rootfs.cve

Cada CVE é um bloco como este (semelhante a):

LAYER: meta
PACKAGE NAME: busybox
PACKAGE VERSION: 1.36.1
CVE: CVE-AAAA-NNNNN
CVE STATUS: Unpatched
CVE SUMMARY: <descrição da vulnerabilidade>
CVSS v2 BASE SCORE: 0.0
CVSS v3 BASE SCORE: 7.5
VECTOR: NETWORK
VECTORSTRING: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H
MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-AAAA-NNNNN

O campo CVE STATUS indica a situação: Patched (já corrigida), Unpatched (em aberto) ou Ignored (analisada e registrada como não aplicável).


Para facilitar os próximos comandos, guarde o caminho do relatório em uma variável do shell:

Executar no HOST
CVE_REPORT=tmp/deploy/images/qemuarm/b2open-core-image-qemuarm.rootfs.cve


Conte quantas CVEs estão em cada situação:

Executar no HOST
grep "^CVE STATUS:" $CVE_REPORT | sort | uniq -c

Saída esperada (semelhante a):

    412 CVE STATUS: Patched
     35 CVE STATUS: Unpatched
     18 CVE STATUS: Ignored


Veja quais pacotes têm CVEs em aberto, do que tem mais para o que tem menos:

Executar no HOST
awk '/^PACKAGE NAME:/ {pkg=$3} /^CVE STATUS: Unpatched/ {print pkg}' $CVE_REPORT | sort | uniq -c | sort -rn

O awk guarda o nome do pacote de cada bloco e imprime esse nome sempre que encontra uma CVE com status Unpatched.


Liste as CVEs em aberto do busybox:

Executar no HOST
awk '/^PACKAGE NAME:/ {pkg=$3} /^CVE: / {cve=$2} /^CVE STATUS: Unpatched/ && pkg=="busybox" {print cve}' $CVE_REPORT


O resultado do cve-check é um ponto de partida, não uma sentença. Muitas CVEs não se aplicam ao produto: o recurso afetado está desligado na configuração, a CVE é de outra plataforma ou já foi corrigida por um patch. Cada caso precisa ser analisado e a decisão registrada.


Ao terminar, remova a linha INHERIT += "cve-check" do local.conf para os próximos builds não passarem pela verificação.


Prática 14 realizada com sucesso!