Infrastructure as Code 스캔

요약

Infrastructure as Code(IaC) 스캐닝은 CI/CD 파이프라인에서 실행되며 인프라 정의 파일에 알려진 취약점이 있는지 검사합니다. IaC 스캐닝 분석기는 JSON 형식의 리포트를 job 아티팩트로 출력합니다.

Infrastructure as Code(IaC) 스캐닝은 CI/CD 파이프라인에서 실행되며 인프라 정의 파일에 알려진 취약점이 있는지 검사합니다. 기본 브랜치에 커밋되기 전에 취약점을 찾아내 애플리케이션의 위험에 미리 대응할 수 있습니다.

IaC 스캐닝 분석기는 JSON 형식의 리포트를 job 아티팩트로 출력합니다.

GitLab Ultimate에서는 IaC 스캐닝 결과가 추가로 처리되어 다음을 할 수 있습니다.

머지 리퀘스트에서 결과를 확인합니다.
승인 워크플로에 활용합니다.
취약점 리포트에서 검토합니다.

시작하기#

IaC 스캐닝을 처음 사용한다면 다음 단계를 따라 프로젝트에 적용합니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.
일관된 성능을 위해 최소 4GB RAM 이 필요합니다.
Docker 또는 Kubernetes 실행기를 사용하는 Linux 기반 GitLab Runner가 필요합니다. GitLab.com의 호스티드 러너를 사용한다면 Docker 또는 Kubernetes 실행기가 기본으로 켜져 있습니다.
- Windows의 GitLab Runner는 지원하지 않습니다.
- AMD64 외의 CPU 아키텍처는 지원하지 않습니다.
GitLab CI/CD 설정(.gitlab-ci.yml)에 test Stage가 있어야 합니다. test Stage는 기본으로 포함되지만, Stage를 재정의했다면 명시적으로 추가해야 합니다.

IaC 스캐닝을 활성화하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Build > Pipeline editor로 이동합니다.
IaC 스캐닝 CI/CD 템플릿이나 컴포넌트 중 하나를 추가합니다.

템플릿을 사용하려면 다음 줄을 추가합니다.
```
include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml
```
CI/CD 컴포넌트를 사용하려면 다음 줄을 추가합니다.
```
include:
  - component: gitlab.com/components/sast/iac-sast@main
```
Validate 탭을 선택한 다음 Validate pipeline을 선택합니다.

Simulation completed successfully 메시지가 나오면 파일이 유효한 것입니다.
Edit 탭을 선택합니다.
다음 항목을 입력합니다.
- 커밋 메시지입니다.
- 브랜치입니다. 예를 들면 add-iac 입니다.
Start a new merge request with these changes 체크박스를 선택한 다음 Commit changes를 선택합니다.

머지 리퀘스트 페이지가 열립니다.
평소 워크플로에 맞게 항목을 입력한 다음 Create merge request를 선택합니다.
평소 워크플로에 맞게 머지 리퀘스트를 검토하고 수정한 다음 Merge를 선택합니다.

이제 파이프라인에서 IaC 스캐닝이 활성화됩니다.

IaC 스캐닝 job 이 모든 파이프라인에서 실행되어 KICS 분석기를 구동합니다.
분석기는 프로젝트에 지원되는 IaC 파일이 있는지 판별합니다.
지원되는 파일이 있으면 분석기가 취약점을 검사합니다.
지원되는 파일이 없으면 job은 결과 없이 완료됩니다.

해당 job은 파이프라인의 test Stage 아래에 표시됩니다.

동작하는 예시는 IaC 스캐닝 예제 프로젝트에서 확인할 수 있습니다.

다음 단계#

IaC 스캐닝을 활성화한 뒤에는 다음을 할 수 있습니다.

결과 이해하기에서 결과 해석 방법을 확인합니다.
최적화 팁을 검토합니다.
더 많은 프로젝트로 확대하는 계획을 세웁니다.

결과 이해하기#

사전 요구 사항:

프로젝트에 대한 Security Manager, Developer, Maintainer, Owner 중 하나의 권한이 필요합니다.

파이프라인에서 취약점을 검토하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
파이프라인을 선택합니다.
Security 탭을 선택합니다.
취약점을 선택하면 다음을 포함한 세부 정보를 볼 수 있습니다.
- Description: 취약점의 원인, 잠재적 영향, 권장 조치를 설명합니다.
- Status: 취약점이 분류되었는지 또는 해결되었는지 나타냅니다.
- Severity: 심각도 수준 자세히 보기에서 확인합니다.
- Location: 문제가 발견된 파일 이름과 줄 번호를 표시합니다. 파일 경로를 선택하면 코드 보기에서 해당 줄이 열립니다.
- Scanner: 어떤 분석기가 취약점을 탐지했는지 알려 줍니다.
- Identifiers: CWE 식별자와 탐지한 규칙의 ID 등 취약점을 분류하는 데 사용한 참조 목록입니다.

