docs: Document symbolic link handling for OCI plugin installs#2184
docs: Document symbolic link handling for OCI plugin installs#2184promptless-for-oss wants to merge 1 commit into
Conversation
Add a Symbolic Links in OCI Plugins subsection to the Plugins User Guide covering symlink extraction security validation introduced in helm/helm PR #32387: relative-only targets, no directory escape, and the Windows elevated-privilege requirement. Signed-off-by: promptless[bot] <promptless[bot]@users.noreply.github.com>
|
|
||
| ### 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: |
There was a problem hiding this comment.
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
|
|
||
| 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: | ||
|
|
||
| - Symbolic-link targets must be relative; absolute targets are rejected. |
There was a problem hiding this comment.
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
| 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: | ||
|
|
||
| - Symbolic-link targets must be relative; absolute targets are rejected. | ||
| - Symbolic-link targets must resolve inside the plugin's installation directory; targets that would escape the plugin directory are rejected. |
There was a problem hiding this comment.
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
| - Symbolic-link targets must be relative; absolute targets are rejected. | ||
| - Symbolic-link targets must resolve inside the plugin's installation directory; targets that would escape the plugin directory are rejected. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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
|
|
||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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
1 participant
Open this suggestion in Promptless to view citations and reasoning process
Adds a "Symbolic Links in OCI Plugins" subsection to the Plugins User Guide (
docs/plugins/user/index.md), under "Installing Plugins".Documents the symlink extraction security behavior added in helm/helm PR #32387 ("fix(plugins): secure symbolic link extraction and path validation in OCI plugins"): OCI plugin archives installed via
helm plugin install oci://...may now contain symbolic links, which Helm extracts subject to validation — targets must be relative and must resolve inside the plugin's installation directory, or the install fails. Also documents that creating symlinks on Windows requires running the terminal as Administrator or enabling Developer Mode.Written at the design-intent level (no exact error strings or path-traversal examples) because the source PR is open and unmerged. Single file changed; internal links to Plugin Security and OCI Registries verified.
Trigger Events
Tip: Sort by Shortest Review in the Dashboard to find quick wins ⚡