Core Project Proposal: The Wasm-micro-runtime Project

[lum1n0us]

Proposing the promotion of Wasm-Micro-Runtime to a core project.

Repository URL: https://github.com/bytecodealliance/wasm-micro-runtime/

WebAssembly Micro Runtime (WAMR) is a lightweight standalone WebAssembly (Wasm) runtime with small footprint, high performance and highly configurable features for applications cross from embedded, IoT, edge to Trusted Execution Environment (TEE), smart contract, cloud native and so on.

Requirements

Alignment with the Bytecode Alliance Mission

Projects must have alignment with the Bytecode Alliance mission:

Our mission is to provide state-of-the-art foundations to develop runtime environments and language toolchains where security, efficiency, and modularity can all coexist across a wide range of devices and architectures. We enable innovation in compilers, runtimes, and tooling, focusing on fine-grained sandboxing, capabilities-based security, modularity, and standards such as WebAssembly and WASI.

The Bytecode Alliance is a group with a specific mission, and we therefore will only sponsor projects that are in alignment with and further that mission. For example, project sponsorship is untenable if the project undermines sandboxing, security, or standardization efforts.

WAMR is a founding project of the Bytecode Alliance, with a key goal of advancing WebAssembly technology in devices and embedded systems. WAMR exemplifies engineering excellence with its extremely small footprint, high performance, and support for a wide range of devices.

WAMR has significantly contributed to the community's success in using WebAssembly at the device level and has been deployed on millions of devices. The WAMR community is actively developing and maintaining the project, with notable contributions from Intel, Amazon, Sony, Midokura, Xiaomi, Siemens, and others. The WAMR project has introduced numerous innovations to fulfill its mission.

The community has also started the ESIG to address challenges in resource-constrained environments and to develop a standard roadmap for WebAssembly's continued success in these areas.

Changelog

Core projects must highlight key additions, breaking changes, security fixes, and otherwise noteworthy changes in a changelog.

See keepachangelog.com for a recommended approach.

We are building an ecosystem that developers can depend on, and one small part of that is communicating important changes downstream.

WAMR maintains detailed records for each release, which include information on breaking changes, new features, enhancements, and bug fixes.

Code Review

All projects must gate merging pull requests on code reviews that audit not only for style but also substance, such as whether security invariants are properly maintained by the new code.

Core projects must maintain a CODEOWNERS file and use it to automatically assign reviewers to pull requests. Auto-assigned reviewers must respond to pull requests in a timely fashion. However, that response doesn't have to be a full code review; it could also be

• "I intend to review this but I can't immediately. Please leave me a message if I haven't responded by $SPECIFIC_DATE_IN_NEAR_FUTURE."
• "I think $SPECIFIC_OTHER_MAINTAINER should review this." (Note that the best reviewer for a PR may not necessarily be listed in the CODEOWNERS file.)

Code reviews have a demonstrable impact on the quality of source code by catching bugs early, determining the best possible implementation, and fostering trust within the community. Timely responses let contributors know that their work is valued and encourages further contribution.

WAMR has a CODEOWNERS to oversee all incoming pull requests. All reviewers in this file will be automatically assigned and notified to review the PRs.

To ensure that every PR is thoroughly reviewed and to prevent insufficient consideration, WAMR requires at least two approvals for every PR.

Good recent examples include:

• Add support for multi-memory proposal in classic interpreter
• aarch64 AOT module fails to load on android

Code of Conduct

All Bytecode Alliance projects must:

• link to the Bytecode Alliance's Code of Conduct documents from a CODE_OF_CONDUCT.md file in root of the repository, and
• enforce the codes of conduct among the community and contributors, or escalate to the Bytecode Alliance CoC Team, if needed.

Having a code of conduct is crucial for creating a positive and respectful environment in any organization, community, or group. It serves as a set of guidelines that outline expected behavior and ethical standards for all members involved.

WAMR maintains a CoC in the repository and takes the enforcement of the CoC very seriously.

To date, all contributors have fully adhered to the CoC, showing respect for community members.

Continuous Fuzzing

Not all projects will necessarily benefit from fuzzing, for example benchmark suites. The TSC may choose lift this requirement for a particular project.

It is required that core projects have continuous fuzzing, for example in OSS-Fuzz. The fuzzing must exercise significant amounts of the code base and test the project's most important properties, such as sandboxing. Bugs and vulnerabilities discovered via fuzzing must be addressed promptly.

Part of our open-source and open contribution model, the corpus and setup for running fuzzing must be open-sourced as part of the project.

Faults discovered via fuzzing must be reported privately to the project's core team so that the project's security vulnerability process can be followed properly, if necessary. For example, fuzzing infrastructure must not automatically open public issues for any fault that is discovered.

