# 사용자 지정 CodeQL 쿼리

사용자 지정 쿼리는 CodeQL의 기본 제공 보안 분석을 확장하여 취약성을 감지하고 코드베이스와 관련된 코딩 표준을 적용합니다.

## 사용자 지정 CodeQL 쿼리란?

사용자 지정 쿼리는 CodeQL의 기본 제공 보안 분석을 확장하여 코드베이스와 관련된 취약성, 코딩 표준 및 패턴을 검색합니다.

> \[!NOTE]
> 쿼리는 엄격한 [메타데이터 요구 사항](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#including-query-metadata)으로 `database analyze`와(과) 실행됩니다. 다음 배관 수준 하위 명령을 사용하여 쿼리를 실행할 수도 있습니다.
>
> * [데이터베이스 실행 쿼리](/ko/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-manual/database-run-queries)- 해석되지 않은 결과를 [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file)라는 중간 이진 형식으로 출력합니다.
> * [쿼리 실행](/ko/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-manual/query-run)- BQRS 파일을 출력하거나 결과 테이블을 명령줄에 직접 출력합니다. 명령줄에서 직접 결과를 보는 것은 CLI를 사용하여 반복 쿼리를 개발하는 데 유용할 수 있습니다.
>
> 이러한 명령으로 실행되는 쿼리에는 동일한 메타데이터 요구 사항이 없습니다. 그러나 사람이 읽을 수 있는 데이터를 저장하려면 [bqrs 디코딩](/ko/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-manual/bqrs-decode) 배관 하위 명령을 사용하여 각 BQRS 결과 파일을 처리해야 합니다. 따라서 대부분의 사용 사례에서는 데이터베이스 분석을 사용하여 해석된 결과를 직접 생성하는 것이 가장 쉽습니다.

## 사용자 지정 쿼리를 사용하는 경우

사용자 지정 쿼리를 사용하여 다음을 수행합니다.

* 애플리케이션의 아키텍처 또는 프레임워크와 관련된 취약성 검색
* 조직별 코딩 표준 또는 모범 사례 적용
* 표준 CodeQL 쿼리 팩으로 커버되지 않는 패턴 찾기
* CodeQL 데이터베이스를 CodeQL CLI를 사용하여 `database analyze` 명령어로 분석하여 해석된 결과를 생성합니다.

## 쿼리 구조

사용자 지정 쿼리는 확장과 함께 저장되는 쿼리 파일로 `.ql` 작성됩니다. 이러한 파일에는 쿼리의 목적에 대한 정보를 제공하고 CodeQL CLI 결과를 처리하는 방법을 알려주는 중요한 메타데이터도 포함되어 있습니다. 필수 속성은 다음과 같습니다.

* ```
          **쿼리 식별자(`@id`)**: 소문자 또는 숫자로, `/` 또는 `-`로 구분됨.
  ```
* ```
          **쿼리 유형(`@kind`)**: 다음 중 하나입니다.
  ```
  \*
  `problem` - 간단한 경고
  \*
  `path-problem` - 코드 위치 시퀀스를 사용하여 경고
  \*
  `diagnostic` - 추출기 문제 해결
  \*
  `metric` - 요약 메트릭(필요 `@tags summary`)

> \[!NOTE]
> 쿼리를 다른 애플리케이션과 함께 사용하려는 경우 메타데이터 요구 사항이 달라질 수 있습니다. 자세한 내용은 [CodeQL 쿼리용 메타데이터](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries)를 참조하세요.

쿼리 메타데이터에 대한 자세한 내용은 [CodeQL 쿼리](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) 및 [쿼리 메타데이터 스타일 가이드](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md)에 대한 메타데이터를 참조하세요.

## 쿼리 설명서

쿼리 설명서는 사용자가 쿼리에서 검색하는 내용과 식별된 문제를 해결하는 방법을 이해하는 데 도움이 됩니다. 사용자 지정 쿼리에 대한 설명서를 다음 두 가지 형식으로 포함할 수 있습니다.

* ```
          **Markdown 파일**: 쿼리와 함께 저장되고 SARIF 파일에 포함할 수 있으며 code scanning UI에 표시될 수 있습니다.
  ```
* ```
          **
          `.qhelp` 파일**: 표준 CodeQL 쿼리와 일관되게 유지되지만, code scanning과(와) 함께 사용하기 위해 마크다운으로 변환되어야 합니다.
  ```

쿼리 도움말이 포함된 SARIF 파일이 GitHub에 업로드되면, 해당 쿼리로 생성된 모든 경고에 대해 code scanning UI에 문서가 표시됩니다.

자세한 내용은 [쿼리 도움말 파일을 참조하세요](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files).

## 사용자 지정 쿼리 공유

사용자 고유의 쿼리 팩을 게시하여 커뮤니티와 사용자 지정 쿼리를 공유할 수 있습니다.
[CodeQL 팩 게시 및 사용](/ko/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs)을(를) 참조하세요.

## 추가 읽기

* ```
          [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)
  ```
* ```
          [CodeQL 쿼리](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)
  ```