Ultimate에서는 보안 스캔 결과를 내려받을 수도 있습니다.

사전 요구 사항:

프로젝트에 대한 Security Manager, Developer, Maintainer, Owner 중 하나의 권한이 필요합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
파이프라인을 선택합니다.
Security 탭을 선택합니다.
파이프라인의 Security 탭에서 Download results를 선택합니다.

자세한 내용은 파이프라인 보안 리포트를 참고합니다.

Note

결과는 기능 브랜치에서 생성됩니다. 기본 브랜치에 병합되면 그 결과가 취약점이 됩니다. 보안 상태를 평가할 때 이 구분이 중요합니다.

IaC 스캐닝 결과를 확인하는 다른 방법은 다음과 같습니다.

머지 리퀘스트 리포트: 새로 발생했거나 해결된 결과를 보여 줍니다.
머지 리퀘스트 변경 사항 보기: 변경된 줄에 인라인 주석을 표시합니다.
취약점 리포트: 기본 브랜치에서 확인된 취약점을 보여 줍니다.

지원되는 언어 및 프레임워크#

IaC 스캐닝은 다양한 IaC 설정 파일을 지원합니다. 프로젝트에서 지원되는 설정 파일이 발견되면 KICS로 스캔합니다. 여러 종류의 IaC 설정 파일이 섞여 있는 프로젝트도 지원합니다.

지원되는 설정 형식은 다음과 같습니다.

Ansible
AWS CloudFormation
Azure Resource Manager

[!note] IaC 스캐닝은 JSON 형식의 Azure Resource Manager 템플릿을 분석할 수 있습니다. 템플릿을 Bicep으로 작성했다면, Bicep CLI로 Bicep 파일을 JSON으로 변환해야 IaC 스캐닝이 분석할 수 있습니다.
Dockerfile
Google Deployment Manager
Kubernetes
OpenAPI
Terraform

KICS는 쿼리가 있는 리소스 유형에 대해서만 결과를 보고합니다. KICS에는 다음 공급자의 Terraform 쿼리가 있습니다.
- Alibaba Cloud
- AWS
- Azure
- Databricks
- GitHub
- Google Cloud
- Kubernetes
- NIFCLOUD
- Tencent Cloud
KICS에는 공급자와 무관한 검사도 있습니다. 다른 공급자에는 이러한 검사만 적용됩니다. 자세한 내용은 KICS 플랫폼을 참고합니다.

[!note] 사용자 지정 레지스트리에 있는 Terraform 모듈은 취약점 스캔 대상이 아닙니다. 제안된 기능에 관한 자세한 내용은 이슈 357004를 참고합니다.

IaC 스캐닝 최적화#

IaC 스캐닝을 최적화하면 잡음을 줄이고 관련 있는 결과에 집중할 수 있습니다.

sast-ruleset.toml 파일로 특정 규칙을 비활성화합니다.
sast-ruleset.toml 파일로 심각도 같은 규칙 속성을 재정의합니다.
해당 파일에 KICS 주석을 넣어 특정 파일의 스캔을 비활성화합니다.

IaC 스캐닝은 규칙 추가 또는 교체를 지원하지 않습니다. 각 분석기가 지원하는 옵션은 규칙 사용자 지정 옵션을 참고합니다.

규칙을 비활성화하거나 규칙 속성을 재정의할 때는 sast-ruleset.toml 파일을 사용합니다. 이 방식의 이점은 다음과 같습니다.

GitLab 취약점 관리와 연동되어 규칙을 비활성화하면 기존 결과가 자동으로 해결됩니다.
보안 정책 결정이 버전 관리되는 형태로 문서화됩니다.
IaC 스캐닝을 확대할 때 여러 프로젝트에서 룰셋을 공유할 수 있습니다.

룰셋 정의#

모든 IaC 스캐닝 규칙은 ruleset 절에 들어가며, 다음을 포함합니다.

규칙의 type 필드입니다. IaC 스캐닝에서 식별자 유형은 kics_id 입니다.
규칙 식별자의 value 필드입니다. KICS 규칙 식별자는 영숫자 문자열입니다. 규칙 식별자를 찾는 방법은 다음과 같습니다.
- JSON 리포트 아티팩트에서 찾습니다.
- 규칙 이름을 KICS 쿼리 목록에서 검색해 표시된 영숫자 식별자를 복사합니다. 규칙 이름은 규칙 위반이 탐지되면 취약점 세부 정보 페이지에 표시됩니다.

