컴파일된 언어에 대한 CodeQL 빌드 옵션 및 단계

컴파일 언어용 자동 빌드 단계

GitHub Actions에 자체 호스트형 실행기를 사용하는 경우, autobuild 프로세스를 이용하려면 추가 소프트웨어를 설치해야 하는 경우가 있습니다. 또한 리포지토리에 특정 버전의 빌드 도구가 필요한 경우 수동으로 설치해야 할 수 있습니다. 자체 호스팅 실행기에서는 종속성을 실행기에 직접 설치해야 합니다. 이 문서의 각 autobuild 섹션에서 C/C++, C# 및 Java 대한 일반적인 종속성의 예를 제공합니다. 자세한 내용은 자체 호스팅 실행기을(를) 참조하세요.

C/C++ 빌드

CodeQL은 C/C++ 코드에 대해 autobuild 또는 manual 빌드 모드를 지원합니다.

C/C++용 자동 빌드 요약

지원되는 시스템 유형	시스템 이름
운영 체제	Windows, macOS 및 Linux
빌드 시스템	Windows: MSBuild 및 빌드 스크립트 Linux 및 macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild 및 빌드 스크립트

          `autobuild` 단계의 동작은 추출이 실행되는 운영 체제에 따라 달라집니다.

Windows 자동 검색

Windows autobuild 단계에서는 다음 방법을 사용하여 C/C++에 적합한 빌드 메서드를 자동 검색하려고 시도합니다.

1. 루트에 가장 가까운 솔루션(MSBuild.exe) 또는 프로젝트(.sln) 파일에 대해 .vcxproj를 호출합니다.

          `autobuild`는 최상위 디렉터리에서 동일한(가장 짧은) 깊이에 있는 여러 솔루션 또는 프로젝트 파일을 검색하면 모두 빌드하려고 합니다.
   

2. 빌드 스크립트처럼 보이는 스크립트(build.bat, build.cmd 및 build.exe)를 해당 순서대로 호출합니다.

Linux 및 macOS 자동 감지

Linux 및 macOS에서 autobuild 단계는 리포지토리에 있는 파일을 검토하여 사용되는 빌드 시스템을 확인합니다.

1. 루트 디렉터리에서 빌드 시스템을 찾습니다.
2. 찾을 수 없는 경우 C/C++용 빌드 시스템이 있는 고유한 디렉터리를 하위 디렉터리에서 검색합니다.
3. 적절한 명령을 실행하여 시스템을 구성합니다.

C/C++용 실행기 요구 사항

Ubuntu Linux 실행기에서 autobuild는 검색된 구성 및 빌드 단계에 필요한 종속성의 자동 설치를 시도할 수 있습니다. 기본적으로 이 동작은 GitHub 호스팅 실행기에서 활성화되어 있으며, 자체 호스팅 실행기에서는 비활성화됩니다. 환경에서 CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES를 true 또는 false로 설정하여 이 기능을 명시적으로 활성화 또는 비활성화할 수 있습니다. 환경 변수 정의에 대한 자세한 내용은 변수에 정보 저장을 참조하세요.

자체 호스팅 실행기의 경우, 종속성 자동 설치를 활성화하지 않는 한 gcc 컴파일러 설치를 요할 수 있으며 특정 프로젝트에 액세스하거나 clang 또는 msvc 실행 파일에 액세스해야 하는 경우도 있습니다. 또한 사용자의 프로젝트가 사용하는 빌드 시스템(예시: msbuild, make, cmake, bazel) 및 유틸리티(예시: python, perl, lex, yacc)도 설치해야 합니다. 종속성의 자동 설치를 활성화하는 경우 실행기에서 Ubuntu를 사용하고 있고 그것이 암호 없이 sudo apt-get을 실행할 수 있도록 보장해야 합니다.

Windows 실행기에서는 powershell.exe가 PATH에 위치하도록 요합니다.

C# 빌드

CodeQL은 C# 코드용으로 autobuild 또는 manual 빌드 모드를 지원합니다.

C/C++ 코드를 포함하는 리포지토리에 기본 설정을 활성화할 때 빌드 모드는 자동으로 none으로 설정됩니다.

C#용 빌드 없음

CodeQL은 모든 소스 파일 및 종속성에서 데이터베이스를 생성하기 전에 종속성을 복원하고 몇 가지 추가 원본 파일을 생성하여 보다 정확한 결과를 제공합니다.

종속성은 여러 가지 추론 및 전략을 사용하여 복원됩니다. *.csproj, *.sln, nuget.config, packages.config, global.json, project.assets.json 파일들이 주요 정보 소스입니다.

