CBL-Mariner/CONTRIBUTING.md

Azure Linux's Contribution Guide

Table of Contents

Please use the auto-generated table of contents GitHub creates. To reveal it, select the three bar menu icon at the top of the page.

Contributing License Agreement

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Security Vulnerabilities

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft, Azure, DotNet, AspNet, Xamarin, and our GitHub organizations.

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's Microsoft's definition of a security vulnerability of a security vulnerability, please report it to us as described below.

Reporting Security Issues

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report.

If you prefer to submit without logging in, send email to secure@microsoft.com. If possible, encrypt your message with our PGP key; please download it from the the Microsoft Security Response Center PGP Key page.

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at microsoft.com/msrc.

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

• Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
• Full paths of source file(s) related to the manifestation of the issue
• The location of the affected source code (tag/branch/commit or direct URL)
• Any special configuration required to reproduce the issue
• Step-by-step instructions to reproduce the issue
• Proof-of-concept or exploit code (if possible)
• Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our Microsoft Bug Bounty Program page for more details about our active programs.

Preferred Languages

We prefer all communications to be in English.

Policy

Microsoft follows the principle of Coordinated Vulnerability Disclosure.

Develop for Azure Linux

When starting to develop for Azure Linux, use the Azure LinuxTutorials repo. This repository guides developers on using Azure Linux's tools to customize or add new packages or images. Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, Azure Linux. Please see our quickstart for a tutorial and building instructions for an in-depth overview of building within Azure Linux. Please adhere to the Pull Request guidelines when contributing.

Packages

Azure Linux packages live in either SPECS or SPECS-EXTENDED. Azure Linux packages that are in the SPECS directory have full support and coverage with timely CVE maintenance. Packages in SPECS-EXTENDED are for experimentation or proof-of-concept purposes only. SPECS-EXTENDED can be used as a staging area for iterating on packages with the possiblity of the package being graduated to SPECS.

Package Support Level	Published	Supported	Comments
SPECS-EXTENDED	Yes	No	- Package needs a viable upstream source which actively addresses CVEs - Package must not include project specific code
SPECS	Yes	Yes	- Package needs a viable upstream source which actively addresses CVEs - Package must not include project specific code - Package needs to offer value for multiple use cases

When looking to graduate a package from SPECS-EXTENDED to SPECS, file a GitHub issue highlighting the package's value and ensure that the following steps are completed for associated PRs.

1. Increment the spec's Release value
2. Add changelog entries "Package promoted from SPECS-EXTENDED to SPECS" and "License verified"
3. Add a %check section to the spec if not already present and confirm it passes
4. Ensure spec is free of references, macros, comments, etc. only applicable to other distros
5. Complete the PR checklist
6. Pass the GitHub checks

Toolkit

We welcome tooling improvements. When contributing to the toolkit, please adhere to golang formatting as described by the fmt package. To format using this package, you can run make go-tidy-all in your Azure Linux toolkit. For guidance on building with the toolkit, see our building instructions.

Documentation

We welcome documentation improvements. See toolkit/docs for the latest documentation.

Pull Request Guidelines

Please direct pull requests to the desired development branch. Development changes to 2.0 should target main. Development changes to 1.0 should target 1.0-dev.

Branch structure

An overview of how the branches are structured can be seen below

Branch / Tag	For PRs	Published	Notes
main	Yes	No	Primary development branch
2.0	No	Yes - eventually	Staging branch for publishing
2.0-stable	No	Yes	Last published release
2.0-preview	No	No	Publishing in progress

Branch / Tag	For PRs	Published	Notes
1.0-dev	Yes	No	Development branch for 1.0
1.0	No	Yes - eventually	Staging branch for publishing
1.0-stable	No	Yes	Last published release
1.0-preview	No	No	Publishing in progress

PR Titles

PR titles should start with an action