규칙 비활성화#

특정 IaC 스캐닝 규칙을 비활성화할 수 있습니다. 비활성화한 규칙이 이전에 탐지한 결과는 자동으로 해결됩니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

분석기 규칙을 비활성화하려면 다음을 수행합니다.

프로젝트 루트에 .gitlab 디렉터리가 없다면 새로 만듭니다.
.gitlab 디렉터리에 sast-ruleset.toml이라는 사용자 지정 룰셋 파일이 없다면 새로 만듭니다.
ruleset 절 안에서 disabled 플래그를 true로 설정합니다.
하나 이상의 ruleset 하위 절에 비활성화할 규칙을 나열합니다.

sast-ruleset.toml 파일을 기본 브랜치에 병합하면 비활성화한 규칙의 기존 결과가 자동으로 해결됩니다.

다음 sast-ruleset.toml 예시에서는 식별자의 type과 value를 대조해 비활성화할 규칙을 kics 분석기에 지정합니다.

[kics]
  [[kics.ruleset]]
    disable = true
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"

  [[kics.ruleset]]
    disable = true
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "b03a748a-542d-44f4-bb86-9199ab4fd2d5"

파일 스캔 비활성화#

파일 전체 또는 특정 규칙에 대해 스캔을 비활성화하려면 해당 파일에 KICS 주석을 사용합니다.

이 기능은 일부 IaC 파일 유형에서만 사용할 수 있습니다. 지원되는 파일 유형 목록은 KICS 문서에서 확인합니다.

파일 전체의 스캔을 건너뛰려면 파일 맨 위에 # kics-scan ignore 주석을 추가합니다.
파일 전체에서 특정 규칙을 비활성화하려면 파일 맨 위에 # kics-scan disable=<kics_id> 주석을 추가합니다.

규칙 재정의#

특정 IaC 스캐닝 규칙을 재정의해 원하는 대로 바꿀 수 있습니다. 예를 들어 규칙의 심각도를 낮추거나, 결과를 해결하는 방법을 설명한 자체 문서로 연결할 수 있습니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

규칙을 재정의하려면 다음을 수행합니다.

프로젝트 루트에 .gitlab 디렉터리가 없다면 새로 만듭니다.
.gitlab 디렉터리에 sast-ruleset.toml이라는 사용자 지정 룰셋 파일이 없다면 새로 만듭니다.
하나 이상의 ruleset.identifier 하위 절에 재정의할 규칙을 나열합니다.
ruleset 절의 ruleset.override 안에 재정의할 키를 지정합니다. 키는 어떤 조합으로도 재정의할 수 있습니다. 유효한 키는 다음과 같습니다.
- description
- message
- name
- severity(유효한 값: Critical, High, Medium, Low, Unknown, Info)

다음 sast-ruleset.toml 예시에서는 식별자의 type과 value로 규칙을 찾아 재정의합니다.

[kics]
  [[kics.ruleset]]
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"
    [kics.ruleset.override]
      description = "OVERRIDDEN description"
      message = "OVERRIDDEN message"
      name = "OVERRIDDEN name"
      severity = "Info"

오프라인 설정#

오프라인 환경은 인터넷을 통한 외부 리소스 접근이 제한되거나 간헐적인 환경을 뜻합니다. 이런 환경의 인스턴스에서는 IaC에 설정 변경이 필요합니다. 이 절의 안내는 오프라인 환경에 설명된 절차와 함께 수행해야 합니다.

GitLab Runner 설정#

러너는 로컬 사본이 있어도 기본적으로 GitLab 컨테이너 레지스트리에서 Docker 이미지를 가져오려고 합니다. Docker 이미지를 최신으로 유지하려면 이 기본 설정을 사용합니다. 다만 네트워크 연결이 전혀 없다면 GitLab Runner의 기본 pull_policy 변수를 변경해야 합니다.

GitLab Runner CI/CD 변수 pull_policy를 if-not-present로 설정합니다.

로컬 IaC 분석기 이미지 사용#

GitLab 컨테이너 레지스트리 대신 로컬 Docker 레지스트리에서 이미지를 가져오려면 로컬 IaC 분석기 이미지를 사용합니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.
Docker 이미지를 로컬 오프라인 Docker 레지스트리로 가져오는 방법은 네트워크 보안 정책에 따라 달라집니다. 외부 리소스를 가져오거나 일시적으로 접근하기 위해 승인된 절차는 IT 담당자에게 확인합니다.

로컬 IaC 분석기 이미지를 사용하려면 다음을 수행합니다.

