코드 검사

Azure DevOps용 GitHub Advanced Security의 코드 검색을 사용하면 Azure DevOps 리포지토리의 코드를 분석하여 보안 취약성 및 코딩 오류를 찾을 수 있습니다. 분석으로 식별되는 모든 문제는 경고로 발생합니다. 코드 검색은 CodeQL을 사용하여 취약성을 식별합니다.

CodeQL은 보안 확인을 자동화하기 위해 GitHub가 개발한 코드 분석 엔진입니다. CodeQL을 사용하여 코드를 분석하고 결과를 코드 검사 경고로 표시할 수 있습니다. CodeQL에 대한 자세한 설명서는 CodeQL 설명서를 참조 하세요.

Azure DevOps용 GitHub Advanced Security는 Azure Repos에서 작동합니다. GitHub 리포지토리에서 GitHub Advanced Security를 사용하려면 GitHub Advanced Security를 참조하세요.

코드 검색을 위한 추가 구성

언어 및 쿼리 지원

GitHub 전문가, 보안 연구원 및 커뮤니티 기여자는 코드 검사에 사용되는 기본 CodeQL 쿼리를 작성하고 유지 관리합니다. 쿼리는 분석을 개선하고 가양성 결과를 줄이기 위해 정기적으로 업데이트됩니다. 쿼리는 오픈 소스이므로 github/codeql 리포지토리에서 쿼리를 보고 기여할 수 있습니다.

CodeQL은 다음 언어 식별자를 지원하고 사용합니다.

자세한 내용은 지원되는 언어 및 프레임워크를 참조 하세요.

빌드 로그에서 CodeQL에서 실행한 특정 쿼리 및 작업 세부 정보를 볼 수 있습니다.

코드 검사 빌드 모드 사용자 지정

코드 검색은 검색을 위해 파이프라인을 설정할 때 두 가지 빌드 모드를 지원합니다.