- Add <package>
- Bump Release version for October Update
- Change whatever you changed.
- Fix <thing you fixed> <reason you fixed it>
- Patch <package> to fix CVE-XXXX-YYYY, CVE-XXXX-YYYY…
- Upgrade <package> to version vvvv to fix CVE-XXXX-YYYY…
- Remove <package> <reason you removed it>

Please avoid titles such as

- package: <whatever you did to the package>
- CVE-XXXX-YYYY (leaving off what package was patched or upgraded)
- [1.0] (prefixing with branch or other information)

PR Checklist

When creating your PR, please ensure the following:

• The toolchain has been rebuilt successfully (or no changes were made to it). This only applies if you changed any packages in the toolchain package manifests. Specifically, toolchain_x86_64.txt and toolchain_aarch64.txt. For guidance on building the toolchain, see our building instructions.

• The toolchain / worker package manifests are up-to-date (versions match latest package versions in SPEC files). The manifests are the following files:

  • toolchain_x86_64.txt
  • toolchain_aarch64.txt
  • pkggen_core_x86_64.txt
  • pkggen_core_aarch64.txt

• Any updated packages successfully build (or no packages were changed). For guidance on building packages, see our building instructions. Please ensure the package is located in the appropriate folder.

• Packages depending on static components modified in this PR (Golang, *-static subpackages, etc.) have had their Release tag incremented. Dependent packages are packages which contain a BuildRequires on the package you are updating and create static links from your package. This can be difficult to discern based on spec files alone and may require investigating make commands in dependent packages or consulting an Azure Linux dev.

• Package tests (%check section) have been verified with RUN_CHECK=y for existing SPEC files, or added to new SPEC files. When running the check section, results will not fail a build. Check the logs for the results of this section.

• All package sources are available. The sources are either in the source server or local SPECS folder (SPECS/<package>/SOURCES or SPECS/<package>). While it is possible to build packages with all sources inside the repo, our policy is generally to have the source compressed and placed on the source server. Uploading to the source server can only be accomplished by an Azure Linux developer. Please request help in your PR for uploading your sources to the source server. To check the source server see [https://azurelinuxsrcstorage.blob.core.windows.net/sources/core/< source tar >].

• cgmanifest files are up-to-date and alphabetically sorted. The cgmanifest files are used to record all package sources. They include the following files:

  • ./cgmanifest.json
  • ./toolkit/tools/cgmanifest.json
  • ./toolkit/scripts/toolchain/cgmanifest.json,
  • .github/workflows/cgmanifest.json

  To validate, run the following in an Azure Linux container or Ubuntu >= 22.04

  .github/workflows/validate-cg-manifest.sh SPECS/<package name>/<package-name>.spec
  

• LICENSE-MAP files are up-to-date. These files indicate which licenses are being used by Azure Linux's packages and where the package may be derived from. The license files include the following files:

  • ./LICENSES-AND-NOTICES/SPECS/data/licenses.json
  • ./LICENSES-AND-NOTICES/SPECS/LICENSES-MAP.md

  This can be checked by running

  python3 ./toolkit/scripts/license_map.py \
  ./LICENSES-AND-NOTICES/SPECS/data/licenses.json \
  ./LICENSES-AND-NOTICES/SPECS/LICENSES-MAP.md \
  ./SPECS \
  ./SPECS-EXTENDED \
  ./SPECS-SIGNED
  

• All source files have up-to-date hashes in the *.signatures.json files. This hash is generated by sha256sum. You can also use the make tools to automatically update these hashes.

  cd toolkit
  sudo make input-srpms REBUILD_TOOLS=y SRPM_FILE_SIGNATURE_HANDLING=update
  

• If you modified the go tools, ensure that the formatting meets golang's standards and that the tests still pass.

  cd toolkit
  # fix formatting
  sudo make go-tidy-all
  # check tests
  sudo make go-test-coverage
  

• Documentation has been updated to match any changes to the build system. See toolkit/docs.

Bugs

If the bug is security related, please use the security guidelines above. Otherwise, please use the issues page on Azure Linux to file bugs.