Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 32 additions & 1 deletion docs/en-US/Templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,38 @@

[`webhook`][w] can parse a hooks configuration file as a Go template when given the `-template` [CLI parameter](Webhook-Parameters.md).

In addition to the [built-in Go template functions and features][tt], `webhook` provides `getenv` for inserting environment variables and `getenvRequired` for rejecting an unset or empty variable. Use `getenvRequired` for authentication secrets so the configuration fails closed.
In addition to the [built-in Go template functions and features][tt], `webhook` provides:

- `getenv` for inserting environment variables.
- `getenvRequired` for rejecting an unset or empty environment variable.
- `getSecret` for reading one named file from a dedicated secret directory.
- `trimSpace` for explicitly removing surrounding whitespace, including a trailing newline, from a template value.

Use `getenvRequired` or `getSecret` for authentication secrets so the configuration fails closed.

## Secret files

`getSecret` accepts a single file name, not an arbitrary path. It reads from
`/run/secrets` by default, which matches Docker and Docker Swarm secret mounts.
Set `WEBHOOK_SECRET_DIR` to an absolute path when the secrets are mounted
elsewhere.

The function rejects absolute paths, directory separators, path traversal,
files that resolve outside the secret directory, non-regular files, and files
larger than 1 MiB. It preserves the file contents exactly; use `trimSpace`
explicitly when the stored secret contains a trailing newline.

```json
{
"source": "string",
"envname": "AUTHORIZATION",
"name": "Bearer {{ getSecret "webhook-token" | trimSpace | js }}"
}
```

Do not use or expect a general-purpose `cat` function. Restricting reads to a
dedicated operator-controlled directory prevents a hook template from becoming
an arbitrary file reader.

## Example Usage

Expand Down
30 changes: 29 additions & 1 deletion docs/zh-CN/Templates.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,34 @@
# 配置模版

使用 `-template` [CLI 参数][CLI-ENV] 时,可以将配置文件解析为 Go 模板。除了支持[Go 模板内置的函数和特性][Go-Template],程序还提供 `getenv` 用于注入环境变量,以及 `getenvRequired` 用于在变量未设置或为空时拒绝加载配置。认证密钥应使用 `getenvRequired`,确保配置缺失时安全失败。
使用 `-template` [CLI 参数][CLI-ENV] 时,可以将配置文件解析为 Go 模板。除了支持[Go 模板内置的函数和特性][Go-Template],程序还提供:

- `getenv`:注入环境变量;
- `getenvRequired`:环境变量未设置或为空时拒绝加载配置;
- `getSecret`:从专用 Secret 目录读取一个具名文件;
- `trimSpace`:显式移除模板值首尾的空白,包括文件末尾的换行符。

认证密钥应使用 `getenvRequired` 或 `getSecret`,确保配置缺失时安全失败。

## Secret 文件

`getSecret` 只接受单个文件名,不接受任意路径。默认从 `/run/secrets`
读取,与 Docker 和 Docker Swarm 的 Secret 挂载方式一致。如果 Secret
挂载在其他位置,可以把 `WEBHOOK_SECRET_DIR` 设置为相应的绝对路径。

该函数会拒绝绝对路径、目录分隔符、路径穿越、解析到 Secret 目录外的
文件、非普通文件,以及大于 1 MiB 的文件。函数原样保留文件内容;如果
Secret 文件末尾带换行符,应显式使用 `trimSpace`。

```json
{
"source": "string",
"envname": "AUTHORIZATION",
"name": "Bearer {{ getSecret "webhook-token" | trimSpace | js }}"
}
```

项目不会提供通用的 `cat` 模板函数。把读取范围限制在运维人员控制的
专用目录内,可以避免 Hook 模板变成任意文件读取器。

## 使用示例

Expand Down
4 changes: 1 addition & 3 deletions internal/hook/hook.go
Original file line number Diff line number Diff line change
Expand Up @@ -818,9 +818,7 @@ func (h *Hooks) loadFromFileWithOptions(path string, asTemplate, strict, validat
}

