CodeQL CLI 설정하기

CodeQL CLI 설정하기

CodeQL 명령을 실행하려면 데이터베이스를 만들고 분석하는 데 필요한 도구, 쿼리 및 라이브러리에 액세스할 수 있도록 CLI를 설정해야 합니다.

CodeQL CLI은(는) 다양한 사용 사례 및 디렉터리 구조를 지원하도록 설정할 수 있습니다. 빠르게 시작하려면 아래 단계에 설명된 대로 비교적 간단한 설정을 채택하는 것이 좋습니다.

보안 연구에 CodeQL CLI을(를) 사용하거나 쿼리를 테스트 또는 기여하려는 경우, CodeQL CLI의 고급 설정이 필요할 수 있습니다. 자세한 내용은 "CodeQL CLI 고급 설정"을(를) 참조하세요.

CI 시스템에서 CodeQL CLI을(를) 설정하는 경우, CodeQL CLI 번들의 전체 콘텐츠를 CodeQL code scanning 분석을 실행하려는 모든 CI 서버에서 사용할 수 있도록 해야 합니다. 예를 들어 중앙 내부 위치에서 번들을 복사하고 추출하도록 각 서버를 구성할 수 있습니다. 또는 REST API를 사용하여 GitHub에서 직접 번들을 가져와 쿼리에 대한 최신 개선 사항을 활용할 수 있습니다. 자세한 내용은 REST API 설명서에서 "릴리스 및 릴리스 자산에 대한 REST API 엔드포인트" 항목을 참조하세요.

Apple Silicon으로 macOS를 사용하는 경우(예: Apple M1), Xcode 명령줄 개발자 도구 및 Rosetta 2가 설치되어 있는지 확인합니다.

1. CodeQL CLI tar 보관 파일 다운로드

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

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

• CodeQL CLI 제품
• https://github.com/github/codeql에서 호환되는 쿼리 및 라이브러리 버전
• 번들에 포함되는 모든 쿼리의 사전 컴파일 버전

항상 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 tar 보관 파일 추출

CodeQL CLI tar 보관 파일을 선택한 디렉터리에 추출합니다.

3. codeql 시작

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

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

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

CodeQL CLI 구성 테스트하기

CodeQL CLI 번들을 추출한 후 다음 명령을 실행하여 CLI가 데이터베이스를 만들고 분석하도록 올바르게 구성되어 있는지 확인할 수 있습니다.

• /<extraction root>/codeql이 PATH에 있는 경우 codeql resolve packs입니다.
• 그렇지 않으면 /<extraction root>/codeql/codeql resolve packs입니다.

성공했다면, 아래 추출된 것과 비슷한 내용이 출력됩니다.

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

간단한 설명을 위해 결과가 잘렸습니다. 실제 결과는 더 길고 더 상세합니다.

출력에 예상된 언어가 포함되어 있고 qlpack 파일의 디렉터리 위치가 올바른지 확인해야 합니다. 위치는 앞서 예시에서 <extraction root>(으)로 표시된 추출된 CodeQL CLI 번들 내에 있어야 합니다. CodeQL CLI에서 예상 언어에 대한 qlpack을 찾을 수 없는 경우 CodeQL 번들을 다운로드했는지 확인하고 CodeQL CLI의 독립 실행형 복사본이 아닌지 확인합니다.

데이터베이스를 만드는 데 사용할 수 있는 언어를 표시하기 위해 codeql resolve languages를 실행할 수도 있습니다. 그러면 CodeQL CLI 패키지에서 기본적으로 지원되는 언어가 나열됩니다.

필요에 따라, 실행하려는 미리 컴파일된 쿼리가 포함된 일부 CodeQL 팩을 다운로드할 수 있습니다. 자세한 내용은 "CodeQL 팩을 사용하여 분석 사용자 지정"을(를) 참조하세요.

이 codeql resolve packs 명령은 CodeQL CLI에서 분석에 사용할 수 있을 것으로 예상되는 쿼리 팩을 찾을 수 없는 경우 문제를 진단하는 데 유용합니다.

다음 단계

CodeQL CLI에서 분석할 코드를 준비하는 방법을 알아보려면 "CodeQL 분석을 위한 코드 준비" 항목을 참조하세요.