Redacción de PHI

El CLI tecsas3-cli aplica redacción de PHI (Protected Health Information) en logs stderr y en cualquier payload que pueda filtrar a un canal no seguro. La capa de redacción vive en cli/src/tecsas3_cli/redaction.py y se activa por defecto — la única manera de desactivarla es combinar --debug con --redact-phi=false, uso estrictamente reservado a depuración local. Los criterios de redacción se alinean con HIPAA (Safe Harbor), GDPR (Art. 4 y 32) y la Ley 1581 de 2012 de Colombia (Habeas Data) para datos de salud.

Campos redactados

La redacción opera en dos niveles: por clave (reemplaza el valor cuando la clave es sensible) y por patrón (reemplaza substrings en strings libres como logs).

Redacción por clave (`PHI_KEYS`)

Cualquier dict (incluso anidado) cuyas claves coincidan con la siguiente lista tendrá su valor reemplazado por [REDACTED]. La comparación es case-insensitive.

Categoría	Claves
Identificadores directos	`cedula`, `numero_documento`, `documento`, `telefono`, `correo`, `email`, `direccion`, `nombres`, `primer_apellido`, `segundo_apellido`, `nacimiento`, `fecha_nacimiento`
Clínicos	`diagnostico`, `valoracion_medica`, `cie10_description`, `chief_complaint`, `care_plan`, `tratamiento`, `motivo_consulta`
Sensibles adicionales	`image`, `image_url`

Redacción por patrón (`redact_blob`)

Para strings libres (logs, trazas, mensajes de error), tres regex buscan y reemplazan por [REDACTED]:

Patrón	Regex	Ejemplo
Cédulas / documentos (6–12 dígitos)	`\b\d{6,12}\b`	`52123456` → `[REDACTED]`
Emails	`\b[\w.+-]+@[\w-]+\.[\w.-]+\b`	`ana@eps.example` → `[REDACTED]`
Teléfonos	`\+?\d[\d\s\-]{7,}`	`+57 300 123 4567` → `[REDACTED]`

Los logs que el CLI emite a stderr (método, URL, status, hasta 500 bytes del body de respuesta) se redactan siempre, incluso sin --debug. La redacción por clave y por patrón se aplica en cadena. Si en algún caso ves un valor crudo en stderr, repórtalo como incidente de seguridad con un request_id reproducible.

Configuración y flags

Setting	Default	Cómo cambiarla
`redact_phi`	`True`	`Settings.redact_phi` (pydantic-settings) o flag `--redact-phi=false`.
`debug`	`False`	`--debug` o env `TECSAS3_DEBUG=1`. Activa el log stderr con redacción aplicada.

El log stderr sólo se emite cuando debug=True. Aun así, el body se redacta con redact_blob(...) antes de imprimirse:

# cli/src/tecsas3_cli/http_client.py
def _log(self, method: str, url: str, status: int | str, body: str = "") -> None:
    if not self.settings.debug:
        return
    safe = redact_blob(body)[:500] if body else ""
    print(f"[tecsas3] {method} {url} -> {status} {safe}", file=sys.stderr)

API de redacción

Tres funciones públicas en tecsas3_cli.redaction:

from tecsas3_cli.redaction import redact_value, redact_dict, redact_blob

# 1. Redacción de un valor escalar por clave.
>>> redact_value("nombres", "Ana Pérez")
'[REDACTED]'
>>> redact_value("id_paciente", 2909)
2909

# 2. Redacción recursiva de un dict (incluye listas y sub-dicts).
>>> redact_dict({"nombres": "Ana", "cedula": "123", "id": 2909})
{'nombres': '[REDACTED]', 'cedula': '[REDACTED]', 'id': 2909}
>>> redact_dict({
...     "results": [
...         {"nombres": "Ana", "telefono": "+57 300 123 4567"},
...         {"nombres": "Juan", "telefono": "+57 301 999 8888"},
...     ]
... })
{'results': [
    {'nombres': '[REDACTED]', 'telefono': '[REDACTED]'},
    {'nombres': '[REDACTED]', 'telefono': '[REDACTED]'},
]}

# 3. Redacción por patrón en strings libres.
>>> redact_blob("Paciente cedula 52123456 email ana@eps.example tel +57 300 123 4567")
'Paciente cedula [REDACTED] email [REDACTED] tel [REDACTED]'

redact_value sólo aplica a claves listadas en PHI_KEYS y nunca toca valores None o "" (no hay información que filtrar).

Desactivación explícita (sólo depuración)

# Producción / CI: redacción activa. No requiere flags.
tecsas3 --json --no-input paciente list

# Depuración local: expone el body crudo en stderr.
# ⚠️ NUNCA en producción: filtra PHI a la terminal y al historial de shell.
tecsas3 --debug --redact-phi=false paciente get 2909 2> /tmp/tecsas3.log

--redact-phi=false debe combinarse únicamente con --debug en entornos de desarrollo aislados. Su uso en producción, staging o pipelines compartidos es una violación de las políticas de protección de datos y debe activar alertas en el SIEM.

Buenas prácticas

No desactivar la redacción para “ver mejor el error” — pedir al backend un request_id y consultar los logs del servidor, que tienen redacción equivalente.
No loguear redact_dict(...) a archivos compartidos — la salida ya está redactada, pero los archivos pueden tener permisos laxos.
En CI, fija TECSAS3_DEBUG=0 y, si necesitas trazabilidad, exporta los logs a un sistema central con redacción adicional en el colector.
Audita periódicamente los logs locales con un grep por patrones conocidos (\b\d{6,12}\b, @) para detectar regresiones.

Verificación rápida

# Confirmar que la redacción está activa.
tecsas3 --json --no-input --debug paciente get 2909 2>&1 | grep -E 'cedula|@'
# (no debe imprimir valores crudos)

