Supply Chain Security

Supply Chain Security — Guia Completa

Companion del AI-First Engineering Framework v7.7.0

Version: 1.0.0 | Fecha: Marzo 2026 Aplica a: Todo proyecto que consuma dependencias externas (npm, pip, Go, Rust, etc.) o componentes AI Fuentes: NIST SP 800-218, NTIA SBOM Minimum Elements, SLSA Framework, OpenSSF Scorecard, EU Cyber Resilience Act Relacionado: aibom-generator.py, sbom-generator.py, sast-sca-scanner.py, AIBOM_SPDX_Guide.md

1. POR QUE IMPORTA LA SEGURIDAD DE SUPPLY CHAIN

1.1 El problema

Un proyecto moderno tiene cientos o miles de dependencias transitivas. Cada una es un vector de ataque:

Typosquatting: paquetes maliciosos con nombres similares a los populares
Dependency confusion: paquetes internos reemplazados por versiones publicas maliciosas
Compromised maintainers: cuentas de mantenedores comprometidas que publican versiones troyanizadas
Vulnerabilidades conocidas: CVEs no parcheados en dependencias transitivas

En proyectos AI-native, el riesgo se amplifica:

Modelos AI descargados de registros publicos sin verificacion
SDKs AI con dependencias pesadas y opacas
Datasets de entrenamiento sin proveniencia verificada
MCP servers de terceros con acceso a datos sensibles

1.2 El enfoque del framework

El framework unifica la seguridad de supply chain en 3 pilares:

SBOM (Software)          AIBOM (AI)              SCA (Vulnerabilidades)
sbom-generator.py        aibom-generator.py      sast-sca-scanner.py
    │                        │                        │
    └───────────┬────────────┘                        │
                │                                     │
        Supply Chain BOM                     Vulnerability Scan
        (que tengo)                          (que esta roto)
                │                                     │
                └──────────────┬──────────────────────┘
                               │
                    CI Pipeline (sbom.yml)
                    ┌──────────┼──────────────┐
                    │          │              │
              GitHub API   Dependency    PR Comment
              (publish)    Track         (diff report)

2. SBOM — SOFTWARE BILL OF MATERIALS

2.1 Que es un SBOM

Un SBOM es un inventario completo de todos los componentes de software que componen una aplicacion:

Dependencias directas e indirectas (transitivas)
Versiones exactas
Licencias
Package URLs (PURL) para identificacion universal
Hashes para verificacion de integridad

2.2 Generar el SBOM

# Generacion basica (CycloneDX)
python3 baseline/scripts/sbom-generator.py --project-dir .

# Formato SPDX 3.0
python3 baseline/scripts/sbom-generator.py --project-dir . --format spdx

# Con verificacion de licencias
python3 baseline/scripts/sbom-generator.py --project-dir . --license-check

# Solo verificar que existe
python3 baseline/scripts/sbom-generator.py --project-dir . --check-only

# Comparar con version anterior
python3 baseline/scripts/sbom-generator.py --project-dir . --diff project/F08_security/sbom.cdx.json.bak

2.3 Estrategia de generacion

El script usa una estrategia de fallback:

Syft (preferido) — herramienta de Anchore, genera SBOMs completos desde filesystem
cdxgen (alternativa) — herramienta de CycloneDX, multi-ecosistema
Parseo de lockfiles (fallback) — parsea directamente package-lock.json, poetry.lock, go.sum, etc.

Ecosistemas soportados:

Ecosistema	Lockfile	PURL Type	Herramienta SCA
npm	`package-lock.json`, `yarn.lock`	`pkg:npm/`	`npm audit`
pip	`requirements.txt`, `poetry.lock`	`pkg:pypi/`	`pip-audit`
Go	`go.sum`	`pkg:golang/`	`govulncheck`
Rust	`Cargo.lock`	`pkg:cargo/`	`cargo audit`
PHP	`composer.lock`	`pkg:composer/`	—
Ruby	`Gemfile.lock`	`pkg:gem/`	`bundler-audit`
Java	`pom.xml`	`pkg:maven/`	`dependency-check`
.NET	`packages.lock.json`	`pkg:nuget/`	`dotnet list --vulnerable`

