참고: 이 문서는 2023년 1월에 CodeQL 설명서 웹 사이트에서 마이그레이션되었습니다.
사용자 지정 쿼리 및 CodeQL CLI 정보
고유한 쿼리를 작성하여 특정 취약성 또는 오류를 강조 표시하여 CodeQL 분석을 사용자 지정할 수 있습니다.
이 항목에서는 특히 데이터베이스 분석 명령과 함께 사용할 쿼리를 작성하여 해석된 결과를 생성하는 방법에 대해 설명합니다.
참고: 를 사용하여 실행되는 database analyze 쿼리에는 엄격한 메타데이터 요구 사항이 있습니다. 다음 배관 수준 하위 명령을 사용하여 쿼리를 실행할 수도 있습니다.
- 데이터베이스 실행 쿼리 - 해석되지 않은 결과를 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 패키지 관리 기능은 현재 베타 릴리스로 사용할 수 있으며 변경될 수 있습니다. 베타 릴리스 중에는 Container registry인 GitHub 패키지만 CodeQL 팩을 사용할 수 있습니다. 이 베타 기능을 사용하려면 에서 https://github.com/github/codeql-action/releases최신 버전의 CodeQL 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에 기여를 참조하세요.