# Forzar la salida cruda sólo en dev aislado.
tecsas3 --json --no-input --debug --redact-phi=false paciente get 2909 2>&1 | head

Troubleshooting

Sigo viendo PHI en `stderr`

Si la regex no capturó el patrón (por ejemplo, una cédula con guiones tipo 52-123-456), reporta el caso. La capa de redacción se actualiza periódicamente. Mientras tanto, no publiques el log.

# Detección rápida.
grep -E '\b\d{6,12}\b|@[\w-]+\.[\w.-]+' /tmp/tecsas3.log

`--redact-phi=false` no surte efecto

La desactivación sólo aplica a la impresión en stderr del log de debug. La salida por stdout (--json, --format yaml/csv) sigue pasando por la capa de redacción cuando el recurso la aplica. Verifica con:

tecsas3 --debug --redact-phi=false --json --no-input paciente get 2909
# stdout: JSON estructurado (puede tener PHI si el recurso lo emite crudo)
# stderr: log con PHI visible (porque --debug + --redact-phi=false)

Una clave nueva debería ser PHI

Si añades un campo nuevo a un recurso y quieres que se redacte, agrégalo a PHI_KEYS en cli/src/tecsas3_cli/redaction.py. La lista está versionada en git.

# cli/src/tecsas3_cli/redaction.py
PHI_KEYS = {
    # ...entradas existentes...
    "token_firma",
    "firma_digital",
}

Después de modificar, reinstala el paquete (pip install -e .) y verifica:

from tecsas3_cli.redaction import redact_dict
redact_dict({"token_firma": "abc", "metadata": "x"})
# {'token_firma': '[REDACTED]', 'metadata': 'x'}

Logs centralizados en ELK / Loki

Si reenvías stderr a un colector, aplica una segunda capa de redacción allí también (Logstash filter, Promtail pipeline stage). El CLI no garantiza la redacción en la cadena de transporte.

Auditoría periódica

# Buscar posibles fugas en logs locales.
grep -rEn '\b\d{6,12}\b|@[\w-]+\.[\w.-]+' ~/.tecsas3/ 2>/dev/null

# Buscar en logs de CI.
grep -rEn '\b\d{6,12}\b' /var/log/tecsas3/ 2>/dev/null

Patrones de uso

Redacción en recursos propios

Si estás escribiendo un recurso nuevo en cli/src/tecsas3_cli/resources/, llama a redact_dict antes de pasar el payload al Output:

from tecsas3_cli.redaction import redact_dict

def list(ctx: typer.Context) -> None:
    rt: Runtime = ctx.obj
    resp = rt.client.get("/mi/recurso/")
    rt.out.emit(redact_dict(resp.json()))

Redacción en logs de aplicación propios

Si extiendes el CLI con código propio, usa redact_blob para cualquier string libre antes de mandarlo a print(..., file=sys.stderr) o a un logger:

import logging, sys
from tecsas3_cli.redaction import redact_blob

logger = logging.getLogger("mi_modulo")
logger.addHandler(logging.StreamHandler(sys.stderr))

def safe_log(msg: str) -> None:
    logger.info(redact_blob(msg))

Redacción selectiva por comando

Si necesitas desactivar la redacción para un único comando (sólo en dev), exporta la variable antes de invocar:

TECSAS3_REDACT_PHI=false tecsas3 --debug --json --no-input paciente get 2909

Combinación con `--debug`

--debug activa el log stderr; redact_phi aplica a ese log. La combinación por defecto es segura: el log sale redactado. La única forma de “ver” el body crudo es --debug --redact-phi=false, que requiere la firma de un humano y un entorno aislado.

Siguientes pasos

Aprende la tabla de exit codes para enrutar errores sin filtrar PHI a logs externos.
Configura correctamente la autenticación y los perfiles por entorno.
Profundiza en los formatos de salida deterministas para agentes.

Empezar

Conceptos

Guías

Soporte

Campos redactados

Redacción por clave (`PHI_KEYS`)

Redacción por patrón (`redact_blob`)

Configuración y flags

API de redacción

Desactivación explícita (sólo depuración)

Buenas prácticas

Verificación rápida

Troubleshooting

Sigo viendo PHI en `stderr`

`--redact-phi=false` no surte efecto

Una clave nueva debería ser PHI

Logs centralizados en ELK / Loki

Auditoría periódica

Patrones de uso

Redacción en recursos propios

Redacción en logs de aplicación propios

Redacción selectiva por comando

Combinación con `--debug`

Siguientes pasos

​Campos redactados

​Redacción por clave (PHI_KEYS)

​Redacción por patrón (redact_blob)

​Configuración y flags

​API de redacción

​Desactivación explícita (sólo depuración)

​Buenas prácticas

​Verificación rápida

​Troubleshooting

​Sigo viendo PHI en stderr

​--redact-phi=false no surte efecto

​Una clave nueva debería ser PHI

​Logs centralizados en ELK / Loki

​Auditoría periódica

​Patrones de uso

​Redacción en recursos propios

​Redacción en logs de aplicación propios

​Redacción selectiva por comando

​Combinación con --debug

​Siguientes pasos

Campos redactados

Redacción por clave (`PHI_KEYS`)

Redacción por patrón (`redact_blob`)

Configuración y flags

API de redacción

Desactivación explícita (sólo depuración)

Buenas prácticas

Verificación rápida

Troubleshooting

Sigo viendo PHI en `stderr`

`--redact-phi=false` no surte efecto

Una clave nueva debería ser PHI

Logs centralizados en ELK / Loki

Auditoría periódica

Patrones de uso

Redacción en recursos propios

Redacción en logs de aplicación propios

Redacción selectiva por comando

Combinación con `--debug`

Siguientes pasos