• none - CodeQL 데이터베이스는 코드베이스를 빌드하지 않고 코드베이스에서 직접 만들어집니다(해석된 모든 언어에 대해 지원되며 C# 및 Java에 추가로 지원됨).
• manual - 워크플로의 코드베이스에 사용할 빌드 단계를 정의합니다(컴파일된 모든 언어에 대해 지원됨).

각 빌드 모드의 이점에 대한 비교를 포함하여 다양한 빌드 모드에 대한 자세한 내용은 컴파일된 언어에 대한 CodeQL 코드 검사를 참조 하세요.

Azure DevOps autobuild 용 GitHub Advanced Security를 통해 코드 검사 분석을 실행하기 위해 빌드 모드는 별도의 빌드 작업 AdvancedSecurity-CodeQL-Autobuild@1입니다.

다음은 여러 언어 및 none 빌드 모드를 사용하는 유효한 구성의 예입니다.

trigger: none
 
pool:
  vmImage: windows-latest

steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language
# and build mode `none` has no impact on JavaScript analysis
    languages: 'csharp, java, javascript' 
    buildtype: 'none'

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

다음은 여러 언어 및 none 빌드 모드를 사용하는 잘못된 구성의 예입니다.

trigger: none
 
pool:
  vmImage: windows-latest

steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift
# so this pipeline definition will result in a failed run
    languages: 'csharp, swift'
    buildtype: 'none'

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

CodeQL에서 사용자 지정 쿼리 사용

기본적으로 파이프라인 설정에 지정된 사용자 지정 구성 파일이 없는 경우 CodeQL은 쿼리 팩을 security-extended 실행하여 코드를 분석합니다. 사용자 지정 CodeQL 쿼리를 활용하여 고유한 쿼리를 작성하여 특정 취약성 및 오류를 찾을 수 있습니다. 또한 CodeQL의 기본 분석을 수정하기 위해 사용자 지정 구성 파일을 만들어야 합니다.

기존 사용자 지정 쿼리를 찾거나 사용자 고유의 사용자 지정 쿼리를 제공하려면 CodeQL에 기여를 참조하세요.

사용자 지정 쿼리를 사용하여 분석

사용자 지정 쿼리로 시작하는 가장 빠른 방법은 쿼리를 작성하고 로컬 Azure DevOps 리포지토리에 저장하는 것입니다. 필요에 따라 사용자 지정 쿼리의 세부 정보를 사용자 지정할 수 있지만 적어도 규칙 ID가 있어야 합니다. 고유한 CodeQL 쿼리를 작성하는 방법에 대한 자세한 내용은 CodeQL 쿼리 작성을 참조 하세요. 여러 쿼리를 쿼리 도구 모음에 함께 묶거나 다른 사용자가 게시한 팩을 활용할 수도 있습니다. 자세한 내용은 CodeQL 팩 게시 및 사용을 참조 하세요.

사용자 지정 구성 파일 사용

사용자 지정 구성 파일은 코드에 대해 CodeQL을 분석하는 동안 실행되는 쿼리를 관리하는 방법입니다. 실행할 더 많은 쿼리 또는 쿼리 팩을 지정하고 기본 CodeQL 쿼리를 변경하거나 사용하지 않도록 설정할 수 있습니다.

포함하려는 특정 쿼리를 포함하려면 리포지토리에서 쿼리 파일(.ql)의 위치에 대한 이름과 경로를 사용하여 쿼리를 지정합니다.

포함하려는 특정 팩을 포함하려면 팩 이름을 지정합니다. 구성 파일에서 실행할 CodeQL 쿼리 팩 수를 지정할 수 있습니다.

다음 단계는 파일을 만드는 것입니다 qlpack.yml . 이 파일은 CodeQL 팩 및 해당 팩에 대한 정보를 선언합니다. 동일한 디렉터리(또는 하위 디렉터리)에 있는 qlpack.yml 모든 *.ql 파일은 패키지의 일부로 간주됩니다.

다음은 예제 구성 파일입니다.

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

사용자 지정 쿼리를 사용하는 경우 사용자 지정 쿼리의 디렉터리에 배치된 예제 qlpack.yml 는 다음과 같습니다.

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

변수에는 이 dependencies 패키지의 모든 종속성과 호환되는 버전 범위가 포함됩니다. 각 종속성은 CodeQL 라이브러리 팩으로 참조 scope/name 됩니다. 정의할 dependencies때 쿼리에서 분석할 qlpack.yml 수 있는 언어를 결정하는 핵심 언어 팩(예: JavaScript, C#, Ruby 등) 중 하나에 따라 달라집니다.

구성 파일을 사용하여 보다 구체적인 조언 및 구성 옵션은 코드 검색 또는 qlpack.yml 설치를 위한 고급 설정 사용자 지정을 참조하세요. CodeQL 팩 구조를 참조하세요.

구성 파일이 있으면 CodeQL 분석을 실행하는 파이프라인을 사용자 지정하여 새 파일을 활용해야 합니다. 구성 파일을 가리키는 샘플 파이프라인은 다음과 같습니다.

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

코드 검사 경고

Azure DevOps 코드 검색 경고에 대한 GitHub 고급 보안에는 코드 수준 애플리케이션 취약성을 경고하는 리포지토리별 코드 검색 플래그가 포함됩니다.

코드 검색을 사용하려면 먼저 Azure DevOps용 GitHub Advanced Security를 구성 해야 합니다.

Azure DevOps의 리포지토리 아래에 있는 고급 보안 탭은 코드 검색 경고를 볼 수 있는 허브입니다. 코드 검색 탭을 선택하여 검색 경고를 봅니다. 분기, 상태, 파이프라인, 규칙 유형 및 심각도별로 필터링할 수 있습니다. 현재 경고 허브는 PR 분기에서 완료된 검사에 대한 경고를 표시하지 않습니다.

파이프라인 또는 분기의 이름이 바뀌면 결과에 영향을 주지 않습니다. 새 이름이 표시되기까지 최대 24시간이 걸릴 수 있습니다.

사용자 지정 CodeQL 쿼리를 실행하도록 선택하는 경우 기본적으로 다른 쿼리 팩에서 생성된 경고에 대한 별도의 필터가 없습니다. 각 쿼리에 대해 고유한 규칙별로 필터링할 수 있습니다.

리포지토리에 대한 고급 보안을 해제하면 고급 보안 탭 및 빌드 작업의 결과에 액세스할 수 없게 됩니다. 빌드 작업이 실패하지는 않지만 고급 보안을 사용하지 않도록 설정된 상태에서 빌드의 결과가 작업과 함께 실행되며 숨겨지고 유지되지 않습니다.

경고 세부 정보

수정 지침을 포함하여 자세한 내용을 보려면 경고를 선택합니다. 각 경고에는 위치, 설명, 예제 및 심각도가 포함됩니다.

리포지토리에 대한 경고 보기

리포지토리에 대한 기여자 권한이 있는 사용자는 리포지토리 아래의 고급 보안 탭에서 리포지토리에 대한 모든 경고의 요약을 볼 수 있습니다. 코드 검색 탭을 선택하여 모든 비밀 검색 경고를 봅니다.

결과를 표시하려면 코드 검사 작업을 먼저 실행해야 합니다. 첫 번째 검사가 완료되면 검색된 취약성이 고급 보안 탭에 표시됩니다.

기본적으로 경고 페이지에는 리포지토리의 기본 분기 대한 종속성 검사 결과가 표시됩니다.

지정된 경고의 상태는 경고가 다른 분기 및 파이프라인에 있더라도 기본 분기 및 최신 실행 파이프라인의 상태를 반영합니다.

코드 검색 경고 해제

경고를 해제하려면 적절한 권한이 필요합니다. 기본적으로 프로젝트 관리자만 고급 보안 경고를 해제할 수 있습니다.

경고를 해제하려면 다음을 수행합니다.

1. 닫을 경고로 이동하고 경고에서 선택합니다.
2. 경고 닫기 드롭다운을 선택합니다.
3. 아직 선택하지 않은 경우 닫는 이유로 허용된 위험 또는 가양성을 선택합니다.
4. 메모 텍스트 상자에 선택적 주석을 추가합니다.
5. 닫기를 선택하여 경고를 제출하고 닫습니다.
6. 경고 상태가 열기에서 닫힘으로 변경되고 해고 사유가 표시됩니다.

이 작업은 선택한 분기에 대한 경고만 해제합니다. 동일한 취약성을 포함하는 다른 분기는 해제될 때까지 활성 상태로 유지됩니다. 이전에 해제된 모든 경고를 수동으로 다시 열 수 있습니다.

끌어오기 요청에 대한 코드 검사 경고 관리

끌어오기 요청의 새 코드 변경에 대한 경고가 생성되면 끌어오기 요청의 개요 탭 주석 섹션에 주석으로 보고되고 고급 보안 리포지토리 탭의 경고로 보고되며 끌어오기 요청 분기에 대한 새 분기 선택 결과가 표시됩니다.

영향을 받는 코드 줄을 찾고 요약한 내용을 확인하고 개요 섹션에서 주석을 확인할 수 있습니다.

끌어오기 요청 경고를 해제하려면 경고 세부 정보 보기로 이동하여 경고를 모두 닫고 주석을 해결해야 합니다. 그렇지 않으면 주석 상태(1)를 변경하기만 하면 주석이 해결되지만 기본 경고를 닫거나 수정하지는 않습니다.

끌어오기 요청 분기에 대한 전체 결과 집합을 보려면 Repos>고급 보안으로 이동하여 끌어오기 요청 분기를 선택합니다. 주석에서 자세한 정보 표시(2)를 선택하면 고급 보안 탭의 경고 세부 정보 보기로 이동합니다.

코드 검사 문제 해결

일반적으로 CodeQL 실행에 오류가 발생하는 경우 CodeQL CLI는 실행 중인 각 명령의 상태를 종료 코드로 보고합니다. 종료 코드는 후속 명령 또는 CodeQL CLI를 사용하는 다른 도구에 대한 정보를 제공합니다. 종료 코드 세부 정보에 대한 자세한 내용은 종료 코드를 참조 하세요.

오류: 'database finalize' CodeQL 명령(32)

이 오류는 추출 오류 또는 빌드 단계 누락으로 인해 CodeQL 데이터베이스 만들기를 완료하는 데 문제가 있음을 나타냅니다.

문제 해결 단계:

1. 코드가 존재하고 컴파일되었는지 확인
   • 컴파일된 언어의 경우 빌드 프로세스가 코드를 컴파일하고 작업 AdvancedSecurity-Codeql-Analyze 간에 AdvancedSecurity-Codeql-Init 발생하는지 확인합니다. 일반적인 빌드 명령 및 필수 플래그(예: 클린 no-cache/no-daemon)는 빌드 명령 지정에서 찾을 수 있습니다.
   • 해석된 언어의 경우 프로젝트에 지정된 언어에 대한 소스 코드가 있는지 확인합니다.
2. 추출 오류 확인
   • 추출 오류가 CodeQL 데이터베이스의 상태에 영향을 주는지 확인합니다.
   • 로그 파일에서 추출 오류 및 경고를 검토하여 전체 데이터베이스 상태를 평가합니다.
3. 압도적인 오류 조사
   • 대부분의 파일에서 추출기 오류가 발생하는 경우 추가로 조사하여 부적절한 추출의 근본 원인을 파악합니다.

오류: 자동 작성 스크립트(1)

이 오류는 자동 빌드 실패에 대해 설명하며, 코드 검색 설정 또는 구성에 문제가 있음을 시사합니다.

문제 해결 단계:

1. 빌드 단계 구성
   • AutoBuild 단계를 제거하고 대신 파이프라인에서 컴파일된 언어에 대한 특정 빌드 단계를 구성합니다.
   • Azure DevOps에 대한 GitHub 고급 보안 구성에 제공된 설정 지침을 참조하세요.

오류: 에이전트 도구 캐시에서 CodeQL 디렉터리를 찾을 수 없음

이 오류는 자체 호스팅 에이전트에 대한 CodeQL 설치와 관련된 문제를 나타냅니다.

문제 해결 단계:

1. Azure DevOps에 대한 GitHub 고급 보안 구성에 제공된 설정 지침 또는 구성 스크립트를 참조하세요.

오류: 언어 파이프라인 변수가 설정되지 않음

이 오류는 검색할 언어를 지정하는 파이프라인 변수를 설정하지 않고 CodeQL을 실행하려고 할 때 발생합니다.

문제 해결 단계:

1. 언어 파이프라인 변수 설정
   • 언어 파이프라인 변수가 올바르게 구성되었는지 확인합니다. Azure DevOps에 대한 GitHub 고급 보안 구성에 제공된 설정 지침을 참조하세요.
   • 지원되는 언어에는 csharp,, gocpp, javajavascript, pythonruby및 .swift

결과를 반환하지 않는 CodeQL

이 섹션에서는 CodeQL 분석에서 결과를 생성하지 않는 상황에 대한 지침을 제공합니다.

문제 해결 단계:

1. 검색된 취약성 확인
   • 코드에 취약성이 없을 수 있는 가능성을 고려합니다. 취약성이 예상되었지만 검색되지 않은 경우 추가 확인을 진행합니다.
2. 쿼리 도구 모음 구성 검토
   • 사용 중인 쿼리 그룹을 확인하고 필요한 경우 보다 포괄적인 제품군으로 전환하는 것이 좋습니다.
   • 또는 맞춤형 분석을 위해 사용자 지정 쿼리 도구 모음을 만들 수 있습니다.
3. 결과 보기에 대한 권한 조정
   • 적어도 기여자 수준에서 적절한 사용 권한이 분석 결과에 액세스하도록 부여되었는지 확인합니다. 자세한 내용은 고급 보안 권한을 참조 하세요.

CodeQL 시간 초과

AdvancedSecurity-Codeql-Analyze@1 작업이 표시 This job was abandoned ... we lost contact with the agent 되고 호스트된 Microsoft 에이전트를 사용하는 경우 이 작업은 유료 호스팅 에이전트에 대한 기본 제공 6시간 제한에 도달합니다. 대신 자체 호스팅 에이전트에서 분석을 실행하려고 할 수 있습니다.

코드 검사 작업 권한

코드 검사 빌드 작업은 파이프라인 ID를 사용하여 고급 보안 REST API를 호출합니다. 기본적으로 동일한 프로젝트의 파이프라인은 CodeQL 분석을 실행하여 생성된 SARIF 파일을 업로드할 수 있습니다. 이러한 권한이 빌드 서비스 계정에서 제거되거나 사용자 지정 설정(예: 리포지토리가 아닌 다른 프로젝트에서 호스트되는 파이프라인)이 있는 경우 이러한 권한을 수동으로 부여해야 합니다.

문제 해결 단계:

• 파이프라인에서 사용되는 빌드 서비스 계정에 대한 권한 Advanced Security: View alerts 부여 및 Advanced Security: Manage and dismiss alerts 권한( 프로젝트 범위 파이프라인의 경우 [Project Name] Build Service ([Organization Name])및 컬렉션 범위 파이프라인의 경우 Project Collection Build Service ([Organization Name])).

자체 호스팅 에이전트에 CodeQL 번들 수동 설치

GitHub에서 사용할 수 있는 아키텍처에 대한 설치 스크립트를 활용하여 CodeQL 번들을 에이전트 도구 캐시에 설치합니다. 이러한 스크립트를 사용하려면 환경 변수를 에이전트의 에이전트 도구 디렉터리 위치(예: )로 설정해야 $AGENT_TOOLSDIRECTORY 합니다. C:/agent/_work/_tool 또는 다음 단계를 수동으로 구현할 수 있습니다.

1. GitHub에서 최신 CodeQL 릴리스 번들을 선택합니다.
2. 일반적으로 다음 아래에 _work/_tool./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/있는 에이전트 도구 디렉터리 내의 다음 디렉터리에 번들을 다운로드하고 압축을 풉니까. 현재 릴리스를 v2.16.0사용하면 폴더 이름에 제목이 지정 ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/됩니다. 에이전트 도구 디렉터리에 대해 자세히 알아봅니다.
3. 폴더 내에 ./CodeQL/0.0.0-[codeql-release-bundle-tag] 있는 빈 파일을 만듭니다x64.complete. 이전 예제를 사용하면 파일의 끝 파일 경로가 x64.complete 여야 ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete합니다.