{"meta":{"title":"사용자 지정 CodeQL 쿼리","intro":"사용자 지정 쿼리는 CodeQL의 기본 제공 보안 분석을 확장하여 취약성을 감지하고 코드베이스와 관련된 코딩 표준을 적용합니다.","product":"보안 및 코드 품질","breadcrumbs":[{"href":"/ko/code-security","title":"보안 및 코드 품질"},{"href":"/ko/code-security/concepts","title":"Concepts"},{"href":"/ko/code-security/concepts/code-scanning","title":"코드 검사"},{"href":"/ko/code-security/concepts/code-scanning/codeql","title":"CodeQL"},{"href":"/ko/code-security/concepts/code-scanning/codeql/custom-codeql-queries","title":"사용자 지정 쿼리"}],"documentType":"article"},"body":"# 사용자 지정 CodeQL 쿼리\n\n사용자 지정 쿼리는 CodeQL의 기본 제공 보안 분석을 확장하여 취약성을 감지하고 코드베이스와 관련된 코딩 표준을 적용합니다.\n\n## 사용자 지정 CodeQL 쿼리란?\n\n사용자 지정 쿼리는 CodeQL의 기본 제공 보안 분석을 확장하여 코드베이스와 관련된 취약성, 코딩 표준 및 패턴을 검색합니다.\n\n> \\[!NOTE]\n> 쿼리는 엄격한 [메타데이터 요구 사항](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#including-query-metadata)으로 `database analyze`와(과) 실행됩니다. 다음 배관 수준 하위 명령을 사용하여 쿼리를 실행할 수도 있습니다.\n>\n> * [데이터베이스 실행 쿼리](/ko/code-security/codeql-cli/codeql-cli-manual/database-run-queries)- 해석되지 않은 결과를 [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file)라는 중간 이진 형식으로 출력합니다.\n> * [쿼리 실행](/ko/code-security/codeql-cli/codeql-cli-manual/query-run)- BQRS 파일을 출력하거나 결과 테이블을 명령줄에 직접 출력합니다. 명령줄에서 직접 결과를 보는 것은 CLI를 사용하여 반복 쿼리를 개발하는 데 유용할 수 있습니다.\n>\n> 이러한 명령으로 실행되는 쿼리에는 동일한 메타데이터 요구 사항이 없습니다. 그러나 사람이 읽을 수 있는 데이터를 저장하려면 [bqrs 디코딩](/ko/code-security/codeql-cli/codeql-cli-manual/bqrs-decode) 배관 하위 명령을 사용하여 각 BQRS 결과 파일을 처리해야 합니다. 따라서 대부분의 사용 사례에서는 데이터베이스 분석을 사용하여 해석된 결과를 직접 생성하는 것이 가장 쉽습니다.\n\n## 사용자 지정 쿼리를 사용하는 경우\n\n사용자 지정 쿼리를 사용하여 다음을 수행합니다.\n\n* 애플리케이션의 아키텍처 또는 프레임워크와 관련된 취약성 검색\n* 조직별 코딩 표준 또는 모범 사례 적용\n* 표준 CodeQL 쿼리 팩으로 커버되지 않는 패턴 찾기\n* CodeQL 데이터베이스를 CodeQL CLI를 사용하여 `database analyze` 명령어로 분석하여 해석된 결과를 생성합니다.\n\n## 쿼리 구조\n\n사용자 지정 쿼리는 확장과 함께 저장되는 쿼리 파일로 `.ql` 작성됩니다. 이러한 파일에는 쿼리의 목적에 대한 정보를 제공하고 CodeQL CLI 결과를 처리하는 방법을 알려주는 중요한 메타데이터도 포함되어 있습니다. 필수 속성은 다음과 같습니다.\n\n* ```\n          **쿼리 식별자(`@id`)**: 소문자 또는 숫자로, `/` 또는 `-`로 구분됨.\n  ```\n* ```\n          **쿼리 유형(`@kind`)**: 다음 중 하나입니다.\n  ```\n  \\*\n  `problem` - 간단한 경고\n  \\*\n  `path-problem` - 코드 위치 시퀀스를 사용하여 경고\n  \\*\n  `diagnostic` - 추출기 문제 해결\n  \\*\n  `metric` - 요약 메트릭(필요 `@tags summary`)\n\n> \\[!NOTE]\n> 쿼리를 다른 애플리케이션과 함께 사용하려는 경우 메타데이터 요구 사항이 달라질 수 있습니다. 자세한 내용은 [CodeQL 쿼리용 메타데이터](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries)를 참조하세요.\n\n쿼리 메타데이터에 대한 자세한 내용은 [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)에 대한 메타데이터를 참조하세요.\n\n## 쿼리 설명서\n\n쿼리 설명서는 사용자가 쿼리에서 검색하는 내용과 식별된 문제를 해결하는 방법을 이해하는 데 도움이 됩니다. 사용자 지정 쿼리에 대한 설명서를 다음 두 가지 형식으로 포함할 수 있습니다.\n\n* ```\n          **Markdown 파일**: 쿼리와 함께 저장되고 SARIF 파일에 포함할 수 있으며 code scanning UI에 표시될 수 있습니다.\n  ```\n* ```\n          **\n          `.qhelp` 파일**: 표준 CodeQL 쿼리와 일관되게 유지되지만, code scanning과(와) 함께 사용하기 위해 마크다운으로 변환되어야 합니다.\n  ```\n\n쿼리 도움말이 포함된 SARIF 파일이 GitHub에 업로드되면, 해당 쿼리로 생성된 모든 경고에 대해 code scanning UI에 문서가 표시됩니다.\n\n자세한 내용은 [쿼리 도움말 파일을 참조하세요](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files).\n\n## 사용자 지정 쿼리 공유\n\n사용자 고유의 쿼리 팩을 게시하여 커뮤니티와 사용자 지정 쿼리를 공유할 수 있습니다.\n[CodeQL 팩 게시 및 사용](/ko/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs)을(를) 참조하세요.\n\n## 추가 읽기\n\n* ```\n          [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)\n  ```\n* ```\n          [CodeQL 쿼리](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)\n  ```"}