Codeql 간단 사용

💻 소개

CodeQL은 코드베이스를 관계형 데이터베이스로 변환해, SQL과 유사한 QL 쿼리로 정적 분석을 수행하도록 설계된 도구이다. 이를 통해 보안 취약점과 안티패턴을 자동으로 탐지하고 코드 품질을 개선할 수 있도록 도와준다.

또한 GitHub CI/CD 파이프라인을 통해 자동화할 수 있다.

 

---

🛠️ 설치

Codeql을 실행하기 위해서는 CLI를 설치해야한다. 다음과 같은 과정을 통해 진행하면 된다.

 

설치는 codeql-home 디렉토리를 만들어 해당 디렉토리에 설치할 예정이다. 최종적으로 다음과 같이 두개의 디렉토리가 존재하면 된다.

codeql-home
 ㄴ codeql
 ㄴ codeql-repo

 

 

1️⃣ CLI 다운로드 받기

https://github.com/github/codeql-action/releases 에서 원하는 버전 및 설치하려는 OS에 맞추어 다운로드 받으면 된다.

CLI와 쿼리를 개별 다운로드 하는 것보다 번들을 통해 한번에 다운로드 받는 것이 더 좋은 성능을 얻을 수 있다고 한다.

 

 

너무 많은 파일들이 존재해서 무엇을 다운로드 받아야할지 어렵다면 다음을 참고하자.

 

👓 OS별 구분

• 모든 플롯폼 지원 : codeql-bundle.tar.gz 또는 codeql-bundle.tar.zst
• 리눅스 : codeql-bundle-linux64.tar.gz 또는 codeql-bundle-linux64.tar.zst
• 윈도우 codeql-bundle-win64.tar.gz 또는 codeql-bundle-win64.tar.zst
• mac : codeql-bundle-osx64.tar.gz 또는 codeql-bundle-osx64.tar.zst

🕶 압축파일 확장자 구분

• 압축 해제 도구가 Zstandard 압축 알고리즘을 지원 : .tar.zst로 다운로드
• 잘 모르겠거나 Zstandard를 지원하지 않는 경우 : .tar.gz로 다운로드

공식 페이지에서는 zst로 다운받는 걸 추천한다.

 

 

2️⃣ 압축 해제 및 사용

1번을 통해서 다운로드가 완료 되면 codeql-home으로 압축파일을 이동 시킨 후 압축을 해제한다. 이때 압축 파일 내에 존재하는 codeql이 가장 밖에 나와야 한다.

 

사용 방법에는 두가지 방법이 있다.

• 설치 된 경로에 직접 이동한 후 codeql 파일을 직접 사용
• codesql 경로를 PATH에 추가하여 codeql 로 사용

 

🚗 MAC에서 PATH 등록

다음과 같이 설치경로 부분에 codesql 설치 경로를 추가해주면 된다.

echo 'export PATH="$HOME/{설치경로}/codeql:$PATH"' >> ~/.zshrc
source ~/.zshrc

 

설정이 완료 된 후 아래와 같이 명령어를 입력하여 정상적으로 설정되었는지 확인해보자.

codeql --version

 

 

3️⃣ 쿼리 다운로드

codeql-home에서 아래 명령어를 통해 저장소를 다운로드 받는다.

git clone git@github.com:github/codeql.git codeql-repo

 

---

 

📜 데이터베이스 생성

설치가 완료되면 codeql을 통해서 분석할 프로젝트에 대한 데이터베이스를 생성할 수 있다. 가장 간단하게 생성하는 방법은 아래와 같다.

codeql database create DB생성할위치 --language=언어 --source-root=대상위치

codeql database create ./codeql-db --language=javascript --source-root=./project

 

CodeQL은 먼저 코드의 구조와 의미 정보를 추출해 관계형 데이터로 변환한하는데 이를 데이터베이스 생성을 통해 진행한다. 이 데이터를 바탕으로 쿼리를 돌려 분석을하게 되는것이다..

 

자세한 내용은 아래를 참고하자.

https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis

 

---

🧐 분석

생성 된 데이터베이스를 토대로 쿼리를 실행해서 코드를 분석할 수 있다.

codeql database analyze DB위치 <쿼리,pack> --sarif-category=언어 --format=포맷 --output=결과파일

• 코드 스캐닝에 사용되는 표준 쿼리를 실행하려면 <쿼리,pack> 부분은 생략해도 된다.
• repo를 다운받으면 언어별 다양한 쿼리가 제공된다. 원하는 분석하고 싶은 쿼리를 선택해서 실행하면 된다.

 

자바스크립트 파일을 분석하는 방법은 다음의 예이다.

codeql database analyze ./codeql-db javascript-code-scanning.qls --sarif-category=javascript --format=sarif-latest --output=./result.sarif

• ./codeql-db : DB 경로 설정
• javascript-code-scanning.qls : 실행할 쿼리 suites 파일(.qls) 을 지정한다. 이 파일 안에는 여러 개의 QL 쿼리(.ql)를 묶어 둔 목록이 들어 있다. 기본적인 쿼리 리스트를 포함하고 있어 처음 분석을 시작한다면 해당 쿼리들로 시작해보는 것도 괜찮다.
• --sarif-category=javascript : 여러 데이터베이스를 분석할 때 각 데이터베이스의 카테고리를 설정할 때 사용한다. 하나만 사용하는 경우에는 옵션이다.
• --format=sarif-latest : 출력 형식을 최신 sarif 스펙을 사용한다.
• --output=./result.sarif : 결과 파일 생성위치를 정한다.

 

 

자세한 내용은 다음을 참고하자.

https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries

---

📊 결과

분석이 끝나면 설정한 경로에 sarif 확장자를 가진 파일이 생성되었을 것이다.

sarif의 결과를 보기 위해서는 뷰어를 사용할 수 있다. vscode를 사용한다면 확장 프로그램을 통해서 결과를 확인할 수 있다.