2.4 Formatos de salida

CycloneDX 1.5 (default, recomendado para herramientas):

Archivo: project/F08_security/sbom.cdx.json
Compatible con: Dependency-Track, Grype, Trivy, Snyk, GUAC

SPDX 3.0 (recomendado para compliance):

Archivo: project/F08_security/sbom.spdx.json
Compatible con: GitHub Dependency Graph, NTIA requirements, ISO 5962

2.5 Verificacion de licencias

El script clasifica licencias en 3 categorias:

Categoria	Licencias	Accion
Permissive (aprobadas)	MIT, Apache-2.0, BSD-2/3, ISC, Unlicense	Ninguna
Weak copyleft (aprobadas con condiciones)	LGPL-2.1/3.0, MPL-2.0, EPL-2.0	Revisar obligaciones
Strong copyleft (requieren revision legal)	GPL-2.0/3.0, AGPL-3.0, SSPL-1.0	Revision obligatoria antes de usar

3. AIBOM — AI BILL OF MATERIALS

3.1 Que es un AIBOM

El AIBOM extiende el SBOM con componentes especificos de AI:

Modelos (proveedor, version, tipo, costo)
SDKs y dependencias AI
Datasets (fuente, clasificacion, licencia)
Agentes y skills
MCP servers

3.2 Generar el AIBOM

# Generacion desde artefactos del proyecto
python3 baseline/scripts/aibom-generator.py --project-dir .

# Formato SPDX 3.0 AI Profile
python3 baseline/scripts/aibom-generator.py --project-dir . --format spdx

Para detalles completos, ver framework/guides/AIBOM_SPDX_Guide.md.

4. SCA — SOFTWARE COMPOSITION ANALYSIS

4.1 Diferencia entre SBOM y SCA

Aspecto	SBOM	SCA
Pregunta	”Que componentes tengo?"	"Cuales tienen vulnerabilidades?”
Output	Inventario completo	Lista de CVEs
Frecuencia	Cada release/merge	Cada PR + continuo
Herramienta	`sbom-generator.py`	`sast-sca-scanner.py`

4.2 Ejecutar SCA

# Scan completo (SAST + SCA)
python3 baseline/scripts/sast-sca-scanner.py --project-dir .

# Solo SCA (dependencias)
python3 baseline/scripts/sast-sca-scanner.py --project-dir . --sca-only

5. CI/CD — PIPELINE DE SUPPLY CHAIN

5.1 Workflow automatizado

El framework incluye .github/workflows/sbom.yml que:

En cada PR:
- Genera SBOM (CycloneDX + SPDX)
- Genera AIBOM
- Compara con SBOM de main (diff de dependencias)
- Publica comment en el PR con resumen
En merge a main / tag:
- Genera SBOMs finales
- Publica SBOM a GitHub Dependency Graph API
- Archiva artefactos por 90 dias

5.2 Frecuencia recomendada

Evento	SBOM	AIBOM	SCA
PR abierto	Generar + diff	Generar	Scan
Merge a main	Generar + publicar	Generar + publicar	—
Release tag	Generar + archivar	Generar + archivar	Scan final
Diario (cron)	—	—	Scan (nuevos CVEs)

6. MONITOREO CONTINUO

6.1 Dependency-Track

Para monitoreo continuo de vulnerabilidades, el SBOM puede subirse a Dependency-Track:

# Subir SBOM via API
curl -X POST "https://dtrack.internal/api/v1/bom" \
  -H "X-Api-Key: $DTRACK_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "project=<project-uuid>" \
  -F "bom=@project/F08_security/sbom.cdx.json"

6.2 Grype / Trivy (scan desde SBOM)

# Grype: escanear vulnerabilidades desde SBOM
grype sbom:project/F08_security/sbom.cdx.json

# Trivy: escanear desde SBOM
trivy sbom project/F08_security/sbom.cdx.json

# Solo criticos
trivy sbom --severity CRITICAL project/F08_security/sbom.cdx.json

