# Entrada de Valkirias

Registro de visitantes para caseta de condominio. Local, sin internet, sin
salida de datos.

Corre en la laptop de la caseta y en ninguna otra parte. Apache escucha solo en
`127.0.0.1`: aunque la laptop este en la red del condominio, el registro no se
alcanza desde otra maquina. No hay nube, no hay cuenta, no hay servicio de nadie
en medio.

**No autoriza. No permite. No sanciona. No decide quien tiene razon.**
Hace constar, con hora, y deja que la acumulacion hable.

---

## Que hace

- **Captura sin friccion.** Placa, Enter, domicilio, Enter. Sin mouse.
- **Todo es un asiento.** Entrada, salida, incidente y aclaracion viven en una
  sola tabla. Nada se actualiza y nada se borra.
- **Los errores se aclaran, no se corrigen.** El asiento equivocado se queda;
  la aclaracion queda a su lado, fechada, y ambos se leen juntos.
- **Cadena de hashes.** Cada asiento encadena con el anterior. Si alguien toca
  la base por fuera del sistema, la pantalla de Integridad dice donde.
- **Dos roles.** El vigilante captura; las pantallas que exponen el patron
  completo del condominio son de administracion.
- **Datos minimos.** Placa, domicilio visitado y hora. No se guardan nombres de
  visitantes, telefonos, identificaciones ni fotografias.

## Que no hace

No emite gafetes. No abre plumas. No califica conductas. No lleva padron de
residentes. No manda nada a ningun lado.

---

## Instalar

Ubuntu 24.04. Desde la carpeta del proyecto:

    cp config.example.php config.php
    nano config.php          # poner el nombre del condominio en UNIDAD
    sudo bash linux/instalar.sh

Eso instala Apache, PHP y MariaDB del repositorio del sistema, crea la base con
su propio usuario y contrasena generada, publica el sistema en
`/var/www/valkirias`, programa el respaldo y el reporte de cierre, y deja
Firefox abriendo la caseta al iniciar sesion.

El instalador se puede volver a correr las veces que haga falta. No rehace lo
que ya esta hecho, no toca la base si ya existe, y no borra respaldos ni
reportes. Es la forma de actualizar el sistema despues de cambiar el codigo.

`config.php` es el unico archivo de configuracion. El instalador le escribe el
usuario y la contrasena de la base; lo demas —nombre de la unidad, zona horaria,
hora de corte del reporte— se ajusta a mano antes de instalar.

### Primer uso

Abrir `http://localhost/`. La primera vez, y solo la primera, sale la pantalla
de alta de usuarios: se crean el administrador y el primer vigilante con las
contrasenas que uno elija.

**No hay contrasenas por omision.** Nunca existe una clave que alguien pudiera
conocer de antemano. En cuanto existe un usuario, esa pantalla desaparece.

### Ver el diseno sin instalar nada

`vista/caseta.html` se abre con doble clic. Son las nueve pantallas en HTML
estatico con datos de ejemplo. **No se instalan**, para que nadie las confunda
con el registro real.

---

## Usuarios

Dos roles. Se administran desde **Panel**, que solo ve el administrador.

| | Vigilante | Administrador |
|---|---|---|
| Caseta (entradas y salidas) | si | si |
| Incidente | si | si |
| Libreta y aclaraciones | si | si |
| Reincidencias | — | si |
| Reporte del dia | — | si |
| Integridad | — | si |
| Panel de usuarios | — | si |

El vigilante captura y consulta su libreta. Las pantallas que exponen el patron
completo del condominio —quien visita que casa, con que frecuencia, a que
horas— son de administracion.

Los usuarios **no se borran**: se dan de baja. Un usuario de baja no puede
entrar, pero los asientos que firmo siguen diciendo su nombre. La libreta no se
reescribe nunca.

Cuando el administrador da de alta a alguien o le reinicia la contrasena, el
sistema muestra la clave **una sola vez**. Hay que anotarla en ese momento. La
persona esta obligada a cambiarla la primera vez que entre.

### Bloqueo por intentos

