diff --git a/website/community/security-model.md b/website/community/security-model.md new file mode 100644 index 000000000..95feb85ed --- /dev/null +++ b/website/community/security-model.md @@ -0,0 +1,137 @@ +--- +id: 'security-model' +title: 'Security Model' +--- + + + +Apache Fesod (Incubating) runs as a library inside your Java application and builds on Apache POI for Excel processing. This security model describes the assumptions and responsibilities for reading and writing Excel and CSV files, including related conversion features. + +**Password protection of a completed XLSX file does not encrypt all data used while processing it.** Plaintext may exist in temporary files, caches, output locations, and JVM memory. Applications and operators must protect each of these locations. + +## Scope and Trust Boundaries + +Apache Fesod (Incubating) performs file access, memory allocation, and enabled network operations with the privileges of its JVM process. It does not provide application authentication, business authorization, or tenant isolation. Use maintained versions of Apache Fesod (Incubating), the JDK, and dependencies, and check the capabilities and configuration of the version you deploy. + +| Resource or operation | Security expectation | Application and operator responsibility | +| --- | --- | --- | +| Application code, converters, listeners, and handlers | Extensions execute as trusted code in the same JVM | Do not execute extensions supplied by untrusted users; extensions can access resources available to the process | +| Documents, templates, and cell data | Input may contain malicious or unexpected content; parsing and streaming APIs are not a sandbox | Validate business input, limit resource consumption, and isolate processing according to risk | +| Local paths and streams | Apache Fesod (Incubating) reads and writes the paths or streams supplied by the caller | Authorize access, protect input, output, and template directories, and isolate tenants | +| Temporary files and read caches | Intermediate data may contain unencrypted workbook or cell content | Prevent untrusted parties from reading, modifying, or replacing temporary storage and its contents | +| JVM memory, dumps, and logs | Sensitive content or passwords may be present | Control debugging, dumps, logs, backups, and access to the service identity separately | +| Network features such as URL images | Remote fetching is disabled by default and requires an explicit exact-host allowlist; requests originate from the JVM process | Keep the default deny policy or restrict destinations, apply network egress controls, and do not directly trust user-supplied URLs | +| Password-protected XLSX output | Successfully completed output uses Apache POI workbook encryption | Protect passwords, intermediate plaintext, and failed output; publish only after successful completion | + +Apache Fesod (Incubating) does not promise to hide data from parties that already have access to the corresponding application files, temporary storage, or process memory. These are separate permissions: the ability to read a temporary file does not imply the ability to inspect JVM heap memory, or vice versa. + +## Relationship with Apache POI {#apache-poi} + +Apache POI's security guidance, supported behavior, and implementation limits must be considered when using Apache Fesod (Incubating)'s POI-based features. A higher-level Apache Fesod (Incubating) API does not remove POI's requirements for protected temporary storage and process memory, resource isolation, or the limitations of its document formats and encryption support. Review the [Apache POI security guidance](https://poi.apache.org/security.html) alongside this model for the POI version used by your application. + +Apache Fesod (Incubating) aims to respect POI's security model, API contracts, and protective checks. It does not aim to bypass POI's safeguards or promise stronger security properties than the underlying implementation provides. Applications should not disable or weaken POI's protections merely to accept a document that is rejected by those checks. Any necessary configuration change must follow POI's documented behavior and account for its security impact, including effects on other code sharing the same JVM. + +This dependency does not remove Apache Fesod (Incubating)'s responsibility for its own code and integration. Unexpected behavior introduced by Apache Fesod (Incubating), or a bypass of security controls through its APIs, should still be reported privately for assessment. Support for a capability in POI does not by itself mean that every Apache Fesod (Incubating) API exposes or enables that capability. + +## Temporary Files and Caches {#temporary-files-and-caches} + +Apache Fesod (Incubating) and its dependencies may use temporary files or disk caches during reading, streaming writes, template processing, and encryption or decryption. Intermediate data may be unencrypted even when the final workbook is password-protected. + +Operators must provide a protected temporary directory for the JVM and protect any separately configured cache, staging, or output locations. Untrusted parties must not be able to read, modify, or replace these directories or their contents. Random names and the sticky bit on a shared directory do not replace access controls. + +On POSIX systems, create a private directory under the service's operating system identity before starting the application: + +```sh +umask 077 +FESOD_TMPDIR="$(mktemp -d "${TMPDIR:-/tmp}/fesod.XXXXXXXX")" || exit 1 +chmod 700 "$FESOD_TMPDIR" || exit 1 +java -Djava.io.tmpdir="$FESOD_TMPDIR" -jar app.jar +``` + +The parent directory must prevent untrusted parties from replacing the private directory. On Windows, use equivalent ACLs. This example protects the default JVM temporary location; separately configured locations need their own protection. Directory permissions do not isolate untrusted tenants that share the same operating system identity. + +Set `java.io.tmpdir` when starting the JVM. Changing it after library initialization does not ensure that every component switches directories. In containers, use protected temporary volumes dedicated to the workload, and avoid sharing accessible staging storage with untrusted workloads. + +Close readers and writers and complete their resource-release lifecycle. During normal resource release, the library and its dependencies attempt to remove temporary files and caches managed by the current operation, including operation-specific temporary subdirectories where applicable. Cleanup is not guaranteed to succeed. + +The library does not perform a general cleanup of shared temporary directories or residual files from earlier runs or other processes. Exceptions, forced termination, host failures, or deletion failures may leave intermediate files behind. Operators must protect temporary storage and arrange controlled cleanup of residual files that are no longer in use by active tasks. Ordinary deletion is not secure erasure and does not remove storage snapshots or backups. + +## Password Protection {#password-protection} + +When writing XLSX with a non-empty password, successfully completed output uses Apache POI's workbook encryption. This protects the completed file's content; it does not provide encryption throughout input, processing, staging, and delivery, nor does it provide authentication, authorization, or a guarantee of password strength. + +The encryption mode is selected by the library, not by the caller. Current releases use Apache POI's standard encryption mode, which is AES-128 with the SHA-1 based key derivation defined by the Office Open XML standard, not the more recent agile mode that allows AES-256. The mode determines key length and key derivation, and therefore how well a completed file resists offline password guessing. Verify the mode used by the version you deploy rather than assuming a stronger one, and reassess if your threat model depends on it. + +Password protection is an access-control measure for data at rest and in transit. It is not a substitute for controlling who can obtain or retain the file, and it is not the right mechanism for long-term storage of high-value secrets. + +Encryption may first produce a plaintext workbook before producing the encrypted result. When writing directly to a file path, that location may also contain plaintext during processing. Protect output locations and prevent downloads or publication until the entire write operation has completed successfully. + +When writing in batches with `ExcelWriter`, a successful `write()` call does not mean that output or encryption is complete. Publish only after all writes and the final `finish()` or `close()` call succeed. With try-with-resources, publish after the entire statement completes normally, not inside its block. + +Treat output from a failed write or encryption operation as incomplete and sensitive. Do not assume that a failure leaves an encrypted file, an empty file, or no file. Where publication must be controlled, generate the result in protected staging storage and publish it only after success. + +An in-memory option is not a promise that every Apache Fesod (Incubating) or dependency execution path avoids disk storage. CSV has no workbook password encryption, and legacy XLS protection must not be assumed to provide the same confidentiality as XLSX encryption. + +Obtain passwords from controlled configuration or a secrets manager. Keep them out of source code, logs, and exception output. Password protection does not replace filesystem permissions, protected transport, or sensitive-data retention policies. + +## Untrusted Documents and Resource Isolation + +Compressed data, shared strings, images, styles, and complex document structures may consume substantial CPU, memory, or disk space. Input size, filename extension, and use of streaming APIs do not guarantee bounded processing costs. Existing checks do not provide complete protection against every malicious document. + +OOXML archives are read through Apache POI, which applies its own expansion-ratio limits to compressed entries. Those limits reject some highly compressed input, but they are a heuristic bound on expansion, not a reliable isolation mechanism. Do not treat them as a substitute for process-level limits. + +Replacing the default XML parser factory changes the parser hardening applied while reading. The library configures DOCTYPE and external-entity restrictions on the parser it creates, but a replacement factory that does not support those settings will not enforce them. If you supply your own factory, verify that equivalent protections are active. + +For externally supplied files, limit input and output size, concurrency, temporary storage, and application-level processing volume. Services requiring reliable isolation from timeouts or memory exhaustion should process documents in a separate process or container, with an external supervisor enforcing time, resource, and network limits. Do not rely on thread interruption to stop every parsing operation. + +Do not treat partially imported data or incomplete exports as successful business operations. Applications are responsible for transaction boundaries, data validation, and retry behavior. + +## Paths, Networks, and Spreadsheet Clients + +Do not pass user input directly as an unrestricted local path. Restrict allowed roots, authorize the actual target, and account for symbolic links and concurrent replacement. Apache Fesod (Incubating) does not know which user or tenant a caller-supplied path belongs to. + +For URL images and other network features, remote fetching is disabled by default and must be enabled with an explicit exact-host allowlist. Requests originate from the server. Allowing a domain does not authorize every location to which it might resolve or redirect. Network operations in custom converters require the same care. + +The URL fetch policy is process-wide, not per workbook or per reader. Any code in the JVM can change it, and a change affects every component using Apache Fesod (Incubating) in that process, including components that believed fetching was disabled. Set it once during application startup, do not let independent modules override each other at runtime, and confirm the effective policy where several libraries share a JVM. + +Apache Fesod (Incubating) does not provide a general sanitization policy for formulas, hyperlinks, external references, or CSV values. Spreadsheet applications may interpret exported content when a user opens the result. Distinguish text from intentionally supplied formulas and choose an output policy appropriate to the data source and target client. CSV quoting alone does not prevent formula injection. + +## Reporting Vulnerabilities and Hardening Suggestions + +If behavior may cross these boundaries or cause unexpected data disclosure, file access, network requests, or code execution, report it privately to [security@apache.org](mailto:security@apache.org). Identify Apache Fesod (Incubating) and include the version, configuration, attacker prerequisites, impact, and a minimal reproduction. Do not first disclose potential vulnerability details in public issues, pull requests, or mailing lists. + +Use the private reporting channel when you are unsure whether an issue is a vulnerability. The project assesses actual behavior, affected versions, and applicable security expectations. Dependency advisories require analysis of the relevant usage path. Reports of bypassed security controls are not excluded solely because operators also have security responsibilities. + +The following are generally not vulnerabilities in Apache Fesod (Incubating) itself, because the boundary is on the application side. They are still worth reporting if the library could reasonably prevent the outcome: + +- Passing an untrusted string to the library as a local path, which makes the application the origin of a path traversal +- Supplying a replacement XML parser factory, or widening the URL fetch policy, and then relying on the library to restore protections the caller disabled +- Leaving plaintext in an unprotected temporary or output directory that the application configured +- A completed password-protected file being guessable because the application chose a weak password + +Risks from operating outside a protected environment generally require deployment changes. The project also welcomes hardening suggestions, such as stricter temporary-file permissions and more reliable cleanup. Vulnerability classification, CVE allocation, and adoption of hardening improvements are separate decisions. + +## Supported Versions and Disclosure + +Security fixes are provided on the most recent release line. Older release lines do not receive backported fixes; upgrade to a maintained version before reporting an issue that may already be addressed. The project follows the [ASF vulnerability handling process](https://www.apache.org/security/committers.html): reports are discussed privately, a fix is prepared, and disclosure is coordinated with the reporter. A CVE is requested when the project and the ASF Security Team determine that the issue warrants one. + +## Further Reading + +- [Apache Fesod (Incubating) security reporting and dependency advisories](./security.md) +- [Apache POI security guidance](https://poi.apache.org/security.html) +- [ASF Security Team](https://www.apache.org/security/) diff --git a/website/community/security.md b/website/community/security.md index 82eabf675..944238873 100644 --- a/website/community/security.md +++ b/website/community/security.md @@ -22,6 +22,8 @@ title: 'Security' The Apache Software Foundation takes a rigorous stance on eliminating security issues in its software projects. Likewise, Apache Fesod (Incubating) is also vigilant and takes security issues related to its features and functionality into the highest consideration. +See the [Security Model](./security-model.md) for Apache Fesod (Incubating)'s trust boundaries, password-protection scope, and application and operator responsibilities. + If you have any concerns regarding Apache Fesod (Incubating)’s security, or you discover a vulnerability or potential threat, please don’t hesitate to get in touch with the [Apache Security Team](http://www.apache.org/security/) by dropping an email at [security@apache.org](mailto:security@apache.org). Please specify the project name as "Apache Fesod (Incubating)" in the email, and provide a description of the relevant problem or potential threat. You are also urged to recommend how to reproduce and replicate the issue. diff --git a/website/docs/sheet/advanced/password.md b/website/docs/sheet/advanced/password.md index 69125f6c7..70835c3f2 100644 --- a/website/docs/sheet/advanced/password.md +++ b/website/docs/sheet/advanced/password.md @@ -26,7 +26,7 @@ This chapter introduces how to read and write password-protected Excel files. ## Overview -Fesod supports Excel's built-in password protection for both reading and writing. Use `.password("xxx")` on the builder to encrypt/decrypt files. For `.xlsx` output, Fesod uses Apache POI's encryption (AES-based) which can be memory-intensive for large workbooks. For legacy `.xls` files, password protection behaves as write-protection rather than full content encryption, so behavior and security guarantees differ from `.xlsx`. +Apache Fesod (Incubating) supports Excel's built-in password protection for both reading and writing. Use `.password("xxx")` on the builder to configure the password. Successfully completed `.xlsx` output with a non-empty password uses Apache POI's encryption (AES-based), which can be memory-intensive for large workbooks. Legacy `.xls` protection differs from `.xlsx` encryption and must not be assumed to provide equivalent confidentiality. ## Writing with Password @@ -67,6 +67,10 @@ public void passwordRead() { ## Security Notes -- Excel password protection encrypts the file content, making it unreadable without the password. +- XLSX password protection applies to successfully completed output; it does not encrypt all temporary files, caches, or JVM memory used during processing. +- Protect temporary and output directories from untrusted access. File output may contain plaintext during processing; publish results only after the entire write succeeds. +- Treat output from a failed write or encryption operation as incomplete and sensitive, and do not deliver it. - Without the correct password, reading will throw an `EncryptedDocumentException`. - In production, avoid hardcoding passwords — use configuration files or secrets management. + +See the [Security Model](/community/security-model#password-protection) for encryption boundaries, [temporary-file requirements](/community/security-model#temporary-files-and-caches), and [Apache POI's role and limitations](/community/security-model#apache-poi). diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security-model.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security-model.md new file mode 100644 index 000000000..65c406abe --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security-model.md @@ -0,0 +1,135 @@ +--- +id: 'security-model' +title: '安全模型' +--- + + + +Apache Fesod (Incubating) 是嵌入 Java 应用运行的电子表格处理库，其 Excel 处理能力基于 Apache POI 实现。本安全模型说明读写 Excel、CSV 及相关转换功能时的信任假设和责任边界。 + +**成功生成的 XLSX 文件受到密码保护，不代表处理期间的所有数据也已加密。** 明文可能存在于临时文件、缓存、输出位置和 JVM 内存中，应用与部署方需要分别保护这些位置。 + +## 适用范围与信任边界 + +Apache Fesod (Incubating) 以所在 JVM 进程的权限执行文件访问、内存分配和已启用的网络操作。它不提供应用身份认证、业务授权或租户隔离机制。应用应使用受维护的 Apache Fesod (Incubating)、JDK 和依赖版本，并确认所部署版本的具体能力与配置。 + +| 对象或操作 | 安全预期 | 应用与部署方责任 | +| --- | --- | --- | +| 应用代码、转换器、监听器和处理器 | 自定义扩展作为受信任代码在同一 JVM 中执行 | 不执行来自不可信用户的扩展代码；扩展可访问进程拥有的资源 | +| 输入文档、模板与单元格数据 | 输入可能包含恶意或异常内容；解析和流式 API 不构成沙箱 | 验证业务输入，限制资源消耗，按风险隔离处理进程 | +| 本地路径和文件流 | Apache Fesod (Incubating) 按调用方指定的路径或流读写 | 校验路径授权，保护输入、输出及模板目录，隔离不同租户 | +| 临时文件与读取缓存 | 中间数据可能包含未加密的工作簿或单元格内容 | 防止不可信主体读取、修改或替换临时存储及其内容 | +| JVM 内存、转储和日志 | 可能包含敏感内容或密码 | 分别控制调试、转储、日志、备份和运行身份的访问权限 | +| URL 图片等网络功能 | 默认禁止远程获取，需显式配置精确主机白名单才能启用；请求由 JVM 进程发起 | 保持默认拒绝策略或限定目标，设置网络出口控制，不直接信任用户提供的 URL | +| 密码保护的 XLSX 输出 | 成功完成写入后，输出使用 Apache POI 的工作簿加密实现 | 保护密码、处理中的明文和失败产物，确认写入成功后再交付 | + +Apache Fesod (Incubating) 不保证对已能访问应用文件、临时存储或进程内存的主体隐藏相应数据。这些访问权限需要分别评估：能读取临时文件，并不意味着能读取 JVM 堆内存；反之亦然。 + +## 与 Apache POI 的关系 {#apache-poi} + +使用 Apache Fesod (Incubating) 中基于 POI 的功能时，必须同时考虑 Apache POI 的安全指导、支持的行为和实现限制。Apache Fesod (Incubating) 提供上层 API，不会消除 POI 对临时存储保护、进程内存保护和资源隔离的要求，也不会消除底层文档格式与加密支持的限制。请结合应用所使用的 POI 版本，同时阅读 [Apache POI 安全指导](https://poi.apache.org/security.html)和本安全模型。 + +Apache Fesod (Incubating) 的目标是遵循 POI 的安全模型、API 约定和保护性检查，不通过封装绕过其安全措施，也不承诺超出底层实现能力的安全属性。应用不应仅为接受被安全检查拒绝的文档而关闭或削弱 POI 的保护措施。确有必要调整配置时，应遵循 POI 的文档约定，评估安全影响，包括对同一 JVM 内其他代码的影响。 + +这一依赖关系不免除 Apache Fesod (Incubating) 对自身代码和集成行为的责任。Apache Fesod (Incubating) 引入的异常行为，或通过其 API 绕过安全控制的情况，仍应通过私密渠道报告并评估。POI 支持某项能力，也不代表所有 Apache Fesod (Incubating) API 都已暴露或启用该能力。 + +## 临时文件与缓存 {#temporary-files-and-caches} + +Apache Fesod (Incubating) 及其依赖可能在读取、流式写入、模板处理和加解密过程中使用临时文件或磁盘缓存。即使最终工作簿受到密码保护，中间数据也可能以明文形式存在。 + +部署方必须为 JVM 配置受保护的临时目录，并保护应用或依赖另行配置的缓存、暂存和输出位置。不可信主体不得读取、修改或替换这些目录及其内容。随机文件名和共享目录的 sticky bit 均不能替代访问控制。 + +在 POSIX 系统中，可在应用启动前，以服务运行身份创建独立的临时目录： + +```sh +umask 077 +FESOD_TMPDIR="$(mktemp -d "${TMPDIR:-/tmp}/fesod.XXXXXXXX")" || exit 1 +chmod 700 "$FESOD_TMPDIR" || exit 1 +java -Djava.io.tmpdir="$FESOD_TMPDIR" -jar app.jar +``` + +父目录必须防止不可信主体替换该私有目录。Windows 部署应使用等效 ACL 限制访问。此示例保护默认 JVM 临时位置，其他显式配置的目录仍需单独保护。目录权限不能隔离共享同一操作系统身份的不可信租户。 + +在 JVM 启动时设置 `java.io.tmpdir`。在库初始化后修改该属性，不能确保所有组件随之切换目录。容器部署应采用受保护的工作负载专用临时卷，避免不可信工作负载共享可访问的暂存空间。 + +关闭读写器并完成其资源释放流程。在正常释放资源时，库及其依赖会尝试清理当前操作管理的临时文件和缓存，在适用的路径中也会删除该操作专用的临时子目录，但不保证清理一定成功。 + +库不会全面清扫共享临时目录，也不会统一清理先前运行或其他进程留下的残留文件。异常、强制终止、主机故障或删除失败都可能留下中间文件。运行环境必须保护临时存储，并对不再被活跃任务使用的残留文件实施受控清理。普通删除不等于安全擦除，也不会自动清除快照或备份。 + +## 密码保护 {#password-protection} + +对 XLSX 设置非空密码并成功完成写入后，最终工作簿使用 Apache POI 的加密实现。这一能力保护最终文件的内容，不提供从输入、处理、暂存到交付的全生命周期加密，也不提供用户身份认证、业务授权或密码强度保证。 + +加密模式由库选定，调用方无法指定。当前版本使用 Apache POI 的 standard 加密模式，即 Office Open XML 标准定义的 AES-128 与基于 SHA-1 的密钥派生，而非允许 AES-256 的较新 agile 模式。该模式决定了密钥长度和密钥派生方式，也决定了成品文件抵御离线密码猜测的能力。请核实所部署版本实际使用的模式，不要默认其强度更高；如果威胁模型依赖更强加密，应重新评估。这一能力面向静态存储与传输过程中的访问控制，不能替代对"谁可以获取或留存该文件"的控制，也不适合作为高价值机密的长期存储手段。 + +加密流程可能先生成明文工作簿，再生成加密结果。直接写入文件路径时，该位置在处理期间也可能包含明文。应用必须保护输出位置，并在整个写入流程成功完成之前禁止下载或公开结果。 + +使用 `ExcelWriter` 分批写入时，单次 `write()` 返回不代表输出或加密已完成。所有写入操作以及最终的 `finish()` 或 `close()` 都必须成功完成后才能交付；使用 try-with-resources 时，应在整个语句正常退出后再交付，而不是在其代码块内交付。 + +写入或加密失败后，应将结果视为未完成，停止交付并按敏感数据处理。不要假设异常必然留下加密文件、空文件或已清理的文件。对需要控制交付时机的场景，可先在受保护的暂存位置生成结果，成功后再发布。 + +内存模式不应被视为所有 Apache Fesod (Incubating) 与依赖执行路径均不落盘的承诺。CSV 没有工作簿密码加密能力，旧版 XLS 的保护不能假定具有与 XLSX 加密相同的保密性。 + +密码应由受控配置或密钥管理机制提供，避免出现在源码、日志和异常输出中。密码保护不能替代文件系统权限、传输保护或敏感数据留存策略。 + +## 不可信文档与资源隔离 + +文档中的压缩数据、共享字符串、图片、样式和复杂结构可能导致较高的 CPU、内存或磁盘消耗。输入文件大小、扩展名及使用流式 API，均不足以保证处理成本有界。现有检查也不构成对所有恶意文档的完整防护。 + +OOXML 压缩包通过 Apache POI 读取，由 POI 对压缩条目施加自身的膨胀比限制。该限制能拒绝部分高压缩比输入，但它只是对膨胀倍数的启发式约束，不是可靠的隔离手段，不能替代进程级限制。 + +替换默认 XML 解析器工厂会改变读取时施加的解析器加固配置。库会对自身创建的解析器设置 DOCTYPE 与外部实体限制，但替换为不支持这些设置的工厂时，这些限制不会被强制执行。如果自行提供工厂，请确认等效防护已经生效。 + +处理外部文件时，应用应设置输入与输出大小、并发数、临时存储容量和业务处理量限制。对超时与内存耗尽需要可靠隔离的服务，建议在独立进程或容器中处理，并由外部监督程序限制运行时间、资源和网络访问。不要依赖线程中断作为终止所有解析工作的保证。 + +处理失败后，不应将部分导入结果或未完成导出视为业务成功。数据库事务、数据校验和任务重试策略由应用负责。 + +## 路径、网络与下游电子表格行为 + +不要把用户输入直接作为具有任意访问能力的本地路径。应用应限定允许的读写根目录，校验实际目标的授权，并考虑符号链接和并发替换带来的影响。Apache Fesod (Incubating) 不理解调用方提供的路径在业务上属于哪个用户或租户。 + +对 URL 图片等网络功能，默认禁止远程获取，必须显式配置精确主机白名单才能启用。请求从服务端发出；允许访问某个域名也不等于允许访问其可能重定向或解析到的任意网络位置。自定义转换器执行的网络操作同样需要受控。 + +URL 获取策略是进程级配置，不随工作簿或读取器隔离。JVM 内任何代码都可以修改它，修改后会作用于该进程中所有使用 Apache Fesod (Incubating) 的组件，包括原本认为已禁用获取的组件。应在应用启动阶段一次性设置，避免各业务模块在运行期相互覆盖；多个库共享同一 JVM 时，应确认实际生效的策略。 + +Apache Fesod (Incubating) 不提供通用的公式、超链接、外部引用或 CSV 数据净化策略。导出内容随后被电子表格软件打开时，可能触发该软件的解释或交互行为。应用应区分普通文本与有意写入的公式，按数据来源和目标客户端制定输出策略；CSV 引号转义本身不消除公式注入风险。 + +## 漏洞报告与安全加固 + +如果行为可能突破上述边界，或导致意外的数据泄露、文件访问、网络请求或代码执行，请先私下发送邮件至 [security@apache.org](mailto:security@apache.org)，注明 Apache Fesod (Incubating)，并提供版本、配置、攻击者已有权限、影响和最小复现。不要在公开 Issue、PR 或邮件列表中首先披露潜在漏洞的细节。 + +即使无法确定报告是否属于漏洞，也可以通过私密渠道提出。项目团队会结合实际行为、受影响版本和适用的安全期望来评估报告。依赖扫描结果应结合实际使用路径分析；涉及安全控制被绕过的报告，不能仅以部署方也负有责任为由排除。 + +以下情形通常不属于 Apache Fesod (Incubating) 自身的漏洞，因为边界在应用侧；但如果库本可以合理避免该结果，仍然值得报告： + +- 把不可信字符串直接作为本地路径传给库，根因是应用侧的路径穿越 +- 自行替换 XML 解析器工厂，或放宽 URL 获取策略，再依赖库恢复调用方已关闭的防护 +- 明文残留在应用配置的、未受保护的临时目录或输出目录中 +- 应用选择了弱密码，导致成品加密文件可被猜解 + +在受保护环境之外运行所带来的风险，通常需要通过部署配置解决。项目也欢迎降低误配置影响的加固建议，例如更严格的临时文件权限和更可靠的清理。是否构成漏洞、是否分配 CVE，以及是否采用某项加固，属于不同的评估事项。 + +## 支持的版本与披露流程 + +安全修复只在最新发布线上提供，旧发布线不做回溯修复；报告前请先升级到受维护的版本，以免报告已被修复的问题。项目遵循 [ASF 漏洞处理流程](https://www.apache.org/security/committers.html)：报告在私密渠道讨论，修复准备完成后与报告者协调披露时间；当项目与 ASF 安全团队判定确有必要时，会申请 CVE。 + +## 相关资料 + +- [Apache Fesod (Incubating) 安全报告与依赖说明](./security.md) +- [Apache POI 安全指导](https://poi.apache.org/security.html) +- [ASF 安全团队](https://www.apache.org/security/) diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security.md index 84111dc66..f76eff639 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/security.md @@ -22,6 +22,8 @@ title: '安全' Apache Software Foundation 在消除其软件项目中的安全问题方面采取了严格的立场。Apache Fesod (Incubating) 也十分关注与其特性和功能相关的安全问题。 +请参阅[安全模型](./security-model.md)，了解 Apache Fesod (Incubating) 的信任边界、密码保护范围，以及应用与部署方的责任。 + 如果您对 Apache Fesod (Incubating) 的安全性感到担忧，或者您发现了漏洞或潜在的威胁，请不要犹豫与 [Apache 安全团队](http://www.apache.org/security/) 联系，发送邮件至 `security@apache.org`。 在邮件中请指明项目名称为 Apache Fesod (Incubating)，并提供相关问题或潜在威胁的描述。同时推荐重现和复制安全问题的方法。在评估和分析调查结果后，Apache 安全团队和 Apache Fesod (Incubating) 社区将直接与您回复。 请注意 在提交安全邮件之前，请勿在公共领域披露安全电子邮件报告的安全问题。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md index d2dbd7013..28a3ad907 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md @@ -26,7 +26,7 @@ title: '密码保护' ## 概述 -Fesod 支持 Excel 内置的密码保护功能，适用于读取和写入操作。在构建器上使用 `.password("xxx")` 即可加密输出文件或解密输入文件。对于 `.xlsx` 文件，Fesod 使用 Apache POI 的加密实现（基于 AES），大文件加密时内存开销较高。对于旧版 `.xls` 文件，密码保护表现为写保护而非完整的内容加密，因此其行为和安全性与 `.xlsx` 有所不同。 +Apache Fesod (Incubating) 支持 Excel 内置的密码保护功能，适用于读取和写入操作。在构建器上使用 `.password("xxx")` 配置密码。对于 `.xlsx` 输出，设置非空密码并成功完成写入后，Apache Fesod (Incubating) 使用 Apache POI 的加密实现（基于 AES），大文件加密时内存开销较高。旧版 `.xls` 的保护行为与 `.xlsx` 加密不同，不应假定其具有相同的保密性。 ## 带密码写入 @@ -67,6 +67,10 @@ public void passwordRead() { ## 安全说明 -- Excel 密码保护会加密文件内容，没有密码将无法读取。 +- XLSX 密码保护适用于成功完成的输出，不代表处理期间的临时文件、缓存或 JVM 内存也已加密。 +- 保护临时目录和输出目录，禁止不可信主体访问。文件输出在处理期间可能包含明文，必须在整个写入流程成功后再交付。 +- 写入或加密失败后的结果应按未完成的敏感数据处理，不得交付。 - 如果密码不正确，读取时会抛出 `EncryptedDocumentException` 异常。 - 在生产环境中，请避免硬编码密码 — 建议使用配置文件或密钥管理服务。 + +请参阅[安全模型](/community/security-model#password-protection)，了解加密边界、[临时文件保护要求](/community/security-model#temporary-files-and-caches)，以及 [Apache POI 的作用与限制](/community/security-model#apache-poi)。 diff --git a/website/sidebarsCommunity.js b/website/sidebarsCommunity.js index 30755bc5c..2d413002e 100644 --- a/website/sidebarsCommunity.js +++ b/website/sidebarsCommunity.js @@ -80,6 +80,10 @@ const sidebarsCommunity = { id: "security", type: "doc", }, + { + id: "security-model", + type: "doc", + }, ] }; export default sidebarsCommunity;