divyanshukumar0014/shipproofGitLab CI에서 스스로 수집되는 SOC 2 증거: 모든 병합은 서명된 번들을 생성하고, OPA 게이트는 증거가 누락된 릴리스를 차단하며, 감사자는 스크린샷 대신 하나의 링크를 받습니다.
GitLab CI에서 스스로 수집되는 SOC 2 증거: 모든 병합은 서명된 번들을 생성하고, Open Policy Agent 게이트는 증거가 누락된 릴리스를 차단하며, 감사자는 스크린샷 대신 하나의 패킷 링크를 받습니다.
실시간 감사자 대시보드 · GitLab 프로젝트 · 데모 증거 · 로드맵
ShipProof를 만든 이유는 엔터프라이즈 영업이 정보보안 검토 단계에서 반복적으로 지연되기 때문입니다. 감사자가 SOC 2 Type II 변경 관리 증거를 요청하면, 엔지니어들은 종종 Jira, Slack, Drive 전반에서 스크린샷을 찾느라 2주를 허비합니다.
저는 증거가 배포 파이프라인 안에 직접 존재하기를 원했습니다. ShipProof의 모든 병합 커밋은 테스트 실행, Semgrep SAST 스캔, Gitleaks 시크릿 탐지, Syft 소프트웨어 구성 명세서(SBOM), CODEOWNERS 승인을 포괄하는 표준화된 서명 증거 번들을 자동으로 생성합니다.
저의 핵심 설계 원칙은 엄격합니다. LLM은 증거를 요약하거나 이슈 설명을 작성할 수 있지만, 릴리스를 승인할 수는 없습니다. 릴리스 게이트는 Rego로 작성된 Open Policy Agent 평가입니다. 아티팩트가 누락되었거나 승인이 형식적인 도장 찍기에 불과해 보이면, 게이트는 폐쇄적으로 실패하고, 릴리스를 중단하며, 수정 경로를 담은 이슈를 생성합니다. 게이트가 허용하면, 감사자는 정적 사이트 또는 인증된 API로의 단일 링크를 받습니다.
저는 ShipProof를 GitLab DevOps 라이프사이클에 매핑했습니다. 9개 단계 모두를 기본적으로 자동화합니다:
| 단계 | 파이프라인에서 자동화한 내용 |
|---|---|
| plan | 폐쇄 루프 격차 작업 항목 관리. 게이트 거부 시 재발 횟수를 포함한 구조화된 추적 이슈가 자동으로 열리며, 이후 통과하는 파이프라인은 수정 커밋 참조와 함께 이슈를 자동으로 해결하고 닫습니다. |
| create | 코드 리뷰 및 소스 관리. CODEOWNERS가 정책 파일을 보호하며, 게이트는 5분 미만의 형식적 승인을 거부하고, 자동화된 MR 노트가 리뷰를 안내하며, Duo 플로우가 MR 코멘트를 설명합니다. |
| verify | pytest, Semgrep SAST, Gitleaks가 verify 단계에서 실행되며 아티팩트 해시를 기록합니다. |
| package | Syft가 package 단계에서 CycloneDX SBOM을 생성하고 아티팩트를 번들에 해시로 기록합니다. |
| secure | 결정론적 OPA 게이트가 릴리스 전에 서명, 체인 해시, 형식적 승인 규칙을 검사합니다. |
| release | 컴플라이언스 게이트 작업이 프로덕션 배포를 차단하며, 배포 작업은 허용 판정을 요구합니다. |
| configure | Cloud Run 배포 매니페스트가 시크릿을 커밋하지 않고 환경 변수로부터 렌더링됩니다. |
| monitor | 배포 후 검사가 실행 중인 컨테이너 이미지 다이제스트가 번들에서 승인된 커밋과 일치하는지 확인합니다. |
| govern | 불변 해시 체인 원장이 감사자 패킷, 격차 이슈, GitLab Pages 대시보드에 공급됩니다. |
저는 ShipProof를 Python 3.11과 Node.js 20으로 개발했습니다.
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
테스트 스위트와 타입 검사를 실행하세요:
OPA_BIN=/tmp/opa pytest -q && ruff check src tests demo-app scripts && mypy --strict src scripts
로컬 번들을 수집합니다(모든 커밋 대상):
PYTHONPATH=src python -m comply.collect --sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --out /tmp/bundle.json
수집기는 stdout에 단일 JSON 라인을 출력하고 전체 번들을 디스크에 policy/inputs.json과 함께 기록합니다. 증명이 누락된 경우 번들에는 거부 상태가 기록됩니다.
PYTHONPATH=src python -m comply.collect --sha <40-hex-sha> --out evidence/bundle.json \
--mr-iid 42 --pipeline-id 1001 --project group/project \
--pipeline-file pipeline.json --approvals-file approvals.json
CI에서 scripts/gate_bridge.py는 pipeline.json을 준비하고, scripts/fetch_approvals.py는 GitLab API에서 리뷰 데이터를 가져옵니다. 누락된 파일은 통과로 간주되지 않고 누락 상태로 기록됩니다. 모든 stderr 로그에는 번들 상관 ID가 포함되며, 시크릿은 ***로 마스킹됩니다.
PYTHONPATH=src python -m comply.gate --bundle evidence/bundle.json --ledger logs/ledger.jsonl
종료 코드 0은 허용 판정을 나타냅니다. 종료 코드 1은 실패한 제어 항목을 명시하는 구조화된 오류와 함께 거부를 나타냅니다. 종료 코드 2는 잘못된 인수를 나타냅니다. CI에서 게이트가 차단하면 파이프라인은 python -m comply.gap을 트리거하여 추적 이슈를 생성합니다.
PYTHONPATH=src python -m comply.packet --ledger logs/ledger.jsonl --release all \
--out packet.json --csv packet.csv --pdf packet.pdf
CSV 내보내기에는 11개의 열이 포함됩니다: bundle_id,commit_sha,mr_iid,pipeline_id,control,proof_type,status,artifact_sha,approver_ids,policy_sha,created_at. PDF는 동일한 JSON 소스에서 print CSS를 통해 렌더링됩니다.
AUDITOR_TOKEN=local-only PYTHONPATH=src uvicorn comply.api:app --port 8000
bearer 인증을 사용하여 번들을 쿼리합니다:
curl -H "Authorization: Bearer local-only" "localhost:8000/api/v1/bundles?mr_iid=42"
API는 번들 쿼리, 릴리스 패킷, 백그라운드 PDF 내보내기를 위한 엔드포인트를 제공하며, 베어러 토큰과 분당 60회 요청의 속도 제한으로 보호됩니다.
cd auditor && npm install && npm run build
인터페이스는 React 19, TypeScript, Tailwind CSS로 구축되었습니다. 해시 라우팅을 사용하는 정적 사이트로 내보내지므로 서버 재작성 없이 GitLab Pages에서 직접 실행할 수 있습니다. 백엔드 API가 없을 때는 public/fallback/demo-packets.json의 샘플 데이터를 사용합니다.
flowchart LR
A["CI jobs (pytest, Semgrep, Gitleaks, Syft)"] --> B["gate_bridge.py (artifact summary)"]
B --> C["comply.collect (bundle.json + inputs.json)"]
C --> D["comply.sign (Cosign, HMAC fallback)"]
D --> E["ledger.jsonl (hash chain)"]
E --> F["comply.gate (OPA policy + signature + chain)"]
F -->|"deny"| G["comply.gap (gap issue + MR comment)"]
F -->|"allow"| H["deploy jobs (gated)"]
E --> I["comply.packet (JSON, CSV, PDF)"]
I --> J["GitLab Pages dashboard + read API"]
파이프라인은 단위 테스트와 보안 스캐너를 실행하고, 출력을 증거 수집기로 연결하며, 번들에 서명하고, 원장에 레코드를 추가합니다. 게이트 작업은 번들, 암호화 서명, 원장 체인에 대해 policy/soc2-v1.rego를 평가합니다. 거부 시 병합 요청에 알림이 전송되고 GitLab 작업 항목이 생성됩니다. 성공적인 평가는 배포 작업을 차단 해제하고 감사인 패킷을 게시합니다.
| 통제 항목 | 기준 | 번들에 수집된 증거 |
|---|---|---|
| CC8.1 변경 관리 | 프로덕션 변경에는 코드 리뷰와 대상 커밋에 대한 통과된 파이프라인이 필요합니다. 대규모 diff에서 5분 미만의 리뷰는 실패합니다. | 병합 요청 IID, 승인자 ID, 리뷰 소요 시간, diff 통계, 파이프라인 ID. |
| CC7.2 시스템 모니터링 | 변경은 불변이며 순차적인 배포 로그를 생성합니다. | 파이프라인 작업 상태, 해시 체인 원장, CycloneDX SBOM 다이제스트, 컨테이너 태그. |
| CC6.1 논리적 접근 | 배포는 혼합된 환경 없이 승인된 ID에서 시작되어야 합니다. | 트리거 ID, 시크릿 탐지 로그, 환경 변수 이름 스냅샷. |
| CC6.3 역할 기반 접근 제어 | 권한이 없는 역할은 프로덕션으로 승격할 수 없습니다. | 서명자 ID, Cosign 인증서 또는 서명 유효성, OPA 정책 평가. |
| CC7.1 감사 연결 | 차단된 릴리스는 추적 이슈에 연결되어야 하며, 해결된 이슈는 병합 요청에 연결되어야 합니다. | 댓글 전반의 이슈 IID, 병합 요청 IID, 번들 ID 참조. |
로컬 실행은 .env에서 읽습니다. 프로덕션 파이프라인은 마스킹된 GitLab CI 변수를 사용합니다.
| 변수 | 필수 여부 | 목적 |
|---|---|---|
GITLAB_TOKEN | CI에서 필수 | 수집기와 격차 이슈 생성기가 사용하는 프로젝트 액세스 토큰. |
AUDITOR_TOKEN | API용 | comply.api 엔드포인트에 필요한 베어러 토큰. |
VANTA_API_KEY | 선택 사항 | 번들 동기화용 API 키이며, 생략 시 정상적으로 건너뜁니다. |
GCP_SA_KEY | 배포 전용 | Google Cloud Run 배포용 서비스 계정 키. |
GCP_PROJECT_PREVIEW | 배포 전용 | 미리보기 환경용 Google Cloud 프로젝트 ID. |
GCP_PROJECT_PROD | 배포 전용 | 프로덕션 배포용 Google Cloud 프로젝트 ID. |
SHIPPROOF_SIGNING_KEY | Cosign 미사용 시 | 키리스 Cosign 서명을 사용할 수 없을 때 사용되는 HMAC 키. |
OPA_BIN | 선택 사항 | OPA 바이너리의 사용자 지정 경로이며, CI에서 자동으로 다운로드합니다. |
CI_API_V4_URL | CI 전용 | fetch 스크립트가 사용하는 GitLab API 루트 URL. |
src/comply/ Collector, gate, signing, ledger, gap reporter, packet builder, read API
policy/ soc2-v1.rego policy contract and evaluation fixtures
tests/ Contract, unit, and API tests
auditor/ Static React auditor interface
demo-app/ FastAPI sample application with container configuration
scripts/ CI bridges and offline seed demonstration scripts
templates/ Markdown templates for gate denial comments
.gitlab/ Duo agent flow definitions and issue templates
demo/ Evidence notes and verified demonstration links
evidence/ logs/ Local bundles and hash-chained ledger storage
게이트가 의도대로 작동하는지 확인하기 위해 두 가지 데모 경로를 구축하고 검증했습니다:
demo/good, MR !8): 테스트, SAST, 시크릿 스캔, SBOM 생성을 실행합니다. CODEOWNERS 승인을 받습니다. 게이트가 프로모션을 허용하고, 감사자 패킷을 게시하며, 병합 요청에 댓글을 남깁니다.demo/missing-scan, MR !9): SAST 스캐너를 건너뜁니다. 수집기가 누락된 아티팩트를 표시하고, OPA가 CC8.1로 릴리스를 거부하며, 파이프라인이 중단되고, comply.gap이 수정 지침과 함께 이슈 #3을 생성합니다.자세한 파이프라인 URL과 댓글 영구 링크는 demo/evidence.md에 기록되어 있습니다.