securego/gosecСканер безопасности Go
# gosec — проверка безопасности Go
Проверяет исходный код на наличие проблем безопасности путём сканирования AST Go
и представления кода в виде 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` мог загружать
зависимости. Задайте следующие переменные окружения в
вашем workflow:
- `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: ./...
```
### Интеграция со сканированием кода
Вы можете [интегрировать сторонние инструменты анализа кода](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning)
со сканированием кода GitHub, загружая данные в виде файлов SARIF.
В рабочем процессе показан пример запуска `gosec` в качестве шага
в рабочем процессе GitHub Actions, который выводит файл `results.sarif`.
Затем рабочий процесс загружает файл `results.sarif` в
GitHub с помощью действия `upload-sarif`.
```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` предоставляет
[`golang.org/x/tools/go/analysis.Analyzer`](https://pkg.go.dev/golang.org/x/tools/go/analysis)
для интеграции с инструментами, поддерживающими стандартный интерфейс
анализа Go, такими как фреймворк
[nogo](https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst)
от Bazel:
```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`: как минимум одна неотфильтрованная находка или ошибка обработки
- Используйте `-no-fail`, чтобы всегда возвращать `0`
## Использование
Gosec можно настроить так, чтобы он запускал только подмножество правил,
исключал определённые пути к файлам и создавал отчёты в разных
форматах. По умолчанию все правила применяются к указанным
входным файлам. Для рекурсивного сканирования из текущего каталога
можно передать `./...` в качестве входного аргумента.
### Доступные правила
gosec включает правила по следующим категориям:
- `G1xx`: общие проблемы безопасного кодирования (например, жёстко заданные
учётные данные, небезопасное использование, усиление безопасности HTTP, безопасность cookie)
- `G2xx`: риски инъекций при построении запросов/шаблонов/команд
- `G3xx`: риски обработки файлов и путей (права доступа, обход каталогов,
временные файлы, извлечение архивов)
- `G4xx`: слабости криптографии и TLS
- `G5xx`: импорты из блок-листа
- `G6xx`: специфичные для Go проверки корректности/безопасности (например,
алиасинг в range и границы срезов)
- `G7xx`: правила анализа заражения данных (taint analysis) (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 | Идентификаторы правил для исключения. `*` для всех |
#### Конфигурация правил
Некоторые правила также принимают флаги конфигурации; эти флаги
описаны в
[RULES.md](https://github.com/securego/gosec/blob/master/RULES.md).
#### Версия Go
Некоторые правила требуют определённой версии Go, которая извлекается
из файла Go-модуля, присутствующего в проекте. Если эту версию
найти не удаётся, используется версия среды выполнения Go.
Версия Go-модуля определяется с помощью команды `go list`,
что в некоторых случаях может привести к снижению производительности. В
такой ситуации версию Go-модуля можно легко указать,
задав переменную окружения
`GOSECGOVERSION=go1.21.1`.
### Зависимости
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 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:<model-id>` для любой чат-модели, размещённой в Atlas Cloud.
Atlas Cloud — это OpenAI-совместимый поставщик, доступный по адресу
[atlascloud.ai](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)
- **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 вы можете создать API-ключ, следуя
[этим инструкциям](https://ai.google.dev/gemini-api/docs/api-key)
- Для Claude получите API-ключ в
[Anthropic Console](https://console.anthropic.com/)
- Для OpenAI получите API-ключ на
[OpenAI Platform](https://platform.openai.com/api-keys)
- `ai-base-url`: (необязательно) пользовательский базовый URL для
OpenAI-совместимых API (например, Azure OpenAI, LocalAI,
Ollama)
- Atlas Cloud по умолчанию использует `https://api.atlascloud.ai/v1`,
поэтому `ai-base-url` необязателен для встроенного поставщика
`atlas`
- `GOSEC_AI_PROVIDER`: (необязательно) переменная окружения
как альтернатива `ai-api-provider`
- `GOSEC_AI_BASE_URL`: (необязательно) переменная окружения
как альтернатива `ai-base-url`
- `ai-skip-ssl`: (необязательно) пропустить проверку SSL-сертификата
для AI API (полезно для самоподписанных сертификатов)
> 🎁 **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)** — это полнофункциональная платформа AI-инференса, которая предоставляет разработчикам единый AI API для доступа к API генерации видео, генерации изображений и LLM. Вместо управления множеством интеграций с разными поставщиками вы подключаетесь один раз и получаете унифицированный доступ к более чем 300 отобранным моделям всех модальностей.
>
> Ознакомьтесь с новой акцией Atlas Cloud на тарифный план для программирования, чтобы получить более экономичный доступ к API: [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 также поддерживает директиву `//gosec:disable`,
которая работает аналогично `#nosec`:
```go
//gosec:disable G101 -- This is a false positive
```
В некоторых случаях также может потребоваться вернуться к местам, где использовались аннотации `#nosec` или `//gosec:disable`. Чтобы запустить сканер и игнорировать любые аннотации `#nosec`, можно сделать следующее:
```bash
gosec -nosec=true ./...
```
#### Требование идентификаторов правил и обоснований
Чтобы аннотации не подавляли случайно не связанные с ними
правила и не добавлялись без объяснения, gosec принимает
два необязательных флага. Оба по умолчанию имеют значение `false`, поэтому существующие
кодовые базы продолжают работать без изменений.
- `-nosec-require-rules` отклоняет «голые» директивы `#nosec` /
`//gosec:disable`, в которых не указан ни один идентификатор правила.
- `-nosec-require-justification` отклоняет директивы, которые
не содержат `-- justification` после списка правил.
Когда флаг включён, директива, не прошедшая проверку, больше не
подавляет ни одного обнаружения и выводится как ошибка в
выводе, наряду с любой основной проблемой в этой строке.
```bash
gosec -nosec-require-rules -nosec-require-justification ./...
```
Те же параметры можно задать через глобальный блок конфигурации:
```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 создаёт
[формат импорта общих проблем](https://docs.sonarqube.org/latest/analysis/generic-issue/)
для SonarQube, и отчёт должен быть импортирован в SonarQube
с помощью
`sonar.externalIssuesReportPaths=path/to/gosec-report.json`.
## Типичные сценарии использования
```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?
Это [список](https://github.com/securego/gosec/blob/master/USERS.md) некоторых пользователей gosec.
## Спонсоры
Поддержите этот проект, став спонсором. Ваш логотип будет
отображаться здесь со ссылкой на ваш сайт
<a href="https://github.com/mercedes-benz" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/2947/08b6f9da5faff0e986172b0c77fed0865a2cb26e6f8c58a8ae588c74bcf16f5f.png"></a>