Mas de 10 intentos fallidos en 5 minutos y esa cuenta queda bloqueada 5
minutos. Se cuenta por usuario, no por equipo: en una sola laptop la direccion
de red es siempre la misma, y contarla dejaria a toda la caseta sin poder
registrar porque alguien tecleo mal. El administrador puede levantarlo desde
**Panel > Bloqueos en curso**.

**Panel** lleva el contador de inicios de sesion de cada usuario, su ultimo
acceso, y la bitacora de los intentos —los buenos y los malos—. Los intentos se
conservan 90 dias; el respaldo diario purga los mas viejos.

---

## Operacion diaria

El vigilante no arranca nada. Al encender la laptop y entrar a la sesion,
Firefox abre solo en la pantalla de caseta.

**Registrar una entrada.** Placa, Enter, calle y numero, Enter. Sin mouse.
Si la calle y numero no existen todavia, se dan de alta solas: `Almendros 12`,
`almendros 12` y `ALMENDROS #12` se reconocen como el mismo domicilio.

**Registrar una salida.** Boton *Salida* en el renglon correspondiente de
"Adentro ahora".

**Asentar un incidente.** Cuando a uno lo mandan a verificar un vehiculo.
Queda constancia de que fue, a que hora, a peticion de quien, y que encontro.
Las ubicaciones que ofrece son las que define el reglamento del condominio:
el sistema no inventa categorias ni califica conductas.

**Corregir un error.** No se corrige: se aclara. En Libreta, boton *Aclarar*.
El asiento equivocado se queda; la aclaracion queda a su lado con la fecha y
hora de hoy, y ambos se leen juntos.

**Terminar el turno.** *cerrar turno*, arriba a la derecha. El siguiente
vigilante entra con su propio usuario, y a partir de ahi los asientos van a su
nombre.

Para el vigilante hay una hoja aparte, pensada para imprimir y dejar pegada en
la caseta: **[MANUAL-CASETA.md](MANUAL-CASETA.md)**.

---

## Respaldo

Automatico, todos los dias a las 03:30. Escribe en `/var/backups/valkirias` y
conserva los ultimos 60. Si la laptop estaba apagada a esa hora, el respaldo se
hace en cuanto enciende.

    systemctl list-timers valkirias-respaldo.timer   # cuando toca el proximo
    sudo systemctl start valkirias-respaldo.service  # correrlo ahora
    ls -lh /var/backups/valkirias                    # ver lo que hay

**Una sola copia no es una copia.** Llevarse un `.sql` a una USB de vez en
cuando. Todo lo demas se puede reinstalar; esto no.

### Probar el respaldo

Un respaldo que nunca se restauro no es un respaldo. Se prueba sobre una base
aparte, sin tocar la de produccion. **Con `sudo mariadb`, no con las
credenciales de la aplicacion:** el usuario `valkirias` esta acotado a su propia
base y no puede crear otra.

    sudo mariadb -e "CREATE DATABASE prueba_restauracion"
    sudo mariadb prueba_restauracion < /var/backups/valkirias/valkirias_FECHA.sql
    sudo mariadb prueba_restauracion -e "SELECT COUNT(*) FROM eventos"
    sudo mariadb -e "DROP DATABASE prueba_restauracion"

Si el conteo se parece al que muestra la pantalla de Integridad, el respaldo
sirve. Conviene hacerlo una vez al mes.

### Restaurar de verdad

    sudo systemctl stop apache2
    sudo mariadb valkirias < /var/backups/valkirias/valkirias_FECHA.sql
    sudo systemctl start apache2

Despues, entrar a **Integridad** y verificar que la cadena este completa.

---

## Reporte del dia

Se escribe solo en `/var/www/valkirias/reportes/AAAA-MM-DD.html` cada vez que
alguien abre la pantalla de Reporte, y ademas todos los dias a las 23:58 por si
nadie la abrio.

Es un HTML autocontenido: se puede copiar, mover, imprimir o adjuntar sin
depender del sistema.

**Al pie del reporte va el hash de cierre del dia.** Eso importa mas de lo que
parece; ver la seccion siguiente.

---

## Integridad, y hasta donde llega

