PDF 문서의 잘못된 가림(블랙박스 처리)을 탐지하는 Python 라이브러리 X-ray

• PDF 문서의 부적절한 가림 처리를 자동으로 찾아내는 Python 라이브러리로, 텍스트가 단순히 검은 사각형으로 덮여 있는 경우를 식별
• Free Law Project가 수백만 개의 PDF를 수집하는 과정에서 발견된 반복적 문제를 해결하기 위해 개발
• 명령줄 또는 Python 코드에서 실행 가능하며, 결과를 JSON 또는 Python 객체 형태로 반환
• 내부적으로 PyMuPDF를 사용해 PDF의 사각형, 텍스트, 색상 정보를 분석하여 가림이 실제로 텍스트를 숨기는지 판단
• 법률 문서나 공개 자료의 개인정보 노출 방지를 위한 자동 검증 도구로 활용 가치가 높음

개요

• x-ray는 PDF 파일 내의 잘못된 가림(redaction) 을 탐지하는 Python 라이브러리
  • 사용자가 PDF 경로를 입력하면, 가림이 제대로 이루어지지 않은 영역을 찾아냄
  • 결과는 페이지별로 좌표(bbox)와 해당 영역의 텍스트(text)를 포함한 JSON 형태로 출력

개발 배경

• Free Law Project는 수백만 개의 PDF를 수집하는 과정에서 가림이 제대로 되지 않은 문서를 다수 발견
  • 일부 사용자는 텍스트를 삭제하지 않고 검은 사각형이나 하이라이트로 덮는 방식을 사용
  • 이 경우, 사각형 아래의 텍스트를 선택하면 원문이 그대로 노출됨
• 이러한 문제의 빈도를 파악하기 위해 x-ray 도구를 제작

사용 방법

• 설치
  • pip install x-ray 또는 uv add x-ray 명령으로 설치 가능
• 명령줄 실행
  • xray path/to/file.pdf 형태로 실행하면 JSON 결과 출력
  • URL 입력 시 원격 PDF 다운로드 후 검사 수행
  • 여러 URL을 한 번에 검사하려면 xargs -n 1 xray < urls.txt 사용
• Python 코드 내 사용
  • xray.inspect("file.pdf") 호출 시 Python 객체로 결과 반환
  • 입력값이 문자열이면 로컬 파일, https://로 시작하면 URL, bytes면 메모리 내 PDF로 처리
  • bytes 타입으로 파일 경로를 전달하면 작동하지 않음

동작 원리

• 내부적으로 PyMuPDF를 이용해 PDF를 분석
  1. PDF 내의 사각형(rectangle) 탐색
  2. 동일 위치의 문자(letter) 탐색
  3. 사각형을 이미지로 렌더링
  4. 사각형이 단일 색상으로 채워져 있으면 잘못된 가림으로 판단
• PDF 구조가 복잡해 완벽한 탐지는 어렵지만, 지속적인 개선 진행 중
• 프로젝트는 기부 및 후원을 통해 유지

기여 및 배포

• GitHub의 issues 목록을 통해 미지원 사례나 개선 요청 확인 가능
• 첫 기여 전에는 기여자 라이선스 동의서(CLA) 서명 필요
• 배포는 GitHub Actions를 통해 자동화되어 있으며, 수동 배포 시 poetry publish --build 명령 사용

라이선스

• BSD 라이선스로 공개되어, 다른 프로젝트에 자유롭게 통합 가능
• Pull Request 및 기능 제안 환영, GitHub 웹 인터페이스에서 직접 수정 가능