安全配置

相关源文件

• common/hexec/exec.go
• config/security/securityConfig.go
• config/security/securityConfig_test.go
• config/security/whitelist.go
• config/security/whitelist_test.go
• docs/data/docs.yaml
• helpers/docshelper.go
• hugolib/securitypolicies_test.go
• hugolib/site_stats_test.go
• markup/pandoc/convert_test.go
• markup/rst/convert_test.go
• output/docshelper.go

此页面介绍了 Hugo 的安全配置系统，该系统用于控制 Hugo 如何限制潜在的危险操作。安全系统通过控制外部进程执行、环境变量访问、远程 HTTP 请求等来保护您的网站。

概述

Hugo 基于可配置的白名单实现了一个全面的安全模型。默认情况下，Hugo 应用一个保守的安全策略，允许常见操作，同时防止潜在的安全风险。

来源：config/security/securityConfig.go58-73 config/security/securityConfig.go32-56

默认安全策略

Hugo 随附的默认安全策略允许常见操作

来源：config/security/securityConfig.go32-56

安全配置结构

安全配置组织结构如下

请注意，这些白名单中的所有项目都是正则表达式模式。Hugo 使用 Go 的 regexp 包进行模式匹配，因此所有模式都应遵循 Go 的正则表达式语法。

来源：config/security/securityConfig.go98-109 config/security/securityConfig.go58-96

外部进程安全（security.exec）

security.exec 部分控制 Hugo 可以执行哪些外部程序以及可以传递给它们的哪些环境变量。

允许的可执行文件（allow）

此白名单控制 Hugo 可以运行哪些可执行文件。默认情况下，包括：

• ^(dart-)?sass(-embedded)?$：sass、dart-sass、dart-sass-embedded 用于 SASS 处理
• ^go$：用于 Go 模块
• ^git$：用于 Git 信息
• ^npx$：用于 Node 工具
• ^postcss$：用于 PostCSS 处理
• ^tailwindcss$：用于 TailwindCSS

允许 Python 的配置示例

要完全禁用外部命令执行

来源：config/security/securityConfig.go35-44 config/security/whitelist.go47-98

操作系统环境变量（osEnv）

控制可以传递给外部进程的来自主机系统的环境变量

来源：config/security/securityConfig.go45-48

模板函数安全（security.funcs）

环境变量访问（getenv）

控制通过 os.Getenv 模板函数可以访问哪些环境变量

默认情况下，Hugo 允许访问：

• 以 HUGO_ 开头的环境变量
• CI 环境变量

使用 os.Getenv 访问其他环境变量将导致访问被拒绝错误。

来源：config/security/securityConfig.go49-51 hugolib/securitypolicies_test.go61-67

HTTP 安全（security.http）

security.http 部分控制 Hugo 通过 resources.GetRemote、getJSON 和 getCSV 函数发起的远程 HTTP 请求。

URL 白名单（urls）

控制可以访问哪些 URL

要禁用所有远程 HTTP 请求

来源：config/security/securityConfig.go52-54 hugolib/securitypolicies_test.go160-168

HTTP 方法（methods）

控制可以使用哪些 HTTP 方法

来源：config/security/securityConfig.go54 hugolib/securitypolicies_test.go154-156

媒体类型白名单（mediaTypes）

此白名单确定 HTTP 响应中的 Content-Type 标头哪些媒体类型可以被信任

当 Hugo 无法通过文件内容分析确定媒体类型时，如果媒体类型在白名单中，它将使用 Content-Type 标头。

来源：config/security/securityConfig.go95 hugolib/securitypolicies_test.go179-190

内联短代码安全

enableInlineShortcodes 设置控制内容文件是否允许使用内联短代码。如果内容来自不受信任的来源，内联短代码可能存在安全风险。

来源：config/security/securityConfig.go72 config/security/securityConfig.go191-194

安全系统架构

来源：config/security/securityConfig.go111-152 config/security/securityConfig.go215-230

常见访问控制场景

操作	默认安全	配置键	示例模式
执行外部程序	仅限于特定程序	security.exec.allow	^python$
访问环境变量	仅限于常见的系统变量	security.exec.osEnv	^PATH$
使用 getenv 函数	仅 HUGO_* 变量和 CI	security.funcs.getenv	^DATABASE_URL$
发起 HTTP 请求	允许所有 URL	security.http.urls	^https://api\.example\.com/.*$
使用 HTTP 方法	仅 GET/POST	security.http.methods	^GET$
允许内联短代码	已禁用	security.enableInlineShortcodes	true

来源: config/security/securityConfig.go35-56 config/security/securityConfig_test.go142-167

错误处理

当发生安全策略违规时，Hugo 会返回一个 `AccessDeniedError`，其中包含：

• 被拒绝资源的名称
• 阻止它的策略路径
• 当前安全配置

错误消息看起来像这样：

access denied: "SOME_ENV_VAR" is not whitelisted in policy "security.funcs.getenv"; the current security configuration is:

[security]
  enableInlineShortcodes = false

  [security.exec]
    allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^npx$', '^postcss$', '^tailwindcss$']
    osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE)$']

  [security.funcs]
    getenv = ['^HUGO_', '^CI$']

  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

来源: config/security/securityConfig.go215-230 config/security/securityConfig_test.go136-139

最佳实践

1. 最小化权限：遵循最小特权原则——仅允许您的站点真正需要的可执行文件和环境变量。

2. 审查默认设置：在修改安全设置之前，请了解其默认值。

3. URL 限制：如果您使用 `resources.GetRemote` 或类似功能，请考虑限制为特定域。

4. 避免内联短代码：除非您完全信任所有内容作者，否则请将 `enableInlineShortcodes` 保持为禁用状态。

5. 审计安全配置：定期审计您的安全设置，尤其是在生产环境中。

相关主题

有关配置 Hugo 的常规信息，请参阅 配置加载和结构。

有关安全设置所控制的 HTTP 客户端功能的信息，请参阅 HTTP 客户端。