Author: msahyoun Date: Thu May 28 19:11:27 2026 New Revision: 1934731 Log: PDFBOX-6208: add AGENTS.md and SECURITY.md
Added: pdfbox/trunk/AGENTS.md pdfbox/trunk/SECURITY.md Added: pdfbox/trunk/AGENTS.md ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ pdfbox/trunk/AGENTS.md Thu May 28 19:11:27 2026 (r1934731) @@ -0,0 +1,112 @@ +# Agent Guidance + +This file is read by automated agents (security scanners, code analyzers, +AI assistants) operating on this repository. It points them at the +human-authored references they should consult before producing output. + +## Project Overview + +Apache PDFBox is a Java library for working with PDF documents. It is used +as a dependency (`pdfbox.jar`) in other Java projects and is accessed through +its public Java API. The project also ships several command-line utilities. + +## Branches + +| Branch | Status | Java requirement | Latest release | +|--------|--------|-----------------|----------------| +| `trunk` | Future development (next major version, not yet released) | Java 11+ | — | +| `3.0` | **Actively maintained** — current stable series | Java 8+ | 3.0.7 | +| `2.0` | **Actively maintained** — legacy stable series | Java 6+ | 2.0.36 | + +When evaluating code or reporting issues, note which branch is in scope. +Security fixes are applied to both `3.0` and `2.0`. New features target +`trunk` and `3.0`. + +## Sub-modules + +All branches share the same multi-module Maven structure: + +- `pdfbox/` — Core library (PDF parsing, rendering, text extraction, encryption) +- `fontbox/` — Font handling support library +- `xmpbox/` — XMP metadata support library +- `io/` — I/O utilities shared across modules (`3.0` and `trunk` only) +- `tools/` — Command-line utilities +- `debugger/` / `debugger-app/` — PDF debugger application +- `examples/` — Standalone usage examples +- `benchmark/` — JMH benchmarks + +## Building + +The standard build command is: + +``` +mvn clean install +``` + +To run only the tests without a full install: + +``` +mvn test +``` + +To build or test a specific module, use the `-pl` flag from the root: + +``` +mvn -pl pdfbox test +``` + +Minimum Java version depends on the branch — see the table above. + +## Sensitive Areas + +The following areas have historically been the source of subtle bugs and +security issues. Changes here require extra care and regression testing. +Avoid large refactorings in these areas unless explicitly requested: + +- PDF parsing and xref recovery +- Font parsing and font substitution +- Stream decoding and decompression +- Incremental save/update logic +- Encryption and digital signatures +- Rendering and text extraction ordering + +## Security + +Security model and scope: [SECURITY.md](SECURITY.md), +also published at <https://pdfbox.apache.org/security.html>. + +Agents that scan this repository **must** read the security model before +reporting any finding. In particular, note: + +- Processing malformed PDFs is **partially in scope**: crashes, unchecked + exceptions (`NullPointerException`, `StackOverflowError`), or general + resource consumption from large PDFs are **known limitations**, not + security vulnerabilities. However, disproportionate resource consumption + triggered by small, attacker-controlled inputs may be in scope — see + `SECURITY.md` for the full scope definition. +- Remote code execution or privilege escalation from untrusted PDFs **is** in scope. +- Issues that require the attacker to control the Java application's classpath + or configuration are **out of scope**. + +For a list of known CVEs, see [SECURITY.md](SECURITY.md) or +<https://pdfbox.apache.org/security.html>. + +To report a new vulnerability, send a plain-text email to <[email protected]>. +Do **not** open a public JIRA issue for undisclosed vulnerabilities. + +## Contribution Guidelines + +- Pull requests on this GitHub repository are welcome. +- Bug reports and feature requests go in the + [JIRA issue tracker](https://issues.apache.org/jira/browse/PDFBOX). +- Code must be compatible with the minimum Java version of the target branch + (see table above). +- Follow the existing code style; a Checkstyle configuration is provided in + `pdfbox-checkstyle-5.xml` and an Eclipse formatter in + `pdfbox-eclipse-formatter.xml`. +- Parser, rendering, font, extraction, encryption, or signing fixes should + include a minimal reproducer document where practical, along with regression + tests covering the reported behavior. +- Avoid introducing new runtime dependencies unless necessary. + Security-sensitive or cryptographic dependencies require maintainer review. +- For questions, use the [Users Mailing List](https://pdfbox.apache.org/mailinglists.html). Added: pdfbox/trunk/SECURITY.md ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ pdfbox/trunk/SECURITY.md Thu May 28 19:11:27 2026 (r1934731) @@ -0,0 +1,96 @@ +# Security Scan Guidance + +This document is for AI security scanners and vulnerability researchers to +understand the security model of Apache PDFBox and to avoid false positives. + +The canonical, human-authored version of this information is published at +<https://pdfbox.apache.org/security.html>. + +## Intended Use + +Apache PDFBox is a Java library (`pdfbox.jar`) for creating, manipulating, +and extracting content from PDF documents. It is accessed through its public +Java API by other Java applications. It also ships command-line utilities +built on top of that API. + +## Security Model + +### Processing untrusted PDFs + +PDFBox supports processing of untrusted (potentially malicious or malformed) +PDF files **to a limited degree**: + +- **In scope**: Remote code execution, privilege escalation, unauthorized data + access, sandbox escape, or disproportionate resource amplification (i.e. + small attacker-controlled inputs triggering catastrophic memory or CPU + consumption) caused by processing an untrusted PDF document. These are + genuine vulnerabilities and should be reported privately. + +- **Known limitations (not vulnerabilities)**: Malformed PDFs may cause + unchecked exceptions such as `NullPointerException` or `StackOverflowError`, + or may consume significant memory or CPU relative to document size. General + parser and resource exhaustion issues are treated as robustness limitations + rather than security vulnerabilities. Pure resource exhaustion findings + without privilege escalation, unauthorized access, or disproportionate + amplification (e.g. tenant starvation, indexing-service disruption from a + tiny crafted input) are generally out of scope. + +### Deployment and sandboxing + +Applications embedding PDFBox are expected to apply appropriate operational +controls — such as timeouts, memory limits, process isolation, and sandboxing +— when processing untrusted documents at scale or in multi-tenant environments. +Resource exhaustion risks in those contexts are the responsibility of the +embedding application, not of PDFBox itself. + +### Encryption and cryptography + +PDFBox uses the Java Cryptography Architecture (JCA) and the Bouncy Castle +libraries to implement PDF encryption (RC4, AES-128, AES-256) and digital +signatures. Vulnerabilities in these dependencies should be reported to their +respective projects; PDFBox will incorporate fixes in its releases as needed. +Issues in how PDFBox *uses* those libraries (e.g. incorrect key derivation, +bypass of access permissions) are in scope. + +### Classpath and configuration trust boundary + +PDFBox is a library. The embedding application is assumed to control its own +JVM environment, including classpath, JVM arguments, installed security +providers, classloaders, and dependency resolution. Attacks that require the +attacker to influence any of these are **out of scope**. + +### Command-line utilities + +The command-line tools (`PDFToText`, `PDFDebugger`, etc.) are convenience +wrappers around the library API. Their security scope follows the library +scope above. + +## Previously Disclosed Vulnerabilities + +For a full list of disclosed CVEs, see <https://pdfbox.apache.org/security.html>. + +Scanners should check there before reporting a finding to avoid duplicate reports. + +## Reporting a Vulnerability + +**Do not open a public JIRA issue for an undisclosed vulnerability.** + +Report undisclosed vulnerabilities by sending a plain-text email to: + +``` [email protected] +``` + +Send one email per vulnerability. The PDFBox security team will work with +you privately to confirm and resolve the issue before public disclosure. + +The typical handling process is: + +1. Reporter sends details to <[email protected]>. +2. The PDFBox security team acknowledges receipt and works privately with the + reporter to validate and fix the issue. +3. A new release is prepared that includes the fix. +4. The vulnerability and its fix are publicly announced on the blog and in the CVE database. + +For more detail on the Apache vulnerability handling process, see +<https://www.apache.org/security/committers.html>.
