PathScope User Manual

This manual walks through the screens in order, from finding the weak spots of this machine with PathScope to working out where to start fixing them. The screen instructions avoid technical jargon where possible, and the commands are collected in the chapter “Using the command line”.

1. What PathScope is

PathScope finds the “paths” by which an ordinary user on this machine can reach root (administrator privileges) or sensitive data, and shows, with priorities, where fixing is most effective. It is meant for checking machines you manage yourself and test environments.

The analysis is read-only. It does not change settings or files, and it does not apply fixes automatically. Example fix commands are shown, but whether to run them is up to you.

2. Installing and launching

PathScope is installed as a separate app with its own icon. Here is how to start it.

When it starts, a window opens with the buttons “Analyze”, “History”, “LLM assist”, “Explain with LLM” and “Settings” along the top. “Explain with LLM” cannot be pressed until a result is shown. PathScope does not open a listening port, and its window does not load external sites.

3. Running an analysis and reading the result

When you click “Analyze”, PathScope gathers the state of this machine, starting from the current user, and analyzes it. It can take from a few seconds to several tens of seconds. When it finishes, the result is saved automatically as one entry in the history.

Steps

1. Click “Analyze”.
2. In “Path diagram” and “Path list”, see which user reaches root or sensitive data by which steps. Circles and squares are users and destinations, and each line is one step that raises privileges. The number on a line corresponds to the “reason the step works” in the table below the diagram.
3. In “Fix points (in the order to fix them)”, check the places where fixing has the biggest effect. Each item shows its priority (critical, high, medium or low, with a score), the number of paths affected, a suggested fix, and the nearest MITRE ATT&CK technique.
4. Click “If I fix this?” to re-analyze, as a trial, the paths you would have if that fix point were fixed as suggested. “If I fix them all?” does the same for all the fix points shown. Neither changes this machine.
5. Read the list of areas that could not be checked, shown below the fix points.

What kinds of paths it finds

• Membership of the docker group (which allows the same operations as root)
• Abusing an executable that runs with root privileges (SUID) to become root, to rewrite files, or to read files
• The executable of a root service, of a program that root listens with, or of a file that root runs periodically can be rewritten
• Settings that allow sudo without a password (the sudo and cron configuration files are covered when they have been read with “LLM assist”)
• On Mac, an app that has been granted access to all files can be rewritten
• The installed software, kernel, or macOS version still has a known vulnerability that has been exploited in real attacks or is very likely to be (listed in the CISA KEV, or not in the KEV but with a high FIRST EPSS score; only those that let an ordinary user become root)

Known vulnerabilities are checked against data bundled with the app. The targets are macOS and the versions of Debian, Ubuntu, RHEL family, SUSE, Arch and Alpine for which data exists; anything else (Debian 11 and earlier, Fedora and so on) is shown as “unchecked”. It is not a feature for examining vulnerabilities exhaustively.

4. History, export, recurring checks

Analysis results are kept automatically as a history on this machine. Click “History” to open the list, where you can open an entry, give it a label (for example, before the fix), or delete it. Select two entries and click “Compare the two selected” to see the paths that disappeared and appeared and the changes in fix points. Use this to compare the situation before and after a fix.

Analysis results saved in JSON format on another machine can be brought into the history with “Import results”. Select two or more entries in the history and click “Summarize selected” to see which machines are most at risk and which weaknesses are shared by several machines.

The result on screen can be saved as “Analysis result (JSON)”, “Watch list (JSON)” or “auditd rules (for the Linux audit feature)”. You choose the destination in the save dialog. It only writes files; it does not apply any settings or change this machine.

This writes a configuration file that analyzes periodically and notifies you when paths have increased since last time.

1. Show an analysis result and click “Save as the result to compare against”.
2. Set the “Interval (minutes)” (from 5 to 10080).
3. On Mac click “Save launchd settings…”, on Linux click “Save systemd settings…”, and choose where to save.
4. Check the written content, then register it yourself (for example with launchctl load). PathScope does not register it.

5. Features that use an LLM (optional)

Getting it ready

1. Check “Enable LLM”.
2. Choose the “LLM to use”. The choices are the commands claude, opencode, codex and agy, and those whose “Status” is “Installed” can be used. If it says “Not found”, install that command first.
3. Choose “What to send to the LLM when reading settings” (see the table below).
4. Click “Save”.

