Gitleaks 적용 방안

Public 전환에 맞춘 1번(Push Protection) + 3번(gitleaks CI) 적용 방안

0. 다시 짚는 배경

이 솔루션 조사 자체가 시작된 이유는 팀 IaC 레포(kintoun-infra)를 포트폴리오용으로 public 전환하려던 계획 때문이었다.

즉 이번 조사의 목적은 "private 상태에서 계속 쓸 보안 도구"가 아니라, "public 전환을 안전하게 만들기 위한 자동화". 이 관점으로 정리했다.

저번 글에서는 팀 IaC(Infrastructure as Code) 레포에 시크릿이 실수로 커밋되는 것을 막기 위해, push/commit 시점에 시크릿을 자동으로 감지·차단하는 자동화 솔루션을 조사했다. 컴플라이언스 팀에서는 이 내용을 바탕으로 자료 조사를 나눠 진행했고, 우리 Organization 환경에서 이 방안들이 실제로 적용 가능한지 확인하는 과정을 중점적으로 정리했다.

1. 현재 레포 환경 분석

항목	현재 상태
저장소	`kintoun-secops/kintoun-infra`, 현재 Private → Public 전환 예정
구조	`bootstrap/`(원격 state·OIDC), `identity/`(팀원 IAM), `platform/`(네트워크·EC2·Wazuh), `modules/`(재사용 모듈, 현재 비어있음), `.github/`(워크플로우·정책·스크립트)
인증 방식	장기 Access Key 미사용, `aws-actions/configure-aws-credentials@v4` + OIDC(`role-to-assume`)
기존 CI (`.github/workflows/`)	`terraform-plan.yml`(PR 시 lint→plan→iam-comment), `terraform-apply.yml`(main push 시 apply)
기존 자동 검사	`terraform fmt`, `conftest`(OPA 정책 검증), IAM 정책 커스텀 검사 스크립트(`validate-iam-policies.js`, `test-iam-pipeline.sh` 등)
`.gitignore`	`.tfstate`, `.terraform/`, `.tfvars`(example 제외), `tfplan` 등 이미 제외 처리
기존 검토 결과	파일·코드 수준 민감정보는 없음 확인됨. 단, Actions 로그 ARN 노출과 git 히스토리 전체 스캔, 2가지는 미확인 상태로 남아있었음

정리: 지금 레포는 이미 상당히 안전하게 설계돼 있지만, public 전환 전 마지막으로 "사람이 놓쳤을 수 있는 부분"을 자동화로 한 번 더 걸러내는 안전장치가 필요한 단계.

2. Public 전환을 기준으로 순서를 다시 짜면

Public 전환이라는 하나의 이벤트를 기준으로 두 솔루션의 역할이 나뉨.

솔루션	역할	적용 시점
3번 (gitleaks CI)	전환 전 마지막 안전 점검 + 전환 후에도 계속 작동하는 상시 방어선	지금 바로 적용
1번 (GitHub Secret Scanning + Push Protection)	전환과 동시에 무료로 자동 활성화되는 GitHub 자체 방어선	Public 전환 시점에 함께

즉 순서가 자연스럽게 이렇게 나옴: 먼저 gitleaks로 지금 상태를 한번 훑고(과거 커밋 포함) → 문제 없으면 public 전환 → 전환되는 순간 1번이 무료로 같이 켜짐.

3. 3번: gitleaks — Public 전환 전 지금 바로 적용

왜 지금 먼저 해야 하는가

Public 전환 전에 git 히스토리 전체(지금까지 쌓인 모든 커밋)를 한 번 스캔해서, 과거에 실수로 커밋했다 지운 값이 없는지 마지막으로 확인하는 역할. 이게 이번 조사의 원래 목적("확인 불가"로 남았던 히스토리 스캔)과 정확히 맞아떨어짐.

3-1. 사전 준비

gitleaks.io 접속 → Organization 소유 레포용 무료 라이선스 키 신청

