alloysecuregroup/phantomfsHoneypot de Windows que utiliza ProjFS para proyectar archivos señuelo que generan alertas en el Registro de Eventos y en el escritorio cuando se accede a ellos, con registro de sesiones SMB remotas para la detección de movimientos laterales.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/788/da15048d34f0c916d75fe48cdb87df4b643834ee3d20ec1c69de360d2b390d06.png" alt="PhantomFS — Fake Files. Real Security." width="420" />
</p>
<p align="center">
<strong>Archivos Falsos. Seguridad Real.</strong><br/>
Sistema de archivos honeypot virtual para Windows: atraiga a los atacantes a un directorio que parece real y luego atrápelos en el acto.
</p>
<p align="center">
<a href="https://github.com/alloysecuregroup/phantomfs/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"/></a>
<a href="https://docs.microsoft.com/en-us/windows/win32/projfs/projected-file-system"><img src="https://img.shields.io/badge/Platform-Windows%2010+-blue" alt="Platform"/></a>
<a href="https://dotnet.microsoft.com/download/dotnet-framework"><img src="https://img.shields.io/badge/.NET%20Framework-4.8-purple" alt=".NET 4.8"/></a>
<a href="https://github.com/sponsors/secdev02"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink" alt="Sponsor"/></a>
</p>
---
## ¿Qué es PhantomFS?
PhantomFS utiliza el **Sistema de Archivos Proyectado de Windows (ProjFS)** para mostrar un directorio virtual lleno de archivos señuelo convincentes: informes financieros, claves SSH, credenciales de API, hojas de cálculo de RR.HH., acuerdos de confidencialidad (NDA), que existen solo en la memoria. Nunca se escribe ningún dato en el disco hasta que un atacante (o amenaza interna) abre uno.
En el momento en que se toca un archivo, PhantomFS:
- Escribe una entrada en el **Registro de Eventos de Windows** (registro de Aplicaciones, origen `PhantomFS`)
- Dispara una **notificación Toast** en la sesión de escritorio activa
- Registra el nombre exacto del archivo, la marca de tiempo y el contexto del proceso
- Cuando se accede a través de un recurso compartido de red: captura el **nombre de usuario SMB y la dirección de origen**
Debido a que los usuarios legítimos no tienen motivo para abrir archivos que ellos no colocaron allí, cada alerta es de alta confianza. Sin ajustes, sin aprendizaje automático, sin dependencias en la nube: solo un controlador nativo de Windows y un único ejecutable.
---
## Características
| Característica | Detalles |
|---|---|
| **Señuelos de huella cero** | Los archivos se proyectan bajo demanda; nada se escribe en el disco a menos que un atacante lea un archivo |
| **Registro de Eventos de Windows** | ID de evento 1001 (lectura de archivo), 1002 (creación de marcador de posición), 1003 (iniciado), 1004 (detenido) |
| **Alertas Toast** | Notificación inmediata en el escritorio mediante Windows PowerShell; funciona incluso a través de RDP |
| **Registro de sesiones remotas** | Nombre de usuario SMB y dirección de origen capturados mediante `NetSessionEnum` cuando el PID 4 desencadena el acceso |
| **Limpieza automática** | Los archivos sintéticos hidratados se eliminan después de un retardo configurable; se revierten a virtuales en el próximo acceso |
| **Plantillas configurables** | PDF, XLSX, DOCX, JSON, CSV, PEM, texto plano; todos servidos desde plantillas XML en la configuración |
| **Enfriamiento por archivo** | Limitación configurable (predeterminado 15 s) evita inundaciones de alertas cuando una herramienta lee múltiples fragmentos |
| **Lista de archivos sintéticos** | Lista XML que se puede incorporar con nombres de archivo convincentes y tamaños en bytes realistas |
| **Ejecutable único** | `PhantomFS.exe` + `PhantomFS.exe.config`; no requiere instalador |
---
## Requisitos
- Windows 10 versión 1809 (compilación 17763) o posterior; se recomienda Windows 11
- .NET Framework 4.8
- Característica opcional **Sistema de Archivos Proyectado de Windows** habilitada (`Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS -NoRestart`)
- Privilegios de administrador para iniciar la raíz virtual
---
## Inicio Rápido
### Comandos Simples (recomendado)
1. Descargue `PhantomFS-v1.1.0-x64.zip` desde [Releases](https://github.com/AlloySecureGroup/PhantomFS/releases) y extráigalo
2. Ejecute como Administrador; habilite ProjFS: `Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS -NoRestart`
3. Ejecute `.\PhantomFS.exe --virtroot C:\PhantomFS\Virtual\Documents --syntheticonly`
4. Navegue a `C:\PhantomFS\Virtual\Documents` en el Explorador; verá los archivos señuelo
5. Abra uno; observe la notificación Toast y revise **Visor de Eventos → Registros de Windows → Aplicación**
---
## Configuración
Toda la configuración reside en `PhantomFS.exe.config`. **Todas las claves son opcionales**: omitir una clave usa el valor predeterminado que se muestra en la tabla.
Use el **PhantomFS Profile Builder** para generar diferentes perfiles de configuración según sus escenarios de implementación:
- https://alloysecuregroup.github.io/PhantomFS/
### Sección `<settings>`
```xml
<settings>
<enableEventLog>true</enableEventLog>
<enableToast>true</enableToast>
<alertOnOpen>true</alertOnOpen>
<alertOnRead>true</alertOnRead>
<toastCooldownSeconds>15</toastCooldownSeconds>
<verbose>false</verbose>
<virtRoot></virtRoot>
<sourceRoot></sourceRoot>
<syntheticOnly>true</syntheticOnly>
<!-- v1.1.0 — auto-cleanup -->
<autoCleanupEnabled>true</autoCleanupEnabled>
<autoCleanupDelaySeconds>300</autoCleanupDelaySeconds>
<!-- v1.1.0 — remote session logging -->
<resolveRemoteIPs>true</resolveRemoteIPs>
</settings>
```
| Clave | Valor predeterminado | Desde | Descripción |
|---|---|---|---|
| `enableEventLog` | `true` | 1.0.0 | Escribir en el registro de eventos de Aplicaciones de Windows |
| `enableToast` | `true` | 1.0.0 | Enviar notificación Toast de escritorio |
| `alertOnOpen` | `true` | 1.0.0 | Alertar cuando se crea un marcador de posición por primera vez (exploración de directorio) |
| `alertOnRead` | `true` | 1.0.0 | Alertar cuando realmente se leen los datos del archivo |
| `toastCooldownSeconds` | `15` | 1.0.0 | Segundos mínimos entre notificaciones Toast para la misma ruta de archivo |
| `verbose` | `false` | 1.0.0 | Salida adicional en la consola para diagnósticos |
| `virtRoot` | _(arg 1)_ | 1.0.0 | Sobrescribir la ruta raíz virtual desde la configuración en lugar de la línea de comandos |
| `sourceRoot` | _(vacío)_ | 1.0.0 | Directorio de respaldo real opcional; dejar vacío para modo solo sintético |
| `syntheticOnly` | `true` | 1.0.0 | Servir solo los archivos listados en `<syntheticFileList>` |
| `autoCleanupEnabled` | `true` | **1.1.0** | Eliminar archivos sintéticos materializados después del retardo y revertir a virtuales |
| `autoCleanupDelaySeconds` | `300` | **1.1.0** | Segundos después de la hidratación antes de que el archivo sea eliminado (el temporizador de limpieza se ejecuta cada 30 s) |
| `resolveRemoteIPs` | `true` | **1.1.0** | Resolver DNS el nombre de host del cliente SMB a una dirección IP; establecer en `false` si la latencia de búsqueda es inaceptable |
### Registro de Sesiones Remotas
Cuando se accede a un archivo a través de un recurso compartido SMB, PhantomFS detecta el PID 4 (el proceso Sistema de Windows / controlador SMB del kernel) como el llamador y llama automáticamente a `NetSessionEnum` para identificar al usuario remoto. La entrada del Registro de Eventos y la notificación Toast incluirán:
```
PhantomFS — Honeypot File Content Read
File : Documents\Q4_Financial_Report_2024.pdf
Process : System (PID 4)
Remote : CORP\jsmith @ DESKTOP-A1B2C3D [192.168.1.45]
```
**Requisitos para el registro remoto:**
- El servicio Server debe estar en ejecución (se inicia automáticamente cuando hay un recurso compartido activo)
- PhantomFS debe estar ejecutándose en la máquina que aloja el recurso compartido
- `resolveRemoteIPs` requiere que la máquina cliente sea resoluble a través de DNS
### Comportamiento de la Limpieza Automática
Después de que un archivo sintético se abre y se hidrata (el contenido se escribe en el disco), un temporizador en segundo plano verifica cada 30 segundos y elimina los archivos cuyo tiempo de hidratación excede `autoCleanupDelaySeconds`. El archivo eliminado vuelve a ser un marcador de posición virtual de ProjFS: el próximo acceso vuelve a desencadenar la devolución de llamada de ProjFS como si el archivo nunca hubiera sido abierto.
Los archivos que aún están abiertos cuando se dispara el temporizador de limpieza se omiten sin error y se reintentan en el siguiente ciclo de 30 segundos.
### Agregar Archivos Señuelo
Agregue entradas debajo de `<syntheticFileList>` en la configuración:
```
\Documents,true,0,1744586986
\Documents\Q4_Financial_Report_2024.pdf,false,8192,1744586986
\Documents\Employee_Salaries_2024.xlsx,false,4096,1743942586
\IT\Keys,true,0,1744586986
\IT\Keys\deploy_key.pem,false,3247,1742354986
```
### Agregar Plantillas de Contenido
```xml
<syntheticTemplates>
<template name="my_custom_file.txt"><![CDATA[
... su contenido de archivo aquí ...
]]></template>
</syntheticTemplates>
```
---
## Referencia del Registro de Eventos
Abra **Visor de Eventos → Registros de Windows → Aplicación** y filtre por origen `PhantomFS`.
| ID de Evento | Nivel | Significado |
|---|---|---|
| 1001 | Advertencia | Se leyó el contenido de un archivo señuelo (incluye usuario/IP remoto cuando corresponda) |
| 1002 | Advertencia | Se creó un marcador de posición de archivo señuelo (se exploró/stat el archivo) |
| 1003 | Información | PhantomFS iniciado: ruta raíz virtual y configuración registradas |
| 1004 | Información | PhantomFS se detuvo correctamente |
---
## CI/CD — Acciones de GitHub
PhantomFS incluye un flujo de trabajo en `.github/workflows/build.yml` que compila para **x64** y **ARM64** en paralelo, y publica una versión de GitHub Release en cada etiqueta de versión.
---
## Compilación desde el Código Fuente
```powershell
# Requiere .NET Framework 4.8 SDK o Visual Studio Build Tools
csc.exe /platform:x64 /r:System.Xml.dll /out:PhantomFS.exe src\PhantomFS.cs
```
`csc.exe` suele estar en:
```
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe
```
---
## Ideas de Implementación
- **Trampa en estación de trabajo**: ejecutar como tarea programada al iniciar sesión; cualquier movimiento lateral hacia `\\nombrehost\PhantomFS\Virtual` dispara una alerta inmediata con el nombre de usuario y la IP de origen del atacante
- **Canario en servidor de archivos**: colocar un recurso compartido `\Finance` que apunte a la raíz virtual junto al recurso compartido real de finanzas; el registro de sesión remota identifica exactamente qué cuenta examinó el cebo
- **Máquina de desarrollador**: mostrar claves falsas de AWS y SSH en `~\Documents`; los ataques internos o de la cadena de suministro activan alertas antes de la exfiltración
- **Segmento aislado (air-gapped)**: establecer `resolveRemoteIPs=false` para omitir DNS en entornos donde las consultas externas están bloqueadas; el nombre de máquina NetBIOS aún se captura
---
---
## Patrocinio
PhantomFS es gratuito, de código abierto y con licencia MIT. Si le ha ahorrado tiempo (o ha detectado un atacante real), considere patrocinar el desarrollo continuo.
**[❤ Patrocinar en GitHub](https://github.com/sponsors/secdev02)**
Los patrocinadores reciben:
- Respuestas prioritarias a incidencias
- Acceso anticipado a nuevas plantillas y funciones
- Una mención en las notas de la versión
Los patrocinadores corporativos (a partir de $500/mes) reciben un canal privado de Slack para soporte directo y solicitudes de funciones.
---
## Licencia
```
MIT License
Copyright (c) 2026 Alloy Secure
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
> **Aviso de Marca Comercial:** PhantomFS™ es una marca comercial de Alloy Secure. Todos los derechos reservados.
---
## Descargo de Responsabilidad — Uso Aceptable
PhantomFS se proporciona **únicamente para fines de seguridad defensiva lícitos**, incluida la detección de intrusiones, la investigación de amenazas y las pruebas de penetración autorizadas en sistemas que posea o para los que tenga permiso explícito por escrito para monitorear.
**Usted es el único responsable de garantizar que su uso de PhantomFS cumpla con todas las leyes locales, nacionales e internacionales aplicables**, incluidas, entre otras, las leyes sobre fraude informático, interceptación de comunicaciones, privacidad y laborales. Implementar PhantomFS en sistemas o redes sin la autorización adecuada puede ser ilegal.
Los autores y colaboradores de PhantomFS:
- **No ofrecen ninguna garantía**, explícita o implícita, sobre la idoneidad para un propósito particular
- **No aceptan ninguna responsabilidad** por daños directos, indirectos, incidentales o consecuentes que surjan del uso o mal uso de este software
- **No son responsables** por pérdida de datos, daños al sistema, responsabilidad legal o daños a terceros resultantes de la implementación de PhantomFS en cualquier entorno
**Úselo bajo su propio riesgo.** Al usar PhantomFS, reconoce que ha leído este descargo, lo comprende y acepta regirse por sus términos.
> **Aviso de Marca Comercial:** PhantomFS™ es una marca comercial de Alloy Secure. Todos los derechos reservados.
---
## Agradecimientos
Construido sobre la [API del Sistema de Archivos Proyectado de Windows](https://docs.microsoft.com/en-us/windows/win32/projfs/projected-file-system), la misma tecnología que impulsa WSL2 y OneDrive Files On-Demand.
Inspirado por mi trabajo como investigador en Thinkst 💚 `https://citation.thinkst.com/talk/94782`