Skip to content

Compress4J

Maven Central Version Build Status Quality Gate Status Coverage Status

Create and extract archives in Java, with guards against Zip Slip and decompression bombs. Compress4J is a thin builder-style API on top of Apache Commons Compress, and a maintained successor to JArchiveLib.

  • Safe extraction. Path traversal (Zip Slip) is rejected, escaping symlinks are rejected by default, and extraction has default limits (1,000,000 entries, expansion ratio 100) that stop decompression bombs. See Safe extraction of untrusted archives.

  • One API for every format. Tar, .tar.gz, .tar.bz2, .tar.xz, .tar.lzma, .tar.lz4, .tar.zst, Zip, 7z, AR, CPIO and more share the same builders.

  • Streams. Read entries as a Java Stream, write from a Stream of files or another archive, repack between formats.

  • Java 17+, JPMS-ready, published to Maven Central.

At a glance

implementation("com.hominux:compress4j:<version>")

Extract an untrusted archive. Zip Slip entries and escaping symlinks fail with UnsafeEntryException, and decompression bombs with LimitExceededException (the default ratio plus the size limit below). Both extend UnsafeInputException, and nothing is written outside outputDir:

try (TarArchiveExtractor extractor = TarArchiveExtractor.builder(Path.of("untrusted.tar.gz"))
        .maxTotalSize(1024L * 1024 * 1024)
        .build()) {
    extractor.extract(Path.of("outputDir"));
} catch (UnsafeInputException e) {
    System.err.println("Rejected: " + e.getMessage());
}

Installation

Requires Java 17 or later.

Gradle:

dependencies {
    implementation("com.hominux:compress4j:<version>")

    // Only needed for the .xz, .tar.xz, .lzma and .tar.lzma formats
    implementation("org.tukaani:xz:<version>")

    // Only needed for the .zst and .tar.zst formats
    implementation("com.github.luben:zstd-jni:<version>")

    // Only needed to read Brotli (.br)
    implementation("org.brotli:dec:<version>")
}

Maven:

<dependency>
    <groupId>com.hominux</groupId>
    <artifactId>compress4j</artifactId>
    <version>VERSION</version>
</dependency>

<!-- Only needed for the .xz, .tar.xz, .lzma and .tar.lzma formats -->
<dependency>
    <groupId>org.tukaani</groupId>
    <artifactId>xz</artifactId>
    <version>XZ_VERSION</version>
</dependency>

<!-- Only needed for the .zst and .tar.zst formats -->
<dependency>
    <groupId>com.github.luben</groupId>
    <artifactId>zstd-jni</artifactId>
    <version>ZSTD_JNI_VERSION</version>
</dependency>

<!-- Only needed to read Brotli (.br) -->
<dependency>
    <groupId>org.brotli</groupId>
    <artifactId>dec</artifactId>
    <version>BROTLI_DEC_VERSION</version>
</dependency>

Quick start

Create a gzip-compressed tar and extract it:

try (TarArchiveCreator creator = TarArchiveCreator.builder(Path.of("example.tar.gz"))
        .compression(Compression.gzip())
        .build()) {
    creator.addDirectoryRecursively(Path.of("exampleDir"));
    creator.addFile(Path.of("path/to/file.txt"));
}

try (TarArchiveExtractor extractor = TarArchiveExtractor.builder(Path.of("example.tar.gz")).build()) {
    extractor.extract(Path.of("outputDir"));
}

Compress or decompress a single file with any codec. Decompressor detects the codec from the stream. Input with no detectable signature (deflate, LZMA, LZ4 block, raw Snappy) passes through unchanged, so name those codecs with Decompressor.builder(path, Compression.lzma()):

try (Compressor compressor = Compressor.builder(Path.of("file.txt.zst"), Compression.zstd().level(6))
        .build()) {
    compressor.write(Path.of("file.txt"));
}

try (Decompressor decompressor = Decompressor.builder(Path.of("file.txt.zst")).build()) {
    decompressor.write(Path.of("copy.txt"));
}

Safe extraction of untrusted archives

Extracting an archive you do not trust? Path traversal, escaping symlinks and decompression bombs are bounded by default: 1,000,000 entries and an expansion ratio of 100 after the first MiB. Add size limits as described in SECURITY.md:

try (TarArchiveExtractor extractor = TarArchiveExtractor.builder(Path.of("untrusted.tar.gz"))
        .maxEntries(10_000)
        .maxEntrySize(100L * 1024 * 1024)
        .maxTotalSize(1024L * 1024 * 1024)
        .build()) {
    extractor.extract(Path.of("outputDir"));
}

Breaching a limit throws LimitExceededException. It and UnsafeEntryException (traversal, escaping symlinks) both extend UnsafeInputException, which an error handler cannot suppress. Raise maxRatio for legitimate highly compressible data, or pass limits(ExtractionLimits.noLimits()) for trusted input.

Pack200 is the one codec the limits do not bound: it unpacks the whole JAR in build(), before any metering. Decompressor never detects it, so choose Compression.pack200() only for input you trust.

Supported formats

AR, CPIO, 7z, ARJ (read-only), UNIX dump (read-only), Deflate, Deflate64 (read-only), BZip2, Brotli (read-only), Gzip, LZ4, LZMA, Pack200 (trusted input only, see Safe extraction of untrusted archives), Snappy, Tar (plain, .tar.gz, .tar.bz2, .tar.xz, .tar.lzma, .tar.lz4, .tar.zst, .tar.Z read-only), Unix compress (.Z, read-only), XZ, Zstandard and Zip.

Documentation

Full documentation, with an example per format, is at https://hominux.com/docs/compress4j/latest/.

It is built with Antora; the pages live in docs/modules/ROOT/pages and the examples they include are compiled from src/examples/java.

Upgrading from 4.x? Read the 4.x to 5.0 migration guide.

Contributing

See CONTRIBUTING.adoc. Commit subjects and pull request titles follow Conventional Commits — they drive the released version, so feat: publishes a minor release, fix: a patch, and anything else publishes nothing.

Releases

Sponsor this project

Packages

Used by

Contributors

Languages