다음 트러블슈팅 시나리오는 고객 지원 사례에서 수집되었습니다. 여기에서 해결되지 않은 문제가 발생하거나 여기의 정보로 문제가 해결되지 않는 경우, 도움을 받는 방법에 대한 GitLab 지원 페이지를 참조하세요.

디버그 수준 로깅#

디버그 수준 로깅은 트러블슈팅 시 도움이 될 수 있습니다. 자세한 내용은 디버그 수준 로깅을 참조하세요.

CI/CD 템플릿의 변경 사항#

GitLab 관리 SAST CI/CD 템플릿은 어떤 분석기 작업이 실행되고 어떻게 구성되는지를 제어합니다. 템플릿을 사용하는 동안 작업 실패 또는 기타 파이프라인 오류가 발생할 수 있습니다. 예를 들어:

• 영향받는 파이프라인을 볼 때 '<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage와 같은 오류 메시지가 표시될 수 있습니다.
• CI/CD 파이프라인 구성에서 다른 유형의 예기치 않은 문제가 발생할 수 있습니다.

작업 실패가 발생하거나 SAST 관련 yaml invalid 파이프라인 상태가 표시되면 파이프라인이 계속 작동하도록 이전 버전의 템플릿으로 일시적으로 되돌릴 수 있습니다. 이전 버전의 템플릿을 사용하려면 CI/CD YAML 파일의 기존 include 문을 변경하여 v15.3.3-ee와 같은 특정 템플릿 버전을 참조하세요:

include:
  remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/v15.3.3-ee/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml'

GitLab 인스턴스의 네트워크 연결이 제한된 경우 파일을 다운로드하여 다른 곳에 호스팅할 수도 있습니다.

이 해결책은 임시로만 사용해야 합니다. 가능한 한 빨리 표준 템플릿으로 돌아오세요.

특정 분석기 작업의 오류#

GitLab SAST 분석기는 컨테이너 이미지로 릴리스됩니다. GitLab 관리 SAST CI/CD 템플릿이나 자체 프로젝트의 변경 사항과 관련이 없어 보이는 새 오류가 발생하는 경우, 영향받는 분석기를 특정 이전 버전으로 고정해 볼 수 있습니다. 이 해결책은 임시로만 사용해야 합니다. 가능한 한 빨리 표준 템플릿으로 돌아오세요.

각 분석기 프로젝트에는 사용 가능한 각 버전의 변경 사항을 나열하는 CHANGELOG.md 파일이 있습니다.

작업 로그 메시지#

SAST 작업의 로그에는 근본 원인을 파악하는 데 도움이 되는 오류 메시지가 포함될 수 있습니다. 아래는 일부 오류 메시지와 권장 조치입니다.

실행 형식#

