paramsx 2.2.2__tar.gz → 2.3.0__tar.gz

{paramsx-2.2.2 → paramsx-2.3.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.3.0
+
+### Añadido
+
+- **La descripción de los parámetros, editable como el valor.** El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**: se lee de AWS, lo editas y al cargar se actualiza. Los cambios de descripción se detectan igual que los de valor y aparecen en la pantalla de confirmación como `Modificado (descripción)`. La opción 4 también la pide al crear un parámetro, entre la ruta y el valor.
+- Los backups incluyen la descripción, así que un backup restaura también las descripciones.
+- **Flag `forzar_securestring`** (por defecto `True`, el comportamiento de siempre): todo lo que sube ParamsX va cifrado como `SecureString`. Con `False` se respeta el tipo que ya tuviera el parámetro en AWS: al actualizar no se manda el tipo y AWS conserva el suyo (`Type` solo es obligatorio al crear). El fichero exportado trae además un campo `parameter_type` editable, por si quieres cambiar el tipo a propósito, y sus cambios se detectan como los del valor o la descripción. El tipo se lee de la misma llamada que el valor, así que no hace falta ningún permiso nuevo.
+
+### Nota sobre el valor y la descripción
+
+`put_parameter` con `Overwrite=True` reescribe la definición del parámetro, así que ParamsX **manda siempre la descripción que trae el fichero**, incluso cuando lo único que cambió fue el valor. Antes no se mandaba, y una descripción que ya existiera en AWS podía quedarse vacía al editar el valor.
+
+### Nota sobre permisos
+
+Leer las descripciones necesita **`ssm:DescribeParameters`**, porque no vienen en `GetParametersByPath` (son metadatos, no valores). Si tu rol no lo tiene, ParamsX te avisa al leer, el campo no aparece en el fichero y al cargar **no se toca** la descripción que haya en AWS. El resto sigue funcionando igual.
+
 ## 2.2.2
 
 Un renombrado de la configuración, sin cambios de comportamiento. **Los nombres antiguos

{paramsx-2.2.2/paramsx.egg-info → paramsx-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramsx
-Version: 2.2.2
+Version: 2.3.0
 Summary: Librería para gestionar y respaldar parámetros de AWS SSM de manera sencilla y eficiente.
 Home-page: https://github.com/pistatxos/paramsx
 Author: Mariox
@@ -70,7 +70,7 @@ Al ejecutar ```paramsx``` desde la terminal, accedes a un menú interactivo con
 - Navega por la lista de parámetros configurada en tu archivo de configuración y selecciona cuál descargar.
 - Elige el entorno deseado (por ejemplo, dev o prod).
 - Archivos generados:
-    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (valores y tags).
+    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (descripciones, valores y tags).
     - parameters_dev_backup.py → Respaldo automático del archivo descargado, incluidas las tags.
 Los archivos se crean en la misma ruta desde donde ejecutas paramsx, evitando movernos innecesariamente entre carpetas.
 - Si tu rol IAM no tiene permisos sobre la ruta configurada, verás un mensaje claro en lugar de una traza de boto3:
@@ -98,6 +98,7 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
     - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
+    - La descripción, opcional: para qué sirve el parámetro. Se guarda en AWS y luego se puede editar en el fichero exportado.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
     - Las tags obligatorias, si tienes `tags_activas = True`.
 - El perfil que se usa es el que declares en `perfil_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
@@ -212,6 +213,16 @@ perfil_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 
@@ -269,6 +280,38 @@ En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden com
 | `{"path": "/API/STA", "perfil": "max"}` | `parameters_dev__API_STA__max.py` |
 | `{"path": "/API/*/STA", "perfil": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
+### La descripción de los parámetros
+
+El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**. Se lee de AWS, se edita como cualquier otro campo y se aplica al cargar:
+
+```python
+parametros = [
+    {'parameter_name': '/dev/api/sta/token',
+     'parameter_description': "Token JWT de la API, rota cada 90 dias",
+     'parameter_value': """abc123"""},
+]
+```
+
+Dos cosas que conviene saber:
+
+- **Hace falta el permiso `ssm:DescribeParameters`.** La descripción no viaja en `GetParametersByPath` como el valor: es un metadato y se pide con `DescribeParameters`. Si tu rol no lo tiene, ParamsX te avisa, el campo **no aparece** en el fichero y al cargar no se toca la descripción que haya en AWS.
+- **Al actualizar un parámetro, AWS reescribe su definición entera.** Por eso ParamsX manda siempre la descripción del fichero cuando cambia el valor, aunque no la hayas tocado: si no la mandara, se perdería. Y como no existe una API para cambiar solo la descripción, editarla crea una versión nueva del parámetro igual que cambiar el valor.
+
+Un cambio de descripción se ve en la pantalla de confirmación como `Modificado (descripción)`, y si cambias las dos cosas, `Modificado (valor | descripción)`.
+
+### Cifrado: `forzar_securestring`
+
+ParamsX sube todo como **SecureString** por defecto, y así se recomienda dejarlo: los parámetros de una cuenta acaban teniendo secretos, y con esto no depende de que nadie se acuerde.
+
+| `forzar_securestring` | Qué hace |
+|---|---|
+| `True` (por defecto) | Todo lo que se sube va cifrado como `SecureString`, sea del tipo que sea en AWS. |
+| `False` | Se respeta el tipo que ya tuviera el parámetro (`String`, `StringList` o `SecureString`): al actualizar no se manda el tipo, y AWS conserva el suyo. El fichero exportado trae además un campo `parameter_type` que puedes editar si quieres cambiarlo a propósito, y ese cambio cuenta como uno más: verás `Modificado (tipo: SecureString)`. |
+
+Los parámetros que creas con la opción 4 se crean siempre como `SecureString`, en los dos modos.
+
+El tipo se lee de la misma llamada que el valor, así que **no hace falta ningún permiso extra** para esto (a diferencia de la descripción).
+
 ### Cómo acotar tu parameter_list (recomendación)
 
 `parameter_list` es solo tu vista de trabajo: **la seguridad real la impone IAM, no este fichero**. La recomendación de uso es:
@@ -300,6 +343,7 @@ Formato del fichero exportado con `tags_activas = True`:
 ```python
 parametros = [
     {'parameter_name': '/dev/email/users',
+     'parameter_description': "Buzon que recibe los avisos de altas",
      'parameter_value': """agpetrovici@stanalytics.es""",
      'tagApplication': "",
      'tagEnvironment': "",

{paramsx-2.2.2 → paramsx-2.3.0}/README.md

@@ -50,7 +50,7 @@ Al ejecutar ```paramsx``` desde la terminal, accedes a un menú interactivo con
 - Navega por la lista de parámetros configurada en tu archivo de configuración y selecciona cuál descargar.
 - Elige el entorno deseado (por ejemplo, dev o prod).
 - Archivos generados:
-    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (valores y tags).
+    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (descripciones, valores y tags).
     - parameters_dev_backup.py → Respaldo automático del archivo descargado, incluidas las tags.
 Los archivos se crean en la misma ruta desde donde ejecutas paramsx, evitando movernos innecesariamente entre carpetas.
 - Si tu rol IAM no tiene permisos sobre la ruta configurada, verás un mensaje claro en lugar de una traza de boto3:
@@ -78,6 +78,7 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
     - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
+    - La descripción, opcional: para qué sirve el parámetro. Se guarda en AWS y luego se puede editar en el fichero exportado.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
     - Las tags obligatorias, si tienes `tags_activas = True`.
 - El perfil que se usa es el que declares en `perfil_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
@@ -192,6 +193,16 @@ perfil_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 
@@ -249,6 +260,38 @@ En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden com
 | `{"path": "/API/STA", "perfil": "max"}` | `parameters_dev__API_STA__max.py` |
 | `{"path": "/API/*/STA", "perfil": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
+### La descripción de los parámetros
+
+El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**. Se lee de AWS, se edita como cualquier otro campo y se aplica al cargar:
+
+```python
+parametros = [
+    {'parameter_name': '/dev/api/sta/token',
+     'parameter_description': "Token JWT de la API, rota cada 90 dias",
+     'parameter_value': """abc123"""},
+]
+```
+
+Dos cosas que conviene saber:
+
+- **Hace falta el permiso `ssm:DescribeParameters`.** La descripción no viaja en `GetParametersByPath` como el valor: es un metadato y se pide con `DescribeParameters`. Si tu rol no lo tiene, ParamsX te avisa, el campo **no aparece** en el fichero y al cargar no se toca la descripción que haya en AWS.
+- **Al actualizar un parámetro, AWS reescribe su definición entera.** Por eso ParamsX manda siempre la descripción del fichero cuando cambia el valor, aunque no la hayas tocado: si no la mandara, se perdería. Y como no existe una API para cambiar solo la descripción, editarla crea una versión nueva del parámetro igual que cambiar el valor.
+
+Un cambio de descripción se ve en la pantalla de confirmación como `Modificado (descripción)`, y si cambias las dos cosas, `Modificado (valor | descripción)`.
+
+### Cifrado: `forzar_securestring`
+
+ParamsX sube todo como **SecureString** por defecto, y así se recomienda dejarlo: los parámetros de una cuenta acaban teniendo secretos, y con esto no depende de que nadie se acuerde.
+
+| `forzar_securestring` | Qué hace |
+|---|---|
+| `True` (por defecto) | Todo lo que se sube va cifrado como `SecureString`, sea del tipo que sea en AWS. |
+| `False` | Se respeta el tipo que ya tuviera el parámetro (`String`, `StringList` o `SecureString`): al actualizar no se manda el tipo, y AWS conserva el suyo. El fichero exportado trae además un campo `parameter_type` que puedes editar si quieres cambiarlo a propósito, y ese cambio cuenta como uno más: verás `Modificado (tipo: SecureString)`. |
+
+Los parámetros que creas con la opción 4 se crean siempre como `SecureString`, en los dos modos.
+
+El tipo se lee de la misma llamada que el valor, así que **no hace falta ningún permiso extra** para esto (a diferencia de la descripción).
+
 ### Cómo acotar tu parameter_list (recomendación)
 
 `parameter_list` es solo tu vista de trabajo: **la seguridad real la impone IAM, no este fichero**. La recomendación de uso es:
@@ -280,6 +323,7 @@ Formato del fichero exportado con `tags_activas = True`:
 ```python
 parametros = [
     {'parameter_name': '/dev/email/users',
+     'parameter_description': "Buzon que recibe los avisos de altas",
      'parameter_value': """agpetrovici@stanalytics.es""",
      'tagApplication': "",
      'tagEnvironment': "",

paramsx-2.3.0/paramsx/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.3.0"

{paramsx-2.2.2 → paramsx-2.3.0}/paramsx/funcions.py

@@ -161,7 +161,10 @@ def get_parameters_by_prefix(ssm, prefix):
         for param in response.get('Parameters', []):
             parameters.append({
                 "parameter_name": param['Name'],
-                "parameter_value": param['Value']
+                "parameter_value": param['Value'],
+                # El tipo viene en la misma respuesta que el valor, sin permisos extra.
+                # Solo se usa si forzar_securestring = False.
+                "parameter_type": param.get('Type', "SecureString"),
             })
 
         next_token = response.get('NextToken')
@@ -174,6 +177,61 @@ def get_parameters_by_prefix(ssm, prefix):
     return parameters
 
 
+# Descripciones de los parámetros de una ruta, indexadas por nombre.
+# La descripción NO viene en get_parameters_by_path: hay que pedirla aparte con
+# describe_parameters, que es la que devuelve los metadatos. Eso exige el permiso
+# ssm:DescribeParameters, que no todo el mundo tiene.
+def get_descriptions_by_prefix(ssm, prefix):
+    descripciones = {}
+    next_token = None
+    # Con prefijo "/" (backup de la cuenta entera) no se filtra: se piden todos
+    ruta = prefix.rstrip("/")
+
+    while True:
+        request_args = {"MaxResults": 50}
+        if ruta:
+            request_args["ParameterFilters"] = [
+                {"Key": "Path", "Option": "Recursive", "Values": [ruta]}
+            ]
+        if next_token:
+            request_args["NextToken"] = next_token
+
+        try:
+            response = ssm.describe_parameters(**request_args)
+        except ClientError as e:
+            if _codigo_error(e) == "AccessDeniedException":
+                raise AccessDeniedError(prefix, sugerir_acotar=False) from None
+            raise
+
+        for meta in response.get("Parameters", []):
+            descripciones[meta["Name"]] = meta.get("Description", "")
+
+        next_token = response.get("NextToken")
+        if not next_token:
+            break
+
+    return descripciones
+
+
+# Rellenar cada parámetro con su descripción. Devuelve la lista de avisos.
+# Si no hay permisos, el campo NO se añade al fichero exportado: así al cargar se sabe
+# que las descripciones no se gestionan y no se toca la que haya en AWS.
+def agregar_descripciones_a_parametros(ssm, parameters, prefix):
+    try:
+        descripciones = get_descriptions_by_prefix(ssm, prefix)
+    except AccessDeniedError:
+        for param in parameters:
+            param.pop("parameter_description", None)
+        return [
+            "⚠ Sin permisos para leer las descripciones (hace falta ssm:DescribeParameters): "
+            "no aparecen en el fichero y al cargar no se tocarán las que ya existan en AWS."
+        ]
+
+    for param in parameters:
+        param["parameter_description"] = descripciones.get(param["parameter_name"], "")
+    return []
+
+
 # Comprobar si existe algún parámetro bajo un prefijo (None = no se pudo comprobar por permisos)
 def existe_prefijo(ssm, prefix):
     try:
@@ -318,7 +376,8 @@ def _orden_tags(param, tags_obligatorias):
 
 
 # Función para exportar parámetros a un archivo
-def export_parameters_to_file(parameters, file_path, tags_activas=False, tags_obligatorias=None):
+def export_parameters_to_file(parameters, file_path, tags_activas=False, tags_obligatorias=None,
+                              incluir_tipo=False):
     tags_obligatorias = tags_obligatorias or []
 
     with open(file_path, 'w') as f:
@@ -329,6 +388,17 @@ def export_parameters_to_file(parameters, file_path, tags_activas=False, tags_ob
             parameter_value = param['parameter_value']
             f.write(f"    {{'parameter_name': '{parameter_name}',\n")
 
+            # La descripción va debajo del nombre y antes del valor. Solo se escribe si
+            # se ha podido leer de AWS: si falta el campo, la carga no la toca.
+            if "parameter_description" in param:
+                descripcion = _escapar_valor_tag(param.get("parameter_description") or "")
+                f.write(f"     'parameter_description': \"{descripcion}\",\n")
+
+            # El tipo solo se escribe si se respeta (forzar_securestring = False): con
+            # el valor por defecto todo acaba en SecureString y el campo solo confundiría.
+            if incluir_tipo and "parameter_type" in param:
+                f.write(f"     'parameter_type': \"{param['parameter_type']}\",\n")
+
             if not tags_activas:
                 # Usar triple comillas para valores largos
                 f.write(f"     'parameter_value': \"\"\"{parameter_value}\"\"\"}},\n\n")
@@ -346,6 +416,10 @@ def indexar_parametros(parametros):
     return {
         p['parameter_name']: {
             "value": p.get('parameter_value', ""),
+            # None (campo ausente) significa "este fichero no gestiona descripciones",
+            # que no es lo mismo que una descripción vacía
+            "description": p.get('parameter_description'),
+            "type": p.get('parameter_type'),
             "tags": extraer_tags(p),
         }
         for p in parametros
@@ -357,6 +431,10 @@ def indice_a_parametros(indice):
     parametros = []
     for nombre, datos in indice.items():
         param = {"parameter_name": nombre, "parameter_value": datos["value"]}
+        if datos.get("description") is not None:
+            param["parameter_description"] = datos["description"]
+        if datos.get("type") is not None:
+            param["parameter_type"] = datos["type"]
         for clave, valor in datos["tags"].items():
             param[f"{TAG_FIELD_PREFIX}{clave}"] = valor
         parametros.append(param)
@@ -416,24 +494,44 @@ def compare_parameters(file_path, backup_file_path, stdscr=None, tags_activas=Fa
                 "tipo": "Nuevo",
                 "detalle": "nuevo parámetro",
                 "value": actual["value"],
+                "description": actual["description"],
+                "type": actual["type"],
                 "tags": actual["tags"],
                 "value_changed": True,
+                "description_changed": actual["description"] is not None,
                 "tags_set": {k: v for k, v in actual["tags"].items() if str(v).strip()},
                 "tags_remove": [],
             })
             continue
 
         value_changed = actual["value"] != anterior["value"]
+        # Solo se compara la descripción si los dos ficheros la traen: si falta en alguno,
+        # es que no se pudo leer de AWS y no se debe tocar
+        description_changed = (
+            actual["description"] is not None
+            and anterior["description"] is not None
+            and actual["description"] != anterior["description"]
+        )
+        type_changed = (
+            actual["type"] is not None
+            and anterior["type"] is not None
+            and actual["type"] != anterior["type"]
+        )
         tags_set, tags_remove = ({}, [])
         if tags_activas:
             tags_set, tags_remove = _diff_tags(actual["tags"], anterior["tags"])
 
-        if not value_changed and not tags_set and not tags_remove:
+        if (not value_changed and not description_changed and not type_changed
+                and not tags_set and not tags_remove):
             continue
 
         detalles = []
         if value_changed:
             detalles.append("valor")
+        if description_changed:
+            detalles.append("descripción")
+        if type_changed:
+            detalles.append(f"tipo: {actual['type']}")
         if tags_set:
             detalles.append(f"tags: {', '.join(sorted(tags_set))}")
         if tags_remove:
@@ -444,8 +542,12 @@ def compare_parameters(file_path, backup_file_path, stdscr=None, tags_activas=Fa
             "tipo": "Modificado",
             "detalle": " | ".join(detalles),
             "value": actual["value"],
+            "description": actual["description"],
+            "type": actual["type"],
             "tags": actual["tags"],
             "value_changed": value_changed,
+            "description_changed": description_changed,
+            "type_changed": type_changed,
             "tags_set": tags_set,
             "tags_remove": tags_remove,
         })
@@ -457,8 +559,12 @@ def compare_parameters(file_path, backup_file_path, stdscr=None, tags_activas=Fa
                 "tipo": "Eliminado",
                 "detalle": "se borrará de AWS",
                 "value": backup_dict[nombre]["value"],
+                "description": backup_dict[nombre]["description"],
+                "type": backup_dict[nombre]["type"],
                 "tags": backup_dict[nombre]["tags"],
                 "value_changed": False,
+                "description_changed": False,
+                "type_changed": False,
                 "tags_set": {},
                 "tags_remove": [],
             })

{paramsx-2.2.2 → paramsx-2.3.0}/paramsx/main.py

@@ -15,6 +15,7 @@ from .funcions import (
     compare_parameters, load_parameters, show_main_menu_selection,
     AccessDeniedError, build_full_path, etiqueta_entrada, agregar_tags_a_parametros,
     validar_tags_obligatorias, aplicar_cambios_tags, check_rds_correlacion,
+    agregar_descripciones_a_parametros,
     show_report, prompt_input, indexar_parametros, indice_a_parametros,
     ficheros_cargables,
     POSICIONES_ENTORNO, CASES_ENTORNO, CASES_RUTA, MARCADOR_ENTORNO, slug_entrada,
@@ -51,7 +52,7 @@ que va siempre en minúscula, aplicándole el 'case_entorno' del perfil."""
 # Opciones que viven fuera de 'configuraciones' y son opcionales: si el usuario no las
 # tiene, se usa el valor de la plantilla. Se listan para poder decirle qué le falta.
 CLAVES_OPCIONALES = (
-    "perfiles", "perfil_nuevos", "fichero_por_ruta",
+    "perfiles", "perfil_nuevos", "fichero_por_ruta", "forzar_securestring",
     "tags_activas", "obligatorias_vacias", "tags_obligatorias",
 )
 
@@ -98,6 +99,9 @@ def load_config():
     config["fichero_por_ruta"] = bool(
         getattr(modulo, "fichero_por_ruta", plantilla_config.fichero_por_ruta)
     )
+    config["forzar_securestring"] = bool(
+        getattr(modulo, "forzar_securestring", plantilla_config.forzar_securestring)
+    )
     # Si no se declara, los parámetros nuevos usan el primer perfil definido
     # ('convencion_nuevos' es el nombre que tuvo en la 2.2.0)
     primer_perfil = next(iter(config["perfiles"]), None)
@@ -301,9 +305,9 @@ def leer_ruta(stdscr, ssm, full_path, tags_activas, tags_obligatorias):
         show_message(stdscr, f"{e}", 2)
         return None, []
 
-    avisos = []
+    avisos = agregar_descripciones_a_parametros(ssm, parameters, full_path)
     if tags_activas:
-        avisos = agregar_tags_a_parametros(ssm, parameters, tags_obligatorias)
+        avisos.extend(agregar_tags_a_parametros(ssm, parameters, tags_obligatorias))
 
     return parameters, avisos
 
@@ -334,7 +338,7 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
     while True:
         path = prompt_input(
             stdscr,
-            "Crear nuevo parámetro (1/4): ruta",
+            "Crear nuevo parámetro (1/5): ruta",
             f"Ruta del parámetro (perfil '{nombre_perfil}', sin el entorno):",
             valor=path,
             ayuda=ayudas.get(posicion, ""),
@@ -360,7 +364,7 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
     path = build_full_path(path_declarado, perfil, entorno)
 
     if not show_report(
-        stdscr, "Crear nuevo parámetro (2/4): confirmar la ruta",
+        stdscr, "Crear nuevo parámetro (2/5): confirmar la ruta",
         [f"Perfil:  {nombre_perfil}",
          f"Escrita:    {path_declarado}",
          f"En AWS:     {path}",
@@ -370,12 +374,26 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
     ):
         return
 
-    # 2. Valor (string plano o JSON)
+    # 3. Descripción: va debajo del nombre y antes del valor, igual que en el fichero
+    descripcion = prompt_input(
+        stdscr,
+        "Crear nuevo parámetro (3/5): descripción",
+        "Descripción del parámetro (opcional):",
+        valor="",
+        permitir_vacio=True,
+        ayuda="Para qué sirve este parámetro. Se guarda en AWS y luego se puede editar "
+              "en el fichero exportado. Máximo 1024 caracteres; Enter para dejarla vacía.",
+    )
+    if descripcion is None:
+        return
+    descripcion = descripcion.strip()[:1024]
+
+    # 4. Valor (string plano o JSON)
     valor = ""
     while True:
         valor = prompt_input(
             stdscr,
-            "Crear nuevo parámetro (3/4): valor",
+            "Crear nuevo parámetro (4/5): valor",
             f"Valor para {path}:",
             valor=valor,
             ayuda='Texto plano o JSON en una línea, ej: {"host": "x", "user": "y", "pass": "z"}',
@@ -392,7 +410,7 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
                 continue
         break
 
-    # 3. Tags obligatorias
+    # 5. Tags obligatorias
     tags = {}
     faltantes = []
     if tags_activas:
@@ -406,7 +424,7 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
             predeterminado = entorno if clave == "Environment" else ""
             respuesta = prompt_input(
                 stdscr,
-                f"Crear nuevo parámetro (4/4): tags [{indice}/{len(tags_obligatorias)}]",
+                f"Crear nuevo parámetro (5/5): tags [{indice}/{len(tags_obligatorias)}]",
                 f"Valor de la tag obligatoria '{clave}':",
                 valor=predeterminado,
                 permitir_vacio=obligatorias_vacias,
@@ -433,7 +451,13 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
     aviso_rds = check_rds_correlacion(ssm, path)
 
     # Resumen y confirmación
-    lineas = [f"Ruta:   {path}", f"Valor:  {valor[:120]}", "Tipo:   SecureString", ""]
+    lineas = [
+        f"Ruta:        {path}",
+        f"Descripción: {descripcion or '(vacía)'}",
+        f"Valor:       {valor[:120]}",
+        "Tipo:        SecureString",
+        "",
+    ]
     if tags_activas:
         lineas.append("Tags:")
         lineas.extend([f"  {clave} = {valor_tag}" for clave, valor_tag in tags.items()])
@@ -456,6 +480,8 @@ def crear_parametro(stdscr, ssm, entornos, perfil, nombre_perfil, tags_activas,
         "Type": "SecureString",
         "Overwrite": False,
     }
+    if descripcion:
+        kwargs["Description"] = descripcion
     if tags_activas and tags:
         kwargs["Tags"] = [{"Key": k, "Value": v} for k, v in tags.items()]
 
@@ -512,6 +538,7 @@ def main(stdscr, config=None):
     TAGS_OBLIGATORIAS = config['tags_obligatorias']
     OBLIGATORIAS_VACIAS = config.get('obligatorias_vacias', False)
     FICHERO_POR_RUTA = config.get('fichero_por_ruta', False)
+    FORZAR_SECURESTRING = config.get('forzar_securestring', True)
     PERFIL_NUEVOS = config.get('perfil_nuevos')
 
     # Nombre del fichero exportado: con fichero_por_ruta cada ruta tiene el suyo, así que
@@ -565,10 +592,12 @@ def main(stdscr, config=None):
                     continue
 
             # Exportar parámetros al archivo principal
-            export_parameters_to_file(parameters, file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS)
+            export_parameters_to_file(parameters, file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS,
+                                      incluir_tipo=not FORZAR_SECURESTRING)
 
             # Crear un respaldo exacto del archivo principal (valores y tags)
-            export_parameters_to_file(parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS)
+            export_parameters_to_file(parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS,
+                                      incluir_tipo=not FORZAR_SECURESTRING)
 
             # Confirmación de archivos creados
             lineas = [
@@ -661,14 +690,30 @@ def main(stdscr, config=None):
                             )
 
                     try:
-                        if change["value_changed"]:
-                            # Subir o actualizar parámetros
-                            ssm.put_parameter(
-                                Name=param_name,
-                                Value=change["value"],
-                                Type='SecureString',
-                                Overwrite=True
-                            )
+                        if (change["value_changed"] or change.get("description_changed")
+                                or change.get("type_changed")):
+                            kwargs_put = {
+                                "Name": param_name,
+                                "Value": change["value"],
+                                "Overwrite": True,
+                            }
+                            # El 'Type' solo es obligatorio al CREAR: al actualizar, si no
+                            # se manda, AWS conserva el que tuviera el parámetro. Por eso
+                            # con forzar_securestring = False se omite en las
+                            # modificaciones en vez de adivinarlo.
+                            if FORZAR_SECURESTRING:
+                                kwargs_put["Type"] = "SecureString"
+                            elif change.get("type"):
+                                kwargs_put["Type"] = change["type"]
+                            elif tipo == "Nuevo":
+                                kwargs_put["Type"] = "SecureString"
+                            # put_parameter con Overwrite reescribe la definición del
+                            # parámetro: si no se manda la descripción, la que hubiera en
+                            # AWS se pierde. Así que se manda siempre que el fichero la
+                            # traiga, incluso cuando lo que cambió fue solo el valor.
+                            if change.get("description") is not None:
+                                kwargs_put["Description"] = change["description"]
+                            ssm.put_parameter(**kwargs_put)
                         # Los cambios de tags se aplican en la misma pasada que el valor
                         aplicar_cambios_tags(
                             ssm, param_name, change["tags_set"], change["tags_remove"]
@@ -715,7 +760,8 @@ def main(stdscr, config=None):
                             "tags": change["tags"],
                         }
                 export_parameters_to_file(
-                    indice_a_parametros(indice), backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS
+                    indice_a_parametros(indice), backup_file_name, TAGS_ACTIVAS,
+                    TAGS_OBLIGATORIAS, incluir_tipo=not FORZAR_SECURESTRING
                 )
 
                 lineas.extend(["", f"Errores ({len(errores)}):"])
@@ -765,6 +811,9 @@ def main(stdscr, config=None):
                             # Ruta sin parámetros para ese entorno: se ignora en el backup total
                             continue
 
+                        avisos_totales.extend(
+                            agregar_descripciones_a_parametros(ssm, parameters, full_path)
+                        )
                         if TAGS_ACTIVAS:
                             avisos_totales.extend(
                                 agregar_tags_a_parametros(ssm, parameters, TAGS_OBLIGATORIAS)
@@ -774,7 +823,8 @@ def main(stdscr, config=None):
                 # Crear archivo de backup total listado
                 backup_file_name = "total_listed_parameters_backup.py"
                 export_parameters_to_file(
-                    all_parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS
+                    all_parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS,
+                    incluir_tipo=not FORZAR_SECURESTRING
                 )
 
                 # Confirmación de backup creado
@@ -796,7 +846,8 @@ def main(stdscr, config=None):
                 # Crear archivo de backup de todos los parámetros
                 backup_file_name = "all_parameters_backup.py"
                 export_parameters_to_file(
-                    parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS
+                    parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS,
+                    incluir_tipo=not FORZAR_SECURESTRING
                 )
                 lineas = [
                     f"Backup de todos los parámetros creado: {backup_file_name}",
@@ -829,7 +880,8 @@ def main(stdscr, config=None):
                 # Crear archivo de backup con nombre claro
                 backup_file_name = f"{slug_entrada(selected_param)}_{selected_env}_backup.py"
                 export_parameters_to_file(
-                    parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS
+                    parameters, backup_file_name, TAGS_ACTIVAS, TAGS_OBLIGATORIAS,
+                    incluir_tipo=not FORZAR_SECURESTRING
                 )
 
                 # Confirmación de backup creado

{paramsx-2.2.2 → paramsx-2.3.0}/paramsx/paramsx_config.py

@@ -77,6 +77,16 @@ perfil_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 

{paramsx-2.2.2 → paramsx-2.3.0/paramsx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramsx
-Version: 2.2.2
+Version: 2.3.0
 Summary: Librería para gestionar y respaldar parámetros de AWS SSM de manera sencilla y eficiente.
 Home-page: https://github.com/pistatxos/paramsx
 Author: Mariox
@@ -70,7 +70,7 @@ Al ejecutar ```paramsx``` desde la terminal, accedes a un menú interactivo con
 - Navega por la lista de parámetros configurada en tu archivo de configuración y selecciona cuál descargar.
 - Elige el entorno deseado (por ejemplo, dev o prod).
 - Archivos generados:
-    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (valores y tags).
+    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (descripciones, valores y tags).
     - parameters_dev_backup.py → Respaldo automático del archivo descargado, incluidas las tags.
 Los archivos se crean en la misma ruta desde donde ejecutas paramsx, evitando movernos innecesariamente entre carpetas.
 - Si tu rol IAM no tiene permisos sobre la ruta configurada, verás un mensaje claro en lugar de una traza de boto3:
@@ -98,6 +98,7 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
     - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
+    - La descripción, opcional: para qué sirve el parámetro. Se guarda en AWS y luego se puede editar en el fichero exportado.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
     - Las tags obligatorias, si tienes `tags_activas = True`.
 - El perfil que se usa es el que declares en `perfil_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
@@ -212,6 +213,16 @@ perfil_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 
@@ -269,6 +280,38 @@ En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden com
 | `{"path": "/API/STA", "perfil": "max"}` | `parameters_dev__API_STA__max.py` |
 | `{"path": "/API/*/STA", "perfil": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
+### La descripción de los parámetros
+
+El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**. Se lee de AWS, se edita como cualquier otro campo y se aplica al cargar:
+
+```python
+parametros = [
+    {'parameter_name': '/dev/api/sta/token',
+     'parameter_description': "Token JWT de la API, rota cada 90 dias",
+     'parameter_value': """abc123"""},
+]
+```
+
+Dos cosas que conviene saber:
+
+- **Hace falta el permiso `ssm:DescribeParameters`.** La descripción no viaja en `GetParametersByPath` como el valor: es un metadato y se pide con `DescribeParameters`. Si tu rol no lo tiene, ParamsX te avisa, el campo **no aparece** en el fichero y al cargar no se toca la descripción que haya en AWS.
+- **Al actualizar un parámetro, AWS reescribe su definición entera.** Por eso ParamsX manda siempre la descripción del fichero cuando cambia el valor, aunque no la hayas tocado: si no la mandara, se perdería. Y como no existe una API para cambiar solo la descripción, editarla crea una versión nueva del parámetro igual que cambiar el valor.
+
+Un cambio de descripción se ve en la pantalla de confirmación como `Modificado (descripción)`, y si cambias las dos cosas, `Modificado (valor | descripción)`.
+
+### Cifrado: `forzar_securestring`
+
+ParamsX sube todo como **SecureString** por defecto, y así se recomienda dejarlo: los parámetros de una cuenta acaban teniendo secretos, y con esto no depende de que nadie se acuerde.
+
+| `forzar_securestring` | Qué hace |
+|---|---|
+| `True` (por defecto) | Todo lo que se sube va cifrado como `SecureString`, sea del tipo que sea en AWS. |
+| `False` | Se respeta el tipo que ya tuviera el parámetro (`String`, `StringList` o `SecureString`): al actualizar no se manda el tipo, y AWS conserva el suyo. El fichero exportado trae además un campo `parameter_type` que puedes editar si quieres cambiarlo a propósito, y ese cambio cuenta como uno más: verás `Modificado (tipo: SecureString)`. |
+
+Los parámetros que creas con la opción 4 se crean siempre como `SecureString`, en los dos modos.
+
+El tipo se lee de la misma llamada que el valor, así que **no hace falta ningún permiso extra** para esto (a diferencia de la descripción).
+
 ### Cómo acotar tu parameter_list (recomendación)
 
 `parameter_list` es solo tu vista de trabajo: **la seguridad real la impone IAM, no este fichero**. La recomendación de uso es:
@@ -300,6 +343,7 @@ Formato del fichero exportado con `tags_activas = True`:
 ```python
 parametros = [
     {'parameter_name': '/dev/email/users',
+     'parameter_description': "Buzon que recibe los avisos de altas",
      'parameter_value': """agpetrovici@stanalytics.es""",
      'tagApplication': "",
      'tagEnvironment': "",

paramsx-2.2.2/paramsx/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.2.2"