Apache Zeppelin HTTP 安全响应头配置指南：HSTS、XSS 防护、Clickjacking 防护与服务器指纹隐藏

• 后端
• 前端
• 大数据
• 数据分析

【免费下载链接】zeppelin

Web-based notebook that enables>项目地址：https://gitcode.com/gh_mirrors/zeppelin2/zeppelin

点击查看免费下载

Apache Zeppelin 作为基于 Web 的交互式数据分析笔记本，其内置的 Jetty 服务器默认会输出若干可能暴露服务器信息或弱化浏览器端安全防护的 HTTP 响应头。本文基于官方安全配置文档，完整讲解如何通过zeppelin-site.xml配置HSTS（HTTP Strict Transport Security）、X-XSS-Protection、X-Frame-Options三类安全响应头，以及如何通过硬编码 Server 头隐藏 Jetty 应用服务器版本信息；同时结合当前仓库的源码实现，说明每条配置的底层生效路径（配置解析、Filter 注入、Jetty 版本覆盖），帮助你在部署 Zeppelin 时按需开启对应的安全加固措施。读完本文，你将能够独立完成 Zeppelin 安全响应头的配置、验证与排障。

一、为什么需要配置 HTTP 安全响应头

Apache Zeppelin 的 Web 界面承担了笔记本编辑、解释器管理、作业监控等功能，浏览器与 Zeppelin Server 之间持续进行着大量 HTTP/WebSocket 交互。如果响应头中缺少浏览器安全防护指令，Zeppelin 网页内容就可能暴露于以下几类风险之下：

• 跨站脚本（XSS）：攻击者注入恶意脚本，浏览器若未启用过滤与拦截机制，页面可能直接执行恶意代码；
• 跨框架脚本（XFS / Clickjacking）：恶意站点通过<frame>、<iframe>或<object>将 Zeppelin 页面嵌入自身页面，诱导用户在不知情的情况下操作笔记本；
• 中间人攻击（MITM）：在 HTTP 明文传输下，攻击者可篡改响应内容；
• 服务器指纹识别（Fingerprinting）：响应头中的Server字段会暴露 Jetty 的精确版本号，攻击者可据此判断当前服务器是否受已知 CVE 影响，从而定向发起攻击。

Apache Zeppelin 为此提供了一组配置项，用于向响应中注入对应的安全头，并支持自定义Server头内容。这些配置统一写在conf/zeppelin-site.xml.template（模板文件）对应的属性中，配置解析与默认值定义在 ZeppelinConfiguration.java（第 771–775 行的ConfVars枚举），响应头的实际写入发生在 CorsFilter.java 的addCorsHeaders方法中。

配置文件位置与启用方式

所有示例均以conf/zeppelin-site.xml为目标（首次部署时由conf/zeppelin-site.xml.template复制得到，相关安装说明见 docs/setup/basics/how_to_build.md 与 docs/setup/deployment/docker.md）。模板中的安全相关属性默认处于注释状态，启用时取消注释并按需修改<value>即可。修改配置后需要重启 Zeppelin Server 才能生效。

二、配置 HSTS（HTTP Strict Transport Security）响应头

配置示例

在zeppelin-site.xml中添加或取消注释以下属性即可启用 HSTS：

<property> <name>zeppelin.server.strict.transport</name> <value>max-age=631138519</value> <description>The HTTP Strict-Transport-Security response header is a security feature that lets a web site tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. Enable this when Zeppelin is running on HTTPS. Value is in Seconds, the default value is equivalent to 20 years.</description> </property>

支持的值

<value>可选用以下三种形式之一：

• max-age=<expire-time>：仅指定有效期。浏览器在此时间段内强制使用 HTTPS 访问该域名；
• max-age=<expire-time>; includeSubDomains：有效期之外，同时将该策略应用到目标域名的所有子域；
• max-age=<expire-time>; preload：声明域名已提交 HSTS preload 列表，便于浏览器在首次访问前即应用该策略。

其中<expire-time>的单位为秒。默认值631138519约等于 20 年，属长期有效的保守选择；实际部署时可根据安全策略调低。

生效条件与底层实现

HSTS 头只有在Zeppelin Server 以 SSL/HTTPS 方式运行时才有意义。从源码可以看到，CorsFilter.java 在addCorsHeaders中做了条件判断：

ZeppelinConfiguration zeppelinConfiguration = ZeppelinConfiguration.create(); response.setHeader("X-FRAME-OPTIONS", zeppelinConfiguration.getXFrameOptions()); if (zeppelinConfiguration.useSsl()) { response.setHeader("Strict-Transport-Security", zeppelinConfiguration.getStrictTransport()); } response.setHeader("X-XSS-Protection", zeppelinConfiguration.getXxssProtection());

