정적 분석 (SAST)

SAST란

소스코드를 실행하지 않고 분석해 SQL 인젝션·XSS·버퍼 오버플로우 등 보안 취약점 패턴을 탐지하는 기법입니다. PR 단계에서 실행해 취약한 코드가 메인 브랜치에 병합되기 전에 차단합니다.

아래 설정은 예시입니다 — 작동하는 전체 구현은 참조 저장소에

이 페이지의 YAML·명령은 핵심을 보여주는 예시입니다. 복사해 바로 쓸 수 있는 전체 파이프라인(정책 파일·샘플 앱 포함)은 Best Practice 저장소에서 확인하세요.

예시의 태그 표기와 실제 운영 설정

아래 예시는 읽기 쉽도록 @v7 같은 태그를 그대로 썼습니다. 태그는 나중에 다른 커밋을 가리키도록 바뀔 수 있으므로, 실제 운영 워크플로에서는 액션을 커밋 SHA로 고정하고 permissions: 로 잡마다 필요한 권한만 부여하세요. 이유와 방법은 파이프라인 자체 보안에서 다룹니다.

---

도구 비교

SAST 도구는 지원 언어와 분석 깊이에 따라 선택 기준이 달라집니다. 오픈소스 생태계에서 널리 사용되는 도구는 다음과 같습니다.

도구	특징	지원 언어	라이선스
Semgrep	커스텀 룰 작성 용이, 빠른 속도	30+ 언어	LGPL-2.1 (Community Edition — 관리 룰셋은 별도 라이선스)
CodeQL	GitHub 네이티브, 깊은 분석	12개 주요 언어	GitHub Actions 무료
Bandit	Python 전용, 경량	Python	Apache-2.0
SpotBugs	Java/Kotlin 전용	Java, Kotlin, Scala	LGPL

멀티 언어 프로젝트에는 Semgrep, GitHub를 사용하는 팀에는 CodeQL이 가장 적합합니다. 단일 언어 프로젝트는 언어 전용 도구 병행을 권장합니다.

---

Semgrep 설정

Semgrep은 공개 룰셋이 풍부하고 커스텀 룰 작성이 쉬워 빠르게 도입할 수 있는 도구입니다. 공식 semgrep/semgrep 컨테이너에서 semgrep ci를 실행하면 별도의 설치 없이 GitHub Actions에서 바로 동작합니다. (과거에 쓰이던 semgrep-action은 2024년에 지원이 종료되었습니다.)

GitHub Actions

YAML

# .github/workflows/sast-semgrep.yml

name: SAST — Semgrep

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  semgrep:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    container:
      image: semgrep/semgrep
    steps:
      - uses: actions/checkout@v7

      - name: Run Semgrep
        run: semgrep ci
        env:
          SEMGREP_RULES: >-
            p/owasp-top-ten
            p/security-audit
            p/secrets

GitLab CI

YAML

# .gitlab-ci.yml (semgrep 잡 부분)

semgrep:
  stage: test
  image: semgrep/semgrep:latest
  script:
    - semgrep ci
      --config p/owasp-top-ten
      --config p/security-audit
      --error
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

---

룰셋 선택 가이드

룰셋	대상	설명
p/owasp-top-ten	전체	OWASP Top 10 취약점 탐지
p/security-audit	전체	보안 감사용 포괄 룰셋
p/secrets	전체	하드코딩된 시크릿 탐지
p/python	Python	Python 전용 보안 룰
p/java	Java	Java 전용 보안 룰
p/javascript	JS/TS	JS·TS 전용 보안 룰

커스텀 룰 작성

팀 특화 패턴은 .semgrep/ 폴더에 YAML 형식으로 커스텀 룰을 추가할 수 있습니다. 기존 공개 룰셋에 없는 조직 내부 코딩 금지 패턴을 직접 정의할 때 유용합니다.

YAML

# .semgrep/custom-rules.yml

rules:
  - id: no-hardcoded-db-password
    patterns:
      - pattern: |
          $DB = new PDO("...", "...", "$PASSWORD", ...)
    message: |
      하드코딩된 DB 패스워드가 감지됐습니다.
      환경변수로 교체하세요.
    languages: [php]
    severity: ERROR

---

CodeQL 설정

