CodeQL CLI 고급 설정

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

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

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.14의 경우, CodeQL CLI 버전 2.17.6을(를) 권장합니다.

항상 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인 경우 CLI를 $HOME/codeql-home/(으)로 추출합니다.

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 패키지에서 기본적으로 지원되는 언어가 나열됩니다.
  • codeql resolve qlpacks를 실행하여 CLI에서 찾을 수 있는 CodeQL 팩을 표시합니다. 그러면 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의 버전을 다운로드하고 동일한 부모 디렉터리에서 두 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를 사용하여 분석을 실행하기 전에 데이터베이스의 압축을 풉니다.