이 버전의 GitHub Enterprise Server는 다음 날짜에 중단됩니다. 2026-03-17. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

CodeQL CLI 고급 설정

CodeQL 리포지토리의 로컬 체크 아웃을 사용하고, 여러 버전의 CodeQL CLI를 설정하며, GitHub에서 다운로드한 데이터베이스를 분석하기 위해 CodeQL CLI 설정을 수정할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

CodeQL은(는) 다음 리포지토리 유형에 사용할 수 있습니다.

이 문서의 내용

CodeQL CLI의 고급 설정에 관한 정보

코드 스캐닝 이상을 목적으로 CodeQL을 사용하기로 계획한 경우, CodeQL CLI의 고급 설정이 나을 수 있습니다.

  • 오픈 소스 공유 CodeQL 쿼리에 기여하고 싶다면, CodeQL 소스 코드를 직접 사용하는 편이 더 적합할 수 있습니다.
  • 코드베이스에 대한 코드 스캐닝 경고를 생성하기 위해 최신 CodeQL 기능을 사용하는 동시에 특정 버전의 CodeQL CLI와만 호환되는 다른 코드베이스를 분석하려는 경우, 여러 버전의 CodeQL CLI를 설치할 수 있습니다.
  • 쿼리를 검색 및 개발 중인 경우 GitHub.com로부터 흥미롭거나 고유한 데이터베이스를 다운로드할 수 있습니다.

CodeQL CLI의 가장 간단한 설정에 대한 자세한 내용은 CodeQL CLI 설정하기을 참조하세요.

CodeQL 소스 코드 직접 체크아웃하기

오픈 소스 공유 쿼리로 작업하거나 기여하기 위해 CodeQL 쿼리 소스로 직접 작업하는 것을 선호하는 사용자가 있습니다. 이 때는 다음 단계를 사용하는 것을 권장합니다.

1. CodeQL CLI tar 아카이브를 다운로드합니다

CodeQL CLI 다운로드 패키지는 도구, 스크립트 및 다양한 CodeQL 관련 파일을 포함하는 tar 보관 파일입니다. GitHub Enterprise 라이선스가 없는 경우, 이 보관 파일을 다운로드하면 GitHub CodeQL 이용 약관에 동의하는 것으로 간주됩니다.

https://github.com/github/codeql-action/releases에서 CodeQL 번들을 다운로드해야 합니다. 번들에는 다음이 포함됩니다.

참고 항목

GitHub Enterprise Server 3.15의 경우, CodeQL CLI 2.18.4버전을 권장합니다.

항상 CodeQL 번들을 사용해야 합니다. 이 번들은 호환성을 보장하고 CodeQL CLI 쿼리를 별도로 다운로드하고 CodeQL 쿼리를 체크 아웃하는 것보다 훨씬 나은 성능을 제공합니다. 하나의 특정 플랫폼에서만 CLI를 실행하는 경우 적절한 codeql-bundle-PLATFORM.tar.zst 파일을 다운로드합니다. 또는 지원되는 모든 플랫폼에 해당하는 CLI가 포함된 codeql-bundle.tar.zst를 다운로드할 수 있습니다.

번들의 tar.gz 변형도 있으며, 효율성이 떨어지는 gzip 알고리즘을 사용하여 압축된다는 점을 제외하고는 tar.zst 변형과 동일합니다. tar.gz 변형을 다운로드하는 유일한 이유는 표준 압축 알고리즘을 지원하지 않는 이전 압축 해제 도구를 사용하는 경우입니다.

2. 새로운 CodeQL 디렉터리를 생성합니다

CLI 및 사용하고자 하는 쿼리와 라이브러리를 넣을 수 있는 새 디렉터리를 생성합니다. 예: $HOME/codeql-home.

기본으로 제공되는 CLI의 검색 작업에서는 데이터베이스 생성 및 분석에 사용되는 파일을 찾기 위해 동일한 상위 디렉터리 아래의 모든 형제 디렉터리를 자동으로 검색합니다. 구성 요소를 자체 디렉터리에 보관하면 명령줄에 추가 옵션을 지정하지 않아도 모든 파일을 사용할 수 있고, CLI가 관련 없는 형제 디렉터리를 검색하는 일을 막을 수 있습니다.

3. CodeQL 쿼리의 로컬 복사본을 가져옵니다.

CodeQL 리포지토리는 지원되는 모든 언어를 대상으로 한 CodeQL 분석에 요구되는 쿼리 및 라이브러리를 포함하고 있습니다. codeql-home에 해당 리포지토리를 복사합니다.

복사한 리포지토리의 루트는 codeql를 기본값으로 합니다. 단계 1에서 압축 해제할 CodeQL CLI와의 충돌을 피하기 위해 이 폴더 codeql-repo의 이름을 변경합니다. 명령줄에서 git을 사용할 때는 codeql-home 폴더에서 git clone git@github.com:github/codeql.git codeql-repo을 실행함으로써 하나의 단계에서 리포지토리를 복사하고 재명명할 수 있습니다.

이 리포지토리 안에서 쿼리 및 라이브러리는 CodeQL 팩에 구성됩니다. CodeQL 팩에는 쿼리 자체와 더불어 CodeQL CLI에게 쿼리 파일의 처리 방법을 알려주는 중요한 메타데이터가 포함되어 있습니다. 자세한 내용은 CodeQL 팩 만들기 및 작업을(를) 참조하세요.

참고 항목

