Skip to main content

CodeQL CLI 알아보기

CodeQL CLI을(를) 사용하여 소프트웨어 프로젝트에서 로컬로 CodeQL 프로세스를 실행하거나 GitHub Enterprise Server에 업로드할 code scanning 결과를 생성할 수 있습니다.

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

GitHub CodeQL은(는) 설치 시 사용자별로 라이선스가 부여됩니다. 라이선스 제한에 따라 특정 작업에만 CodeQL을(를) 사용할 수 있습니다. 자세한 내용은 "CodeQL CLI 알아보기"을 참조하세요.

GitHub Advanced Security 라이선스가 있는 경우 CodeQL을(를) 사용하여 분석 자동화, 연속 통합 및 지속적인 업데이트를 할 수 있습니다. 자세한 내용은 "GitHub Advanced Security 정보.

CodeQL CLI 정보

소프트웨어 개발자 및 보안 연구원은 CodeQL 분석을 사용하여 코드를 보호할 수 있습니다. CodeQL에 대한 자세한 내용은 "CodeQL을 사용하는 코드 검사 안내"을 참조하세요.

CodeQL CLI는 코드를 분석하는 데 사용할 수 있는 독립 실행형 명령줄 도구입니다. 그 주요 목적은 코드베이스, 즉 CodeQL 데이터베이스의 데이터베이스 표현을 생성하는 것입니다. 데이터베이스가 준비되면 대화형으로 쿼리하거나 쿼리 도구 모음을 실행하여 SARIF 형식으로 결과 집합을 생성하고 결과를 에 업로드할 수 있습니다.

CodeQL CLI을(를) 사용하여 다음을 분석합니다.

  • GitHub 엔지니어 및 오픈 소스 커뮤니티에서 제공하는 쿼리를 사용하여 CodeQL 분석 실행
  • 업로드하여 GitHub Enterprise Server에 표시할 수 있는 코드 스캔 경고 생성
  • Visual Studio Code 확장용 CodeQL에 사용할 CodeQL 데이터베이스를 만듭니다.
  • 사용자 고유의 분석에 사용할 사용자 지정 CodeQL 쿼리 개발 및 테스트

