[TOOL-010][실무] 비밀값 없이 안전하게 코드 공유하기 > IT 기술 공유

• 목록

[이번 수업]
API 키, 비밀번호처럼 공개되면 권한을 빼앗길 수 있는 비밀정보를 코드와 Git 기록에 넣지 않는 습관을 배웁니다. 가짜 값으로 환경변수와 무시 파일을 연습하고 공유 전 변경을 점검합니다.

[선수지식]
터미널, 환경변수, Git 저장소와 스테이징을 알아야 합니다. 스테이징은 다음 커밋에 넣을 변경을 미리 올리는 단계입니다.

[학습목표]
1. 비밀정보와 일반 설정을 구분합니다.
2. 코드에는 값 대신 환경변수 이름만 둡니다.
3. 커밋 전 추적 파일과 변경을 확인합니다.

[핵심개념]
비밀정보는 비밀번호, API 토큰, 개인키처럼 노출되면 인증에 악용될 수 있는 값입니다. 서버 주소 같은 공개 설정과 다릅니다. 하드코딩은 값을 코드에 직접 적는 방식입니다. 한 번 커밋하면 현재 파일에서 지워도 복제본이나 이전 커밋에 남을 수 있습니다.

코드에는 `APP_TOKEN` 같은 참조 이름만 두고 실제 값은 실행 환경이 전달하게 합니다. 환경변수는 코드와 값을 분리하는 통로일 뿐 암호화된 저장소는 아닙니다. 로컬 값은 저장소에서 제외하고 파일 권한과 백업 범위를 확인합니다. 운영 값은 접근 통제와 교체 기록을 제공하는 승인된 비밀 저장소에서 필요한 작업에만 전달합니다.

`.gitignore`는 Git이 아직 추적하지 않는 경로를 실수로 추가하지 않도록 돕지만 이미 추적한 파일과 과거 기록은 지우지 않습니다. `.env.example`에는 변수 이름과 설명만 두고 실제 값을 넣지 않습니다. 공유 전 `git status`로 대상 파일을, `git diff --cached`로 커밋될 내용을 확인합니다.

비밀이 커밋됐다면 파일 삭제보다 먼저 값을 폐기하고 교체합니다. 접근 기록과 사용 범위를 확인한 뒤 저장소 환경의 공식 절차에 따라 기록 제거를 검토합니다. 공유 이력을 다시 쓰면 다른 복제본에 영향을 주므로 담당자와 조율합니다.

[따라하기]
아래를 app.py로 저장합니다. 실제 비밀값은 사용하지 않습니다.

```python
import os

token = os.getenv("APP_TOKEN")
if token is None:
    raise SystemExit("APP_TOKEN is missing")

print("token_loaded=True")
```

app.py가 있는 폴더에서 macOS/Linux는 다음을 실행합니다.

```sh
mkdir secret-demo
cd secret-demo
git init
printf ".env\n" > .gitignore
printf "APP_TOKEN=local-demo-only\n" > .env
python3 ../app.py
git status --short --ignored
```

첫 실행은 값이 없어 `APP_TOKEN is missing`으로 중단됩니다. `APP_TOKEN=local-demo-only python3 ../app.py`를 실행하면 `token_loaded=True`가 나옵니다. Windows PowerShell은 다음과 같습니다.

```powershell
mkdir secret-demo
cd secret-demo
git init
Set-Content .gitignore ".env"
Set-Content .env "APP_TOKEN=local-demo-only"
$env:APP_TOKEN = "local-demo-only"
py ..\app.py
Remove-Item Env:APP_TOKEN
git status --short --ignored
```

상태 출력의 핵심은 `?? .gitignore`와 `!! .env`입니다. 앞은 추적하지 않은 파일, 뒤는 무시된 파일이며 순서는 다를 수 있습니다. app.py를 연습 폴더로 옮긴 뒤 `git add .gitignore app.py`와 `git diff --cached`를 실행해 값이 커밋 대상에 없는지 확인합니다.

[흔한 실수]
파일 이름만 `.env`로 바꾸면 안전하다고 생각하거나 이미 추적한 파일이 무시 규칙으로 사라진다고 오해하기 쉽습니다. 비밀을 마스킹해 채팅이나 로그에 붙이지 말고 예제에는 `YOUR_VALUE_HERE`처럼 분명한 자리표시자를 씁니다.

[보안 주의]
실습에는 `local-demo-only` 같은 가짜 값만 사용합니다. 실제 값이 노출되면 즉시 폐기·교체하고 접근 기록을 봅니다. 화면 공유, 셸 기록, 오류 로그에도 값이 남을 수 있습니다. 본인 소유의 로컬 또는 허가된 격리 환경에서만 연습합니다.

[직접 해볼 과제]
`.env.example`을 만들고 `APP_TOKEN=`만 넣으세요. 이 파일은 스테이징하고 `.env`는 계속 무시되는지 상태와 스테이징 차이로 확인합니다.

[확인문제]
1. 환경변수는 왜 비밀 저장소 자체가 아닌가요?
2. `.gitignore`가 이미 커밋된 비밀을 지우지 못하는 이유는 무엇인가요?
3. 비밀이 커밋됐을 때 파일 삭제보다 먼저 해야 할 일은 무엇인가요?

[다음 학습]
다음 과정 PY-010에서는 비동기 I/O와 async·await를 배웁니다. TOOL-011에서는 README와 기술 문서를 작성합니다.

[공식 참고 자료]
- Git gitignore 공식 문서: https://git-scm.com/docs/gitignore
- Git diff 공식 문서: https://git-scm.com/docs/git-diff
- Python 환경변수 공식 문서: https://docs.python.org/3/library/os.html#os.environ
- OWASP 비밀정보 관리 지침: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
- CWE-798 하드코딩 자격증명 분류: https://cwe.mitre.org/data/definitions/798.html