CodeQL 팩 정보
참고: 이 문서에서는 CodeQL CLI 2.17.6 번들에서 사용할 수 있는 기능을 GitHub Enterprise Server 3.14의 초기 릴리스에 포함되어 있습니다.
사이트 관리자가 CodeQL CLI 버전을 최신 릴리스로 업데이트한 경우 최신 기능에 대한 자세한 내용은 이 문서의 GitHub Enterprise Cloud 버전을 참조하세요.
CodeQL 팩은 CodeQL 쿼리 및 라이브러리를 만들고, 공유하고, 사용하고, 실행하는 데 사용됩니다. CodeQL 팩에는 쿼리, 라이브러리 파일, 쿼리 도구 모음 및 메타데이터가 포함됩니다. 다른 사용자가 만든 팩을 다운로드하고 코드베이스에서 실행하여 CodeQL 분석을 사용자 지정할 수 있습니다.
CodeQL 팩은 세 개 유형이 있습니다. 쿼리 팩, 라이브러리 팩, 그리고 모델 팩입니다.
-
쿼리 팩에는 CodeQL 데이터베이스에서 평가할 수 있는 미리 컴파일된 쿼리 집합이 포함되어 있습니다. 쿼리 팩은 실행되도록 설계되었습니다. 쿼리 팩이 게시되면 번들에 쿼리 원본 외에도 각 쿼리의 모든 전이적 종속성과 미리 컴파일된 표현이 포함됩니다. 이렇게 하면 팩에서 쿼리를 일관되고 효율적으로 실행할 수 있습니다.
-
라이브러리 팩은 쿼리 팩(또는 다른 라이브러리 팩)에서 사용하도록 설계되었으며 쿼리 자체를 포함하지 않습니다. 라이브러리는 별도로 컴파일되지 않습니다.
-
code scanning 분석을 확장하여 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식하는 데 모델 팩을 사용할 수 있습니다. 모델 팩은 현재 베타 버전이며 변경될 수 있습니다. 베타에서 모델 팩은 C#, Java/Kotlin, and Ruby 분석에 사용할 수 있습니다. 자체 모델 팩을 만드는 방법에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을 참조하세요.
지원되는 모든 언어에 대한 표준 CodeQL 팩이 Container registry에 게시됩니다. CodeQL CLI를 표준 방식으로 설치한 경우 CodeQL CLI 번들을 사용하여 핵심 쿼리 팩을 이미 다운로드하여 사용할 수 있습니다. 화면은 다음과 같습니다.
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries
CodeQL CLI를 사용하여 자체 CodeQL 팩을 만들고, 팩에 종속성을 추가하고, 종속성을 설치하거나 업데이트할 수도 있습니다. 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.
CodeQL CLI을 사용하여 만든 CodeQL 팩을 게시할 수 있습니다. CodeQL 팩 게시 및 다운로드에 대한 자세한 내용은 "CodeQL 팩 게시 및 사용"을 참조하세요.
CodeQL 쿼리 팩 다운로드 및 사용
CodeQL CLI 번들에는 GitHub 전문가, 보안 연구원 및 커뮤니티 기여자들이 유지 관리하는 쿼리가 포함되어 있습니다. 다른 조직에서 개발한 쿼리를 실행하려는 경우, CodeQL 쿼리 팩을 사용하면 쿼리를 효율적이고 안정적으로 다운로드하고 실행할 수 있으며, 모델 팩(베타)을 사용하면 code scanning 분석을 확장해 기본적으로 지원되지 않는 라이브러리 및 프레임워크를 인식할 수 있습니다. 쿼리 팩에 대한 자세한 내용은 "CodeQL을 사용하는 코드 검사 안내"을 참조하세요. 자체 모델 팩을 작성하는 방법에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을(를) 참조하세요.
CodeQL 쿼리 팩을 사용하여 데이터베이스를 분석하려면 GitHub Container registry에서 필요한 패키지를 다운로드해야 합니다. 이 작업은 codeql database analyze
명령에서 --download
플래그를 사용하거나 codeql pack download
를 실행하여 수행할 수 있습니다. 패키지를 공개적으로 사용할 수 없는 경우 GitHub App 또는 personal access token을 사용하여 인증해야 합니다. 자세한 내용과 예제는 "GitHub에 CodeQL 분석 결과 업로드"을(를) 참조하세요.
옵션 | 필수 | 사용 |
---|---|---|
<scope/name@version:path> | 쉼표로 구분된 목록을 사용하여 다운로드할 하나 이상의 CodeQL 쿼리 팩의 범위와 이름을 지정합니다. 필요에 따라 다운로드하고 압축을 풀 버전을 포함시킵니다. 기본적으로 이 팩의 최신 버전이 다운로드됩니다. 필요에 따라 실행할 쿼리, 디렉터리 또는 쿼리 모음의 경로를 포함시킵니다. 경로가 없으면 이 팩의 기본 쿼리를 실행합니다. | |
--github-auth-stdin | 표준 입력을 통해 비밀 저장소에서 GitHub의 REST API를 사용하여 인증을 위해 만든 GitHub App 또는 personal access token을(를) CLI에 전달합니다. 명령이 이 토큰을 사용하여 설정된 GITHUB_TOKEN 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다. |
참고: 사용할 특정 버전의 쿼리 팩을 지정하는 경우 지정한 버전이 너무 오래되어 최신 버전의 CodeQL을 효율적으로 사용할 수 없게 될 수 있습니다. 최적의 성능을 보장하려면 정확한 쿼리 팩 버전을 지정해야 하는 경우 사용 중인 CodeQL CLI를 업그레이드할 때마다 고정할 버전을 다시 평가해야 합니다.
팩 호환성에 대한 자세한 정보는 "CodeQL 팩 게시 및 사용"을(를) 참조하세요.
쿼리 팩 다운로드 및 사용의 기본 예
이 예제에서는 codeql database analyze
명령을 실행하고 --download
옵션을 선택하여 다음을 수행합니다.
- 최신 버전의
octo-org/security-queries
팩을 다운로드합니다. - 버전 1.0.1과 _호환_되는
octo-org/optional-security-queries
팩 버전(이 예제에서는 버전 1.0.2)을 다운로드합니다. semver 호환성에 대한 자세한 내용은 npm의 의미 체계 버전 범위 설명서를 참조하세요. octo-org/security-queries
에서 모든 기본 쿼리를 실행합니다.octo-org/optional-security-queries
에서queries/csrf.ql
쿼리만 실행합니다.
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
octo-org/security-queries \
octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
--format=sarif-latest --output=/temp/example-repo-js.sarif
> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.
CodeQL 팩 직접 다운로드
CodeQL 팩을 즉시 실행하지 않고 다운로드하려면 codeql pack download
명령을 사용합니다. 이 방법은 인터넷에 액세스하지 않고 CodeQL 쿼리를 실행할 때 유용합니다. CodeQL 분석을 실행하는 경우 이전 예제와 동일한 방식으로 팩, 버전 및 경로를 지정할 수 있습니다.
echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...
여러 GitHub 컨테이너 레지스트리에서 CodeQL 팩 다운로드
CodeQL 팩이 여러 컨테이너 레지스트리에 있는 경우 CodeQL CLI에 각 팩을 찾을 위치를 지시해야 합니다. 자세한 내용은 "코드 검색을 위한 고급 설정 사용자 지정"을(를) 참조하세요.
CodeQL 팩에서 실행할 쿼리 지정
쿼리 지정자는 codeql database analyze
및 쿼리 집합에서 작동하는 기타 명령에서 사용됩니다.
쿼리 지정자의 전체 형식은 scope/name@range:path
입니다. 여기에서:
scope/name
(은)는 CodeQL 팩의 정규화된 이름입니다.range
(은)는 semver(의미론적 버전 관리) 범위입니다.path
는 단일 쿼리, 쿼리가 포함된 디렉터리 또는 쿼리 도구 모음 파일에 대한 파일 시스템 경로입니다.
scope/name
(을)를 지정하면 range
및 path
(은)는 선택 사항입니다. range
을(를) 생략하면 지정된 팩의 최신 버전이 사용됩니다. path
(을)를 생략하면 지정된 팩의 기본 쿼리 도구 모음이 사용됩니다.
path
는 .ql
쿼리 파일, 하나 이상의 쿼리가 포함된 디렉터리 또는 .qls
쿼리 도구 모음 파일 중 하나가 됩니다. 팩 이름을 생략하면 현재 프로세스의 작업 디렉터리를 기준으로 해석되는 path
(을)를 제공해야 합니다. Glob 패턴은 지원되지 않습니다.
scope/name
과 path
를 모두 지정하면 path
는 절대값이 될 수 없습니다. CodeQL 팩의 루트를 기준으로 고려됩니다.
쿼리 지정자 예
-
codeql/python-queries
-codeql/python-queries
팩 최신 버전의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다. -
codeql/python-queries@1.2.3
-codeql/python-queries
팩 버전1.2.3
의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다. -
codeql/python-queries@~1.2.3
-codeql/python-queries
팩 최신 버전(1.2.3
이상1.3.0
미만)의 기본 쿼리 도구 모음에 있는 모든 쿼리입니다. -
codeql/python-queries:Functions
-codeql/python-queries
팩 최신 버전에 있는Functions
디렉터리의 모든 쿼리입니다. -
codeql/python-queries@1.2.3:Functions
-codeql/python-queries
팩 버전 1.2.3의Functions
디렉터리에 있는 모든 쿼리입니다. -
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls
-codeql/python-queries
팩 버전 1.2.3의codeql-suites/python-code-scanning.qls
디렉터리에 있는 모든 쿼리입니다. -
suites/my-suite.qls
- 현재 작업 디렉터리를 기준으로 하는suites/my-suite.qls
파일의 모든 쿼리입니다.
팁
표준 CodeQL 쿼리 팩의 기본 쿼리 도구 모음은 codeql-suites/<lang>-code-scanning.qls
입니다. 다른 몇 가지 유용한 쿼리 도구 모음은 각 팩의 codeql-suites
디렉터리에서도 찾을 수 있습니다. 예를 들어 codeql/cpp-queries
팩에는 다음 쿼리 도구 모음이 포함됩니다.
-
cpp-code-scanning.qls
- C++용 표준 코드 검사 쿼리입니다. 이 팩의 기본 쿼리 도구 모음입니다. -
cpp-security-extended.qls
- C++용 기본cpp-code-scanning.qls
도구 모음의 쿼리와 낮은 심각도, 정밀도 쿼리입니다. -
cpp-security-and-quality.qls
-cpp-security-extended.qls
의 쿼리와 유지 관리 기능 및 안정성 쿼리입니다.
CodeQL 리포지토리에서 이러한 쿼리 도구 모음의 원본을 볼 수 있습니다. 다른 언어의 쿼리 도구 모음도 비슷합니다.
모델 팩을 사용하여 사용자 지정 종속성 호출 분석
code scanning 분석에 게시된 모델 팩을 --model-packs
옵션과 함께 사용할 수 있습니다. 예시:
$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
--model-packs my-repo/my-java-model-pack \
--output=/temp/my-company.sarif codeql/java-queries
이 예에서 표준 쿼리 팩 codeql/java-queries
의 관련 쿼리는 모델 팩 my-repo/my-java-model-pack
의 종속성 정보를 사용하여 해당 종속성을 호출하는 코드의 취약성을 확인합니다.
여러 번 게시된 모델 팩을 분석에서 지정할 수 있습니다.
자체 모델 팩 작성에 대한 자세한 내용은 "CodeQL 팩 만들기 및 작업"을 참조하세요.
게시된 팩 정보
팩이 분석에 사용하기 위해 게시되면 codeql pack create
또는 codeql pack publish
명령은 콘텐츠가 완료되었는지 확인하고 콘텐츠의 일부를 추가합니다.
-
쿼리 팩의 경우 해당 쿼리 팩이 개발된 정확한 버전의 각 라이브러리 팩의 복사본입니다. 쿼리 팩 사용자는 이러한 라이브러리 팩을 별도로 다운로드할 필요가 없습니다.
-
쿼리 팩의 경우 각 쿼리를 미리 컴파일한 표현입니다. 각 분석에서 쿼리에 대한 QL 원본을 컴파일하는 것보다 실행하는 것이 더 빠릅니다.
이 데이터의 대부분은 게시된 팩의 .codeql
디렉터리에 있지만 미리 컴파일된 쿼리는 각 쿼리의 .ql
원본 옆에 .qlx
접미사가 있는 파일에 있습니다. 게시된 팩의 쿼리를 사용하여 데이터베이스를 분석할 때 CodeQL은 .ql
원본 대신 이 파일을 로드합니다. 게시된 팩의 콘텐츠를 수정해야 하는 경우 .ql
파일의 수정이 적용되지 않게 할 수 있으므로 .qlx
파일을 모두 제거해야 합니다.