Skip to content

docs: Document symbolic link handling for OCI plugin installs #2184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
promptless-for-oss wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Document symbolic link handling for OCI plugin installs #2184

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
13 changes: 13 additions & 0 deletions docs/plugins/user/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,19 @@ Helm has a built-in command to install plugins that defaults to secure installat

See `helm plugin install --help` for more information.

### Symbolic Links in OCI Plugins

When you install a plugin from an OCI registry with `helm plugin install oci://<registry>/<plugin>`, the plugin archive may contain symbolic links. Helm extracts these links subject to security validation (see [Plugin Security](#plugin-security)), which keeps a plugin from writing files outside its own installation directory:

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

OCI plugin install (oci://) tar extraction adds a tar.TypeSymlink case with security validation. The filepath.Rel + strings.HasPrefix(rel, "..") escape check keeps symlinks from resolving outside the installation directory. Source: internal/plugin/installer/oci_installer.go in PR #32387.

Source: https://github.com/helm/helm/pull/32387/files#diff-oci_installer.go


- Symbolic-link targets must be relative; absolute targets are rejected.

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Absolute symlink targets are rejected: after cleanTarget := filepath.Clean(header.Linkname), if filepath.IsAbs(cleanTarget) the code returns an error ("symlink with absolute target"). Source: oci_installer.go in PR #32387.

Source: https://github.com/helm/helm/pull/32387/files#diff-oci_installer.go

- Symbolic-link targets must resolve inside the plugin's installation directory; targets that would escape the plugin directory are rejected.

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Symlink targets must resolve inside the installation directory: targetPath := filepath.Join(filepath.Dir(path), cleanTarget); rel := filepath.Rel(targetDir, targetPath); if err != nil || strings.HasPrefix(rel, "..") returns "symlink target ... escapes installation directory". Source: oci_installer.go in PR #32387.

Source: https://github.com/helm/helm/pull/32387/files#diff-oci_installer.go


If a symbolic link fails these checks, the installation fails as a whole. A rejected symbolic link means the plugin archive is malformed or potentially unsafe, so obtain the plugin from a trusted source or contact its author.

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

A failed validation aborts the whole install: each rejection is a return fmt.Errorf(...) inside the tar.TypeSymlink case, which propagates out of extractTar and up through the OCI install path (helm plugin install oci://...), rather than silently skipping the bad link. Source: oci_installer.go in PR #32387.

Source: https://github.com/helm/helm/pull/32387/files#diff-oci_installer.go


On Windows, creating symbolic links requires elevated privileges. Run your terminal as Administrator or [enable Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development); otherwise, installation fails.

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Windows requires elevated privileges: if runtime.GOOS == "windows" and !hasSymlinkPrivilege(), install fails with a message to run as administrator or enable developer mode; os.Symlink permission errors are also mapped to an admin-privileges-required error. Source: oci_installer.go in PR #32387.

Source: https://github.com/helm/helm/pull/32387/files#diff-oci_installer.go


For more on OCI registries, see [OCI Registries](/topics/registries.mdx).

## Listing Installed Plugins

The command to list plugins includes the plugin's name, version, type, API version, provenance, and source.
Expand Down
Loading