기본 IaC 분석기 이미지를 registry.gitlab.com에서 로컬 Docker 컨테이너 레지스트리로 가져옵니다.
```
registry.gitlab.com/security-products/kics:6
```
IaC 분석기 이미지는 주기적으로 업데이트되므로 로컬 사본도 주기적으로 갱신합니다.

CI/CD 변수 SECURE_ANALYZERS_PREFIX를 로컬 Docker 컨테이너 레지스트리로 설정합니다.

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

variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

이제 IaC job 이 인터넷 접속 없이 로컬에 있는 분석기 Docker 이미지 사본을 사용합니다.

특정 분석기 버전 사용#

GitLab 이 관리하는 CI/CD 템플릿은 메이저 버전을 지정하고 그 메이저 버전의 최신 분석기 릴리스를 자동으로 가져옵니다. 특정 버전을 사용해야 하는 경우도 있습니다. 예를 들어 이후 릴리스의 회귀를 피해야 할 수 있습니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

특정 분석기 버전을 사용하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipeline editor를 선택합니다.
SAST-IaC.gitlab-ci.yml 템플릿을 포함하는 줄 뒤에 SAST_ANALYZER_IMAGE_TAG CI/CD 변수를 추가합니다.

[!note] 이 변수는 특정 job 에만 설정합니다. 최상위에 설정하면 지정한 버전이 다른 SAST 분석기에도 적용됩니다.

태그는 다음과 같이 설정합니다.
- 3처럼 메이저 버전으로 설정합니다. 파이프라인이 이 메이저 버전에서 나오는 마이너·패치 업데이트를 사용합니다.
- 3.7처럼 마이너 버전으로 설정합니다. 파이프라인이 이 마이너 버전에서 나오는 패치 업데이트를 사용합니다.
- 3.7.0처럼 패치 버전으로 설정합니다. 파이프라인이 업데이트를 받지 않습니다.

다음 예시는 IaC 분석기의 특정 마이너 버전을 사용합니다.

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

kics-iac-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "3.1"

지원되는 배포판#

GitLab 스캐너는 크기와 유지 보수성을 고려해 Alpine 베이스 이미지로 제공됩니다.

FIPS 지원 이미지 사용#

GitLab은 표준 이미지 외에 FIPS 지원 Red Hat UBI 기반 스캐너 이미지도 제공합니다.

파이프라인에서 FIPS 지원 이미지를 사용하려면 SAST_IMAGE_SUFFIX를 -fips로 설정하거나 표준 태그에 -fips 확장을 붙입니다.

다음 예시는 SAST_IMAGE_SUFFIX CI/CD 변수를 사용합니다.

variables:
  SAST_IMAGE_SUFFIX: '-fips'

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

자동 취약점 해결#

여전히 유효한 취약점에 집중할 수 있도록, IaC 스캐닝은 다음 경우에 취약점을 자동으로 해결합니다.

미리 정의된 규칙을 비활성화한 경우입니다.
GitLab 이 기본 룰셋에서 규칙을 제거한 경우입니다.

나중에 그 규칙을 다시 활성화하면 결과가 다시 열려 분류 대상이 됩니다.

취약점 관리 시스템은 취약점을 자동으로 해결할 때 노트를 추가합니다.

리포트 JSON 형식#

IaC 스캐너는 기존 SAST 리포트 형식의 JSON 리포트 파일을 출력합니다. 자세한 내용은 이 리포트의 스키마를 참고합니다.

JSON 리포트 파일은 다음에서 내려받을 수 있습니다.

CI/CD 파이프라인 페이지입니다.
머지 리퀘스트의 파이프라인 탭입니다. artifacts: paths를 gl-sast-report.json으로 설정해야 합니다.

자세한 내용은 아티팩트 내려받기를 참고합니다.

확대 적용#

한 프로젝트에서 IaC 스캐닝 결과를 검증했다면 같은 방식을 다른 프로젝트에도 적용할 수 있습니다.

강제 스캔 실행으로 그룹 전체에 IaC 스캐닝 설정을 적용합니다.
원격 설정 파일 지정으로 중앙 룰셋을 공유하고 재사용합니다.

문제 해결#

IaC 스캐닝을 사용할 때 다음 문제가 발생할 수 있습니다.

IaC 스캐닝 결과가 예기치 않게 `No longer detected`로 표시됨#

이전에 탐지된 결과가 예기치 않게 No longer detected로 표시된다면 스캐너 업데이트 때문일 수 있습니다. 업데이트로 효과가 없거나 오탐으로 확인된 규칙이 비활성화되면 그 결과는 No longer detected로 표시됩니다.

job 로그의 `exec /bin/sh: exec format error` 메시지#

