XAR/PKG Format

Purpose

This guide covers working with XAR archives and macOS installer packages (PKG) using Excavate.

References

XAR Format

Concepts

XAR (eXtensible ARchive) is an archive format used primarily for macOS installer packages (.pkg). PKG files contain XAR archives with CPIO payloads.

Basic Usage

Extract PKG File

# Basic extraction (CPIO remains compressed)
Excavate::Archive.new('Installer.pkg').extract

# Recursive extraction (payload is extracted)
Excavate::Archive.new('Installer.pkg').extract(recursive_packages: true)

Extract XAR File

Excavate::Archive.new('archive.xar').extract

PKG Structure

macOS installer packages contain:

Installer.pkg
├── Distribution      # Installer configuration XML
├── Resources/        # Images, licenses, etc.
└── Packages/
    └── Package.pkg/
        ├── Bom       # Bill of Materials
        ├── Info.plist
        └── Payload   # CPIO.GZ archive with files

When to Use Recursive

Use recursive_packages: true to extract file contents:

# Without recursive - you get Payload file
Excavate::Archive.new('Installer.pkg').extract
# Result: Installer/Distribution, Installer/Packages/Package.pkg/Payload

# With recursive - Payload is extracted
Excavate::Archive.new('Installer.pkg').extract(recursive_packages: true)
# Result: Installer/Applications/..., Installer/Library/..., etc.

XAR Characteristics

Characteristic Description

Characteristic	Description
File extension	`.xar`, `.pkg`
Compression	GZIP, BZIP2, LZMA, None
Platform	macOS (primary)

File extension

.xar, .pkg

Compression

GZIP, BZIP2, LZMA, None

Platform

macOS (primary)

Common Use Cases

Extract macOS Application

Excavate::Archive.new('App.pkg').extract(
  recursive_packages: true,
  filter: '**/Applications/**/*'
)

Extract Installer Resources

resources = Excavate::Archive.new('Installer.pkg').extract(
  filter: '**/Resources/**/*'
)

Analyze Installer Contents

# List all files in a PKG
Excavate::Archive.new('Installer.pkg').files(recursive_packages: true) do |path|
  puts path
end

CLI Usage

# Extract PKG recursively
excavate -r Installer.pkg

# Extract with filter
excavate -r --filter "**/*.app" Installer.pkg

Technical Details

Excavate uses the Omnizip gem’s XAR support:

Extracts XAR archive structure
Renames Payload to Payload.cpio.gz for recognition
Passes to CPIO/GZIP extractors recursively

Payload Handling

The PKG Payload is a CPIO archive, often GZIP compressed:

# Excavate handles this chain automatically:
# PKG (XAR) → Payload (CPIO.GZ) → Files

Excavate::Archive.new('Installer.pkg').extract(recursive_packages: true)