Security & Untrusted Files

package bookshelf.security;

import org.apache.poi.hssf.usermodel.HSSFWorkbook;
import org.apache.poi.hwpf.HWPFDocument;
import org.apache.poi.openxml4j.util.ZipSecureFile;
import org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource;
import org.apache.poi.util.DefaultTempFileCreationStrategy;
import org.apache.poi.util.IOUtils;
import org.apache.poi.util.TempFile;

/** Process-wide POI limits for a service that opens uploaded files. Call once at startup. */
public final class PoiLimits {

    private PoiLimits() {
    }

    public static void apply() {
        // zip bombs in .xlsx / .docx
        ZipSecureFile.setMinInflateRatio(0.01);          // compressed / expanded; default 0.01
        ZipSecureFile.setMaxEntrySize(100L * 1024 * 1024); // 100 MiB per entry; default 4 GiB (0xFFFFFFFF)
        ZipSecureFile.setMaxTextSize(10L * 1024 * 1024);   // 10 MiB of text per extraction; default 10 MiB
        ZipSecureFile.setMaxFileCount(2_000);              // zip entries; default 1 000

        // length-prefixed records in OLE2 files and in the OOXML parts that POI reads into byte[]
        IOUtils.setByteArrayMaxOverride(50 * 1024 * 1024);  // largest single array POI may allocate
        IOUtils.setMaxByteArrayInitSize(1024 * 1024);       // initial allocation, grown as data arrives
        HSSFWorkbook.setMaxRecordLength(50 * 1024 * 1024);
        HWPFDocument.setMaxRecordLength(50 * 1024 * 1024);
    }

    /** POI writes temp files for large parts and for SXSSF; keep them where only this service can read them. */
    public static void useTempDirectory(java.nio.file.Path privateDir) throws java.io.IOException {
        java.nio.file.Files.createDirectories(privateDir);
        TempFile.setTempFileCreationStrategy(new DefaultTempFileCreationStrategy(privateDir.toFile()));
        ZipInputStreamZipEntrySource.setEncryptTempFiles(true); // temp files for zip entries are encrypted
    }

    public static String describe() {
        return "minInflateRatio=" + ZipSecureFile.getMinInflateRatio()
                + " maxEntrySize=" + ZipSecureFile.getMaxEntrySize()
                + " graceEntrySize=" + ZipSecureFile.getGraceEntrySize()
                + " maxTextSize=" + ZipSecureFile.getMaxTextSize()
                + " maxFileCount=" + ZipSecureFile.getMaxFileCount()
                + " byteArrayMaxOverride=" + IOUtils.getByteArrayMaxOverride()
                + " maxByteArrayInitSize=" + IOUtils.getMaxByteArrayInitSize()
                + " hssfMaxRecordLength=" + HSSFWorkbook.getMaxRecordLength();
    }
}

defaults : minInflateRatio=0.01 maxEntrySize=4294967295 graceEntrySize=102400 maxTextSize=10485760 maxFileCount=1000 byteArrayMaxOverride=-1 maxByteArrayInitSize=-1 hssfMaxRecordLength=100000
applied  : minInflateRatio=0.01 maxEntrySize=104857600 graceEntrySize=102400 maxTextSize=10485760 maxFileCount=2000 byteArrayMaxOverride=52428800 maxByteArrayInitSize=1048576 hssfMaxRecordLength=52428800

package bookshelf.security;

import java.io.OutputStream;
import java.io.StringReader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipOutputStream;

import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import org.apache.poi.ooxml.POIXMLTypeLoader;
import org.apache.poi.util.XMLHelper;
import org.apache.xmlbeans.XmlOptions;
import org.w3c.dom.Document;
import org.xml.sax.InputSource;

public class XmlHardening {