발급받은 키를 레포 Settings > Secrets and variables > Actions > Secrets 탭에 GITLEAKS_LICENSE라는 이름으로 등록

3-2. 정확한 삽입 위치

현재 terraform-plan.yml의 lint job:


jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform fmt -check -recursive
      - name: conftest 설치
        run: |
          curl -sSFL -o /tmp/conftest.tar.gz ...
      - name: 정책 테스트
        run: conftest verify --policy .github/policy
      ...

actions/checkout@v4 바로 다음에 이렇게 추가:


      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # 전체 git 히스토리를 받아야 gitleaks가 과거 커밋까지 스캔 가능

      - name: 시크릿 스캔 (gitleaks)
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

      - uses: hashicorp/setup-terraform@v3
      - run: terraform fmt -check -recursive
      ...

놓치기 쉬운 디테일: actions/checkout@v4는 기본값이 얕은 클론(최신 커밋 1개)이라, fetch-depth: 0을 꼭 줘야 과거 커밋까지 스캔됨. 이 옵션이 바로 "히스토리 전체 스캔"을 실현하는 핵심.

3-3. Public 전환 이후에도 남겨둔다

전환 후에도 이 스텝은 그대로 유지 — 이후 팀원이 실수로 시크릿을 커밋해도 PR 단계에서 바로 막아주는 상시 방어선이 됨. conftest(정책 위반 검사)와는 역할이 다르므로 중복 아님.

4. 1번: GitHub Secret Scanning + Push Protection — Public 전환과 동시 적용

핵심: Public 전환이 곧 무료 활성화 조건

저장소 공개 여부	Secret Scanning	Push Protection	비용
Private (현재)	GitHub Secret Protection 필요	위와 동일	유료 (Active committer당 과금)
Public (전환 후)	자동 활성화	자동 활성화	무료

즉 우리가 이미 하려던 public 전환 자체가, 1번을 별도 결제 없이 얻는 방법임. 순서를 반대로 생각하면 안 되고, "gitleaks로 먼저 점검 → 전환 → 전환하자마자 1번이 공짜로 따라온다"는 흐름이 맞음.

확인만 해두면 되는 것

전환 직후 레포 Settings > Code security에서 Secret scanning / Push protection이 자동으로 "Enabled" 상태인지 한 번 확인. 혹시 조직 정책상 기본 비활성이면 관리자가 수동으로 켜야 함(설정 몇 번 클릭이면 끝).

5. 별개로 남아있는 이슈 — gitleaks로도 안 잡히는 부분

기존에 확인했던 "AWS_APPLY_ROLE_ARN이 Variables라 Actions 로그에 평문 노출" 문제는 gitleaks·Secret Scanning 둘 다 해결 못 함.

gitleaks·Secret Scanning이 보는 대상: git 커밋 안의 코드/파일

로그 노출 문제: 워크플로우 실행 시 출력되는 로그 (커밋된 파일이 아님)

Public 전환 시 과거 Actions 실행 로그도 함께 공개되므로, 이건 전환 전에 별도로 vars.AWS_APPLY_ROLE_ARN → secrets.AWS_APPLY_ROLE_ARN으로 옮겨야 함. 이번 자동화 도입과 별개로 반드시 같이 처리해야 하는 체크리스트 항목.

6. 종합 순서 (Public 전환 로드맵)

(지금) gitleaks 라이선스 발급 → Secrets 등록 → terraform-plan.yml에 스텝 추가, fetch-depth: 0으로 전체 히스토리 1차 스캔

(지금, 별개 작업) AWS_APPLY_ROLE_ARN/AWS_PLAN_ROLE_ARN을 Variables → Secrets로 이전 (로그 노출 차단)

(1·2 완료 후) gitleaks 스캔 결과 이상 없음 확인되면 Public 전환 진행

(전환 직후) Settings > Code security에서 Secret Scanning·Push Protection 자동 활성화 여부 확인 — 이걸로 상시 이중 방어선(gitleaks + GitHub 자체 기능) 완성