Manual de uso de PathScope
Este manual recorre las pantallas en orden, desde encontrar con PathScope los puntos débiles de este equipo hasta comprobar por dónde conviene empezar a corregirlos. Las explicaciones de las pantallas evitan la jerga técnica en lo posible; los comandos están reunidos en el capítulo «Uso desde la línea de comandos».
1. Qué es PathScope
PathScope identifica las «rutas» por las que un usuario común de este equipo puede llegar a root (privilegios de administrador) o a datos sensibles, y muestra con prioridades dónde corregir es más eficaz. Está pensado para revisar equipos que usted administra y entornos de prueba.
El análisis es de solo lectura. No modifica ajustes ni archivos y no corrige nada automáticamente. Muestra ejemplos de comandos de corrección, pero la decisión de ejecutarlos es del usuario.
pathscope). PathScope es una app independiente bajo Apache License 2.0. Queda fuera del alcance del EULA de RoamSwitch.2. Instalación e inicio
PathScope se instala como una aplicación independiente con su propio icono. Así se inicia.
| Entorno | Cómo iniciarlo |
|---|---|
| Mac | Abra PathScope.app desde el archivo de distribución (DMG) y pulse «Analizar». |
| Linux | Abra «PathScope» desde la lista de aplicaciones y pulse «Analizar». Desde un terminal, ejecute pathscope-gui. La ventana necesita WebKitGTK 4.1, que se instala automáticamente con deb y rpm. En Arch, instale webkit2gtk-4.1 como dependencia opcional. |
| Línea de comandos | Ejecute pathscope en un terminal. En Mac es PathScope.app/Contents/MacOS/pathscope. |
Al iniciarse se abre una ventana con los botones «Analizar», «Historial», «Asistente LLM», «Explicar con LLM» y «Ajustes» en la parte superior. «Explicar con LLM» no se puede pulsar hasta que se muestre un resultado. PathScope no abre ningún puerto en escucha y su ventana no carga sitios externos.
3. Analizar y leer el resultado
Al pulsar «Analizar», PathScope reúne el estado de este equipo a partir del usuario actual y lo analiza. Puede tardar de unos segundos a varias decenas de segundos. Al terminar, el resultado se guarda automáticamente como una entrada del historial.
Pasos
- Pulse «Analizar».
- En el «Diagrama de rutas» y en la «Lista de rutas» se ve qué usuario llega a root o a datos confidenciales, y mediante qué pasos. Los círculos y cuadrados representan usuarios y destinos, y cada línea representa un paso que eleva privilegios. El número sobre una línea corresponde a «por qué se cumple ese paso» en la tabla situada debajo del diagrama.
- En «Puntos de corrección (en el orden en que conviene corregirlos)», compruebe dónde corregir tiene mayor efecto. Cada elemento muestra su prioridad (crítica, alta, media o baja, con una puntuación), el número de rutas afectadas, una corrección sugerida y la técnica de MITRE ATT&CK más cercana.
- Pulse «¿Y si corrijo este?» para volver a analizar, de forma hipotética, las rutas que quedarían si ese punto se corrigiera como se sugiere. «¿Y si corrijo todos?» hace lo mismo con todos los puntos mostrados. Ninguna de las dos opciones modifica este equipo.
- Lea la lista de las áreas que no se pudieron comprobar, mostrada bajo los puntos de corrección.
Qué rutas encuentra
- Pertenencia al grupo docker, lxd, incus, libvirt o disk (Linux; permite las mismas operaciones que root), o al grupo shadow, adm o systemd-journal (Linux; permite leer los hashes de contraseñas y los registros de autenticación)
- Abuso de un ejecutable que se ejecuta con privilegios de root (SUID) para convertirse en root, reescribir archivos o leer archivos
- Abuso de un ejecutable con una capability privilegiada (como cap_setuid o cap_dac_override) para convertirse en root o leer archivos protegidos (Linux)
- Se puede reescribir el ejecutable de un servicio que corre como root, de un programa en el que root escucha o de un archivo que root ejecuta periódicamente (también cuando el usuario pertenece a un grupo con permiso de escritura)
- Se puede reescribir el archivo de entorno de un servicio que corre como root (Linux) o una biblioteca dinámica que carga (Mac)
- Aunque el ejecutable en sí no se pueda reescribir, el directorio donde está es escribible (sin el bit sticky), por lo que se puede reemplazar el archivo entero
- Configuraciones que permiten sudo sin contraseña (como root o como otro usuario)
- Reescribir o abusar de un servicio o de un archivo programado que se ejecuta como otro usuario, o de un comando que se puede ejecutar con sudo, para convertirse en ese usuario y llegar desde allí a root (una ruta de varios pasos)
- Se pueden leer los archivos de credenciales del directorio personal de otro usuario (claves privadas SSH, ~/.aws/credentials, etc.) (solo se comprueban su existencia y sus permisos, nunca su contenido)
- En Mac, se puede reescribir una aplicación con permiso de acceso a todos los archivos
- El software instalado, el kernel o la versión de macOS conservan una vulnerabilidad conocida que permite a un usuario común convertirse en root (las incluidas en el KEV de CISA, las que no están en el KEV pero tienen un EPSS alto de FIRST, y las que tienen un módulo de explotación público. Que exista un módulo de explotación no significa que se haya confirmado su explotación)
Las líneas de sudoers, doas.conf y cron escritas en un formato fijo se leen sin usar un LLM. Solo Linux lee doas.conf y cron. sudoers normalmente solo lo puede leer root, así que se incluye cuando se ejecuta como root. Las líneas que no se pudieron leer en una forma fija, como las de alias que no se resuelven, las negaciones y los comodines, quedan en el ámbito no comprobado. Estas se pueden leer con la «asistencia de LLM».
La comprobación de vulnerabilidades conocidas usa los datos incluidos en la app. Cubre macOS y las versiones de Debian, Ubuntu, familia RHEL, SUSE, Arch y Alpine para las que hay datos. Las demás (Debian 11 y anteriores, Fedora, etc.) se muestran como «sin comprobar». No es una función que busque vulnerabilidades de forma exhaustiva. Una vulnerabilidad cuyas condiciones de explotación se conocen no se convierte en ruta si esas condiciones no se dan en este equipo. Ejemplos de condiciones son que exista un ejecutable SUID concreto, que se puedan usar espacios de nombres de usuario y que se pueda cargar un módulo concreto del kernel.
4. Historial, exportación y comprobación periódica
Los resultados del análisis se guardan automáticamente como historial en este equipo. Al pulsar «Historial» se abre la lista, donde se puede abrir un resultado, ponerle una etiqueta (por ejemplo, «antes de corregir») o eliminarlo. Si selecciona dos y pulsa «Comparar las dos seleccionadas», verá las rutas que han desaparecido, las que se han añadido y el cambio en los puntos de contramedida. Úselo para comparar el antes y el después de una corrección.
Los resultados de análisis en formato JSON guardados en otros equipos se pueden incorporar al historial con «Importar resultado de análisis». Si selecciona dos o más entradas del historial y pulsa «Agregar el historial seleccionado», verá el orden de los equipos por mayor riesgo y las debilidades comunes a varios equipos.
Si no se pudo guardar en el historial, en las «Premisas del análisis» del resultado aparece «No se pudo guardar en el historial: motivo».
El resultado del análisis que se está mostrando se puede guardar como «Resultado del análisis (formato JSON)», «Objetivos de vigilancia (JSON)», «Reglas de auditd (para la función de auditoría de Linux)», «Reglas para RoamSwitch Server (Falco)» y «Resultado del análisis (formato SARIF)». El destino se elige en la pantalla que se abre. Solo exporta archivos: no aplica ajustes ni modifica este equipo. Revise el contenido de las reglas de Falco y colóquelas en /etc/falco/rules.d/.
Esto escribe un archivo de configuración que analiza periódicamente y avisa cuando hay más rutas que la vez anterior.
- Muestre un resultado de análisis y pulse «Guardar como referencia».
- Indique el «Intervalo (minutos)» (de 5 a 10080).
- En Mac pulse «Guardar configuración de launchd…», en Linux «Guardar configuración de systemd…», y elija dónde guardar.
- Compruebe el contenido escrito y regístrelo usted mismo (por ejemplo, con launchctl load). PathScope no lo registra.
Cree el archivo de referencia con los mismos permisos que la ejecución periódica (root o usuario normal). Si crea la referencia como root y ejecuta la ejecución periódica como usuario normal, no se puede detectar el aumento de rutas en el ámbito que el usuario normal no ve. Si los permisos son distintos, se emite un aviso por la salida de error estándar y, si la referencia es de root, también se notifica.
5. Funciones que usan un LLM (opcional)
Puesta en marcha
- Marque «Activar la integración con LLM».
- Elija el «LLM que se usará». Las opciones son los comandos claude, opencode, codex y agy, y se pueden usar aquellos cuyo «Estado» es «Instalado». Si indica «No encontrado», instale primero ese comando.
- Elija «Qué se envía al LLM al leer la configuración» (vea la tabla de abajo).
- Pulse «Guardar».
En la lista, el «Modelo» y el «Tiempo de espera (segundos)» se pueden cambiar para cada LLM. claude se inicia con la ejecución de comandos y la lectura de archivos desactivadas. opencode, codex y agy se tratan como no restringibles y no se pueden usar si no marca «Entiendo que a este LLM no se le puede impedir ejecutar comandos ni leer archivos». Un LLM que no se puede restringir puede leer archivos por su cuenta durante el proceso, y su contenido puede enviarse al servicio del LLM.
Explicar con LLM
Al mostrar un resultado de análisis y pulsar «Explicar con LLM», el LLM redacta la valoración global, la prioridad y los motivos de las correcciones, el significado del ámbito no comprobado, etc. Lo que se entrega es solo un resumen de las rutas, los puntos de contramedida y el ámbito no comprobado. La información en bruto recopilada (como listas de propietarios y permisos de archivos) no se entrega. Sin embargo, el resumen incluye los nombres de usuario y las rutas de archivo que aparecen en las rutas. La respuesta del LLM es orientativa. La comprobación y la respuesta las decide una persona, y nada cambia automáticamente a partir de la respuesta.
Las direcciones IP, dominios, números CVE y hashes que escribe el LLM se comparan con lo que recibió (resumen del resultado del análisis). Un valor que no aparece en ese material consta bajo la explicación en pantalla en «Valores que no aparecen en el material recopilado», como posible invención. Solo se comparan cadenas; no se pregunta al LLM.
Asistente LLM (lectura de archivos de configuración)
Los archivos de configuración como sudoers, cron y los scripts se escriben de formas muy variadas, y un programa por sí solo a veces no puede leerlos. El asistente LLM hace que un LLM lea esos archivos y busque descripciones relacionadas con los privilegios de root.
- Pulse «Asistente LLM». Los archivos candidatos a leer aparecen en una lista con el motivo de cada uno (al principio están todos seleccionados). Son candidatos sudoers, cron, la configuración de systemd y launchd y los ejecutables que cargan los servicios que corren como root, entre otros. Desmarque los que no quiera enviar.
- Pulse «Enviar al LLM los ○ seleccionados». Aparece una confirmación de lo que se enviará; léala y pulse «Enviar (confirmado)».
- Revise en el resultado «Elementos encontrados», «Archivos leídos» y «Archivos no leídos (siguen sin comprobar)».
- Pulse «Aplicar y volver a analizar» para añadir los elementos encontrados al análisis. Si ya no quiere usarlos, elimínelos desde «Guardado».
Solo se usan los elementos indicados por el LLM cuya línea se ha confirmado que existe realmente en el archivo original. Los que no se pudieron confirmar aparecen únicamente en «Solo como referencia» y no se usan en el análisis. La comprobación se repite en cada análisis, por lo que un elemento cuya línea original ha desaparecido deja de usarse.
| Qué se envía | Detalle |
|---|---|
| Estándar | Los valores que parecen contraseñas o claves se sustituyen por «[REDACTED]» antes de enviarlos. No se envían archivos como claves privadas. De un archivo grande solo se envían las líneas que contienen rutas o comandos. |
| Sin restricciones | Un ajuste para los casos en que el contenido no sale de su equipo, como con un LLM local (bajo su responsabilidad). También se envían los hashes de contraseñas y similares. |
6. Uso desde la línea de comandos
El mismo análisis de la ventana se puede ejecutar con el comando pathscope. Sin opciones, analiza las rutas del usuario actual a root. La recopilación es de solo lectura y no modifica el estado del equipo.
En Mac, si la app está en la carpeta Aplicaciones, el comando está en /Applications/PathScope.app/Contents/MacOS/pathscope. Para llamarlo por su nombre corto, ejecute lo siguiente en el Terminal. Después basta con pathscope.
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/PathScope.app/Contents/MacOS/pathscope /usr/local/bin/pathscope
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 --export-roamswitch=94-pathscope-watch.yaml
pathscope --format=json
pathscope --sarif-out=report.sarif
sudo pathscope --check-agent-users
pathscope --plain
pathscope --version
pathscope --lang=en
| Opción | Detalle |
|---|---|
--json-out=<file> | Guarda el resultado como JSON. |
--what-if-fix=all | Vuelve a analizar, de forma hipotética, las rutas que quedarían si todo se corrigiera como se sugiere. Con un número, solo ese punto de corrección. |
--baseline=<file> --fail-on=new | Compara con un JSON anterior y termina con el código 1 si han aumentado las rutas. Con --notify también se muestra una notificación de escritorio (solo el número). |
--fail-on=any|new|critical|high|medium | any termina con el código 1 si hay al menos una ruta; critical, high y medium lo hacen cuando hay un punto de corrección de esa prioridad o superior. |
--print-schedule=launchd|systemd | Muestra un ejemplo de configuración de ejecución periódica. No la registra. Con --interval-min se indica el intervalo en minutos. |
--format=markdown|plain|json|sarif | Elige el formato de la salida estándar. Con json o sarif, solo esos datos van a la salida estándar, y el avance y las notas van a la salida de error. A la salida estándar solo puede ir un tipo de datos, y no se puede combinar con --what-if-*. --json-out=- y --sarif-out=- también escriben en la salida estándar. |
--sarif-out=<file> | Guarda el resultado en formato SARIF 2.1.0. La prioridad de cada punto de corrección se traduce así: crítica y alta pasan a error, media a warning y baja a note. |
--export-roamswitch=<file> | Escribe un archivo de reglas para el Runtime Guard de eBPF (Falco) de RoamSwitch Server. Todas las reglas tienen la prioridad WARNING. Revise el contenido y coloque usted mismo el archivo en /etc/falco/rules.d/. No aplica las reglas. |
--check-agent-users | Analiza de una sola vez todas las cuentas registradas en agent_users en la configuración de RoamSwitch Server, cada una como punto de partida. El archivo de configuración normalmente solo lo puede leer root, así que ejecute el comando con sudo. No se puede combinar con --baseline ni --what-if-*. |
--lang=<lang> | Elige el idioma de la salida: ja, en, ko, zh-Hans, zh-Hant, de, fr, es, it o pt. Si no se indica, el idioma se decide primero por la variable de entorno PATHSCOPE_LANG y después por el idioma del sistema; para un idioma no admitido se usa inglés. |
--plain | Muestra la presentación anterior en texto sencillo en lugar de Markdown. Las suposiciones del análisis se envían entonces a la salida de error en lugar de incluirse en el resultado. |
--help / --version | --help (-h) muestra la descripción de todas las opciones, los códigos de salida y ejemplos. --version (-V) muestra la versión. |
La salida es Markdown, en el orden tabla de resumen, rutas, puntos de contramedida, ámbito de recopilación y supuestos del análisis, y se puede pegar tal cual en notas o tickets. Si cambia algo con --what-if-*, a continuación aparece el cambio respecto a la ejecución anterior con --baseline. Para la forma de texto anterior, añada --plain.
El código de salida es 0 si todo va bien, 1 cuando se cumple una condición de --fail-on y 2 si hay un error de uso o de entrada/salida. Al ejecutarlo como root, también recopila directamente los procesos en escucha de root. Los resultados de lectura guardados con el asistente LLM también se incorporan al análisis del comando.
Si no se puede leer el archivo de referencia, o si el SO, el punto de partida o el terminal son distintos y no se pueden comparar, el código de salida es 2. Con --notify, se notifica «La comprobación periódica de PathScope no está funcionando: motivo».
La herramienta MCP get_privilege_escalation_paths de RoamSwitch para Linux ejecuta el pathscope instalado con argumentos fijos (--lang=en --start=nombre-de-usuario --format=json) y lee el resultado. Devuelve el número de rutas y sus pasos, los puntos de corrección de prioridad crítica o alta y las áreas que no se pudieron comprobar. No devuelve comandos de corrección ni los ejecuta nunca. Aunque no se encuentre ninguna ruta, eso no significa que el equipo sea seguro si no se ejecutó como root o si hubo áreas sin comprobar.
7. Dónde se guardan los datos y actualizaciones
| Elemento | Ubicación |
|---|---|
| Historial de resultados del análisis | En Mac, ~/Library/Application Support/net.lafine.pathscope/history.sqlite3; en Linux, ~/.local/share/net.lafine.pathscope/history.sqlite3 |
| Configuración del LLM | ~/.config/pathscope/settings.json (se guarda con permisos que solo le permiten a usted leerlo y escribirlo) |
| Contenido guardado por el asistente LLM | ~/.local/share/pathscope/facts.json |
| La «referencia» de la comprobación periódica | ~/.local/share/pathscope/baseline.json |
El historial se puede borrar con «Eliminar todo» en la pantalla del historial. Los resultados del análisis contienen información sensible sobre la configuración de este equipo (nombres de usuario, rutas de archivos, permisos), así que limite dónde se guardan y con quién se comparten. Para usar un comando que no está en la lista de LLM, añádalo a mano en profiles del archivo de configuración. No se puede cambiar desde la ventana.
Actualizar la aplicación
PathScope en Mac se actualiza por su cuenta, aparte de RoamSwitch. Solo se conecta a lafine.net cuando pulsa «Buscar actualizaciones», para obtener la información de la última versión (no se envía información sobre este equipo ni sobre los resultados del análisis). Si hay una versión nueva, pulse «Instalar v○○» y, al terminar, «Reiniciar para aplicar». La actualización descargada se verifica por firma y solo se sustituye si se confirma que no ha sido manipulada.
PathScope en Linux está incluido en el paquete de RoamSwitch, así que se actualiza al actualizar ese paquete. La pestaña «Actualización» también lo indica.
Los datos que se usan en el análisis, como los de vulnerabilidades conocidas, vienen incluidos en la aplicación. Lo que se descubra después no se comprueba hasta que actualice PathScope. Cuando los datos incluidos se han quedado antiguos, el resultado del análisis lo indica.
8. Lo que no hace
- No cambia ajustes ni archivos y no ejecuta correcciones automáticamente. Se limita a mostrar las correcciones sugeridas.
- «No se encontraron rutas» es un resultado dentro del alcance que se pudo recopilar. No es una prueba de seguridad.
- No examina las vulnerabilidades de forma exhaustiva. Solo mira las vulnerabilidades conocidas que permiten a un usuario normal convertirse en root, y de ellas únicamente las que se han explotado en ataques reales (KEV de la CISA), las que se explotan con facilidad (EPSS de FIRST alto) y las que tienen un módulo de ataque público.
- «¿Y si corrijo este?» solo se puede usar con el resultado de un análisis recién hecho, no con uno abierto desde el historial.
9. Si algo no funciona
| Síntoma | Qué hacer |
|---|---|
| En Mac, «Datos de ajustes de privacidad (TCC.db)» aparece entre las áreas no comprobadas | En la pestaña «Permisos» de «Ajustes», pulse «Abrir los ajustes de Acceso total al disco», active PathScope en Ajustes del Sistema, reinicie PathScope y vuelva a analizar. Los demás análisis funcionan aunque no lo permita. |
| Aparece «No se puede usar el LLM» o no se puede guardar | Actívelo en «Integración con LLM» dentro de «Ajustes» y elija el LLM que se usará. Si la lista indica «No encontrado», instale el comando. Con opencode, codex o agy también hace falta marcar la casilla de confirmación. |
| Un LLM se detiene con «Tiempo de espera agotado» | En la lista de «Integración con LLM» dentro de «Ajustes», aumente el «Tiempo de espera (segundos)» de ese LLM (de 1 a 900) y guarde. |
| «¿Y si corrijo este?» no se puede usar | No se puede usar con un resultado abierto desde el historial. Pulse «Analizar» de nuevo y úselo después. |
| No se puede usar la actualización dentro de la aplicación | Si lo instaló en Linux desde un paquete de RoamSwitch, actualícelo actualizando el paquete. Si no lo instaló desde un paquete (.deb, .rpm o AppImage), la actualización dentro de la aplicación no se puede usar, así que reinstale el paquete distribuido. |