CodeQL CLI은(는) 다음을 분석할 수 있습니다.

  • 동적 언어(예: JavaScript 및 Python).
  • 컴파일된 언어(예: C/C++, C#, Go, 및 Java).
  • 여러 언어로 작성된 코드베이스.

CodeQL CLI 설정 방법에 대한 자세한 내용은 "CodeQL CLI 설정하기"을(를) 참조하세요.

code scanning에 대한 CodeQL CLI 사용 정보

CodeQL CLI는 타사 CI(연속 통합) 시스템에서 처리 중인 코드에서 code scanning을 실행하는 데 사용할 수 있는 도구입니다. Code scanning는 GitHub 리포지토리의 코드를 분석하여 보안 취약성 및 코딩 오류를 찾는 데 사용하는 기능입니다. 분석으로 식별되는 모든 문제는 리포지토리에 표시됩니다. 외부 CI 시스템에서 코드 스캔을 사용하는 방법에 대한 개요는 "AUTOTITLE"을(를) 참조하세요. CodeQL 분석을 실행하기 위한 권장 사양(RAM, CPU 코어 및 디스크)은 "CodeQL을 실행하기 위한 권장 하드웨어 리소스"을(를) 참조하세요.

또는 GitHub Actions 또는 Azure DevOps 파이프라인을 통해 CodeQL CLI을(를) 사용하여 코드를 스캔할 수 있습니다. 자세한 내용은 Microsoft Learn에서 "코드 스캔을 위한 기본 설정 구성" 또는 GitHub Advanced Security for Azure DevOps 구성을 참조하세요.

코드 스캔을 위해 CodeQL 분석을 사용하는 모든 옵션에 대한 개요는 "CodeQL을 사용하는 코드 검사 안내"을 참조하세요.

참고:

  • CodeQL CLI는 Advanced Security 라이선스가 있는 고객이 사용할 수 있습니다.

  • CodeQL CLI는 (musl 기반) Alpine Linux와 같은 비 glibc Linux 배포판과 현재 호환되지 않습니다.

CodeQL CLI을(를) 사용한 코드 스캔 결과 생성 알아보기

CodeQL CLI을(를) 직접 실행하도록 선택한 경우, 먼저 로컬로 CodeQL CLI을(를) 설치해야 합니다. 외부 CI 시스템에서 CodeQL CLI을(를) 사용하려는 경우, CI 시스템의 서버에서 CodeQL CLI을(를) 사용할 수 있도록 해야 합니다. 자세한 내용은 "CodeQL CLI 설정하기"을(를) 참조하세요.

CodeQL CLI이(가) 설정되면 세 가지 명령을 사용하여 결과를 생성하고 GitHub Enterprise Server에 업로드할 수 있습니다.

  1. database create - 리포지토리에서 지원되는 각 프로그래밍 언어의 계층 구조를 나타내는 CodeQL 데이터베이스를 만듭니다. 자세한 내용은 "CodeQL 분석을 위한 코드 준비"을(를) 참조하세요.
  2. database analyze - 각 CodeQL 데이터베이스를 분석하고 그 결과를 SARIF 파일로 요약하는 쿼리를 실행합니다. 자세한 내용은 "CodeQL 쿼리를 사용하여 코드 분석"을(를) 참조하세요.
  3. github upload-results - 결과가 분기 또는 끌어오기 요청과 일치하고 code scanning 경고로 표시되는 GitHub Enterprise Server에 결과 SARIF 파일을 업로드합니다. 자세한 내용은 "GitHub에 CodeQL 분석 결과 업로드"을(를) 참조하세요.

참고: code scanning로 표시할 SARIF 데이터를 업로드하면 GitHub Enterprise Server가 GitHub Advanced Security를 사용하도록 설정된 조직 소유 리포지토리의 퍼블릭 리포지토리가 지원됩니다. 자세한 내용은 "리포지토리에 대한 보안 및 분석 설정 관리"을 참조하세요.

CodeQL 분석을 위한 CI 구성 예시

다음은 지원되는 두 언어로 코드베이스를 분석한 후 결과를 GitHub Enterprise Server에 업로드하는 데 사용할 수 있는 CodeQL CLI에 대한 일련의 명령 전체의 예시입니다.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

GitHub CodeQL 라이선스 알아보기

라이선스 알림: GitHub Enterprise 라이선스가 없는 경우, 이 제품을 설치하면 GitHub CodeQL 이용 약관에 동의하는 것으로 간주됩니다.

GitHub CodeQL은(는) 사용자 단위로 라이선스가 부여됩니다. 라이선스 제한에 따라 CodeQL을(를) 사용하여 다음 작업을 수행할 수 있습니다.

  • 학술 연구를 수행합니다.
  • 소프트웨어를 시연합니다.
  • OSI 승인 라이선스로 릴리스된 CodeQL 쿼리를 테스트하여 해당 쿼리의 새 버전이 계속해서 올바르게 취약성을 찾는지 확인합니다.

여기서 "OSI 승인 라이선스"는 OSI(오픈 소스 이니셔티브)가 승인한 오픈 소스 소프트웨어 라이선스를 의미합니다.

오픈 소스 코드베이스(OSI 승인 라이선스에 따라 릴리스된 코드베이스)로 작업하는 경우, 다음 작업에 CodeQL을(를) 사용할 수도 있습니다.

  • 오픈 소스 코드베이스의 분석을 수행합니다.
  • 오픈 소스 코드베이스가 GitHub.com에서 호스팅되고 유지 보수되는 경우 자동화된 분석, 연속 통합 또는 지속적인 업데이트를 위해 또는 해당 기간 동안 CodeQL 데이터베이스를 생성합니다.

CodeQL은(는) GitHub Advanced Security에 대한 라이선스가 없는 한, 일반적인 소프트웨어 엔지니어링 프로세스의 일부이든 아니든, 여기에 나열된 명시적 경우 외에는 자동화된 분석, 연속 통합 또는 지속적인 업데이트에 사용할 수 없습니다.