히스토리

• GitLab 16.2에서 모호한 패스스루 참조 지정을 위한 지원이 활성화되었습니다.

Semgrep 기반 SAST 분석기와 GitLab Advanced SAST 분석기에는 각각 기본 룰셋이 있습니다. 조직의 보안 요구사항에 맞게 규칙을 사용자 정의할 수 있습니다. 예를 들어 특정 규칙의 심각도 수준을 올리고 싶을 수 있습니다.

Semgrep 기반 SAST 분석기에 대한 사용자 정의 규칙을 작성하기 전에 Semgrep Playground에서 인터랙티브하게 프로토타입 및 테스트할 수 있습니다. Playground를 사용할 때 별표 아이콘(star)이 있고 Semgrep Pro Engine으로 발견된 결과 툴팁이 있는 test code 패널의 결과는 무시하세요. 이 결과들은 GitLab이 사용하는 오픈 소스 Semgrep 엔진과 호환되지 않습니다. Semgrep 규칙 형식에 대한 자세한 내용은 Semgrep 구문 배우기를 참조하세요.

룰셋 용어집#

규칙(Rule) : 특정 취약점을 스캔하는 개별 보안 검사 또는 감지 패턴.

규칙 파일(Rules file) : 분석기가 적용할 개별 규칙을 지정하는 YAML 형식 파일.

룰셋 구성 파일(Ruleset configuration file) : 적용할 룰셋과 해당 룰셋이 로컬 또는 원격에 저장되는지를 지정하는 TOML 형식 파일. 파일명은 sast-ruleset.toml.

패스스루(Passthrough) : 패스스루는 파일, Git 저장소, URL 또는 인라인 구성에서 룰셋 사용자 정의를 가져오는 구성 소스입니다. 여러 패스스루를 체인으로 결합할 수 있으며, 각각은 이전 구성을 덮어쓰거나 추가할 수 있습니다.

규칙 사용자 정의 옵션#

규칙을 비활성화하거나, 메타데이터를 재정의하거나, 규칙을 교체하거나 추가하여 기본 룰셋을 사용자 정의할 수 있습니다.

아래 표는 각 분석기 유형에 대해 사용 가능한 사용자 정의 옵션을 보여줍니다.

기본 규칙 비활성화#

모든 SAST 분석기에 대한 기본 규칙을 비활성화할 수 있습니다. 예를 들어 조직 정책에 따라 특정 규칙을 제외하고 싶을 수 있습니다.

다음 예제를 참조하세요:

• 특정 기본 GitLab Advanced SAST 규칙 비활성화
• 기타 SAST 분석기의 특정 기본 규칙 비활성화

기본 규칙 메타데이터 재정의#

모든 SAST 분석기에 대한 기본 규칙의 특정 속성을 재정의할 수 있습니다. 예를 들어 조직 정책에 따라 취약점의 심각도를 재정의하거나 취약점 보고서에 표시할 다른 메시지를 선택할 수 있습니다.

예제는 기본 규칙 메타데이터 재정의를 참조하세요.

기본 규칙 교체 또는 추가#

Semgrep 기반 SAST 분석기 및 GitLab Advanced SAST 분석기의 기본 규칙을 교체하거나 추가할 수 있습니다. 기본적으로 사용자 정의 룰셋을 정의하면 기본 룰셋이 교체됩니다. 기본 룰셋에 추가하려면 룰셋 구성 파일에서 keepdefaultrules를 true로 설정해야 합니다.

다음 예제를 참조하세요:

• 모든 기본 GitLab Advanced SAST 규칙 교체
• semgrep의 기본 규칙 교체 또는 추가

룰셋 사용자 정의의 효과#

다음 표는 SAST 룰셋을 사용자 정의할 때 발생하는 결과를 설명합니다:

구성 방법#

다음과 같은 방법으로 룰셋 사용자 정의를 제공할 수 있습니다:

로컬 룰셋 파일 : 저장소에 커밋된 sast-ruleset.toml 파일에 사용자 정의를 정의합니다. 이 접근 방식은 소스 코드와 함께 룰셋 구성을 버전 관리 하에 유지합니다.

원격 룰셋 파일 : 룰셋 파일이 호스팅되는 원격 위치(Git 저장소, URL 또는 기타 소스)를 지정합니다. 이 접근 방식을 통해 룰셋을 중앙에서 관리하고 여러 프로젝트에서 재사용할 수 있습니다.

