Skip to content
Back to search

census

Census: instant file index for Windows. Reads the NTFS MFT at ~543k nodes/s, speaks the QUERY2W IPC that SortEverything/WizEverything already use, ships an MCP server, a C.wcat snapshot and natural-language search via Groq. A homage to Everything.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/luciomerlo--census/badge.svg)](/listings/luciomerlo--census)

HTML

<a href="/listings/luciomerlo--census"><img src="/api/listings/luciomerlo--census/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines
  1. # Census
  2. <img src="assets/icon.svg" width="128" align="right" alt="Census">
  3. Indexador de archivos para Windows: lee la MFT del volumen NTFS en bloque, una sola vez,
  4. y contesta consultas sobre millones de archivos en milisegundos. Expuesto con una API
  5. mínima pensada para que otras apps (SortEverything, WizEverything) lo usen como base de
  6. datos, con un servidor MCP para que lo use una IA y con una ventana propia.
  7. Un censo enumera a todos los habitantes de un territorio; Census enumera a todos los
  8. archivos de tus unidades, y responde antes de que termines de escribir.
  9. ## Homenaje
  10. Este proyecto es un homenaje a [Everything](https://www.voidtools.com/) (voidtools), el
  11. programa que demostró que un índice completo del disco puede responder al instante.
  12. **Everything es el programa que más recomendé en mi vida.** No hay exageración: durante
  13. años, cada vez que alguien dijo "no encuentro un archivo", la respuesta fue instalar
  14. Everything. Census existe porque esa idea —un índice que contiene todo— merece una API
  15. que otras apps puedan usar como base de datos.
  16. - **El icono**: una lupa ámbar con un índice de filas dentro, en guiño a su lupa
  17. (`assets/icon.svg`, `assets/icon.ico` con 16/32/48 en DIB y 256 en PNG). No es su icono ni está
  18. extraído de su binario.
  19. - **El nombre**: homenajea la idea, no la marca — la de un índice que contiene *todo*.
  20. - **Lo que no hacemos**: no usamos su nombre como nombre propio, ni su logo, ni su
  21. formato de base, ni su binario. La referencia a Everything es descriptiva y a título
  22. de crédito.
  23. No hay relación con voidtools, ni patrocinio, ni afiliación.
  24. ## Capturas
  25. | Oscuro | Claro | Contraste |
  26. |---|---|---|
  27. | ![](docs/gui-dark.png) | ![](docs/gui-light.png) | ![](docs/gui-contrast.png) |
  28. Tres temas (`dark`, `light`, `contrast`) con las mismas claves que WizEverything, y la
  29. tipografía de WizEverything: **Segoe UI** como principal y **Segoe UI Symbol** de
  30. respaldo, leídas de `%WINDIR%\Fonts` (no se empaqueta ninguna fuente). Los tres pasan un
  31. test de contraste WCAG: texto ≥ 7:1 y texto secundario ≥ 4.5:1 sobre el fondo de su tema.
  32. ## Base
  33. No se escribe desde cero: se apoya en trabajo abierto ya existente.
  34. | Base | Licencia | Qué se toma |
  35. |---|---|---|
  36. | [`omerbenamram/mft`](https://github.com/omerbenamram/mft) | MIT | Parseo de registros `$FILE`: fixups (USA), `$STANDARD_INFORMATION`, `$FILE_NAME`, `$DATA`, extensiones y `$ATTRIBUTE_LIST` (0.10, que además trae `jiff` para las fechas) |
  37. | [`omerbenamram/ntfs`](https://github.com/omerbenamram/ntfs) | MIT | Lectura de bajo nivel del volumen y de los *data runs* de la MFT |
  38. | [Everything SDK](https://www.voidtools.com/support/everything/sdk/) (voidtools) | Documentación pública | Sólo el **layout del protocolo IPC** (QUERY2 / QUERY2W) para interoperar. No se usa, copia ni redistribuye código ni binarios de voidtools |
  39. Las licencias y avisos de copyright de las bases se conservan en `THIRD-PARTY.md`.
  40. Cambios de cada versión en [CHANGELOG.md](CHANGELOG.md).
  41. ## Unidades: todo lo disponible, cada una con su tipo
  42. Census no pide permiso por unidad: indexa **todo lo que esté montado**, y distingue el
  43. tipo como WizTree.
  44. | Tipo | Cómo se detecta | Cómo se indexa |
  45. |---|---|---|
  46. | `fijo` / `extraíble` en NTFS | `GetDriveTypeW` | **MFT**: la vía rápida |
  47. | `fijo` en exFAT/FAT32 | `GetVolumeInformationW` | recorrido de directorios |
  48. | `red` | `DRIVE_REMOTE` | recorrido de directorios |
  49. | `nube` | etiqueta del volumen (`Google Drive`, `OneDrive`, `Dropbox`, …; Google Drive monta `cuenta@dominio - G…` sobre un FAT32 del tamaño del disco anfitrión) | recorrido de directorios |
  50. | `cd` / sin medio | `DRIVE_CDROM` / sin sistema de archivos | se saltea |
  51. Si la MFT falla (por ejemplo, sin elevación), esa unidad **no se cae**: se recorre. Y la
  52. lista de exclusión de WizEverything se respeta como punto de partida, pero la decisión
  53. final es de Census (`%APPDATA%\Census\settings.ini`, misma clave y formato
  54. `excluded_drives=C:,H:`). Por defecto no se excluye nada.
  55. ```
  56. $ census drives
  57. unidad tipo fs total libre indexa como
  58. C: fijo NTFS 237.4 GB 33.6 GB mft
  59. G: nube FAT32 237.4 GB 31.9 GB recorrido lucio@… - G…
  60. ```
  61. ## Búsqueda en lenguaje natural (Groq)
  62. Si cargás una clave de Groq, la ventana acepta preguntas en vez de sintaxis:
  63. ```
  64. census key gsk_... # se guarda cifrada con DPAPI para tu usuario de Windows
  65. census ask "¿cuáles son los archivos más grandes de este mes?"
  66. ```
  67. La lógica es la misma que la de WizEverything:
  68. - Se listan los modelos de la cuenta (`GET /models`), se descartan los que no son de chat
  69. y se ordenan por una lista de preferencia y, después, por cantidad de parámetros.
  70. - El modelo elegido responde **llamando a las herramientas de Census** (`search`,
  71. `count`, `largest`, `recent`, `stats`), hasta 8 pasos; nunca inventa números.
  72. - Si un modelo devuelve 429 o se quedó sin cuota (se lee en las cabeceras
  73. `x-ratelimit-*`), se reintenta con el siguiente. Sólo una clave inválida corta.
  74. - La clave se guarda cifrada con **DPAPI** en `%APPDATA%\Census\settings.ini`
  75. (`groq_key=…`); también se acepta `GROQ_API_KEY` del entorno.
  76. - En la ventana: botón `IA: sí/no`; la respuesta aparece con el modelo que la produjo.
  77. ## Como herramienta para una IA (MCP)
  78. `census mcp` habla MCP por stdio, así que cualquier agente puede consultar el índice como
  79. una herramienta más. No escribe nada: todo es consulta.
  80. ```json
  81. {
  82. "mcpServers": {
  83. "census": { "command": "C:\\ruta\\a\\census.exe", "args": ["mcp"] }
  84. }
  85. }
  86. ```
  87. | Herramienta | Qué hace |
  88. |---|---|
  89. | `search` | Busca con la misma sintaxis que las apps (`path:`, `file:`, `ext:`, `size:`, `dm:`, `rc:`, términos sueltos). Devuelve total + página. |
  90. | `count` | Cuántas entradas cumplen una consulta, sin traerlas. |
  91. | `largest` | Los archivos más grandes que cumplen una consulta. |
  92. | `recent` | Los modificados más recientemente. |
  93. | `stats` | Estado del índice: nodos, archivos, carpetas, de dónde salen los datos. |
  94. Si el cliente MCP no corre elevado, arrancá `census serve` como administrador: `census mcp`
  95. lo detecta por IPC y usa ese índice en vez de intentar leer la MFT.
  96. ## Qué hace
  97. - Carga inicial: abre `\\.\C:`, pide geometría con `FSCTL_GET_NTFS_VOLUME_DATA`, parsea
  98. los *data runs* de `$DATA` del registro 0 y lee la MFT en bloques, en paralelo.
  99. - Índice en RAM en arrays planos (~48 B por nodo, nombres en una arena UTF-16).
  100. - Snapshot propio en `%LOCALAPPDATA%\Census\C.wcat`: cabecera de 89 B, versión, raíces,
  101. nodos y arena, con checksum FNV-1a. Se reusa si tiene menos de 30 s (`--max-age`) y
  102. cubre las mismas unidades; `--rebuild` obliga a releer la MFT.
  103. - Consultas: `""`, `path:"X"`, `file:`, `folder:`, `dm:`, `rc:>=`, `ext:`, `size:` y
  104. términos por subcadena; orden por nombre y paginación por `offset`/`max`.
  105. - Interoperación: servidor IPC `QUERY2W` (clase `CENSUS_IPC`) y cliente que habla el
  106. mismo protocolo, byte a byte.
  107. ## Línea de comandos
  108. | Comando | Qué hace |
  109. |---|---|
  110. | `census index` | Construye el índice de todas las unidades y guarda el snapshot. |
  111. | `census query [consulta]` | Consulta el índice (`--volume C`, `--root <dir>`). |
  112. | `census drives` | Unidades, tipo, sistema de archivos y cómo se indexarían. |
  113. | `census bench` | Mide carga y consultas sobre el volumen real. |
  114. | `census serve` | Demonio IPC para las apps (requiere elevación para la MFT). |
  115. | `census mcp` | Servidor MCP por stdio. |
  116. | `census gui [--theme dark\|light\|contrast]` | Ventana. |
  117. | `census ask "<pregunta>"` | Lenguaje natural con Groq. |
  118. | `census key <clave>` | Guarda (o borra, con `--clear`) la clave de Groq cifrada. |
  119. ## Qué queda afuera a propósito
  120. `content:` y OCR · regex, comodines avanzados, `case:`, `wholeword:`, operadores
  121. booleanos · `dc:`, `da:`, `dr:`, `attrib:`, `dupe:`, `parent:`, `child:`, `sibling:`,
  122. `ancestor:`, `len:`, `depth:`, `startwith:`, `endwith:`, `type:` · metadata de medios y
  123. EXIF · historial de ejecución · bookmarks, macros y alias · bandeja, hotkey global,
  124. integración con Explorer, previews, thumbnails, iconos por archivo · columnas
  125. configurables y pestañas · FTP, comprimidos, ReFS, FAT, Linux · plugins de propiedades y
  126. columnas personalizadas · tamaño recursivo de carpetas y ADS · estructuras *fast
  127. sort/size/date* · los ~200 ajustes del `.ini` · el servidor HTTP/ETP y `es.exe` completo
  128. · los ~30 mensajes IPC y ~70 exports restantes.
  129. ## Nombres e identificadores
  130. | Elemento | Valor |
  131. |---|---|
  132. | Producto | **Census** |
  133. | Binario | `census.exe` |
  134. | Crate | `census-core` (el nombre `census` ya está tomado en crates.io) |
  135. | Base por volumen | `%LOCALAPPDATA%\Census\C.wcat` |
  136. | Clase IPC | `CENSUS_IPC` |
  137. | Servicio | `CensusIndex` |
  138. | Registro | `HKCU\Software\Census` |
  139. | Configuración | `%APPDATA%\Census\settings.ini` |
  140. ## Política de nombres
  141. Nada de Everything en el producto: ni el nombre de la app, ni la base, ni la clave de
  142. registro, ni el servicio, ni el icono.
  143. - **Base de datos: nombre propio.** Copiar el nombre de su base no da compatibilidad —
  144. ninguna app de terceros lee ese archivo — y sí aporta riesgo.
  145. - **DLL de compatibilidad: opcional y explícito.** Un binario llamado `Everything64.dll`
  146. sólo tiene sentido para apps de terceros que ya lo buscan por nombre, y como archivo
  147. suelto invita a *DLL planting*. Se ofrece como paso manual, no se instala por defecto.
  148. - **Clase de ventana: opcional.** `CENSUS_IPC` por defecto; la clase de Everything sólo
  149. en modo compatibilidad, y sólo si está libre.
  150. ## Rendimiento medido
  151. Medido con `census bench` en un equipo real (NVMe WD SN740, 15 GB de RAM), volumen `C:`
  152. con **1.868.924** registros de MFT, 1.274.814 archivos y 315.052 carpetas:
  153. | Métrica | Valor |
  154. |---|---|
  155. | Carga desde la MFT (lectura paralela) | **2.834 ms** |
  156. | Registros usados | 1.589.866 de 1.868.924 (279.958 descartados) |
  157. | Lectura | 1.826 MB ≈ **543.000 nodos/s** |
  158. | RAM del índice | 156 MB (83,6 MB son nombres) |
  159. | `file: dm:today` | 16,8 ms (35.378 resultados) |
  160. | `ext:log` | 79,4 ms (4.021) |
  161. | `file: rc:>=` última semana | 188,4 ms (307.937) |
  162. | Consulta vacía, volcado completo | 1.269 ms (1.589.857 resultados, ya ordenados) |
  163. Lo que dice ese número: el parseo no es el cuello de botella — **el disco sí**. La
  164. lectura pasó de 4.224 ms a 2.834 ms leyendo la MFT desde varios hilos; el mismo equipo
  165. debería bajar a ~1,5 s con lecturas más grandes.
  166. ## Seguridad de dependencias
  167. `tools/audit-advisories.py` revisa `Cargo.lock` contra la base de RUSTSEC:
  168. ```
  169. lock: 341 paquetes · avisos revisados: 1536
  170. 1 aviso aplicable: RUSTSEC-2026-0192 ttf-parser [unmaintained] (vía egui)
  171. ```
  172. La versión 0.1.1 sacó `lru` 0.4.3 (use-after-free), `rand_core` 0.5.1, `chrono` y
  173. `ring`/`rustls`. CI corre `rustsec/audit-check` en cada push.
  174. ## Estado
  175. Motor, protocolo IPC, snapshot, ventana con tres temas y servidor MCP funcionando y
  176. medidos: **99 tests en verde** (incluidos los de robustez y fuzz-lite) (`cargo test --workspace`), incluidos 13 de conformidad
  177. byte a byte del protocolo y 8 del formato `C.wcat`.
  178. Falta: delta por USN Journal (hoy el snapshot se reusa con una ventana de 30 s), el shim
  179. `Everything64.dll` para que SortEverything funcione sin tocarla, y ordenar por tamaño,
  180. fecha y ruta además de por nombre.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.