다음과 같이 생성된 원본 파일은 선택 사항이지만 CodeQL 데이터베이스의 정확성이 현저히 향상됩니다.

•         `global`가 MSbuild의 암시적 `using` 기능을 처리하기 위해 `using` 지시문을 생성하였습니다.
  

• ASP.NET Core 뷰 파일인 .cshtml 파일은 .cs 파일로 변환됩니다.

종속성 어셈블리명, 생성된 원본 파일, 프라이빗 피드에 저장된 및 리포지토리 내 원본 파일의 정보가 컴파일되어 CodeQL 데이터베이스를 생성하는 데에 사용됩니다.

C#의 빌드 없이 분석한 결과 정확도

전체 코드를 빌드하지 않고 CodeQL 데이터베이스를 생성하기 위해서는 종속성을 복원할 수 있고 리포지토리의 원본 파일을 함께 컴파일할 수 있어야 합니다. 종속성을 복원하거나 소스 코드를 컴파일하는 데 문제가 있는 경우 CodeQL 데이터베이스 및 code scanning 분석 결과의 정확도에 영향을 줄 수 있습니다.

다음 단계를 수행하여 보다 정확한 분석을 확보할 수 있습니다.

• 퍼블릭 인터넷에 대한 액세스를 제공하거나 프라이빗 NuGet 피드에 대한 액세스를 보장하고.
• 리포지토리에서 동일한 NuGet 종속성의 여러 버전을 필요로 하는지 확인합니다. CodeQL은 하나의 버전만 사용할 수 있으며 보통 여러 버전이 있는 최신 버전을 선택합니다. 이 방법이 모든 리포지토리에서 작동하지 않을 수도 있습니다.
• .NET 여러 버전(예: net48, net5.0 및 netstandard1.6)이 참조되는지 확인합니다. CodeQL은 하나의 버전만 이용할 수 있으므로 정확도에 영향을 미칠 수 있습니다.
• 클래스명이 충돌하지 않도록 해야 하며, 충돌 시 메서드 호출 대상이 누락되어 데이터 흐름 분석에 영향을 줄 수 있습니다.

C#용 자동 빌드 요약

지원되는 시스템 유형	시스템 이름
운영 체제	Windows, macOS 및 Linux
빌드 시스템	.NET 및 MSbuild 및 빌드 스크립트

Windows 자동 검색

          `autobuild` 프로세스는 다음 방법을 사용하여 C#에 적합한 빌드 메서드를 자동 검색하려고 시도합니다.

1. 루트에 가장 가까운 솔루션(dotnet build) 또는 프로젝트(.sln) 파일에 대해 .csproj를 호출합니다.

2. 루트에 가장 가까운 솔루션 또는 프로젝트 파일에 MSBuild.exe를 호출합니다.

          `autobuild`는 최상위 디렉터리에서 동일한(가장 짧은) 깊이에 있는 여러 솔루션 또는 프로젝트 파일을 검색하면 모두 빌드하려고 합니다.
   

3. 빌드 스크립트처럼 보이는 스크립트, build.bat, build.cmd 및 build.exe를 순서대로 호출합니다.

Windows C#에 대한 Runner 요구 사항

자체 호스팅 실행기에서 .NET Core 애플리케이션 개발의 경우 .NET SDK가 필요합니다(dotnet).

.NET Framework 애플리케이션 개발의 경우 Microsoft Build 도구(msbuild) 및 NuGet CLI(nuget)가 필요합니다.

Windows 실행기에서는 powershell.exe가 PATH에 위치하도록 요합니다.

          `build-mode: none`을 이용해 CodeQL 데이터베이스를 생성할 계획인 경우, 공용 인터넷에 대한 액세스도 제공하거나, 프라이빗 NuGet 피드에 대한 액세스가 제공되도록 확보해야 합니다.

Linux 및 macOS 자동 감지

1. 루트에 가장 가까운 솔루션(dotnet build) 또는 프로젝트(.sln) 파일에 대해 .csproj를 호출합니다.

2. 루트에 가장 가까운 솔루션 또는 프로젝트 파일에 MSbuild를 호출합니다.

          `autobuild`는 최상위 디렉터리에서 동일한(가장 짧은) 깊이에 있는 여러 솔루션 또는 프로젝트 파일을 검색하면 모두 빌드하려고 합니다.
   

3. 빌드 스크립트처럼 보이는 스크립트, build와 build.sh를 순서대로 호출합니다.

Linux 및 macOS에서 C#용 실행기 요구 사항

자체 호스팅 실행기에서 .NET Core 애플리케이션 개발의 경우 .NET SDK가 필요합니다(dotnet).

