Stirling-PDF安全加固指南：防止CSRF与XSS攻击的配置方法
项目地址: https://gitcode.com/gh_mirrors/st/Stirling-PDF 安全风险概述
Web应用程序面临的两大主要安全威胁是跨站请求伪造（CSRF）和跨站脚本攻击（XSS）。Stirling-PDF作为本地部署的PDF处理工具，虽然数据不经过公共网络传输，但仍需防范来自内部网络的潜在攻击。本文将详细介绍如何通过配置增强Stirling-PDF的安全性，抵御这两类常见攻击。
CSRF防护配置
CSRF防护原理
跨站请求伪造（CSRF）攻击利用用户已认证的身份执行非预期操作。Stirling-PDF通过Spring Security实现CSRF防护，核心机制是验证请求中的CSRF令牌与服务器端存储的令牌是否匹配。
启用CSRF保护
Stirling-PDF的CSRF保护默认启用，相关配置位于app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java文件中：
if (!securityProperties.getCsrfDisabled()) {
CookieCsrfTokenRepository cookieRepo = CookieCsrfTokenRepository.withHttpOnlyFalse();
CsrfTokenRequestAttributeHandler requestHandler = new CsrfTokenRequestAttributeHandler();
requestHandler.setCsrfRequestAttributeName(null);
http.csrf(
csrf -> csrf.ignoringRequestMatchers(
request -> {
String apiKey = request.getHeader("X-API-KEY");
// API密钥验证逻辑
})
.csrfTokenRepository(cookieRepo)
.csrfTokenRequestHandler(requestHandler)
);
}
配置说明
-
CSRF令牌存储：使用
CookieCsrfTokenRepository将CSRF令牌存储在Cookie中，withHttpOnlyFalse()确保JavaScript可以访问令牌以包含在请求中 -
API密钥例外：对包含有效
X-API-KEY请求头的请求跳过CSRF验证，适用于API调用场景 -
令牌传递：前端需从Cookie中获取CSRF令牌，并在非GET请求中通过
X-CSRF-TOKEN请求头或表单字段传递
禁用CSRF的风险
不建议禁用CSRF保护，但在特定场景下（如纯API服务）可通过设置禁用：
if (securityProperties.getCsrfDisabled() || !loginEnabledValue) {
http.csrf(CsrfConfigurer::disable);
}
此配置位于app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/SecurityConfiguration.java，禁用前请确保已通过其他机制（如API密钥）确保请求合法性。
XSS防护实现
XSS防护策略
跨站脚本攻击（XSS）允许攻击者在受害者浏览器中注入恶意脚本。Stirling-PDF采用多重防御策略防范XSS攻击：输入验证、输出编码和内容安全策略。
输入验证与输出编码
Stirling-PDF使用自定义HTML清理器对用户输入进行验证和净化，相关实现位于app/common/src/main/java/stirling/software/common/util/CustomHtmlSanitizer.java：
public class CustomHtmlSanitizer {
private static final PolicyFactory POLICY = new HtmlPolicyBuilder()
.allowElements("b", "i", "u", "a")
.allowAttributes("href").onElements("a")
.allowStandardUrlProtocols()
.requireRelNofollowOnLinks()
.build();
public static String sanitize(String html) {
if (html == null) {
return null;
}
return POLICY.sanitize(html);
}
}
内容安全策略配置
内容安全策略（CSP）是防御XSS的重要手段，Stirling-PDF通过WebMvc配置实现CSP头：
app/core/src/main/java/stirling/software/SPDF/config/WebMvcConfig.java文件中的资源处理器配置：
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**")
.addResourceLocations("file:" + InstallationPathConfig.getStaticPath(), "classpath:/static/");
}
安全的资源加载策略
Stirling-PDF仅从以下受信任来源加载资源：
- 应用安装目录下的静态资源
- 应用程序类路径中的内置资源
这种限制有效防止了恶意脚本的加载，降低了XSS攻击风险。
安全配置验证
验证CSRF保护
- 访问Stirling-PDF登录页面
- 使用浏览器开发者工具查看Cookie，确认存在
XSRF-TOKEN - 提交表单时检查请求头，确认包含
X-CSRF-TOKEN
验证XSS防护
- 在PDF元数据等用户输入字段中尝试输入：
<script>alert('XSS')</script> - 保存后查看渲染结果，确认恶意脚本已被过滤为：
<script>alert('XSS')</script>
登录安全增强
除了CSRF和XSS防护外，Stirling-PDF还提供了登录安全增强功能，可在安全配置文件中进一步强化：
http.rememberMe(
rememberMeConfigurer -> rememberMeConfigurer
.tokenRepository(persistentTokenRepository())
.tokenValiditySeconds(14 * 24 * 60 * 60)
.useSecureCookie(true)
);
此配置启用了安全的"记住我"功能，使用持久化令牌存储和安全Cookie，防止会话劫持风险。
安全加固最佳实践
定期更新
保持Stirling-PDF最新版本，安全相关修复会在README.md中说明。
服务器强化
- 配置HTTPS，即使在本地网络环境
- 限制服务器访问权限，仅允许授权IP访问
- 定期审计服务器日志，检查异常访问模式
安全配置检查清单
- CSRF保护已启用（默认启用）
- XSS过滤功能正常工作
- 安全Cookie属性已设置（Secure、HttpOnly）
- API访问使用密钥认证
- 定期更新应用版本
总结
通过正确配置CSRF防护和XSS过滤，Stirling-PDF能够有效抵御常见的Web安全威胁。安全是一个持续过程，建议定期查看项目的安全文档和更新日志，保持安全配置与时俱进。如有安全问题发现，可通过项目的SECURITY.md中说明的渠道进行报告。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
