# gosec - Go 보안 검사기
Go AST와 SSA 코드 표현을 스캔하여 소스 코드의 보안 문제를 검사합니다.
<img src="https://assets.kitploit.com/production/public/readmes/2947/83d294db3a312bcea542b6eb8261128e6f09b50a95271788fe301e164b1655b1.png" width="320">
## 빠른 링크
- [GitHub Action](#github-action)
- [로컬 설치](#local-installation)
- [빠른 시작](#quick-start)
- [일반적인 사용 패턴](#common-usage-patterns)
- [규칙 선택](#selecting-rules)
- [출력 형식](#output-formats)
## 기능
- Go 코드에서 흔한 보안 문제를 탐지하기 위한 **패턴 기반 규칙**
- 타입 변환, 슬라이스 경계, 암호화 문제를 위한 **SSA 기반 분석기**
- 사용자 입력에서 위험한 함수로의 데이터 흐름을 추적하기 위한 **오염 분석(taint analysis)** (SQL 인젝션, 명령 인젝션, 경로 순회, SSRF, XSS, 로그 인젝션, SMTP 인젝션, SSTI, 안전하지 않은 역직렬화, 오픈 리다이렉트)
## 라이선스
Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
라이선스를 준수하지 않는 한 이 파일을 사용할 수 없습니다.
라이선스 사본은
[여기](http://www.apache.org/licenses/LICENSE-2.0)에서 확인할 수 있습니다.
## 프로젝트 상태
[](https://bestpractices.coreinfrastructure.org/projects/3218)
[](https://github.com/securego/gosec/actions?query=workflows%3ACI)
[](https://codecov.io/gh/securego/gosec)
[](https://goreportcard.com/report/github.com/securego/gosec)
[](https://pkg.go.dev/github.com/securego/gosec/v2)
[](https://securego.io/)
[](https://github.com/securego/gosec/releases)
[](https://github.com/orgs/securego/packages/container/package/gosec)
[](http://securego.slack.com)
[](https://github.com/nikolaydubina/go-recipes)
## 설치
### GitHub Action
다음과 같이 `gosec`을 GitHub action으로 실행할 수 있습니다:
최신 안정 릴리스에 고정된 `@master`와 함께 버전 태그를 사용하세요. 이렇게 하면 안정적인 동작을 제공합니다.
```yaml
name: Run Gosec
on:
push:
branches:
- master
pull_request:
branches:
- master
jobs:
tests:
runs-on: ubuntu-latest
env:
GO111MODULE: on
steps:
- name: Checkout Source
uses: actions/checkout@v3
- name: Run Gosec Security Scanner
uses: securego/gosec@master
with:
args: ./...
```
#### 비공개 모듈을 사용하는 프로젝트 스캔하기
프로젝트에서 비공개 Go 모듈을 임포트하는 경우, `gosec`이
의존성을 가져올 수 있도록 인증을 구성해야 합니다.
워크플로에서 다음 환경 변수를 설정하세요:
- `GOPRIVATE`: 비공개로 간주해야 하는 모듈 경로 접두사의
쉼표로 구분된 목록
(예: `github.com/your-org/*`).
- `GITHUB_AUTHENTICATION_TOKEN`: 비공개 저장소에 대한 읽기
권한이 있는 GitHub 토큰.
```yaml
name: Run Gosec
on:
push:
branches:
- master
pull_request:
branches:
- master
jobs:
tests:
runs-on: ubuntu-latest
env:
GO111MODULE: on
GOPRIVATE: github.com/your-org/*
GITHUB_AUTHENTICATION_TOKEN: ${{ secrets.PRIVATE_REPO_TOKEN }}
steps:
- name: Checkout Source
uses: actions/checkout@v3
- name: Run Gosec Security Scanner
uses: securego/gosec@v2
with:
args: ./...
```
### 코드 스캐닝과 통합하기
데이터를 SARIF 파일로 업로드하여 [타사 코드 분석 도구](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning)를 GitHub 코드 스캐닝과 통합할 수 있습니다.
이 워크플로는 GitHub 액션 워크플로에서 `gosec`을 단계로 실행하여 `results.sarif` 파일을 출력하는 예시를 보여줍니다. 그런 다음 워크플로는 `upload-sarif` 액션을 사용하여 `results.sarif` 파일을 GitHub에 업로드합니다.
```yaml
name: "Security Scan"
# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every at 00:00 on Sunday UTC time.
on:
push:
schedule:
- cron: '0 0 * * 0'
jobs:
tests:
runs-on: ubuntu-latest
env:
GO111MODULE: on
steps:
- name: Checkout Source
uses: actions/checkout@v3
- name: Run Gosec Security Scanner
uses: securego/gosec@v2
with:
# we let the report trigger content trigger a failure using the GitHub Security features.
args: '-no-fail -fmt sarif -out results.sarif ./...'
- name: Upload SARIF file
uses: github/codeql-action/upload-sarif@v2
with:
# Path to SARIF file relative to the root of the repository
sarif_file: results.sarif
```
### Go 분석
`goanalysis` 패키지는 표준 Go 분석 인터페이스를 지원하는 도구(예: Bazel의 [nogo](https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst) 프레임워크)와의 통합을 위한 [`golang.org/x/tools/go/analysis.Analyzer`](https://pkg.go.dev/golang.org/x/tools/go/analysis)를 제공합니다:
```starlark
nogo(
name = "nogo",
deps = [
"@com_github_securego_gosec_v2//goanalysis",
# add more analyzers as needed
],
visibility = ["//visibility:public"],
)
```
### 로컬 설치
gosec는 Go 1.25 이상이 필요합니다.
```bash
go install github.com/securego/gosec/v2/cmd/gosec@latest
```
## 빠른 시작
```bash
# Scan all packages in current module
gosec ./...
# Write JSON report
gosec -fmt json -out results.json ./...
# Write SARIF report for code scanning
gosec -fmt sarif -out results.sarif ./...
```
### 종료 코드
- `0`: 억제되지 않은 발견 사항/오류 없이 스캔 완료
- `1`: 억제되지 않은 발견 사항 또는 처리 오류가 하나 이상 존재
- 항상 `0`을 반환하려면 `-no-fail` 사용
## 사용법
Gosec은 규칙의 일부만 실행하도록 구성하거나, 특정 파일 경로를
제외하거나, 다양한 형식으로 보고서를 생성하도록 구성할 수 있습니다.
기본적으로 모든 규칙은 제공된 입력 파일에 대해 실행됩니다.
현재 디렉터리부터 재귀적으로 스캔하려면 입력 인수로 `./...`를
제공하면 됩니다.
### 사용 가능한 규칙
gosec은 다음 범주에 걸친 규칙을 포함합니다:
- `G1xx`: 일반적인 보안 코딩 문제 (예: 하드코딩된 자격 증명,
안전하지 않은 사용, HTTP 강화, 쿠키 보안)
- `G2xx`: 쿼리/템플릿/명령 구성에서의 인젝션 위험
- `G3xx`: 파일 및 경로 처리 위험 (권한, 경로 순회,
임시 파일, 아카이브 추출)
- `G4xx`: 암호화 및 TLS 취약점
- `G5xx`: 차단 목록에 포함된 임포트
- `G6xx`: Go 특유의 정확성/보안 검사 (예: range 별칭 지정 및
슬라이스 경계)
- `G7xx`: 오염 분석 규칙 (SQL 인젝션, 명령 인젝션, 경로 순회,
SSRF, XSS, 로그, SMTP 인젝션, SSTI, 안전하지 않은 역직렬화,
오픈 리다이렉트)
전체 목록, 규칙 설명 및 규칙별 구성은 [RULES.md](https://github.com/securego/gosec/blob/master/RULES.md)를
참조하세요.
### 폐기된 규칙
- G105: math/big.Int.Exp 사용 감사 -
[CVE가 수정됨](https://github.com/golang/go/issues/15184)
- G307: 오류를 반환하는 메서드 지연 호출 - 이
[블로그 게시물](https://www.joeshaw.org/dont-defer-close-on-writable-files/)의
세부 내용에도 불구하고 보안 문제를 해결하기보다 오히려 더 많은
불편을 초래함
### 규칙 선택
기본적으로 gosec은 제공된 파일 경로에 대해 모든 규칙을 실행합니다.
그러나 `-include=` 플래그를 통해 실행할 규칙의 하위 집합을
선택하거나, `-exclude=` 플래그를 사용하여 명시적으로 제외할
규칙 집합을 지정할 수 있습니다.
```bash
# Run a specific set of rules
$ gosec -include=G101,G203,G401 ./...
# Run everything except for rule G303
$ gosec -exclude=G303 ./...
```
### CWE 매핑
`gosec`에서 탐지한 모든 이슈는 취약점을 보다 일반적인 용어로 설명하는
[CWE(Common Weakness Enumeration)](http://cwe.mitre.org/data/index.html)에 매핑됩니다.
정확한 매핑은
[여기](https://github.com/securego/gosec/blob/master/issue/issue.go#L50)에서 확인할 수 있습니다.
### 구성
다음과 같이 구성 파일에서 여러 전역 설정을 제공할 수 있습니다:
```JSON
{
"global": {
"nosec": "enabled",
"audit": "enabled"
}
}
```
- `nosec`: 이 설정은 코드베이스 전체에 정의된 모든 `#nosec` 지시문을 덮어씁니다
- `audit`: 일반적인 코드 분석에는 지나치게 간섭적일 수 있는 추가 검사를 활성화하는 감사 모드로 실행합니다
```bash
# Run with a global configuration file
$ gosec -conf config.json .
```
### 경로 기반 규칙 제외
여러 구성 요소가 있는 대규모 저장소는 경로마다 다른 보안 규칙이 필요할 수 있습니다. `exclude-rules`를 사용하여 특정 경로에 대해 특정 규칙을 억제하세요.
**구성 파일:**
```json
{
"exclude-rules": [
{
"path": "cmd/.*",
"rules": ["G204", "G304"]
},
{
"path": "scripts/.*",
"rules": ["*"]
}
]
}
```
**CLI 플래그:**
```bash
# Exclude G204 and G304 from cmd/ directory
gosec --exclude-rules="cmd/.*:G204,G304" ./...
# Exclude all rules from scripts/ directory
gosec --exclude-rules="scripts/.*:*" ./...
# Multiple exclusions
gosec --exclude-rules="cmd/.*:G204,G304;test/.*:G101" ./...
```
| 필드 | 유형 | 설명 |
|-------|------|-------------|
| `path` | string (regex) | 파일 경로와 대조되는 정규식 |
| `rules` | []string | 제외할 규칙 ID. `*`는 전체를 의미 |
#### 규칙 구성
일부 규칙은 구성 플래그도 허용하며, 이러한 플래그는
[RULES.md](https://github.com/securego/gosec/blob/master/RULES.md)에
문서화되어 있습니다.
#### Go 버전
일부 규칙은 프로젝트에 존재하는 Go 모듈 파일에서
가져온 특정 Go 버전을 요구합니다. 이 버전을
찾을 수 없는 경우 Go 런타임 버전으로 대체됩니다.
Go 모듈 버전은 `go list` 명령을 사용하여 파싱되며,
경우에 따라 성능 저하를 초래할 수 있습니다. 이러한
상황에서는 환경 변수
`GOSECGOVERSION=go1.21.1`을 설정하여 Go 모듈 버전을
쉽게 제공할 수 있습니다.
### 종속성
gosec은 Go 모듈을 사용하여 패키지를 로드합니다. 대부분의 프로젝트에서
종속성은 스캔 중에 자동으로 해결됩니다.
종속성이 누락된 경우 다음을 실행하세요:
```bash
go mod tidy
go mod download
```
### 테스트 파일 및 폴더 제외
gosec은 모든 패키지의 테스트 파일과 vendor 디렉터리에 있는
모든 종속성을 무시합니다.
테스트 파일 스캔은 다음 플래그로
활성화할 수 있습니다:
```bash
gosec -tests ./...
```
다음과 같이 추가 폴더도 제외할 수 있습니다:
```bash
gosec -exclude-dir=rules -exclude-dir=cmd ./...
```
### 생성된 파일 제외
gosec는 기본 생성 코드 주석이 있는 생성된 Go 파일을 무시할 수 있습니다.
```
// Code generated by some generator DO NOT EDIT.
```
```bash
gosec -exclude-generated ./...
```
### 취약점 자동 수정
gosec은 AI 추천을 기반으로 수정 사항을 제안할 수 있습니다. 보안 발견 사항에 대한 제안을 받기 위해 AI API를 호출합니다.
다음 명령줄 인수를 제공하여 이 기능을 활성화할 수 있습니다:
- `ai-api-provider`: AI API 제공자의 이름.
지원되는 제공자:
- **Atlas Cloud**: `atlas` (기본 모델
`deepseek-ai/deepseek-v4-flash`),
`atlas-deepseek-v4-flash`,
`atlas-qwen3-coder-next`, `atlas-kimi-k2.6`, 또는
Atlas Cloud에서 호스팅되는 모든 채팅 모델의 경우
`atlas:<model-id>`.
Atlas Cloud는
[atlascloud.ai](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)에서
이용할 수 있는 OpenAI 호환 제공자입니다
- **Gemini**: `gemini-3.1-pro-preview` (기본),
`gemini-2.5-pro`, `gemini-2.5-flash`,
`gemini-2.5-flash-lite`
- **Claude**: `claude-sonnet-4-6` (기본),
`claude-opus-4-7`, `claude-opus-4-6`,
`claude-sonnet-4-5`, `claude-opus-4-5`,
`claude-haiku-4-5`
- **OpenAI**: `gpt-5.4` (기본), `gpt-5.4-mini`,
`gpt-5.4-nano`
- **사용자 정의 OpenAI 호환**: 모든 사용자 정의 모델 이름
(`ai-base-url` 필요)
- `ai-api-key` 또는 환경 변수
`GOSEC_AI_API_KEY` 설정: AI API에 접근하기 위한 키
- Gemini의 경우,
[다음 지침](https://ai.google.dev/gemini-api/docs/api-key)에 따라
API 키를 생성할 수 있습니다
- Claude의 경우,
[Anthropic Console](https://console.anthropic.com/)에서
API 키를 받으세요
- OpenAI의 경우,
[OpenAI Platform](https://platform.openai.com/api-keys)에서
API 키를 받으세요
- `ai-base-url`: (선택 사항) OpenAI 호환 API를 위한
사용자 정의 기본 URL (예: Azure OpenAI, LocalAI,
Ollama)
- Atlas Cloud는 기본적으로 `https://api.atlascloud.ai/v1`을
사용하므로, 내장된 `atlas` 제공자의 경우
`ai-base-url`은 선택 사항입니다
- `GOSEC_AI_PROVIDER`: (선택 사항) `ai-api-provider`의
대안이 되는 환경 변수
- `GOSEC_AI_BASE_URL`: (선택 사항) `ai-base-url`의
대안이 되는 환경 변수
- `ai-skip-ssl`: (선택 사항) AI API에 대한 SSL 인증서
검증 건너뛰기 (자체 서명 인증서에 유용)
> 🎁 **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)**는 개발자에게 비디오 생성, 이미지 생성, LLM API에 접근할 수 있는 단일 AI API를 제공하는 풀모달 AI 추론 플랫폼입니다. 여러 벤더 통합을 관리하는 대신, 한 번 연결하면 모든 모달리티에 걸쳐 300개 이상의 엄선된 모델에 통합 접근할 수 있습니다.
>
> 더 예산 친화적인 API 접근을 위해 Atlas Cloud의 새로운 코딩 플랜 프로모션을 확인해 보세요: [https://www.atlascloud.ai/console/coding-plan](https://www.atlascloud.ai/console/coding-plan)
**예시:**
```bash
# Using Atlas Cloud with the default DeepSeek V4 Flash model
export GOSEC_AI_API_KEY="your_key"
export GOSEC_AI_PROVIDER="atlas"
gosec ./...
# Using Atlas Cloud with an explicit hosted model
GOSEC_AI_API_KEY="your_key" \
gosec -ai-api-provider="atlas:qwen/qwen3-coder-next" ./...
# Using Gemini
gosec -ai-api-provider="gemini-3.1-pro-preview" \
-ai-api-key="your_key" ./...
# Using Claude
gosec -ai-api-provider="claude-sonnet-4-6" \
-ai-api-key="your_key" ./...
# Using OpenAI
gosec -ai-api-provider="gpt-5.4" \
-ai-api-key="your_key" ./...
# Using Azure OpenAI
gosec -ai-api-provider="gpt-5.4" \
-ai-api-key="your_azure_key" \
-ai-base-url="https://your-resource.openai.azure.com/openai/deployments/your-deployment" \
./...
# Using local Ollama with custom model
gosec -ai-api-provider="llama3.2" \
-ai-base-url="http://localhost:11434/v1" \
./...
# Using self-signed certificate API
gosec -ai-api-provider="custom-model" \
-ai-api-key="your_key" \
-ai-base-url="https://internal-api.company.com/v1" \
-ai-skip-ssl \
./...
```
### 코드에 주석 달기
모든 자동화된 탐지 도구와 마찬가지로, 오탐이 발생하는 경우가 있습니다. gosec이 보고한 실패가 수동으로 안전하다고 검증된 경우, `#nosec`으로 시작하는 주석을 사용하여 코드에 주석을 달 수 있습니다.
`#nosec` 주석은 `#nosec [RuleList] [-- Justification]` 형식이어야 합니다.
`#nosec` 주석은 경고가 보고된 줄에 배치해야 합니다.
```go
func main() {
tr := &http.Transport{
TLSClientConfig: &tls.Config{
InsecureSkipVerify: true, // #nosec G402
},
}
client := &http.Client{Transport: tr}
_, err := client.Get("https://go.dev/")
if err != nil {
fmt.Println(err)
}
}
```
특정 오탐이 식별되어 안전한 것으로 검증된 경우,
코드의 한 섹션 내에서 해당 단일 규칙(또는 특정 규칙 집합)만
억제하면서 다른 문제에 대한 스캔은 계속하고 싶을 수 있습니다. 이를 위해
`#nosec` 주석 내에 억제할 규칙을 나열할 수 있습니다.
예: `/* #nosec G401 */` 또는 `//#nosec G201 G202 G203`
주석에 대한 설명이나 정당화 텍스트를 넣을 수도 있습니다.
정당화 텍스트는 억제할 규칙 뒤에 위치해야 하며 두 개 이상의 대시로
시작해야 합니다.
예: `//#nosec G101 G102 -- This is a false positive`
또는 gosec는 `#nosec`와 유사하게 동작하는 `//gosec:disable`
지시문도 지원합니다:
```go
//gosec:disable G101 -- This is a false positive
```
경우에 따라 `#nosec` 또는 `//gosec:disable` 주석이 사용된 위치를 다시 검토하고 싶을 수도 있습니다. 스캐너를 실행하면서 모든 `#nosec` 주석을 무시하려면 다음과 같이 하면 됩니다:
```bash
gosec -nosec=true ./...
```
#### 규칙 ID 및 사유 요구
주석이 의도치 않게 관련 없는 규칙을 억제하거나 설명 없이 추가되는 것을 방지하기 위해, gosec은 두 가지 옵트인 플래그를 제공합니다. 두 플래그 모두 기본값이 `false`이므로 기존 코드베이스는 변경 없이 계속 작동합니다.
- `-nosec-require-rules`는 규칙 ID를 나열하지 않은 순수한 `#nosec` / `//gosec:disable` 지시문을 거부합니다.
- `-nosec-require-justification`은 규칙 목록 뒤에 `-- justification`을 포함하지 않은 지시문을 거부합니다.
활성화된 경우, 검사를 통과하지 못한 지시문은 더 이상 어떤 발견 사항도 억제하지 않으며, 해당 줄의 기저 문제와 함께 출력에서 오류로 보고됩니다.
```bash
gosec -nosec-require-rules -nosec-require-justification ./...
```
동일한 옵션은 전역 config 블록을 통해 설정할 수 있습니다:
```json
{
"global": {
"nosec-require-rules": "enabled",
"nosec-require-justification": "enabled"
}
}
```
### 억제 추적
위에서 설명한 대로, 위반 사항을 외부에서(`-include`/`-exclude` 사용) 또는 인라인으로(`#nosec` 주석 사용) 억제할 수 있습니다. 감사를 위해 억제 메타데이터를 출력할 수 있습니다.
`-track-suppressions`로 억제 추적을 활성화합니다:
```bash
gosec -track-suppressions -exclude=G101 \
-fmt=sarif -out=results.sarif ./...
```
- 외부 억제의 경우, gosec은 `kind`가 `external`이고 `justification`이 `Globally suppressed.`인 억제 정보를 기록합니다.
- 인라인 억제의 경우, gosec은 `kind`가 `inSource`이고 `justification`이 주석에서 두 개 이상의 대시 뒤에 오는 텍스트인 억제 정보를 기록합니다.
**참고:** SARIF 및 JSON 형식만 억제 추적을 지원합니다.
### 빌드 태그
gosec은 [Go 빌드 태그](https://pkg.go.dev/go/build/)를 분석기에 전달할 수 있습니다.
다음과 같이 쉼표로 구분된 목록으로 제공할 수 있습니다:
```bash
gosec -tags debug,ignore ./...
```
### 출력 형식
gosec은 `text`, `json`, `yaml`, `csv`, `junit-xml`,
`html`, `sonarqube`, `golint`, `sarif`를 지원합니다. 기본적으로
결과는 stdout으로 보고되지만, 출력 파일에 작성할 수도
있습니다. 출력 형식은 `-fmt` 플래그로 제어되며,
출력 파일은 다음과 같이 `-out` 플래그로 제어됩니다:
```bash
# Write output in json format to results.json
$ gosec -fmt=json -out=results.json *.go
```
`-stdout`를 사용하면 `-out`에 기록하면서 동시에 결과를 출력합니다.
`-verbose`를 사용하면 파일 형식을 유지하면서 stdout 형식을 재정의합니다.
```bash
# Write output in json format to results.json as well as stdout
$ gosec -fmt=json -out=results.json -stdout *.go
# Overrides the output format to 'text' when stdout the results,
# while writing it to results.json
$ gosec -fmt=json -out=results.json -stdout -verbose=text *.go
```
**참고:** gosec는 SonarQube용
[일반 이슈 가져오기 형식](https://docs.sonarqube.org/latest/analysis/generic-issue/)을
생성하며, 보고서는
`sonar.externalIssuesReportPaths=path/to/gosec-report.json`을
사용하여 SonarQube로 가져와야 합니다.
## 일반적인 사용 패턴
```bash
# Fail only on medium+ severity findings
gosec -severity medium ./...
# Fail only on medium+ confidence findings
gosec -confidence medium ./...
# Exclude specific rules for specific paths
gosec --exclude-rules="cmd/.*:G204,G304;scripts/.*:*" ./...
# Exclude generated files in scan
gosec -exclude-generated ./...
# Include test files in scan
gosec -tests ./...
```
## 개발
개발 문서는
[DEVELOPMENT.md](https://github.com/securego/gosec/blob/master/DEVELOPMENT.md)로 이동되었습니다.
## gosec을 사용하는 곳은 어디인가요?
gosec 사용자 일부를 정리한 [목록](https://github.com/securego/gosec/blob/master/USERS.md)입니다.
## 스폰서
스폰서가 되어 이 프로젝트를 지원해 주세요. 귀하의 로고가
웹사이트 링크와 함께 여기에 표시됩니다
<a href="https://github.com/mercedes-benz" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/2947/08b6f9da5faff0e986172b0c77fed0865a2cb26e6f8c58a8ae588c74bcf16f5f.png"></a>
