CodeQL 쿼리 실행 정보
github/codeql 리포지토리에는 많은 수의 예제 쿼리가 포함되어 있습니다. "쿼리" 보기를 통해 작업 영역의 기존 쿼리에 액세스할 수 있습니다.
필수 조건
코드베이스를 분석하려면 코드에서 추출된 CodeQL 데이터베이스에 대해 쿼리를 실행하므로 익스텐션에서 작업할 데이터베이스를 선택해야 합니다. 로컬(ZIP 보관 파일 또는 보관하지 않은 폴더에서), 공용 URL 또는 GitHub.com의 프로젝트 URL에서 데이터베이스를 선택할 수 있습니다. 자세한 내용은 "CodeQL 데이터베이스 관리"을(를) 참조하세요.
단일 쿼리 실행
-
사이드바에서 "쿼리" 보기를 엽니다.
-
선택한 데이터베이스에 대해 쿼리를 실행하려면 원하는 쿼리를 마우스로 가리킨 다음 로컬 쿼리 실행 아이콘을 클릭합니다.
CodeQL 익스텐션은 현재 데이터베이스에서 쿼리를 실행하고 애플리케이션의 오른쪽 하단에 진행률을 보고합니다. 결과가 준비되면 CodeQL "쿼리 결과" 보기에 표시됩니다.
쿼리를 실행하는 데 문제가 있는 경우 애플리케이션의 오른쪽 하단에 알림이 표시됩니다. 알림에는 오류 메시지 외에도 문제를 해결하는 방법에 대한 세부 정보가 포함됩니다.
디렉터리에서 모든 쿼리 실행
디렉터리의 모든 쿼리를 실행할 수 있습니다.
-
사이드바에서 "쿼리" 보기를 엽니다.
-
원하는 쿼리 디렉터리를 마우스로 가리킨 다음 로컬 쿼리 실행 아이콘을 클릭합니다.
쿼리 선택 실행
단일 명령으로 여러 쿼리를 실행할 수 있습니다.
-
파일 탐색기로 이동합니다.
-
쿼리가 포함된 여러 파일 또는 폴더를 선택합니다.
-
마우스 오른쪽 단추를 클릭하고 CodeQL: 선택한 파일에서 쿼리 실행을 선택합니다.
설정 없이 쿼리 실행
새 쿼리를 작업할 때 작업 영역에 .ql 파일을 저장하지 않고도 "빠른 쿼리" 탭을 열어 코드를 쉽게 실행하고 결과를 볼 수 있습니다. VS Code Command Palette에서 CodeQL: 빠른 쿼리를 선택한 다음 CodeQL: 선택한 데이터베이스에서 쿼리 실행을 사용하여 쿼리를 실행합니다.
"쿼리 기록" 보기의 현재 세션에서 실행한 모든 빠른 쿼리를 확인할 수 있습니다. 항목을 클릭하여 결과를 생성한 빠른 쿼리의 정확한 텍스트를 확인합니다. 자세한 내용은 “쿼리 기록 보기”를 참조하세요.
빠른 쿼리에 만족하는 경우 나중에 액세스할 수 있도록 CodeQL 팩에 저장해야 합니다. 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.
쿼리 또는 라이브러리의 특정 부분 실행
이는 쿼리 또는 라이브러리를 디버깅하고 잘못된 부분을 찾으려는 경우에 유용할 수 있습니다.
CodeQL: 선택한 데이터베이스에서 쿼리 실행을 사용하는 대신, 전체 쿼리(select 절 및 쿼리 조건자)를 실행하여 CodeQL: 빠른 평가를 통해 .ql 또는 .qll 파일의 특정 부분을 실행할 수 있습니다.
CodeQL: 빠른 평가는 전체 쿼리 대신 선택한 코드 조각을 평가하고 해당 선택 결과를 "결과" 보기에 표시합니다.
빠른 평가를 위한 가능한 대상은 다음과 같습니다.
예를 들어 다음 조각에서 빠른 평가를 위해 조건자 이름 foo 또는 s = "bar" 수식을 선택할 수 있습니다.
predicate foo(string s) { s = "bar" }
여러 데이터베이스에서 쿼리 실행
이는 여러 코드베이스에서 쿼리를 테스트하거나 여러 프로젝트에서 취약성을 찾으려는 경우에 유용할 수 있습니다.
-
쿼리(
.ql) 파일을 엽니다. -
CodeQL: 여러 데이터베이스에서 쿼리 실행을 마우스 오른쪽 단추로 클릭하고 선택합니다.
-
드롭다운 메뉴에서 쿼리를 실행하려는 데이터베이스를 선택합니다.
쿼리 기록 보기
현재 세션에서 실행하는 쿼리를 보려면 "쿼리 기록" 보기를 엽니다.
"쿼리 기록" 보기에는 쿼리가 실행된 날짜 및 시간, 쿼리 이름, 실행된 데이터베이스 및 쿼리를 실행하는 데 걸린 시간을 포함한 정보가 포함됩니다.
-
표시되는 정보를 사용자 지정하려면 항목을 마우스 오른쪽 단추로 클릭하고 이름 바꾸기를 선택합니다.
-
필요에 따라 언어 선택기를 사용하여 언어별로 보기를 필터링합니다. 자세한 내용은 "언어별 데이터베이스 및 쿼리 필터링"을 참조하세요.
-
항목을 클릭하여 해당 결과를 표시하고 두 번 클릭하여 편집기에서 쿼리 자체를 표시하거나 마우스 오른쪽 단추를 클릭하고 쿼리 보기를 선택합니다.
-
특정 항목에 대한 결과를 생성한 정확한 텍스트를 표시하려면 마우스 오른쪽 단추로 클릭하고 쿼리 텍스트 보기를 선택합니다. 쿼리 파일이 마지막으로 실행된 이후 수정되었을 수 있으므로 쿼리 보기와 다를 수 있습니다.
-
보기에서 쿼리를 제거하려면 제거하려는 모든 쿼리를 선택한 다음 마우스 오른쪽 단추를 클릭하고 삭제를 선택합니다.
쿼리 결과 해석
-
"쿼리 기록" 보기에서 쿼리를 클릭하여 결과를 "결과" 보기에 표시합니다.
참고: 쿼리에 따라 CSV, CodeQL CLI SARIF 출력 또는 DIL 형식과 같은 다른 보기를 선택할 수도 있습니다. 예를 들어 DIL 형식을 보려면 결과를 마우스 오른쪽 단추로 클릭하고 DIL 보기를 선택합니다. 사용 가능한 출력 보기는 쿼리의 형식 및 메타데이터에 따라 결정됩니다. 자세한 내용은 "CodeQL 쿼리"를 참조하십시오.
-
"결과" 보기의 드롭다운 메뉴를 사용하여 표시할 결과와 표시할 양식(예: 서식이 지정된 경고 메시지 또는 원시 결과 테이블)을 선택합니다.
-
특정 열의 항목을 기준으로 결과를 정렬하려면 열 머리글을 클릭합니다.
결과가 소스 코드 포인트에 연결되는 경우 해당 요소를 클릭하여 원본에 표시할 수 있습니다.
소스 코드에서 표준 코드 탐색 기능을 사용하려면 요소를 마우스 오른쪽 단추로 클릭하고 정의로 이동 또는 참조로 이동 명령을 사용할 수 있습니다. 그러면 활성 파일에서 CodeQL 쿼리가 실행되며, 몇 초 정도 소요될 수 있습니다. 이 쿼리는 모든 파일에 대해 한 번 실행되어야 하므로 동일한 파일의 추가 참조는 빠릅니다.
참고: 이전 데이터베이스를 사용하는 경우 정의로 이동 및 참조로 이동과 같은 코드 탐색 명령이 작동하지 않을 수 있습니다.
코드 탐색을 사용하려면 데이터베이스의 압축을 풀고 CodeQL CLI을(를) 사용하여 압축을 푼 데이터베이스에서 codeql database cleanup <database>를 실행합니다. 그런 다음 데이터베이스를 Visual Studio Code에 다시 추가합니다. 자세한 내용은 "데이터베이스 정리"을(를) 참조하세요.
쿼리 결과 비교
쿼리를 작성하거나 디버깅할 때 변경 내용이 결과에 미치는 영향을 확인하는 것이 유용합니다. 두 개의 결과 집합을 비교하여 변경된 내용을 정확하게 확인할 수 있습니다. 결과를 비교하려면 두 쿼리를 동일한 데이터베이스에서 실행해야 합니다.
-
"쿼리 기록" 보기에서 쿼리를 마우스 오른쪽 단추로 클릭하고 결과 비교를 선택합니다.
-
빠른 선택 메뉴에는 비교할 유효한 모든 쿼리가 표시됩니다. 쿼리를 선택합니다.
-
"비교" 보기는 두 쿼리 결과의 차이를 보여 줍니다.
문제 해결
특정 쿼리 실행의 로그를 보려면 "쿼리 기록" 보기에서 쿼리를 마우스 오른쪽 단추로 클릭하고 쿼리 로그 표시를 선택합니다. 로그 파일이 너무 커서 익스텐션이 VS Code에서 열리지 않는 경우 파일 탐색기에 파일이 표시되므로 외부 프로그램으로 열 수 있습니다.
쿼리 컴파일 및 실행에 대한 자세한 내용과 데이터베이스 업그레이드에 대한 자세한 내용은 CodeQL 쿼리 서버 로그를 확인합니다. 자세한 내용은 "로그 액세스"을(를) 참조하세요.
기본적으로 익스텐션은 각 작업 영역 세션 후에 로그를 삭제합니다. 이 동작을 재정의하려면 쿼리 서버 로그에 대한 사용자 지정 디렉터리를 지정하면 됩니다. 자세한 내용은 "설정 사용자 지정"을(를) 참조하세요.
CodeQL: 쿼리 서버 다시 시작 명령을 사용하여 쿼리 서버를 다시 시작할 수 있습니다. 그러면 CodeQL 세션 기록에 영향을 주지 않고 서버가 다시 시작됩니다. 익스텐션에서 사용 중인 파일을 외부로 변경하는 경우 쿼리 서버를 다시 시작해야 할 가능성이 높습니다. 예를 들어 VS Code에 열려 있는 CodeQL 데이터베이스를 다시 생성합니다. 로그의 문제 외에도 코드 강조 표시 오류, 잘못된 결과 합계 또는 쿼리가 실행 중인 중복 알림이 표시될 수 있습니다.
다음 단계
필요에 따라 익스텐션을 사용하여 사용자 지정 쿼리를 만들 수 있습니다. 자세한 내용은 "사용자 지정 쿼리 만들기"을(를) 참조하세요.
많은 CodeQL 데이터베이스에서 대규모 분석을 실행하는 방법에 대한 자세한 내용은 "다중 리포지토리 변형 분석을 사용하여 대규모 CodeQL 쿼리 실행" 섹션을 참조하세요.