chenBright commented on code in PR #3324: URL: https://github.com/apache/brpc/pull/3324#discussion_r3346986780
########## THREAT_MODEL.md: ########## @@ -0,0 +1,627 @@ +# Apache bRPC — Threat Model (v1 draft) + +## §1 Header + +- **Project:** Apache bRPC (`apache/brpc`). +- **Scope:** the `apache/brpc` repository only. The PMC confirmed on 2026-05-20 that `apache/brpc-website` is out of scope for this engagement. This draft is first authored by the ASF Security Team and then reviewed by the PMC. +- **Version binding:** based on `master` around 2026-05-21. Vulnerability reports should be triaged against the model for the corresponding version, not against `HEAD`; re-bind on each release. +- **Authors and status:** drafted by the ASF Security Team (Glasswing pre-scan), revised by PMC member Weibing Wang. **DRAFT v1** +- **Reporting entry point:** at drafting time, the repository had no `SECURITY.md`, and the Apache security project index listed only the generic `[email protected]` address. Until project-level disclosure documentation is published, report vulnerabilities to `[email protected]` per ASF policy. +- **Provenance legend:** + - *(documented — source)*: from repository documentation, headers, gflags, source code, or Apache governance artifacts. + - *(inferred — Qn)*: inferred from code structure, general RPC security experience, or absence of a defense, with a corresponding question in §14. + - *(maintainer)*: not yet used in this draft; to be substituted after PMC confirmation. +- **Draft confidence:** most factual descriptions in §1-§13 come from documentation and source code. Intent, default security posture, resource boundaries, the built-in service trust model, and vulnerability triage criteria still require confirmation in §14. +- **bRPC overview:** bRPC is an embeddable C++ RPC framework that supports dispatching multiple protocols on the same port via content sniffing, including `baidu_std`, HTTP/1.x, HTTP/2/gRPC, Thrift, Redis, memcached, RTMP, Mongo, the nshead family, and others. It provides naming services, load balancers, optional TLS, bthread scheduling, and HTTP built-in admin services. bRPC is not a standalone daemon; downstream applications link `libbrpc` and start `brpc::Server` in-process. + +--- + +## §2 Scope and intended use + +bRPC's primary uses are: + +1. Expose one or more `google::protobuf::Service` implementations on a TCP port, with multiple protocols sharing the same port. +2. Act as a client `brpc::Channel` to access a single server or a cluster described by a naming service plus load balancer. +3. Be embedded by a host application; deployment, TLS, network exposure, authentication, routing, and process lifecycle are the responsibility of the application or operator. +4. Use built-in services such as `/status`, `/vars`, `/flags`, `/connections`, `/rpcz`, and `/health` for debugging and monitoring. +5. Use bRPC as an HTTP/h2 server or client, including Restful URL mapping and JSON-to-Protobuf / Protobuf-to-JSON conversion. + +bRPC is not a secure-by-default managed service. Threats land in the runtime code linked by the application and in the built-in admin services the application chooses to expose. + +### Caller / actor roles + +- **Application developer:** defines `.proto` files, implements services, chooses protocols and ports, and calls clients. Trusted within the compile-time and configuration boundary. +- **Operator:** runs the binary and configures ports, `internal_port`, TLS, gflags, naming services, rate limiting, and built-in services. Trusted for that instance. +- **Client peer (RPC client):** sends bytes to a bRPC server. Untrusted by default; protocol sniffers must handle arbitrary input. +- **Server peer:** the remote server that a bRPC client connects to. Response bytes are also untrusted. +- **Naming-service backend:** `bns`, `file`, `consul`, `nacos`, DNS, and similar backends. Configured by the operator and treated by bRPC as trusted infrastructure. +- **Built-in admin-service consumer:** a person or program accessing `/status`, `/flags`, `/rpcz`, and similar endpoints. Its trust level depends entirely on whether the operator places these endpoints on an internal network or disables them. + +### Component-family table + +| Family | Representative entry point | Touches outside the process? | In model? | +| --- | --- | --- | --- | +| **C++ runtime core** | `Server::Start`, `Channel::CallMethod`, `Socket`, `InputMessenger` | sockets, files, threads, TLS, optional RDMA | **In model** | +| **Wire-protocol parsers** | `Parse*Message` | reads untrusted bytes from sockets | **In model**, highest priority | +| **HTTP / h2 (+ gRPC) stack** | `HttpServerHandler`, `H2StreamContext`, `URI` | sockets, TLS, json2pb | **In model** | +| **Built-in admin services** | `/status`, `/vars`, `/flags`, `/rpcz`, `/dir`, `/threads`, profiler, metrics | HTTP, `/proc`, filesystem, profiler | **In model**, depending on exposure | +| **TLS / SSL layer** | `ServerSSLOptions`, `ChannelSSLOptions` | OpenSSL, certificate files | **In model** | +| **Authentication hooks** | `Authenticator::VerifyCredential` | wire token | **In model**, policy is implemented by the application | +| **Naming services** | `file://`, `http(s)://`, `consul://`, `nacos://`, `dns://` | files and network | **In model**, backend treated as trusted | +| **Load balancers** | rr, wrr, random, la, consistent hashing | pure computation | **In model**, not a direct attack surface | +| **Compression layer** | gzip/snappy/zlib/lz4 | CPU/memory | **In model** | +| **RDMA transport** | `rdma://` | verbs API, pinned memory | **In model** only when enabled at build time and runtime | +| **Coroutine bridge** | `usercode_in_coroutine` | scheduling | **In model** in non-default mode | +| **bthread / butil / bvar** | scheduler, IOBuf, counters | threads, futex, files, `/proc` | **In model** | +| **mcpack2pb / json2pb** | mcpack/JSON <-> pb | pure computation | **In model** on the corresponding protocol paths | +| **Java / Python bindings** | JNI / pyBRPC | language bridge | currently unsupported; **Out of model** | +| **tools / test / example / build / community / docs** | CLI, tests, examples, build, governance, docs | non-production runtime surface | **Out of model** | + +Wire-protocol parsers are the most important surface: they directly receive untrusted bytes, are implemented in C++, cover many protocols with different maturity levels, and multi-protocol sniffing can make every registered parser reachable from the same listening port. `enabled_protocols` can restrict the sniffing set, but its implementation details need maintainer confirmation. + +--- + +## §3 Out of scope (explicit non-goals) + +The following scenarios or threats are not protected by the bRPC threat model. Matching reports are closed according to §13. + +### Use cases out of scope + +1. **A secure-by-default RPC endpoint.** bRPC provides components, not a `brpcd` with a strong default security posture. +2. **A sandbox or process-isolation boundary.** Deserialization, business handlers, and the host application run in the same process. +3. **Cryptographic primitives.** TLS security comes from OpenSSL; bRPC only wraps and configures it. +4. **An application field-validation framework.** bRPC validates wire framing, not semantic fields such as email addresses, IDs, or business ranges. +5. **A complete replacement for authenticated transport.** Bare `baidu_std`, HTTP, Thrift, Redis, and similar protocols have no default authentication; `Authenticator` and mTLS require explicit configuration. +6. **A general HTML/JSON rendering security surface.** Escaping in application HTTP handlers is the application's responsibility. +7. **A general file server.** `/dir` is disabled by default and is not modeled as a production file-serving feature. +8. **Exposing built-in services to the public internet.** bRPC built-in services should only be exposed to trusted internal consumers. + +### Threats explicitly out of scope + +8. Attackers who control the calling process, can read/write process memory, or can call arbitrary bRPC APIs. +9. Attackers who control the compiler, dependencies, build environment, or supply chain. +10. Side channels such as timing, cache, power, and RowHammer. +11. Raw socket-layer DoS: SYN flood, slowloris, half-open connection exhaustion, and kernel table exhaustion. +12. Resource exhaustion in `bvar`/`bthread`/`butil` caused purely by in-process call patterns. +13. Performance loss caused by an operator intentionally enabling expensive tracing/profiling. +14. Compromise of the naming-service backend; bRPC trusts the backend configured by the operator. +15. Vulnerabilities in application handlers, such as SQL injection or missing business authorization. Review Comment: The serial number is incorrect; it should start from 1. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
