CodeQL 쿼리 실행

CodeQL 쿼리 실행 정보

github/codeql 리포지토리에는 많은 예제 쿼리가 포함되어 있습니다. "쿼리" 보기에서 작업 영역의 기존 쿼리에 액세스할 수 있습니다.

필수 조건

코드베이스를 분석하려면 코드에서 추출된 CodeQL 데이터베이스에 대해 쿼리를 실행하므로, 확장 프로그램에서 작업할 데이터베이스를 선택해야 합니다. 로컬(Zip 아카이브 또는 압축 해제된 폴더), 공개 URL 또는 GitHub.com의 프로젝트 URL에서 데이터베이스를 선택할 수 있습니다. 자세한 내용은 CodeQL 데이터베이스 관리을(를) 참조하세요.

단일 쿼리 실행

1. 사이드바에서 "쿼리" 보기를 엽니다.

2. 선택한 데이터베이스에 대해 쿼리를 실행하려면 원하는 쿼리에 마우스를 올린 다음 로컬 쿼리 실행 아이콘을 클릭합니다.

CodeQL 확장 프로그램은 현재 데이터베이스에서 쿼리를 실행하고 애플리케이션 오른쪽 아래에 진행 상황을 보고합니다. 결과가 준비되면 CodeQL "쿼리 결과" 보기에서 표시됩니다.

쿼리 실행에 문제가 있으면 애플리케이션 오른쪽 아래에 알림이 표시됩니다. 알림에는 오류 메시지 외에도 문제를 해결하는 방법에 대한 세부 정보가 포함됩니다.

디렉터리의 모든 쿼리 실행

디렉터리의 모든 쿼리를 실행할 수 있습니다.

1. 사이드바에서 "쿼리" 보기를 엽니다.

2. 원하는 쿼리 디렉터리에 마우스를 올린 다음 로컬 쿼리 실행 아이콘을 클릭합니다.

선택한 쿼리 실행

단일 명령으로 여러 쿼리를 실행할 수 있습니다.

1. 파일 탐색기로 이동합니다.

2. 쿼리가 포함된 여러 파일 또는 폴더를 선택합니다.

3. 마우스 오른쪽 버튼을 클릭하고 CodeQL: 선택한 파일에서 쿼리 실행을 선택합니다.

설정 없이 쿼리 실행

새 쿼리를 작업할 때, 작업 영역에 .ql 파일을 저장하지 않아도 코드를 쉽게 실행하고 결과를 볼 수 있도록 "빠른 쿼리" 탭을 열 수 있습니다. VS Code Command Palette에서 CodeQL: 빠른 쿼리를 선택한 다음, 쿼리를 실행하려면 CodeQL: 선택한 데이터베이스에서 쿼리 실행을 사용합니다.

현재 세션에서 실행한 모든 빠른 쿼리는 "쿼리 기록" 보기에서 확인할 수 있습니다. 항목을 클릭하면 결과를 생성한 빠른 쿼리의 정확한 텍스트를 볼 수 있습니다. 자세한 내용은 쿼리 기록 보기를 참조하세요.

빠른 쿼리가 만족스러우면, 나중에 액세스할 수 있도록 CodeQL 팩에 저장해야 합니다. 자세한 내용은 CodeQL 팩을 사용하여 분석 사용자 지정을(를) 참조하세요.

쿼리 또는 라이브러리의 특정 부분 실행

쿼리 또는 라이브러리를 디버깅하면서 잘못된 부분을 찾으려는 경우에 유용할 수 있습니다.

CodeQL: 선택한 데이터베이스에서 쿼리 실행을 사용하여 전체 쿼리(select 절과 모든 쿼리 조건자)를 실행하는 대신, CodeQL: 빠른 평가를 사용하여 .ql 또는 .qll 파일의 특정 부분을 실행할 수 있습니다.

          **CodeQL: 빠른 평가**는 전체 쿼리 대신 선택한 코드 스니펫을 평가하고, 해당 선택의 결과를 "결과" 보기에서 표시합니다.

빠른 평가의 가능한 대상은 다음과 같습니다:

• 해당 엔터티를 평가하기 위해 CodeQL 엔터티(예: 클래스 또는 조건자)의 이름을 선택합니다.

• 해당 수식 또는 표현식을 평가하기 위해 자유 변수가 있는 수식 또는 표현식을 선택합니다.

예를 들어 다음 스니펫에서 빠른 평가를 위해 조건자 이름 foo 또는 수식 s = "bar"을(를) 선택할 수 있습니다:

predicate foo(string s) { s = "bar" }

여러 데이터베이스에서 쿼리 실행

여러 코드베이스에서 쿼리를 테스트하거나, 여러 프로젝트에서 취약성을 찾으려는 경우에 유용할 수 있습니다.

1. 쿼리(.ql) 파일을 엽니다.

2. 마우스 오른쪽 버튼을 클릭하고 CodeQL: 여러 데이터베이스에서 쿼리 실행을 선택합니다.

3. 드롭다운 메뉴에서 쿼리를 실행할 데이터베이스를 선택합니다.

쿼리 기록 보기

현재 세션에서 실행한 쿼리를 보려면 "쿼리 기록" 보기를 엽니다.

"쿼리 기록" 보기에는 쿼리가 실행된 날짜와 시간, 쿼리 이름, 실행된 데이터베이스, 쿼리 실행에 걸린 시간 등의 정보가 포함됩니다.

• 표시되는 정보를 사용자 지정하려면 항목을 마우스 오른쪽 버튼으로 클릭하고 이름 바꾸기를 선택합니다.

