python-deps-pinning

Complemento directo de security-audit: ese skill declara que las dependencias sin pin exacto quedan fuera del scan; este las cuantifica y las nombra.

Por qué existe

Un scanner de vulnerabilidades (OSV, GHSA, PyPA) responde a la pregunta "¿la versión X del paquete Y tiene CVEs?". Si el repo declara requests a secas, o requests>=2.0, no hay versión X que consultar. La dependencia no es que salga limpia: es que nunca se miró.

El resultado es un reporte que dice "0 vulnerabilidades" sobre una superficie que jamás se auditó. Ese es el falso tranquilizante que este skill elimina: convierte el silencio en un número.

Cuándo invocar este skill

Triggers explícitos:

• "pinea las dependencias"
• "las deps no están fijadas"
• "genera el lockfile"
• "por qué el scan de seguridad no encuentra nada"
• "auditá las versiones de las dependencias"
• "pin dependencies" / "generate lockfile"

Triggers proactivos:

• Antes o después de correr security-audit (para interpretar su cobertura)
• Al añadir una dependencia nueva a requirements.txt o pyproject.toml
• Al preparar un release reproducible

Cómo se invoca

python ~/.agents/skills/python-deps-pinning/python_deps_pinning.py                 # reporte
python ~/.agents/skills/python-deps-pinning/python_deps_pinning.py --strict        # exit 1 si hay invisibles
python ~/.agents/skills/python-deps-pinning/python_deps_pinning.py --threshold 90  # exit 1 si cobertura < 90%
python ~/.agents/skills/python-deps-pinning/python_deps_pinning.py --json          # salida JSON

Cómo clasifica cada dependencia

Un ==1.2.* cuenta como rango, no como pin: el comodín no fija una versión.

La detección de lockfile es conservadora: solo cubre el manifest que vive en su mismo directorio. Un poetry.lock en la raíz no se asume válido para un requirements.txt de un subproyecto.

Fuentes que lee

Lockfiles reconocidos: poetry.lock, uv.lock, Pipfile.lock, pdm.lock, requirements.lock.

Excluye node_modules, .venv, venv, vendor_py, site-packages, dist, build, target y cualquier directorio oculto.

Qué NO hace / limitaciones

• No modifica ningún fichero. Es solo lectura: reporta y da la receta. No ejecuta pip-compile ni poetry lock por su cuenta — regenerar un lockfile cambia el árbol de dependencias y esa es una decisión del proyecto.
• No consulta la red. No resuelve versiones ni valida que existan en PyPI. Para eso está security-audit.
• No lee el contenido del lockfile. Comprueba su presencia junto al manifest; no verifica que esté sincronizado con él (un lockfile obsoleto cuenta como cobertura).
• No cubre setup.py con install_requires computado en Python: es código arbitrario, no un manifest declarativo.
• Solo Python. Para el resto del árbol de dependencias → security-audit.

Dependencias

Cero dependencias externas.

Ejemplo de salida

python-deps-pinning — repo: /repo

Manifests analizados: 2
  · requirements.txt
  · pyproject.toml

COBERTURA REAL DEL SCAN DE VULNERABILIDADES
  ----------------------------------------------------------
  dependencias declaradas   : 61
  resolubles a versión exacta: 0
  invisibles para el scanner : 61
  cobertura                  : 0.0%

FUERA DEL SCAN — un CVE en estas dependencias no se detectaría
  requirements.txt  (60)
    · flask                        rango sin lockfile
    · numpy                        rango sin lockfile
    … y 48 más

CÓMO CERRARLO
  pip-tools  → pip-compile requirements.in -o requirements.txt --generate-hashes
  uv         → uv pip compile requirements.in -o requirements.txt