Cada asiento guarda el hash del anterior. **Integridad** recorre la cadena
completa desde el origen y recalcula. Si alguien modifico, borro o inserto algo
directamente en la base, ahi se ve en que asiento.

Lo que la cadena **si** detecta: que alguien edite la base por fuera del
sistema. Una fila cambiada a mano, un asiento borrado, uno insertado.

Lo que la cadena **no** detecta: que alguien con la contrasena de la base
regenere la cadena entera. Reescribe los asientos, recalcula todos los hashes,
y la pantalla dira "integra". La cadena por si sola no protege contra quien
administra la maquina.

**Lo unico que la ancla es sacar el hash de cierre de la laptop.** El reporte
diario lo lleva impreso al pie. Si esos reportes se imprimen y se archivan cada
dia, un hash anterior contradice cualquier cadena rehecha, y la cadena vale.
Si se quedan en el disco, es decorativa.

Imprimir y archivar el reporte no es burocracia: es lo que hace que el registro
sirva de prueba.

Y una distincion que conviene fijar: la cadena acredita que **un asiento no se
altero despues de escrito**. No acredita **quien lo escribio**.

---

## Como esta hecho

**Una sola tabla: `eventos`.** Todo es un asiento: entrada, salida, incidente,
aclaracion. Nada se actualiza y nada se borra.

- Una **salida** no modifica la entrada: es un asiento nuevo que la referencia.
- Una **correccion** no modifica el error: es una aclaracion fechada, y ambos quedan.
- Cada asiento encadena con el hash del anterior.

**El catalogo de domicilios lo construyen los vigilantes** conforme pasan los
autos. No hay padron que cargar. Se guarda siempre lo que el vigilante tecleo.

**No se guardan nombres de visitantes, telefonos, identificaciones ni
fotografias.** Solo placa, domicilio que visita y hora. El minimo para que el
registro sirva.

**Las ubicaciones del incidente las define el reglamento del condominio.** El
sistema no inventa categorias ni califica conductas: cita las que ya existen y
hace constar el hecho. La lista viene en `lib/core.php` y **hay que adaptarla al
reglamento de cada condominio** antes de instalar.

### Donde queda cada cosa

| | |
|---|---|
| Sistema en produccion | `/var/www/valkirias` |
| Reportes | `/var/www/valkirias/reportes` |
| Respaldos | `/var/backups/valkirias` |
| Contrasena de la base | `config.php` y `/etc/valkirias/respaldo.cnf` |
| Sitio de Apache | `/etc/apache2/sites-available/valkirias.conf` |
| Bitacora de Apache | `/var/log/apache2/valkirias-error.log` |

---

## Auditoria de seguridad

Antes de publicar este codigo se ejecuto una auditoria completa en local, sobre
el sistema desplegado y corriendo. No fue analisis estatico: fue **revision
manual de codigo mas simulacion de ataque real** con OWASP ZAP 2.17.0 en dos
corridas —una autenticada como administrador, con 1713 asientos escritos contra
la cadena, y otra sin sesion contra el formulario de entrada.

Resultado: **siete hallazgos, ninguno explotable de forma remota** — el sistema
escucha unicamente en `127.0.0.1`. Cinco alertas mas se verificaron una por una
y se descartaron como falsos positivos, con la prueba que las descarta escrita
al lado. La auditoria tambien documenta lo que se probo **y resistio**, para que
se pueda distinguir lo revisado-y-correcto de lo no revisado.

Los siete hallazgos estan enumerados abajo, en «Estado conocido». El reporte
completo y su paquete de evidencia se entregan por separado.

### Auditoria automatica en cada envio

| Revision | Que busca |
|---|---|
| `php -l` en 8.1, 8.3 y 8.4 | que compile en las versiones que hay en produccion |
| **PHPStan** nivel 3 | errores de tipo, metodos inexistentes, codigo inalcanzable |
| **Psalm** `--taint-analysis` | dato de `$_GET`/`$_POST` que llega a SQL o a la pagina sin escapar |
| **Semgrep** `p/php`, `p/security-audit`, `p/owasp-top-ten` | patrones conocidos de vulnerabilidad |