job 로그에 exec /bin/sh: exec format error 오류가 표시될 수 있습니다. 이 문제는 AMD64가 아닌 아키텍처에서 IaC 스캐닝 분석기를 실행하려 할 때 발생합니다. IaC 스캐닝의 사전 요구 사항은 사전 요구 사항에서 확인합니다.

Infrastructure as Code 스캔

GitLab v19.5

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-10-15

요약

IaC 스캐닝 분석기는 JSON 형식의 리포트를 job 아티팩트로 출력합니다.

GitLab Ultimate에서는 IaC 스캐닝 결과가 추가로 처리되어 다음을 할 수 있습니다.

머지 리퀘스트에서 결과를 확인합니다.
승인 워크플로에 활용합니다.
취약점 리포트에서 검토합니다.

시작하기#

IaC 스캐닝을 처음 사용한다면 다음 단계를 따라 프로젝트에 적용합니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.
일관된 성능을 위해 최소 4GB RAM 이 필요합니다.
Docker 또는 Kubernetes 실행기를 사용하는 Linux 기반 GitLab Runner가 필요합니다. GitLab.com의 호스티드 러너를 사용한다면 Docker 또는 Kubernetes 실행기가 기본으로 켜져 있습니다.
- Windows의 GitLab Runner는 지원하지 않습니다.
- AMD64 외의 CPU 아키텍처는 지원하지 않습니다.
GitLab CI/CD 설정(.gitlab-ci.yml)에 test Stage가 있어야 합니다. test Stage는 기본으로 포함되지만, Stage를 재정의했다면 명시적으로 추가해야 합니다.

IaC 스캐닝을 활성화하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Build > Pipeline editor로 이동합니다.
IaC 스캐닝 CI/CD 템플릿이나 컴포넌트 중 하나를 추가합니다.

템플릿을 사용하려면 다음 줄을 추가합니다.
```
include:
  - template: Jobs/SAST-IaC.gitlab-ci.yml
```
CI/CD 컴포넌트를 사용하려면 다음 줄을 추가합니다.
```
include:
  - component: gitlab.com/components/sast/iac-sast@main
```
Validate 탭을 선택한 다음 Validate pipeline을 선택합니다.

Simulation completed successfully 메시지가 나오면 파일이 유효한 것입니다.
Edit 탭을 선택합니다.
다음 항목을 입력합니다.
- 커밋 메시지입니다.
- 브랜치입니다. 예를 들면 add-iac 입니다.
Start a new merge request with these changes 체크박스를 선택한 다음 Commit changes를 선택합니다.

머지 리퀘스트 페이지가 열립니다.
평소 워크플로에 맞게 항목을 입력한 다음 Create merge request를 선택합니다.
평소 워크플로에 맞게 머지 리퀘스트를 검토하고 수정한 다음 Merge를 선택합니다.

이제 파이프라인에서 IaC 스캐닝이 활성화됩니다.

IaC 스캐닝 job 이 모든 파이프라인에서 실행되어 KICS 분석기를 구동합니다.
분석기는 프로젝트에 지원되는 IaC 파일이 있는지 판별합니다.
지원되는 파일이 있으면 분석기가 취약점을 검사합니다.
지원되는 파일이 없으면 job은 결과 없이 완료됩니다.

해당 job은 파이프라인의 test Stage 아래에 표시됩니다.

동작하는 예시는 IaC 스캐닝 예제 프로젝트에서 확인할 수 있습니다.

다음 단계#

IaC 스캐닝을 활성화한 뒤에는 다음을 할 수 있습니다.

결과 이해하기에서 결과 해석 방법을 확인합니다.
최적화 팁을 검토합니다.
더 많은 프로젝트로 확대하는 계획을 세웁니다.

결과 이해하기#

사전 요구 사항:

프로젝트에 대한 Security Manager, Developer, Maintainer, Owner 중 하나의 권한이 필요합니다.

파이프라인에서 취약점을 검토하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
파이프라인을 선택합니다.
Security 탭을 선택합니다.
취약점을 선택하면 다음을 포함한 세부 정보를 볼 수 있습니다.
- Description: 취약점의 원인, 잠재적 영향, 권장 조치를 설명합니다.
- Status: 취약점이 분류되었는지 또는 해결되었는지 나타냅니다.
- Severity: 심각도 수준 자세히 보기에서 확인합니다.
- Location: 문제가 발견된 파일 이름과 줄 번호를 표시합니다. 파일 경로를 선택하면 코드 보기에서 해당 줄이 열립니다.
- Scanner: 어떤 분석기가 취약점을 탐지했는지 알려 줍니다.
- Identifiers: CWE 식별자와 탐지한 규칙의 ID 등 취약점을 분류하는 데 사용한 참조 목록입니다.

