OWASP/www-project-csrfguard

# [OWASP CSRFGuard 4.x](https://owasp.org/www-project-csrfguard) [](https://www.opensource.org/licenses/bsd-license.php) [](https://github.com/OWASP/www-project-csrfguard/releases) [](https://search.maven.org/search?q=g:org.owasp%20AND%20a:csrfguard) [](https://owasp.org/projects#div-flagships) [](https://github.com/OWASP/www-project-csrfguard/actions/workflows/ci.yaml) [](https://github.com/OWASP/www-project-csrfguard/actions/workflows/dependency_check.yaml) [](https://github.com/OWASP/www-project-csrfguard/actions/workflows/snyk.yaml) ## 概述 欢迎来到 OWASP CSRFGuard 项目的官方主页！OWASP CSRFGuard 是一个库，通过实现同步器令牌模式的变体来缓解跨站请求伪造 (CSRF) 攻击的风险。 OWASP CSRFGuard 库通过 JavaEE Filter 进行集成，并提供了各种自动和手动的方式将每次会话或伪每次请求的令牌集成到 HTML 中。当用户与此 HTML 交互时，CSRF 防御令牌（即加密安全的随机同步器令牌）将随相应的 HTTP 请求一起提交。OWASP CSRFGuard 的职责是确保令牌存在且对当前 HTTP 请求有效。任何试图在没有正确相应令牌的情况下向受保护资源提交请求的行为都会被视为正在进行的 CSRF 攻击并被丢弃。在丢弃请求之前，CSRFGuard 可配置为执行一项或多项操作，例如记录请求的相关方面并将用户重定向到着陆页。最新版本增强了此策略，以支持对使用 Ajax 提交的 HTTP 请求进行可选验证，以及对 referrer 头进行可选验证。 ## 项目负责人 CSRFGuard 项目由 [Azzeddine RAMRAMI](mailto:azzeddine.ramrami@owasp.org) 和 [Istvan ALBERT-TOTH](mailto:istvan.alberttoth@owasp.org) 运营。 ## 使用 Maven 将以下依赖项添加到您的 Maven POM 文件中以使用该库： **注意**：对于 [Jakarta](https://github.com/OWASP/www-project-csrfguard/tree/jakarta) 版本，请在 `version` 中使用 `-jakarta` 后缀。 ``` org.owasp csrfguard 4.4.0 org.owasp csrfguard-extension-session 4.4.0 org.owasp csrfguard-jsp-tags 4.4.0 ``` ## JavaScript 配置参数 CSRFGuard 公开了几个与 JavaScript 相关的配置参数，用于控制 JavaScript servlet 的行为。这些参数可以在 CSRFGuard 属性文件中配置，也可以使用 `web.xml` 上下文参数进行覆盖。 下表列出了可用的配置选项、其用途和默认值。 ### 基于字符串的参数 | 属性名称 | 描述 | 默认值 | |--------------|------------|---------------| | `cache-control` | 生成的 JavaScript 响应的 Cache-Control 头值。 | `private, max-age=28800` | | `cache-control-tagged` | 使用带标签的 JavaScript 响应时的 Cache-Control 头值。 | `private, max-age=600` | | `referer-pattern` | 用于验证 HTTP referer 头的正则表达式。 | `.*` | | `unprotected-extensions` | 不应受 CSRFGuard 保护的文件扩展名。 | 空 | | `source-file` | CSRFGuard 的自定义 JavaScript 源文件位置。 | `null` | | `x-requested-with` | 用于 `X-Requested-With` HTTP 头的值。 | `OWASP CSRFGuard Project` | | `dynamic-node-creation-event` | 用于检测动态创建的 DOM 节点的事件名称。 | `null` | ### 基于布尔值的参数 | 属性名称 | 描述 | 默认值 | |--------------|------------|---------------| | `domain-strict` | 在 referer 验证期间强制执行严格的域名匹配。 | `true` | | `inject-into-attributes` | 启用将 CSRF token 注入到 HTML 属性中。 | `true` | | `inject-get-forms` | 启用 HTTP GET 表单的 token 注入。 | `true` | | `inject-form-attributes` | 启用将 token 注入到表单属性中。 | `true` | | `inject-into-forms` | 启用将 CSRF token 注入到 HTML 表单中。 | `true` | | `inject-into-dynamic` | 启用注入到动态创建的 DOM 节点中。 | `false` | | `referer-match-protocol` | 在 referer 验证期间要求协议匹配。 | `true` | | `referer-match-domain` | 在 referer 验证期间要求域名匹配。 | `true` | ### 使用 `web.xml` 覆盖值 可以通过在 `web.xml` 中定义相应的上下文参数来覆盖这些配置选项。 示例： ``` org.owasp.csrfguard.JavascriptServlet.cacheControl no-store ------------------------------------------------------------------------------- ## 构建代码 1. Make sure you have [Apache Maven](https://maven.apache.org/) 3.6.3+, JDK 1.8+ and respectively JDK 11+ for Jakarta installed 2. Clone this repository locally 3. Build the project by running ```mvn clean install``` in the project root directory 4. Build and run the test JSP web application by running one of the following commands: ```shell mvn pre-integration-test -Pdeploy-jsp-webapp -pl csrfguard-test/csrfguard-test-jsp ``` ``` mvn -Pdeploy-jsp-webapp -pl csrfguard-test/csrfguard-test-jsp tomcat7:run ``` 6. 可选：您可以使用 ```mvnDebug``` 启用远程调试，然后将您的 IDE 连接到它（默认端口为 8000） 7. 使用 Web 浏览器访问 ```http://localhost:8080``` 以打开测试项目的主页 ## 上传到 Maven Central 仓库（针对项目负责人） 1. 按照 [Sonatype Open-Source Project Maven Repository Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) 创建一个 Sonatype 用户账户； 2. 接下来，[open a support request](https://issues.sonatype.org/browse/OSSRH) 以将您新创建的用户名添加到 Maven groupId ```org.owasp``` 下； 3. 该工单必须由 CSRFGuard 项目负责人或已经有权在该 group 和 artifactId 下部署的人员批准。 4. 支持请求完成后，请按照上面提到的 Sonatype Maven 仓库使用指南中的说明将新版本上传到 Maven Central 仓库。 ### GPG 密钥生成和分发 参见：https://central.sonatype.org/publish/requirements/gpg/ ``` gpg --full-gen-key gpg --list-keys gpg --list-secret-keys # if you've migrated your keys from another machine, make sure you have your secret key(s) imported gpg --keyserver keys.gnupg.net --send-key # you can define other supported key servers as well ``` ### 发布所需的 `.m2/settings.xml` 代码片段示例： ``` ossrh ossrh true ``` 手动测试签名您的构件： ``` mvn clean verify -Psign-artifacts -Dgpg.passphrase= # should generate .asc files in the target directory ``` ### 部署到 OSS Sonatype / Maven Central #### 部署 `-SNAPSHOT` 版本： ``` mvn clean deploy ``` #### 准备发布： ``` mvn release:clean release:prepare ``` 1. 以 <_MAJOR.MINOR.PATCH_> 格式设置您想要发布的版本号（例如 `4.0.0`） 2. 设置 SCM 发布标签：（例如 `4.0.0`） 3. 设置新的开发版本（例如 `4.0.1-SNAPSHOT`） 检查创建的提交和标签，确保一切看起来符合预期： ``` git log git show HEAD git show HEAD^ git tag -l # list tags ``` #### 回滚本地发布： ``` mvn release:rollback # or "git reset HEAD^^ --hard" git tag -d ``` #### 将发布版本上传到 OSS Sonatype（暂存）： ``` mvn release:perform ``` `maven-release-plugin` 执行 `deploy`（默认）。这会触发 `nexus-staging-maven-plugin` 的执行，该插件将构件上传到 [OSS Sonatype staging repository](https://oss.sonatype.org/#stagingRepositories) 并在满足要求时释放它们。 ### [Manual release of a staging repository](https://central.sonatype.org/publish/release/)（如果 `autoReleaseAfterClose` 设置为 `false`） * 访问 https://oss.sonatype.org/#stagingRepositories * 根据 [requirements](https://central.sonatype.org/publish/requirements/) 审查新创建的仓库（JAR 文件、源码、JavaDocs 以及相关的 PGP armored ASCII 文件都存在且版本正确等） * `Close` 仓库以触发对上传组件的验证 * 如果没有错误，点击 `Release` 发布后，新版本将发布到 Central Repository，通常在 30 分钟内完成，但 [search](https://search.maven.org/) 的更新可能需要长达 4 小时。 #### 将新版本推送到 GitHub： ``` git push origin master git push origin ``` ### Maven 仓库 您可以从以下地址下载预编译版本： * [Maven Central repository](https://search.maven.org/search?q=csrfguard) * [OSS Sonatype Nexus repository](https://oss.sonatype.org/#nexus-search;gav~~csrfguard~~~)

标签：BSD协议, CSRF防护, DNS解析, JavaEE Filter, JS文件枚举, Maven, Synchronizer Token, Web安全, YAML, 域名枚举, 域名枚举, 安全库, 开源项目, 数据可视化, 漏洞防御, 漏洞验证, 私有化部署, 网络安全, 蓝队分析, 跨站请求伪造, 防御规避, 隐私保护