의존성 스캐닝은 프로젝트에서 취약한 의존성을 모두 식별합니다. 그러나 모든 취약점의 위험도가 같지는 않습니다. 정적 도달 가능성 분석은 취약한 패키지 중 애플리케이션이 실제로 가져다 쓰는, 즉 도달 가능한 패키지를 판별하여 조치 우선순위를 정하는 데 도움을 줍니다. 정적 도달 가능성 분석을 사용하면 도달 가능한 취약점에 집중하여, 이론적 위험이 아니라 실제 노출 위협을 기준으로 조치 우선순위를 정할 수 있습니다.

정적 도달 가능성 분석은 프로젝트의 소스 코드를 분석하여 SBOM의 의존성 중 어떤 것이 도달 가능한지 판별합니다. 의존성 스캐닝은 모든 구성 요소와 그 전이 의존성을 식별하는 SBOM 리포트를 생성합니다. 그런 다음 정적 도달 가능성 분석이 SBOM의 각 의존성을 확인하여 도달 가능성 값을 추가하고, 실제 사용 데이터로 리포트를 보강합니다. 보강된 이 SBOM은 GitLab에 수집되어 취약점 결과를 보완합니다.

SBOM은 SBOM 파일과 소스 코드 파일이 동일한 프로젝트 디렉터리 트리에 속할 때만 보강됩니다. 중첩된 프로젝트가 여러 개 있으면 시스템은 가장 가까운(가장 깊은) 프로젝트 경로를 선택하여 보강 대상을 결정합니다. 정적 도달 가능성 분석은 Python 및 Java 패키지에 대해 SBOM의 패키지 이름을 해당 코드 임포트 경로에 매핑하는 메타데이터에 의존합니다. 이 메타데이터는 매주 업데이트됩니다.

의견은 이슈 535498에 남깁니다.

정적 도달 가능성 분석 켜기#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• 프로젝트가 지원되는 언어 및 패키지 관리자를 사용해야 합니다.
• 의존성 스캐닝 분석기 0.39.0 이상 버전이어야 합니다(이전 버전도 특정 언어를 지원할 수 있습니다. 위 History 참고).
• 프로젝트에 SBOM을 사용한 의존성 스캐닝이 켜져 있어야 합니다. Gemnasium 분석기는 지원되지 않습니다.
• 언어별 필수 요건:
  • Python:
    • 의존성 그래프 파일을 build Stage의 job 아티팩트로 제공해야 합니다. pip 또는 pipenv 안내를 참고합니다. 지원되는 그 밖의 Python 패키지 관리자는 의존성 스캐닝 분석기 문서를 참고합니다.
  • JavaScript 및 TypeScript:
    • 리포지터리에 의존성 스캐닝 분석기가 지원하는 lockfile 이 있어야 합니다.
  • Java:
    • 의존성 그래프 파일을 build Stage의 job 아티팩트로 제공해야 합니다. Maven 또는 Gradle 안내를 참고합니다.

프로젝트에서 정적 도달 가능성 분석을 켜려면 다음 단계를 수행합니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Code > Repository를 선택합니다.

3. .gitlab-ci.yml 파일을 선택합니다.

4. Edit > Edit single file을 선택합니다.

5. 다음 구성을 추가합니다.

   include:
   - template: Jobs/Dependency-Scanning.v2.gitlab-ci.yml
   
   variables:
     DS_STATIC_REACHABILITY_ENABLED: true
   

6. Commit changes를 선택합니다.

의존성 스캐닝이 실행되어 SBOM을 출력하면 그 결과가 정적 도달 가능성 분석으로 보완됩니다.

도달 가능성 값#

의존성은 다음 도달 가능성 값 중 하나를 가집니다. Yes로 표시된 의존성은 코드에서 실제로 사용되는 것이 확인된 항목이므로 분류와 조치를 우선합니다.

Yes : 이 취약점과 연결된 패키지가 코드에서 도달 가능한 것으로 확인되었습니다. 직접 의존성이 도달 가능으로 표시되면 그 전이 의존성도 도달 가능으로 표시됩니다.

Not Found : 정적 도달 가능성 분석이 정상적으로 실행되었지만 취약한 패키지의 사용을 감지하지 못했습니다.

Not Available : 정적 도달 가능성 분석이 실행되지 않아 도달 가능성 데이터가 없습니다.

취약한 의존성의 도달 가능성 값을 확인하려면 다음 방법을 사용합니다.

• 취약점 리포트에서 Severity 값 위에 포인터를 올립니다.
• 취약점 세부 정보 페이지에서 Reachable 값을 확인합니다.
• GraphQL 쿼리로 도달 가능한 취약점 목록을 조회합니다.

"Not Found" 결과#

Not Found 도달 가능성 값이 해당 의존성을 사용하지 않는다는 보장은 아닙니다. 정적 도달 가능성 분석이 패키지 사용 여부를 항상 확정할 수는 없기 때문입니다.

의존성은 다음과 같은 경우에 not found로 표시됩니다.

• lockfile에는 있지만 코드에서 임포트되지 않는 경우
• 제외된 디렉터리에 있는 경우(예: DS_EXCLUDED_PATHS로 구성된 디렉터리)
• 커버리지 테스트나 린팅 패키지처럼 로컬 사용 전용으로 포함된 도구인 경우

제외된 디렉터리의 예를 살펴봅니다. CI/CD 변수 DS_EXCLUDED_PATHS="test"를 정의했고, 프로젝트의 리포지터리 구조가 다음과 같다고 가정합니다.

.
├── pipdeptree.json  // contains "requests" dependency
└── test/
    └── app.py       // imports "requests" dependency

이 예시에서 그래프 파일 pipdeptree.json은 제외된 디렉터리 바깥에 있으므로 분석되어 파일에 나열된 의존성이 식별됩니다. 그러나 requests 의존성을 임포트하는 소스 코드는 제외된 디렉터리 안에 있으므로 정적 도달 가능성 분석이 도달 가능성을 확인하지 않습니다. 그 결과 requests 의존성은 Not found로 표시됩니다. 다시 말해 lockfile은 제외된 디렉터리 바깥에 있고 의존성을 임포트하는 코드는 그 안에 있을 때 이런 현상이 발생합니다.

지원되는 언어 및 패키지 관리자#

지원 범위는 언어별 성숙도에 따라 다르며, 언어마다 특정 패키지 관리자와 파일 유형을 포함합니다.

오프라인 환경#

오프라인 환경에서 정적 도달 가능성 분석을 실행하려면 초기 설정과 지속적인 유지 관리가 필요합니다.

초기 설정:

• 의존성 스캐닝(SBOM)의 오프라인 환경 요건을 완료합니다.

지속적인 유지 관리:

• 새 버전이 릴리스될 때마다 로컬 의존성 스캐닝(SBOM) 이미지를 업데이트합니다.

Python 및 Java 패키지에서 정적 도달 가능성 분석은 메타데이터를 사용하여 SBOM의 패키지 이름을 해당 코드 임포트 경로에 매핑합니다. 이 메타데이터는 의존성 스캐닝 분석기의 이미지에 포함되어 있습니다. 메타데이터가 오래되면 도달 가능성 분석이 불완전하거나 부정확할 수 있습니다.