# Auditoría de dependencias y cadena de suministro

Reporta de qué depende realmente un proyecto, qué parte de eso alcanza de verdad su código y qué hallazgos importan, por tanto, primero.

## Entregable

Un documento Markdown, `dependency-risk-report.md`, con la estructura fijada en **Salida** más abajo. Recibe las dependencias que nombra **Revisión de seguridad de un cambio** y devuelve el riesgo que lleva cada una.

## Entradas obligatorias

- **El manifiesto de dependencias y su archivo de bloqueo** — los dos. El manifiesto declara la intención; el archivo de bloqueo declara qué se instala.
- **El código de la aplicación** — para poder trazar una dependencia hasta los caminos que la alcanzan, o demostrar que no la alcanza ninguno.
- **La fuente de avisos que puedes consultar** y la fecha de sus datos. Esta habilidad copia avisos de una fuente; nunca los recuerda.

Si falta cualquiera, repórtalo como ausente antes de auditar. Nunca declares un identificador de aviso, un rango afectado ni una versión de memoria: un aviso citado de recuerdo no se distingue de uno inventado.

## Entradas opcionales

- La configuración de compilación y despliegue, incluido lo que se ejecuta al instalar
- La política de licencias que el proyecto tiene que cumplir
- Auditorías anteriores y las decisiones tomadas sobre lo que encontraron
- Qué dependencias están fijadas por política y cuáles pueden flotar
- La configuración de registros y réplicas, y si los artefactos se verifican al descargarlos
- La lista de dependencias añadidas por el cambio que se está revisando

Cuando falte una entrada opcional, la sección que depende de ella reporta `no evaluado` con el motivo. Nunca reporta `limpio`.

## Ejecución

**1 — Resolver el árbol real.** A partir del archivo de bloqueo, lista las dependencias directas y todo lo que arrastran, con la versión resuelta de cada una. Registra la profundidad de cada dependencia transitiva y el camino por el que llegó. Un árbol leído del manifiesto en vez del archivo de bloqueo es otro árbol, y el informe declara cuál leyó.

**2 — Separar lo alcanzable de lo meramente instalado.** Por cada dependencia, establece si algún camino de la aplicación la alcanza y registra `alcanzada`, `no alcanzada` o `indeterminado`, con cómo se estableció. Casi siempre la mayor parte del árbol no se alcanza; tratarlo todo como vivo entierra la parte que sí se ejecuta.

**3 — Contrastar cada dependencia con la fuente de avisos que te dieron.** Registra la fuente y la fecha de sus datos. Copia de ella cada identificador y cada rango afectado, y compáralos con la versión instalada. Una dependencia que la fuente no cubre se registra como `no cubierta`, que no es lo mismo que segura.

**4 — Leer las señales de mantenimiento.** Por dependencia directa: cuándo cambió por última vez, cuántas personas pueden publicar una versión, si el artefacto publicado se corresponde con un árbol de fuentes público y si está archivada o descontinuada. Registra cada señal con dónde se leyó y cuándo.

**5 — Registrar las obligaciones de licencia.** Por dependencia: la licencia declarada, si la forma en que este proyecto distribuye su software activa alguna obligación, y cualquier dependencia cuya licencia no se haya podido determinar. Una licencia tomada de los metadatos del paquete y no de su archivo de licencia se marca como tal.

**6 — Encontrar qué se ejecuta al instalar y al compilar.** Ganchos de instalación, scripts posteriores a la instalación, generación de código, binarios descargados durante la compilación y todo lo que toca la red mientras se empaqueta. Ese código corre en máquinas de desarrollo y en agentes de compilación con sus privilegios, así que se audita como código en ejecución y no como metadatos.

**7 — Ordenar los hallazgos por alcanzabilidad.** Agrúpalos en código alcanzado, solo en tiempo de compilación y no alcanzado, y declara en qué grupo está cada hallazgo. Dentro de un grupo, ordena por impacto. El informe nunca presenta un aviso contra código que ningún camino alcanza como equivalente a uno sobre un camino que corre en cada petición.

## Salida

`dependency-risk-report.md`, en este orden:

- **1. Alcance y fecha** — qué manifiesto y archivo de bloqueo se leyeron, qué fuente de avisos y la fecha de sus datos, y cuándo
- **2. Árbol de dependencias** — dependencias directas con su versión resuelta, y el número y la profundidad de las transitivas detrás de cada una
- **3. Alcanzabilidad** — por dependencia: `alcanzada`, `no alcanzada` o `indeterminado`, y cómo se estableció
- **4. Hallazgos de avisos** — por hallazgo: la dependencia, el identificador tal como lo da la fuente, el rango afectado, la versión instalada, el grupo de alcanzabilidad
- **5. Señales de mantenimiento** — por dependencia directa: último cambio, quién puede publicar, correspondencia con las fuentes, estado
- **6. Licencias** — por dependencia: la licencia declarada, la obligación que activa, o `indeterminado`
- **7. Ejecución al instalar y al compilar** — qué se ejecuta, desde qué paquete y con qué acceso
- **8. Fijación y verificación** — qué está fijado, qué flota y si los artefactos se verifican al instalar
- **9. Sin determinar** — qué no se pudo establecer, por qué y qué lo establecería

## Validación

El informe está listo cuando se cumple todo esto:

- Cada dependencia directa de la sección 2 aparece en las secciones 3, 5 y 6
- Cada hallazgo de la sección 4 nombra la fuente de la que se copió y su grupo de alcanzabilidad
- No aparece ningún identificador, rango afectado ni versión que no venga de la fuente aportada
- Cada dependencia de la sección 3 lleva uno de los tres valores de alcanzabilidad, sin dejar ninguno en blanco
- Las secciones 5 y 6 dicen `indeterminado` donde el material no lo cerró, nunca `ninguna`
- La sección 9 no está vacía, o declara que se determinó todo lo que estaba en alcance

Falla la ejecución si un identificador de aviso o una versión aparecen sin la fuente de la que se leyeron, o si una dependencia se reporta como segura por el hecho de que no se encontró nada.

## Gestión de fallos

- **No hay archivo de bloqueo** — audita el manifiesto, marca cada versión como `declarada, no instalada` y reporta que los resultados de alcanzabilidad y de avisos describen un árbol que puede no ser el desplegado.
- **No hay fuente de avisos disponible** — produce todas las demás secciones y marca la sección 4 como `no evaluado — sin fuente de avisos aportada`. Nunca la rellenes de memoria.
- **La alcanzabilidad no se puede determinar** — marca la dependencia como `indeterminado`, ordénala como si estuviera alcanzada y declara en la sección 9 a qué hallazgos afecta eso.
- **El manifiesto y el archivo de bloqueo no coinciden** — registra ambos, audita el archivo de bloqueo y eleva la discrepancia a la sección 9 como bloqueante. Un proyecto que instala algo distinto de lo que declara tiene un segundo problema detrás del primero.
- **Varios ecosistemas en un mismo proyecto** — audita cada manifiesto por separado y repórtalos por separado, listando en la sección 9 cualquier directorio no cubierto. Una única lista fusionada esconde qué gestor de paquetes instala qué.