也就是说，Strict-Transport-Security仅当useSsl()返回true（即配置了zeppelin.server.ssl.enabled等相关 SSL 属性，见 ZeppelinConfiguration.java）时才会被写入响应。SSL 的具体配置方法参见 docs/setup/operation/configuration.md。

启用 HSTS 后，即使页面内包含通过 HTTP 加载的资源或 HTTP 链接，浏览器也会自动将其重定向到 HTTPS（针对目标域名）。此外，当攻击者向用户出示伪造的无效 SSL 证书时，HSTS 会阻止用户绕过证书错误提示继续访问，从而有效抵御中间人攻击。

为什么先启用 SSL 再启用 HSTS

HSTS 策略一旦被浏览器记录，在max-age内该域名将只接受 HTTPS 连接。因此必须确保 Zeppelin 的 SSL 配置（证书、端口zeppelin.server.ssl.port等）完全正确后再启用 HSTS，否则可能出现浏览器因策略缓存而无法访问 HTTP 回退端口的情况。

三、配置 X-XSS-Protection 响应头

配置示例

<property> <name>zeppelin.server.xxss.protection</name> <value>1; mode=block</value> <description>The HTTP X-XSS-Protection response header is a feature of Internet Explorer, Chrome and Safari that stops pages from loading when they detect reflected cross-site scripting (XSS) attacks. When value is set to 1 and a cross-site scripting attack is detected, the browser will sanitize the page (remove the unsafe parts).</description> </property>

支持的值

该头是 Internet Explorer、Chrome 和 Safari 浏览器提供的反射型 XSS 检测功能，可取以下值：

• 0：禁用 XSS 过滤；
• 1：启用 XSS 过滤。检测到跨站脚本攻击时，浏览器会清理页面（移除不安全部分）；
• 1; mode=block：启用 XSS 过滤。检测到攻击时，浏览器将阻止整个页面的渲染。

底层实现

该头在 CorsFilter.java 中通过response.setHeader("X-XSS-Protection", zeppelinConfiguration.getXxssProtection())无条件写入（不依赖 SSL 开关），对应配置枚举ZEPPELIN_SERVER_X_XSS_PROTECTION("zeppelin.server.xxss.protection", "1")，即仓库默认值为1。需要说明的是，X-XSS-Protection是较早期的浏览器防御机制，现代浏览器（尤其 Chrome）已逐渐以 CSP 等更完善的机制替代它，建议将其视为纵深防御的一环，而非唯一防线。

四、配置 X-Frame-Options 响应头（防 Clickjacking）

配置示例

<property> <name>zeppelin.server.xframe.options</name> <value>SAMEORIGIN</value> <description>The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a frame/iframe/object.</description> </property>

支持的值

X-Frame-Options用于告知浏览器是否允许页面被其他站点以<frame>、<iframe>或<object>嵌入，从而防止点击劫持（Clickjacking）攻击。可取以下值：

• DENY：页面不能被任何站点嵌入；
• SAMEORIGIN：仅允许同源页面嵌入（Zeppelin 默认值，即仅允许 Zeppelin 自身域名嵌入）；
• ALLOW-FROM uri：允许指定uri来源的页面嵌入（注意该值兼容性有限，部分现代浏览器已不支持）。

底层实现与默认值

从 CorsFilter.java 可以看到，X-FRAME-OPTIONS头同样无条件写入响应（response.setHeader("X-FRAME-OPTIONS", zeppelinConfiguration.getXFrameOptions())），配置枚举默认值为SAMEORIGIN（见 ZeppelinConfiguration.java）。也就是说，即便不显式配置，Zeppelin 也会默认输出X-Frame-Options: SAMEORIGIN，这是保护笔记本页面不被第三方站点嵌套的基础防线。

五、配置 Server 头（隐藏应用服务器版本）

配置示例

<property> <name>zeppelin.server.jetty.name</name> <value>Jetty(7.6.0.v20120127)</value> <description>Hardcoding Application Server name to Prevent Fingerprinting</description> </property>

作用与取值规则

出于安全考虑，很多组织不希望对外暴露应用服务器的名称与精确版本号：攻击者可通过版本号快速判断当前 Jetty 是否未修补某些公开 CVE，从而降低攻击成本。该属性允许你将Server响应头硬编码为任意字符串（<value>可以是任意String），例如设置为一个不含版本号的通用名称，或伪装成其他服务器标识，达到混淆指纹的目的。

底层实现

该属性并不通过CorsFilter写入，而是在 Jetty 层面直接覆盖版本信息。在 ZeppelinServer.java 中，Jetty 服务器启动后会执行：

jettyWebServer.start(); //Instantiates ZeppelinServer if (conf.getJettyName() != null) { org.eclipse.jetty.http.HttpGenerator.setJettyVersion(conf.getJettyName()); }

