참고: 이 문서는 2023년 1월에 CodeQL 설명서 웹 사이트에서 마이그레이션되었습니다.
사용자 정의 쿼리 및 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 패키지 관리 기능은 현재 베타 릴리스 상태로 이용 가능하며 변경될 수 있습니다. 베타 릴리스 중에 CodeQL 팩은 GitHub 패키지 (Container registry)을(를) 사용하여만 사용할 수 있습니다. 이 베타 기능을 사용하려면 다음에서 https://github.com/github/codeql-action/releasesCodeQL CLI 번들의 최신 버전을 설치합니다.
다른 사용자와 공유하려는 의도로 사용자 고유의 쿼리를 작성할 때 사용자 지정 CodeQL 팩에 저장해야 합니다. CodeQL 팩으로 팩을 GitHub Packages에 게시할 수 있습니다. GitHub Container registry. 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.
CodeQL 팩은 CodeQL 분석에 사용되는 파일을 구성하고 쿼리, 라이브러리 파일, 쿼리 도구 모음 및 중요한 메타데이터를 저장할 수 있습니다. 루트 디렉터리에는 qlpack.yml 이름이 지정된 파일이 포함되어야 합니다. 사용자 지정 쿼리는 CodeQL 팩 루트 또는 해당 하위 디렉터리에 저장되어야 합니다.
각 CodeQL 팩에 대해 qlpack.yml 파일에는 CodeQL CLI에게 쿼리를 컴파일하는 방법, 팩이 의존하는 다른 CodeQL 팩 및 라이브러리, 쿼리 도구 모음 정의를 찾을 수 있는 위치를 알려주는 정보가 포함되어 있습니다. 이 파일에 포함할 항목에 대한 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.
CodeQL 리포지토리에 기여
다른 CodeQL 사용자와 쿼리를 공유하려면 CodeQL 리포지토리에서 끌어오기 요청을 열 수 있습니다. 자세한 내용은 "CodeQL에 기여"를 참조하세요.