Preguntas frecuentes y mejores prácticas

Seguridad y arquitectura

¿Qué ocurre si pierdo la contraseña maestra?

Sin la contraseña maestra, descifrar los secretos es imposible — una consecuencia directa de la arquitectura Zero-Knowledge. El servidor no almacena las claves y no puede ayudar en la recuperación.

Qué hacer:

• Para cuentas de servicio, almacene la contraseña maestra en variables de CI protegidas y en una ubicación segura separada (una caja fuerte o HSM).
• Para usuarios, asegúrese de que el administrador pueda restablecer la contraseña y otorgar nuevo acceso a la bóveda.

¿Qué puede ver el administrador del servidor de Passwork?

Un administrador que gestiona la infraestructura de Passwork puede ver:

Visible	No visible
Estructura de bóvedas y carpetas	Contraseñas descifradas
Nombres de registros	Valores de campos
Metadatos (etiquetas, fechas)	Contenido de archivos adjuntos
Registro de auditoría	Claves de cifrado de usuarios

Incluso con acceso completo al servidor y a la base de datos, el administrador no puede leer los secretos.

¿Se puede desactivar Zero-Knowledge?

En la versión autoalojada de Passwork, el cifrado del lado del cliente (Zero-Knowledge) es el principio básico de la arquitectura. En una instancia ya instalada, es imposible activarlo o desactivarlo: la elección del modo se determina en la etapa del asistente de configuración.

¿Qué hacer si se filtra un token de CI?

1. Revocar el token inmediatamente — desde la configuración de la cuenta de servicio.
2. Revisar el registro de auditoría — identificar qué operaciones realizó el token.
3. Rotar los secretos afectados — cualquier secreto al que la cuenta comprometida pudiera acceder.
4. Emitir un nuevo token — actualizarlo en su sistema de CI.

tip

Utilice cuentas de servicio separadas por cada pipeline de CI. De esta forma, la filtración de un token no expone todo.

Trabajo con CLI y SDK

¿Por qué el CLI necesita tanto un token de acceso como una contraseña maestra?

• Token de acceso — le autentica en la API de Passwork.
• Contraseña maestra — descifra los datos localmente (Zero-Knowledge).

Sin el token de acceso, no puede obtener los datos cifrados. Sin la contraseña maestra, no puede descifrarlos.

¿Cómo obtiene los datos el CLI?

Cuando ejecuta passwork-cli, este:

1. Se autentica con el servidor.
2. Descarga los registros cifrados de la carpeta especificada.
3. Los descifra localmente.
4. Inyecta los valores en variables de entorno o los escribe en STDOUT.

No hay caché entre llamadas — cada invocación obtiene datos actualizados del servidor.

¿Cómo se gestionan los conflictos de actualización?

Passwork utiliza bloqueo optimista. Cuando dos clientes actualizan el mismo registro simultáneamente:

1. El primero tiene éxito.
2. El segundo recibe un error de conflicto.
3. El segundo cliente debe volver a obtener el registro e intentarlo de nuevo.

En Python SDK:

try:
    client.update_password(item)
except ConflictError:
    # Reload and try again
    item = client.get_password(item_id=item.id)
    item.password = new_password
    client.update_password(item)

¿Puedo usar el CLI sin Docker?

Por supuesto. passwork-cli es un paquete de Python que puede instalar mediante pip:

pip install passwork-python

# Or from GitHub
pip install git+https://github.com/passwork-me/passwork-python.git

Docker es conveniente para CI/CD cuando no desea gestionar un entorno de Python.

Organización de secretos

¿Cómo debo estructurar las carpetas para varios equipos?

Un ejemplo para una organización con varios productos:

infrastructure/
├── shared/             # Shared infrastructure
│   ├── production/
│   └── staging/
├── orders-team/        # Orders service team
│   ├── production/
│   ├── staging/
│   └── development/
└── payments-team/      # Payments service team
    ├── production/
    └── staging/

Derechos de acceso:

• Equipo de pedidos → solo orders-team/*
• Equipo de pagos → solo payments-team/*
• Ingenieros de plataforma → todas las carpetas
• Cuentas de servicio de CI/CD → solo lectura en carpetas específicas

¿Cómo debo nombrar los registros para la automatización?

Utilice nombres predecibles y descriptivos:

# Good — purpose is obvious
mysql-orders-prod
elasticsearch-logs
sendgrid-api-key

# Avoid — requires opening to understand
creds-1
temp-secret
abc123

Cuando utiliza exec con una carpeta, los nombres de los registros se convierten en nombres de variables de entorno. Utilice UPPER_SNAKE_CASE:

MYSQL_PASSWORD
ELASTIC_AUTH
SENDGRID_API_KEY

¿Debo almacenar varios secretos relacionados en un solo registro?

Sí, cuando los secretos están lógicamente relacionados y se usan juntos:

Record: mysql-orders-prod
├── login: order_service
├── password: ...
├── MYSQL_HOST: mysql.prod.internal
├── MYSQL_PORT: 3306
└── MYSQL_DATABASE: orders

No, cuando los secretos son independientes o rotan en diferentes intervalos.

Rotación y ciclo de vida

¿Por qué Passwork no rota los secretos automáticamente?

Zero-Knowledge significa que el servidor no puede acceder a los datos descifrados. La rotación requiere:

1. Descifrar el valor actual (necesita las claves del cliente).
2. Generar uno nuevo.
3. Actualizar el sistema de destino (base de datos, servicio).
4. Cifrar y almacenar el nuevo valor.

Los pasos 1, 3 y 4 requieren un cliente con claves y acceso al sistema de destino. El servidor no dispone de eso.

¿Puedo recuperar un secreto eliminado?

La recuperación depende de la configuración del servidor (papelera de reciclaje, eliminación lógica). Consulte con su administrador.

aviso

Realice siempre una copia de seguridad antes de operaciones masivas y pruebe los scripts en un entorno de pruebas primero.

Migración e integración

¿Cómo migro desde otro gestor de secretos?

Enfoque general:

1. Exportar los secretos del sistema anterior (normalmente JSON o YAML).
2. Escribir un script para transformar los datos a la estructura de Passwork.
3. Importar mediante Python SDK (create_password).

Consulte la sección de Python SDK para ver un ejemplo de migración de .env.

¿Cómo integro Passwork con Terraform?

No existe un proveedor oficial de Terraform, pero puede:

1. Usar una fuente de datos external con passwork-cli get.
2. Escribir un script envolvente que lea los secretos y los pase a Terraform.

data "external" "db_password" {
  program = ["bash", "-c", "passwork-cli get --password-id $ID --json"]
}

resource "aws_db_instance" "main" {
  password = data.external.db_password.result.password
}