Ultimate에서는 보안 스캔 결과를 내려받을 수도 있습니다.

사전 요구 사항:

프로젝트에 대한 Security Manager, Developer, Maintainer, Owner 중 하나의 권한이 필요합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipelines를 선택합니다.
파이프라인을 선택합니다.
Security 탭을 선택합니다.
파이프라인의 Security 탭에서 Download results를 선택합니다.

자세한 내용은 파이프라인 보안 리포트를 참고합니다.

Note

결과는 기능 브랜치에서 생성됩니다. 기본 브랜치에 병합되면 그 결과가 취약점이 됩니다. 보안 상태를 평가할 때 이 구분이 중요합니다.

IaC 스캐닝 결과를 확인하는 다른 방법은 다음과 같습니다.

머지 리퀘스트 리포트: 새로 발생했거나 해결된 결과를 보여 줍니다.
머지 리퀘스트 변경 사항 보기: 변경된 줄에 인라인 주석을 표시합니다.
취약점 리포트: 기본 브랜치에서 확인된 취약점을 보여 줍니다.

지원되는 언어 및 프레임워크#

지원되는 설정 형식은 다음과 같습니다.

Ansible
AWS CloudFormation
Azure Resource Manager

[!note] IaC 스캐닝은 JSON 형식의 Azure Resource Manager 템플릿을 분석할 수 있습니다. 템플릿을 Bicep으로 작성했다면, Bicep CLI로 Bicep 파일을 JSON으로 변환해야 IaC 스캐닝이 분석할 수 있습니다.
Dockerfile
Google Deployment Manager
Kubernetes
OpenAPI
Terraform

KICS는 쿼리가 있는 리소스 유형에 대해서만 결과를 보고합니다. KICS에는 다음 공급자의 Terraform 쿼리가 있습니다.
- Alibaba Cloud
- AWS
- Azure
- Databricks
- GitHub
- Google Cloud
- Kubernetes
- NIFCLOUD
- Tencent Cloud
KICS에는 공급자와 무관한 검사도 있습니다. 다른 공급자에는 이러한 검사만 적용됩니다. 자세한 내용은 KICS 플랫폼을 참고합니다.

[!note] 사용자 지정 레지스트리에 있는 Terraform 모듈은 취약점 스캔 대상이 아닙니다. 제안된 기능에 관한 자세한 내용은 이슈 357004를 참고합니다.

IaC 스캐닝 최적화#

IaC 스캐닝을 최적화하면 잡음을 줄이고 관련 있는 결과에 집중할 수 있습니다.

sast-ruleset.toml 파일로 특정 규칙을 비활성화합니다.
sast-ruleset.toml 파일로 심각도 같은 규칙 속성을 재정의합니다.
해당 파일에 KICS 주석을 넣어 특정 파일의 스캔을 비활성화합니다.

IaC 스캐닝은 규칙 추가 또는 교체를 지원하지 않습니다. 각 분석기가 지원하는 옵션은 규칙 사용자 지정 옵션을 참고합니다.

규칙을 비활성화하거나 규칙 속성을 재정의할 때는 sast-ruleset.toml 파일을 사용합니다. 이 방식의 이점은 다음과 같습니다.

GitLab 취약점 관리와 연동되어 규칙을 비활성화하면 기존 결과가 자동으로 해결됩니다.
보안 정책 결정이 버전 관리되는 형태로 문서화됩니다.
IaC 스캐닝을 확대할 때 여러 프로젝트에서 룰셋을 공유할 수 있습니다.

룰셋 정의#

모든 IaC 스캐닝 규칙은 ruleset 절에 들어가며, 다음을 포함합니다.

규칙의 type 필드입니다. IaC 스캐닝에서 식별자 유형은 kics_id 입니다.
규칙 식별자의 value 필드입니다. KICS 규칙 식별자는 영숫자 문자열입니다. 규칙 식별자를 찾는 방법은 다음과 같습니다.
- JSON 리포트 아티팩트에서 찾습니다.
- 규칙 이름을 KICS 쿼리 목록에서 검색해 표시된 영숫자 식별자를 복사합니다. 규칙 이름은 규칙 위반이 탐지되면 취약점 세부 정보 페이지에 표시됩니다.

규칙 비활성화#

특정 IaC 스캐닝 규칙을 비활성화할 수 있습니다. 비활성화한 규칙이 이전에 탐지한 결과는 자동으로 해결됩니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

분석기 규칙을 비활성화하려면 다음을 수행합니다.