Los hallazgos de Semgrep se publican como alertas de seguridad del repositorio.

Para correrla en local, con las herramientas que instala el propio guion:

    sudo bash linux/auditar.sh

---

## Estado conocido al 26 de julio de 2026

Esta seccion dice lo que el sistema es hoy, no lo que quisiera ser. Quien
herede esto se entera leyendo, no por un incidente.

### Corregido y verificado con pruebas

| | Que era | Como se comprobo |
|---|---|---|
| Bloqueo por intentos | Era global por direccion de red; en una sola laptop eso dejaba fuera a toda la caseta. Ahora cuenta **por usuario** | 12 fallos bloquean a la cuenta objetivo y la otra sigue entrando |
| `reportes/*.html` | Apache los servia como archivo estatico, sin sesion. Ahora los prohibe y pasan por `ver_reporte.php`, que exige administrador | HTTP 403 sin sesion; 200 con sesion de administrador |
| Base de datos caida | Salia un error en blanco. Ahora sale una pantalla que dice que hacer | Verificado durante la auditoria |
| "Levantar bloqueos" | Borraba la bitacora entera de intentos. Ahora solo levanta el bloqueo | Revision de codigo y prueba en vivo |
| Separacion de roles | — | 25 de 25 pruebas de control de acceso, y se sostuvo durante todo el escaneo activo |
| Integridad bajo concurrencia | — | 1713 asientos escritos con 4 hilos; la cadena quedo integra de punta a punta |

### Abierto — hallazgos de la auditoria

Ninguno esta corregido. Cada uno lleva su correccion exacta en el reporte.

| # | Hallazgo | Severidad |
|---|---|---|
| 1 | `linux/instalar.sh` publica la carpeta completa en el webroot: la exclusion es lista negra, no lista blanca | Alta |
| 2 | `/server-status` de Apache expone las consultas en vivo, con placas y domicilios en la URL | Alta |
| 3 | `generar_reporte.php` es un guion de linea de comandos que Apache tambien sirve y ejecuta, sin sesion | Media |
| 4 | `panel.php`: la accion de reiniciar contrasena no reautentica ni protege la cuenta propia | Media |
| 5 | Ningun formulario lleva token anti-CSRF | Media |
| 6 | Faltan las cabeceras de seguridad; `Referrer-Policy` importa porque las URL de consulta llevan placas | Baja |
| 7 | Apache anuncia su version, y se sirven por HTTP archivos de desarrollo | Baja |

### Abierto — operativos

1. **"Adentro ahora" crece para siempre.** Todo visitante sin salida asentada se
   queda ahi permanentemente. No hay cierre de dia, y es la pantalla principal.
2. **La verificacion diaria de integridad no avisa a nadie.** Escribe al journal
   de systemd, donde nadie va a mirar.
3. **El respaldo automatico nunca se ha restaurado con exito.** El primer intento
   fallo porque el usuario `valkirias` de MariaDB solo tiene privilegios sobre su
   propia base y no puede crear la de prueba. Hay que correrlo con `sudo mariadb`.
4. **La sesion dura 7 dias de inactividad para los dos roles.** Es un `php_value`
   del host virtual; por esa via no se puede separar administrador de vigilante.

### Abierto — probatorio y legal

5. **El sistema asienta escrituras, no lecturas.** Quien consulto el patron de
   visitas de una casa, y cuando, no queda registrado en ningun lado.
6. **No hay constancia de la fuente de tiempo.** La hora va sellada dentro del
   hash; sin internet la caseta deriva y nada lo registra.
7. **Proteccion de datos personales.** Una placa es dato personal identificable.
   El sistema guarda placa, domicilio y hora de forma indefinida, y con eso se
   reconstruye quien visita que casa. Bajo la LFPDPPP el condominio es
   responsable del tratamiento, y el derecho de cancelacion choca de frente con
   "nada se borra jamas". No se resuelve con una herramienta.

### No auditado