    public static void main(String[] args) throws Exception {
        String xxe = """
                <?xml version="1.0"?>
                <!DOCTYPE title [ <!ENTITY secret SYSTEM "file:///etc/hosts"> ]>
                <title>&secret;</title>""";
        // 1. XML you parse yourself next to POI (a custom part, a sidecar file): use POI's factories
        try {
            Document d = XMLHelper.newDocumentBuilder().parse(new InputSource(new StringReader(xxe)));
            System.out.println("parsed: " + d.getDocumentElement().getTextContent());
        } catch (Exception e) {
            System.out.println("XMLHelper : " + e.getClass().getSimpleName() + ": " + e.getMessage());
        }
        // 2. the same input through the JDK defaults, to show why the helper matters
        Document d = javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder()
                .parse(new InputSource(new StringReader(xxe)));
        System.out.println("JDK default: entity expanded, " + d.getDocumentElement().getTextContent().length() + " characters of the local file read");

        // 3. the options POI hands to XMLBeans for every OOXML part
        XmlOptions opts = POIXMLTypeLoader.DEFAULT_XML_OPTIONS;
        System.out.println("disallowDocTypeDeclaration=" + opts.disallowDocTypeDeclaration()
                + " entityExpansionLimit=" + opts.getEntityExpansionLimit()
                + " loadStripComments=" + opts.isLoadStripComments()
                + " loadStripProcinsts=" + opts.isLoadStripProcinsts());

        // 4. a workbook whose sheet part declares a DOCTYPE is refused by POI itself
        Path src = Files.createTempFile("xxe", ".xlsx");
        try (Workbook wb = new XSSFWorkbook(); OutputStream os = Files.newOutputStream(src)) {
            wb.createSheet("Books").createRow(0).createCell(0).setCellValue("Dune");
            wb.write(os);
        }
        Path hostile = Files.createTempFile("xxe-doctype", ".xlsx");
        try (ZipFile zf = new ZipFile(src.toFile()); ZipOutputStream zo = new ZipOutputStream(Files.newOutputStream(hostile))) {
            for (var en = zf.entries(); en.hasMoreElements();) {
                ZipEntry e = en.nextElement();
                String xml = new String(zf.getInputStream(e).readAllBytes(), StandardCharsets.UTF_8);
                if (e.getName().equals("xl/worksheets/sheet1.xml")) {
                    xml = xml.replaceFirst("\\?>", "?>\n<!DOCTYPE worksheet [ <!ENTITY secret SYSTEM \"file:///etc/hosts\"> ]>");
                }
                zo.putNextEntry(new ZipEntry(e.getName()));
                zo.write(xml.getBytes(StandardCharsets.UTF_8));
                zo.closeEntry();
            }
        }
        try (Workbook wb = new XSSFWorkbook(hostile.toFile())) {
            System.out.println("opened, first cell = " + wb.getSheetAt(0).getRow(0).getCell(0));
        } catch (Throwable t) {
            System.out.println("XSSFWorkbook: " + t.getClass().getSimpleName() + " / cause " + t.getCause());
        }
    }
}

XMLHelper : SAXParseException: DOCTYPE is disallowed when the feature "http://apache.org/xml/features/disallow-doctype-decl" set to true.
JDK default: entity expanded, 213 characters of the local file read
disallowDocTypeDeclaration=true entityExpansionLimit=1 loadStripComments=true loadStripProcinsts=true
XSSFWorkbook: POIXMLException / cause org.apache.xmlbeans.XmlException: error: DOCTYPE is disallowed when the feature "http://apache.org/xml/features/disallow-doctype-decl" set to true.

package bookshelf.security;

import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Enumeration;
import java.util.HashSet;
import java.util.Locale;
import java.util.Set;

import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
import org.apache.poi.openxml4j.util.ZipSecureFile;
import org.apache.poi.poifs.filesystem.DirectoryNode;
import org.apache.poi.poifs.filesystem.FileMagic;
import org.apache.poi.poifs.filesystem.POIFSFileSystem;

/**
 * Cheap checks that run before the document is parsed. They look at the name, the size, the first
 * bytes and the zip directory (or the OLE2 directory); they never build a Workbook or a document.
 */
public final class UploadValidator {

    public enum Kind { XLSX, XLS, DOCX, DOC }

    private static final long MAX_UPLOAD_BYTES = 10L * 1024 * 1024;
    private static final int MAX_ZIP_ENTRIES = 2_000;
    private static final int MAX_CONTENT_TYPES_BYTES = 256 * 1024;

    /** Extension allow-list. Macro-enabled extensions (xlsm, docm, xlsb, xltm) are deliberately absent. */
    private static final Set<String> ALLOWED = Set.of("xlsx", "xls", "docx", "doc");

