PEP 721 – 소스 배포판 추출에 tarfile.data_filter 사용하기

Author:

Petr Viktorin <encukou at gmail.com>

PEP-Delegate:

Paul Moore <p.f.moore at gmail.com>

Status:

Final

Type:

Standards Track

Topic:

Packaging

Requires:

706

Created:

12-Jul-2023

Python-Version:

3.12

Post-History:

04-Jul-2023

Resolution:

02-Aug-2023

---

Table of Contents

• 초록
• 동기
• 근거
  • 패치되지 않은 Python 버전
  • 권한
• 명세
  • data 필터를 사용한 압축 해제
  • data 필터 없이 압축 해제하기
  • 추가 힌트
• 하위 호환성
• 보안 영향
• 교육 방법
• 참조 구현
• 기각된 아이디어
• 미해결 문제
• Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical spec, Source distribution archive features, is maintained on the PyPA specs page.

×

See the PyPA specification update process for how to propose changes.

초록

소스 배포판 아카이브를 추출할 때는 일반적으로 PEP 706에서 추가된 data 필터를 사용해야 합니다. 이 PEP에서는 세부 사항을 명확히 하고, 이 필터를 직접 사용할 수 없는 도구의 동작을 규정합니다.

동기

소스 배포판인 sdist는 tar 아카이브로 정의됩니다.

tar 형식은 Unix 계열 파일의 모든 메타데이터를 담도록 설계되었습니다. 이러한 메타데이터 중 일부는 위험하거나, 소스 코드에 불필요하거나, 플랫폼에 따라 달라집니다. PEP 706에서 설명한 것처럼, tarball을 추출할 때는 항상 허용되는 기능을 제한하거나, tarball에 모든 제어 권한을 명시적으로 부여해야 합니다.

근거

소스 배포판에는 PEP 706에서 도입된 data 필터로 충분합니다. 이 필터는 git과 zip(둘 다 패키징 워크플로에서 흔히 사용됩니다)보다 약간 더 많은 기능을 허용합니다.

하지만 모든 도구가 data 필터를 사용할 수 있는 것은 아니므로, 이 PEP에서는 명시적인 기대 사항을 규정합니다. 허용하기에 너무 위험하다고 판단되는 경우를 제외하면, pip download와 setuptools.archive_util.unpack_tarfile의 현재 동작이 유효하도록 하는 것이 목표입니다. 또 다른 고려 사항은 Python이 아닌 도구에서 쉽게 구현할 수 있는지입니다.

패치되지 않은 Python 버전

tarfile 필터가 없는 Python에서 실행될 때 도구는 이 PEP를 무시해도 됩니다.

이 기능은 python.org에서 지원하는 모든 Python 버전에 백포트되었습니다. 이 기능을 서드파티 라이브러리에 벤더링하는 것은 까다로우며, 모든 도구에 그렇게 하도록 강제해서는 안 됩니다. 이에 따라 보안 업데이트를 따라가야 할 책임이 도구에서 사용자에게로 넘어갑니다.

권한

일반적인 도구(git, zip)는 Unix 권한(모드 비트)을 보존하지 않습니다. 사용자에게 sdists에서 이러한 권한에 의존하지 말라고 안내하고, 도구가 권한을 비교적 자유롭게 다루도록 허용하는 것이 타당해 보입니다.

유일한 예외는 실행 권한입니다. 도구가 이 권한을 보존하도록 권장하지만, 요구하지는 않습니다. 스크립트는 일반적으로 플랫폼에 특화되어 있으므로, 스크립트를 실행 가능한 상태로 유지하는 것은 도구별 동작이라고 하는 것이 적절해 보입니다.

git은 실행 가능 여부를 보존하지만, zip은(따라서 wheel도) 기본적으로 이를 보존하지 않는다는 점에 유의하십시오. (“외부 속성”에 이를 인코딩할 수는 있지만, Python의 ZipFile.extract는 이를 반영하지 않습니다.)

명세

다음 내용이 PyPA 소스 배포판 형식 명세에 “소스 배포판 아카이브 기능”이라는 새 제목 아래에 추가됩니다:

tar 파일을 있는 그대로 추출하는 것은 위험하고 그 결과가 플랫폼에 따라 다르므로, 소스 배포판의 아카이브 기능은 제한됩니다.

data 필터를 사용한 압축 해제

소스 배포판을 추출할 때 도구는 반드시 tarfile.data_filter를 사용하거나(예: TarFile.extractall(..., filter='data')), 아래의 data 필터를 사용하지 않는 압축 해제 절을 따라야 합니다.

예외적으로, hasattr(tarfile, 'data_filter') (PEP 706)가 없는 Python 인터프리터에서는 평소에 그 필터를 (직접 또는 간접적으로) 사용하는 도구가 사용자에게 경고하고 이 명세를 무시할 수 있습니다(MAY). 이 경우 사용성(예: 아카이브를 전적으로 신뢰함)과 보안(예: 압축 해제를 거부함) 사이의 절충은 도구에 맡깁니다.

data 필터 없이 압축 해제하기

data 필터를 직접 사용하지 않는 도구(예: 하위 호환성을 위해, 추가 기능을 허용하기 위해, 또는 Python을 사용하지 않기 때문에)는 이 절을 따라야 합니다(MUST). (이 글을 쓰는 시점에는 data 필터도 이 절을 따르지만, 앞으로는 서로 어긋날 수 있습니다.)

다음 파일은 sdist 아카이브에서 유효하지 않습니다. 이러한 항목을 만나면 도구는 사용자에게 알려야 하고(SHOULD), 해당 항목의 압축을 해제해서는 안 되며(MUST NOT), 실패로 중단할 수 있습니다(MAY):

• 대상 디렉터리 바깥에 놓이게 될 파일.
• 대상 디렉터리 바깥을 가리키는 링크(심볼릭 링크 또는 하드 링크).
• 장치 파일(파이프 포함).

다음 항목도 유효하지 않습니다. 도구는 이들을 위와 같이 취급할 수 있지만(MAY), 반드시 그래야 하는 것은 아닙니다(NOT REQUIRED):

• 파일 이름이나 링크 대상에 .. 구성 요소가 있는 파일.
• 아카이브에 포함되지 않은 파일을 가리키는 링크.

도구는 링크(심볼릭 링크 또는 하드 링크)를 아카이브의 내용을 사용하여 일반 파일로 압축 해제할 수 있습니다(MAY).

sdist 아카이브를 추출할 때에는 다음을 따릅니다:

• 파일 이름 앞의 슬래시는 제거해야 합니다(MUST). (이는 오늘날 tar 압축 해제의 표준 동작입니다.)
• 각 mode (Unix 권한) 비트에 대해 도구는 다음 중 하나를 해야 합니다(MUST):
  • 새 파일/디렉터리에 대해 (각각) 플랫폼의 기본값을 사용하거나,
  • 아카이브에 따라 비트를 설정하거나,
  • 실행 불가능한 파일에는 rw-r--r-- (0o644)의 비트를, 실행 가능한 파일과 디렉터리에는 rwxr-xr-x (0o755)의 비트를 사용합니다.
• 상위 mode 비트(setuid, setgid, sticky)는 지워야 합니다(MUST).
• 사용자 실행 비트는 보존할 것을 권장합니다(RECOMMENDED).

추가 힌트

도구 작성자는 tarfile 문서의 추가 검증을 위한 힌트가 자신의 도구에 어떻게 적용되는지 검토해 보시기 바랍니다.

하위 호환성

기존 동작은 명세되어 있지 않으며, 도구마다 다르게 처리됩니다. 이 PEP는 기대 사항을 명시적으로 규정합니다.

하위 호환성이 깨지는 것으로 알려진 사례는 없지만, 어딘가의 어떤 프로젝트는 아마 보장되지 않는 세부 사항에 의존하고 있을 것입니다. 이 PEP는 그러한 기능 중 가장 위험한 것을 금지하고, 나머지는 도구별로 정하도록 합니다.

보안 영향

권장되는 data 필터는 일반적인 공격에 대해 안전한 것으로 여겨지며, 앞으로 결함이 발견되면 이 한 곳만 고치면 됩니다.

명시적인 명세에는 data 필터가 제공하는 보호 기능이 포함되어 있습니다.

교육 방법

이 PEP는 패키징 도구 작성자를 대상으로 하며, 이들에게는 PEP와 갱신된 패키징 명세만으로 충분할 것입니다.

참조 구현

미정

기각된 아이디어

아직 없습니다.

미해결 문제

아직 없습니다.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.