프로젝트 루트에 .gitlab 디렉터리가 없다면 새로 만듭니다.
.gitlab 디렉터리에 sast-ruleset.toml이라는 사용자 지정 룰셋 파일이 없다면 새로 만듭니다.
ruleset 절 안에서 disabled 플래그를 true로 설정합니다.
하나 이상의 ruleset 하위 절에 비활성화할 규칙을 나열합니다.

sast-ruleset.toml 파일을 기본 브랜치에 병합하면 비활성화한 규칙의 기존 결과가 자동으로 해결됩니다.

다음 sast-ruleset.toml 예시에서는 식별자의 type과 value를 대조해 비활성화할 규칙을 kics 분석기에 지정합니다.

[kics]
  [[kics.ruleset]]
    disable = true
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"

  [[kics.ruleset]]
    disable = true
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "b03a748a-542d-44f4-bb86-9199ab4fd2d5"

파일 스캔 비활성화#

파일 전체 또는 특정 규칙에 대해 스캔을 비활성화하려면 해당 파일에 KICS 주석을 사용합니다.

이 기능은 일부 IaC 파일 유형에서만 사용할 수 있습니다. 지원되는 파일 유형 목록은 KICS 문서에서 확인합니다.

파일 전체의 스캔을 건너뛰려면 파일 맨 위에 # kics-scan ignore 주석을 추가합니다.
파일 전체에서 특정 규칙을 비활성화하려면 파일 맨 위에 # kics-scan disable=<kics_id> 주석을 추가합니다.

규칙 재정의#

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

규칙을 재정의하려면 다음을 수행합니다.

프로젝트 루트에 .gitlab 디렉터리가 없다면 새로 만듭니다.
.gitlab 디렉터리에 sast-ruleset.toml이라는 사용자 지정 룰셋 파일이 없다면 새로 만듭니다.
하나 이상의 ruleset.identifier 하위 절에 재정의할 규칙을 나열합니다.
ruleset 절의 ruleset.override 안에 재정의할 키를 지정합니다. 키는 어떤 조합으로도 재정의할 수 있습니다. 유효한 키는 다음과 같습니다.
- description
- message
- name
- severity(유효한 값: Critical, High, Medium, Low, Unknown, Info)

다음 sast-ruleset.toml 예시에서는 식별자의 type과 value로 규칙을 찾아 재정의합니다.

[kics]
  [[kics.ruleset]]
    [kics.ruleset.identifier]
      type = "kics_id"
      value = "8212e2d7-e683-49bc-bf78-d6799075c5a7"
    [kics.ruleset.override]
      description = "OVERRIDDEN description"
      message = "OVERRIDDEN message"
      name = "OVERRIDDEN name"
      severity = "Info"

오프라인 설정#

GitLab Runner 설정#

GitLab Runner CI/CD 변수 pull_policy를 if-not-present로 설정합니다.

로컬 IaC 분석기 이미지 사용#

GitLab 컨테이너 레지스트리 대신 로컬 Docker 레지스트리에서 이미지를 가져오려면 로컬 IaC 분석기 이미지를 사용합니다.

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.
Docker 이미지를 로컬 오프라인 Docker 레지스트리로 가져오는 방법은 네트워크 보안 정책에 따라 달라집니다. 외부 리소스를 가져오거나 일시적으로 접근하기 위해 승인된 절차는 IT 담당자에게 확인합니다.

로컬 IaC 분석기 이미지를 사용하려면 다음을 수행합니다.

기본 IaC 분석기 이미지를 registry.gitlab.com에서 로컬 Docker 컨테이너 레지스트리로 가져옵니다.
```
registry.gitlab.com/security-products/kics:6
```
IaC 분석기 이미지는 주기적으로 업데이트되므로 로컬 사본도 주기적으로 갱신합니다.

CI/CD 변수 SECURE_ANALYZERS_PREFIX를 로컬 Docker 컨테이너 레지스트리로 설정합니다.

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

variables:
  SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers"

이제 IaC job 이 인터넷 접속 없이 로컬에 있는 분석기 Docker 이미지 사본을 사용합니다.

특정 분석기 버전 사용#

사전 요구 사항:

프로젝트에 대한 Maintainer 또는 Owner 권한이 필요합니다.

특정 분석기 버전을 사용하려면 다음을 수행합니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Build > Pipeline editor를 선택합니다.
SAST-IaC.gitlab-ci.yml 템플릿을 포함하는 줄 뒤에 SAST_ANALYZER_IMAGE_TAG CI/CD 변수를 추가합니다.

[!note] 이 변수는 특정 job 에만 설정합니다. 최상위에 설정하면 지정한 버전이 다른 SAST 분석기에도 적용됩니다.

