diff --git a/projects/microcks/governance-review/2026-05-25.md b/projects/microcks/governance-review/2026-05-25.md new file mode 100644 index 000000000..53ae49ef3 --- /dev/null +++ b/projects/microcks/governance-review/2026-05-25.md @@ -0,0 +1,232 @@ + + +# **Governance Review: Microcks** + +**Reviewer:** Carol Valencia (krol3 github) **Date:** 2026-05-25 + **Review Type:** Incubation (Post-Acceptance Update) + **Project Repository:** [https://github.com/microcks/microcks](https://github.com/microcks/microcks) + **CNCF Stage:** Incubation (accepted 2026-05-07) + +--- + +## **Executive Summary** + +Microcks is a CNCF Incubating project providing open source tooling for API mocking and contract testing across REST, gRPC, GraphQL, and event-driven protocols. This document is an updated governance review to reflect that Microcks was formally accepted as a CNCF Incubating project on May 7, 2026 (TOC Issue [\#1552](https://github.com/cncf/toc/issues/1552)). + +Several findings from the April draft have been resolved prior to or concurrent with acceptance: a third Maintainer from an independent organisation (AXA France) has been formally added, a `SECURITY.md` is now present in the primary repository, the OpenSSF Best Practices badge has been confirmed, and the `GOVERNANCE.md` has been materially expanded to include a contributor ladder, explicit voting procedures, a Steering Committee charter, and a documented emeritus process. + +The principal remaining recommendations concern maintainer diversity (two of three Core Maintainers remain Postman-affiliated), the addition of objective quantitative promotion thresholds to the contributor ladder, and the publication of a consolidated sub-project inventory. + +--- + +## **Project Description** + +Microcks ([https://microcks.io](https://microcks.io)) is a cloud-native API mocking and testing platform that supports REST/OpenAPI, gRPC, GraphQL, AsyncAPI, and SOAP interfaces. Created in 2015 by Laurent Broudoux, it was donated to the CNCF as a Sandbox project on 22 June 2023 and graduated to Incubating status on 7 May 2026\. + +The platform integrates natively with Kubernetes via a dedicated operator and provides contract-testing capabilities aligned with API-first development practices. The project now lists **36 public adopters** ([ADOPTERS.md](https://github.com/microcks/.github/blob/main/ADOPTERS.md)), spanning financial services (BNP Paribas, Société Générale, Lombard Odier, Banco PAN), logistics (J.B. Hunt), healthcare (CNAM, Waymark Health), telecom (GSMA), consulting (Deloitte, Agile Actors), and cloud-native infrastructure. + +Container image downloads exceeded **2.5 million in 2025**, a 3× increase over 2024\. + +--- + +## **Governance Overview** + +Microcks operates under a Maintainer-council governance model documented in `GOVERNANCE.md`, stored in the organisation-level [`.github` repository](https://github.com/microcks/.github/blob/main/GOVERNANCE.md) and automatically replicated across all organisation repositories via GitHub Actions. The model defines four roles: **Maintainer**, **Code Owner** (alias Domain Maintainer), **Contributor**, and **Adopter**. Maintainers hold binding votes over the entire project and organisation; Code Owners hold scoped authority over specific sub-projects or domains. Decision-making requires a supermajority (66%) of maintainer votes, with a two-week voting deadline. Governance changes themselves require 66% approval by PR review or vote. A **Steering Committee (SC)** has been introduced to represent the adopter voice in strategic roadmap decisions, governed by a dedicated charter at [microcks/community/steering/STEERING.md](https://github.com/microcks/community/blob/main/steering/STEERING.md). The overall model is consistent with similarly sized CNCF Incubating projects and has matured meaningfully since the April 2026 draft. + +--- + +## **Governance Assessment** + +### **Governance Documentation** + +The `GOVERNANCE.md` file in [microcks/.github](https://github.com/microcks/.github/blob/main/GOVERNANCE.md) is the canonical governance document, automatically synchronised to all repositories. As of May 2026 it spans 97 lines and covers: guiding principles (open, transparent, merit-based, vendor-neutral), all four role definitions and their scope, a contributor ladder with advancement criteria, the voting-in/voting-out process for Maintainers, the Code Owner appointment process, the emeritus transition path, sub-project lifecycle policy, conflict-resolution procedures, community meeting structure, the new Steering Committee, and governance amendment rules. The document credits and builds on governance patterns from CoreDNS, Kyverno, OpenEBS, and fluxcd. + +A mirrored `GOVERNANCE.md` is now also present directly in the primary `microcks/microcks` repository root, meaning the governance document is surfaced alongside the codebase without requiring a cross-repository link. `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are also present and link to `GOVERNANCE.md`. The CLOMonitor score for the project is **98 (A grade)**, confirming broad compliance with CNCF community health file requirements. + +The document does not carry a "last reviewed" or "last updated" date stamp in its header, which would help future reviewers confirm currency. This is a minor recommendation. + +### **Roles and Contributor Ladder** + +The `GOVERNANCE.md` now documents four roles with clear scope distinctions. The contributor ladder section specifies that advancement to Maintainer requires: + +* **Participation:** Three months or more, including discussions, contributions, and code or documentation reviews. +* **Collaboration:** Demonstrated ability to work with others, take on new ideas, and help others succeed. +* **Availability** (ideally full-time): Reachable on Slack, Discord, GitHub, and email. +* **Respect:** Alignment with Microcks and CNCF code of conduct and guiding principles. + +The voting-in procedure is clearly defined: a public nomination at a community meeting, a PR to the centralised MAINTAINERS file, a two-week public comment and vote period, and a 66% supermajority threshold. The process has demonstrably been applied: Sebastien Degodez was promoted from Code Owner to Maintainer via this mechanism. + +The criteria remain predominantly qualitative. The three-month participation floor is a useful minimum, but the ladder does not yet specify quantitative thresholds (e.g., number of merged contributions, percentage of community meetings attended, or number of PR reviews completed). More objective thresholds would reduce ambiguity in borderline cases and are recommended before the project applies for graduation. + +### **Maintainer List and Succession** + +The `MAINTAINERS.md` in the primary repository ([microcks/microcks/MAINTAINERS.md](https://github.com/microcks/microcks/blob/master/MAINTAINERS.md)) lists the following as of May 2026: + +**Maintainers (Full Binding Vote):** + +| Name | GitHub ID | Affiliation | +| ----- | ----- | ----- | +| Laurent Broudoux | [@lbroudoux](https://github.com/lbroudoux) | Sponsored by Postman | +| Yacine Kheddache | [@yada](https://github.com/yada) | Sponsored by Postman | +| Sebastien Degodez | [@SebastienDegodez](https://github.com/SebastienDegodez) | AXA France | + +**Code Owners (Domain Scope):** + +| Name | GitHub ID | Affiliation | Domain | +| ----- | ----- | ----- | ----- | +| Harshvardhan Parmar | [@Harsh4902](https://github.com/Harsh4902) | Yosemite Crew | Microcks CLI | +| Hugo Guerrero | [@hguerrero](https://github.com/hguerrero) | Kong (ex Red Hat) | Docker Desktop Extension | + +**Emeritus:** + +| Name | GitHub ID | Affiliation | Sub-Projects | +| ----- | ----- | ----- | ----- | +| Julien Breux | [@JulienBreux](https://github.com/JulienBreux) | Google | Microcks CLI, Microcks Go Client | + +The addition of Sebastien Degodez (AXA France) as a full Maintainer is a material improvement over the April 2026 state, where all Core Maintainer authority resided with two Postman-affiliated co-founders. Vendor distribution now stands at 2/3 Postman-affiliated, 1/3 independent. While this improvement is meaningful and addresses the prior Risk finding, two of three Maintainers remain sponsored by a single organisation. The project should continue to grow independent Maintainers toward a plurality. + +The Emeritus section is now formally present in MAINTAINERS.md with at least one confirmed transition (Julien Breux), demonstrating the process is operational and not merely documented. This closes the emeritus risk from the April draft. + +Both Laurent Broudoux and Yacine Kheddache remain verifiably active, with commits and community engagement observed through May 2026\. Sebastien Degodez's activity as a Code Owner prior to promotion and as a Maintainer post-promotion is visible in GitHub history. + +The MAINTAINERS file notes it applies to every sub-project, repository, and file within the Microcks GitHub organisation — making scope of authority explicit. + +### **Decision-Making Process** + +The governance document specifies consensus as the default, with voting via the CNCF [GitVote](https://github.com/cncf/gitvote) application when consensus cannot be reached. A supermajority (66%) of maintainer votes is required for significant decisions, including governance changes; the Project Lead holds the final say in the event of a tied or disputed outcome. The two-week voting deadline with early-close at 66% approval is clearly defined. All votes are recorded as GitHub PR comments, creating a public and verifiable audit trail. + +The `GOVERNANCE.md` also specifies that maintainers may hold closed meetings to discuss security reports or Code of Conduct violations, with all maintainers required to be invited (except any accused of a CoC violation). This is a mature provision appropriate for an Incubating project. + +Community meeting notes and recordings are referenced through the community repository, though comprehensive archiving of all 2024–2025 meeting notes in a searchable public location was not fully verified during this review. The project is encouraged to ensure that summaries of significant decisions taken at community calls are recorded in the community repository within one week of each meeting. + +### **Security Response Process** + +A `SECURITY.md` file is now confirmed present in the primary `microcks/microcks` repository ([visible in repository file listing](https://github.com/microcks/microcks)), closing the principal security documentation gap identified in the April 2026 draft. The file provides the security contact email (`security@microcks.io`) for private vulnerability disclosure and references GitHub Private Security Advisories. + +The project has confirmed engagement with supply chain security tooling: + +* **FOSSA license and security scans** are integrated and badged in the README. +* **SECURITY-INSIGHTS.yml** files are present across multiple sub-project repositories. +* **OpenSSF Best Practices badge** is confirmed at [bestpractices.coreinfrastructure.org/projects/7513](https://bestpractices.coreinfrastructure.org/projects/7513), resolving the prior uncertainty. +* **OpenSSF Scorecard** badge is present and links to [securityscorecards.dev/viewer/?uri=github.com/microcks/microcks](https://securityscorecards.dev/viewer/?uri=github.com/microcks/microcks). +* **SonarCloud** quality and security rating badges are present in the README. +* **Signature, provenance, and SBOM** documentation is referenced at [microcks.io/documentation/references/container-images\#software-supply-chain-security](https://microcks.io/documentation/references/container-images#software-supply-chain-security). + +The specific response SLA (e.g., acknowledgement within N business days) and the coordinated disclosure timeline (e.g., 90-day embargo) were not confirmed as explicitly documented in SECURITY.md during this review. The project should ensure these are stated in the document to meet the standard expected of CNCF Incubating projects. + +No public CVE disclosures were identified. Given the project's production adoption footprint, the absence of public CVEs may reflect a low vulnerability surface, responsible handling of disclosures, or simply the project's relatively early security maturity history. + +### **Code of Conduct** + +The project adopts the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) by reference. The `CODE_OF_CONDUCT.md` is present in the [`.github` repository](https://github.com/microcks/.github/blob/main/CODE_OF_CONDUCT.md) and propagated organisation-wide. The `GOVERNANCE.md` explicitly links to the CoC and states that maintainers hold closed meetings to handle CoC violation reports. + +The CNCF CoC Committee (`conduct@cncf.io`) was established in October 2024 and provides the escalation path for complaints involving project Maintainers, which resolves the concern raised in the April draft about the adequacy of the `info@microcks.io` enforcement contact for maintainer-involving cases. The `GOVERNANCE.md` states that any maintainer accused of a CoC violation is excluded from the closed meeting convened to address it, which is sound procedural design. + +One remaining note: the primary enforcement contact visible in `CODE_OF_CONDUCT.md` should clearly reference `conduct@cncf.io` for maintainer-involving reports, in addition to any project-level contact, so that reporters are aware of the CNCF escalation path. + +### **Project Health and Community Activity** + +Microcks demonstrate a healthy and sustained release cadence. The current stable release is **1.13.2** (released January 6, 2026; the April draft referenced 1.13.0 as the latest). The `1.13.x` maintenance branch is active with a `1.13.3-SNAPSHOT` in progress. The `1.12.x` branch is also under active maintenance. Each major release in the 1.11–1.13 series resolved 60–80 issues with approximately 12 active contributors per release. + +Community health metrics as of the incubation application (May 2026): + +* **Stars:** 1.9k on the primary repository; **Forks:** 331\. +* **Total contributors (GitHub):** 73 on primary repository; **LFX Insights:** 761 total contributors across the organisation. +* **Active contributors (1Y):** 208 (LFX); **51 active contributors in the last quarter** with a 57% quarter-over-quarter retention rate (rated "Excellent" by LFX). +* **Contributing organisations in 2025:** 167 active contributors representing **35 organisations**. +* **CLOMonitor score:** 98 (A grade). +* **Container downloads:** 2.5 million+ in 2025 (3× the 2024 total). + +The contributor count concern raised in the April draft (19% YoY decline from a cumulative 633\) requires contextualisation in light of the LFX data showing 51 active contributors in the last quarter and a 57% QoQ retention rate rated "Excellent." The apparent decline in some metrics likely reflects a normalisation following the burst of activity at CNCF Sandbox acceptance in 2023, not a structural contraction. The incubation application explicitly addresses this. + +The project hosts two monthly community meetings in APAC-friendly (2nd Thursday, 09:00 CET) and Americas-friendly (4th Thursday, 18:00 CET) time slots, documented at [community/JOIN-OUR-MEETINGS.md](https://github.com/microcks/community/blob/main/JOIN-OUR-MEETINGS.md). The project continues to participate in the LFX Mentorship programme. A public **ROADMAP.md** is present in the primary repository. + +Public adopters have grown to **36 organisations** as of this review (up from 16+ in the April draft), with 13 new adopters added in 2025 alone. Adopters span financial services, healthcare, logistics, telecom, consulting, and cloud-native tooling. + +### **Subproject Governance** + +The Microcks GitHub organisation ([github.com/microcks](https://github.com/microcks)) hosts several actively maintained sub-projects: + +* **microcks-operator** — Kubernetes Operator; maintains own `MAINTAINERS.md` +* **microcks-cli** — CLI tool; Code Owner: Harshvardhan Parmar (Yosemite Crew) +* **microcks-quarkus** — Quarkus integration library; maintains own `MAINTAINERS.md` +* **microcks-backstage-provider** — Backstage plugin; maintains own `GOVERNANCE.md` +* **microcks-postman-runtime** — Postman test bridge; maintains own `DEPENDENCY_POLICY.md` and `SECURITY-INSIGHTS.yml` +* **microcks-docker-desktop-extension** — Docker Desktop integration; Code Owner: Hugo Guerrero (Kong) +* **hub.microcks.io** — Community API artefact hub + +Each sub-project benefits from the centrally replicated community health files. The `GOVERNANCE.md` states that Maintainers have authority to add or remove sub-projects and that removed sub-projects are archived in the `microcks-archive` organisation for historical reference. The sub-project lifecycle policy is clearly defined at the organisational level. + +The `microcks-backstage-provider` sub-project maintains a dedicated `GOVERNANCE.md`, which is a positive practice. However, there is still no single consolidated inventory document listing all active sub-projects, their maturity level, and their current Code Owner assignments. Publishing such an index would improve transparency for the TOC and for prospective contributors. + +### **Community** + +**community meeting notes archived publicly** + +Community meeting structure and how-to-join instructions are documented at [microcks/community/JOIN-OUR-MEETINGS.md](https://github.com/microcks/community/blob/main/JOIN-OUR-MEETINGS.md). Comprehensive archiving of meeting notes in a searchable format was not fully verified during this review. Outstanding. + +--- + +## **Findings Summary** + +### **Observations** + +* Microcks was accepted as a CNCF Incubating project on 7 May 2026 (TOC Issue [\#1552](https://github.com/cncf/toc/issues/1552)), reflecting the project's technical maturity and community health. +* The `GOVERNANCE.md` has been materially expanded since 2025 to include a detailed contributor ladder, explicit voting procedures (66% supermajority, two-week deadline), a Steering Committee, an emeritus process, and conflict-resolution procedures. The document now references and acknowledges CNCF vendor-neutrality principles explicitly. +* A third Maintainer, Sebastien Degodez (AXA France), has been added via the documented voting process, demonstrating that the process is operational and that the project is actively growing independent maintainership. +* An Emeritus section is present in `MAINTAINERS.md` and has been used (Julien Breux, formerly of Google, is listed), confirming the process is functional rather than merely documented. +* The `SECURITY.md` file is now present in the primary repository, and the project has deployed a comprehensive set of supply chain security tooling: FOSSA, SECURITY-INSIGHTS.yml, OpenSSF Best Practices badge (project 7513), OpenSSF Scorecard badge, SonarCloud scanning, and container image provenance/SBOM documentation. +* Public adopter count has grown from 16+ at the time of the April draft to 36 confirmed public adopters, spanning 10+ countries and multiple industry verticals, with 13 organisations added in 2025 alone. Container image downloads exceeded 2.5 million in 2025\. +* The project achieved a CLOMonitor score of 98 (A grade), indicating strong compliance with CNCF community health file expectations. +* The project hosts two monthly community meetings at APAC-friendly and Americas-friendly times; a public `ROADMAP.md` is present; and the project participates in LFX Mentorship. +* Most sub-projects maintain their own `MAINTAINERS.md` and `CODEOWNERS` files. The `microcks-backstage-provider` sub-project additionally maintains a dedicated `GOVERNANCE.md`. Removed sub-projects are archived in `microcks-archive`. + +### **Recommendations** + +* **Add quantitative thresholds to the contributor ladder.** The current criteria (three months participation, collaboration, availability, respect) are meaningful but predominantly qualitative. Adding objective minimums (e.g., a specified number of significant merged contributions, a minimum PR review count, or confirmed attendance at a percentage of community meetings) would reduce ambiguity and support consistent application as the project scales toward graduation. +* **Explicitly state the security response SLA and disclosure timeline in `SECURITY.md`.** The file should document: (1) the target acknowledgement window (e.g., 5 business days), (2) the coordinated disclosure embargo period (e.g., 90 days), and (3) a reference to GitHub Private Security Advisories. This is standard practice for CNCF Incubating projects and will be required for graduation. +* **Ensure `CODE_OF_CONDUCT.md` explicitly references `conduct@cncf.io`** as the escalation path for maintainer-involving reports, so that reporters are clearly directed to the CNCF CoC Committee. The project-level `info@microcks.io` contact may remain for general enquiries. +* **Publish a sub-project inventory.** A single document listing all active repositories in the Microcks organisation, their maturity status, current Code Owner or Maintainer assignments, and lifecycle stage would make the scope of the project legible to external reviewers and prospective contributors. +* **Add a "last reviewed" date to `GOVERNANCE.md`** to allow future reviewers to confirm document currency at a glance. +* **Continue growing independent Maintainers.** With two of three current Maintainers sponsored by Postman, the project should articulate a concrete target (e.g., majority of Maintainers from independent organisations by graduation) and timeline. The Steering Committee's adopter representation is a positive structural complement but does not substitute for independent Maintainer diversity at the binding-vote level. + +### **Risks** + +* **Residual Postman concentration in Core Maintainership.** Two of three current Maintainers (Laurent Broudoux and Yacine Kheddache) are listed as "Sponsored by Postman." While the addition of Sebastien Degodez (AXA France) as a full Maintainer materially reduces the bus factor compared to the April 2026 state, a single organisation still holds a majority (2/3) of binding votes. This does not rise to a blocker at the Incubation stage — the project has demonstrated active progress toward diversity — but it must be resolved before graduation. *([MAINTAINERS.md](https://github.com/microcks/microcks/blob/master/MAINTAINERS.md))* + +--- + +## **References** + +* [Microcks GitHub Organisation](https://github.com/microcks) +* [Microcks Primary Repository](https://github.com/microcks/microcks) +* [Microcks MAINTAINERS.md](https://github.com/microcks/microcks/blob/master/MAINTAINERS.md) +* [Microcks GOVERNANCE.md (.github)](https://github.com/microcks/.github/blob/main/GOVERNANCE.md) +* [Microcks .github Community Health Repository](https://github.com/microcks/.github) +* [Microcks Community Repository](https://github.com/microcks/community) +* [Microcks Community Meetings](https://github.com/microcks/community/blob/main/JOIN-OUR-MEETINGS.md) +* [Microcks Steering Committee Charter](https://github.com/microcks/community/blob/main/steering/STEERING.md) +* [Microcks ADOPTERS.md (.github)](https://github.com/microcks/.github/blob/main/ADOPTERS.md) +* [Microcks ADOPTERS.md (main repo)](https://github.com/microcks/microcks/blob/master/ADOPTERS.md) +* [Microcks SECURITY.md](https://github.com/microcks/microcks/blob/master/SECURITY.md) +* [Microcks backstage-provider GOVERNANCE.md](https://github.com/microcks/microcks-backstage-provider/blob/main/GOVERNANCE.md) +* [Microcks ROADMAP.md](https://github.com/microcks/microcks/blob/master/ROADMAP.md) +* [CNCF TOC Incubation Application Issue \#1552](https://github.com/cncf/toc/issues/1552) +* [CNCF Blog: Microcks becomes a CNCF incubating project (2026-05-07)](https://www.cncf.io/blog/2026/05/07/microcks-becomes-a-cncf-incubating-project/) +* [Microcks CNCF Project Page](https://www.cncf.io/projects/microcks/) +* [Microcks 1.13.0 Release Notes](https://microcks.io/blog/microcks-1.13.0-release/) +* [Microcks 1.13.2 Release](https://github.com/microcks/microcks/releases/tag/1.13.2) +* [Microcks GitHub Releases](https://github.com/microcks/microcks/releases) +* [Microcks DevStats](https://microcks.devstats.cncf.io/) +* [Microcks LFX Insights](https://insights.linuxfoundation.org/project/microcks/repository/microcks-microcks) +* [OpenSSF Best Practices — Microcks (project 7513\)](https://bestpractices.coreinfrastructure.org/projects/7513) +* [OpenSSF Scorecard — Microcks](https://securityscorecards.dev/viewer/?uri=github.com/microcks/microcks) +* [Microcks CLOMonitor](https://clomonitor.io/projects/cncf/microcks) +* [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) +* [CNCF GitVote](https://github.com/cncf/gitvote) +* [CNCF Governance Review Handbook](https://github.com/cncf/toc/blob/main/toc_subprojects/project-reviews-subproject/governance-review-handbook.md) +* [CNCF Governance Review Template](https://github.com/cncf/toc/blob/main/toc_subprojects/project-reviews-subproject/governance-review-template.md) +* [Microcks "Thriving Year in the CNCF Sandbox" Blog](https://microcks.io/blog/microcks-a-thriving-year-in-the-cncf-sandbox/) +* [Microcks Adopters Blog Post](https://microcks.io/blog/join-adopters-list/) +* [Supply Chain Security Documentation](https://microcks.io/documentation/references/container-images#software-supply-chain-security) + diff --git a/projects/microcks/security-assessment/images/architecture-full.png b/projects/microcks/security-assessment/images/architecture-full.png deleted file mode 100644 index 14ae1b34c..000000000 Binary files a/projects/microcks/security-assessment/images/architecture-full.png and /dev/null differ diff --git a/projects/microcks/security-assessment/images/microcks-cloud-native-ecosystem.png b/projects/microcks/security-assessment/images/microcks-cloud-native-ecosystem.png deleted file mode 100644 index dbd4139b7..000000000 Binary files a/projects/microcks/security-assessment/images/microcks-cloud-native-ecosystem.png and /dev/null differ diff --git a/projects/microcks/security-assessment/self-assessment.md b/projects/microcks/security-assessment/self-assessment.md deleted file mode 100644 index 925b158ff..000000000 --- a/projects/microcks/security-assessment/self-assessment.md +++ /dev/null @@ -1,311 +0,0 @@ -# Microcks Self-assessment - - - -March 2025, written by Microcks [Maintainers](https://github.com/microcks/.github/blob/main/MAINTAINERS.md): Yacine Kheddache([@yada](https://github.com/yada)) & Laurent Broudoux([@lbroudoux](https://github.com/lbroudoux)). - -## Self-assessment outline - -### Table of contents - -* [Metadata](#metadata) - * [Security links](#security-links) -* [Overview](#overview) - * [Actors](#actors) - * [Actions](#actions) - * [Background](#background) - * [Goals](#goals) - * [Non-goals](#non-goals) -* [Self-assessment use](#self-assessment-use) -* [Security functions and features](#security-functions-and-features) -* [Project compliance](#project-compliance) -* [Secure development practices](#secure-development-practices) -* [Security issue resolution](#security-issue-resolution) -* [Appendix](#appendix) - -### Metadata - -A table at the top for quick reference information, later used for indexing. - -||| -| -- | -- | -| Assessment Stage | Complete | -| Software | [https://github.com/microcks/microcks](https://github.com/microcks/microcks) | -| Security Provider? | No. Microcks is not be considered a security provider | -| Languages | Java | -| SBOM | Known Weakness. Automated generation of each repo's SBOM is not yet complete for all repos (6 missings on 19, see [CLOMonitor](https://clomonitor.io/projects/cncf/microcks) checks) and should be added to the roadmap to reach 100% | - -#### Security links - -| Doc | url | -| -- | -- | -| Security Policy | [Microcks Security Policy](https://github.com/microcks/.github/blob/main/SECURITY.md) | -| Security Insights | [Microcks Security Insights main repo](https://github.com/microcks/microcks/blob/master/SECURITY-INSIGHTS.yml) but 100% present on our 19 repos, see [CLOMonitor](https://clomonitor.io/projects/cncf/microcks) checks. | - -### Overview - -Microcks is a tool for **mocking and testing** your APIs and microservices. It leverages **API standards** to provide a **uniform and multi-protocol approach** for simulating complex distributed environments and validating service components in isolation. - -#### Background - -Microcks facilitates **rapid simulation generation**, **automated API testing**, and **seamless CI/CD integration**, streamlining development and deployment processes. By reducing development time, minimizing errors, and ensuring consistent API behavior across environments, Microcks enables teams to optimize services, embrace cloud-native development, and accelerate product releases. - -**The Problems**: - -* API Dependencies in Development: When building or testing a system that relies on APIs (internal or external), those APIs might not always be available, might be slow, or might not exist yet. This makes development and testing difficult. -* Realistic API Testing: Traditional unit tests don’t fully test API interactions, and manually setting up API responses is time-consuming and error-prone. -* Consistency Across Environments: Ensuring API behaviors are consistent across dev, test, and production environments is hard. Mocks can drift from reality, making tests unreliable. - -**How Microcks Solves It**: - -* API Mocking: It automatically generates realistic mock versions of APIs based on OpenAPI, AsyncAPI, or other API contracts. These mocks behave like the real API, so developers can work without waiting for an actual backend. -* Contract-Based Testing: It verifies that real APIs conform to their defined contract (e.g., OpenAPI spec) by running automated tests against them. -* Supports Multiple Protocols: Works with REST, GraphQL, gRPC, WebSockets, and event-driven APIs, making it useful for modern microservices. - -**Competitive advantage**: - -By streamlining API workflows and development life cycle, Microcks helps organizations stay ahead of competitors: - -* Faster Time-to-Market: Releasing new features and products more quickly than competitors. -* Higher Reliability: Delivering stable and well-tested APIs, reducing downtime and post-release fixes. -* Improved Developer Efficiency: Allowing teams to focus on innovation rather than manually managing mocks and test environments. -* Better Customer Experience: Ensuring APIs work as expected, leading to higher user satisfaction and retention. - -**The Core Value**: - -Microcks helps developers and testers work independently, detect API issues early such as incorrect responses, contract violations, or unexpected changes (breaking changes or regressions) and ensure that APIs behave as expected across different environments without manually maintaining mocks or writing complex test scripts. - -#### Actors - -Microcks actors are: - -* The Microcks main web application (also called webapp) that holds the UI front-end resources (HTML, JS, and CSS) as well as API endpoints. This component wraps a database for holding your data such as the repository of API simulations and Tests, - -* The Microcks Postman runtime (microcks-postman-runtime) that allows the execution of Postman Collection tests and calls back Microcks for storing results, - -* The Microcks Async Minion (microcks-async-minion) is a component responsible for publishing mock messages corresponding to AsyncAPI definitions as well as testing asynchronous endpoints. It retrieves these definitions from Microcks webapp at startup and then listens for changes on these definitions, -* A Keycloak instance that holds the authentication mechanisms and identity provider integration. - -#### Actions - -The schema below represents a full-featured architecture deployment with relations and actions between actors and connection to outer brokers. We represented Kafka ones (X broker) as well as brokers (Y and Z) from other protocols. Microcks users access the main webapp either from their browser to see the console or from the CLI or any other application using the API endpoints. - -![Microcks actions](images/architecture-full.png) - -See the [Architecture & deployment options](https://microcks.io/documentation/explanations/deployment-options/) documentation for comprehensive details. - -#### Goals - -The goal of the Microcks project is to ease cloud native applications adoption by addressing the pains of dealing with complex, distributed, and multi-protocol applications: - -* **Simplifying API Development & Testing:** Enabling teams to rapidly mock and test APIs, including REST, SOAP, GraphQL, gRPC, and AsyncAPI. -* **Enhancing API-First Practices:** Supporting contract-driven development by leveraging API specifications. Microcks verifies that real APIs conform to their defined contract (e.g., OpenAPI spec) by running manual or automated tests against them. -* **Facilitating CI/CD Integration:** Automating API testing and validation within DevOps pipelines. -* **Bridging Business and Technical Stakeholders:** Connecting API producers and consumers by ensuring standardized API specifications and seamless collaboration. - -Microcks incorporates several security measures to ensure safe API testing and mocking: - -* **Access Control & Authentication:** Supports authentication mechanisms such as OAuth2 and OpenID Connect to secure API access. Microcks secures its services using OAuth2 and OpenID authentication with Keycloak, including support for role-based access control (RBAC). Learn more here: [Microcks Security Configuration](https://microcks.io/documentation/references/configuration/security-config/#identity-management). -* **Data Integrity & Confidentiality:** Ensures proper handling of API specifications and test data, preventing unauthorized modifications. -* **Secure Deployment Options:** Can be deployed in isolated environments to restrict unauthorized access. - -#### Non-goals - -Microcks is not part of the production critical path. It is a tool designed to enhance an organization's development lifecycle and workflow. -While Microcks provides powerful API mocking, testing, and governance capabilities, there are certain aspects that are **not** within its intended scope: - -* **Not an API Gateway or Security Enforcement Tool:** - Microcks is designed for mocking and testing APIs but does not act as an API gateway, firewall, or security enforcement layer for live production traffic. -* **Not a Load Testing or Performance Benchmarking Tool:** - While Microcks can simulate API responses for testing purposes, it is not built for large-scale load testing or performance benchmarking. -* **Not a Production API Management Platform:** - Microcks does not replace full-fledged API management solutions like Kong, Apigee, or Azure API Management. It focuses on contract-driven API development and testing rather than production traffic management. -* **No Built-in Data Persistence Beyond Mocking Needs:** - Microcks does not function as a long-term API data store. While it can mock API responses, it does not store or manage large-scale application data. -* **Not a Compliance or Security Auditing Tool:** - While Microcks supports API contract validation, it does not provide formal security audits, compliance enforcement, or penetration testing capabilities. - -### Self-assessment use - -This self-assessment is created by the Microcks team to perform an internal analysis of the project's security. It is not intended to provide a security audit of Microcks, or function as an independent assessment or attestation of Microcks's security health. - -This document serves to provide Microcks users with an initial understanding of -Microcks's security, where to find existing security documentation, Microcks plans for security, and general overview of Microcks security practices, both for development of Microcks as well as security of Microcks. - -This document provides the CNCF TAG-Security with an initial understanding of Microcks to assist in a joint-assessment, necessary for projects under incubation. Taken together, this document and the joint-assessment serve as a cornerstone for if and when Microcks seeks graduation and is preparing for a security audit. - -### Security functions and features - -#### Critical Security Components - -Below are the critical security components of the Microcks project that are essential for ensuring its security. These elements are part to the overall security design of the product: - -1. **Authentication & Authorization Mechanisms** - * Microcks relies on secure authentication protocols such as OAuth2 and OpenID Connect to ensure that only authorized users have access to its features and data. These mechanisms are fundamental to protecting access to the system. - -2. **API Contract Validation** - * The core feature of Microcks is validating API implementation against their contracts, ensuring that the API implementation is not drifting from the specification including security constraints. - -3. **Secure Storage of API Specifications** - * Microcks securely stores API specifications (such as OpenAPI, AsyncAPI, gRPC protos,…) and test results. Proper handling of these files with a customizable RBAC system prevents unauthorized changes and ensures that they remain intact and secure for testing purposes. - -4. **Encryption in Transit** - * All API endpoints exposed by Microcks components are encrypted using TLS. Microcks integrates smoothly with your KPI or other CNCF project like cert-manager. This protects sensitive information from being intercepted during communication and it is essential for some adopters since Microcks can expose API mocks with examples that may contain sensitive personal information or company data. - -#### Security-Relevant Components - -These are important components of the project that contribute to enhancing the overall security of Microcks. These items should also be considered in threat modeling and can be configured or adjusted to improve the system’s security posture: - -1. **Deployment Configurations** - * Microcks can be deployed in various environments, including on-premises and cloud-based systems. Configurations such as firewall rules, secure networking setups, and containerization (e.g., Docker or Kubernetes) are critical for maintaining a secure deployment. - -2. **Access Control to connected Repositories** - * Proper access control to the repositories where Microcks is sourcing its content, particularly for those involving sensitive information, ensures that only trusted collaborators can contribute and make changes. - -3. **Logging and Monitoring** - * Microcks include logging and observability mechanisms to track the activities of the system, thanks to Prometheus and OpenTelemetry. Monitoring these logs helps detect suspicious activities, unauthorized access, or security breaches early. - -4. **API Mocking and Testing Environments** - * Microcks allows mocking and testing APIs in isolated environments. Configuring secure and properly isolated testing environments helps mitigate risks of testing on production systems or with untrusted data. - -5. **Container Security** - * Microcks components are distributed as [OCI](https://opencontainers.org/) container images that can be executed using container runtimes such as [Docker](https://www.docker.com/) or [Podman](https://podman.io/). - All our container images are scanned for vulnerabilities with both [Clair](https://www.redhat.com/en/topics/containers/what-is-clair) on [Quay.io](https://quay.io/) and [Docker Scout](https://docs.docker.com/scout/) on [Docker Hub](https://hub.docker.com/). Scanning reports are available for each image on every repository. - Regular updates and patches to container images are crucial for protecting against known vulnerabilities. - -The container images base layers as well as the Microcks application dependencies are regularly updated as per the SECURITY-INSIGHTS.yml and DEPENDENCY_POLICY.md file you may find in each GitHub source repository. See full details in our documentation: [Container Images](https://microcks.io/documentation/references/container-images/) - -These security-relevant components are crucial for the overall security of Microcks and can be adjusted based on deployment needs to improve security posture. - -### Project compliance - -* Microcks does not comply with any specific security standards. - -### Secure development practices - -As a Github hosted project, we rely on the Github authentication mechanisms. All the maintainers and bots (GitHub Actions and Workflow) use two factor authentication and sign commits. The maintainers are responsible for regularly reviewing and updating the organization's membership and ensuring that 2FA and commit signature checks are enforced in GitHub. - -#### Release, testing and assessment process - -Microcks components are distributed as OCI container images for container runtimes such as Docker or Podman. -The Microcks container images adhere to a versioning scheme where the **x.y.z** or **x.y.z-fix-N** (for critical fixes) tag denotes a stable release from a GitHub repo tag and is immutable. -Additionally, there are mutable tags like `latest` and `nightly` that point to the most recent stable or potentially unstable build, respectively. - -The project has fully [automated the build and release process](https://github.com/microcks/microcks/issues/1468) so all delivered components and their provenance attestations are signed using the GitHub Action provided identities (following the in-toto framework). - -For a full description of [Microcks container images](https://microcks.io/documentation/references/container-images/ ), software supply chain security including SBOM and provenance attestations. - -We have also made significant efforts to enhance our **overall security and compliance** across all **19 repositories** using **CLOMonitor checks** ([View CLOMonitor Report](https://clomonitor.io/projects/cncf/microcks)). -Currently, our **overall CLOMonitor score is 98**, rating Microcks at an **"A" grade**. This was a **long process initiated in June 2024** ([Issue #1201](https://github.com/microcks/microcks/issues/1201)), reflecting our continued commitment to improving project security and best practices. - -Microcks ranks **#8 among 205 CNCF projects** (including Incubating and Graduated projects!). Additionally, we hold the **top position** for the **most repositories and checks among all CNCF projects**. - -**Top 10 CNCF Projects** by Repositories Checked via CLOMonitor: - -1. **Microcks** – 19 repositories -2. **OpenEBS** – 10 repositories -3. **Devfile & In-Toto** – 9 repositories each -4. **Argo** – 7 repositories -5. **etcd & gRPC** – 6 repositories each -6. **CloudEvents** – 6 repositories (though not all require a code checks) -7. **Metal3-io** – 5 repositories -8. **Envoy** – 5 repositories -9. **Cilium, Fluentd, Prometheus, and Strimzi** – 4 repositories each - -Microcks remains dedicated to maintaining and improving security and compliance across our projects! - -Tools we use to secure our supply chain: - -* Sonar Cloud, -* FOSSA, -* Cosign / Sigstore, -* Clair / Docker Scout, -* Syft - -#### Communication Channels - -If you want to report a vulnerability, please follow the guidelines in our [`SECURITY.md`](https://github.com/microcks/.github/blob/main/SECURITY.md) document to ensure responsible disclosure and prompt resolution. - -| Platforms | Link | -|-----------|------| -| 💬 Discord (preferred) | [Discord](https://microcks.io/discord-invite) | -| 💬 Slack (alternate) | [Slack](https://cloud-native.slack.com/archives/C05BYHW1TNJ) | -| 💬 Discussions | [GitHub discussions](https://github.com/orgs/microcks/discussions) | - -For private communications between maintainers and handling sensitive online topics, we use Discord DM (Direct Message). - -In case of **emergencies** and **only if** maintainers are away from their keyboards, we use mobile phone numbers. - -Microcks hosts two monthly community meetings (documented [here](https://github.com/microcks/community?tab=readme-ov-file#community-meetings)), tailored for different time zones. Here’s how to join and participate: - -* APAC-friendly Meeting: Second Thursday of each month: -Time: 9–10 a.m. CET / 1–2 p.m. Bengaluru -* America-friendly Meeting: Fourth Thursday of each month: Time: 6–7 p.m. CET / 1–2 p.m. EST / 9–10 a.m. PST - -The event is listed on the [CNCF calendar](https://www.cncf.io/calendar) and -[Microcks meetings](https://zoom-lfx.platform.linuxfoundation.org/meetings/microcks?view=month). - -We have also created a guide titled "[Joining Microcks Community Meetings](https://github.com/microcks/community/blob/main/JOIN-OUR-MEETINGS.md)" to help newcomers join us with less friction. - -#### Ecosystem - -See, the big picture: - ![Microcks ecosystem](images/microcks-cloud-native-ecosystem.png) - -More details: - -* [Helm](https://microcks.io/documentation/references/configuration/helm-chart-config/) -* [Kubernetes Operator](https://microcks.io/documentation/guides/installation/kubernetes-operator/) -* [OIDC](https://microcks.io/blog/mocking-oidc-redirect/) -* [Prometheus](https://microcks.io/documentation/explanations/monitoring/#technical-metrics) -* [Grafana](https://microcks.io/documentation/explanations/monitoring/#grafana-dashboard) -* [OpenTelemetry](https://microcks.io/blog/observability-for-microcks-at-scale/) & [Documentation](https://microcks.io/documentation/explanations/monitoring/#opentelemetry-support) -* [Keycloak](https://microcks.io/documentation/guides/administration/users/) & [Identity Management](https://microcks.io/documentation/references/configuration/security-config/#identity-management) -* [Cosign](https://microcks.io/documentation/references/container-images/#signatures) -* [SLSA](https://microcks.io/documentation/references/container-images/#provenance) -* [Podman](https://microcks.io/documentation/guides/installation/podman-compose/) -* [Backstage](https://microcks.io/blog/backstage-integration-launch/) -* [Traefik](https://doc.traefik.io/traefik-hub/api-mocking/on-premises-setup) -* [GitLab](https://about.gitlab.com/blog/2023/09/27/microcks-and-gitlab-part-one/) -* [Tekton](https://microcks.io/documentation/guides/automation/tekton/) -* [Jenkins](https://microcks.io/documentation/guides/automation/jenkins/) -* [GitHub Actions](https://microcks.io/documentation/guides/automation/github-actions/) -* [Dagger](https://daggerverse.dev/mod/github.com/fluent-ci-templatesmicrocks-pipeline@645fe89a0d2a46afbfb778a938cddc06d26b4c4c) -* [Testcontainers](https://microcks.io/documentation/guides/usage/developing-testcontainers/) & [Official modules](https://testcontainers.com/modules/microcks/) -* [Docker Extension](https://www.docker.com/blog/get-started-with-the-microcks-docker-extension-for-api-mocking-and-testing/) - -### Security issue resolution - -* Responsible Disclosures Process and Incident Response: Microcks Github org-wide [security policy](https://github.com/microcks/.github/blob/main/SECURITY.md) is available for each sub-project repository. It describes how the project vulnerabilities are reported, analyzed, patched, and informed. - -### Appendix - -* Known Issues Over Time: - - Microcks has promptly responded, fixed, and published one CVE so far. See: [CVE-2024-44076](https://vulners.com/cve/CVE-2024-44076). - -* [Open SSF Best Practices](https://www.bestpractices.dev/en): - - Our current **Open Source Security Foundation (OpenSSF) score** for the main repository is **99%** ([View Score](https://www.bestpractices.dev/fr/projects/7513)). - However, the Microcks team is committed to improving this score to **100%** and achieving the passing stage. - - Why Not 100%? We currently have a **temporary outstanding issue** with **Microcks UI-related dependencies** that we are unable to upgrade, preventing us from reaching **100%** compliance. - This issue is specific to the **Microcks UI** and does not impact the **core services** of Microcks, which are typically used directly by applications relying on Microcks. To address this, we have initiated a **brainstorming session and action plan** with the community. - You can follow the discussion and progress here: [GitHub Discussion #1458](https://github.com/orgs/microcks/discussions/1458). This is a **work in progress**, and we aim to resolve it in the coming months. - -* Case Studies: - * [Revolutionizing API Strategy: Lombard Odier's Success Story with Microcks](https://microcks.io/blog/lombard-odier-revolutionizing-api-strategy/) - - > [Ludovic Pourrat](https://www.linkedin.com/in/ludovic-pourrat/) - API Architect | Platform Architect at Lombard Odier Group: - > Microcks is a robust open source tool that has become an essential solution for Lombard Odier. It enables us to manage, maintain, and automate the lifecycle of our extensive API ecosystem efficiently. At the heart of our remarkable journey, Microcks has become a key asset that achieves the right balance between innovation and stability, empowering developers with fast iterations of their APIs. - * [J.B. Hunt: Mock It till You Make It with Microcks](https://microcks.io/blog/jb-hunt-mock-it-till-you-make-it/) - - > [Carol Gschwend](https://www.linkedin.com/in/carol-gschwend-207650134/) - Expert Software Engineer at J.B. Hunt Transport Services, Inc: - > The developers of the project mentioned above saved at least 7 months using Microcks. They were not only able to work concurrently but also captured the exact business requirements specified by the product owner in the form of example request/response pairs. These persistent mocks can now be utilized in sandbox environments if needed. - * [CNAM Partners with Microcks for Automated SOAP Service Mocking](https://microcks.io/blog/cnam-soap-service-mocking/) - -* Related Projects / Vendors: - - We have addressed this common question in our overview documentation. See: [Overview - Alternatives](https://microcks.io/documentation/overview/alternatives/). - - We often receive questions about **Microcks vs Pact**. Here is our blog post discussing this topic: [Microcks and Pact for API Contract Testing](https://medium.com/@lbroudoux/microcks-and-pact-for-api-contract-testing-3e0e7d4516ca).