패스스루를 사용하여 사용자 정의를 제공합니다. 패스스루는 룰셋으로 결합할 수 있는 구성 소스입니다.

모든 룰셋 사용자 정의는 SAST 룰셋 스키마를 준수해야 합니다.

로컬 룰셋 파일 사용#

소스 코드와 함께 사용자 정의를 저장하려면 로컬 룰셋 파일을 사용하세요. 로컬 사용자 정의는 개별 프로젝트에만 적용됩니다.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할.

로컬 룰셋 파일을 만들려면:

1. 프로젝트 루트에 .gitlab 디렉토리가 없으면 만듭니다.
2. .gitlab 디렉토리에 sast-ruleset.toml이라는 파일을 만듭니다.
3. sast-ruleset.toml 파일에 사용자 정의 룰셋을 추가합니다.
4. 로컬 룰셋 파일을 저장소에 커밋합니다.

로컬 룰셋 파일의 예제를 참조하세요.

원격 룰셋 파일 사용#

히스토리

• GitLab 16.1에서 도입되었습니다.

여러 프로젝트에 동일한 사용자 정의를 적용하려면 원격 룰셋 파일을 사용하세요. 원격 룰셋 파일은 이를 사용하는 프로젝트의 저장소 외부에 저장됩니다.

원격 룰셋 파일을 사용하려면 다음을 수행하세요:

• 원격 룰셋을 만듭니다.
• 각 프로젝트에서 원격 룰셋을 참조합니다.

원격 룰셋 파일 만들기#

여러 프로젝트의 중앙 룰셋으로 원격 룰셋 파일을 만듭니다.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할.

원격 룰셋을 만들려면:

• 프로젝트 저장소에 룰셋을 만드세요.

  룰셋 파일 예제는 예제를 참조하세요.

원격 룰셋 파일 참조#

원격 룰셋 파일을 참조하여 해당 규칙을 프로젝트에 적용합니다.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할.
• 프로젝트의 원격 룰셋.
• 원격 룰셋이 저장된 프로젝트에 대한 읽기 액세스. 예를 들어 작업 토큰이나 그룹 액세스 토큰을 사용하세요.

각 프로젝트에서 원격 룰셋 파일을 참조하려면 다음을 수행하세요:

• CI/CD 변수 SAST_RULESET_GIT_REFERENCE를 원격 룰셋 파일의 위치를 지정하도록 설정하세요.

  원격 룰셋 파일 참조는 프로젝트 URI, 선택적 인증 및 선택적 Git SHA를 지정하기 위한 Git URL과 유사한 형식을 사용합니다. 변수는 다음 형식을 사용합니다:

  [[:]@][@]
  

다음 예제는 SAST를 활성화하고 원격 룰셋 파일을 사용합니다. 이 예제에서 파일은 example-ruleset-project의 기본 브랜치에 .gitlab/sast-ruleset.toml 경로로 커밋됩니다.

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

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"

고급 예제는 개인 원격 구성 지정 예제를 참조하세요.

원격 구성 파일 트러블슈팅#

원격 구성 파일이 사용자 정의를 올바르게 적용하지 않는 것처럼 보이는 경우 원인은 다음과 같을 수 있습니다:

1. 저장소에 로컬 .gitlab/sast-ruleset.toml 파일이 있습니다.
   • 기본적으로 원격 구성이 변수로 설정된 경우에도 로컬 파일이 있으면 사용됩니다.
   • SECURE_ENABLE_LOCAL_CONFIGURATION CI/CD 변수를 false로 설정하여 로컬 구성 파일을 무시할 수 있습니다.
2. 인증 문제가 있습니다.
   • 이것이 문제의 원인인지 확인하려면 인증이 필요 없는 저장소 위치에서 구성 파일을 참조해 보세요.

스키마#

룰셋 구성 파일은 TOML 구문을 사용합니다. 다음 섹션은 각 구성 요소의 구조 및 유효한 설정을 설명합니다.

최상위 섹션#

최상위 섹션에는 TOML 테이블로 정의된 하나 이상의 구성 섹션이 포함됩니다.

구성 예:

[semgrep]
...

기존 규칙을 수정하는 구성 섹션과 사용자 정의 룰셋을 빌드하는 구성 섹션을 동시에 만드는 것을 피하세요. 후자는 기본 규칙을 완전히 교체합니다.