if asTemplate {
funcMap := template.FuncMap{"getenv": getenv, "getenvRequired": getenvRequired}

tmpl, err := template.New("hooks").Funcs(funcMap).Parse(string(file))
tmpl, err := template.New("hooks").Funcs(templateFunctions()).Parse(string(file))
if err != nil {
return err
}
Expand Down
76 changes: 76 additions & 0 deletions internal/hook/template_secret.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
package hook

import (
"fmt"
"io"
"os"
"path/filepath"
"strings"
"text/template"
)

const (
defaultSecretDirectory = "/run/secrets"
templateDirectoryEnv = "WEBHOOK_SECRET_DIR"
maxSecretFileSize = int64(1 << 20)
)

func templateFunctions() template.FuncMap {
return template.FuncMap{
"getenv": getenv,
"getenvRequired": getenvRequired,
"getSecret": getSecret,
"trimSpace": strings.TrimSpace,
}
}

// getSecret reads one named secret from the configured secret directory.
// Names, rather than arbitrary paths, keep template file access confined to
// the directory supplied by the operator.
func getSecret(name string) (string, error) {
if name == "" || name == "." || name == ".." || filepath.IsAbs(name) ||
strings.ContainsAny(name, `/\`) || filepath.Base(name) != name {
return "", fmt.Errorf("invalid secret name %q: use a single file name", name)
}

secretDirectory := os.Getenv(templateDirectoryEnv)
if secretDirectory == "" {
secretDirectory = defaultSecretDirectory
}
if !filepath.IsAbs(secretDirectory) {
return "", fmt.Errorf("%s must be an absolute path", templateDirectoryEnv)
}

secretRoot, err := os.OpenRoot(filepath.Clean(secretDirectory))
if err != nil {
return "", fmt.Errorf("open secret directory: %w", err)
}
defer secretRoot.Close()

secretFile, err := secretRoot.Open(name)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid blocking before rejecting FIFO secret entries

When the selected secret is a FIFO with no writer, secretRoot.Open(name) blocks indefinitely, so execution never reaches the later regular-file check. A hook configuration referencing such an entry can therefore hang validation or server startup instead of rejecting the documented unsupported file type; open the entry without blocking or otherwise verify its type before a potentially blocking read.

Useful? React with 👍 / 👎.

if err != nil {
return "", fmt.Errorf("open secret %q: %w", name, err)
}
defer secretFile.Close()

secretInfo, err := secretFile.Stat()
if err != nil {
return "", fmt.Errorf("stat secret %q: %w", name, err)
}
if !secretInfo.Mode().IsRegular() {
return "", fmt.Errorf("secret %q is not a regular file", name)
}
if secretInfo.Size() > maxSecretFileSize {
return "", fmt.Errorf("secret %q exceeds the %d-byte size limit", name, maxSecretFileSize)
}

contents, err := io.ReadAll(io.LimitReader(secretFile, maxSecretFileSize+1))
if err != nil {
return "", fmt.Errorf("read secret %q: %w", name, err)
}
if int64(len(contents)) > maxSecretFileSize {
return "", fmt.Errorf("secret %q exceeds the %d-byte size limit", name, maxSecretFileSize)
}

return string(contents), nil
}
111 changes: 111 additions & 0 deletions internal/hook/template_secret_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
package hook

import (
"bytes"
"os"
"path/filepath"
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestGetSecretReadsNamedFileWithoutChangingContents(t *testing.T) {
secretDirectory := t.TempDir()
t.Setenv(templateDirectoryEnv, secretDirectory)
require.NoError(t, os.WriteFile(filepath.Join(secretDirectory, "webhook-token"), []byte("secret-value\n"), 0o600))

value, err := getSecret("webhook-token")
require.NoError(t, err)
assert.Equal(t, "secret-value\n", value)
}

func TestGetSecretRejectsInvalidNames(t *testing.T) {
t.Setenv(templateDirectoryEnv, t.TempDir())

for _, name := range []string{"", ".", "..", "../secret", "nested/secret", `nested\secret`, "/etc/passwd"} {
t.Run(name, func(t *testing.T) {
_, err := getSecret(name)
require.Error(t, err)
assert.Contains(t, err.Error(), "invalid secret name")
})
}
}

func TestGetSecretRequiresAbsoluteDirectory(t *testing.T) {
t.Setenv(templateDirectoryEnv, "relative/secrets")

_, err := getSecret("webhook-token")
require.Error(t, err)
assert.Contains(t, err.Error(), templateDirectoryEnv+" must be an absolute path")
}

func TestGetSecretRejectsPathEscapingSymlink(t *testing.T) {
secretDirectory := t.TempDir()
t.Setenv(templateDirectoryEnv, secretDirectory)
outsideFile := filepath.Join(t.TempDir(), "outside-secret")
require.NoError(t, os.WriteFile(outsideFile, []byte("must-not-be-read"), 0o600))
if err := os.Symlink(outsideFile, filepath.Join(secretDirectory, "webhook-token")); err != nil {
t.Skipf("cannot create symlink: %v", err)
}

_, err := getSecret("webhook-token")
require.Error(t, err)
assert.Contains(t, err.Error(), `open secret "webhook-token"`)
assert.NotContains(t, err.Error(), "must-not-be-read")
}

func TestGetSecretRejectsNonRegularAndOversizedFiles(t *testing.T) {
secretDirectory := t.TempDir()
t.Setenv(templateDirectoryEnv, secretDirectory)
require.NoError(t, os.Mkdir(filepath.Join(secretDirectory, "directory"), 0o700))
require.NoError(t, os.WriteFile(
filepath.Join(secretDirectory, "oversized"),
bytes.Repeat([]byte("x"), int(maxSecretFileSize)+1),
0o600,
))

_, err := getSecret("directory")
require.Error(t, err)
assert.Contains(t, err.Error(), "is not a regular file")

_, err = getSecret("oversized")
require.Error(t, err)
assert.Contains(t, err.Error(), "exceeds the")
}

func TestGetSecretReportsMissingFileWithoutLeakingContents(t *testing.T) {
secretDirectory := t.TempDir()
t.Setenv(templateDirectoryEnv, secretDirectory)

_, err := getSecret("missing-secret")
require.Error(t, err)
assert.Contains(t, err.Error(), `secret "missing-secret"`)
}

func TestHooksTemplateLoadsSecretFile(t *testing.T) {
secretDirectory := t.TempDir()
t.Setenv(templateDirectoryEnv, secretDirectory)
require.NoError(t, os.WriteFile(filepath.Join(secretDirectory, "webhook-token"), []byte("secret-value\n"), 0o600))

hooksPath := filepath.Join(t.TempDir(), "hooks.json.tmpl")
templateConfig := `[{"id":"secret-template","execute-command":"/bin/echo","response-message":"{{ getSecret "webhook-token" | trimSpace | js }}"}]`
require.NoError(t, os.WriteFile(hooksPath, []byte(templateConfig), 0o600))

var hooks Hooks
require.NoError(t, hooks.LoadFromFile(hooksPath, true))
require.Len(t, hooks, 1)
assert.Equal(t, "secret-value", hooks[0].ResponseMessage)
}

func TestHooksTemplateFailsClosedWhenSecretIsMissing(t *testing.T) {
t.Setenv(templateDirectoryEnv, t.TempDir())
hooksPath := filepath.Join(t.TempDir(), "hooks.json.tmpl")
templateConfig := `[{"id":"secret-template","execute-command":"/bin/echo","response-message":"{{ getSecret "missing-secret" }}"}]`
require.NoError(t, os.WriteFile(hooksPath, []byte(templateConfig), 0o600))

var hooks Hooks
err := hooks.LoadFromFile(hooksPath, true)
require.Error(t, err)
assert.Contains(t, err.Error(), "missing-secret")
}
Loading