• 선택적으로 언어 선택기를 사용하여 언어별로 보기를 필터링할 수 있습니다. 자세한 내용은 언어별 데이터베이스 및 쿼리 필터링을 참조하세요.

• 항목을 클릭하여 해당 결과를 표시하고, 더블 클릭하여 편집기에서 쿼리 자체를 표시합니다(또는 마우스 오른쪽 버튼을 클릭하고 쿼리 보기를 선택합니다).

• 특정 항목의 결과를 생성한 정확한 텍스트를 표시하려면 마우스 오른쪽 버튼을 클릭하고 쿼리 텍스트 보기를 선택합니다. 이는 마지막으로 실행한 이후 쿼리 파일이 수정되었을 수 있으므로 쿼리 보기와 다를 수 있습니다.

• 보기에서 쿼리를 제거하려면 제거할 쿼리를 모두 선택한 다음 마우스 오른쪽 버튼을 클릭하고 삭제를 선택합니다.

쿼리 결과 해석

1. "쿼리 기록" 보기에서 쿼리를 클릭하여 "결과" 보기에서 해당 결과를 표시합니다.

   참고 항목

   쿼리에 따라 CSV, CodeQL CLI SARIF 출력, 또는 DIL 형식과 같은 다른 보기를 선택할 수도 있습니다. 예를 들어 DIL 형식을 보려면 결과를 마우스 오른쪽 버튼으로 클릭하고 DIL 보기를 선택합니다. 사용 가능한 출력 보기는 쿼리의 형식과 메타데이터에 의해 결정됩니다. 자세한 내용은 CodeQL 쿼리를 참조하세요.

2. "결과" 보기의 드롭다운 메뉴를 사용하여 표시할 결과와 표시 형식을 선택할 수 있습니다(예: 형식화된 경고 메시지 또는 원시 결과의 테이블).

3. 특정 열의 항목을 기준으로 결과를 정렬하려면 열 헤더를 클릭합니다.

결과가 소스 코드 요소에 연결되어 있으면 클릭하여 소스에서 표시할 수 있습니다.

소스 코드에서 표준 코드 탐색 기능을 사용하려면 요소를 마우스 오른쪽 버튼으로 클릭하고 정의로 이동 또는 참조로 이동 명령을 사용합니다. 이는 활성 파일에 대해 CodeQL 쿼리를 실행하며, 몇 초가 걸릴 수 있습니다. 이 쿼리는 파일마다 한 번 실행되어야 하므로, 같은 파일에서 추가로 참조를 찾는 작업은 빠르게 수행됩니다.

쿼리 결과 비교

쿼리를 작성하거나 디버깅할 때 변경 사항이 결과에 어떤 영향을 주는지 확인하는 것이 유용합니다. 두 결과 집합을 비교하여 정확히 무엇이 바뀌었는지 확인할 수 있습니다. 결과를 비교하려면 두 쿼리를 동일한 데이터베이스에서 실행해야 합니다.

1. "쿼리 기록" 보기에서 쿼리를 마우스 오른쪽 버튼으로 클릭하고 결과 비교를 선택합니다.

2. 빠른 선택 메뉴에 비교할 수 있는 모든 유효한 쿼리가 표시됩니다. 쿼리를 선택합니다.

3. "비교" 보기에 두 쿼리 결과의 차이가 표시됩니다.

Troubleshooting

특정 쿼리 실행의 로그를 보려면 "쿼리 기록" 보기에서 쿼리를 마우스 오른쪽 버튼으로 클릭하고 쿼리 로그 표시를 선택합니다. 로그 파일이 너무 커서 확장 프로그램이 VS Code에서 열 수 없으면, 파일 탐색기에 표시되므로 외부 프로그램으로 열 수 있습니다.

쿼리 컴파일 및 실행에 대한 세부 정보와 데이터베이스 업그레이드 정보는 CodeQL 쿼리 서버 로그를 확인하세요. 자세한 내용은 로그 액세스을(를) 참조하세요.

기본적으로 확장 프로그램은 각 작업 영역 세션 후에 로그를 삭제합니다. 이 동작을 재정의하려면 쿼리 서버 로그를 위한 사용자 지정 디렉터리를 지정할 수 있습니다. 자세한 내용은 설정 사용자 지정을(를) 참조하세요.

쿼리 서버를 다시 시작하려면 CodeQL: 쿼리 서버 재시작 명령을 사용할 수 있습니다. 이렇게 하면 CodeQL 세션 기록에는 영향을 주지 않고 서버만 다시 시작됩니다. 확장 프로그램이 사용하는 파일을 외부에서 변경하는 경우 쿼리 서버를 다시 시작해야 하는 경우가 가장 많습니다. 예: VS Code에서 열려 있는 CodeQL 데이터베이스를 다시 생성하는 경우. 로그의 문제 외에도 다음이 표시될 수 있습니다. 코드 강조 표시 오류, 잘못된 결과 합계, 또는 쿼리가 실행 중이라는 중복 알림.

다음 단계

선택적으로 확장 프로그램을 사용하여 사용자 지정 쿼리를 만들 수도 있습니다. 자세한 내용은 사용자 지정 쿼리 만들기을(를) 참조하세요.

여러 CodeQL 데이터베이스에 걸쳐 대규모로 분석을 실행하는 방법에 대한 정보는 다중 리포지토리 변형 분석을 이용한 대규모 CodeQL 쿼리 실행을(를) 참조하세요.