[$analyzer] 구성 섹션#

[$analyzer] 섹션을 통해 분석기의 동작을 사용자 정의할 수 있습니다. 유효한 속성은 수행하는 구성의 종류에 따라 다릅니다.

interpolate#

아래 예제는 개인 저장소에 액세스하기 위해 $GITURL 환경 변수를 사용하는 구성을 보여줍니다. 변수에는 사용자 이름과 토큰이 포함되어 있으므로(예: https://user:token@url) 구성 파일에 명시적으로 저장되지 않습니다.

[semgrep]
  description = "My private Semgrep ruleset"
  interpolate = true

  [[semgrep.passthrough]]
    type  = "git"
    value = "$GITURL"
    ref = "main"

[[$analyzer.ruleset]] 섹션#

[[$analyzer.ruleset]] 섹션은 단일 기본 규칙을 대상으로 하여 수정합니다. 분석기당 하나에서 여러 개의 이러한 섹션을 정의할 수 있습니다.

구성 예:

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    ...

[$analyzer.ruleset.identifier] 섹션#

[$analyzer.ruleset.identifier] 섹션은 수정하려는 기본 규칙의 식별자를 정의합니다.

분석기에서 생성된 gl-sast-report.json을 보면 type 및 value에 대한 올바른 값을 조회할 수 있습니다. 이 파일은 분석기의 CI 작업에서 작업 아티팩트로 다운로드할 수 있습니다.

예를 들어 아래 스니펫은 세 개의 식별자를 가진 semgrep 규칙의 발견 결과를 보여줍니다. JSON 개체의 type 및 value 키는 이 섹션에서 제공해야 하는 값에 해당합니다.

...
  "vulnerabilities": [
    {
      "id": "7331a4b7093875f6eb9f6eb1755b30cc792e9fb3a08c9ce673fb0d2207d7c9c9",
      "category": "sast",
      "message": "Key Exchange without Entity Authentication",
      "description": "Audit the use of ssh.InsecureIgnoreHostKey\n",
      ...
      "identifiers": [
        {
          "type": "semgrep_id",
          "name": "gosec.G106-1",
          "value": "gosec.G106-1"
        },
        {
          "type": "cwe",
          "name": "CWE-322",
          "value": "322",
          "url": "https://cwe.mitre.org/data/definitions/322.html"
        },
        {
          "type": "gosec_rule_id",
          "name": "Gosec Rule ID G106",
          "value": "G106"
        }
      ]
    }
    ...
  ]
...

구성 예:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1
    ...

[$analyzer.ruleset.override] 섹션#

[$analyzer.ruleset.override] 섹션을 통해 기본 규칙의 속성을 재정의할 수 있습니다.

구성 예:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.override]
      severity = "Critical"
      name = "Command injection"
    ...

[[$analyzer.passthrough]] 섹션#

[[$analyzer.passthrough]] 섹션을 통해 분석기의 사용자 정의 구성을 빌드할 수 있습니다. 분석기당 최대 20개의 이러한 섹션을 정의할 수 있습니다. 패스스루는 분석기의 기본 규칙을 교체하는 완전한 구성으로 평가되는 _패스스루 체인_으로 구성됩니다.

패스스루는 순서대로 평가됩니다. 체인의 뒷부분에 나열된 패스스루는 더 높은 우선순위를 가지며 이전 패스스루에서 생성된 데이터를 덮어쓰거나 추가할 수 있습니다(mode에 따라). 이는 기존 구성을 사용하거나 수정해야 하는 경우에 유용합니다.

단일 패스스루에 의해 생성된 구성의 크기는 10MB로 제한됩니다.

패스스루 유형#

예제#

다음 예제는 일반적인 시나리오에 대한 룰셋을 사용자 정의하는 방법을 보여줍니다. 각 예제에서 사용된 구성 옵션을 이해하려면 스키마 섹션을 사용하세요.

모든 기본 GitLab Advanced SAST 규칙 교체#

다음 사용자 정의 룰셋 구성으로 GitLab Advanced SAST 분석기의 기본 룰셋이 스캔되는 저장소의 my-gitlab-advanced-sast-rules.yml이라는 파일에 포함된 사용자 정의 룰셋으로 교체됩니다.

