erickguan commented on code in PR #7641: URL: https://github.com/apache/opendal/pull/7641#discussion_r3413260133
########## SECURITY-THREAT-MODEL.md: ########## @@ -0,0 +1,440 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# Apache OpenDAL Security Threat Model + +## 1. Status + +This document defines the security boundary for Apache OpenDAL. It is intended +for maintainers, security reporters, downstream users, and automated security +scanners that need to decide whether a report describes an OpenDAL +vulnerability or a responsibility of the embedding application, storage backend, +or deployment. + +The canonical disclosure process remains +[`website/community/security.md`](website/community/security.md). Reports that +may affect OpenDAL security should be sent to `[email protected]` +before public disclosure. + +## 2. Purpose + +OpenDAL is an in-process storage access library. It gives a host application a +uniform `Operator` API over many storage backends. It is not a daemon, gateway, +identity provider, authorization service, sandbox, or multi-tenant broker. + +The purpose of this document is to help maintainers triage security reports by +answering three questions: + +1. What does OpenDAL treat as its own security boundary? +2. What is delegated to the embedding application or storage provider? +3. Which reports are OpenDAL vulnerabilities, hardening requests, caller + misuse, or out-of-scope deployment issues? + +The most important premise is: + +> OpenDAL trusts the storage service that the caller configured it to access. + +If a caller intentionally points OpenDAL at an untrusted S3-compatible endpoint, +WebDAV server, FTP server, database, local path, or other backend, the caller +is responsible for the consequences of trusting that backend. OpenDAL does not +authenticate remote object contents, prove remote metadata correctness, or +protect the caller from a malicious storage service that the caller chose. + +That premise does not remove OpenDAL's responsibility for its own library +boundary. OpenDAL must still preserve its API contracts, keep credentials +isolated, avoid leaking secrets through debug or observability output, and avoid +memory-safety violations in code reachable through the public API. + +## 3. System Model + +An OpenDAL deployment has these participants: + +| Participant | Role in this model | +| --- | --- | +| Host application | Trusted caller that creates `Builder`s, supplies config, applies `Layer`s, and decides which end-user input may reach OpenDAL. | +| OpenDAL | In-process library that normalizes public API inputs, builds service requests, signs requests when configured, parses service responses, and returns data or errors. | +| Storage backend | A trusted service that the host application use. e.g., An OpenDAL uses connects to S3, or a database uses OpenDAL communicates with Google Cloud. OpenDAL trusts a trusted service for backend-side authentication, object bytes, metadata, consistency, and durability. | +| End user of the host application | Out of OpenDAL's direct model. The host application must authenticate, authorize, and sanitize end-user requests before calling OpenDAL. | +| Network attacker | Out of scope unless the report shows OpenDAL weakened the configured transport. TLS and proxy policy are delegated to the HTTP client and host environment. | + +OpenDAL doesn't use principal model. A `Operator` takes control of a backend service by user-provided credentials, root and other configurations. Every operation via an +`Operator` instance shares the same OpenDAL-level authority. +A typical interaction will be: + +Trusted service <-> Backend <-> Operator <-> Host Application <-> End user + | | + |------------------------| + OpenDAL code surface +## 4. Security Boundary + +OpenDAL's security boundary is the public library boundary plus the internal +state that OpenDAL owns behind that boundary. + +The following properties are in scope for OpenDAL security. + +### 4.1 Public API contract + +OpenDAL must handle inputs accepted by the public API without memory-safety +violations, data races, panics across FFI boundaries, or inconsistent internal +state. + +Examples: + +- `Operator` path normalization must be deterministic and consistent with the + documented path rules in `core/core/src/raw/path.rs`. +- `Operator::from_uri(...)` and `Operator::via_iter(...)` must build the service + and root implied by trusted caller config. +- Public operation options such as ranges, conditional headers, metadata, and + presign expiry must be encoded according to the selected service contract. + +OpenDAL does not decide whether a host application's end user is allowed to use +a path. The host application owns that policy. However, once the host +application passes a path into OpenDAL, OpenDAL must not accidentally map it to +OpenDAL does not care whether a host application's end user has permissions for a path access. A host application decides what and how to interact with data and path with a configured service via an `Operator` instance. In another word, if +a host application passes a path into OpenDAL, OpenDAL must not map it to +a different backend location than that backend's API contract describes. e.g. when passing `/path` to an `Fs` operator, OpenDAL should only access `/path`. + +### 4.2 Local resource boundary + +Remote storage services are trusted by configuration. Local resources touched +directly by OpenDAL are different because OpenDAL itself constructs host +filesystem paths, cache directories, temporary files, and local database paths. + +For local services and layers, OpenDAL is responsible for the filesystem effects +created by its own path construction. + +Examples: + +- `services::Fs` documents `root` as the root under which operations happen. + Reports showing that normalized OpenDAL paths can escape that configured root + through OpenDAL's path construction are in scope. +- `services::Foyer` and `FoyerLayer` can use on-disk cache storage. Reports about + OpenDAL writing cache data outside the configured cache location, leaking + credentials into cache metadata, or corrupting unrelated local files are in + scope. +- `atomic_write_dir` and temporary-write behavior are in scope when OpenDAL + creates or renames files itself. + +Symlink behavior for local filesystems should be documented explicitly by the +service. A report about symlink traversal should not be closed solely because +OpenDAL is a library; it should be triaged against the service's documented +local filesystem contract. + +### 4.3 Credential isolation + +OpenDAL must not leak credentials between independent operators, services, or +layers in the same process. + +Examples: + +- A request from `Operator` B must not be signed with credentials from + `Operator` A. +- An OAuth token, temporary credential, signer context, or credential-provider + cache must not be shared across operators unless the sharing is explicitly + configured by the caller. +- `disable_config_load`, `disable_ec2_metadata`, and `disable_vm_metadata` must + prevent the ambient credential sources they document. + Review Comment: Ok -- 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]