In the list, the “Model” and “Timeout (seconds)” can be changed for each LLM. claude is started with command execution and file reading switched off. opencode, codex and agy are treated as ones that cannot be switched off, and cannot be used unless you check “I understand that this LLM cannot be stopped from running commands or reading files”. An LLM that cannot be restricted may read files on its own judgment along the way, and their contents may be sent to the LLM’s service.

Explain with LLM

With a result shown, click “Explain with LLM” to have the LLM write an overall assessment, the order and reasons for fixing, what the areas that could not be checked mean, and similar points. Only a summary of the paths, fix points and unchecked areas is passed; the raw collected information (such as lists of file owners and permissions) is not. The summary does, however, contain the user names and file paths that appear in the paths. The LLM’s reply is for reference. People check it and decide what to do, and nothing changes automatically on the basis of the reply.

LLM assist (reading configuration files)

Configuration files such as sudoers, cron and scripts are written in all sorts of ways, and a program alone sometimes cannot read them. LLM assist has an LLM read such files and look for descriptions that involve root privileges.

1. Click “LLM assist”. Candidate files to be read are listed with the reason for each (all are selected at first). Candidates include sudoers, cron, systemd and launchd settings, and executables loaded by services that run as root. Uncheck any you do not want to send.
2. Click “Send the ○ selected to the LLM”. A confirmation of what will be sent appears; read it, then click “Send (confirmed)”.
3. Check “Items found”, “Files read” and “Files not read (these stay unchecked)” in the result.
4. Click “Apply and analyze again” to add the items found to the analysis. If you no longer want to use them, delete them from “Saved”.

Only the items the LLM listed that were confirmed to be actually present as a line in the original file are used. Items that could not be confirmed appear only under “For reference” and are not used in the analysis. The confirmation is repeated at every analysis, so an item whose original line has disappeared is no longer used.

6. Using the command line

The same analysis as in the window can be run with the pathscope command. Run with no options, it analyzes the paths from the current user to root. Collection is read-only and does not change the state of the machine.

pathscope
pathscope --json-out=report.json
pathscope --what-if-fix=all
pathscope --baseline=base.json --fail-on=new --notify
pathscope --print-schedule=systemd --interval-min=60
pathscope --export-watch=watch.json --export-auditd=pathscope.rules
pathscope --plain
pathscope --version
pathscope --lang=en

The output is Markdown. Under the heading “PathScope result” come a summary table, the paths, the fix points (a table of priority, step, reason and paths affected, then, for each number, a detail section with the ATT&CK mapping, the fix commands and a caution), the coverage, and the assumptions, in that order. The fix points appear only when paths were found, and the assumptions only when there is something to state. With --what-if-* a list titled “If these changes were made” follows, and with --baseline a list of the changes since the previous run. You can paste it straight into a note or a ticket. To get the older plain-text layout, add --plain.

The exit code is 0 for normal, 1 when a --fail-on condition was met, and 2 for a usage or input/output error. When run as root, it also collects the listeners that root is waiting on directly. Results of reading settings that were saved with LLM assist are also included in the command’s analysis.

7. Where data is stored, and updates

The history can be erased with “Delete all” on the history screen. Analysis results contain sensitive information about how this machine is configured (user names, file paths, permissions), so please limit where they are kept and shared. To use a command that is not in the LLM list, add it by hand to profiles in the settings file. It cannot be changed from the window.

Updating the app

PathScope on Mac updates itself, separately from RoamSwitch. It connects to lafine.net, to get the latest version information, only when you click “Check for updates” (no information about this machine or the analysis results is sent). If a new version is available, click “Install v○○”, and when it finishes click “Restart to apply”. A downloaded update is replaced in only after its signature has been verified to show it has not been tampered with and passes.

On Linux it is part of the RoamSwitch package, so it is updated by updating that package. The “Updates” tab also says so.

The data used for analysis, such as known vulnerabilities, is bundled with the app. Anything found after that is not checked until you update PathScope. When the bundled data has become old, the analysis result says so.

8. What it does not do

• It does not change settings or files, and it does not run fixes automatically. It goes only as far as showing suggested fixes.
• “No paths found” is a result within the range that could be collected. It is not proof of safety.
• It does not examine vulnerabilities exhaustively. It looks only at known vulnerabilities that have been exploited in real attacks and that let an ordinary user become root.
• “If I fix this?” can be used only on a result from an analysis just made. It cannot be used on a result opened from the history.

9. Troubleshooting