# my-gitlab-advanced-sast-rules.yml
---
rules:
- id: my-custom-rule
  pattern: print("Hello World")
  message: |
    Unauthorized use of Hello World.
  severity: ERROR
  languages:
  - python

[gitlab-advanced-sast]
  description = "My custom ruleset for Semgrep"

  [[gitlab-advanced-sast.passthrough]]
    type  = "file"
    value = "my-gitlab-advanced-sast-rules.yml"

특정 기본 GitLab Advanced SAST 규칙 비활성화#

이 예제에서는 다음 기준을 기반으로 특정 기본 규칙을 비활성화합니다:

• 취약점의 전체 클래스를 식별하는 CWE 식별자.
• GitLab Advanced SAST에서 사용된 특정 감지 전략을 식별하는 GitLab Advanced SAST 규칙 ID.
• 호환성을 위해 GitLab Advanced SAST 발견 결과에 포함된 관련 Semgrep 규칙 ID. 이 추가 메타데이터를 통해 두 분석기가 같은 위치에서 유사한 발견 결과를 생성할 때 발견 결과가 자동으로 전환될 수 있습니다.

이러한 식별자는 각 취약점의 취약점 세부 정보에 표시됩니다. 다운로드 가능한 SAST 보고서 아티팩트에서 각 식별자와 관련 type도 볼 수 있습니다.

[gitlab-advanced-sast]
  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "cwe"
      value = "89"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "gitlab-advanced-sast_id"
      value = "java-spring-csrf-unrestricted-requestmapping-atomic"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "semgrep_id"
      value = "java_cookie_rule-CookieHTTPOnly"

기타 SAST 분석기의 특정 기본 규칙 비활성화#

다음 사용자 정의 룰셋 구성으로 다음 기본 규칙이 보고서에서 제외됩니다:

• semgrep_id가 gosec.G106-1이거나 cwe가 322인 semgrep 규칙.
• sobelow_rule_id가 sql_injection인 sobelow 규칙.
• flawfinder_func_name이 memcpy인 flawfinder 규칙.

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1"

  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "cwe"
      value = "322"

[sobelow]
  [[sobelow.ruleset]]
    disable = true
    [sobelow.ruleset.identifier]
      type = "sobelow_rule_id"
      value = "sql_injection"

[flawfinder]
  [[flawfinder.ruleset]]
    disable = true
    [flawfinder.ruleset.identifier]
      type = "flawfinder_func_name"
      value = "memcpy"

기본 규칙 메타데이터 재정의#

다음 사용자 정의 룰셋 구성으로 semgrep으로 발견된 유형 CWE 및 값 322의 취약점의 심각도가 Critical로 재정의됩니다.

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.identifier]
      type = "cwe"
      value = "322"
    [semgrep.ruleset.override]
      severity = "Critical"

semgrep의 기본 규칙 교체 또는 추가#

다음 사용자 정의 룰셋 구성으로 semgrep 분석기의 기본 룰셋이 스캔되는 저장소의 my-semgrep-rules.yml이라는 파일에 포함된 사용자 정의 룰셋으로 교체됩니다.

# my-semgrep-rules.yml
---
rules:
- id: my-custom-rule
  pattern: print("Hello World")
  message: |
    Unauthorized use of Hello World.
  severity: ERROR
  languages:
  - python

[semgrep]
  description = "My custom ruleset for Semgrep"

  [[semgrep.passthrough]]
    type  = "file"
    value = "my-semgrep-rules.yml"

semgrep을 위한 패스스루 체인을 사용하여 사용자 정의 구성 빌드#

다음 사용자 정의 룰셋 구성으로 semgrep 분석기의 기본 룰셋이 네 개의 패스스루 체인을 평가하여 생성된 사용자 정의 룰셋으로 교체됩니다. 각 패스스루는 컨테이너 내의 /sgrules 디렉토리에 기록되는 파일을 생성합니다. Git 원격이 응답하지 않는 경우를 대비하여 60초의 timeout이 설정됩니다.

이 예제에서는 다양한 패스스루 유형이 시연됩니다:

• 두 개의 git 패스스루: 첫 번째는 myrules Git 저장소의 develop 브랜치를 가져오고, 두 번째는 sast-rules 저장소의 97f7686 리비전을 가져오며 go 하위 디렉토리의 파일만 고려합니다.
  • sast-rules 항목은 구성의 뒷부분에 나타나므로 더 높은 우선순위를 가집니다.
  • 두 체크아웃 사이에 파일 이름 충돌이 있으면 sast-rules 저장소의 파일이 myrules 저장소의 파일을 덮어씁니다.
