[SAST 자동화] Part 01. Github Action + Checkmarx one
안녕하세요 !
Github에 소스코드 커밋 시 보안 진단을 수동으로 진행하면 꽤나 번거롭습니다.
특히나 코드 수정이 많은 환경이라면 더욱더 그렇겠죠.
그래서, SAST 진단을 자동화하는 CI를 만들어볼 예정입니다.
추 후에는 AWS CodeDeploy와 연동하여 CD까지 구축해보겠습니다.
참고로, 오늘 주제는 구축하기 이전에 사전 조사라고 생각해주시면 됩니다.
항상 건물을 짓기 이전에 인테리어를 어떻게 할지 구상하는거 처럼요 ^^.
01. 구성 목표
✅ 왜 CI를 구성하는가?
요즘 시대는 보안이 점점 중요해져가는 시기입니다 (실제로 지금도 공격당하고 있는 시대죠..) 즉, 보안은 필수죠.
웹앱을 띄운다고 한다면 코드가 운영환경에 배포되기 전 취약점이 없는지 검사하고,
문제가 있다면 배포를 차단하는 구조가 필요합니다.
하지만? 만약 코드 수정이 많은 웹앱이라고 했을 때 매번 수정할때마다 SAST를 수동으로 돌려야 한다면
굉장히 효율성이 떨어진다고 생각합니다. 그래서 아래와 같이 보안 진단 CI를 구성할 예정입니다.
✅ Branch에 Code commit 시 CI 파이프라인의 작업 순서
- Checkmarx API 실행
- 자동으로 SAST 진단
- 결과에 따라 배포, 배포 차단 구성
위 내용을 깔끔하게 정리하자면 GitActions + Checkmarx를 사용하는 이유는 아래와 같습니다.
- 기존 SAST 진단 방식 (예시로 Dev Branch)
- 개발자가 Project 단위로 기능 개발 → 개발 완료 → Development Branch로 PR 생성
- 담당자가 코드 리뷰(검토)후 PR 승인.
- 담당자가 수동으로 SAST 진행
- 취약점 검출이 되지 않았다면 Development Branch로 Merge
- 만약 취약점이 검출되었다면 다시 Step 1. 부터 진행 (코드 수정 → PR 생성)
- 보안게이트 CI 도입 후.
- 개발자 : Project 단위로 기능 개발 → 개발 완료 → Dev Branch로 PR 생성
- Github Actions : PR 이벤트 탐지 → Checkmarx API를 호출하여 SAST 진단
- 취약점이 검출되지 않았다면 Dev Branch로 Merge. 검출된다면, Merge 차단.
02. 활용 도구 설명
1) Github Actions 이란?
- Github에 내장된 CI/CD 플랫폼 입니다.
- github/workflows/*.yml 파일로 파이프라인을 정의하고, 이벤트 기반으로 실행됩니다.
- Runner가 존재하여 아래와 같이 사용됩니다.
- Hosted Runner : GitHub이 임시로 VM을 띄워서 작업을 진행하며 OS는 변수로 지정.
- Self-Hosted Runner : 만약 사내에 Private Registry를 운영중이라면, 이곳에서 Github와 연동하여 작업.
2) Checkmarx 란?
- Application Security Platform 이라고 해서 ASP라고 부릅니다.
- SAST(정적 분석), SCA(오픈소스 취약점), IaC, API 보안 등 제공
- 저희는 이 SAST 진단을 자동화 할 예정이므로 역할은 GitHub와 연동하여 자동 스캔 기능을 사용.
- 인증 방식은OAuth 기반 (Client ID/Secret + Refresh Token)
- 스캔 트리거 방식: REST API를 호출하는 방식과 공식 Github Action을 사용하는 방식이 존재함.
📌연동 방식 2가지 설명
- REST API 직접 호출
- Github Event 발생 → 러너 실행 → OAuth 토큰 발급 → POST /api/scans → 상태 폴링 → 결과 파싱
- 보통 커스터마이징이 필요한 세밀하게 구현을 하는 저장소에서 사용됩니다.
- Github Event 발생 → 러너 실행 → OAuth 토큰 발급 → POST /api/scans → 상태 폴링 → 결과 파싱
- 공식 Github Action 방식 (Market place)
- <소유자>/<리포지토리>@<버전> 형식 설정
- ex: yml 파일에 'uses: Checkmarx/ast-github-action@v1' 부분 형식으로 사용됨.
- 현재 리포지토리의 코드 주소를 나타내며, 코드를 러너(VM)에 가져오는 Action 이다.
- 즉, 주소를 불러와서 러너 내부에서 모든 API 호출을 대신 처리해줍니다.
- <소유자>/<리포지토리>@<버전> 형식 설정
| 방식 | 러너 사용 | 우리(사용자)가 할 일 | 장점 | 단점 |
|
API 호출
|
O |
curl로 OAuth, POST, 폴링, 파싱 직접 구현
|
세밀한 제어 (커스터마이징)
|
복잡, 유지보수 부담 |
| 공식 액션 | O |
액션 호출 + 파라미터 설정
|
간단, PR 코멘트·SARIF 지원 | 액션 버전 관리 필요. |
📌 두 가지 방식 판별법
1) 직접 API 호출 방식 : IAM/AST API를 curl로 직접 호출
2) 공식 Github Action 방식
- name: Run Checkmarx Scan
uses: Checkmarx/ast-github-action@v1 # ← 이 줄이 있으면 공식 액션
03. 인증 토큰 종류와 역할
✅왜 Token이 필요한가?
두 방식(API 직접 호출, 공식 GitAction 방식)에 상관없이, 모두 Github Action과 Checkmarx가 통신을 하려면
인증이 필요하겠죠. Checkmarx는 OAuth 기반 인증을 하고 Github Action은 자체 인증(PAT)을 제공합니다.
두 방식 모두 Action에서 Checkmarx의 API를 호출하기 때문에 토큰은 필수적으로 필요합니다.
그렇다면 아래에서 token 종류와 역할에 대해서 설명드릴게요.
📌Refresh Token (Checkmarx OAuth)
- API 직접 호출, 공식 액션 방식에 모두 필요함.
- 역할 : Checkmarx One에서 Access Token 발급용.
- Refresh Token을 서비스 계정에 한번 받아두고 이후 Access Token을 계속 갱신하기 위한 장기 자격.
- 통신 흐름 : GitHub Actions → Checkmarx IAM → Access Token 발급 → Checkmarx API 호출
- 저장 위치 : GitHub Secrets (CX_REFRESH_TOKEN)
- 역할 : Checkmarx One에서 Access Token 발급용.
📌 Client ID / Client Secret
- 공식 액션 방식에선 필수.
- 역할 : Checkmarx one에서 OAuth 클라이언트를 생성할 때 발급된다.
- 공식 액션(Checkmarx/ast-github-action)이 OAuth 인증할 때 사용
- GitHub Actions이 "나는 Checkmarx에 접근하는 합법적인 Client다"라고 증명할 때 사용됨.
- 저장 위치 : GitHub Secrets (CX_CLIENT_ID, CX_CLIENT_SECRET)
- 역할 : Checkmarx one에서 OAuth 클라이언트를 생성할 때 발급된다.
📌 GitHub PAT (Personal Access Token)
- API 방식에서 필요
- Checkmarx가 GitHub Repo를 직접 읽을 때 인증
- API 호출 시 handler.credentials.value에 넣음
- 그렇다면, 공식 액션 방식에서는 사용 안하는가?
- 불필요한 경우 많음. 공식 액션은 러너에서 ZIP 업로드 방식으로 소스를 전달하기 때문
- 저장 위치 : GitHub Secret (GIT_PAT_TOKEN)
✅ 인증 흐름 정리
- GitHub Actions가 시작됨
- Checkmarx OAuth 서버에 요청
- Client ID / Client Secret → 클라이언트 신원 확인
- Refresh Token → 사용자/서비스 계정 인증
- Access Token 발급 → Checkmarx API 호출 가능
- Access Token 만료 시 → Refresh Token으로 새 Access Token 발급
즉, CI 파이프라인이 생성될 때 마다 Access Token 발급 필요!
마무리 하며..
CI를 구성하기 이전에 먼저 사전 조사를 하는 과정이라고 생각해주시고 같이 공부해봐요.
피드백은 언제나 환영입니다.