Add user cache directory as fallback for downloaded symbols

[oh2fih]

Problem

Currently, class PDBUtility() writes downloaded Windows PDB symbols directly to the directories listed in symbols.__path__. When Volatility3 is installed in a system location (e.g., /usr/lib/python3/dist-packages), these directories are not writable by a regular user, causing warnings such as:

WARNING  volatility3.framework.symbols.windows.pdbutil: Cannot write necessary symbol file, please check permissions on /usr/lib/python3/dist-packages/volatility3/symbols/windows/ntkrnlmp.pdb/***.json.xz
WARNING  volatility3.framework.symbols.windows.pdbutil: Cannot write necessary symbol file, please check permissions on /usr/lib/python3/dist-packages/volatility3/framework/symbols/windows/ntkrnlmp.pdb/***.json.xz
WARNING  volatility3.framework.symbols.windows.pdbutil: Cannot write downloaded symbols, please add the appropriate symbols or add/modify a symbols directory that is writable

The documentation on Windows symbol tables states:

If such a symbol table cannot be found, then the associated PDB file will be downloaded from Microsoft’s Symbol Server and converted into the appropriate JSON format, and will be saved in the correct location.

On systems where Volatility3 is installed globally, these “correct locations” are not writable, and defining --symbol-dirs is currently the only way to avoid these errors.

Solution

This PR appends the user cache directory ($XDG_CACHE_HOME/volatility3/symbols or ~/.cache/volatility3/symbols) to constants.SYMBOL_BASEPATHS, which is used to construct symbols.__path__. The parent directory ~/.cache/volatility3 is already used for metadata such as identifier.cache, making it a natural location for cached symbols as well.

After this change, the symbol search order will be:

1. User-specified directories (--symbol-dirs)
2. Shipped framework symbols
3. User cache directory ($XDG_CACHE_HOME/volatility3/symbols)

This is a clean, minimal change to the constants, fully compatible with user-defined symbol directories (--symbol-dirs). It provides a writable fallback location for downloaded symbols, avoiding permission issues when the shipped framework directories are not writable; download_pdb_isf() in class PDBUtility() can write to the user cache directory if needed, ensuring symbols can still be saved even when earlier directories are read-only.

To reduce unnecessary noise during the search process, per-directory write failures are now logged at DEBUG level, while the existing warning remains if no writable directory can be found. This ensures the user is informed about permanent errors while possibly temporary failures remain silent.

In addition, this approach prevents similar permission problems for any future temporary symbol classes that may be added.

[ikelos]

Thanks for the pull request. It looks good, but I'm concerned about putting the cache first. Right now users should be able to permanently set a symbol directory using a ~/.config/volatility3/vol.json file containing:

{
'symbol_dirs': ['~/path/of/their/choosing']
}

This has some downsides, in that I think -s would then overwrite it if provided, and it's not widely known aboutnor well documented (sadly the CLI documentation has yet to make it out of draft), but it is present.

Meanwhile, I do like the concept of allowing for a user-writable symbols directory by default, but I don't think it should be searched first, since that could easily lead to confusion when a user's local cache is taking priority over files they can see in the "right" location. It could also easily act as a disk drain for users that analyse a lot of windows images that are new (and suddenly a random directory in their profile starts filling up rather than where they expected the data to go).

As such, I'd propose that the cache directory get added to the end of the path list, and we add a check that runs through the symbol directories in order, looking for the first one that's writable and then saving it there (or writing out a log message to say it couldn't saved). That would solve the issue we're trying to solve while not impacting users who do already have write access to their volatility directory. Would you be happy adapting this submission into that form please?

[oh2fih]

@ikelos: Thanks for the thoughtful review and explanation.

My original reasoning for prepending the cache directory was based on the general principle of separating application code from mutable runtime data. In many environments (system installs, packaged environments, containers, etc.), the framework directories are not user-writable, so having a dedicated user cache directory avoids permission issues and keeps runtime data separate from the shipped framework directories. Since ~/.cache/volatility3 is already used for metadata such as identifier.cache, it seemed like a natural place for downloaded symbols as well.

That said, I understand the need to preserve predictable behavior and avoid surprising users who expect the shipped or configured symbol directories to be checked first. The concern about cache priority potentially causing confusion also makes sense in that context.

This PR now appends the user cache directory to the symbol search path as a fallback location for downloaded symbols. This ensures symbols can still be saved in a writable location without changing the existing search order for shipped or user-configured directories.

One UX detail to note: if earlier directories are not writable, the framework may emit warnings for those, but later silently and successfully use the cache fallback. Users could see warnings without realizing that the issue was ultimately resolved.

[ikelos]

Thanks very much. So we probably need to drop the "Cannot write necessary symbol file" warnings down to DEBUG messages, but keep the "Cannot write downloaded symbols" as an error. I know the PR is very clean and only touches the constant at the moment, but feel free to fix up pdbutil.py to only issue a debug message for those... Then I think it'll be good for inclusion! 5:)

[oh2fih]

Good idea – I agree that these messages are more appropriate at the DEBUG level.

With this change, permanent failures are still logged as a warning, so the user remains informed and guided:

WARNING  volatility3.framework.symbols.windows.pdbutil: Cannot write downloaded symbols, please add the appropriate symbols or add/modify a symbols directory that is writable

However, individual and likely temporary per-path failures are now logged at the DEBUG level, reducing potential confusion:

DEBUG  volatility3.framework.symbols.windows.pdbutil: Cannot write necessary symbol file, please check permissions on /usr/lib/python3/dist-packages/volatility3/symbols/windows/ntkrnlmp.pdb/***.json.xz
DEBUG  volatility3.framework.symbols.windows.pdbutil: Cannot write necessary symbol file, please check permissions on /usr/lib/python3/dist-packages/volatility3/framework/symbols/windows/ntkrnlmp.pdb/***.json.xz