- El sistema operativo y el servidor de base de datos. Solo se audito la aplicacion.
- El analisis de contaminacion de Psalm y Semgrep. **Sin el, la revision estatica
  del codigo esta incompleta.** Se desbloquean con `sudo bash linux/auditar.sh`.
- El cumplimiento de la LFPDPPP.

---

## Sobre este repositorio

**Este no es el arbol que se audito: es obra derivada de el.** Se hace constar
para que las referencias del reporte de auditoria puedan cotejarse sin sorpresas.

El repositorio tiene 51 archivos de codigo y documentacion. **29 son byte a byte
identicos** al arbol auditado, 20 son derivados y 2 se agregaron. Los 20
derivados son estos:

- **16 archivos** donde se sustituyo lo que era propio de un condominio
  concreto por datos de ejemplo y por referencias genericas:
  las nueve maquetas de `vista/`, mas `index.php`, `incidente.php`,
  `lib/core.php`, `lib/reporte_html.php`, `reincidencias.php`,
  `MANUAL-CASETA.md` y este archivo.
  Se sustituyo el nombre real de la unidad habitacional, nueve placas de muestra,
  cuatro nombres de calle y dos nombres de vigilante.

  En los tres archivos `.php` la sustitucion afecta **unicamente a comentarios y
  a atributos `placeholder`**: no cambia una sola instruccion ejecutable, y el
  numero de lineas es identico al del arbol auditado.

  Ademas se generalizaron las referencias al reglamento del condominio: donde
  el codigo citaba un articulo concreto de un reglamento concreto, ahora dice
  «el reglamento del condominio», y `lib/core.php` advierte que la lista de
  ubicaciones debe adaptarse en cada unidad.

  Este README se reescribio: reune lo que antes estaba repartido entre dos
  archivos y corrige una lista de pendientes que declaraba como abiertos
  cuatro defectos ya corregidos.

- **4 correcciones de empaquetado**, que impedian que el repositorio funcionara
  al clonarse. `phpstan.neon` cargaba un `config.php` que no existe en un clon,
  y la revision automatica fallaba en el primer envio; ahora carga
  `config.example.php`. `psalm.xml` abortaba por un directorio `vendor`
  inexistente. A `.gitignore` se le agregaron entradas que faltaban.
  `css/main.css` era el unico archivo del arbol con fines de linea de Windows;
  se normalizo, para que quien clone no vea diferencias espurias.

## Lo que no se publica

Se retiraron cinco cosas. Cuatro archivos: `config.php`, que lleva el nombre de
la unidad y la contrasena de la base; dos archivos de trabajo interno; y
`LEEME.md`, cuyo contenido quedo integrado en este README para no tener dos
archivos que digan lo mismo.

Y la carpeta `historico/`, que guardaba lo que se elimino antes de que el
proyecto tuviera control de versiones: el guion de turno anterior a la
autenticacion y los dos `.bat` de la etapa Windows. No le sirve a nadie que
clone, y `historico/turno.php` es codigo retirado que el propio reporte de
auditoria documenta como **ejecutable y accesible** una vez instalado. Publicarla
le recrearia ese hallazgo a cualquiera que replique el sistema.

Se agregaron `reportes/.gitkeep` y `respaldos/.gitkeep`, para que existan tras un
clon las dos carpetas que el sistema necesita.

**Ninguno de los siete hallazgos fue corregido.** La logica, el esquema de la
base, la cadena de hashes y el control de acceso son exactamente los que se
auditaron.

---

## Licencia

**GNU Affero General Public License v3.0 o posterior** — [LICENSE](LICENSE).

Se eligio AGPL y no GPL a proposito. El copyleft de la GPL se dispara al
*distribuir* el programa; quien toma un sistema web, lo modifica y lo pone a
correr en un servidor nunca distribuye nada, y no queda obligado a devolver sus
cambios. La AGPL cierra ese hueco: quien lo corra para otros por red tiene que
ofrecer su codigo modificado.

Es software para vigilar un porton. Que cualquiera pueda leer exactamente que
hace con los datos de quien pasa no es un detalle de licenciamiento.

Copyright (C) 2026 Jocsan &lt;jocsan@duriva.com&gt;
