AI 어시스턴트를 위한 Python 난독화: 실행 가능한 워크스페이스와 디스크 외부의 비밀 정보

AI 도구를 위해 Python을 난독화(Obfuscating)하는 작업이 Java와는 왜 다른 사고 모델을 요구하는지 — 그리고 .env 처리가 왜 핵심적인 문제가 되는지에 대하여.

Java vs Python: 워크스페이스와의 서로 다른 관계

AI 어시스턴트를 위해 Java를 난독화하는 것은 — 본질적으로 — 여전히 컴파일이 가능한 워크스페이스를 생성하는 것에 관한 문제입니다. 개발자는 난독화된 워크스페이스를 직접 실행하는 경우가 드뭅니다. 대신 AI가 그 안에서 작업하게 하고, 변경 사항을 소스 코드에 다시 적용한 뒤, 거기서 앱을 실행합니다. 컴파일이 곧 계약(Contract)입니다. 난독화 후 mvn test-compile이 통과한다면, 작업의 95%는 완료된 것입니다.

Python은 근본적으로 다른 게임입니다. 컴파일 단계가 없습니다. 워크스페이스의 "검증(Validation)"은 개발자가 다음과 같은 명령을 실행하는 런타임(Runtime) 시점에 발생합니다:

streamlit run dashboard.py
pytest -v
python main.py
...

만약 프레임워크가 클래스 이름, 함수 이름, URL 패턴 내의 문자열, 또는 Pydantic 필드를 조사(Introspect)하는데 — 그 이름이 난독화 도구(Obfuscator)에 의해 재작성되었다면 — 오류는 Python이 이를 호출하려고 시도할 때에만 나타납니다. 이를 대신 잡아줄 컴파일러가 없습니다.

이 점은 난독화 도구의 역할을 세 가지 구체적인 방식으로 변화시킵니다:

1. 보호해야 할 대상이 달라집니다. 문자열 식별자 역할을 겸하는 식별자 이름(템플릿 참조, JSON 키, 테스트 탐색 이름 등)이 부차적인 문제가 아닌 주요 격전지가 됩니다.
2. 난독화 후 확인해야 할 사항이 달라집니다. Python의 --verify 단계는 컴파일을 할 수 없습니다. 대신 정적 임포트 해석(Static import resolution)을 수행하고 나머지는 런타임이 잡아내도록 해야 합니다.
3. 비밀 정보(Secrets)를 다루는 방식이 달라집니다. Java 워크스페이스는 AI에게 읽기 전용(Read-only)입니다. 반면 Python 워크스페이스는 개발자에 의해 실행되는데, 이는 실제 값이 어딘가에는 존재해야 함을 의미합니다. 이때 순진한 선택(워크스페이스로 .env를 복사하는 것)은 난독화의 목적을 즉시 무력화합니다.

이 글에서는 이 각각의 사항을 살펴본 후, promptcape run 패턴을 설명합니다. 즉, AI가 볼 수 있는 위치의 디스크에 환경 변수를 전혀 기록하지 않고도, 실행 시점에 Python 워크스페이스에 필요한 환경 변수(Env vars)를 전달하는 방법을 다룹니다.

문자열 계약 역할을 겸하는 이름들

Java의 경우, 프레임워크 관례(conventions)는 대개 컴파일 타임(compile-time)에 흔적을 남깁니다. 예를 들어 Lombok으로 이름을 변경한 필드에서 getName()이 누락되면 javac 단계에서 cannot find symbol 오류가 발생합니다. 이를 감지하거나 자동으로 수정할 수 있습니다. Spring Data의 파생 쿼리(findByActiveTrue)는 컴파일 타임이 아닌 시작 시점(startup)에 문제가 발생하는 드문 예외이며, 이는 이미 까다로운 사례로 문서화되어 있습니다.

Python 프레임워크는 Spring Data와 같은 관례로 가득 차 있습니다. 이름은 암묵적인 계약(silent contracts)입니다:

프레임워크	식별자 (Identifier)	계약 (Contract)
Pydantic v2	class User(BaseModel): email: str	email은 모든 user.model_dump() 호출 시 JSON 키가 됩니다. 이름을 변경하면 모든 API 소비자(consumer)가 조용히 깨지게 됩니다.
...

이 모든 것들은 "컴파일" 타임(애초에 존재하지도 않지만)에는 보이지 않습니다. 이들은 런타임(runtime)에 실패하며, 종종 AI가 접근하는 두 번째 경로에서 500 오류 형태로 나타납니다.

