{"meta":{"title":"CodeQL 팩을 사용하여 분석 사용자 지정","intro":"CodeQL 팩을 사용하여 다른 사람이 유지 관리하는 CodeQL 쿼리를 실행하거나, 당신이 개발한 CodeQL 쿼리를 공유할 수 있습니다.","product":"보안 및 코드 품질","breadcrumbs":[{"href":"/ko/code-security","title":"보안 및 코드 품질"},{"href":"/ko/code-security/tutorials","title":"Tutorials"},{"href":"/ko/code-security/tutorials/customize-code-scanning","title":"코드 검색 사용자 지정"},{"href":"/ko/code-security/tutorials/customize-code-scanning/customizing-analysis-with-codeql-packs","title":"분석 사용자 지정"}],"documentType":"article"},"body":"# CodeQL 팩을 사용하여 분석 사용자 지정\n\nCodeQL 팩을 사용하여 다른 사람이 유지 관리하는 CodeQL 쿼리를 실행하거나, 당신이 개발한 CodeQL 쿼리를 공유할 수 있습니다.\n\n다른 사용자가 만든 팩을 다운로드하고 코드베이스에서 실행하여 CodeQL 분석을 사용자 지정할 수 있습니다. 자세한 내용은 [CodeQL 쿼리 팩](/ko/code-security/concepts/code-scanning/codeql/codeql-query-packs)을(를) 참조하세요.\n\n## CodeQL 쿼리 팩 다운로드 및 사용\n\nCodeQL 쿼리 팩을 사용하여 데이터베이스를 분석하려면 GitHub Container registry에서 필요한 패키지를 다운로드해야 합니다. 이 작업은 `--download` 명령에서 `codeql database analyze` 플래그를 사용하거나 `codeql pack download`를 실행하여 수행할 수 있습니다. 패키지를 공개적으로 사용할 수 없는 경우 GitHub App 또는 personal access token을 사용하여 인증해야 합니다. 자세한 내용과 예제는 [CodeQL 분석 결과를 GitHub 업로드](/ko/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-results-to-github)을(를) 참조하세요.\n\n| Option                                                                             |                                                                                                                                                                                                              필수                                                                                                                                                                                                              | Usage                                                                                                                                                                                                   |\n| ---------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| <code><span style=\"white-space: nowrap;\">\\<scope/name\\@version:path></span></code> |                                                    <svg version=\"1.1\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" class=\"octicon octicon-check\" aria-label=\"Required\" role=\"img\"><path d=\"M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z\"></path></svg>                                                   | 쉼표로 구분된 목록을 사용하여 다운로드할 하나 이상의 CodeQL 쿼리 팩의 범위와 이름을 지정합니다. 필요에 따라 다운로드하고 압축을 풀기 위한 버전을 선택적으로 포함할 수 있습니다. 기본적으로 이 팩의 최신 버전이 다운로드됩니다. 필요에 따라 실행할 쿼리, 디렉터리 또는 쿼리 모음의 경로를 포함시킵니다. 경로가 없으면 이 팩의 기본 쿼리를 실행합니다. |\n| <code><span style=\"white-space: nowrap;\">--github-auth-stdin</span></code>         | <svg version=\"1.1\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" class=\"octicon octicon-x\" aria-label=\"x icon\" role=\"img\"><path d=\"M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z\"></path></svg> | 표준 입력을 통해 비밀 저장소로부터 GitHub App의 REST API를 사용하여 인증을 위해 생성한 personal access token 또는 GitHub을 CLI에 전달합니다. 명령이 이 토큰을 사용하여 설정된 `GITHUB_TOKEN` 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다.                         |\n\n> \\[!NOTE]\n> 사용할 특정 버전의 쿼리 팩을 지정하는 경우 지정한 버전이 너무 오래되어 최신 버전의 CodeQL을 효율적으로 사용할 수 없게 될 수 있습니다. 최적의 성능을 보장하려면 정확한 쿼리 팩 버전을 지정해야 하는 경우 사용 중인 CodeQL CLI를 업그레이드할 때마다 고정할 버전을 다시 평가해야 합니다.\n>\n> 팩 호환성에 대한 자세한 내용은 [CodeQL 쿼리 팩 참조](/ko/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility)을(를) 참조하세요.\n\n### 쿼리 팩 다운로드 및 사용의 기본 예\n\n이 예제에서는 `codeql database analyze` 명령을 실행하고 `--download` 옵션을 선택하여 다음을 수행합니다.\n\n1. 최신 버전의 `octo-org/security-queries` 팩을 다운로드합니다.\n2. 버전 1.0.1과 호환되는 `octo-org/optional-security-queries` 팩 버전(이 경우 버전 1.0.2)을 다운로드합니다. semver 호환성에 대한 자세한 내용은 [npm의 의미 체계 버전 범위 설명서](https://github.com/npm/node-semver#ranges)를 참조하세요.\n3. ```\n          `octo-org/security-queries`에서 모든 기본 쿼리를 실행합니다.\n   ```\n4. ```\n          `queries/csrf.ql`에서 `octo-org/optional-security-queries` 쿼리만 실행합니다.\n   ```\n\n```shell\n$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \\\n    octo-org/security-queries \\\n    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \\\n    --format=sarif-latest --output=/temp/example-repo-js.sarif\n\n> Download location: /Users/mona/.codeql/packages\n> Installed fresh octo-org/security-queries@1.0.0\n> Installed fresh octo-org/optional-security-queries@1.0.2\n> Running queries.\n> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.\n> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.\n> Starting evaluation of octo-org/security-queries/query1.ql.\n> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.\n> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.\n> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.\n> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.\n> Shutting down query evaluator.\n> Interpreting results.\n```\n\n### CodeQL 팩 직접 다운로드\n\nCodeQL 팩을 즉시 실행하지 않고 다운로드하려면 `codeql pack download` 명령을 사용합니다. 이 방법은 인터넷에 액세스하지 않고 CodeQL 쿼리를 실행할 때 유용합니다. CodeQL 분석을 실행하는 경우 이전 예제와 동일한 방식으로 팩, 버전 및 경로를 지정할 수 있습니다.\n\n```shell\necho $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...\n```\n\n### 여러 CodeQL 컨테이너 레지스트리에서 GitHub 팩 다운로드\n\nCodeQL 팩이 여러 컨테이너 레지스트리에 있는 경우 CodeQL CLI에 각 팩을 찾을 위치를 지시해야 합니다. 자세한 내용은 [코드 검색을 위한 워크플로 구성 옵션](/ko/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server)을(를) 참조하세요.\n\n## CodeQL 팩에서 실행할 쿼리 지정\n\n쿼리 지정자는 `codeql database analyze` 및 쿼리 집합에서 작동하는 기타 명령에서 사용됩니다.\n쿼리 지정자의 전체 형식은 `scope/name@range:path`입니다. 여기에서:\n\n* `scope/name`는 CodeQL 패키지의 정규화된 이름입니다.\n* `range`는 [semver 범위](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)입니다.\n* `path`는 단일 쿼리, 쿼리가 포함된 디렉터리 또는 쿼리 도구 모음 파일에 대한 파일 시스템 경로입니다.\n\n  ```\n          `scope/name`(을)를 지정하면 `range` 및 `path`(은)는 선택 사항입니다. \n          `range`을(를) 생략하면 지정된 팩의 최신 버전이 사용됩니다. \n          `path`(을)를 생략하면 지정된 팩의 기본 쿼리 도구 모음이 사용됩니다.\n\n          `path`는 `.ql` 쿼리 파일, 하나 이상의 쿼리가 포함된 디렉터리 또는 `.qls` 쿼리 도구 모음 파일 중 하나가 됩니다. 팩 이름을 생략하면 현재 프로세스의 작업 디렉터리를 기준으로 해석되는 `path`(을)를 제공해야 합니다. Glob 패턴은 지원되지 않습니다.\n\n          `scope/name`과 `path`를 모두 지정하면 `path`는 절대값이 될 수 없습니다. CodeQL 팩의 루트를 기준으로 고려됩니다.\n  ```\n\n### 쿼리 지정자 예\n\n* `codeql/python-queries` - `codeql/python-queries` 팩 최신 버전의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.\n\n* `codeql/python-queries@1.2.3` - `1.2.3` 팩 버전 `codeql/python-queries`의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다.\n\n* `codeql/python-queries@~1.2.3` - `codeql/python-queries` 팩의 최신 버전 중 `1.2.3` 이상의 버전이면서 `1.3.0` 미만인 기본 쿼리 세트에 있는 모든 쿼리입니다.\n\n* `codeql/python-queries:Functions` - `Functions` 팩 최신 버전에 있는 `codeql/python-queries` 디렉터리의 모든 쿼리입니다.\n\n* `codeql/python-queries@1.2.3:Functions` - `Functions` 팩 버전 1.2.3의 `codeql/python-queries` 디렉터리에 있는 모든 쿼리입니다.\n\n* `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` - `codeql-suites/python-code-scanning.qls` 팩 버전 1.2.3의 `codeql/python-queries` 디렉터리에 있는 모든 쿼리입니다.\n\n* `suites/my-suite.qls` - 현재 작업 디렉터리를 기준으로 하는 `suites/my-suite.qls` 파일의 모든 쿼리입니다.\n\n> \\[!TIP]\n> 표준 CodeQL 쿼리 팩의 기본 쿼리 도구 모음은 `codeql-suites/<lang>-code-scanning.qls`입니다. 다른 몇 가지 유용한 쿼리 도구 모음은 각 팩의 `codeql-suites` 디렉터리에서도 찾을 수 있습니다. 예를 들어 `codeql/cpp-queries` 팩에는 다음 쿼리 도구 모음이 포함됩니다.\n>\n> *\n\n```\n          `cpp-code-scanning.qls` - C++용 표준 코드 검사 쿼리입니다. 이 팩의 기본 쿼리 도구 모음입니다.\n```\n\n> *\n\n```\n          `cpp-security-extended.qls` - 기본 C++ 제품군의 쿼리 및 낮은 심각도의 쿼리, 그리고 정밀도 쿼리입니다.\n```\n\n> *\n\n```\n          `cpp-security-and-quality.qls` - `cpp-security-extended.qls`의 쿼리와 유지 관리 기능 및 안정성 쿼리입니다.\n```\n\n>\n\n```\n          [CodeQL 리포지토리](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites)에서 이러한 쿼리 도구 모음의 원본을 볼 수 있습니다. 다른 언어의 쿼리 도구 모음도 비슷합니다.\n```\n\n## 모델 팩을 사용하여 사용자 지정 종속성 호출 분석\n\ncode scanning 분석에 게시된 모델 팩을 `--model-packs` 옵션과 함께 사용할 수 있습니다. 다음은 그 예입니다.\n\n```shell\n$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \\\n  --model-packs my-repo/my-java-model-pack \\\n  --output=/temp/my-company.sarif codeql/java-queries\n```\n\n이 예에서 표준 쿼리 팩 `codeql/java-queries`의 관련 쿼리는 모델 팩 `my-repo/my-java-model-pack`의 종속성 정보를 사용하여 해당 종속성을 호출하는 코드의 취약성을 확인합니다.\n\n여러 번 게시된 모델 팩을 분석에서 지정할 수 있습니다.\n\n자체 모델 팩 작성에 대한 자세한 내용은 [CodeQL 팩 만들기 및 작업](/ko/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack)을(를) 참조하세요.\n\n### 게시된 팩에 대한 정보\n\n팩이 분석에 사용하기 위해 게시되면 `codeql pack create` 또는 `codeql pack publish` 명령은 콘텐츠가 완료되었는지 확인하고 콘텐츠의 일부를 추가합니다.\n\n* 쿼리 팩의 경우, 해당 팩이 의존하는 각 라이브러리 팩의 복사본이 포함되며, 개발에 사용된 정확한 버전으로 제공됩니다. 쿼리 팩 사용자는 이러한 라이브러리 팩을 별도로 다운로드할 필요가 없습니다.\n\n* 쿼리 팩의 경우 각 쿼리를 미리 컴파일한 표현입니다. 각 분석에서 쿼리에 대한 QL 원본을 컴파일하는 것보다 실행하는 것이 더 빠릅니다.\n\n이 데이터의 대부분은 게시된 팩의 `.codeql` 디렉터리에 있지만 미리 컴파일된 쿼리는 각 쿼리의 `.qlx` 원본 옆에 `.ql` 접미사가 있는 파일에 있습니다. 게시된 팩의 쿼리를 사용하여 데이터베이스를 분석할 때 CodeQL은 `.ql` 원본 대신 이 파일을 로드합니다.\n*게시된* 팩의 콘텐츠를 수정해야 하는 경우 `.qlx` 파일의 수정이 적용되지 않게 할 수 있으므로 `.ql` 파일을 모두 제거해야 합니다."}