Una aplicación en Rust que convierte imágenes de contenedores (Docker, etc.) en repositorios Git y genera una factura de materiales del sistema de archivos (fsbom) en YAML. Cada capa del contenedor se representa como un commit de Git, preservando la historia y estructura de la imagen original.

Características

• Analiza imágenes Docker y extrae información de las capas
• Crea un repositorio Git donde cada capa de imagen se representa como un commit
• Genera una factura de materiales del sistema de archivos (fsbom) en YAML con listados de archivos por capa
• Soporte para capas vacías (ENV, WORKDIR, etc.) como commits vacíos
• Extracción completa de metadatos en formato Markdown
• Arquitectura extensible para soportar diferentes motores de contenedores

Casos de Uso

Comparación de Capas

Al solucionar problemas de contenedores, puedes usar las potentes capacidades de comparación de Git para identificar exactamente qué cambió entre dos capas. Ejecutando git diff entre commits, los ingenieros pueden ver con precisión qué archivos fueron añadidos, modificados o eliminados, facilitando mucho la comprensión del impacto de cada instrucción del Dockerfile y la localización de cambios problemáticos.

Rastrear el Origen

Usando git blame, los desarrolladores pueden determinar rápidamente qué capa introdujo un archivo o línea de código específico. Esto es especialmente valioso al diagnosticar problemas con archivos de configuración o dependencias. En lugar de inspeccionar manualmente cada capa, puedes rastrear inmediatamente el origen de cualquier archivo hasta su capa fuente e instrucción correspondiente en el Dockerfile.

Seguimiento del Ciclo de Vida de Archivos

OCI2Git te permite seguir el recorrido de un archivo específico a lo largo de la historia de la imagen de contenedor. Puedes observar cuándo se creó inicialmente un archivo, cómo fue modificado a través de las capas y si/cuando fue finalmente eliminado. Esta vista integral ayuda a entender la evolución de los archivos sin tener que rastrear manualmente los cambios a través de docenas de capas.

Para rastrear la historia de un archivo en tu imagen de contenedor — incluyendo cuándo apareció por primera vez, fue modificado o eliminado — puedes usar estos comandos de Git tras la conversión:

# Full history of a file (including renames)
git log --follow -- /rootfs/my/file/path
First appearance (i.e. creation) - see which layer introduced the file
git log --diff-filter=A -- /rootfs/my/file/path
All changes made to the file (with diffs)
git log -p --follow -- /rootfs/my/file/path
When the file was deleted
git log --diff-filter=D -- /rootfs/my/file/path
Show short commit info (concise layer history)
git log --follow --oneline -- /rootfs/my/file/path

Estos comandos facilitan rastrear el historial completo de cualquier archivo a través de las capas del contenedor sin la complejidad de extraer y comparar manualmente los archivos tar de las capas.

Análisis Multicapa

A veces, las comparaciones más reveladoras provienen de examinar cambios a través de múltiples capas no consecutivas. Con OCI2Git, puedes usar las herramientas de comparación de Git para analizar cómo evolucionaron los componentes a lo largo de varias etapas de construcción, identificando patrones que podrían ser invisibles al mirar solo capas adyacentes.

Exploración de Capas

Al usar git checkout para moverte a cualquier commit específico, puedes examinar el sistema de archivos del contenedor exactamente como existía en esa capa. Esto permite a los desarrolladores inspeccionar el estado preciso de archivos y directorios en cualquier punto del proceso de creación de la imagen, proporcionando un contexto invaluable al depurar o examinar el comportamiento del contenedor.

Análisis Multi-Imagen

Al trabajar con múltiples imágenes de contenedor que comparten un ancestro común, OCI2Git crea ramas inteligentemente solo cuando las imágenes realmente divergen. Esto te permite analizar múltiples imágenes relacionadas en un único repositorio mientras preservas su historia común.

# Convert first image to create the base repository
oci2git postgres:16.9-alpine3.21 -o alp
Convert second image to the same output folder
oci2git nginx:1.28.0-alpine-slim -o alp

OCI2Git detecta automáticamente las capas compartidas entre imágenes y crea una estructura de ramificación que refleja su base común. El historial de Git mostrará:

• Un tronco común que contiene todas las capas compartidas
• Ramas separadas que divergen solo cuando las imágenes realmente difieren
• Visualización clara de dónde las imágenes comparten ascendencia común vs. dónde se vuelven únicas
• Manejo inteligente de duplicados: si la misma imagen exacta se procesa dos veces, el algoritmo lo detecta antes del commit final de metadatos y omite la creación de una rama duplicada

Este enfoque es particularmente valioso para:

• Análisis de familias de imágenes: Comprender cómo diferentes variantes de una imagen (diferentes versiones, arquitecturas o configuraciones) se relacionan entre sí
• Impacto de la imagen base: Ver exactamente cómo los cambios en una imagen base afectan a múltiples imágenes derivadas
• Oportunidades de optimización: Identificar componentes compartidos que podrían aprovecharse mejor entre variantes de imágenes

Casos de uso adicionales

• Auditoría de seguridad: Identifique exactamente cuándo se introdujeron paquetes o configuraciones vulnerables y rastree hasta instrucciones de compilación específicas.
• Optimización de imagen: Analice la estructura de capas para encontrar operaciones redundantes o archivos grandes que puedan consolidarse, ayudando a reducir el tamaño de la imagen.
• Gestión de dependencias: Controle cuándo se agregaron, actualizaron o eliminaron dependencias a lo largo del historial de la imagen.
• Mejora del proceso de compilación: Examine la composición de capas para optimizar instrucciones de Dockerfile y mejorar el caché y tamaño de la imagen.
• Comparación entre imágenes: Convierta varias imágenes relacionadas en repositorios Git y utilice las herramientas de comparación de Git para analizar sus diferencias y similitudes.