exec /bin/sh: exec format error` message in job log

GitLab SAST 분석기는 amd64 CPU 아키텍처에서의 실행만 지원합니다. 이 메시지는 작업이 arm과 같은 다른 아키텍처에서 실행 중임을 나타냅니다.

Docker 오류#

Error response from daemon: error processing tar file: docker-tar: relocation error

이 오류는 SAST 작업을 실행하는 Docker 버전이 19.03.0일 때 발생합니다. Docker 19.03.1 이상으로 업데이트하는 것을 고려하세요. 이전 버전은 영향을 받지 않습니다. 자세한 내용은 이슈 13830 - "Current SAST container fails"를 참조하세요.

일치하는 파일 없음#

gl-sast-report.json: no matching files

이에 대한 정보는 일반 애플리케이션 보안 트러블슈팅 섹션을 참조하세요.

구성 전용#

sast is used for configuration only, and its script should not be executed

이에 대한 정보는 GitLab Secure 트러블슈팅 섹션을 참조하세요.

오류: An error occurred while creating the merge request#

UI를 사용하여 프로젝트에서 SAST를 활성화하려고 할 때 다음 경고와 함께 작업이 실패할 수 있습니다:

An error occurred while creating the merge request.

이 문제는 Merge request에 대한 브랜치 생성을 방해하는 무언가가 있을 때 발생할 수 있습니다. UI를 사용하여 SAST를 구성할 때 set-sast-config-1과 같은 숫자 접미사가 있는 브랜치가 생성됩니다. 브랜치 이름을 검증하는 push 규칙과 같은 기능이 명명 형식 때문에 브랜치 생성을 차단할 수 있습니다.

이 문제를 해결하려면 SAST에 필요한 브랜치 명명 형식을 허용하도록 push 규칙을 편집하세요.

SAST 작업이 예기치 않게 실행됨#

SAST CI 템플릿은 rules:exists 파라미터를 사용합니다. 성능상의 이유로, 주어진 glob 패턴에 대해 최대 10000개의 매칭이 이루어집니다. 매칭 수가 최대값을 초과하면 rules:exists 파라미터는 true를 반환합니다. 저장소의 파일 수에 따라, 스캐너가 프로젝트를 지원하지 않더라도 SAST 작업이 트리거될 수 있습니다. 이 제한에 대한 자세한 내용은 rules:exists 문서를 참조하세요.

SpotBugs 오류#

아래에는 발생하는 가장 일반적인 SpotBugs 오류와 권장 조치에 대한 세부 정보가 있습니다.

UTF-8 매핑 불가 문자 오류#

이 오류는 SpotBugs 빌드에서 UTF-8 인코딩이 활성화되지 않고 소스 코드에 UTF-8 문자가 있을 때 발생합니다. 이 오류를 수정하려면 프로젝트의 빌드 도구에 UTF-8을 활성화하세요.

Gradle 빌드의 경우 build.gradle 파일에 다음을 추가하세요:

compileJava.options.encoding = 'UTF-8'
tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

Maven 빌드의 경우 pom.xml 파일에 다음을 추가하세요:

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

프로젝트를 빌드할 수 없음#

spotbugs-sast 작업이 "Project couldn't be built" 메시지와 함께 빌드 단계에서 실패하는 경우, 가장 가능성 있는 원인은 다음과 같습니다:

• 프로젝트가 SpotBugs에게 기본 도구에 포함되지 않은 도구로 빌드하도록 요청하고 있습니다. SpotBugs 기본 도구 목록은 SpotBugs의 asdf 의존성을 참조하세요.
• 빌드에 분석기의 자동 빌드 프로세스가 수용할 수 없는 사용자 정의 구성이나 추가 의존성이 필요합니다.

SpotBugs 기반 분석기는 Groovy 코드 스캔에만 사용되지만, 모든 SAST 작업이 예기치 않게 실행될 때와 같이 다른 경우에 트리거될 수 있습니다.

해결책은 Groovy 코드를 스캔해야 하는지 여부에 따라 다릅니다:

• Groovy 코드가 없거나 스캔이 필요하지 않은 경우 SpotBugs 분석기를 비활성화해야 합니다.
• Groovy 코드를 스캔해야 하는 경우 사전 컴파일을 사용해야 합니다. 사전 컴파일은 spotbugs-sast 작업에서 컴파일하려는 대신 파이프라인에서 이미 빌드한 아티팩트를 스캔하여 이러한 실패를 방지합니다.

Java 메모리 부족 오류#

spotbugs-sast 작업이 실행 중일 때 java.lang.OutOfMemoryError 오류가 발생할 수 있습니다. 이 문제는 Java가 스캔 중에 메모리가 부족할 때 발생합니다.

이 문제를 해결하려면 다음을 시도할 수 있습니다:

• 더 낮은 노력 수준을 선택합니다.
• CI/CD 변수 JAVA_OPTS를 설정하여 기본값 -XX:MaxRAMPercentage=80을 교체합니다(예: -XX:MaxRAMPercentage=90).
• spotbugs-sast 작업에서 더 큰 러너에 태그합니다.

관련 주제#

• OpenJDK 컨테이너의 메모리 튜닝 개편 업데이트
• OpenJDK 구성 및 튜닝
• Garbage First 가비지 컬렉터 튜닝

예외 분석#

작업 로그에 "Exception analyzing ... using detector ..." 형식의 메시지와 그 뒤에 Java 스택 추적이 포함된 경우, 이것은 SAST 파이프라인의 실패가 아닙니다. SpotBugs는 예외가 복구 가능하다고 판단하여 로그에 기록하고 분석을 재개했습니다.

메시지의 첫 번째 "..." 부분은 분석 중인 클래스입니다 - 프로젝트의 일부가 아닌 경우 메시지와 그 뒤에 오는 스택 추적을 무시할 수 있습니다.

반면에 분석 중인 클래스가 프로젝트의 일부인 경우 GitHub에서 SpotBugs 프로젝트에 이슈를 생성하는 것을 고려하세요.

Flawfinder 인코딩 오류#

이 오류는 Flawfinder가 유효하지 않은 UTF-8 문자를 만날 때 발생합니다. 이를 수정하려면 전체 저장소에 또는 before_script 기능을 사용하여 작업별로만 문서화된 권장 사항을 적용하세요.

각 .gitlab-ci.yml 파일에서 before_script 섹션을 구성하거나 파이프라인 실행 정책을 사용하여 인코더를 설치하고 변환 명령을 실행할 수 있습니다. 예를 들어 보안 스캐너 템플릿에서 생성된 flawfinder-sast 작업에 before_script 섹션을 추가하여 .cpp 확장자를 가진 모든 파일을 변환할 수 있습니다.

파이프라인 실행 정책 YAML 예제#

---
pipeline_execution_policy:
- name: SAST
  description: 'Run SAST on C++ application'
  enabled: true
  pipeline_config_strategy: inject_ci
  content:
    include:
    - project: my-group/compliance-project
      file: flawfinder.yml
      ref: main

flawfinder.yml:

include:
  - template: Jobs/SAST.gitlab-ci.yml

flawfinder-sast:
  before_script:
    - pip install cvt2utf
    - cvt2utf convert "$PWD" -i cpp

Semgrep 속도 저하, 예기치 않은 결과 또는 기타 오류#

Semgrep이 느리거나, 너무 많은 거짓 양성 또는 거짓 음성을 보고하거나, 충돌하거나, 실패하거나, 기타 문제가 있는 경우 GitLab SAST 트러블슈팅에 대한 Semgrep 문서를 참조하세요.