CodeQL은 GitHub 전용 도구로(GitLab CI에서는 위 Semgrep의 GitLab 예시를 사용), GitHub Actions에서 퍼블릭 저장소 및 GitHub Code Security(구 GitHub Advanced Security 의 분리 제품) 구독 조직에 무료로 제공됩니다. 데이터플로우 분석을 지원해 간접적인 취약점 경로도 탐지할 수 있습니다.

GitHub Actions

YAML

# .github/workflows/sast-codeql.yml

name: SAST — CodeQL

on:
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1' # 매주 월요일 새벽 2시 전체 스캔

jobs:
  codeql:
    runs-on: ubuntu-latest
    permissions:
      security-events: write

    steps:
      - uses: actions/checkout@v7

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: javascript, python
          # 인터프리터 언어는 빌드가 불필요합니다.
          # 컴파일 언어(java, cpp 등)는 build-mode: autobuild 를 사용하세요.
          build-mode: none
          # 지원 언어: javascript, python, java,
          #            cpp, csharp, go, ruby, swift

      - name: Analyze
        uses: github/codeql-action/analyze@v4
        with:
          category: '/language:javascript'

도입 시 주의사항

처음부터 빌드 차단으로 설정하지 마세요

단계적 강화: 처음 2~4주는 경고만 출력하고 팀이 결과에 익숙해진 뒤 빌드 차단으로 전환합니다. 한 번에 수백 개의 경고가 쏟아지면 팀이 알림 피로에 빠져 도구 자체를 무시하게 됩니다.

오탐(False Positive) 관리: Semgrep은 .semgrepignore 파일로 특정 파일·경로를 제외할 수 있습니다. 테스트 코드·서드파티 라이브러리 경로는 제외를 권장합니다.

룰셋 범위: 처음에는 p/owasp-top-ten 하나만 적용하고 안정화 후 추가 룰셋 확장을 권장합니다. 룰셋을 한꺼번에 모두 활성화하면 오탐 비율이 높아져 개발 흐름을 방해할 수 있습니다.

---

SAST 결과 분석기

Semgrep·CodeQL 결과 파일을 업로드하면 취약점별 우선순위와 수정 가이드를 자동으로 생성합니다.

먼저 샘플로 미리보기 (API 키 불필요)

API 키 없이 미리 만든 샘플 스캔 결과의 분석을 바로 확인할 수 있습니다. 도구가 어떤 결과를 만들어 주는지 먼저 체감한 뒤, 아래에서 본인 결과로 실제 분석을 진행하세요.

내 결과로 실제 분석하기

이 도구는 Anthropic API 키가 필요합니다

브라우저에서 직접 Anthropic API를 호출합니다. 본인의 Anthropic API 키를 입력하면 바로 사용할 수 있으며, 키와 입력 내용은 브라우저에서 Anthropic으로만 전송됩니다(trustedoss 서버를 거치지 않습니다). 사용량은 본인 Anthropic 계정에 과금됩니다.

실제 운영 사례

TRUSCA 는 SAST 를 두 워크플로우로 나눠 운영합니다. sast.yml 은 bandit(High 심각도)과 semgrep(ERROR 심각도)을 각각 Hard Fail 기준으로 돌리고, codeql.yml 은 CodeQL 분석을 별도로 수행합니다.

같은 SAST 라도 도구마다 잡는 것이 달라 겹쳐 쓰는 구성이며, 차단 기준을 심각도로 명확히 끊어 오탐 때문에 개발이 멈추지 않도록 한 점을 참고할 만합니다.

셀프 스터디

Claude Code로 SAST 결과 심층 분석

위 분석기는 브라우저에서 바로 사용 가능합니다. 수정 코드 예시와 .semgrepignore 파일 생성이 필요하면 아래 agent를 사용하세요.

사전 조건: Trusted OSS 저장소 클론 필요

Bash

cd agents/sast-analyst
claude

agent가 아래를 자동으로 수행합니다.

• Semgrep JSON / CodeQL SARIF 자동 감지
• 규칙별 수정 코드 예시 직접 생성
• 오탐 처리 예시 (.semgrepignore) 생성
• 우선순위 기반 수정 로드맵 제시

---

다음 단계

• 의존성 취약점 관리: SCA
• 전체 파이프라인 통합: 파이프라인 설계