CodeQL 모델 편집기 사용

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 모델 편집기 표시

1. VS Code에서 CodeQL 작업 영역을 엽니다. 예를 들면 vscode-codeql-starter 작업 영역을 엽니다. 시작 작업 영역을 사용하는 경우 main의 ql 하위 모듈을 업데이트하여 모델 편집기용 데이터를 수집하는 데 사용되는 쿼리가 있는지 확인합니다.

2. Visual Studio Code에서 왼쪽 사이드바의 QL을 클릭하여 GitHub Copilot 익스텐션을 표시합니다.

3. "데이터베이스" 보기에서 모델링하려는 CodeQL 데이터베이스를 선택합니다.

4. CodeQL "메서드 모델링" 보기에서 모델링 시작을 클릭하여 모델 편집기를 표시합니다. 또는 VS Code Command Palette을(를) 사용하여 CodeQL: 모델 편집기 열기(베타) 명령을 실행합니다.

5. CodeQL 모델 편집기는 코드에서 API를 식별하기 위해 일련의 원격 분석 쿼리를 실행하며 편집기는 새 탭에 표시됩니다.

6. 원격 분석 쿼리가 완료되면 식별된 API가 편집기에 표시됩니다.

코드베이스가 외부 API에 대해 호출하는 모델링

이 방법은 일반적으로 CodeQL 결과의 정밀도를 향상하려는 특정 코드베이스를 볼 때 사용합니다. 이 기능은 코드베이스가 CodeQL에서 지원하지 않는 프레임워크 또는 라이브러리를 사용하고 프레임워크 또는 라이브러리의 소스 코드가 분석에 포함되지 않은 경우에 유용합니다.

이 섹션에서는 "sofa-jraft"라는 오픈 소스 Java 프로젝트를 예로 사용합니다. 다른 컴파일된 언어로 작성된 외부 API에 대한 호출을 모델링하는 환경도 비슷합니다.

1. Visual Studio Code에서 CodeQL 적용 범위를 개선할 CodeQL 데이터베이스를 선택합니다.

2. CodeQL 모델 편집기를 표시합니다. 기본적으로 편집기는 애플리케이션 모드에서 실행되므로 선택한 코드베이스에서 사용하는 외부 API 목록이 표시됩니다.

   

3. 외부 API를 확장하고 코드베이스에서 외부 의존 관계로의 호출 목록을 보려면 클릭합니다.

   

4. API 호출 또는 메서드와 연결된 보기를 클릭하여 코드베이스에서 사용되는 위치를 표시합니다.

5. 코드베이스에서 API로의 첫 번째 호출이 포함된 파일이 열리고 CodeQL "메서드 사용량" 보기가 VS Code에 표시됩니다(여기서 "문제" 및 "터미널" 보기는 일반적으로 표시됨). CodeQL "메서드 사용량" 보기는 코드에서 API로의 모든 호출 목록을 메서드별로 그룹화합니다. 각 사용을 통해 클릭하여 메서드 사용을 모델링하는 방법을 결정할 수 있습니다.

6. 메서드 사용을 모델링하는 방법을 결정한 경우 다른 모델 유형을 선택할 수 있습니다. CodeQL 익스텐션의 CodeQL "메서드 모델링" 보기에서 "모델 유형" 아래의 드롭다운을 클릭합니다. 이 변경 내용은 기본 모델 편집기에서 자동으로 반영됩니다.

7. 해당 행의 나머지 필드는 선택한 모델 유형에 사용할 수 있는 옵션으로 업데이트됩니다.

   • "원본": 모델링할 "출력" 요소를 선택합니다.
   • "싱크": 모델링할 "입력" 요소를 선택합니다.
   • "흐름 요약": 모델링할 "입력" 및 "출력" 요소를 선택합니다.

8. 모델에 대한 데이터 흐름의 "종류"를 정의합니다.

9. 모델링을 마쳤으면 기본 모델 편집기를 표시하고 모두 저장 또는 저장을 클릭합니다(확장된 각 메서드 목록의 오른쪽 아래에 표시됨). 편집기에서 모델링된 메서드의 백분율이 업데이트됩니다.

모델은 .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에 대한 호출을 모델링하는 환경도 비슷합니다.

1. 모델링하려는 CodeQL 데이터베이스를 선택합니다.

2. CodeQL 모델 편집기를 표시합니다. 기본적으로 편집기가 애플리케이션 모드에서 실행됩니다. 종속성 모드를 표시하려면 종속성으로 모델링을 클릭합니다. 프레임워크 또는 라이브러리의 공용 API를 표시하도록 화면이 변경됩니다.

   

3. 패키지를 확장하고 사용 가능한 메서드 목록을 보려면 클릭합니다.

4. 메서드와 연결된 보기를 클릭하여 해당 정의를 표시합니다.

   

5. 메서드를 모델링하는 방법을 결정한 경우 "모델 형식"을 정의합니다.

6. 해당 행의 나머지 필드는 선택한 모델 유형에 사용할 수 있는 옵션으로 업데이트됩니다.

   • "원본": 모델링할 "출력" 요소를 선택합니다.
   • "싱크": 모델링할 "입력" 요소를 선택합니다.
   • "흐름 요약": 모델링할 "입력" 및 "출력" 요소를 선택합니다.

7. 모델에 대한 데이터 흐름의 "종류"를 정의합니다.

8. 모델링을 마쳤으면 모두 저장 또는 저장을 클릭합니다(확장된 각 호출 목록의 오른쪽 아래에 표시됨). 편집기에서 모델링된 호출의 백분율이 업데이트됩니다.

모델은 .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 파일을 업데이트합니다.

모델이 잘 작동하는 경우 두 실행의 결과에 차이가 표시됩니다. 결과에 차이가 없는 경우 알려진 버그를 도입하여 모델이 예상대로 작동하는지 확인해야 할 수 있습니다.

추가 참고 자료

• 기본 설정 구성 편집
• 코드 검색을 위한 고급 설정 사용자 지정 CodeQL 팩을 사용하여 분석 사용자 지정.