태그는 다음과 같이 설정합니다.
- 3처럼 메이저 버전으로 설정합니다. 파이프라인이 이 메이저 버전에서 나오는 마이너·패치 업데이트를 사용합니다.
- 3.7처럼 마이너 버전으로 설정합니다. 파이프라인이 이 마이너 버전에서 나오는 패치 업데이트를 사용합니다.
- 3.7.0처럼 패치 버전으로 설정합니다. 파이프라인이 업데이트를 받지 않습니다.

다음 예시는 IaC 분석기의 특정 마이너 버전을 사용합니다.

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

kics-iac-sast:
  variables:
    SAST_ANALYZER_IMAGE_TAG: "3.1"

지원되는 배포판#

GitLab 스캐너는 크기와 유지 보수성을 고려해 Alpine 베이스 이미지로 제공됩니다.

FIPS 지원 이미지 사용#

GitLab은 표준 이미지 외에 FIPS 지원 Red Hat UBI 기반 스캐너 이미지도 제공합니다.

파이프라인에서 FIPS 지원 이미지를 사용하려면 SAST_IMAGE_SUFFIX를 -fips로 설정하거나 표준 태그에 -fips 확장을 붙입니다.

다음 예시는 SAST_IMAGE_SUFFIX CI/CD 변수를 사용합니다.

variables:
  SAST_IMAGE_SUFFIX: '-fips'

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

자동 취약점 해결#

여전히 유효한 취약점에 집중할 수 있도록, IaC 스캐닝은 다음 경우에 취약점을 자동으로 해결합니다.

미리 정의된 규칙을 비활성화한 경우입니다.
GitLab 이 기본 룰셋에서 규칙을 제거한 경우입니다.

나중에 그 규칙을 다시 활성화하면 결과가 다시 열려 분류 대상이 됩니다.

취약점 관리 시스템은 취약점을 자동으로 해결할 때 노트를 추가합니다.

리포트 JSON 형식#

IaC 스캐너는 기존 SAST 리포트 형식의 JSON 리포트 파일을 출력합니다. 자세한 내용은 이 리포트의 스키마를 참고합니다.

JSON 리포트 파일은 다음에서 내려받을 수 있습니다.

CI/CD 파이프라인 페이지입니다.
머지 리퀘스트의 파이프라인 탭입니다. artifacts: paths를 gl-sast-report.json으로 설정해야 합니다.

자세한 내용은 아티팩트 내려받기를 참고합니다.

확대 적용#

한 프로젝트에서 IaC 스캐닝 결과를 검증했다면 같은 방식을 다른 프로젝트에도 적용할 수 있습니다.

강제 스캔 실행으로 그룹 전체에 IaC 스캐닝 설정을 적용합니다.
원격 설정 파일 지정으로 중앙 룰셋을 공유하고 재사용합니다.

문제 해결#

IaC 스캐닝을 사용할 때 다음 문제가 발생할 수 있습니다.

Infrastructure as Code 스캔

시작하기#

다음 단계#

결과 이해하기#

지원되는 언어 및 프레임워크#

IaC 스캐닝 최적화#

룰셋 정의#

규칙 비활성화#

파일 스캔 비활성화#

규칙 재정의#

오프라인 설정#

GitLab Runner 설정#

로컬 IaC 분석기 이미지 사용#

특정 분석기 버전 사용#

지원되는 배포판#

FIPS 지원 이미지 사용#

자동 취약점 해결#

리포트 JSON 형식#

확대 적용#

문제 해결#

IaC 스캐닝 결과가 예기치 않게 No longer detected로 표시됨#

job 로그의 exec /bin/sh: exec format error 메시지#

Infrastructure as Code 스캔

시작하기#

다음 단계#

결과 이해하기#

지원되는 언어 및 프레임워크#

IaC 스캐닝 최적화#

룰셋 정의#

규칙 비활성화#

파일 스캔 비활성화#

규칙 재정의#

오프라인 설정#

GitLab Runner 설정#

로컬 IaC 분석기 이미지 사용#

특정 분석기 버전 사용#

지원되는 배포판#

FIPS 지원 이미지 사용#

자동 취약점 해결#

리포트 JSON 형식#

확대 적용#

문제 해결#

IaC 스캐닝 결과가 예기치 않게 No longer detected로 표시됨#

job 로그의 exec /bin/sh: exec format error 메시지#

IaC 스캐닝 결과가 예기치 않게 `No longer detected`로 표시됨#

job 로그의 `exec /bin/sh: exec format error` 메시지#

IaC 스캐닝 결과가 예기치 않게 `No longer detected`로 표시됨#

job 로그의 `exec /bin/sh: exec format error` 메시지#