适用于 Java 8+ 的上下文输出编码。针对接收不可信文本的解析器上下文选择相应的编码器:HTML、JavaScript、CSS、XML 或 URL 组件。核心模块没有运行时依赖;可选的 JSP 和 Jakarta 适配器提供视图层绑定。编码是 XSS 防护 的一部分,此外还需配合安全模板、URL 校验及其他应用控制措施。
1.6.0 已可从 Maven Central 获取。 此次要版本减少了不必要的 JavaScript 字母转义,同时在可信片段中保留了已识别的 HTML 标记保护。编码后的字节和流式行为有所变化;请参阅发布说明和发布验证。
1.5.0 中引入的解析器边界安全修复仍然有效;截至 1.4.1 的版本不包含这些修复。请参阅安全公告和 VERIFYING.md。
选择你需要的依赖项。
三个受支持的构件均使用 group ID org.owasp.encoder:
| 构件 ID | 用途及运行时依赖 |
|---|---|
encoder | 核心 String/Writer API;无运行时依赖 |
encoder-jsp | 旧版 javax JSP 标签/EL 函数;核心模块加容器提供的 JSP API |
encoder-jakarta-jsp | Jakarta JSP 标签/EL 函数;核心模块加容器提供的 Jakarta JSP API |
<dependency>
<groupId>org.owasp.encoder</groupId>
<artifactId>encoder</artifactId>
<version>1.6.0</version>
</dependency>
需要时,将 encoder 替换为某个标签适配器构件 ID;每个适配器都会引入 core。请保持单独管理的 core/适配器版本一致。使用 javax 或 Jakarta taglib JAR 中的一个:它们共享 org.owasp.encoder.tag,不得在同一 classpath 或 module path 上共存。参见运行时矩阵和依赖/许可证清单。
encoder-esapi 在 1.4.1 之后已退役,1.5.x 或 1.6.0 中不包含也不支持它。使用它的应用程序必须从该适配器迁移出去。
已发布的 1.6.0 API 文档(托管索引可能滞后于发布):core、 javax JSP 和 Jakarta JSP。
import org.owasp.encoder.Encode;
out.write("<p>");
Encode.forHtmlContent(out, userText); // Writer overload; no intermediate String
out.write("</p>");
等价的 String 调用是 Encode.forHtmlContent(userText)。调用方提供可信的周边语法和属性引号。在输出边界处对原始数据编码一次;考虑你的模板引擎已经执行的任何转义。
| 目标 | API 与限制 |
|---|---|
| HTML 文本,包括 textarea 内容 | forHtmlContent;forHtml 也覆盖带引号的普通文本属性 |
| 带引号的 HTML 文本属性 | forHtmlAttribute;不是事件处理程序表达式或 URL 验证器 |
| 一个原始 URL 组件 | forUriComponent;用可信分隔符组装,验证 URL,然后为外层 HTML 属性编码 |
| JavaScript 字符串 | forJavaScript;提供单/双引号。普通无标签模板字面量文本需要 1.5。切勿用于带标签模板、表达式体、JSON 或脚本 URL |
| JSON 字符串内容 | forJson(1.5);提供双引号。完整文档优先使用序列化器 |
带引号的 CSS 字符串 / CSS url(...) 值 | forCssString / forCssUrl;验证 URL 并遵守该方法的周边上下文规则 |
| XML 1.0 文本 / 带引号属性 | forXmlContent / forXmlAttribute;forXml 覆盖两者 |
| XML 1.1 文本 / 带引号属性 | forXml11Content / forXml11Attribute(核心 1.4+);需要 XML 1.1 文档/解析器,而非 HTML |
| XML CDATA / 注释 | forCDATA / forXmlComment;不是 HTML 注释 |
| Java 源代码字符串字面量 | forJava;调用方提供引号;未配对的代理项可能无法编译 |
列出的每个 facade 方法都有 String 和 Writer 重载。 上下文指南 解释了嵌套、null/Unicode 行为、 JavaScript 变体、模板边界、JSON 和不安全上下文。 Java/JSP 示例 展示了完整的周边语法。
编码不会净化 HTML、验证输入/URL、序列化 JSON 文档、 执行 SQL 参数化,或解码/规范化数据。当必须允许标记时,使用 HTML 净化器; 对 SQL 使用参数化查询。有关这些不同角色,请参阅 OWASP Java 安全库指南。
Taglib URI 是标识符,不是必须在浏览器中打开的 URL:
| 适配器 | 基本标识符 | 高级标识符 |
|---|---|---|
| Jakarta | owasp.encoder.jakarta | owasp.encoder.jakarta.advanced |
| javax JSP | https://www.owasp.org/index.php/OWASP_Java_Encoder_Project | 相同标识符后附加 #advanced |
<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="e" uri="owasp.encoder.jakarta" %>
<p>${e:forHtmlContent(param.message)}</p>
对于 javax 容器,请使用 javax 标识符。标签使用空主体和必需的 value 属性,例如 <e:forHtmlContent value="${param.message}" />。有关基础与高级方法以及版本敏感的部署设置,请参阅绑定与 EL 求值。在 1.5 中,高级 taglib 暴露除 forJava 之外的每个 Encode.forX(String) 上下文;Java 源代码生成不是 JSP 上下文。XML 1.1 绑定是 1.5 中的新增功能。
Encode.forUri 在已发布的 API 中已弃用。版本 1.5.0 将该弃用扩展到 Encoders.URI、两个 ForUriTag 类以及 forUri 标签/函数文档。所有这些入口点在 1.x 中均保留。对整个 URI 进行编码并不会验证它:
forUri("javascript:alert(1)") 会原样返回。现有的 % 符号会被再次编码。对于单个原始参数名/值、路径段或片段,请使用 forUriComponent;单独验证完整 URL,然后在将其放入带引号的 HTML 属性时使用 forHtmlAttribute。仅使用 java.net.URI 进行解析并不能确立安全性。请参阅完整 URL 示例。
移除已弃用的 core/tag API 需要经过单独审查的未来主版本决策;弃用并非移除时间表。单独的历史 ESAPI 适配器已退役,而不会带入 1.5.0。
请使用已发布的模块名称和 OSGi 范围以及可运行的 JPMS 示例。显式多版本模块名称有意与历史自动名称不同。不要重命名用于自动模块的依赖 JAR。CI 在 Java 8/11/17/21/25、classpath、JPMS 和 Felix R6/R8 上测试原始打包 JAR;这并不证明每个容器或下游依赖组合均可用。
使用 JDK 17 和已提交的 wrapper(Maven 3.10.1)进行构建;在 Windows 上使用 mvnw.cmd:
./mvnw clean verify
./mvnw clean verify -PtestJakarta # optional locally; requires Docker
常规验证包含无需 Docker 的 JSP 引擎。浏览器/WAR 测试套件在 CI 中仍为必需。有关风格/覆盖率策略,请参阅 BUILDING.md;有关审查和诊断命令,请参阅 CONTRIBUTING.md;有关独立的发布门禁,请参阅 RELEASING.md。不存在基准测试或 Maven Site 发布配置。
受支持的 1.x 构件保留 Java 8 库 API/字节码及其已发布的 API/模块标识和依赖范围。精确的编码输出同样是可观察行为:添加转义并不自动具备补丁兼容性。变更需要上下文/解析器测试、输出变更说明,并在需要时提供迁移指导。安全修复可以在补丁中纠正不安全行为,并附有明确的公告;其他兼容性破坏需要未来主版本决策,而不仅仅是版本标签。有关保留的 1.x 契约及未来提案的处理方式,请参阅兼容性与范围决策。
负责人:Jim Manico 和 Jeremy Long;原作者:Jeff Ichnowski。 请参阅 MAINTAINERS.md 和 OWASP 项目页面。 独立的 OWASP 网站可能滞后于本仓库的发布状态。
请通过 SECURITY.md 私下报告疑似漏洞。 使用 KEYS 和 VERIFYING.md 验证下载。 本项目使用 BSD 3-Clause 许可证 和 OWASP 行为准则。资助 链接区分维护者支持与 OWASP 基金会捐赠。