    public Kind validate(Path stored, String clientFileName) throws UploadRejectedException {
        Kind byName = kindFromName(clientFileName);

        try {
            if (Files.size(stored) > MAX_UPLOAD_BYTES) {
                throw new UploadRejectedException("The file is larger than 10 MiB.");
            }
            FileMagic magic = FileMagic.valueOf(stored.toFile());
            boolean ooxml = byName == Kind.XLSX || byName == Kind.DOCX;
            if (ooxml && magic != FileMagic.OOXML || !ooxml && magic != FileMagic.OLE2) {
                throw new UploadRejectedException("The content does not match the file extension.");
            }
            if (ooxml) {
                checkZip(stored, byName);
            } else {
                checkOle2(stored, byName);
            }
            return byName;
        } catch (UploadRejectedException e) {
            throw e;
        } catch (Throwable t) { // corrupt input can raise runtime exceptions and even errors
            throw new UploadRejectedException("The file is not a valid Office document.", t);
        }
    }

    private static Kind kindFromName(String clientFileName) throws UploadRejectedException {
        // use the name only to pick the expected type; never to build a storage path
        String name = clientFileName == null ? "" : clientFileName.toLowerCase(Locale.ROOT);
        int dot = name.lastIndexOf('.');
        String ext = dot < 0 ? "" : name.substring(dot + 1);
        if (!ALLOWED.contains(ext)) {
            throw new UploadRejectedException("Only .xlsx, .xls, .docx and .doc files are accepted.");
        }
        return Kind.valueOf(ext.toUpperCase(Locale.ROOT));
    }

    private static void checkZip(Path stored, Kind kind) throws IOException, UploadRejectedException {
        String mainPart = kind == Kind.XLSX ? "xl/workbook.xml" : "word/document.xml";
        Set<String> names = new HashSet<>();
        boolean hasMain = false;
        try (ZipSecureFile zip = new ZipSecureFile(stored.toFile())) {
            Enumeration<ZipArchiveEntry> entries = zip.getEntries();
            while (entries.hasMoreElements()) {
                ZipArchiveEntry entry = entries.nextElement();
                String name = entry.getName();
                if (names.size() >= MAX_ZIP_ENTRIES) {
                    throw new UploadRejectedException("The document has too many parts.");
                }
                if (!names.add(name.toLowerCase(Locale.ROOT))) {
                    throw new UploadRejectedException("The document contains duplicate parts.");
                }
                if (name.startsWith("/") || name.contains("..") || name.contains("\\")) {
                    throw new UploadRejectedException("The document contains an unsafe part name.");
                }
                if (name.toLowerCase(Locale.ROOT).endsWith("vbaproject.bin")) {
                    throw new UploadRejectedException("Documents with macros are not accepted.");
                }
                hasMain |= name.equals(mainPart);
            }
            if (!hasMain) {
                throw new UploadRejectedException("The file is not a " + kind + " document.");
            }
            ZipArchiveEntry types = zip.getEntry("[Content_Types].xml");
            if (types == null) {
                throw new UploadRejectedException("The file is not an Office document.");
            }
            try (InputStream in = zip.getInputStream(types)) {
                String xml = new String(in.readNBytes(MAX_CONTENT_TYPES_BYTES), StandardCharsets.UTF_8);
                if (xml.contains("macroEnabled")) {
                    throw new UploadRejectedException("Macro-enabled documents are not accepted.");
                }
            }
        }
    }

    private static void checkOle2(Path stored, Kind kind) throws IOException, UploadRejectedException {
        try (POIFSFileSystem fs = new POIFSFileSystem(stored.toFile(), true)) {
            DirectoryNode root = fs.getRoot();
            String mainStream = kind == Kind.XLS ? "Workbook" : "WordDocument";
            if (!root.hasEntry(mainStream) && !(kind == Kind.XLS && root.hasEntry("Book"))) {
                throw new UploadRejectedException("The file is not a " + kind + " document.");
            }
            if (root.hasEntry("_VBA_PROJECT_CUR") || root.hasEntry("Macros") || root.hasEntry("VBA")) {
                throw new UploadRejectedException("Documents with macros are not accepted.");
            }
        }
    }
}

package bookshelf.security;

/** A rejected upload; the message is safe to show to the user, the cause is for the log only. */
public class UploadRejectedException extends Exception {

    public UploadRejectedException(String userMessage) {
        super(userMessage);
    }