.NET Framework 애플리케이션 개발의 경우 Mono 런타임(mono, msbuild 또는 nuget)을 실행해야 합니다.

          `build-mode: none`을 이용해 CodeQL 데이터베이스를 생성할 계획인 경우, 공용 인터넷에 대한 액세스도 제공하거나, 프라이빗 NuGet 피드에 대한 액세스가 제공되도록 확보해야 합니다.

수동 빌드용으로 CodeQL가 추가한 C# 컴파일러 플래그

CodeQL 추적기는 빌드 프로세스를 가로채 관련 CodeQL 언어 추출기로 정보를 전달함으로써 모든 컴파일된 언어를 추출할 수 있도록 합니다. 추적기는 모든 구성 요소가 빌드되어 CodeQL 데이터베이스에 포함되도록 C# 컴파일러 호출에 특정 플래그를 삽입하고, 이로 인해 CodeQL 분석 중 C# 코드가 예상과 다른 방식으로 빌드될 수 있습니다.

/p:MvcBuildViews=true

이 옵션을 true 설정하면 ASP.NET MVC(model-view-controller) 프로젝트의 보기가 빌드 프로세스의 일부로 미리 컴파일되어 오류를 catch하고 성능을 향상시키는 데 도움이 됩니다. 추적기는 이 플래그를 삽입하여 CodeQL가 이러한 뷰에서 생성된 코드의 데이터 흐름과 관련될 수 있는 보안 문제를 찾아 강조할 수 있도록 합니다. 자세한 내용은 Microsoft Learn의 MVC 애플리케이션에 뷰 추가를 참조하세요.

/p:UseSharedCompilation=false

이 옵션을 false로 설정 시 공유 컴파일 기능이 비활성화되어 빌드 시간이 느려질 수 있습니다. /p:UseSharedCompilation=false가 not 지정되면 msbuild는 컴파일러 서버 프로세스를 시작하고, 해당하는 단일 프로세스에 의해 모든 컴파일이 완료됩니다. 하지만 CodeQL 추적기는 새로 생성되는 프로세스의 인수를 검사하는 데 의존합니다.

/p:EmitCompilerGeneratedFiles=true

이 옵션을 true로 설정하면 빌드 프로세스 중에 컴파일러가 생성한 파일이 출력됩니다. 이 옵션을 통해 컴파일러는 향상된 정규식 지원, 직렬화 및 웹 애플리케이션 뷰 생성 등 기능을 지원하는 데 사용되는 추가 소스 파일을 생성하게 됩니다. 이렇게 생성되는 아티팩트는 보통 컴파일러에 의해 디스크에 기록되지 않지만, 이 옵션을 true로 설정하면 파일을 디스크에 기록되도록 강제되어 추출기가 파일을 처리할 수 있습니다.

일부 레거시 프로젝트와 .sqlproj 파일을 사용하는 프로젝트의 경우, 삽입된 /p:EmitCompilerGeneratedFiles=true 속성으로 인해 msbuild에서 예기치 못한 문제가 발생하는 것을 볼 수 있습니다. 이 문제 해결에 대한 자세한 내용은 C# 컴파일러가 예기치 않게 실패을 참조하세요.

Go 빌드

CodeQL은 Go 코드용 autobuild 또는 manual 빌드 모드를 지원합니다.

Go용 자동 빌드 요약

지원되는 시스템 유형	시스템 이름
운영 체제	Windows, macOS 및 Linux
빌드 시스템	Go 모듈, dep 및 글라이드를 비롯해 Makefiles 및 Ninja 스크립트를 포함한 빌드 스크립트

Go용 자동 감지

          `autobuild` 프로세스는 `.go` 파일을 모두 추출하기 전에 Go 리포지토리에서 필요로 하는 종속성을 설치하는 적절한 방법을 자동으로 검색하려 합니다.

1. make, ninja, ./build 또는 ./build.sh를 순서대로 실행하여 이 명령들 중 하나가 성공하고 이어서 go list ./...도 성공하면 필요한 종속성이 설치되었음을 의미합니다.

1. 명령이 모두 실패하면 go.mod, Gopkg.toml 또는 glide.yaml을 찾아서 go get(벤더링이 사용 중이지 않는 한), dep ensure -v 또는 glide install을 각각 실행하여 종속성 설치를 시도합니다.
2. 마지막으로, 이러한 종속성 관리자에 대한 구성 파일을 찾을 수 없는 경우, GOPATH로 추가하는 데에 적절하게 리포지토리 디렉터리 구조를 재정렬하고 go get을 이용하여 종속성을 설치합니다. 디렉터리 구조는 추출 완료 후 정상으로 되돌립니다.