해결책은 사후 대응이 아닌 **선제적 탐지(proactive detection)**여야 합니다. 각 프레임워크에 대해 프로젝트를 스캔하여 관련 선언을 찾고, 식별자 수집(identifier collection)을 수행하기 전에 발견된 이름들을 프로젝트 전역 제외 목록(exclusion list)에 추가해야 합니다. PromptCape 코드베이스에는 현재 16개의 Python 탐지기(detectors)가 있으며, 그중 11개는 AST 스캔(AST scan)을 수행합니다 (나머지는 순수하게 임포트 확인(import-check) 및 고정된 이름 목록을 사용합니다):

PydanticDetector       AST 스캔: 모든 BaseModel/RootModel 필드 이름
SqlalchemyDetector     AST 스캔: 모든 선언적 모델(declarative-model) 컬럼 / 관계(relationship)
StreamlitDetector      AST 스캔: Streamlit 스크립트 내의 모든 최상위 호출 가능 객체(top-level callable)
...

AST 스캔은 LibCST을 사용하여 각 후보 파일을 파싱하고 발견된 이름을 JSON 형식으로 Java 엔진에 다시 전달하는 번들된 Python 사이드카(sidecar)를 통해 실행됩니다. 엔진은 난독화 단계(obfuscation pass)가 시작되기 전에 모든 탐지기의 출력을 단일 제외 세트(exclusion set)로 병합합니다.

Python을 위한 --verify: 컴파일이 아닌 임포트 해석(import resolution)

Java의 --verify는 mvn test-compile을 실행하고 javac 출력을 읽습니다. Python 측에서 이에 상응하는 한 줄짜리 명령어가 있을까요? 없습니다.

Python에서 가장 유사한 기능은 importlib.util.find_spec(...)입니다. staffing.database와 같은 점 표기법(dotted name)이 주어지면, 모듈을 찾을 수 없는 경우 None을 반환하고, 찾을 수 있는 경우 ModuleSpec을 반환합니다. 문제는 여기서 발생합니다: 이를 찾는 과정에서 부모 패키지의 __init__.py를 **실행(executes)**한다는 점입니다. 만약 staffing/__init__.py가 from .database import sqlalchemy_stuff를 수행한다면, find_spec은 SQLAlchemy, DB 드라이버, 그리고 아마도 애플리케이션의 절반을 전이적으로(transitively) 임포트하게 됩니다.

이는 난독화 검증 단계(obfuscation verification step)에서 사용할 수 없는 방식입니다. 사용자의 코드를 임포트하고 싶지 않으며, 사용자의 서드파티 의존성(third-party dependencies)이 사이드카(sidecar)의 Python 인터프리터에 설치되어 있는 것도 원치 않고, 무엇보다 부작용(side effects)을 원치 않기 때문입니다 (모듈 임포트 시점에 데이터베이스 연결이 열리는 것 — 이는 실제 Python의 안티 패턴(anti-pattern)이지만 흔히 발생합니다).

PromptCape가 최종적으로 채택한 전략은 AST(Abstract Syntax Tree) 레벨에서 각 임포트 문을 분류하고 이를 서로 다른 검사로 라우팅하는 방식입니다:

임포트 형태	검사 방식
import xmlrpc.client (최상위 레벨이 표준 라이브러리 이름임)	importlib.util.find_spec("xmlrpc.client") — 안전함, 표준 라이브러리는 부작용이 없음
...

이 방식은 난독화 도구가 실행되는 환경에 프로젝트 의존성이 설치되어 있을 필요 없이, 사용자 식별자 client가 레지스트리에 등록되어 import xmlrpc.client가 import xmlrpc.fld_b8460726으로 재작성되는 전형적인 버그를 잡아냅니다.

다만, 표준 라이브러리 인스턴스에서 발생하는 런타임 AttributeError는 잡아내지 못합니다 (예: 사용자가 year라는 함수를 가지고 있어 year가 이름 변경된 경우의 today.year). 이러한 경우에는 선제적 탐지 패턴(proactive detector pattern)이 유일한 대안입니다. 가장 빈번하게 액세스되는 약 210개의 표준 라이브러리 속성 이름을 가진 StdlibCommonAttrsDetector를 조건 없이 적용하는 것입니다. 여기에는 확실한 트레이드오프(trade-off)가 존재합니다 (사용자의 메서드 이름이 문자 그대로 year인 경우 이 또한 난독화되지 않습니다). 하지만 그 대안은 코드베이스의 첫 번째 날짜(date) 객체를 만나는 순간 워크스페이스가 충돌하는 상황뿐입니다.

주석과 독스트링(docstrings): 라인 수는 하중을 견디는 속성입니다

Java 난독화는 라인 수(line count)를 유지하면서 주석을 // Processed.로 제거합니다. 이는 역적용(reverse-apply) 3-way 머지(merge)를 위해 소스 코드와 난독화된 캐시(cache) 사이에 1:1 라인 대응이 필요하기 때문입니다.