Continuous fuzzing is a valuable practice for projects, due to its significant benefits in improving security and reliability. Within the Bytecode Alliance, we host projects that provide a sandbox. The fidelity of these sandboxes must be battle-tested via a number of methodologies including automated fuzzing.

WAMR has established continuous fuzz testing on the OSS-Fuzz platform. WAMR utilizes this to test the loader's ability to validate. WAMR previously assumed that there would be no security issues if the loader could prevent all malformed binaries from executing. Moving forward, to conform to the BA's definition of security issues, WAMR will expand fuzz testing to include the instantiation and execution phases. This will help to enhance the overall security level.

Continuous Integration Testing

All projects must run continuous integration (CI) tests on all pull requests and merges. Key project features must be covered by CI.

If any part of the CI gates on merging changes that is not reproducible by external contributors, then the project must make affordances to support those external contributors.

Implementing CI offers several benefits to software projects, helping ensure correctness and quality, making it an essential practice for modern software development.

WAMR utilizes GitHub Actions to execute a large number of test cases on every pull request, every merge, and on a scheduled basis. These test cases cover:

• Multiple platforms, including Linux, Windows, macOS, NuttX, and SGX in simulation.
• Various types of tasks, such as verifying different combinations of compilation options, confirming samples, running unit tests, running integration tests, running specification tests, running WASI tests, and running sanitizers.

Contributor Documentation

All projects must have a CONTRIBUTING.md document in the root of their repository. This document must provide, or link to another form of project-specific documentation that provides, high-quality contributor documentation.

See "How to build a CONTRIBUTING.md" by the Mozilla Science Lab for more details on what a high-quality CONTRIBUTING.md file looks like.

A CONTRIBUTING.md serves as a guide for potential contributors, outlining the expectations for individuals who wish to contribute to the project. The Bytecode Alliance is a community-driven software foundation and documents like CONTRIBUTING.md are necessary for fostering community contributions.

WAMR maintains a CONTRIBUTION to provide developers with foundational knowledge. Furthermore, WAMR provides an extensive collection of documentation to assist developers in getting started. This documentation offers guidance on setting up the development environment, building the runtime, understanding and tuning the memory model, integrating WAMR on various platforms and embedding into another project.

End-User Documentation

We abide by the OpenSSF requirements for documentation:

The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so).

Furthermore, we identify a few different types of (sometimes overlapping) documentation:

• API documentation: Documentation for each type, method, function, and module in a library.
• Architectural overviews: High-level documentation about the architecture of the project and how it works from a 1000-foot view that helps endusers take advantage of the project in the best way possible and helps onboard new contributors.
• Examples: Code examples that show off how to use the project as a whole or particular features it supports.
• Guides and tutorials: Long-form prose, with code samples interspersed, that shows how to accomplish a task using the project.

All of the above types of documentation are required for core projects.

Documentation is necessary for end-users to productively use the project; source code comments are not sufficient.

WAMR keeps online documentation up to date to assist individuals in using, learning about, contributing to, and embedding WAMR. Maintainers periodically review the documentation to ensure it remains current.

In addition to written documents, WAMR offers diagrams to visualize concepts and internal data structures. Examples are also provided as another way to convey ideas to end users, and they are often the most effective method as we learned.

Following the Bytecode Alliance Operational Principles

All projects must follow the Bytecode Alliance Operational Principles.

In pursuing our mission and vision, the Bytecode Alliance follows a set of operational principles aimed at keeping us aligned on three key aspects: what we want to create, how we want to work together, and how we want to work with others.

WAMR adheres to the operational principles of the Bytecode Alliance. WAMR is driven by product implementation challenges and community needs. WAMR approaches post-MVP features, the component model, and new WASI proposals with caution. WAMR assists users in implementing WebAssembly technology on embedded devices by overcoming resource constraints and meeting stringent stability requirements.

WAMR adheres to the standardization process and utilizes non-official proposal features to align with product timelines. WAMR employs compilation options to separate each feature from the MVP-compatible code base. Users can configure their unique runtime libraries to meet specific requirements.

Issue Triage Process

Core projects must use an issue tracker for tracking individual issues.

Core projects must have a documented process for expeditiously triaging incoming issues and pull requests, and follow that process. Contributors should get prompt responses to their issues and pull requests, even if a response is not an immediate fix or review.

For a successful community-driven project, expedient communication within issues and PRs encourages further collaboration and contribution.

WAMR uses GitHub issues to track issues and pull requests. Users can collaborate on the same platform and share their ideas.

The TSC meeting and the monthly community meeting are utilized to share requirements and statuses, make technical decisions, and announce new features and products across different teams.

Leverage the Bytecode Alliance RFC Process

A request for comments (RFC) is a technique for soliciting the community and contributors for feedback on proposed major changes and decisions.

Core projects must follow the Bytecode Alliance RFC process for changes that significantly affect project stakeholders or contributors. The RFCs repo describes when an RFC is needed in more detail:

Many changes to Bytecode Alliance projects can and should happen through every-day GitHub processes: issues and pull requests. An RFC is warranted when:

• The work involves changes that will significantly affect stakeholders or project contributors. Each project may provide more specific guidance. Examples include:
  • Major architectural changes
  • Major new features
  • Simple changes that have significant downstream impact
  • Changes that could affect guarantees or level of support, e.g. removing support for a target platform
  • Changes that could affect mission alignment, e.g. by changing properties of the security model
• The work is substantial and you want to get early feedback on your approach.

This is a best practice for aligning contributors, the community, and downstream project's needs with proposed technical implementations.

WAMR uses the RFC process to announce new features to the community and to gather as wide a range of discussion as possible.

Licensing Compatible with the Bytecode Alliance

All projects must be licensed under the Apache 2.0 license with an LLVM exception. Exemptions may be granted by the board.

All projects must only use dependencies and third-party code licensed under one of the following open source licenses:

• Apache-2.0 WITH LLVM-exception
• Apache-2.0
• BSD-2-Clause
• BSD-3-Clause
• ISC
• MIT
• MPL-2.0
• OpenSSL
• Unicode-DFS-2016
• Zlib

All dependencies and third-party code must be properly attributed.

The source for all projects must be available to all members and must be available to all non-members under the same license.

All projects must automatically ensure that licensing requirements of dependencies are met in CI.

We strive to build an open community and a legally-compatible software ecosystem.

WAMR fully complies with the BA's licensing requirements. All code is licensed under the Apache License 2.0 with LLVM exception. The licenses for all third-party dependencies are documented in the ATTRIBUTIONS.md.

Production Use

Core projects must have demonstrated use in production by at least three independent organizations which are, in the TSC's judgement, of adequate quality and scope.

It is recommended that projects track production usage by organizations in an ADOPTERS.md at the root of the project, for example see ADOPTERS.md in Wasmtime.

In order to become a core project, that project must demonstrate that it is practical, useful, and reliable enough to use in production.

WAMR maintains an ADOPTERS.md to list a small partial of the production uses that are permitted to be published. Many customers prefer to keep their use of embedded WASM runtime technology confidential. Several products using WAMR have been extensively deployed in military devices.

Public Project Meetings and Notes

Core projects must hold regular and public project meetings. Meeting times and frequency must be advertised publicly, for example in the project's CONTRIBUTING.md. To avoid spam and "Zoom bombing", the video conferencing link need not be public, but must be available upon request.

Agendas for upcoming meetings and notes from past meetings must be published publicly. The notes should be in the bytecodealliance/meetings repository.

Public meetings encourage open communication, collaboration, and engagement within the project's community. Notes allow community members who were not present to remain aligned and can document any decisions made during the meeting.

WAMR holds a community meeting every month. These meetings are open to all members of the community. Everyone can access the meeting link on Zulip. Agendas and meeting notes are stored within the BA meeting repo.

README

All projects must have a README.md file in the root of the repository which begins with:

• The project name and logo (if one exists)
• A one-sentence description of the project
• <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> core project</strong>

The most important information about the project should be "above the fold". Projects should identify themselves as Bytecode Alliance projects so that with time they associate the Bytecode Alliance with quality projects that they can rely on.

WAMR maintains a top level README.md to provide a brief overview of the project. Additionally, there are detailed documents categorized into multiple topics stored in the docs.

Release Process

Documentation of a release process that any project maintainer may execute to create a new release version of the software.

Multiple people must have permissions to publish releases. A github team must have access to publish packages and package ownership on the associated package repository when possible. For example a Rust project may have multiple owners on crates.io.

Core projects must additionally leverage a fully-automated release process, where the only manual step performed by project maintainers is to trigger the process (for example by starting a github workflow or merging an automated pull request).

Projects and their releases shouldn't be tied to any single user's machine or keys to ensure continuity of the project. A project isn't an open, community project if only one person can publish releases.

Automation makes fewer mistakes than humans, and getting releases right is critical, since only releases are typically used downstream, not random commits from main.

WAMR employs an actions script to handle the whole process for a release. This process typically includes a manual review before the official release is published.

A release is triggered by community demand and if there is a modification that affects compatibility and/or introduces new features. WAMR aims not to burden customers with too many releases.

Sanitizers and Code Analysis

Static and dynamic code analysis tools (such as valgrind or miri) where applicable must be used by core projects.

Core projects with non-trivial amounts of unsafe code (e.g. unsafe in Rust or any C/C++) must run tests and fuzzers with the relevant sanitizers: Address Sanitizer, Memory Sanitizer, Thread Sanitizer, etc.

Automated code analysis is key to meeting our mission of developing runtime environments and language toolchains where security, efficiency, and modularity can all coexist.