3.        `go build ./...` 실행과 유사하게 리포지토리의 모든 Go 코드를 추출합니다.
   

Go용 추출기 옵션

테스트 코드(파일 내 _test.go로 끝나는 코드)는 분석되지 않는 것이 기본 설정입니다. CodeQL CLI를 사용 시 --extractor-option extract_tests=true 옵션을 이용하거나 CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS 환경 변수를 true로 설정하여 이를 재정의할 수 있습니다.

또한 vendor 디렉터리는 CodeQL Go 분석에서 제외되는 것이 기본 설정입니다. CodeQL CLI를 사용할 때 --extractor-option extract_vendor_dirs=true 옵션을 이용하거나 CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS 환경 변수를 true로 설정하여 이를 재정의할 수 있습니다.

자바 및 코틀린 빌드

CodeQL은 다음과 같은 빌드 모드를 지원합니다.

• Java: none, autobuild 또는 manual
• Kotlin: autobuild 또는 manual

리포지토리에 대한 기본 설정을 처음 사용하도록 설정하면 Java 코드만 검색되면 빌드 모드가 none 설정됩니다. Kotlin 또는 Java 및 Kotlin 코드 조합이 검색되면 빌드 모드가 autobuild 설정됩니다.

이후에 사용자가 none 빌드 모드를 사용하는 리포지토리에 Kotlin 코드를 추가할 경우, CodeQL 분석은 Kotlin이 지원되지 않음을 설명하는 경고 메시지를 보고합니다. 사용자는 기본 설정을 비활성화한 후 다시 활성화해야 합니다. 기본 설정을 다시 활성화하면 빌드 모드는 두 언어를 모두 분석할 수 있도록 autobuild로 변경됩니다. 또는 사용자가 고급 설정으로 변경할 수도 있습니다. 자세한 내용은 경고: 빌드 없이 처리할 수 없는 프로젝트에서 X Kotlin 파일이 검색됨을(를) 참조하세요.

Java 대한 빌드 없음

CodeQL는 Gradle 또는 Maven을 실행하여 정확한 종속성 정보를 추출하려고 시도합니다(단, 빌드를 호출하지 않음). 그런 다음 모든 Java 파일에서 데이터베이스를 생성합니다. 모든 루트 Maven 또는 Gradle 프로젝트 파일(상위 디렉터리에 빌드 스크립트가 없는 빌드 스크립트)은 종속성 정보를 쿼리하고, 충돌이 있는 경우 최신 버전의 종속성이 선호됩니다. Maven 또는 Gradle을 실행하기 위한 실행기 요구 사항에 대한 자세한 내용은 Java 대한 러너 요구 사항을 참조하세요.

Java 대한 빌드 분석 없음의 정확도

빌드를 하지 않고 CodeQL Java 데이터베이스를 생성하면, 다음과 같은 경우에 autobuild 또는 수동 빌드 단계를 사용하는 것보다 정확도가 떨어질 수 있습니다.

• Gradle 또는 Maven 빌드 스크립트는 종속성 정보를 쿼리할 수 없으며 종속성 추측(Java 패키지 이름 기반)은 정확하지 않습니다.
• 리포지토리는 보통 빌드 프로세스 중에 코드를 생성합니다. 이는 사용자가 다른 모드를 사용하여 CodeQL 데이터베이스를 생성한 경우 분석됩니다.

다음 단계를 수행하여 보다 정확한 분석을 확보할 수 있습니다.

• 공개 인터넷으로의 액세스를 제공하거나 프라이빗 아티팩트 리포지토리에 대한 액세스를 보장하고.
• 리포지토리에서 동일한 종속성의 여러 버전을 필요로 하는지 확인합니다. CodeQL은 하나의 버전만 사용할 수 있으며 보통 여러 버전이 있는 최신 버전을 선택합니다. 이 방법이 모든 리포지토리에서 작동하지 않을 수도 있습니다.
• 여러 원본 Java 파일에서 둘 이상의 JDK API 버전이 필요한지 확인합니다. 여러 개의 버전이 표시되면 CodeQL은 빌드 스크립트에서 필요로 하는 최상의 버전을 사용합니다. 즉, 하위 버전의 JDK를 요하는 일부 파일이 부분적으로 분석될 수 있다는 뜻입니다. 예를 들어, 일부 파일에서 JDK 8을 요하지만 하나 이상의 빌드 스크립트에서 JDK 17 요구 사항이 발견되면 CodeQL는 JDK 17을 사용합니다. JDK 8을 필요로 하고 JDK 17을 이용해 빌드할 수 없는 파일은 부분적으로 분석됩니다.
• 클래스명이 충돌되는 것을 피해야 하며(예시: org.myproject.Test를 정의하는 여러 개의 파일), 이를 어길 시 메서드 호출 대상이 누락되어 데이터 흐름 분석에 영향을 줄 수 있습니다.