Python 역시 동일한 요구 사항을 가지지만, 두 가지 별개의 구조를 가집니다:

• 라인 주석 (Line comments) (# something) — Java의 // something과 유사합니다.
• 독스트링 (Docstrings) ("""multi-line""") — Module / FunctionDef / ClassDef 본문의 첫 번째 문장인 문자열입니다.

두 가지를 모두 제거하는 것은 간단합니다. 문제는 라인 수를 보존하는 것입니다:

# Original                          # After obfuscation
"""Module docstring                 """Processed.
spanning four
...

여러 줄로 된 독스트링(multi-line docstrings)의 경우 규칙은 다음과 같습니다: 원본 문자열 값에서 \n 문자의 개수를 세고, """Processed. + N개의 줄바꿈 + """를 출력합니다. 이렇게 하면 소스 라인 수가 동일하게 유지되므로, 트레이스백(traceback)의 File "...", line 243과 같은 정보가 두 버전 모두에서 동일한 소스 라인을 가리키게 됩니다.

독스트링 제거기(docstring stripper)의 첫 번째 버전에는 미묘한 버그가 있었습니다. 이 버전은 FunctionDef.body가 항상 IndentedBlock(여러 줄 형태, def foo():\n body)이라고 가정했습니다. def foo(): return 1과 같은 한 줄 함수는 SimpleStatementSuite 본문을 사용하는데, 이는 완전히 다른 LibCST 노드 타입입니다. 이로 인해 제거기는 'SimpleStatementSuite' object is not subscriptable 오류와 함께 충돌했습니다. 이 예외(exception)가 포착되면서 파일 전체가 워크스페이스로 아무런 수정 없이 그대로(verbatim) 복사되었고, 이는 며칠 뒤 ImportError: cannot import name 'OdooClient'로 나타났습니다 (원본 복사본에는 임포트(import) 라인이 그대로 유지된 반면, 난독화된 odoo_client.py에서는 클래스 정의의 이름이 변경되었기 때문입니다).

해결 방법은 기계적입니다(두 가지 본문 형태를 모두 처리하도록 함). 하지만 여기서 얻는 교훈은 일반적입니다. Python 난독화에서 **조용한 원본 복사 폴백(silent verbatim fallback)**은 매우 위험한 실수(foot-gun)가 될 수 있습니다. 다음 진단 명령어를 반드시 기억해 둘 가치가 있습니다:

# 난독화 마커가 전혀 없는 워크스페이스 내의 모든 .py 파일을 나열합니다
for f in $(find ~/.promptcape/cache/<hash> -name "*.py" -size +10c); do
  count=$(grep -c "fld_\|mtd_\|Cls_\|Processed" "$f")
...

결과로 나오는 파일들은 비어 있는 플레이스홀더(Placeholder)이거나(이것은 괜찮습니다. 테스트 스위트에서 conftest.py는 종종 비어 있습니다), 폴백(fallback) 과정을 통과하지 못한 파일들입니다(이 경우 버그를 보고해야 합니다).

.env 문제

이 질문은 무엇보다도 Python 난독화와 Java 난독화를 가르는 결정적인 지점입니다.

Java 워크스페이스는 일반적으로 **AI에게 읽기 전용(read-only)**입니다. 개발자가 난독화를 수행하면, AI는 난독화된 복사본에서 작업하고, 개발자는 변경 사항을 다시 소스에 적용하며, 앱은 소스 프로젝트(실제 .env, 실제 application.properties, 실제 DB가 포함된)에서 실행됩니다. 난독화된 워크스페이스의 역할은 실행 가능한 것이 아니라 읽기 가능한 것이어야 합니다.

반면 Python 워크스페이스는 개발자에 의해 **실행(run)**됩니다. 개발자는 반복 작업을 수행합니다. Streamlit을 열고, pytest를 실행하고, 개발 서버를 시작합니다. 이를 위해서는 런타임(runtime)에 실제 설정 값이 필요하지만, .env 파일은 순수한 비밀 정보(secrets)입니다: API 키, 데이터베이스 URL, OAuth 클라이언트 비밀(client secrets) 등입니다. application.properties(키가 아키텍처의 일부이고 값이 말단 비밀 정보인 경우)와 달리, .env 파일에는 보존해야 할 "구조"라는 것이 없습니다. 모든 것이 끝까지 비밀 정보일 뿐입니다.

Python 파이프라인의 첫 번째 반복 버전은 기존 Java 새니타이저(sanitizer)를 .env에 실행했습니다:

# 원본 .env
DATABASE_URL=postgres://prod-db.acme.com:5432/myapp
SECRET_KEY=hunter2
...

개발자가 워크스페이스에서 처음으로 streamlit run을 실행했을 때, 즉시 충돌이 발생했습니다:

ValueError: invalid literal for int() with base 10: 'REDACTED'
  File ".../dashboard.py", line 243, in <module>
    ACTIVITY_MONTHS = int(os.getenv('ACTIVITY_MONTHS', '6'))

ACTIVITY_MONTHS=6은 비밀 정보가 아닙니다. 그것은 설정 노브(config knob)입니다. 하지만 새니타이저는 일괄적이었습니다: 일부 항목이 민감하기 때문에 모든 것을 가려버린(redact) 것입니다. 이는 워크스페이스가 실행되지 않는 Java에서는 작동하지만, Python 유스케이스(use case)에서는 즉시 시스템을 먹통으로 만듭니다.

세 가지 옵션이 나타났습니다:

옵션	워크스페이스 실행 여부?	AI가 비밀 정보를 보는가?
A. .env를 그대로 복사	예	예 (파일을 읽는 모든 도구가 이를 볼 수 있음)
...

A와 B는 서로 다른 방식으로 좋지 않습니다. C는 취약합니다. 생각하지 못한 모든 비밀 정보 형식이 유출 경로가 되고, 휴리스틱 (heuristic)과 우연히 일치하는 모든 설정 값이 충돌을 일으킵니다.

실제로 작동한 해결책은 워크스페이스에 디스크 상의 .env 파일이 전혀 필요하지 않다는 점을 인식하는 것이었습니다. 워크스페이스에는 자식 프로세스 (child process)가 시작되는 순간에 환경 변수 (env vars)가 필요할 뿐입니다. PromptCape는 "저장된 비밀 정보 (secrets at rest)"와 "실행 중인 앱의 환경 내 비밀 정보" 사이에 위치할 수 있는 계층이 존재합니다.

promptcape run: 디스크가 아닌 서브프로세스 (subprocess) 실행 시 .env 주입

이 패턴은 12-factor 앱 (12-factor apps)이 컨테이너에서 배포되는 방식에서 차용했습니다. 오케스트레이터 (orchestrator)가 컨테이너 시작 시점에 비밀 저장소 (secret store)를 읽고 키를 프로세스 환경 (process environment)으로 내보내는 방식입니다. 컨테이너 이미지 자체에는 비밀 정보가 포함되지 않습니다.

PromptCape로 번역하면 다음과 같습니다:

1. promptcape obfuscate는 .env 없이 워크스페이스를 작성합니다. 대신 원본 .env에 대한 절대 경로와 promptcape run을 사용하라는 지침이 담긴 작은 파일 .env.promptcape-pointer를 작성합니다. AI가 이 포인터를 열면 내용을 보게 되는데, 이는 의도된 것입니다. 우리는 이러한 간접 참조 (indirection)가 문서화되기를 원합니다.
2. promptcape run <command>는 다음과 같은 기능을 수행하는 래퍼 (wrapper)입니다:
   • 현재 작업 디렉토리 (current working directory)로부터 원본 프로젝트를 확인합니다 (promptcape apply / promptcape status와 동일한 메커니즘).
   • 최소한의 python-dotenv 호환 파서 (parser)를 사용하여 <source>/.env 및 <source>/.env.local을 파싱합니다.
   • cwd = workspace와 함께 <command>를 생성하며, 자식의 환경은 현재 OS 환경 위에 파싱된 .env 항목들이 레이어링 (layered)되어 채워집니다.
   • stdin/stdout/stderr를 상속하여 자식이 실제 TTY를 가질 수 있도록 합니다 (색상, 프롬프트, 진행률 표시줄 등이 모두 작동함).
   • 자식의 종료 코드 (exit code)를 전달합니다.

흐름:

# 소스 프로젝트: ~/projects/my-streamlit-app/.env
# DATABASE_URL=postgres://prod-db.acme.com:5432/myapp
# SECRET_KEY=hunter2
...

pytest의 경우도 동일한 형태입니다:

promptcape run pytest -v
# 난독화된 소스를 대상으로 테스트가 실행되며, 자식 프로세스 실행 시 실제 환경 변수 (env vars)가 주입됩니다.

Spring Boot의 완화된 바인딩 (relaxed binding, DATABASE_PASSWORD 환경 변수가 database.password 속성을 덮어씀)을 사용하는 Java 애플리케이션의 경우, 추가적인 작업 없이 동일한 명령어가 작동합니다:

promptcape run mvn spring-boot:run
# Spring Boot는 application.properties (순위 8)보다 OS 환경 변수 (순위 5)를 먼저 읽습니다.
# 워크스페이스 내의 정화된 (sanitized) application.properties에는 database.password=REDACTED라고 되어 있습니다.
...

이 방식이 정확하게 처리하는 세 가지 속성은 다음과 같습니다: