[Moep90]

Summary

${from_file:...} now only reads a file that resolves, after following symlinks, below the directory Kapitan runs in or below the inventory path. Any other path fails the inventory render.

Fixes #1639

This should land together with #1676 (reload the inventory after --fetch) or before it. #1676 lets classes fetched from someone else take effect in the same run, and without this change such a class can read any file the user running Kapitan can read.

Motivation

On master, a class with ${from_file:${oc.env:HOME}/.kube/config} or ${from_file:../outside/secret.txt} compiles with exit code 0, and both files end up in the compiled output. Same on 0.36.3.

How it works:

• register_resolvers binds the real paths of the working directory and of the inventory path to from_file when it registers it. Each inventory worker calls it, so the roots come from the process that renders.
• from_file compares the real path of its argument with those roots via os.path.commonpath and raises InventoryError when neither contains it. The check runs before the file is opened, so it also doesn't tell whether an outside file exists.
• Relative paths still resolve against the working directory.
• A project that reads outside on purpose can define its own from_file in resolvers.py. User resolvers are registered after the built-ins and replace them. I checked that by hand and wrote it into the docs.

I didn't tie this to --path-traversal-mode from #1566. That PR isn't merged, its default warn wouldn't confine anything, and it sets the mode in the compile workers, while from_file runs during the inventory render. If you'd rather have one switch for all file accessors, I can make from_file follow that flag once #1566 is in.

Affected files or URLs

• kapitan/inventory/backends/omegaconf/resolvers.py: from_file, register_resolvers
• tests/test_omegaconf_from_file.py (new)
• docs/pages/inventory/omegaconf.md: Utility Resolvers

Test plan

• Tests added: allowed relative and absolute paths in the project and a file in an inventory outside the working directory, refused absolute path, ../ path and symlink pointing out. Two of the tests run a real kapitan compile. The four refusal tests fail on master, the allowed ones pass on both.
• Documentation updated, make docs_build (mkdocs --strict) and make docs_check pass
• make lint passes
• make format passes (ruff format --check and pre-commit on the changed files)
• Full test suite passes (uv run pytest tests/ --no-cov, 764 passed, 4 skipped)
• The repro from [feat]: confine the omegaconf from_file resolver to the project #1639 now fails with the new error and writes no compiled output.

Risk assessment

Projects that use from_file on files outside the working directory and the inventory path break with this change, for example a monorepo reading ../shared/ca.crt. The error names the path and says how to override the resolver. Revert is a single commit.

Follow-up work intentionally left out

• A missing file still logs an error and returns the string FILE NOT EXISTS, so the compile carries on. [feat]: confine the omegaconf from_file resolver to the project #1639 suggests failing there too. That changes behaviour for a different reason, so I'd do it separately.
• The other file accessors (jsonnet natives, jinja2 render, input paths) are covered by feat: add --path-traversal-mode to warn or fail when file accessors leave their search paths #1566.
• external, jinja2 and kadet inputs in a fetched class can still run code by design, as [feat]: confine the omegaconf from_file resolver to the project #1639 says.