Java에 대한 자동 빌드 요약

지원되는 시스템 유형	시스템 이름
운영 체제	Windows, macOS 및 Linux(제한 없음)
빌드 시스템	Gradle, Maven 및 Ant

Java 자동 감지

          `autobuild` 프로세스는 다음 전략을 적용하여 Java 코드베이스에 대한 빌드 시스템을 확인하려고 합니다.

1. 루트 디렉터리에서 빌드 파일을 검색합니다. Gradle, Maven 및 Ant 빌드 파일을 순서대로 확인합니다.
2. 찾은 첫 번째 빌드 파일을 실행합니다. Gradle 및 Maven 파일이 모두 있는 경우 Gradle 파일이 사용됩니다.
3. 그렇지 않으면 루트 디렉터리의 직접 하위 디렉터리에서 빌드 파일을 검색합니다. 하나의 하위 디렉터리에 빌드 파일이 포함되어 있는 경우 해당 하위 디렉터리에서 식별된 첫 번째 파일을 실행합니다(1의 경우와 동일한 기본 설정 사용). 둘 이상의 하위 디렉터리에 빌드 파일이 포함된 경우 오류를 보고합니다.

Java에 대한 Runner 요구 사항

자체 호스팅 실행기를 사용하는 경우 필요한 Java 버전이 있어야 합니다.

• 단일 버전의 Java 필요한 리포지토리를 분석하는 데 실행기를 사용하는 경우 적절한 JDK 버전을 설치해야 하며 PATH 변수에 있어야 합니다(java 및 javac 찾을 수 있도록).

• 여러 버전의 Java 필요한 리포지토리를 분석하는 데 실행기를 사용하는 경우 적절한 JDK 버전을 설치해야 하며 toolchains.xml 파일을 통해 지정할 수 있습니다. 주로 Apache Maven에서 사용하는 구성 파일로, 도구의 위치, 도구 버전, 도구 사용에 필요한 추가 구성을 지정하도록 해줍니다. 자세한 내용은 Apache Maven 설명 문서에서 툴체인 사용 가이드를 참조하세요.

다음 실행 파일은 다양한 Java 프로젝트에 필요할 수 있으며 PATH 변수에 있어야 하지만 모든 경우에 필수는 아닙니다.

•         `mvn` (Apache Maven)
  

•         `gradle` (Gradle)
  

•         `ant` (Apache Ant)
  

사용자는 사용자의 프로젝트에서 사용하는 빌드 시스템(예: make, cmake, bazel)과 유틸리티(예: python, perl, lex, and yacc)도 설치해야 합니다.

Windows 실행기에서는 powershell.exe가 PATH에 위치하도록 요합니다.

Swift 빌드

CodeQL는 Go 코드용 autobuild 또는 manual 빌드 모드를 지원합니다.

Swift용 자동 빌드 요약

지원되는 시스템 유형	시스템 이름
운영 체제	macOS
빌드 시스템	Xcode

          `autobuild` 프로세스는 Xcode 프로젝트 또는 작업 영역으로부터 가장 큰 타겟의 빌드를 시도합니다.

Swift 코드의 코드 스캐닝은 기본적으로 macOS 실행기를 사용합니다.

데이터 재사용 가능성.코드 스캐닝.기본 설정 스위프트 셀프 호스티드 러너 %}

CodeQL 분석 워크플로

Swift 컴파일 사용자 지정하기

          `xcodebuild` 및 `swift build`는 모두 Swift 빌드용으로 지원됩니다. 빌드 중에는 하나의 아키텍처만 타겟으로 지정할 것을 권장합니다. 예를 들어, `ARCH=arm64`용으로 `xcodebuild`, 또는 `--arch arm64`용으로 `swift build`를 지정합니다.

          `archive` 및 `test` 옵션을 `xcodebuild`로 전달할 수 있습니다. 하지만, `xcodebuild` 표준 명령어가 가장 빠르고 CodeQL가 성공적인 스캔을 위해 요구하는 전부이므로 권장됩니다.

Swift 분석의 경우, CodeQL 데이터베이스를 생성하기 전에 CocoaPods 또는 Carthage를 통해 관리되는 종속성을 언제나 명시적으로 설치해야 합니다.