# Technical Documentation: apache/dubbo
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/apache/dubbo)
### Overview (`README.md`)
# Apache Dubbo Project
[](https://github.com/apache/dubbo/actions/workflows/build-and-test-pr.yml)
[](https://codecov.io/gh/apache/dubbo)
[](https://github.com/apache/dubbo/releases)
[](https://github.com/apache/dubbo/blob/3.3/LICENSE)
[](http://isitmaintained.com/project/apache/dubbo)
[](http://isitmaintained.com/project/apache/dubbo)
Apache Dubbo is a powerful and user-friendly Web and RPC framework. It supports multiple language implementations such as Java, [Go](https://github.com/apache/dubbo-go), [Python](https://github.com/dubbo/py-client-for-apache-dubbo), [PHP](https://github.com/apache/dubbo-php-framework), [Erlang](https://github.com/apache/dubbo-erlang), [Rust](https://github.com/apache/dubbo-rust), and [Node.js/Web](https://github.com/apache/dubbo-js).
Dubbo provides solutions for communication, service discovery, traffic management, observability, security, tooling, and best practices for building enterprise-grade microservices.
> 🚀 We're collecting user info to improve Dubbo. Help us out here: [Who's using Dubbo](https://github.com/apache/dubbo/discussions/13842)
---
## 🧱 Architecture
- Communication between consumers and providers is done via RPC protocols like Triple, TCP, REST, etc.
- Consumers dynamically discover provider instances from registries (e.g., Zookeeper, Nacos) and manage traffic using defined strategies.
- Built-in support for dynamic config, metrics, tracing, security, and a visualized console.
---
## 🚀 Getting Started
### 📦 Lightweight RPC API
Start quickly with our [5-minute guide](https://cn.dubbo.apache.org/zh-cn/overview/mannual/java-sdk/tasks/framework/lightweight-rpc/)
Dubbo allows you to build RPC services using a minimal codebase and a lightweight SDK. It supports protocols like:
- [Triple (gRPC-compatible)](https://dubbo.apache.org/zh-cn/overview/reference/protocols/triple/)
- Dubbo2 (TCP)
- REST
- Custom protocols
### 🌱 Microservices with Spring Boot
Kickstart your project using [Spring Boot Starter](https://cn.dubbo.apache.org/zh-cn/overview/mannual/java-sdk/tasks/develop/springboot/).
Using just a dependency and a YAML config, you can unlock the full power of Dubbo: service discovery, observability, tracing, etc.
➡️ Learn how to [deploy](https://dubbo.apache.org/zh-cn/overview/tasks/deploy/), [monitor](https://dubbo.apache.org/zh-cn/overview/tasks/observability/), and [manage traffic](https://dubbo.apache.org/zh-cn/overview/tasks/traffic-management/) for Dubbo services.
---
## 🛠️ More Features
Explore more through our hands-on tasks:
- [Launch a Dubbo project](https://dubbo.apache.org/zh-cn/overview/tasks/develop/template/)
- [RPC protocols](https://dubbo.apache.org/zh-cn/overview/core-features/protocols/)
- [Traffic management](https://dubbo.apache.org/zh-cn/overview/core-features/traffic/)
- [Service discovery](https://dubbo.apache.org/zh-cn/overview/core-features/service-discovery/)
- [Observability](https://dubbo.apache.org/zh-cn/overview/core-features/observability/)
- [Extensibility](https://dubbo.apache.org/zh-cn/overview/core-features/extensibility/)
- [Security](https://dubbo.apache.org/zh-cn/overview/core-features/security/)
- [Visualized Console](https://dubbo.apache.org/zh-cn/overview/reference/admin/)
- [Kubernetes & Service Mesh](https://dubbo.apache.org/zh-cn/overview/core-features/service-mesh/)
---
## 📦 Which Dubbo Version Should I Use?
### Dubbo3
## 📦 Version Compatibility
| Version | JDK Support | Dependencies | Highlights |
|--------------------|-------------|-----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| **3.3.7-SNAPSHOT** | 1.8 – 25 | Coming Soon | ✅ JDK 25 Support
| **3.3.6** | 1.8 – 21 | [View Dependencies](https://github.com/apache/dubbo/blob/dubbo-3.3.6/dubbo-dependencies-bom/pom.xml#L92) | ✅ Mutiny Reactive Support
✅ Affinity Router
✅ Method-level TPS Limiting
✅ Spring 6 Security Plugin
✅ Enhanced Environment Variable Config |
| **3.3.5** | 1.8 – 21 | [View Dependencies](https://github.com/apache/dubbo/blob/dubbo-3.3.5/dubbo-dependencies-bom/pom.xml#L92) | ✅ Actively Maintained
✅ Triple Protocol (gRPC/cURL)
✅ REST Support
✅ Spring Boot Starters |
| **3.2.16** | 1.8 – 17 | [View Dependencies](https://github.com/apache/dubbo/blob/dubbo-3.2.5/dubbo-dependencies-bom/pom.xml#L94) | ✅ Actively Maintained
✅ Metrics & Tracing
✅ Thread Pool Isolation
✅ +30% Performance
✅ Native Image Support |
| **3.1.11** | 1.8 – 17 | [View Dependencies](https://github.com/apache/dubbo/blob/dubbo-3.2.11/dubbo-dependencies-bom/pom.xml#L90) | ⚠️ Stable, but Not Actively Maintained |
### Dubbo2
| Version | JDK | Dependencies | Description |
|-------------|-----------|--------------------------------------------------------------------------------------------------------|-------------|
| 2.7.23 | 1.8 | [dependency list](https://github.com/apache/dubbo/blob/dubbo-2.7.23/dubbo-dependencies-bom/pom.xml#L92) | ❌ EOL |
| 2.6.x, 2.5.x| 1.6 - 1.7 | [dependency list](https://github.com/apache/dubbo/blob/dubbo-2.6.12/dependencies-bom/pom.xml#L90) | ❌ EOL |
---
## 🤝 Contributing
See our [CONTRIBUTING](https://github.com/apache/dubbo/blob/master/CONTRIBUTING.md) guide to get started!
### 🔁 Community Collaboration
- **Issues**: For bugs or tasks – [GitHub Issues](https://github.com/apache/dubbo/issues)
- **Discussions**: For questions, ideas – [GitHub Discussions](https://github.com/apache/dubbo/discussions)
- **PRs**: For merging your contributions – [GitHub Pull Requests](https://github.com/apache/dubbo/pulls)
- **Project Board**: [Dubbo Project Board](https://github.com/orgs/apache/projects/337)
### 💡 How You Can Help
- Check out "help wanted" issues: [Project Board](https://github.com/orgs/apache/projects/337)
- Join [mailing list discussions](https://github.com/apache/dubbo/wiki/Mailing-list-subscription-guide)
- Engage in [discussions](https://github.com/apache/dubbo/discussions)
- Fix [bugs](https://github.com/apache/dubbo/issues) or review [pull requests](https://github.com/apache/dubbo/pulls)
- Enhance the [website](https://github.com/apache/dubbo-website)
- Improve [dubbo-admin](https://github.com/apache/dubbo-admin)
- Contribute to the [ecosystem](https://github.com/apache/?q=dubbo&type=all&language=&sort=)
If you're interested in contributing, email us at [dev@dubbo.apache.org](mailto:dev@dubbo.apache.org).
---
## 🐞 Reporting Issues
Please use our [issue template](https://github.com/apache/dubbo/issues/new?template=dubbo-issue-report-template.md) when reporting bugs.
---
## 🔐 Reporting Security Vulnerabilities
Please report vulnerabilities **privately** to [security@dubbo.apache.org](mailto:security@dubbo.apache.org).
---
## 📬 Contact
- **WeChat**: `apachedubbo`
- **DingTalk**: Group ID `37290003945`
- **Mailing List**: [Contact Guide](https://dubbo.apache.org/zh-cn/contact/)
- **Twitter**: [@ApacheDubbo](https://twitter.com/ApacheDubbo)
- **Security**: [security@dubbo.apache.org](mailto:security@dubbo.apache.org)
---
## 📄 License
Apache Dubbo is licensed under the [Apache License 2.0](https://github.com/apache/dubbo/blob/3.3/LICENSE).
---
### Overview (`dubbo-compatible/README.md`)
### dubbo-compatible
Hi, all
From 2.7.x, `Dubbo` has renamed package to `org.apache.dubbo`, so `dubbo-compatible` module is provided.
For compatibility with older versions, we provider the following most popular APIs(classes/interfaces):
* com.alibaba.dubbo.rpc.Filter / Invocation / Invoker / Result / RpcContext / RpcException
* com.alibaba.dubbo.config.annotation.Reference / Service
* com.alibaba.dubbo.config.spring.context.annotation.EnableDubbo
* com.alibaba.dubbo.common.Constants / URL
* com.alibaba.dubbo.common.extension.ExtensionFactory
* com.alibaba.dubbo.common.serialize.Serialization / ObjectInput / ObjectOutput
* com.alibaba.dubbo.cache.CacheFactory / Cache
* com.alibaba.dubbo.rpc.service.EchoService / GenericService
The above APIs work fine with some unit tests in the test root.
Except these APIs, others provided in `dubbo-compatible` are just bridge APIs without any unit tests, they may work with wrong. If you have any demand for them, you could:
* Implement your own extensions with new APIs. (RECOMMENDED)
* Follow `com.alibaba.dubbo.rpc.Filter` to implement bridge APIs, and then contribute to community.
* Open issue on github.
By the way, We will remove this module some day, so it's recommended that implementing your extensions with new APIs at the right time.
Now we need your help: Any other popular APIs are missing?
For compatible module, any suggestions are welcome. Thanks.
---
### Overview (`dubbo-demo/README.md`)
# Dubbo Demo
This directory contains basic Dubbo usages to help Dubbo developers with debugging and smoke test purposes. Check [dubbo-samples](https://github.com/apache/dubbo-samples) repository for more examples that showcase Dubbo's rich features.
## Brief introduction
1. **`dubbo-demo-api`**
This demo demonstrates the basic usage of Dubbo's RPC protocol, serving as a fundamental example. It showcases how to define and implement a simple RPC service using Dubbo, how to start a server that serves at a specified port and then a consumer that consumes the service.
2. **`dubbo-demo-springboot`**
This demo illustrates the integration of Dubbo with Spring Boot, showing how Dubbo services can be utilized and configured within a Spring Boot application. It demonstrates how to configure and manage Dubbo services seamlessly through Spring Boot, making it ideal for developers leveraging the popular Spring Boot framework.
3. **`dubbo-demo-springboot-idl`**
This demo focuses on showcasing how to use Dubbo with Spring Boot when IDL (Interface Definition Language) files such as Proto files are available. It illustrates how developers can work with Dubbo services defined through IDL, integrating them into a Spring Boot application.
---
### Overview (`dubbo-plugin/dubbo-compiler/README.md`)
## dubbo-complier
> dubbo-complier supports generating code based on .proto files
### How to use
#### 1.Define Proto file
greeter.proto
```protobuf
syntax = "proto3";
option java_multiple_files = true;
option java_package = "org.apache.dubbo.demo";
option java_outer_classname = "DemoServiceProto";
option objc_class_prefix = "DEMOSRV";
package demoservice;
// The demo service definition.
service DemoService {
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
```
#### 2.Use dubbo-maven-plugin,rather than ```protobuf-maven-plugin```
now dubbo support his own protoc plugin base on dubbo-maven-plugin
```xml
org.apache.dubbo
dubbo-maven-plugin
${dubbo.version}
compile
```
#### 3.generate file
```
/* Detailed source-code truncated for AI context efficiency. */
```
#### 4.others
dubbo-maven-plugin protoc mojo supported configurations
| configuration params | isRequired | explain | default | eg |
|:----------------------|------------|------------------------------------------------|------------------------------------------------------------|----------------------------------------------------------------------------|
| dubboVersion | true | dubbo version ,use for find Generator | ${dubbo.version} | 3.3.0 |
| dubboGenerateType | true | dubbo generator type | dubbo3 | grpc |
| protocExecutable | false | protoc executable,you can use local protoc.exe | | protoc |
| protocArtifact | false | download protoc from maven artifact | | com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier} |
| protoSourceDir | true | .proto files dir | ${basedir}/src/main/proto | ./proto |
| outputDir | true | generated file output dir | ${project.build.directory}/generated-sources/protobuf/java | ${basedir}/src/main/java |
| protocPluginDirectory | false | protoc plugin dir | ${project.build.directory}/protoc-plugins | ./target/protoc-plugins |
---
### Overview (`dubbo-spring-boot-project/dubbo-spring-boot-actuator/README.md`)
# Dubbo Spring Boot Production-Ready
`dubbo-spring-boot-actuator` provides production-ready features (e.g. [health checks](#health-checks), [endpoints](#endpoints), and [externalized configuration](#externalized-configuration)).
## Content
1. [Main Content](https://github.com/apache/dubbo-spring-boot-project)
2. [Integrate with Maven](#integrate-with-maven)
3. [Health Checks](#health-checks)
4. [Endpoints](#endpoints)
5. [Externalized Configuration](#externalized-configuration)
## Integrate with Maven
You can introduce the latest `dubbo-spring-boot-actuator` to your project by adding the following dependency to your pom.xml
```xml
org.apache.dubbo
dubbo-spring-boot-actuator
2.7.4.1
```
If your project failed to resolve the dependency, try to add the following repository:
```xml
apache.snapshots.https
Apache Development Snapshot Repository
https://repository.apache.org/content/repositories/snapshots
false
true
```
## Health Checks
`dubbo-spring-boot-actuator` supports the standard Spring Boot `HealthIndicator` as a production-ready feature , which will be aggregated into Spring Boot's `Health` and exported on `HealthEndpoint` that works MVC (Spring Web MVC) and JMX (Java Management Extensions) both if they are available.
### Web Endpoint : `/health`
Suppose a Spring Boot Web application did not specify `management.server.port`, you can access http://localhost:8080/actuator/health via Web Client and will get a response with JSON format is like below :
```json
{
"status": "UP",
"dubbo": {
"status": "UP",
"memory": {
"source": "management.health.dubbo.status.defaults",
"status": {
"level": "OK",
"message": "max:3641M,total:383M,used:92M,free:291M",
"description": null
}
},
"load": {
"source": "management.health.dubbo.status.extras",
"status": {
"level": "OK",
"message": "load:1.73583984375,cpu:8",
"description": null
}
},
"threadpool": {
"source": "management.health.dubbo.status.extras",
"status": {
"level": "OK",
"message": "Pool status:OK, max:200, core:200, largest:0, active:0, task:0, service port: 12345",
"description": null
}
},
"server": {
"source": "dubbo@ProtocolConfig.getStatus()",
"status": {
"level": "OK",
"message": "/192.168.1.103:12345(clients:0)",
"description": null
}
}
}
// ignore others
}
```
`memory`, `load`, `threadpool` and `server` are Dubbo's built-in `StatusChecker`s in above example.
Dubbo allows the application to extend `StatusChecker`'s SPI.
Default , `memory` and `load` will be added into Dubbo's `HealthIndicator` , it could be overridden by
externalized configuration [`StatusChecker`'s defaults](#statuschecker-defaults).
### JMX Endpoint : `Health`
`Health` is a JMX (Java Management Extensions) Endpoint with ObjectName `org.springframework.boot:type=Endpoint,name=Health` , it can be managed by JMX agent ,e.g. JDK tools : `jconsole` and so on.
### Built-in `StatusChecker`s
`META-INF/dubbo/internal/org.apache.dubbo.common.status.StatusChecker` declares built-in `StatusChecker`s as follow :
```properties
registry=org.apache.dubbo.registry.status.RegistryStatusChecker
spring=org.apache.dubbo.config.spring.status.SpringStatusChecker
datasource=org.apache.dubbo.config.spring.status.DataSourceStatusChecker
memory=org.apache.dubbo.common.status.support.MemoryStatusChecker
load=org.apache.dubbo.common.status.support.LoadStatusChecker
server=org.apache.dubbo.rpc.protocol.dubbo.status.ServerStatusChecker
threadpool=org.apache.dubbo.rpc.protocol.dubbo.status.ThreadPoolStatusChecker
```
The property key that is name of `StatusChecker` can be a valid value of `management.health.dubbo.status.*` in externalized configuration.
## Endpoints
Actuator endpoint `dubbo` supports Actuator Endpoints :
| ID | Enabled | HTTP URI | HTTP Method | Description | Content Type |
| ------------------- | ----------- | ----------------------------------- | ------------------ | ------------------ | ------------------ |
| `dubbo` | `true` | `/actuator/dubbo` | `GET` | Exposes Dubbo's meta data | `application/json` |
| `dubboproperties` | `true` | `/actuator/dubbo/properties` | `GET` | Exposes all Dubbo's Properties | `application/json` |
| `dubboservices` | `false` | `/actuator/dubbo/services` | `GET` | Exposes all Dubbo's `ServiceBean` | `application/json` |
| `dubboreferences` | `false` | `/actuator/dubbo/references` | `GET` | Exposes all Dubbo's `ReferenceBean` | `application/json` |
| `dubboconfigs` | `true` | `/actuator/dubbo/configs` | `GET` | Exposes all Dubbo's `*Config` | `application/json` |
| `dubboshutdown` | `false` | `/actuator/dubbo/shutdown` | `GET` | Shutdown Dubbo services | `application/json` |
| `help` | `false` | `/actuator/dubbo/help` | `GET` | List all commands | |
| `ready` | `true` | `/actuator/dubbo/ready` | `GET` | Check whether the current process/service is ready for external service | `application/json` |
| `live` | `true` | `/actuator/dubbo/live` | `GET` | Check whether the current process/service is alive | `application/json` |
| `ls` | `false` | `/actuator/dubbo/ls` | `GET` | List consumers and providers | `application/json` |
| `startup` | `true` | `/actuator/dubbo/startup` | `GET` | Check if the current framework has been started | `application/json` |
| `ps` | `false` | `/actuator/dubbo/ps` | `GET` | View information about the current process, including `listenable` ports | `application/json` |
| `version` | `false` | `/actuator/dubbo/version` | `GET` | Display the version number of the currently running `Dubbo` | `application/json` |
| `getaddress` | `false` | `/actuator/dubbo/getaddress?args=xxx.*` | `GET` | View the list of valid `IP` addresses for a service | `application/json` |
| `getconfig` | `false` | `/actuator/dubbo/getconfig` | `GET` | View the valid `configuration` of the current application | `application/json` |
| `metrics` | `false` | `/actuator/dubbo/metrics` | `GET` | View `metrics`(Need to enable metrics statistics) | `application/json` |
| `metrics_default` | `false` | `/actuator/dubbo/metrics_default` | `GET` | View the default `metrics`(Need to enable metrics statistics) | `application/json` |
| `publishmetadata` | `false` | `/actuator/dubbo/publishmetadata` or `/actuator/dubbo/publishmetadata?args=10` | `GET` | Publishes or updates the current application `Metadata` (Delay can be set) | `application/json` |
| `online` | `false` | `/actuator/dubbo/online` or `/actuator/dubbo/online?args=xxx.*` | `GET` | Register one or more services to the registry (including application and interface addresses) | `application/json` |
| `onlineapp` | `false` | `/actuator/dubbo/onlineApp` or `/actuator/dubbo/onlineApp?args=xxx.xxx.*` | `GET` | Register one or more services to the registry (only application addresses) | `application/json` |
| `onlineinterface` | `false` | `/actuator/dubbo/onlineInterface` or `/actuator/dubbo/onlineInterface?args=xxx.*` | `GET` | Register one or more services to the registry (only interface addresses) | `application/json` |
| `offline` | `false` | `/actuator/dubbo/offline` or `/actuator/dubbo/offline?args=xxx.*` | `GET` | Unregister one or more services from the registry (including application and interface addresses) | `application/json` |
| `offlineapp` | `false` | `/actuator/dubbo/offlineApp` or `/actuator/dubbo/offlineApp?args=xxx.*` | `GET` | Unregister one or more services from the registry (only application addresses) | `application/json` |
| `offlineinterface` | `false` | `/actuator/dubbo/offlineInterface` or `/actuator/dubbo/offlineInterface?args=xxx.*` | `GET` | Unregister one or more services from the registry (only interface addresses) | `application/json` |
| `loggerinfo` | `false` | `/actuator/dubbo/loggerInfo` | `GET` | Query log configuration | `application/json` |
| `switchlogger` | `false` | `/actuator/dubbo/switchLogger?args={loggerAdapterName}` | `GET` | Modify the log output framework，`loggerAdapterName`: `slf4j`, `jcl`, `log4j`, `jdk`, `log4j2` | `application/json` |
| `switchloglevel` | `false` | `/actuator/dubbo/switchLogLevel?args={level}` | `GET` | Modify log level，level: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF` | `application/json` |
| `disabledetailprofiler` | `false` | `/actuator/dubbo/disableDetailProfiler` | `GET` | Turn off `detail profiler` mode, it will not affect `simple profiler` | `application/json` |
| `enabledetailprofiler` | `false` | `/actuator/dubbo/enableDetailProfiler` | `GET` | Enable the `detail profiler` mode, which is disabled by default, you need to enable the `simple profiler` mode to actually enable it | `application/json` |
| `disablesimpleprofiler` | `false` | `/actuator/dubbo/disableSimpleProfiler` | `GET` | Turn off the `simple profiler` mode, and the `detail profiler` will not be enabled after it is turned off | `application/json` |
| `enablesimpleprofiler` | `false` | `/actuator/dubbo/enableSimpleProfiler` | `GET` | Enable `simple profiler` mode, enabled by default | `application/json` |
| `setprofilerwarnpercent` | `false` | `/actuator/dubbo/setProfilerWarnPercent?args={percent}` | `GET` | Control `serialization` alarm frequency (only for classes in the warning list) | `application/json` |
| `serializecheckstatus` | `false` | `/actuator/dubbo/dubboserializecheckstatus` | `GET` | View the current configuration information | `application/json` |
| `serializewarnedclasses` | `false` | `/actuator/dubbo/dubboserializewarnedclasses` | `GET` | View the real-time alarm list | `application/json` |
| `disableroutersnapshot` | `false` | `/actuator/dubbo/disableRouterSnapshot` or `/actuator/dubbo/disableRouterSnapshot?args=xxx.*` | `GET` | Disable routing result collection mode | `application/json` |
| `enableroutersnapshot` | `false` | `/actuator/dubbo/enableRouterSnapshot` or `/actuator/dubbo/enableRouterSnapshot?args=xxx.*` | `GET` | Enable routing result collection mode | `application/json` |
| `getrecentroutersnapshot` | `false` | `/actuator/dubbo/getRecentRouterSnapshot` | `GET` | Obtain the historical routing status (up to 32 results stored) | `application/json` |
| `getenabledroutersnapshot` | `false` | `/actuator/dubbo/getEnabledRouterSnapshot` | `GET` | Get the services that are currently collecting | `application/json` |
| `gracefulshutdown` | `false` | `/actuator/dubbo/gracefulShutdown` | `GET` | Unregister all services registered by the current IP instance from the registry | `application/json` |
### Web Endpoints
#### `/actuator/dubbo`
`/dubbo` exposes Dubbo's meta data :
```json
{
"timestamp": 1516623290166,
"versions": {
"dubbo-spring-boot": "2.7.5",
"dubbo": "2.7.5"
},
"urls": {
"dubbo": "https://github.com/apache/dubbo/",
"google-group": "dev@dubbo.apache.org",
"github": "https://github.com/apache/dubbo-spring-boot-project",
"issues": "https://github.com/apache/dubbo-spring-boot-project/issues",
"git": "https://github.com/apache/dubbo-spring-boot-project.git"
}
}
```
###
#### `/actuator/dubbo/properties`
`/actuator/dubbo/properties` exposes all Dubbo's Properties from Spring Boot Externalized Configuration (a.k.a `PropertySources`) :
```json
{
"dubbo.application.id": "dubbo-provider-demo",
"dubbo.application.name": "dubbo-provider-demo",
"dubbo.application.qos-enable": "false",
"dubbo.application.qos-port": "33333",
"dubbo.protocol.id": "dubbo",
"dubbo.protocol.name": "dubbo",
"dubbo.protocol.port": "12345",
"dubbo.registry.address": "N/A",
"dubbo.registry.id": "my-registry",
"dubbo.scan.basePackages": "org.apache.dubbo.spring.boot.sample.provider.service"
}
```
The structure of JSON is simple Key-Value format , the key is property name as and the value is property value.
#### `/actuator/dubbo/services`
`/actuator/dubbo/services` exposes all Dubbo's `ServiceBean` that are declared via `` or `@Service` present in Spring `ApplicationContext` :
```json
{
"ServiceBean@org.apache.dubbo.spring.boot.sample.api.DemoService#defaultDemoService": {
"accesslog": null,
"actives": null,
"cache": null,
"callbacks": null,
"class": "org.apache.dubbo.config.spring.ServiceBean",
"cluster": null,
"connections": null,
"delay": null,
"document": null,
"executes": null,
"export": null,
"exported": true,
"filter": "",
"generic": "false",
"group": null,
"id": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"interface": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"interfaceClass": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"layer": null,
"listener": "",
"loadbalance": null,
"local": null,
"merger": null,
"mock": null,
"onconnect": null,
"ondisconnect": null,
"owner": null,
"path": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"proxy": null,
"retries": null,
"scope": null,
"sent": null,
"stub": null,
"timeout": null,
"token": null,
"unexported": false,
"uniqueServiceName": "org.apache.dubbo.spring.boot.sample.api.DemoService:1.0.0",
"validation": null,
"version": "1.0.0",
"warmup": null,
"weight": null,
"serviceClass": "DefaultDemoService"
}
}
```
The key is the Bean name of `ServiceBean` , `ServiceBean`'s properties compose value.
#### `/actuator/dubbo/references`
`/actuator/dubbo/references` exposes all Dubbo's `ReferenceBean` that are declared via `@Reference` annotating on `Field` or `Method ` :
```json
{
"private org.apache.dubbo.spring.boot.sample.api.DemoService org.apache.dubbo.spring.boot.sample.consumer.controller.DemoConsumerController.demoService": {
"actives": null,
"cache": null,
"callbacks": null,
"class": "org.apache.dubbo.config.spring.ReferenceBean",
"client": null,
"cluster": null,
"connections": null,
"filter": "",
"generic": null,
"group": null,
"id": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"interface": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"interfaceClass": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"layer": null,
"lazy": null,
"listener": "",
"loadbalance": null,
"local": null,
"merger": null,
"mock": null,
"objectType": "org.apache.dubbo.spring.boot.sample.api.DemoService",
"onconnect": null,
"ondisconnect": null,
"owner": null,
"protocol": null,
"proxy": null,
"reconnect": null,
"retries": null,
"scope": null,
"sent": null,
"singleton": true,
"sticky": null,
"stub": null,
"stubevent": null,
"timeout": null,
"uniqueServiceName": "org.apache.dubbo.spring.boot.sample.api.DemoService:1.0.0",
"url": "dubbo://localhost:12345",
"validation": null,
"version": "1.0.0",
"invoker": {
"class": "org.apache.dubbo.common.bytecode.proxy0"
}
}
}
```
The key is the string presentation of `@Reference` `Field` or `Method ` , `ReferenceBean`'s properties compose value.
#### `/actuator/dubbo/configs`
`/actuator/dubbo/configs` exposes all Dubbo's `*Config` :
```json
{
"ApplicationConfig": {
"dubbo-consumer-demo": {
"architecture": null,
"class": "org.apache.dubbo.config.ApplicationConfig",
"compiler": null,
"dumpDirectory": null,
"environment": null,
"id": "dubbo-consumer-demo",
"logger": null,
"name": "dubbo-consumer-demo",
"organization": null,
"owner": null,
"version": null
}
},
"ConsumerConfig": {
},
"MethodConfig": {
},
"ModuleConfig": {
},
"MonitorConfig": {
},
"ProtocolConfig": {
"dubbo": {
"accepts": null,
"accesslog": null,
"buffer": null,
"charset": null,
"class": "org.apache.dubbo.config.ProtocolConfig",
"client": null,
"codec": null,
"contextpath": null,
"dispatcher": null,
"dispather": null,
"exchanger": null,
"heartbeat": null,
"host": null,
"id": "dubbo",
"iothreads": null,
"name": "dubbo",
"networker": null,
"path": null,
"payload": null,
"port": 12345,
"prompt": null,
"queues": null,
"serialization": null,
"server": null,
"status": null,
"telnet": null,
"threadpool": null,
"threads": null,
"transporter": null
}
},
"ProviderConfig": {
},
"ReferenceConfig": {
},
"RegistryConfig": {
},
"ServiceConfig": {
}
}
```
The key is the simple name of Dubbo `*Config` Class , the value is`*Config` Beans' Name-Properties Map.
#### `/actuator/dubbo/shutdown`
`/actuator/dubbo/shutdown` shutdowns Dubbo's components including registries, protocols, services and references :
```json
{
"shutdown.count": {
"registries": 0,
"protocols": 1,
"services": 0,
"references": 1
}
}
```
"shutdown.count" means the count of shutdown of Dubbo's components , and the value indicates how many components have been shutdown.
`/actuator/dubbo/ls `List consumers and providers :
```
As Provider side:
+-----------------------------------------------------------------------------------+-----------------------------+
| Provider Service Name | PUB |
+-----------------------------------------------------------------------------------+-----------------------------+
| DubboInternal - dubbo-springboot-demo-provider/org.apache.dubbo.metadata.MetadataService: 1.0.0 | |
+-----------------------------------------------------------------------------------+-----------------------------+
|DubboInternal - dubbo-springboot-demo-provider/org.apache.dubbo.metrics.service.MetricsService: 1.0.0| |
+-----------------------------------------------------------------------------------+-----------------------------+
| org.apache.dubbo.springboot.demo.DemoService |zookeeper-A(Y)/zookeeper-I(Y)|
+-----------------------------------------------------------------------------------+-----------------------------+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+
```
- Services prefixed with `DubboInternal` are built-in services of Dubbo, and are not registered with the registry by default.
- The first part of `zookeeper-A(Y)` in the service publishing status is the corresponding registry name, and the second part is the registration mode (`A` stands for application-level address registration, `I` stands for interface-level address registration), The third part represents whether the corresponding mode has been registered
- The first part of `zookeeper-AF(I-2,A-2)` in the service subscription status is the corresponding registration center name, and the second part is the subscription mode (`AF` stands for dual subscription mode, `FA` stands for only Application-level subscription, `FI` stands for interface-level subscription only), the first half of the third part represents the source of the address mode (`A` stands for application-level address, `I` stands for interface-level address), and the second half represents the corresponding number of addresses
`/actuator/dubbo/switchLogLevel?args={level}` allows switching between permitted log levels, and the parameter cannot be empty, `/actuator/dubbo/switchLogLevel?args=WARN`.
The log configuration modified by `switchLogger`/`switchLogLevel` is not stored persistently and will become invalid after the application is restarted.
`/actuator/dubbo/disableSimpleProfiler` turn off the `simple profiler` mode, and the `detail profiler` will not be enabled after it is turned off.
The performance sampling function can detect the time consumption of various parts of the Dubbo processing link,where `simple profiler` mode is enabled by default.
`/actuator/dubbo/enableDetailProfiler` enable the `detail profiler` mode, which is disabled by default, you need to enable the `simple profiler` mode to actually enable it.
Compared with the `simple profiler` mode, the `detail profiler` collects more time-consuming processing of each filter, specific time-consuming protocols, etc. In the `simple profiler` mode, if you find that there is a long time-consuming situation inside the Dubbo framework, you can enable the `detail profiler` mode to better troubleshoot the problem.
`/actuator/dubbo/gracefulShutdown` unregister all services registered by the current IP instance from the registry. The difference from 'offline' is that this command will also notify all consumers via TCP connection to stop calling this instance. To restore, please execute 'online' to bring all services back online.
## Externalized Configuration
### `StatusChecker` Defaults
`management.health.dubbo.status.defaults` is a property name for setting names of `StatusChecker`s , its value is allowed to multiple-values , for example :
```properties
management.health.dubbo.status.defaults = registry,memory,load
```
#### Default Value
The default value is :
```properties
management.health.dubbo.status.defaults = memory,load
```
### `StatusChecker` Extras
`management.health.dubbo.status.extras` is used to override the [ [`StatusChecker`'s defaults]](#statuschecker-defaults) , the multiple-values is delimited by comma :
```properties
management.health.dubbo.status.extras = load,threadpool
```
### Health Checks Enabled
`management.health.dubbo.enabled` is a enabled configuration to turn on or off health checks feature, its' default is `true`.
If you'd like to disable health checks , you could apply `management.health.dubbo.enabled` to be `false`:
```properties
management.health.dubbo.enabled = false
```
### Endpoints Enabled
Dubbo Spring Boot providers actuator endpoints , however some of them are disable. If you'd like to enable them , please add following properties into externalized configuration :
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
### Overview (`dubbo-spring-boot-project/dubbo-spring-boot-autoconfigure/README.md`)
# Dubbo Spring Boot Auto-Configure
`dubbo-spring-boot-autoconfigure` uses Spring Boot's `@EnableAutoConfiguration` which helps core Dubbo's components to be auto-configured by `DubboAutoConfiguration`. It reduces code, eliminates XML configuration.
## Content
1. [Main Content](https://github.com/apache/dubbo-spring-boot-project)
2. [Integrate with Maven](#integrate-with-maven)
3. [Auto Configuration](#auto-configuration)
4. [Externalized Configuration](#externalized-configuration)
5. [Dubbo Annotation-Driven (Chinese)](http://dubbo.apache.org/zh-cn/blog/dubbo-annotation-driven.html)
6. [Dubbo Externalized Configuration (Chinese)](http://dubbo.apache.org/zh-cn/blog/dubbo-externalized-configuration.html)
## Integrate with Maven
You can introduce the latest `dubbo-spring-boot-autoconfigure` to your project by adding the following dependency to your pom.xml
```xml
org.apache.dubbo
dubbo-spring-boot-autoconfigure
2.7.4.1
```
If your project failed to resolve the dependency, try to add the following repository:
```xml
apache.snapshots.https
Apache Development Snapshot Repository
https://repository.apache.org/content/repositories/snapshots
false
true
```
## Auto Configuration
Since `2.5.7` , Dubbo totally supports Annotation-Driven , core Dubbo's components that are registered and initialized in Spring application context , including externalized configuration features. However , those features need to trigger in manual configuration , e.g `@DubboComponentScan` , `@EnableDubboConfig` or `@EnableDubbo`.
> If you'd like to learn more , please read [Dubbo Annotation-Driven (Chinese)](http://dubbo.apache.org/zh-cn/blog/dubbo-annotation-driven.html)
`dubbo-spring-boot-autoconfigure` uses Spring Boot's `@EnableAutoConfiguration` which helps core Dubbo's components to be auto-configured by `DubboAutoConfiguration`. It reduces code, eliminates XML configuration.
## Externalized Configuration
Externalized Configuration is a core feature of Spring Boot , Dubbo Spring Boot not only supports it definitely , but also inherits Dubbo's Externalized Configuration, thus it provides single and multiple Dubbo's `*Config` Bindings from `PropertySources` , and `"dubbo."` is a common prefix of property name.
> If you'd like to learn more , please read [Dubbo Externalized Configuration](http://dubbo.apache.org/zh-cn/blog/dubbo-externalized-configuration.html)(Chinese).
### Single Dubbo Config Bean Bindings
In most use scenarios , "Single Dubbo Config Bean Bindings" is enough , because a Dubbo application only requires single Bean of `*Config` (e.g `ApplicationConfig`). You add properties in `application.properties` to configure Dubbo's `*Config` Beans that you want , be like this :
```properties
dubbo.application.name = foo
dubbo.application.owner = bar
dubbo.registry.address = 10.20.153.10:9090
```
There are two Spring Beans will be initialized when Spring `ApplicationContext` is ready, their Bean types are `ApplicationConfig` and `RegistryConfig`.
#### Getting Single Dubbo Config Bean
If application requires current `ApplicationConfig` Bean in somewhere , you can get it from Spring `BeanFactory` as those code :
```java
BeanFactory beanFactory = ....
ApplicationConfig applicationConfig = beanFactory.getBean(ApplicationConfig.class)
```
or inject it :
```java
@Autowired
private ApplicationConfig application;
```
#### Identifying Single Dubbo Config Bean
If you'd like to identify this `ApplicationConfig` Bean , you could add **"id"** property:
```properties
dubbo.application.id = application-bean-id
```
#### Mapping Single Dubbo Config Bean
The whole Properties Mapping of "Single Dubbo Config Bean Bindings" lists below :
| Dubbo `*Config` Type | The prefix of property name for Single Bindings |
| -------------------- | ---------------------------------------- |
| `ProtocolConfig` | `dubbo.protocol` |
| `ApplicationConfig` | `dubbo.application` |
| `ModuleConfig` | `dubbo.module` |
| `RegistryConfig` | `dubbo.registry` |
| `MonitorConfig` | `dubbo.monitor` |
| `ProviderConfig` | `dubbo.provider` |
| `ConsumerConfig` | `dubbo.consumer` |
An example properties :
```properties
# Single Dubbo Config Bindings
## ApplicationConfig
dubbo.application.id = applicationBean
dubbo.application.name = dubbo-demo-application
## ModuleConfig
dubbo.module.id = moduleBean
dubbo.module.name = dubbo-demo-module
## RegistryConfig
dubbo.registry.address = zookeeper://192.168.99.100:32770
## ProtocolConfig
dubbo.protocol.name = dubbo
dubbo.protocol.port = 20880
## MonitorConfig
dubbo.monitor.address = zookeeper://127.0.0.1:32770
## ProviderConfig
dubbo.provider.host = 127.0.0.1
## ConsumerConfig
dubbo.consumer.client = netty
```
### Multiple Dubbo Config Bean Bindings
In contrast , "Multiple Dubbo Config Bean Bindings" means Externalized Configuration will be used to configure multiple Dubbo `*Config` Beans.
#### Getting Multiple Dubbo Config Bean
The whole Properties Mapping of "Multiple Dubbo Config Bean Bindings" lists below :
| Dubbo `*Config` Type | The prefix of property name for Multiple Bindings |
| -------------------- | ---------------------------------------- |
| `ProtocolConfig` | `dubbo.protocols` |
| `ApplicationConfig` | `dubbo.applications` |
| `ModuleConfig` | `dubbo.modules` |
| `RegistryConfig` | `dubbo.registries` |
| `MonitorConfig` | `dubbo.monitors` |
| `ProviderConfig` | `dubbo.providers` |
| `ConsumerConfig` | `dubbo.consumers` |
#### Identifying Multiple Dubbo Config Bean
There is a different way to identify Multiple Dubbo Config Bean , the configuration pattern is like this :
`${config-property-prefix}.${config-bean-id}.${property-name} = some value` , let's explain those placeholders :
- `${config-property-prefix}` : The The prefix of property name for Multiple Bindings , e.g. `dubbo.protocols`, `dubbo.applications` and so on.
- `${config-bean-id}` : The bean id of Dubbo's `*Config`
- `${property-name}`: The property name of `*Config`
An example properties :
```properties
dubbo.applications.application1.name = dubbo-demo-application
dubbo.applications.application2.name = dubbo-demo-application2
dubbo.modules.module1.name = dubbo-demo-module
dubbo.registries.registry1.address = zookeeper://192.168.99.100:32770
dubbo.protocols.protocol1.name = dubbo
dubbo.protocols.protocol1.port = 20880
dubbo.monitors.monitor1.address = zookeeper://127.0.0.1:32770
dubbo.providers.provider1.host = 127.0.0.1
dubbo.consumers.consumer1.client = netty
```
### IDE Support
If you used advanced IDE tools , for instance [Jetbrains IDEA Ultimate](https://www.jetbrains.com/idea/) develops Dubbo Spring Boot application, it will popup the tips of Dubbo Configuration Bindings in `application.properties` :
#### Case 1 - Single Bindings
#### Case 2 - Multiple Bindings
---
### Overview (`dubbo-spring-boot-project/dubbo-spring-boot/README.md`)
# Dubbo Spring Boot interceptor
`dubbo-spring-boot-interceptor` copy the header(dubbo-tag)/cookie(dubbo.tag)/urlParameter(dubbo.tag) to dubbo .
## Integrate with spring boot
### copy the header(dubbo-tag=tagx)/urlParameter(dubbo.tag=tagx) to dubbo
if there is no header(dubbo-tag) , downgrade use urlParameter(dubbo.tag)
```
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new DubboTagHeaderOrParameterInterceptor()).addPathPatterns("/*").excludePathPatterns("/admin");
}
}
```
### copy the cookie(dubbo.tag=tagx) to dubbo
```
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new DubboTagCookieInterceptor()).addPathPatterns("/*").excludePathPatterns("/admin");
}
}
```
---
### Overview (`dubbo-demo/dubbo-demo-spring-boot-idl/dubbo-demo-spring-boot-idl-provider/README.md`)
## 1. startup
1. run the maven plugin `dubbo:compile`, generate protobuf java file.
2. run `ProviderApplication`
## 2. http request
### 2.1 sample request
```shell
curl -v -d '{"name":"dubbo"}' -H 'Content-Type: application/json' http://127.0.0.1:50051/org.apache.dubbo.demo.hello.GreeterService/sayHello
```
### 2.2 request async
```shell
curl -v -d '{"name":"dubbo async"}' -H 'Content-Type: application/json' http://127.0.0.1:50051/org.apache.dubbo.demo.hello.GreeterService/sayHelloAsync
```
### 2.3 server stream
```shell
curl -v -d '{"name":"dubbo"}' -H 'Content-Type: application/json' http://127.0.0.1:50051/org.apache.dubbo.demo.hello.GreeterService/sayHelloStream
```
---
### Overview (`dubbo-spring-boot-project/dubbo-spring-boot-compatible/dubbo-spring-boot-autoconfigure-compatible/README.md`)
# About spring-configuration-metadata
## Why
Configuration beans of dubbo are located in the `dubbo-common` module, and it's not suitable to add spring boot dependencies.
However, spring configuration metadata generation relies on read javadoc from the source code and cannot use the @NestedConfigurationProperty annotation.
This leads to missing comments and a lack of nested configuration options. Therefore, we use an independent module to copy the code and generate metadata.
## Principles
1. Copy classes under `org/apache/dubbo/config` from `dubbo-common` to the `generated-sources` directory.
2. Replace `@Nest` with `@NestedConfigurationProperty`.
3. Use an annotation-only option to compile and generate `spring-configuration-metadata.json`.
## How to add a new configuration option
- For standard configuration options, add javadoc to the corresponding configuration classes in `dubbo-common`.
- For non-standard configuration options, there are unnecessary to add nested classes. add them directly to `additional-spring-configuration-metadata.json`.
## Configuration Javadoc Guideline
1. For noun-type configuration options, use "The xxx" format for comments.
2. For boolean-type configuration options, use "Whether to xxx" format and add ", default value is <code>true</code>" at the end.
3. For configuration options with longer comments, use multi-line comments, with a clear summary in the first line.
4. All comments should end with a period.
---
### Threat Model (`docs/threat-model.md`)
# Threat Model — Apache Dubbo
## §1 Header
| Field | Value |
|-------|-------|
| **Project** | Apache Dubbo |
| **Version/commit** | 3.3 branch (commit to be pinned at release) |
| **Date** | 2026-06-05 |
| **Author(s)** | AI-assisted, maintainer-interviewed |
| **Status** | Reviewed — maintainer interview completed (Wave 1 + Wave 2) |
**Version binding.** This threat model is versioned alongside the project. A vulnerability report against Dubbo *N* is triaged against this model as it stood at *N*, not at HEAD.
**Reporting cross-reference.**
- Findings that violate §8 (claimed properties) should be reported to [security@dubbo.apache.org](mailto:security@dubbo.apache.org) per `SECURITY.md`.
- Findings that fall under §3 (out of scope) or §9 (disclaimed properties) will be closed citing this document.
**Provenance legend.**
| Tag | Meaning |
|-----|---------|
| *(documented)* | Stated in Dubbo's own docs (README, source comments, official website, SECURITY.md). Source cited inline. |
| *(maintainer)* | Stated by a maintainer in response to a question from this process. |
| *(inferred)* | Reasoned from code structure, absence of a feature, or general domain knowledge — not yet confirmed. Must have a matching entry in §14. |
**Draft confidence.**
| Tag | Count |
|-----|-------|
| *(documented)* | 30 |
| *(maintainer)* | 13 |
| *(inferred)* | 5 |
**One-paragraph description.** Apache Dubbo is a high-performance, extensible RPC and microservices framework for Java. It provides service discovery, load balancing, traffic management, and observability for distributed systems. Applications use Dubbo's API (Spring Boot starters or programmatic configuration) to export and consume remote services over protocols such as Triple (HTTP/2, gRPC-compatible), Dubbo TCP, and REST. Service metadata is managed through pluggable registries (ZooKeeper, Nacos, etc.) and configuration centers. Dubbo assumes an internal-network deployment model throughout *(maintainer)*.
---
## §2 Scope and intended use
### Primary intended use cases
- **In-process Java library** for building RPC-based microservices. A developer adds Dubbo as a dependency, configures service interfaces, and the framework handles remote invocation, serialization, service discovery, and load balancing *(documented: README.md)*.
- **Service-to-service communication** between Java applications (providers and consumers) within a trusted internal network. The entire framework is designed around this assumption *(maintainer — "整个Dubbo都默认在内网环境工作")*.
- **Polyglot communication** via Triple protocol (gRPC-compatible) with Go, Python, Rust, and other language implementations *(documented: README.md)*.
### Deployment contexts
- In-process Java library (not a standalone server or daemon).
- Typically deployed inside Spring Boot or plain Java applications.
- JDK 8–21 supported (3.3.x line) *(documented: README.md)*.
- Designed for internal data-center / VPC deployment; not designed for direct internet exposure.
### Caller expectations
| Role | Trust level | Description |
|------|-------------|-------------|
| **Provider developer** | Trusted | Configures and exports services; sets auth, SSL, serialization policy |
| **Consumer developer** | Trusted | Configures and invokes remote services |
| **Operator** | Trusted | Manages registry, config center, QoS access |
| **RPC Client (network)** | **Untrusted** | Any network client reaching the provider's RPC port |
| **Registry** | **Trusted** | Dubbo "can only fully trust the data [registries] push" *(documented: official security docs)*. Confirmed: compromised registry = total cluster compromise *(maintainer)*. |
| **Config Center** | **Trusted** | Pushes configuration that may contain credentials |
### Component-family table
| Family | Representative entry point | Touches network | In this model |
|--------|---------------------------|-----------------|---------------|
| **RPC Protocol (Triple)** | `TripleProtocol.export()`, `TripleProtocol.refer()` — port 50051 | Yes (HTTP/2) | Yes |
| **RPC Protocol (Dubbo TCP)** | `DubboProtocol.export()`, `DubboProtocol.refer()` — port 20880 | Yes (TCP) | Yes |
| **RPC Protocol (InJVM)** | `InjvmProtocol` | No (in-process) | Yes |
| **Serialization** | SPI: `Serialization` interface (Hessian2, Protobuf, Java, Fastjson2, etc.) | No (encoding layer) | Yes |
| **Registry** | `RegistryFactory` → ZooKeeper/Nacos/Multicast | Yes (registry protocol) | Yes |
| **Config Center** | `ConfigCenterFactory` | Yes (config protocol) | Yes |
| **Cluster / Routing** | `Cluster` SPI, `Router` SPI | No (in-process routing) | Yes |
| **QoS (Management)** | `QosProtocolWrapper` — port 22222 | Yes (TCP/HTTP) | Yes |
| **Authentication** | `dubbo-auth` plugin: `ConsumerSignFilter`, `ProviderAuthFilter` | No (filter chain) | Yes |
| **TLS / Certificate** | `SslConfig`, `DubboCertManager` | Yes (CA connection) | Yes |
| **Spring Security** | `dubbo-spring-security` / `dubbo-spring6-security` plugins | No (context propagation) | Yes |
| **dubbo-demo** | `dubbo-demo-api/`, `dubbo-demo-spring-boot/` | Varies | **No** — demo/test only |
| **dubbo-test** | `dubbo-test/` | Varies | **No** — test infrastructure |
| **dubbo-compatible** | Dubbo 2.x compatibility layer | No | **No** — scheduled for removal *(maintainer)* |
---
## §3 Out of scope (explicit non-goals)
### Use cases not supported
- **Direct internet exposure.** Dubbo is designed for internal networks. Exposing RPC ports (20880, 50051) or QoS (22222) to the internet without a reverse proxy, API gateway, or service mesh is not a supported use case *(documented: security docs — "deploy in trusted internal network"; maintainer)*.
- **Standalone authorization engine.** Dubbo has no built-in RBAC or ABAC. Authorization requires Istio integration *(documented: security docs — authorization is "equivalent to Istio documentation")*.
- **Certificate management and distribution.** Users must provide their own PKI. Dubbo recommends Istio for this *(documented: security docs)*.
- **Build-time or supply-chain security.** Dependency pinning, artifact signing, and reproducible builds are out of scope for this threat model.
- **Dubbo Admin.** Dubbo Admin is a separate project outside the Dubbo security boundary *(maintainer)*.
### Threats not defended against
- A **compromised registry** that pushes malicious provider addresses *(documented + maintainer confirmed)*.
- A **malicious provider** that returns crafted deserialized objects to exploit the consumer *(maintainer confirmed)*.
- **Insider attacks** from operators or developers with access to the registry, config center, or QoS port.
- **Denial of service** from unbounded resource consumption. Dubbo delegates rate limiting to external tools like Sentinel *(maintainer)*.
### Code that ships but is not covered
| Path | Reason |
|------|--------|
| `dubbo-demo/` | Demo/test only; explicitly for "debugging and smoke test purposes" *(documented: dubbo-demo README)* |
| `dubbo-test/` | Test infrastructure |
| `dubbo-compatible/` | Legacy compatibility; scheduled for removal *(maintainer)* |
| `*.class` files at repo root (e.g., `SimpleAI.class`) | Not part of the project |
---
## §4 Trust boundaries and data flow
### Trust boundary locations
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Data flow and trust transitions
1. **Provider registration**: Provider sends its URL (containing IP, port, serialization config, credentials) to the registry. **Trust transition**: Provider → Network → Registry. The registry is trusted to store and distribute this data faithfully.
2. **Consumer subscription**: Consumer queries the registry for provider URLs. **Trust transition**: Registry → Network → Consumer. Consumer trusts registry data *(documented + maintainer confirmed)*.
3. **RPC invocation**: Consumer serializes method arguments and sends them to the provider's port (20880 or 50051). **Serialization type is determined by provider-priority negotiation**: the Provider declares supported serialization formats in its URL; if multiple formats are declared, negotiation occurs with Provider priority *(maintainer)*. Provider deserializes and invokes. **Trust transition**: Consumer → Network → Provider. Without TLS, this is cleartext. Without auth, unauthenticated.
4. **RPC response**: Provider returns the result (serialized). Consumer deserializes. **Trust transition**: Provider → Network → Consumer. Consumer implicitly trusts the provider's return value *(maintainer confirmed)*.
5. **QoS command**: Client connects to port 22222 via TCP telnet or HTTP, sends command text. **Trust transition**: Network → QoS Server. When `acceptForeignIp=false` (default), only loopback connections are accepted. Default `anonymousAccessPermissionLevel` is `PUBLIC` *(maintainer confirmed — historical default)*.
### Reachability preconditions per component
| Component | Reachability precondition for a finding |
|-----------|----------------------------------------|
| RPC Provider | Attacker can reach the provider's RPC port (20880 or 50051) |
| RPC Consumer | Attacker controls a provider's return value OR the registry pushes a malicious provider address |
| Registry | Attacker has write access to the registry (ZK/Nacos) |
| QoS | Attacker can reach port 22222 (localhost or remote if `acceptForeignIp=true`) |
| Serialization | Attacker controls serialized data on the wire (either direction) |
| Config Center | Attacker has write access to the config center |
---
## §5 Assumptions about the environment
### Operating system and runtime
- **JDK 8–21** on Linux, macOS, Windows *(documented: README.md)*.
- JVM memory model; no native code (pure Java).
- Netty4 for network I/O (NIO/epoll).
### Concurrency
- Thread-per-connection model in Netty; Dubbo dispatches RPC calls to thread pools.
- `ServiceConfig` and `ReferenceConfig` are not thread-safe for concurrent reconfiguration *(inferred)*.
### Network
- **Internal network assumed throughout.** Dubbo's defaults (no TLS, no auth, no serialization strict mode) assume a trusted network. This is a foundational design assumption, not a temporary limitation *(documented: security docs; maintainer — "整个Dubbo都默认在内网环境工作")*.
- DNS is trusted for hostname resolution *(inferred)*.
### What Dubbo does *not* do to its host
- Does not open privileged ports (< 1024) by default.
- Does not write to system directories.
- Does not install signal handlers.
- Does not spawn external processes (user code might).
---
## §5a Build-time and configuration variants
### Security-relevant configuration knobs
| Knob | Default | Effect on security model | Discouraged? |
|------|---------|-------------------------|--------------|
| `ssl-enabled` | `false` | Without SSL, all RPC traffic is cleartext | No, but opt-in |
| `auth` | `false` | No authentication on RPC requests | No, but opt-in |
| `serialize.check.status` | `WARN` | Logs but allows unlisted class deserialization; `STRICT` would block | Will become `STRICT` eventually *(maintainer — "eventually")* |
| `serialize.check.serializable` | `true` | Enforces `Serializable` interface on deserialized classes | No |
| `qos.enable` | `true` | QoS server starts on port 22222 | No |
| `qos.acceptForeignIp` | `false` | QoS only accepts loopback connections | No |
| `qos.anonymousAccessPermissionLevel` | `PUBLIC` | Anonymous users get PUBLIC-level command access *(maintainer confirmed — historical default)* | **Review recommended** |
| `authenticator` SPI | `basic` | Authentication mechanism selection | No |
| Serialization SPI | `hessian2` | Default serializer is Hessian2 | No |
| `dubbo.cert.manager.caCertPath` | (empty) | Falls back to `InsecureTrustManagerFactory` if empty *(documented: code — "will use insecure connection")* | **Yes, code warns** |
| `dubbo.cert.manager.oidcTokenPath` | (empty) | Connects to CA without auth token | **Yes, code warns** |
### The insecure-default case
Dubbo's default configuration provides **no authentication, no encryption, and permissive deserialization**. This is by design for the assumed internal-network deployment. Every security property in §8 is conditional on opt-in configuration.
---
## §6 Assumptions about inputs
### Input sources
| Source | Example | Trusted? |
|--------|---------|----------|
| RPC request body (consumer → provider) | Serialized method arguments | **No** — attacker can reach the provider port |
| RPC response body (provider → consumer) | Serialized return value | **Partially** — trusted if provider is trusted; compromised provider can attack consumer *(maintainer confirmed)* |
| Registry data | Provider URLs | **Yes** *(documented + maintainer confirmed)* |
| Config center data | Application configuration | **Yes** |
| QoS command input | Telnet/HTTP text | **No** — any client reaching port 22222 |
| Serialization type | Determined by Provider-priority negotiation *(maintainer)* | **Provider-controlled** — Provider declares supported formats; Consumer negotiates within Provider's declared set |
| Dubbo URL parameters | Configuration strings | **Yes** — set by trusted developer/operator |
### Per-parameter trust table — RPC Provider (Dubbo TCP / Triple)
| Entry point | Parameter | Attacker-controllable? | Caller must enforce |
|-------------|-----------|----------------------|-------------------|
| Dubbo TCP request | Serialization type | **Partial** — bounded by Provider's declared supported formats *(maintainer)* | Provider should declare only intended serializers |
| Dubbo TCP request | Request body (serialized args) | **Yes** | `serialize.check.status=STRICT` + allowlist |
| Dubbo TCP request | Service/interface name | **Yes** | Provider must expose only intended interfaces |
| Dubbo TCP request | Method name | **Yes** | Provider must validate method exists |
| Dubbo TCP request | Attachments (metadata) | **Yes** | Provider must not trust attachment values blindly |
| Triple HTTP/2 request | Content-Type | **Yes** | Provider must validate content-type matches expected serializer |
| Triple HTTP/2 request | HTTP headers | **Yes** | Provider must validate auth headers |
| Triple HTTP/2 request | gRPC trailers | **Yes** | Provider must validate |
| RPC response | Return value (serialized) | **Partial** (provider-controlled) | Consumer must use `STRICT` serialization mode |
### Per-parameter trust table — QoS
| Entry point | Parameter | Attacker-controllable? | Caller must enforce |
|-------------|-----------|----------------------|-------------------|
| QoS telnet/HTTP | Command name | **Yes** | Permission level check |
| QoS `invoke` | Service/method selector | **Yes** | Must be PRIVATE permission |
| QoS `invoke` | JSON argument string | **Yes** | `PojoUtils.realize()` must be safe |
| QoS HTTP | Source IP | **Partial** (spoofable) | `acceptForeignIp` check |
### Size, shape, and rate assumptions
- **No built-in rate limiting** at the framework level. Rate limiting is delegated to external tools like Sentinel *(maintainer)*.
- **No request body size limit** enforced by Dubbo; Netty's default max message size applies (varies by configuration) *(inferred)*.
- **No limit on the number of service interfaces or methods** a provider exposes.
- Hessian2 deserialization can create deeply nested objects; no recursion depth limit enforced by Dubbo *(inferred)*.
---
## §7 Adversary model
### Assumed attacker (in scope)
**Network-level attacker** who can:
- Observe and modify traffic on the network between consumer and provider (MITM).
- Send crafted RPC requests to any provider's RPC port.
- Send crafted responses if they control a provider instance.
- Connect to the QoS port if it is accessible.
**Capabilities:**
- Can observe timing *(inferred: no constant-time guarantees)*.
- Can inject/modify packets on the wire (if TLS is not used).
- Can influence serialized data content (controls request body).
- Can request a serialization format, but **Provider has priority** in negotiation — the attacker cannot force a serialization format the Provider has not declared *(maintainer)*.
- Cannot break TLS/mTLS (assumes proper PKI).
- Cannot write to the registry (registry is trusted).
- Cannot write to the config center (config center is trusted).
### Explicitly out of scope
| Actor | Reason |
|-------|--------|
| Compromised registry | Dubbo explicitly trusts the registry *(documented + maintainer)* |
| Compromised config center | Configuration is trusted |
| Malicious Dubbo developer (insider) | Not a threat the framework can mitigate |
| Attacker with physical host access | OS-level compromise is out of scope |
| Compromised CI/CD pipeline | Supply-chain security is out of scope |
### Distributed-systems actor: authenticated-but-Byzantine provider
Dubbo's consumer implicitly trusts the provider *(maintainer confirmed)*. A **legitimately registered provider that turns malicious** (or serves compromised code) can:
- Return crafted serialized objects to exploit the consumer's deserialization *(maintainer confirmed)*.
- Slow-read or refuse connections to cause consumer timeouts.
- Return incorrect results without detection (no result integrity verification).
This actor is **in scope** but Dubbo provides **no defense** against it by default.
---
## §8 Security properties the project provides
### P1: Serialization class checking (conditional)
**Property:** When `serialize.check.status=STRICT`, Dubbo blocks deserialization of classes not on the allowlist, mitigating deserialization-based RCE. *(documented: code — `DefaultSerializeClassChecker`, official security docs)*
**Conditions:** Requires explicit opt-in (`STRICT` mode); only applies to serializers integrated with `SerializeSecurityManager` (Hessian2, Fastjson2). Java native serialization is NOT covered.
**Violation symptom:** Remote code execution via gadget chain deserialization.
**Severity tier:** Security-critical.
**Provenance:** *(documented: `DefaultSerializeClassChecker.java`, official security docs on serialization)*
### P2: Request authentication via HMAC (conditional)
**Property:** When `auth=true` and `authenticator=accesskey`, Dubbo authenticates RPC requests using HMAC-SHA256 signatures over `{serviceKey}#{method}#{secretKey}#{timestamp}`. *(documented: `AccessKeyAuthenticator.java`)*
**Conditions:** Requires explicit opt-in; credentials stored in URL parameters. Replay protection is **not provided** — the timestamp is signed but not validated for recency on the server side *(maintainer — timestamp validation is no longer planned)*.
**Violation symptom:** Unauthorized RPC invocations if credentials are compromised; replay of previously-signed requests.
**Severity tier:** Security-critical.
**Provenance:** *(documented: `AccessKeyAuthenticator.java`; maintainer on replay protection)*
### P3: Request authentication via Basic Auth (conditional)
**Property:** When `auth=true` and `authenticator=basic`, Dubbo authenticates using `username:password` (Base64-encoded). *(documented: `BasicAuthenticator.java`)*
**Conditions:** Requires explicit opt-in; credentials in URL parameters; Base64 is not encryption — requires TLS to be secure.
**Violation symptom:** Unauthorized RPC invocations.
**Severity tier:** Security-critical.
**Provenance:** *(documented: `BasicAuthenticator.java`)*
### P4: Transport encryption via TLS (conditional)
**Property:** When `ssl-enabled=true`, Dubbo encrypts RPC traffic using TLS via Netty's `SslHandler`. Supports mTLS. `DubboCertManager` is production-ready *(maintainer)*. *(documented: `SslConfig.java`, official security docs)*
**Conditions:** Requires explicit opt-in; certificates must be provided by the user; `DubboCertManager` falls back to `InsecureTrustManagerFactory` if `caCertPath` is empty *(documented: code warning)*.
**Violation symptom:** Eavesdropping, MITM, credential theft.
**Severity tier:** Security-critical.
**Provenance:** *(documented: `SslConfig.java`, `DubboCertManager.java`; maintainer on production readiness)*
### P5: QoS localhost restriction (default)
**Property:** When `qos.acceptForeignIp=false` (default), QoS only accepts connections from loopback addresses. Default `anonymousAccessPermissionLevel` is `PUBLIC` *(maintainer confirmed)*. *(documented: `QosProtocolWrapper.java`)*
**Conditions:** Default behavior; can be overridden by configuration.
**Violation symptom:** Remote invocation of QoS commands (including `invoke` for arbitrary method execution).
**Severity tier:** Security-critical.
**Provenance:** *(documented: `QosProtocolWrapper.java`; maintainer on PUBLIC default)*
### P6: Deserialization blocklist (defense-in-depth)
**Property:** Dubbo maintains a blocklist of known gadget chain classes (`security/serialize.blockedlist`) that are rejected even in `WARN` mode. *(documented: `DefaultSerializeClassChecker.java`, blocklist file)*
**Conditions:** Only as effective as the blocklist is complete; bypass has occurred historically.
**Violation symptom:** RCE via new or unblocked gadget chains.
**Severity tier:** Security-critical.
**Provenance:** *(documented: blocklist file with 195 entries)*
### P7: Provider-priority serialization negotiation
**Property:** The serialization format used for RPC is determined by Provider-priority negotiation. The Provider declares supported serialization formats; the Consumer negotiates within that set. A network attacker cannot force a serialization format the Provider has not declared. *(maintainer)*
**Conditions:** Effective when the Provider declares a limited set of serializers (e.g., Hessian2 only). If the Provider declares all installed serializers, the protection is reduced.
**Violation symptom:** Deserialization attacks via a permissive serializer if Provider declares too many formats.
**Severity tier:** Security-critical.
**Provenance:** *(maintainer)*
### P8: QoS invoke as a managed feature (conditional)
**Property:** The QoS `invoke` command is an officially supported feature *(maintainer)*. It is protected by the QoS permission system: `invoke` requires PRIVATE permission, which is only granted to localhost connections by default (when `acceptForeignIp=false`).
**Conditions:** Requires `qos.enable=true` (default). Safety depends on correct QoS access configuration. The `invoke` command uses `PojoUtils.realize()` for argument conversion, which bypasses the `SerializeSecurityManager` framework.
**Violation symptom:** Arbitrary method invocation on registered services if PRIVATE permission is incorrectly granted to remote users.
**Severity tier:** Security-critical.
**Provenance:** *(maintainer)*
---
## §9 Security properties the project does *not* provide
### NP1: Authentication by default
Dubbo ships with `auth=false`. Without explicit configuration, any client that can reach the provider port can invoke any service method. *(documented: default value, official docs)*
### NP2: Encryption by default
Dubbo ships with `ssl-enabled=false`. All RPC traffic (including authentication credentials) is transmitted in cleartext. *(documented: default value)*
### NP3: Strict deserialization by default
Dubbo ships with `serialize.check.status=WARN`. Unknown classes are logged but allowed. The project intends to change the default to `STRICT` eventually *(maintainer)*, but as of 3.3.x, permissive deserialization is the default.
### NP4: Result integrity verification
Dubbo does not cryptographically verify the integrity of RPC responses. A provider (or MITM if TLS is off) can return arbitrary data without detection. *(maintainer confirmed)*
### NP5: Built-in authorization
Dubbo has no standalone authorization engine. Service-level access control requires Istio integration. *(documented: official security docs — "equivalent to Istio documentation")*
### NP6: Timestamp validation / replay protection for HMAC auth
The `AccessKeyAuthenticator` includes a timestamp in the signature but the provider does not validate that the timestamp is recent. Replay protection is **not planned** *(maintainer)*. This is by design: valid signatures can be replayed indefinitely.
### NP7: Consumer protection from malicious providers
A consumer implicitly trusts serialized return values from providers *(maintainer confirmed)*. There is no mechanism for a consumer to verify provider identity beyond registry data.
### NP8: Rate limiting or resource bounding
Dubbo does not enforce request rate limits, connection limits, or payload size limits at the framework level. Rate limiting is delegated to external tools like Sentinel *(maintainer)*.
### False-friend properties
| What it looks like | What it actually is | Why it's not a security property |
|---------------------|---------------------|----------------------------------|
| Hessian2 is "safe by default" (Dubbo 3.2+) | Uses a class allowlist in STRICT mode | Default is WARN, not STRICT; allowlist may not cover all application classes |
| `AccessKeyAuthenticator` with timestamp | Looks like replay protection | Timestamp is signed but not validated for recency; replay is possible *(maintainer)* |
| QoS `acceptForeignIp=false` | Looks like access control | Default `anonymousAccessPermissionLevel=PUBLIC` grants PUBLIC-level access to localhost *(maintainer)* |
| `serialize.check.serializable=true` | Looks like deserialization safety | Only checks `Serializable` interface; most gadget chains implement it |
| `DubboCertManager` TLS | Looks like secure PKI | Falls back to `InsecureTrustManagerFactory` if CA cert not provided |
---
## §10 Downstream responsibilities
For the assumptions in §5–§7 to hold, the downstream integrator **must**:
1. **Enable TLS** (`ssl-enabled=true`) with proper certificates. Without TLS, all data and credentials are cleartext.
2. **Enable authentication** (`auth=true`) with `accesskey` authenticator. Basic Auth over cleartext is equivalent to no auth.
3. **Set `serialize.check.status=STRICT`** and maintain an application-specific allowlist.
4. **Declare only intended serialization formats** on the Provider. The Provider-priority negotiation protects only as well as the Provider's declaration is restrictive.
5. **Secure the registry** — enable ZooKeeper ACLs or Nacos authentication; keep the registry off public networks.
6. **Secure the config center** — authenticate connections; treat config data as trusted input.
7. **Configure QoS appropriately** — default `anonymousAccessPermissionLevel=PUBLIC` grants PUBLIC access to localhost. For production, set to `NONE` or disable QoS (`qos.enable=false`) if the `invoke` command is not needed.
8. **Do not expose RPC ports (20880, 50051) to the internet.** Use a reverse proxy, API gateway, or service mesh.
9. **Validate provider identity** — in environments with untrusted providers, use mTLS with client certificate verification.
10. **Review serialization configuration** — disable Java native serialization if not needed; prefer Protobuf for Triple protocol.
11. **Use Sentinel or equivalent** for rate limiting and circuit breaking — Dubbo does not provide these at the framework level.
---
## §11 Known misuse patterns
### M1: Exposing RPC ports to the internet
**What it looks like:** Deploying Dubbo providers with RPC ports reachable from the internet (e.g., via `0.0.0.0` bind + no firewall).
**Why it's unsafe:** Default Dubbo has no auth and permissive deserialization. Internet-facing Dubbo ports have led to RCE vulnerabilities *(documented: CVE history)*.
**What to do instead:** Deploy behind an API gateway; restrict to internal networks.
### M2: Using Java native serialization
**What it looks like:** Configuring `prefer-serialization=java` or including Java native serialization in the Provider's declared format set.
**Why it's unsafe:** Java native deserialization is the most common RCE vector in the JVM ecosystem. Dubbo's blocklist cannot cover all gadget chains. Java native serialization remains a supported format *(maintainer)* but is dangerous.
**What to do instead:** Use Hessian2 with `STRICT` mode, or Protobuf with Triple protocol.
### M3: Declaring all serialization formats on the Provider
**What it looks like:** A Provider declares every installed serialization format as supported, giving Consumers maximum flexibility.
**Why it's unsafe:** Even though serialization is Provider-priority *(maintainer)*, declaring all formats (including Java native) means a malicious Consumer can request the most permissive serializer. The negotiation protects only as well as the Provider's declaration is restrictive.
**What to do instead:** Declare only the serialization formats actually needed (e.g., Hessian2 for Dubbo TCP, Protobuf for Triple).
### M4: Using Basic Auth without TLS
**What it looks like:** `auth=true` + `authenticator=basic` without `ssl-enabled=true`.
**Why it's unsafe:** Basic Auth sends credentials as Base64-encoded strings (not encrypted). Network observers can capture credentials.
**What to do instead:** Always pair Basic Auth with TLS, or use `accesskey` authenticator with HMAC.
### M5: Using the HMAC authenticator without TLS
**What it looks like:** `auth=true` + `authenticator=accesskey` without TLS.
**Why it's unsafe:** While the HMAC secret is not transmitted, the request data is still in cleartext. An observer can capture valid signatures for replay (timestamps are not validated for recency, and replay protection is not planned *(maintainer)*).
### M6: Connecting `DubboCertManager` without CA certificate
**What it looks like:** Using the built-in certificate manager without setting `caCertPath`.
**Why it's unsafe:** The code falls back to `InsecureTrustManagerFactory.INSTANCE`, accepting any certificate *(documented: code warning — "will use insecure connection")*.
**What to do instead:** Always provide `caCertPath` and `oidcTokenPath` when using `DubboCertManager`.
### M7: Leaving QoS with permissive defaults
**What it looks like:** Running production Dubbo with `qos.enable=true` (default) and default `anonymousAccessPermissionLevel=PUBLIC`.
**Why it's unsafe:** The `invoke` command is an officially supported feature *(maintainer)* that can invoke any service method via reflection. While `invoke` requires PRIVATE permission, other PUBLIC-level commands may expose configuration or operational data.
**What to do instead:** Set `qos.anonymousAccessPermissionLevel=NONE` in production; restrict QoS to localhost only.
---
## §11a Known non-findings (recurring false positives)
### NF1: Telnet handler RCE on external port
**What scanners report:** Telnet handlers (`LogTelnetHandler`, `ChangeTelnetHandler`, etc.) in `dubbo-remoting-api` allow remote command execution.
**Why it's a non-finding:** These legacy telnet handlers are deprecated in 3.x and replaced by the QoS module. The telnet codec is retained for backward compatibility but is not exposed on external ports by default. The QoS module has its own permission system.
**Suppression:** Verify the finding is against `dubbo-remoting-api` telnet handlers, not the QoS module; verify the port is not externally accessible.
### NF2: Hessian2 class loading without blocklist
**What scanners report:** Hessian2 deserialization allows arbitrary class instantiation.
**Why it's a non-finding (partial):** Dubbo integrates `DefaultSerializeClassChecker` into Hessian2's serializer factory. Classes are checked against the blocklist (WARN mode) or allowlist (STRICT mode). This is a defense-in-depth measure, not a vulnerability in itself. However, if STRICT mode is not enabled, the protection is limited.
**Suppression:** Cite `Hessian2SerializerFactory.java` integration and §8 P6.
### NF3: `InsecureTrustManagerFactory` usage in tests
**What scanners report:** `InsecureTrustManagerFactory.INSTANCE` is used, accepting all certificates.
**Why it's a non-finding:** In test code and in `DubboCertManager` only as a fallback when `caCertPath` is not configured. The code explicitly warns about this case. `DubboCertManager` is production-ready *(maintainer)*; the fallback is an operator configuration issue.
**Suppression:** Verify the finding is in test code or the documented fallback path; cite §10 responsibility to provide `caCertPath`.
### NF4: Client-controlled serialization type
**What scanners report:** The Dubbo TCP protocol header contains a serialization type field that the client can set to any value.
**Why it's a non-finding:** Serialization type is determined by Provider-priority negotiation *(maintainer)*. The client cannot force a serialization format that the Provider has not declared. The protocol header field reflects the negotiated result, not an unconstrained client choice.
**Suppression:** Cite §8 P7 (Provider-priority serialization negotiation).
---
## §12 Conditions that would change this model
This threat model should be revised when:
1. **Default serialization mode changes** from `WARN` to `STRICT` (intended eventually *(maintainer)*).
2. **Authentication becomes default** (`auth=true`).
3. **New serialization formats** are added to the SPI.
4. **New protocol implementations** are added (e.g., a new transport).
5. **QoS default changes** (e.g., `anonymousAccessPermissionLevel` defaults to `NONE`).
6. **New trust boundaries** are introduced (e.g., mesh-sidecar communication).
7. **Registry integrity verification** is added.
8. **`dubbo-compatible` module is removed** *(maintainer)*.
9. **Replay protection is added** to `AccessKeyAuthenticator`.
10. **Framework-level rate limiting** is introduced.
---
## §13 Triage dispositions
| Disposition | Meaning | Licensed by |
|-------------|---------|-------------|
| `VALID` | Violates a claimed property in §8, via in-scope adversary and input | §8, §6, §7 |
| `VALID-HARDENING` | No §8 property violated, but API makes §11 misuse easy | §11 |
| `OUT-OF-MODEL: trusted-input` | Requires attacker control of a trusted parameter (registry, config center, URL config) | §6 |
| `OUT-OF-MODEL: adversary-not-in-scope` | Requires excluded attacker capability (compromised registry, insider) | §7 |
| `OUT-OF-MODEL: unsupported-component` | Lands in `dubbo-demo/`, `dubbo-test/`, `dubbo-compatible/`, or deprecated code | §3 |
| `OUT-OF-MODEL: non-default-build` | Only under discouraged §5a configuration (e.g., `caCertPath` empty) | §5a |
| `OUT-OF-MODEL: separate-project` | Lands in Dubbo Admin or other separate project | §3 |
| `BY-DESIGN: property-disclaimed` | Concerns a property explicitly disclaimed in §9 (e.g., no auth by default, no replay protection) | §9 |
| `KNOWN-NON-FINDING` | Matches documented false positive in §11a | §11a |
| `MODEL-GAP` | Cannot be routed to any above | Triggers §12 revision |
---
## §14 Open questions for the maintainers
All questions from Wave 1 and Wave 2 have been resolved. Answers:
### Wave 1 — Scope and trust model
| # | Question | Answer | Provenance update |
|---|----------|--------|-------------------|
| 1 | Registry trust | Confirmed: fully trusted, compromised registry = cluster compromise | *(documented + maintainer)* |
| 2 | Consumer-Provider trust | Confirmed: consumer implicitly trusts provider return values | *(maintainer)* |
| 3 | QoS default `anonymousAccessPermissionLevel` | `PUBLIC` — historical default | *(maintainer)* |
| 4 | STRICT mode timeline | Eventually, no target version | *(maintainer)* |
| 5 | Timestamp validation in AccessKeyAuthenticator | Not planned | *(maintainer)* → §9 NP6 confirmed by-design |
| 6 | Java native serialization support | Still supported | *(maintainer)* |
| 7 | Dubbo Admin scope | Separate project | *(maintainer)* → §3 updated |
### Wave 2 — Configuration and components
| # | Question | Answer | Provenance update |
|---|----------|--------|-------------------|
| 8 | Serialization type control | Provider-priority negotiation; Provider declares, then negotiation | *(maintainer)* → §6, §7, §8 P7 rewritten |
| 9 | `dubbo-compatible` security | Will be removed at some point | *(maintainer)* → §3 updated |
| 10 | Spring Security context propagation | Dubbo assumes internal network throughout; same security domain | *(maintainer)* |
| 11 | `DubboCertManager` readiness | Production-ready | *(maintainer)* → §8 P4 updated |
| 12 | Rate limiting plans | No; delegated to Sentinel etc. | *(maintainer)* → §9 NP8 confirmed |
| 13 | QoS `invoke` command | Official feature, not just debugging | *(maintainer)* → §8 P8 added, §11 M4 rewritten |
### Remaining *(inferred)* claims
The following *(inferred)* claims remain and could benefit from further maintainer input:
1. `ServiceConfig`/`ReferenceConfig` not thread-safe for concurrent reconfiguration — §5.
2. DNS trusted for hostname resolution — §5.
3. No recursion depth limit in Hessian2 deserialization — §6.
4. No request body size limit enforced by Dubbo (Netty defaults apply) — §6.
5. No constant-time guarantees (timing observable) — §7.
These are low-impact inferences that do not materially affect triage decisions. They can be confirmed or corrected in a future revision.
---
## §15 Optional: machine-readable companion
A machine-readable companion (`threat-model.yaml`) can be generated for automated triage. Structure:
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
*End of threat model. Maintainer interview completed 2026-06-05. Remaining 5 low-impact *(inferred)* claims listed in §14 may be confirmed in a future revision.*
---
--- METRICS ---
- Files Extracted: 10
- Estimated Token Budget: ~21402 tokens
- Canonical Reference: https://codewiki.google/github.com/apache/dubbo