Instalación

Gestores de paquetes

#### macOS / Linux (Homebrew)

brew tap virviil/oci2git
brew install oci2git

#### Debian / Ubuntu

Descargue e instale el paquete .deb desde la última versión:

# For amd64 (x86_64)
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git_VERSION_amd64.deb
sudo dpkg -i oci2git_VERSION_amd64.deb
For arm64
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git_VERSION_arm64.deb
sudo dpkg -i oci2git_VERSION_arm64.deb

#### Arch Linux (AUR)

# Using yay
yay -S oci2git-bin
Using paru
paru -S oci2git-bin
Manual installation
git clone https://aur.archlinux.org/oci2git-bin.git
cd oci2git-bin
makepkg -si

Binarios precompilados

Descarga el binario apropiado para tu plataforma desde la última versión:

# Linux x86_64
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git-linux-x86_64.tar.gz
tar xzf oci2git-linux-x86_64.tar.gz
sudo mv oci2git-linux-x86_64 /usr/local/bin/oci2git
chmod +x /usr/local/bin/oci2git
macOS (Apple Silicon)
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git-darwin-aarch64.tar.gz
tar xzf oci2git-darwin-aarch64.tar.gz
sudo mv oci2git-darwin-aarch64 /usr/local/bin/oci2git
chmod +x /usr/local/bin/oci2git

Desde Crates.io

cargo install oci2git

Desde la fuente

# Clone the repository
git clone https://github.com/virviil/oci2git.git
cd oci2git
Install locally
cargo install --path .

Uso

oci2git [OPTIONS] 
oci2git convert [OPTIONS] 
oci2git fsbom [OPTIONS] 

convert — Imagen OCI → Repositorio Git

oci2git convert [OPTIONS] 
or simply:
oci2git 

Opciones: -o, --output

Directorio de salida para el repositorio Git [por defecto: ./container_repo] -e, --engine Motor de contenedores a usar (docker, nerdctl, tar) [por defecto: docker] -v, --verbose Modo detallado (-v para información, -vv para depuración, -vvv para rastreo)

fsbom — Lista de materiales del sistema de archivos

oci2git fsbom [OPTIONS] 

Opciones: -o, --output

Ruta de salida para el archivo BOM en YAML [por defecto: ./fsbom.yml] -e, --engine Motor de contenedores a usar (docker, nerdctl, tar) [por defecto: docker] -v, --verbose Modo detallado (-v para info, -vv para depuración, -vvv para rastreo)

Variables de entorno: TMPDIR Establece esta variable de entorno para cambiar la ubicación por defecto usada para el procesamiento de datos intermedios. Esto depende de la plataforma (por ejemplo, TMPDIR en Unix/macOS, TEMP o TMP en Windows).

Ejemplos

Convertir

Usando el motor Docker (por defecto):

oci2git ubuntu:latest
or explicitly:
oci2git convert ubuntu:latest -o ./ubuntu-repo

Usando un archivo tarball de imagen ya descargado:

oci2git convert -e tar -o ./ubuntu-repo /path/to/ubuntu-latest.tar

El motor tar espera un tarball en formato OCI válido, que típicamente se crea con docker save:

# Create a tarball from a local Docker image
docker save -o ubuntu-latest.tar ubuntu:latest
Convert the tarball to a Git repository
oci2git convert -e tar -o ./ubuntu-repo ubuntu-latest.tar

Esto creará un repositorio Git en ./ubuntu-repo que contiene:

• Image.md - Metadatos completos sobre la imagen en formato Markdown
• rootfs/ - El contenido del sistema de archivos del contenedor

El historial de Git refleja el historial de capas del contenedor:

• El primer commit contiene solo el archivo Image.md con todos los metadatos
• Cada commit posterior representa una capa de la imagen original
• Los commits incluyen el comando Dockerfile como mensaje del commit

Lista de materiales del sistema de archivos (fsbom)

Genera un YAML que enumera cada archivo introducido o modificado por capa:

oci2git fsbom ubuntu:latest -o ubuntu.yml

Usando un archivo tarball:

oci2git fsbom -e tar image.tar -o image-bom.yml

La salida YAML enumera cada capa con sus entradas etiquetadas por tipo (file, hardlink, symlink, directory) y estado (n:uid:gid para nuevos, m:uid:gid para modificados). Los archivos eliminados (OCI whiteouts) se excluyen.

layers:
  
index: 0
    
command: "ADD rootfs.tar.gz / # buildkit"
    digest: "sha256:45f3ea58..."
    entries:
      
type: file
        
path: "bin/busybox"
        size: 919304
        mode: 493
        stat: "n:0:0"
      
type: hardlink
        
path: "bin/sh"
        target: "bin/busybox"
        stat: "n:0:0"
      
type: symlink
        
path: "lib64"
        target: "lib"
        stat: "n:0:0"
  
index: 1
    
command: "RUN apk add --no-cache curl"
    digest: "sha256:..."
    entries:
      
type: file
        
path: "usr/bin/curl"
        size: 204800
        mode: 493
        stat: "n:0:0"
      
type: file
        
path: "etc/apk/world"
        size: 32
        mode: 420
        stat: "m:0:0"

Estructura del Repositorio

repository/
├── .git/
├── Image.md     # Complete image metadata
└── rootfs/      # Filesystem content from the container

Requisitos

• Rust edición 2021
• Docker CLI (para soporte del motor Docker)
• Git

Licencia

MIT

[documentación]: https://docs.rs/oci2git/

--- Tranlated By Open Ai Tx | Last indexed: 2026-04-02 ---