Multiple sanitizers, including undefined behavior, address, and thread sanitizers, are integrated into CI system to scan the main branch of WAMR every night.

WAMR also employs oss-fuzz to continuously run the asan and usan.

CodeQL is also integrated into CI system to scan the code every night.

Security Process

All projects must have a documented security process for reporting and disclosing vulnerabilities, managing patches that fix vulnerabilities, and announcing and making available security releases. Furthermore, projects must actually follow their documented processes.

Core projects must request Common Vulnerability and Exposure (CVE) numbers for discovered vulnerabilities and report the CVE when disclosing the vulnerability.

A tool like dependabot should be used for security updates only, and not apply all updates indiscriminantly. Updating dependencies should otherwise be done with intention (never automatically). Automatic creation of pull requests is acceptable, but manual review is required to prevent supply chain attacks.

Bytecode Alliance projects must be a secure foundation for others to build upon. Transparency and a managed security release process is key to being this foundation.

WAMR uses the same security policy published by the Bytecode Alliance to instruct developers on how to report and work on security issues.

Security advisories managed by GitHub have been utilized to disclose any security issues from the beginning.

Semantic Versioning

All projects must follow either standard semantic versioning or their ecosystem's local-dialect of semantic versioning (for example, Rust and cargo's interpretation of semantic versioning slightly differs from the standard, but is acceptable for Rust Bytecode Alliance projects).

A clear versioning scheme is necessary for end-users. We desire consistency across projects and so the Bytecode Alliance has adopted semantic versioning as a required best practice.

WAMR adheres to the best practices outlined by Semantic Versioning 2.0.0. Different major versions indicate changes that are not backward compatible. Minor versions typically introduce new features. Patch versions are reserved for bug fixes and security patches.

Secrets Management

GitHub organization and repository level secrets should be used. Secrets must not be hard coded in source.

For secrets like passwords for the project's associated social media account, these should be stored in the password service paid for by the Bytecode Alliance. Contact the TSC for access and ability to manage a given secret.

Secure secret management is a requirement for a secure project. Additionally, projects and their associated accounts shouldn't be tied to any single user's machine or keys to ensure continuity of the project. A project isn't an open, community project if only one person can access its accounts.

All necessary secrets are managed under the control of the Bytecode Alliance organization. This is achieved through the use of GitHub's secrets management system.

Supply Chain Security

All projects must follow a well-documented process for updating dependencies and auditing them for malicious supply-chain attacks.

When applicable, projects should:

• Integrate auditing tools in CI (such as cargo vet)
• Use code review and static analysis tools on dependencies

Finally, projects must document and follow their process for responding to upstream vulnerabilities in dependencies.

Our mission of developing runtime environments and language toolchains where security, efficiency, and modularity can all coexist necessarily means that we have performed our due dilligence to mitigate software supply chain attacks.

WAMR incorporates a Scorecard check as part of its CI process to continuously monitor the security status of its dependencies.

There are no universally accepted methods for managing dependencies in C/C++. Our approach is to use release notifications to monitor each release and determine if it contains any critical security patches that necessitate merging the new release. If not, compatibility with existing APIs and performance remain the top priorities.

Dependabot assists us in keeping track of the latest releases and security alerts of our dependencies. The maintainers will review the pull requests generated by Dependabot before merging them.

Sustainable Contributor Base

All projects must have regular contributions from multiple contributors.

Core projects must have contributors affiliated with at least two different Bytecode Alliance organizations and the project leadership must have representation from at least two different Bytecode Alliance organizations.

There must not be any private information necessary to fully contribute to the project.

A project is not considered healthy with only one contributor. An open, community project requires input from multiple stakeholders and does not rely on a single person.

Since the inception of WAMR project, there have been 171 contributors. In addition to the original team, an increasing number of contributors from various companies, such as Midokura, Netflix, Xiaomi, and Amazon, have become active over the past 12 months.

All contributors come from a diverse range of organizations, including members of the Bytecode Alliance like Amazon, Midokura, Microsoft, and Siemens.

Version Control

All projects must be hosted on the Bytecode Alliance Organization on GitHub.

Access controls are managed via the Bytecode Alliance organization on GitHub. This allows for continuity of the project when hosted in one place. Finally, this is the only way to reasonable manage the projects within the organization.

WAMR and its main dependencies are available on GitHub and use git for version control. All third-party dependencies are listed in ATTRIBUTIONS.md.

[tschneidereit]

Hi @lum1n0us, thank you for the submission, and apologies for the late reply! Over the xmas holidays and through New Year, many people are out, leading to slow responses.

The TSC will evaluate the submission, follow up with requests for clarification or further information where needed, etc. Note though that the final decision on the submission will be up to the board of directors, as described here.

CC @bytecodealliance/tsc, @bytecodealliance/board