CodeQL CLI에서 사용자 지정 쿼리 사용하기

고유한 CodeQL 쿼리를 작성하여 특정한 취약성 및 오류를 찾을 수 있습니다.

누가 이 기능을 사용할 수 있나요?

CodeQL은(는) 다음 리포지토리 유형에 사용할 수 있습니다.

GitHub.com의 퍼블릭 리포지토리, GitHub CodeQL 사용 약관 참조
GitHub Code Security를 사용하도록 설정된 GitHub Team의 조직 소유 리포지토리

이 문서의 내용

사용자 지정 쿼리 및 CodeQL CLI 알아보기

고유한 쿼리를 작성하여 CodeQL 분석을 사용자 지정함으로써 특정한 취약성 또는 오류를 강조 표시할 수 있습니다.

이 항목에서는 특히 데이터베이스 분석 명령과 함께 사용할 쿼리를 작성하여 해석된 결과를 생성하는 방법에 대해 설명합니다.

참고 항목

쿼리는 엄격한 메타데이터 요구 사항으로 database analyze와(과) 실행됩니다. 다음 배관 수준 하위 명령을 사용하여 쿼리를 실행할 수도 있습니다.

database run-queries- 해석되지 않은 결과를 BQRS라는 중간 이진 형식으로 출력합니다.
쿼리 실행- BQRS 파일을 출력하거나 결과 테이블을 명령줄에 직접 출력합니다. 명령줄에서 직접 결과를 보는 것은 CLI를 사용하여 반복 쿼리를 개발하는 데 유용할 수 있습니다.

이러한 명령으로 실행되는 쿼리에는 동일한 메타데이터 요구 사항이 없습니다. 그러나 사람이 읽을 수 있는 데이터를 저장하려면 bqrs 디코딩 배관 하위 명령을 사용하여 각 BQRS 결과 파일을 처리해야 합니다. 따라서 대부분의 사용 사례에서는 데이터베이스 분석을 사용하여 해석된 결과를 직접 생성하는 것이 가장 쉽습니다.

유효한 쿼리 작성하기

사용자 지정 분석을 실행하기 전에 유효한 쿼리를 작성하고 .ql 확장자로 된 파일에 저장해야 합니다. 쿼리를 작성하는 데 도움이 되는 광범위한 설명서를 참고하실 수 있습니다. 자세한 내용은 CodeQL 쿼리를 참조하세요.

쿼리 메타데이터 포함하기

쿼리 메타데이터는 각 쿼리 파일의 맨 위에 포함됩니다. 쿼리 메타데이터는 사용자에게 쿼리에 대한 정보를 제공하고 CodeQL CLI에 쿼리 결과를 처리하는 방법을 알려줍니다.

database analyze 명령을 사용하여 쿼리를 실행할 때 결과가 올바르게 해석되도록 하려면 다음 두 가지 속성을 포함해야 합니다.

쿼리 식별자(@id): 소문자 또는 숫자로 구성되고 / 또는 -에 의해 구분되는 단어 시퀀스로, 쿼리를 식별 및 분류합니다.
쿼리 유형(@kind): 쿼리를 간단한 경고(@kind problem), 코드 위치 시퀀스에 의해 문서화된 경고(@kind path-problem), 추출기 문제 해결용(@kind diagnostic) 또는 요약 메트릭(@kind metric 및 @tags summary)의 유형으로 구분합니다.

이러한 메타데이터 속성에 대한 자세한 내용은 CodeQL 쿼리에 대한 메타데이터 및 쿼리 메타데이터 스타일 가이드를 참조하세요.

참고 항목

쿼리를 다른 애플리케이션과 함께 사용하려는 경우 메타데이터터 요구 사항이 다를 수 있습니다. 자세한 내용은 CodeQL 쿼리에 대한 메타데이터를 참조하세요.

사용자 지정 QL 쿼리 패키징하기

다른 사용자와 공유하려는 의도로 사용자 고유의 쿼리를 작성할 때는 사용자 지정 CodeQL 팩에 저장해야 합니다. CodeQL 팩으로 팩을 GitHub Packages에 게시할 수 있습니다. GitHub Container registry. 자세한 내용은 CodeQL 팩을 사용하여 분석 사용자 지정을(를) 참조하세요.

CodeQL 팩은 CodeQL 분석에 사용되는 파일을 구성하고 쿼리, 라이브러리 파일, 쿼리 모음 및 중요한 메타데이터를 저장할 수 있습니다. 그 루트 디렉터리에는 파일 이름이 qlpack.yml(으)로 지정된 파일이 포함되어야 합니다. 사용자 지정 쿼리는 CodeQL 팩 루트 또는 그 하위 디렉터리에 저장되어야 합니다.

각 CodeQL 팩에 대해 qlpack.yml 파일에는 CodeQL CLI에 쿼리를 컴파일하는 방법, 팩이 의존하는 다른 CodeQL 팩 및 라이브러리, 쿼리 모음 정의를 찾을 수 있는 위치를 알려주는 정보가 포함되어 있습니다. 이 파일에 포함할 항목에 대한 자세한 내용은 CodeQL 팩을 사용하여 분석 사용자 지정을(를) 참조하세요.

SARIF 파일에 사용자 지정 CodeQL 쿼리에 대한 쿼리 도움말 포함하기

CodeQL CLI를 사용하여 제3자 CI/CD 시스템에서 코드 스캔 분석을 실행하는 경우, 분석 중에 생성된 SARIF 파일에 사용자 지정 쿼리에 대한 쿼리 도움말을 포함할 수 있습니다. SARIF 파일을 GitHub에 업로드하면 사용자 지정 쿼리에서 생성된 모든 경고에 대한 쿼리 도움말이 코드 스캔 UI에 표시됩니다.

CodeQL CLI v2.7.1 이상에서는 codeql database analyze 실행 시 --sarif-add-query-help 옵션을 제공하여 SARIF 파일에 Markdown 렌더링 된 쿼리 도움말을 포함할 수 있습니다.

사용자 지정 쿼리에 대한 쿼리 도움말을 Markdown 파일에 직접 작성하고 해당 쿼리와 함께 저장할 수 있습니다. 또는 표준 CodeQL 쿼리와의 일관성을 위해 쿼리 도움말을 .qhelp 형식으로 작성할 수 있습니다. .qhelp 파일에 작성된 쿼리 도움말은 SARIF 파일에 포함될 수 없으며 코드 스캔으로 처리할 수 없으므로 분석을 실행하기 전에 Markdown으로 변환해야 합니다. 자세한 내용은 쿼리 도움말 파일 및 쿼리 도움말 파일 테스트하기을(를) 참조하세요.

CodeQL 리포지토리에 기여하기

다른 CodeQL 사용자와 쿼리를 공유하려면 CodeQL 리포지토리에서 끌어오기 요청을 열 수 있습니다. 자세한 내용은 "CodeQL에 기여하기"를 참조하세요.

추가 참고 자료

CodeQL 쿼리