6.3 Alertas automaticas

Configurar GitHub Dependabot + el SBOM para alertas:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"

7. MEJORES PRACTICAS

7.1 Para desarrolladores

Lockfiles siempre en git — sin lockfile no hay SBOM reproducible
Revisar dependencias nuevas — cada npm install X o pip install X debe ser consciente
Preferir dependencias con buen OpenSSF Scorecard — ver scorecard.dev
Pinear versiones — "lodash": "4.17.21" no "lodash": "^4.0.0"
Auditar antes de mergear — el CI lo hace automatico, pero revisar el diff

7.2 Para tech leads

Definir politica de licencias — que licencias son aceptables
Establecer umbral de CVE — zero critical, max N high
Revisar SBOM diff en cada release — que se agrego, que se removio
Mantener AIBOM actualizado — cada modelo o SDK nuevo debe registrarse
Configurar Dependency-Track — para monitoreo continuo

7.3 Para la comunidad

Publicar SBOMs con cada release — transparencia de supply chain
Contribuir politicas de licencias — compartir listas aprobadas por industria
Reportar falsos positivos — mejorar la precision del scanner
Compartir integraciones — Dependency-Track, GUAC, Snyk configs

8. CHECKLIST DE IMPLEMENTACION

Fase 1: Basico (semana 1)

Ejecutar sbom-generator.py --project-dir . y revisar output
Ejecutar aibom-generator.py --project-dir . y completar datos AI
Agregar sbom.yml workflow al repo
Agregar .github/dependabot.yml

Fase 2: Enforcement (semana 2-3)

Configurar sast-sca-scanner.py en CI (ya existe security-scan.yml)
Definir politica de licencias en project-config.yaml
Establecer umbrales de CVE (zero critical)
Ejecutar --license-check y resolver copyleft

Fase 3: Monitoreo continuo (semana 4+)

Configurar Dependency-Track o similar
Configurar alertas de nuevos CVEs
Agregar SBOM diff review al proceso de PR
Publicar SBOM con cada release

9. RELACION CON OTROS ARTEFACTOS DEL FRAMEWORK

sbom-generator.py ────> sbom.cdx.json ────> Dependency-Track / GitHub
                   ────> sbom.spdx.json ───> GitHub Dependency Graph
                                                │
aibom-generator.py ───> aibom.yaml ────────────┤
                   ────> aibom.spdx.json ──────┘
                                                │
sast-sca-scanner.py ──> sast_report.json       │
                   ────> sca_report.json ──────> Vulnerability Dashboard
                                                │
compliance-linter.py ─> Verifica que           │
                        SBOM + AIBOM existen ──┘

data_classification.yaml ──> Clasifica datos sensibles en dependencias
data_provenance_registry.yaml ──> Proveniencia de datos AI

10. FIRMADO DE ARTEFACTOS (SBOM Y AIBOM)

10.1 Por que firmar

Un SBOM o AIBOM sin firma no ofrece garantias de integridad. Cualquier actor intermedio (CI comprometido, cache manipulado, repositorio alterado) podria modificar el inventario sin dejar rastro. La firma criptografica resuelve esto:

Deteccion de manipulacion: si el artefacto cambia despues de firmado, la verificacion falla
Cadena de confianza: vincula el artefacto a un builder o identidad verificable
Cumplimiento regulatorio: EU Cyber Resilience Act y NIST SSDF recomiendan artefactos firmados

10.2 Uso

# Firmar SBOM despues de generarlo
python3 baseline/scripts/sbom-generator.py --project-dir . --sign

# Firmar AIBOM despues de generarlo
python3 baseline/scripts/aibom-generator.py --project-dir . --sign

# Combinar con otras opciones
python3 baseline/scripts/sbom-generator.py --project-dir . --license-check --sign

10.3 Cadena de fallback

El firmado usa una estrategia de fallback automatica:

Prioridad	Herramienta	Metodo	Caso de uso
1	cosign (Sigstore)	Keyless signing via OIDC	CI/CD (GitHub Actions, GitLab CI)
2	gpg	Firma PGP con clave local	Desarrollo local con clave GPG configurada
3	SHA-256 hash	Attestation de integridad	Siempre disponible, sin dependencias externas