• value를 /sgrules/insecure.yml에 기록하는 raw 패스스루.
• URL에 호스팅된 구성을 가져와 /sgrules/gosec.yml에 기록하는 url 패스스루.

그 후 Semgrep은 /sgrules 아래에 있는 최종 구성으로 호출됩니다.

[semgrep]
  description = "My custom ruleset for Semgrep"
  targetdir = "/sgrules"
  timeout = 60

  [[semgrep.passthrough]]
    type  = "git"
    value = "https://gitlab.com/user/myrules.git"
    ref = "develop"

  [[semgrep.passthrough]]
    type  = "git"
    value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git"
    ref = "97f7686db058e2141c0806a477c1e04835c4f395"
    subdir = "go"

  [[semgrep.passthrough]]
    type  = "raw"
    target = "insecure.yml"
    value = """
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function insecure detected
  metadata:
    cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor"
  severity: "ERROR"
  languages:
    - "go"
"""

  [[semgrep.passthrough]]
    type  = "url"
    value = "https://semgrep.dev/c/p/gosec"
    target = "gosec.yml"

체인에서 패스스루 모드 구성#

체인의 패스스루 사이에서 발생하는 파일 이름 충돌을 처리하는 방법을 선택할 수 있습니다. 기본 동작은 동일한 이름의 기존 파일을 덮어쓰는 것이지만, 대신 mode = append를 선택하여 나중 파일의 내용을 이전 파일에 추가할 수 있습니다.

append 모드는 file, url, raw 패스스루 유형에만 사용할 수 있습니다.

다음 사용자 정의 룰셋 구성에서, 두 개의 raw 패스스루를 사용하여 /sgrules/my-rules.yml 파일을 반복적으로 조합하고, 이를 룰셋으로 Semgrep에 제공합니다. 각 패스스루는 룰셋에 단일 규칙을 추가합니다. 첫 번째 패스스루는 Semgrep 규칙 구문에 따라 최상위 rules 객체를 초기화합니다.

[semgrep]
  description = "My custom ruleset for Semgrep"
  targetdir = "/sgrules"
  validate = true

  [[semgrep.passthrough]]
    type  = "raw"
    target = "my-rules.yml"
    value = """
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function 'insecure' detected
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
"""

  [[semgrep.passthrough]]
    type  = "raw"
    mode  = "append"
    target = "my-rules.yml"
    value = """
- id: "secret"
  patterns:
    - pattern-either:
        - pattern: '$MASK = "..."'
    - metavariable-regex:
        metavariable: "$MASK"
        regex: "(password|pass|passwd|pwd|secret|token)"
  message: |
    Use of hard-coded password
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
"""

# /sgrules/my-rules.yml
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function 'insecure' detected
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
- id: "secret"
  patterns:
    - pattern-either:
        - pattern: '$MASK = "..."'
    - metavariable-regex:
        metavariable: "$MASK"
        regex: "(password|pass|passwd|pwd|secret|token)"
  message: |
    Use of hard-coded password
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"

개인 원격 구성 지정#

다음 예제는 SAST를 활성화하고 공유 룰셋 사용자 정의 파일을 사용합니다:

• 파일은 인증이 필요한 개인 프로젝트에서 다운로드됩니다. 이 예제는 CI/CD 변수에 안전하게 저장된 그룹 액세스 토큰을 사용합니다.
• 파일은 기본 브랜치 대신 특정 Git 커밋 SHA에서 체크아웃됩니다.

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

variables:
  SAST_RULESET_GIT_REFERENCE: "oauth2:$GROUP_ACCESS_TOKEN@gitlab.com/example-group/example-ruleset-project@c8ea7e3ff126987fb4819cc35f2310755511c2ab"

데모 프로젝트#

이러한 구성 옵션 중 일부를 보여주는 데모 프로젝트를 참조하세요.

이러한 프로젝트 중 상당수는 원격 룰셋을 사용하여 규칙을 재정의하거나 비활성화하는 것을 시연하며 각 분석기별로 그룹화되어 있습니다.

원격 룰셋 설정에 대한 비디오 데모도 시청할 수 있습니다:

• 원격 룰셋이 있는 IaC 분석기