    public UploadRejectedException(String userMessage, Throwable cause) {
        super(userMessage, cause);
    }
}

books.xlsx   -> XLSX
books.xls    -> XLS
books.xlsx   -> rejected: The content does not match the file extension.      (an .xls named .xlsx)
books.xlsx   -> rejected: The content does not match the file extension.      (MZ header, not a workbook)
books.xlsm   -> rejected: Only .xlsx, .xls, .docx and .doc files are accepted.
books.xlsx   -> rejected: Documents with macros are not accepted.              (contains xl/vbaProject.bin)
books.xlsx   -> XLSX                                                           (the zip bomb: normal directory)

package bookshelf.security;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

import org.apache.poi.ss.usermodel.DataFormatter;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.ss.usermodel.WorkbookFactory;

/** Parses a validated upload on a bounded worker, with a timeout, and converts every failure. */
public final class SafeWorkbookReader implements AutoCloseable {

    private final ExecutorService pool = Executors.newFixedThreadPool(2, r -> {
        Thread t = new Thread(r, "untrusted-parse");
        t.setDaemon(true); // a stuck parse must not keep the JVM alive
        return t;
    });

    public List<String> readFirstColumn(Path stored, long timeoutSeconds) throws UploadRejectedException {
        Future<List<String>> future = pool.submit(() -> parse(stored));
        try {
            return future.get(timeoutSeconds, TimeUnit.SECONDS);
        } catch (TimeoutException e) {
            future.cancel(true); // interrupts, but POI does not check for interruption
            throw new UploadRejectedException("The file took too long to process.", e);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new UploadRejectedException("Processing was interrupted.", e);
        } catch (ExecutionException e) {
            // e.getCause() may be an Error such as StackOverflowError or OutOfMemoryError
            throw new UploadRejectedException("The file could not be read.", e.getCause());
        }
    }

    private static List<String> parse(Path stored) throws Exception {
        List<String> titles = new ArrayList<>();
        DataFormatter formatter = new DataFormatter();
        try (Workbook wb = WorkbookFactory.create(stored.toFile(), null, true)) { // read-only
            Sheet sheet = wb.getSheetAt(0);
            for (Row row : sheet) {
                if (row.getCell(0) != null) {
                    titles.add(formatter.formatCellValue(row.getCell(0)));
                }
            }
        }
        return titles;
    }

    @Override
    public void close() {
        pool.shutdownNow();
    }
}

package bookshelf.security;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

/** The whole pipeline: stream to a private temp file, validate, parse with a timeout, always clean up. */
public final class BookImportService implements AutoCloseable {

    private static final long MAX_BYTES = 10L * 1024 * 1024;

    private final Path uploadDir;
    private final UploadValidator validator = new UploadValidator();
    private final SafeWorkbookReader reader = new SafeWorkbookReader();

    public BookImportService(Path uploadDir) {
        this.uploadDir = uploadDir; // a directory only this service can read, outside the web root
    }

    public List<String> importTitles(InputStream upload, String clientFileName) throws UploadRejectedException {
        Path stored = null;
        try {
            stored = Files.createTempFile(uploadDir, "upload-", ".bin"); // the client name is never used in a path
            copyAtMost(upload, stored, MAX_BYTES);
            validator.validate(stored, clientFileName);
            return reader.readFirstColumn(stored, 20);
        } catch (IOException e) {
            throw new UploadRejectedException("The upload could not be stored.", e);
        } finally {
            if (stored != null) {
                try {
                    Files.deleteIfExists(stored);
                } catch (IOException ignored) {
                    // logged in a real service
                }
            }
        }
    }

    private static void copyAtMost(InputStream in, Path target, long max) throws IOException, UploadRejectedException {
        byte[] buffer = new byte[8192];
        long total = 0;
        try (OutputStream out = Files.newOutputStream(target)) {
            int n;
            while ((n = in.read(buffer)) != -1) {
                total += n;
                if (total > max) {
                    throw new UploadRejectedException("The file is larger than 10 MiB.");
                }
                out.write(buffer, 0, n);
            }
        }
    }

    @Override
    public void close() {
        reader.close();
    }
}

service ok   : 7 rows
service big  : The file is larger than 10 MiB.
service bomb : The file could not be read.
left in uploads: 0