10.4 Archivo .sig sidecar

La firma se escribe como archivo sidecar junto al artefacto original:

project/F08_security/
  sbom.cdx.json          # SBOM original
  sbom.cdx.json.sig      # Firma (cosign, gpg, o JSON con SHA-256)
  aibom.yaml             # AIBOM original
  aibom.yaml.sig         # Firma del AIBOM

Cuando se usa el fallback SHA-256, el archivo .sig contiene un JSON con el hash, timestamp y generador:

{
  "algorithm": "SHA-256",
  "hash": "a1b2c3d4...",
  "file": "sbom.cdx.json",
  "timestamp": "2026-03-28T10:00:00+00:00",
  "generator": "sbom-generator/7.7.0"
}

Para verificar manualmente:

# Verificar hash SHA-256
sha256sum project/F08_security/sbom.cdx.json
# Comparar con el valor en .sig

11. SLSA LEVEL 2 — PROVENANCE

11.1 Que es SLSA Provenance

SLSA (Supply-chain Levels for Software Artifacts) es un framework de seguridad que define niveles de garantia sobre el origen y construccion de artefactos. El provenance es un documento que responde:

Quien genero el artefacto (builder identity)
Que materiales se usaron como entrada (lockfiles, fuentes)
Como se construyo (build type, parametros)
Cuando y en que entorno (timestamps, CI metadata)

El framework genera provenance compatible con SLSA v1.0 y el formato in-toto Statement v1.

11.2 Uso

# Generar SBOM con provenance SLSA
python3 baseline/scripts/sbom-generator.py --project-dir . --slsa-provenance

# Combinar con firmado para maxima seguridad
python3 baseline/scripts/sbom-generator.py --project-dir . --sign --slsa-provenance

El documento de provenance se escribe como sidecar:

project/F08_security/
  sbom.cdx.json                      # SBOM
  sbom.cdx.json.provenance.json      # Provenance SLSA v1.0

11.3 Contenido del documento de provenance

El documento sigue la especificacion in-toto Statement v1:

Campo	Valor	Descripcion
`_type`	`https://in-toto.io/Statement/v1`	Envelope type
`predicateType`	`https://slsa.dev/provenance/v1`	Tipo de predicado
`subject`	Nombre + SHA-256 del SBOM	Artefacto producido
`predicate.buildDefinition.buildType`	`https://framework.ai-first/sbom-generation/v1`	Tipo de build
`predicate.runDetails.builder.id`	`scripts/sbom-generator.py@7.7.0`	Identidad del builder
`predicate.buildDefinition.resolvedDependencies`	Hashes de lockfiles	Materiales de entrada
`predicate.runDetails.metadata`	Timestamps + CI env vars	Contexto de ejecucion

11.4 Metadata de CI

Cuando se ejecuta en GitHub Actions, el provenance captura automaticamente:

GITHUB_SHA — commit que disparo el build
GITHUB_WORKFLOW — nombre del workflow
GITHUB_RUN_ID — ID unico de la ejecucion
GITHUB_REPOSITORY — repositorio fuente

11.5 Niveles SLSA y roadmap

Nivel	Requisitos	Estado
Level 1	Provenance existe	Implementado (v7.7)
Level 2	Provenance generado por servicio de build	Implementado (via GitHub Actions)
Level 3	Build aislado en servicio hosted (no local)	Futuro — requiere build service dedicado

Nota: SLSA Level 3 requiere que el build ocurra en un servicio hosted con aislamiento fuerte (como GitHub Actions con runners ephemeral). Esto esta fuera del alcance actual del framework pero se soporta como trabajo futuro.

12. REFERENCIAS

Estandares

Herramientas

Framework

framework/guides/AIBOM_SPDX_Guide.md — Guia detallada de AIBOM y SPDX 3.0
framework/guides/OWASP_Agentic_Security_Guide.md — Seguridad de agentes AI
framework/guides/Compliance_Regulatory_Alignment_Guide.md — Compliance regulatorio