참고: CodeQL 모델 팩 및 CodeQL 모델 편집기는 현재 베타 버전이며 변경될 수 있습니다. 모델 팩은 C#, Java/Kotlin, and Ruby 분석에 의해 지원됩니다.
CodeQL 모델 편집기 정보
CodeQL 모델 팩을 사용하면 CodeQL code scanning 분석을 확장하여 기본적으로 지원되지 않는 코드베이스에서 사용되는 사용자 지정 라이브러리 및 프레임워크를 인식할 수 있습니다. CodeQL 모델 편집기를 사용하여 고유한 모델 팩을 만들 수 있습니다. 모델 편집기에서는 애플리케이션의 외부 의존 관계에 대한 호출을 모델링하거나 외부 의존 관계의 모든 공용 항목 및 종료 지점을 완전히 모델링하는 방법을 안내합니다.
모델 팩으로 code scanning 분석을 사용자 지정하는 방법에 대한 자세한 내용은 "기본 설정 구성 편집" 및 "코드 검색을 위한 고급 설정 사용자 지정"을 참조하십시오.
모델 편집기를 열면 현재 선택한 CodeQL 데이터베이스를 분석하고 애플리케이션에서 외부 API 및 모든 공용 메서드를 사용하는 위치를 식별합니다. 외부(또는 타사) API는 선택한 CodeQL 데이터베이스에 속하지 않는 API입니다.
모델 편집기에는 다음의 두 가지 모드가 있습니다.
-
애플리케이션 모드(기본 보기): 선택한 CodeQL 데이터베이스에서 사용하는 각 외부 프레임워크를 편집기에 나열합니다. 프레임워크를 확장하면 각 호출을 통해 데이터 흐름을 모델링하는 데 사용할 수 있는 옵션과 함께 외부 API와의 모든 호출 목록이 표시됩니다. 이 모드는 특정 코드베이스에 대한 CodeQL 결과를 개선하는 데 가장 유용합니다.
-
종속성 모드: 선택한 CodeQL 데이터베이스에서 공개적으로 액세스할 수 있는 모든 API를 편집기에서 식별합니다. 이 보기는 코드베이스에서 사용할 수 있는 각 공용 API를 모델링하는 단계를 안내합니다. 전체 API 모델링을 완료하면 모델을 저장하고 사용하여 종속성을 사용하는 모든 코드베이스에 대한 CodeQL 분석을 개선할 수 있습니다.
이 문서의 나머지 부분에서는 CodeQL 모델 편집기를 사용하여 종속성을 모델링하는 실질적인 내용을 다룹니다. 기술 정보는 CodeQL 언어 설명서에서 Java 및 Kotlin용 라이브러리 모델 사용자 지정, Ruby용 라이브러리 모델 사용자 지정 및 C#용 라이브러리 모델 사용자 지정를 참조하세요.
CodeQL 모델 편집기 표시
참고: 이 베타 기능을 사용하려면 Visual Studio Code용 최신 버전의 CodeQL 익스텐션을 설치합니다.
-
VS Code에서 CodeQL 작업 영역을 엽니다. 예를 들면
vscode-codeql-starter
작업 영역을 엽니다. 시작 작업 영역을 사용하는 경우main
의ql
하위 모듈을 업데이트하여 모델 편집기용 데이터를 수집하는 데 사용되는 쿼리가 있는지 확인합니다. -
Visual Studio Code에서 왼쪽 사이드바의 QL을 클릭하여 GitHub Copilot 익스텐션을 표시합니다.
-
"데이터베이스" 보기에서 모델링하려는 CodeQL 데이터베이스를 선택합니다.
-
CodeQL "메서드 모델링" 보기에서 모델링 시작을 클릭하여 모델 편집기를 표시합니다. 또는 VS Code Command Palette을(를) 사용하여 CodeQL: 모델 편집기 열기(베타) 명령을 실행합니다.
-
CodeQL 모델 편집기는 코드에서 API를 식별하기 위해 일련의 원격 분석 쿼리를 실행하며 편집기는 새 탭에 표시됩니다.
-
원격 분석 쿼리가 완료되면 식별된 API가 편집기에 표시됩니다.
팁: 호출 또는 메서드를 모델링하는 동안 더 많은 공간을 확보하기 위해 CodeQL "메서드 모델링" 보기를 기본 사이드바에서 보조 사이드바로 이동할 수 있습니다. 보기를 닫은 경우 VS Code의 "보기" 메뉴에서 다시 열어 보기 열기... 를 클릭할 수 있습니다.
코드베이스가 외부 API에 대해 호출하는 모델링
이 방법은 일반적으로 CodeQL 결과의 정밀도를 향상하려는 특정 코드베이스를 볼 때 사용합니다. 이 기능은 코드베이스가 CodeQL에서 지원하지 않는 프레임워크 또는 라이브러리를 사용하고 프레임워크 또는 라이브러리의 소스 코드가 분석에 포함되지 않은 경우에 유용합니다.
이 섹션에서는 "sofa-jraft"라는 오픈 소스 Java 프로젝트를 예로 사용합니다. 다른 컴파일된 언어로 작성된 외부 API에 대한 호출을 모델링하는 환경도 비슷합니다.
-
Visual Studio Code에서 CodeQL 적용 범위를 개선할 CodeQL 데이터베이스를 선택합니다.
-
CodeQL 모델 편집기를 표시합니다. 기본적으로 편집기는 애플리케이션 모드에서 실행되므로 선택한 코드베이스에서 사용하는 외부 API 목록이 표시됩니다.
-
외부 API를 확장하고 코드베이스에서 외부 의존 관계로의 호출 목록을 보려면 클릭합니다.
-
API 호출 또는 메서드와 연결된 보기를 클릭하여 코드베이스에서 사용되는 위치를 표시합니다.
-
코드베이스에서 API로의 첫 번째 호출이 포함된 파일이 열리고 CodeQL "메서드 사용량" 보기가 VS Code에 표시됩니다(여기서 "문제" 및 "터미널" 보기는 일반적으로 표시됨). CodeQL "메서드 사용량" 보기는 코드에서 API로의 모든 호출 목록을 메서드별로 그룹화합니다. 각 사용을 통해 클릭하여 메서드 사용을 모델링하는 방법을 결정할 수 있습니다.
-
메서드 사용을 모델링하는 방법을 결정한 경우 다른 모델 유형을 선택할 수 있습니다. CodeQL 익스텐션의 CodeQL "메서드 모델링" 보기에서 "모델 유형" 아래의 드롭다운을 클릭합니다. 이 변경 내용은 기본 모델 편집기에서 자동으로 반영됩니다.
-
해당 행의 나머지 필드는 선택한 모델 유형에 사용할 수 있는 옵션으로 업데이트됩니다.
- "원본": 모델링할 "출력" 요소를 선택합니다.
- "싱크": 모델링할 "입력" 요소를 선택합니다.
- "흐름 요약": 모델링할 "입력" 및 "출력" 요소를 선택합니다.
-
모델에 대한 데이터 흐름의 "종류"를 정의합니다.
-
모델링을 마쳤으면 기본 모델 편집기를 표시하고 모두 저장 또는 저장을 클릭합니다(확장된 각 메서드 목록의 오른쪽 아래에 표시됨). 편집기에서 모델링된 메서드의 백분율이 업데이트됩니다.
모델은 .github/codeql/extensions/CODEQL-MODEl-PACK
작업 영역에 저장되며, 여기서 CODEQL-MODEL-PACK
은 선택한 CodeQL 데이터베이스의 이름입니다. 즉, CodeQL에서 분석한 리포지토리, 하이픈, 언어의 이름입니다. 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.
모델은 각 외부 API에 대해 하나씩 일련의 YAML 데이터 확장 프로그램 파일에 저장됩니다. 예시:
.github/codeql/extensions/sofa-jraft-java # the model pack directory
models
jmh-core.model.yml # models calls to jmh-core@1.20
rocksdbjni.model.yml # models calls to rocksdbjni@7.7.3
코드베이스의 공용 API 모델링
일반적으로 조직에서 둘 이상의 코드베이스에 사용하는 프레임워크 또는 라이브러리를 모델링하려는 경우 이 메서드를 사용합니다. 모델 만들기 및 테스트를 마쳤으면 전체 조직에서 사용할 GitHub Container registry에 CodeQL 모델 팩을 게시할 수 있습니다.
이 섹션에서는 "sofa-jraft"라는 오픈 소스 Java 프로젝트를 예로 사용합니다. 다른 컴파일된 언어로 작성된 외부 API에 대한 호출을 모델링하는 환경도 비슷합니다.
-
모델링하려는 CodeQL 데이터베이스를 선택합니다.
-
CodeQL 모델 편집기를 표시합니다. 기본적으로 편집기가 애플리케이션 모드에서 실행됩니다. 종속성 모드를 표시하려면 종속성으로 모델링을 클릭합니다. 프레임워크 또는 라이브러리의 공용 API를 표시하도록 화면이 변경됩니다.
-
패키지를 확장하고 사용 가능한 메서드 목록을 보려면 클릭합니다.
-
메서드와 연결된 보기를 클릭하여 해당 정의를 표시합니다.
-
메서드를 모델링하는 방법을 결정한 경우 "모델 형식"을 정의합니다.
-
해당 행의 나머지 필드는 선택한 모델 유형에 사용할 수 있는 옵션으로 업데이트됩니다.
- "원본": 모델링할 "출력" 요소를 선택합니다.
- "싱크": 모델링할 "입력" 요소를 선택합니다.
- "흐름 요약": 모델링할 "입력" 및 "출력" 요소를 선택합니다.
-
모델에 대한 데이터 흐름의 "종류"를 정의합니다.
-
모델링을 마쳤으면 모두 저장 또는 저장을 클릭합니다(확장된 각 호출 목록의 오른쪽 아래에 표시됨). 편집기에서 모델링된 호출의 백분율이 업데이트됩니다.
모델은 .github/codeql/extensions/CODEQL-MODEL-PACK
작업 영역에 저장되며, 여기서 CODEQL-MODEL-PACK
은 선택한 CodeQL 데이터베이스의 이름입니다. 즉, CodeQL에서 분석한 리포지토리, 하이픈, 언어의 이름입니다. 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.
모델은 각 공용 메서드에 대해 하나씩 일련의 YAML 데이터 확장 프로그램 파일에 저장됩니다. 예시:
.github/codeql/extensions/sofa-jraft-java # the model pack directory
models
com.alipay.sofa.jraft.option.model.yml # models public methods in package
com.alipay.sofa.jraft.rhea.options.model.yml
편집기에서 모델링하는 각 패키지에 대해 별도의 모델 파일을 만듭니다.
여러 잠재적인 흐름을 사용하여 메서드 모델링
일부 메서드는 둘 이상의 데이터 흐름을 지원합니다. 메서드에 대한 모든 데이터 흐름을 모델링하는 것이 중요하며, 그렇지 않은 경우 메서드 사용과 관련된 모든 잠재적인 문제를 감지할 수 없습니다. 먼저 메서드에 대해 하나의 데이터 흐름을 모델링한 다음 메서드 행의 + 버튼을 사용하여 두 번째 데이터 흐름 모델을 지정합니다.
VS Code의 CodeQL 모델 팩 테스트
"실행 중인 쿼리: 익스텐션 팩 사용" 설정을 사용하여 VS Code에서 만든 CodeQL 모델 팩을 테스트할 수 있습니다. 자세한 내용은 "설정 사용자 지정"을(를) 참조하세요. 이 메서드는 데이터베이스와 변형 분석 리포지토리 모두에서 작동합니다.
-
작업 영역의
.github/codeql/extensions
디렉터리 내에 저장된 모델 팩을 사용하여 CodeQL 데이터베이스에서 쿼리를 실행하려면"codeQL.runningQueries.useExtensionPacks": "all",
로settings.json
파일을 업데이트합니다. -
모델 팩을 사용하지 않고 CodeQL 데이터베이스에서 쿼리를 실행하려면
"codeQL.runningQueries.useExtensionPacks": "none",
을 사용하여settings.json
파일을 업데이트합니다.
모델이 잘 작동하는 경우 두 실행의 결과에 차이가 표시됩니다. 결과에 차이가 없는 경우 알려진 버그를 도입하여 모델이 예상대로 작동하는지 확인해야 할 수 있습니다.