Cuadrante Digital S.A.S. y la Dirección de Servicios Compartidos son entidades ficticias. No existen: se crearon como escenario para el curso Seguridad en el software del programa de Ingeniería de Sistemas de la Universidad Tecnológica de Bolívar.
Este repositorio contiene una aplicación con fallas de seguridad deliberadas, usada como caso de estudio para practicar la revisión de seguridad previa a un despliegue. Los datos, las personas, los casos y las credenciales son inventados.
No la despliegue ni la exponga en ninguna red. No la use como base para un sistema real ni copie su código a uno: varias de sus decisiones de diseño son incorrectas a propósito.
A partir de aquí, el documento está escrito en la voz del equipo proveedor ficticio, que es parte del ejercicio.
Plataforma de recepción y triaje de solicitudes de la Dirección de Servicios Compartidos (DSC), con asistente automatizado para apoyar a los analistas en la revisión y el resumen de casos.
Versión de este paquete: 2.4.0-rc1 (candidata a producción). Desarrollada por Cuadrante Digital S.A.S. — equipo de plataforma.
Este paquete se entrega para revisión técnica previa al despliegue. Antes de ejecutarlo lea
ENTREGA.mdyENCARGO-DE-REVISION.md.
La versión candidata corresponde a la etiqueta v2.4.0-rc1 de este
repositorio.
git clone --branch v2.4.0-rc1 --depth 1 https://github.com/ISCOUTB/tramitia-app.git
O el archivo comprimido de la etiqueta, si prefiere no usar git:
https://github.com/ISCOUTB/tramitia-app/archive/refs/tags/v2.4.0-rc1.zip
Las dos formas dan el mismo contenido. Trabaje sobre una copia y no modifique el paquete original de la entrega.
Cada analista radica solicitudes en un área temática, les asigna prioridad y las mantiene actualizadas. La coordinación consolida el listado completo para el comité semanal.
Sobre esa base, el asistente responde consultas en lenguaje natural
(«resume las solicitudes pendientes», «consulta la guía de clasificación
vigente»). No responde de memoria: decide qué herramienta usar, la plataforma la
ejecuta, el resultado vuelve al contexto y el ciclo se repite hasta el tope de
pasos configurado. Hay tres herramientas: listar_solicitudes, priorizar y
consultar_referencia.
- Python 3.11 o superior
- Flask 3.1 (única dependencia)
No hay servicios externos: la base es SQLite en archivo y el cliente de modelo que se incluye es local. Funciona igual en macOS, Linux y Windows; la integración continua corre la suite en Linux y el equipo desarrolla en Windows y en macOS.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
python run.pyEn macOS, si python3 no está disponible: brew install python@3.12, o el
instalador de https://www.python.org/downloads/.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env
python run.pySi PowerShell rechaza el script de activación, habilite la política para la
sesión actual: Set-ExecutionPolicy -Scope Process RemoteSigned.
La plataforma queda en http://127.0.0.1:5050/. Sin credenciales:
curl http://127.0.0.1:5050/health # macOS y LinuxInvoke-RestMethod http://127.0.0.1:5050/health # WindowsDevuelve estado, versión y cliente de modelo activo.
run.py ocupa la terminal. Abra una segunda para lanzar peticiones, o
detenga el servicio con Ctrl+C antes de cambiar la configuración: las
variables de entorno se leen al arrancar.
Idéntico en los tres sistemas:
docker compose build
docker compose up -d
En macOS requiere Docker Desktop o Colima con el motor en marcha.
El conector con el directorio institucional (LDAP) está pendiente para 2.5.0, así que el ambiente resuelve las credenciales contra una tabla local. Personas y casos son ficticios.
| Usuario | Contraseña | Rol |
|---|---|---|
ana.vargas |
Tramitia2024 |
analista |
bruno.mejia |
bruno123 |
analista |
carla.osorio |
Tramitia2024 |
coordinador |
Autenticación HTTP Basic en todo /api. El detalle de cuerpos y respuestas está
en docs/API.md.
| Método y ruta | Descripción |
|---|---|
GET / |
Panel web de solicitudes y asistente |
GET /health |
Estado y versión |
GET /api/solicitudes |
Listado visible para la identidad actual |
POST /api/solicitudes |
Radica una solicitud |
GET /api/solicitudes/<id> |
Detalle |
PATCH /api/solicitudes/<id> |
Actualiza resumen y prioridad |
GET /api/asistente/herramientas |
Catálogo de herramientas y topes vigentes |
POST /api/asistente/ejecutar |
Ejecuta el asistente sobre una tarea |
POST /api/asistente/herramientas/priorizar |
Invocación directa, para el tablero del comité |
GET /api/admin/auditoria |
Últimos eventos registrados |
En bruno/ va la coleccion de Bruno con
los nueve endpoints, el caso valido de cada uno y los casos de error que declara
el contrato. Son archivos de texto versionados junto al codigo, asi que la
coleccion no se desincroniza de la API.
Desde la aplicacion: Open Collection y seleccione la carpeta bruno. Elija
el ambiente Local antes de lanzar la primera peticion.
Desde la linea de comandos, con el CLI:
npm install -g @usebruno/cli
cd bruno
bru run --env Local -r
Las credenciales de las tres cuentas y la direccion del servicio viven en
bruno/environments/Local.bru, no en cada peticion. Cada peticion trae
aserciones sobre el codigo de respuesta y sobre los campos que el contrato
promete: si alguna falla, el servicio no se comporta como su documentacion.
Con el servicio recien levantado, la coleccion completa pasa: 18 peticiones y 24 aserciones.
POST /api/asistente/ejecutar recibe tarea y opcionalmente modelo y
semilla. Devuelve la respuesta final y la traza completa: herramientas usadas,
argumentos, contexto que recibió el modelo en cada paso, URLs consultadas,
identidad efectiva y consumo. La traza fue un pedido explícito de soporte para
poder explicar a un analista por qué el asistente respondió lo que respondió.
El paquete incluye dos clientes locales, sin credenciales ni salida a internet, para que la revisión pueda hacerse sin acceso al proveedor:
local— determinista. Es el que usa la suite de pruebas: con la misma entrada produce siempre la misma salida.muestreado— con variabilidad, como el modelo del proveedor. Aceptasemillapara reproducir una corrida concreta.
El cliente del proveedor se habilita en el despliegue apuntando
TRAMITIA_MODELO al nombre correspondiente; ver
docs/PENDIENTES.md.
Todas las variables, con sus valores por defecto, están documentadas en
.env.example y en docs/OPERACION.md.
Mismo comando en los tres sistemas, con el entorno virtual activado:
python -m unittest discover -s tests -t tests
Sin activar el entorno, en macOS y Linux: .venv/bin/python -m unittest discover -s tests -t tests. En Windows: .venv\Scripts\python.exe -m unittest discover -s tests -t tests.
35 pruebas, alrededor de 5 segundos. Cubren la API de solicitudes, la validación del cuerpo, el bucle del asistente, los topes de consumo, el catálogo de herramientas, el panel web y el registro de auditoría. La suite pasa completa en esta versión.
.github/workflows/ci.yml corre en cada push y en cada pull request contra
main:
| Trabajo | Qué hace |
|---|---|
pruebas |
Instala dependencias y corre la suite en Python 3.11 y 3.12 |
imagen |
Construye la imagen de contenedor, la levanta y comprueba /health |
El pipeline está en verde en la etiqueta v2.4.0-rc1, que es la que se
entrega.
Lo que el equipo de plataforma afirma sobre esta versión. Están numeradas porque
el encargo de revisión pide un veredicto por cada una
(ENCARGO-DE-REVISION.md).
- C-1 Toda la API exige autenticación; no hay endpoints anónimos salvo
/health. - C-2 La validación del cuerpo se hace en el servidor contra listas de valores permitidos, no solo en el portal.
- C-3 El límite de 180 caracteres del resumen evita que alguien inserte en el campo contenido con marcado o con instrucciones.
- C-4 Un analista solo puede ver y modificar sus propias solicitudes; la coordinación ve todas.
- C-5 Las instrucciones del asistente le prohíben expresamente revelar la política interna de escalamiento.
- C-6 El asistente no puede ejecutar herramientas privilegiadas:
priorizarexige rol coordinador. - C-7 La herramienta
consultar_referenciasolo resuelve documentos del catálogo de normativa de la DSC. - C-8 Toda decisión de acceso y toda invocación de herramienta queda registrada en la auditoría con la identidad que la ejecutó.
- C-9 El asistente tiene topes de consumo: pasos por ejecución, longitud de la tarea e invocaciones por usuario.
tramitia/
__init__.py factory de la aplicacion y /health
api.py API de solicitudes
admin.py consulta de auditoria
ui.py panel web
templates/
panel.html plantilla unica, sin recursos externos
auth.py autenticacion y cuenta tecnica
audit.py registro append-only
db.py SQLite y datos de arranque
asistente/
api.py endpoints del asistente
loop.py bucle de herramientas e instrucciones del sistema
tools.py listar_solicitudes, priorizar, consultar_referencia
modelo/
base.py contrato del cliente de modelo
local.py cliente determinista
muestreado.py cliente con variabilidad
_heuristica.py apoyo interno de los clientes locales
tests/ suite de la iteracion
docs/ arquitectura, API, operacion, decisiones y pendientes
bruno/ coleccion de la API para pruebas manuales
.github/
workflows/ci.yml pruebas y construccion de la imagen
ISSUE_TEMPLATE/ ficha de hallazgo de revision
PULL_REQUEST_TEMPLATE.md
CODEOWNERS
| Archivo | Contenido |
|---|---|
ENTREGA.md |
Acta de entrega: qué se entrega, estado, advertencias y cronograma |
ENCARGO-DE-REVISION.md |
Encargo de la revisión previa al despliegue |
CHANGELOG.md |
Cambios por versión |
SECURITY.md |
Canal y reglas para reportar hallazgos |
LICENSE |
Aviso de uso |
docs/ARQUITECTURA.md |
Componentes, flujos y fronteras de confianza |
docs/API.md |
Referencia de endpoints |
bruno/ |
Coleccion de la API para Bruno |
docs/OPERACION.md |
Variables, despliegue, registros y respaldo |
docs/DECISIONES.md |
Registro de decisiones de diseño (ADR) |
docs/PENDIENTES.md |
Backlog y deuda técnica al cierre de la iteración |
Equipo de plataforma, Cuadrante Digital S.A.S. — plataforma@cuadrantedigital.example