다른 사용자에게 사용할 수 있는 CodeQL 쿼리 버전들이 있습니다. 사용 사례에 알맞은 버전을 확인하세요.

  • CodeQL CLI의 최신 배포판과 같이 사용하려는 쿼리의 경우, codeql-cli/latest 태그가 지정된 브랜치를 체크아웃하세요. CodeQL CLI를 사용하여 구축하였거나 최근 GitHub에서 다운로드한 데이터베이스에는 해당 브랜치를 사용해야 합니다.
  • 최신 CodeQL 쿼리의 경우, main 브랜치를 체크아웃합니다. 이 브랜치는 최신 버전의 CodeQL 분석을 나타냅니다.

4. CodeQL CLI tar 아카이브를 압축 해제합니다.

2단계에서 생성한 디렉터리에 tar 아카이브를 압축 해제합니다.

예를 들어, CodeQL 리포지토리 복사본의 경로가 $HOME/codeql-home/codeql-repo인 경우 $HOME/codeql-home/로 CLI를 압축 해제합니다.

5.codeql 시작

추출한 후에는 codeql 실행 파일을 몇 가지 방법으로 실행하여 CodeQL 프로세스를 실행할 수 있습니다.

  • <extraction-root>/codeql/codeql을(를) 실행합니다. 여기서 <extraction-root>는 CodeQL CLI 패키지를 추출한 폴더입니다.
  • codeql처럼 실행 파일을 실행할 수 있도록 PATH에 <extraction-root>/codeql를 추가합니다.

이제 CodeQL 명령을 실행할 수 있습니다. CodeQL CLI 명령의 전체 목록은 CodeQL CLI 명령 매뉴얼을(를) 참조하세요.

6. CodeQL CLI 설정을 확인하세요.

CodeQL CLI에는 데이터베이스의 생성 및 분석을 위해 올바로 설정되었는지 확인하기 위해 실행할 수 있는 하위 명령이 있습니다.

  • 데이터베이스를 만드는 데 사용할 수 있는 언어를 표시하려면 codeql resolve languages를 실행합니다. 그러면 CodeQL CLI 패키지에서 기본적으로 지원하는 언어가 나열됩니다.
  • CLI에서 찾을 수 있는 CodeQL 팩을 표시하기 위해 codeql resolve qlpacks를 실행합니다. 이후, CodeQL CLI에 직접 사용할 수 있는 모든 CodeQL 팩의 사용할 수 있는 이름이 표시됩니다. 여기에는 다음 사항이 포함됩니다.
  • 각 지원 언어에 대한 쿼리 팩(예시: codeql/{language}-queries). 이러한 팩에는 분석마다 실행하게 될 표준 쿼리가 포함됩니다.
  • 각 지원 언어마다 쿼리 팩(예시: codeql/{language}-all). 이러한 팩에는 쿼리 작성기에 유용한 제어 흐름 및 데이터 흐름 라이브러리 등 쿼리 라이브러리가 포함됩니다.
  • 지원되는 언어마다 예시 팩(예시: codeql/{language}-examples). 이러한 팩에는 CodeQL 코드 조각이 포함되어 있는데, 이는 쿼리 작성자에게 유용합니다.
  • 레거시 팩은 이전 제품을 사용하여 생성된 사용자 지정 쿼리 및 라이브러리가 사용자의 CodeQL 버전과 호환되도록 보장합니다.

CodeQL CLI의 두 가지 버전 사용하기

최신 CodeQL 기능을 사용하여 쿼리 또는 CodeQL 테스트를 실행하는 동시 GitHub Enterprise Server에서 특정 버전의 CodeQL 코드 검사와 호환되는 데이터베이스를 준비하고 싶다면 두 가지 버전의 CLI를 설치해야 할 것입니다. 원하는 버전의 CodeQL CLI를 다운로드하고 동일한 상위 디렉터리에 2개의 CLI 아카이브를 압축 해제할 수 있습니다.

GitHub.com로부터 데이터베이스 다운로드하기

GitHub은(는) GitHub.com에 200,000개 이상의 리포지토리에 대한 CodeQL 데이터베이스는 REST API를 사용하여 다운로드할 수 있습니다. 리포지토리 목록은 계속 성장 및 발전하고 있으며, 보안 연구에 가장 흥미로운 코드베이스를 포함하도록 보장합니다.

VS Code 확장용 CodeQL을 사용하여 GitHub.com에서 데이터베이스를 분석할 수도 있습니다. 자세한 내용은 CodeQL 쿼리 실행을(를) 참조하세요.

/repos/<owner>/<repo>/code-scanning/codeql/databases 엔드포인트를 사용하여 이용해 다운로드 시 사용 가능한 CodeQL 데이터베이스가 리포지토리에 포함되어 있는지 확인할 수 있습니다. 예를 들어 GitHub CLI를 이용해 CodeQL 데이터베이스를 확인하기 위해서는 다음을 실행합니다.

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

이 명령은 리포지토리에 사용할 수 있는 CodeQL 데이터베이스에 대한 정보를 반환하며, 여기에는 데이터베이스가 나타내는 언어 및 데이터베이스가 마지막으로 업데이트된 시점이 포함됩니다. 사용할 수 있는 CodeQL 데이터베이스가 없는 경우, 응답이 빈 값이 됩니다.

관심 있는 언어에 대한 CodeQL 데이터베이스가 있는지 확인했다면, 다음 명령을 이용해 다운로드할 수 있습니다.

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

자세한 내용은 CodeQL 데이터베이스 엔드포인트 가져오기 설명 문서를 참조하세요.

CodeQL CLI를 이용한 분석을 실행하기 전에는 데이터베이스의 압축을 해제해야 합니다.