即：当zeppelin.server.jetty.name配置了非空值时，调用HttpGenerator.setJettyVersion(...)将 Jetty 内置的版本字符串整体替换为自定义值；该配置的默认值为null（见 ZeppelinConfiguration.java 中ZEPPELIN_SERVER_JETTY_NAME("zeppelin.server.jetty.name", null)），因此默认情况下 Jetty 会输出真实的服务器版本，需要加固时务必显式配置此项。

补充：请求头大小限制

与安全响应头同属 Jetty 加固范畴的还有zeppelin.server.jetty.request.header.size（默认8192），用于限制 HTTP 请求头大小以防止 HTTP 413 错误，可在同一配置文件（conf/zeppelin-site.xml.template 第 472–478 行）中按需调整，其取值通过 ZeppelinConfiguration.java 的getJettyRequestHeaderSize()读取。

六、安全响应头的写入位置与验证方法

写入链路小结

综合源码可以确认以下生效链路：

1. 配置解析：zeppelin-server与zeppelin-interpreter共享的 ZeppelinConfiguration.java 通过ConfVars枚举读取zeppelin-site.xml中四个安全属性（第 771–775 行），并提供getJettyName()、getXFrameOptions()、getXxssProtection()、getStrictTransport()四个 getter（第 553–572 行）；
2. 响应注入：作为 Servlet Filter 的 CorsFilter.java 在每个 HTTP 响应经过时调用addCorsHeaders()，写入X-FRAME-OPTIONS、Strict-Transport-Security（仅 SSL 模式下）与X-XSS-Protection三个头，同时处理 CORS 相关的Access-Control-*头；
3. 版本覆盖：Jetty 启动后由 ZeppelinServer.java 调用HttpGenerator.setJettyVersion()替换Server头中的版本字符串。

对应的单元测试 CorsFilterTest.java 使用 Mockito 模拟HttpServletResponse验证了 Filter 的头部写入行为，可用于理解setHeader的调用时机。

验证方法

配置并重启 Zeppelin 后，可以用以下任一方式确认响应头已生效：

• 浏览器开发者工具：打开 Zeppelin 页面，在 Network 面板查看主页响应头中是否包含Strict-Transport-Security、X-XSS-Protection、X-Frame-Options；
• curl 命令：

curl -I https://<zeppelin-host>:<ssl-port>/

重点检查输出的响应头中是否出现：

Strict-Transport-Security: max-age=631138519 X-XSS-Protection: 1; mode=block X-Frame-Options: SAMEORIGIN Server: Jetty(7.6.0.v20120127)

注意事项

• HSTS 头仅在 SSL 模式（useSsl()为真）下输出，若 Zeppelin 以纯 HTTP 运行，该头不会出现，这属于预期行为；
• 浏览器缓存了 HSTS 策略后，max-age到期前难以撤销，测试时建议使用短max-age（如max-age=60）并配合清空浏览器站点数据；
• Server头的自定义值仅影响 Jetty 输出的Server头字符串，不会改变 Zeppelin 其他接口返回体中的版本信息（如 REST API 返回的版本号），如需全面隐藏版本信息应同时考虑这些出口。

七、完整配置示例

以下是一个面向 HTTPS 部署的安全加固完整片段，可直接合并到conf/zeppelin-site.xml：

<!-- 启用 HSTS，有效期 20 年（需先配置 SSL） --> <property> <name>zeppelin.server.strict.transport</name> <value>max-age=631138519; includeSubDomains</value> <description>HTTP Strict-Transport-Security for Zeppelin over HTTPS</description> </property> <!-- 启用 XSS 过滤并阻止页面渲染 --> <property> <name>zeppelin.server.xxss.protection</name> <value>1; mode=block</value> <description>X-XSS-Protection response header</description> </property> <!-- 禁止第三方站点嵌入 Zeppelin 页面 --> <property> <name>zeppelin.server.xframe.options</name> <value>SAMEORIGIN</value> <description>X-Frame-Options response header</description> </property> <!-- 隐藏 Jetty 真实版本，防止指纹识别 --> <property> <name>zeppelin.server.jetty.name</name> <value>Jetty(7.6.0.v20120127)</value> <description>Hardcoding Application Server name to Prevent Fingerprinting</description> </property>

修改完成后重启 Zeppelin Server，并按上一节方法验证。若需要在同一 Zeppelin 实例上同时加固认证与授权，可进一步参考 docs/setup/security/shiro_authentication.md（Shiro 认证）、docs/setup/security/notebook_authorization.md（笔记本授权）与 docs/setup/security/datasource_authorization.md（数据源授权），与本篇的响应头加固配合构成完整的 Web 安全体系。

赞分享

• 后端
• 前端
• 大数据
• 数据分析

【免费下载链接】zeppelin

Web-based notebook that enables>项目地址：https://gitcode.com/gh_mirrors/zeppelin2/zeppelin

点击查看免费下载