securego/gosecVerificador de segurança Go
# gosec - Verificador de Segurança para Go
Inspeciona o código-fonte em busca de problemas de segurança, analisando a AST do Go
e a representação de código SSA.
<img src="https://assets.kitploit.com/production/public/readmes/2947/83d294db3a312bcea542b6eb8261128e6f09b50a95271788fe301e164b1655b1.png" width="320">
## Links rápidos
- [GitHub Action](#github-action)
- [Instalação local](#local-installation)
- [Início rápido](#quick-start)
- [Padrões de uso comuns](#common-usage-patterns)
- [Seleção de regras](#selecting-rules)
- [Formatos de saída](#output-formats)
## Recursos
- **Regras baseadas em padrões** para detectar problemas de segurança comuns
em código Go
- **Analisadores baseados em SSA** para conversões de tipo, limites de slice
e problemas de criptografia
- **Análise de taint** para rastrear o fluxo de dados desde a entrada do usuário até
funções perigosas (injeção de SQL, injeção de comandos, path
traversal, SSRF, XSS, injeção de log, injeção de SMTP, SSTI,
desserialização insegura, open redirect)
## Licença
Licenciado sob a Apache License, Version 2.0 (a "Licença").
Você não pode usar este arquivo exceto em conformidade com a Licença.
Você pode obter uma cópia da Licença
[aqui](http://www.apache.org/licenses/LICENSE-2.0).
## Status do projeto
[](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)
## Instalação
### GitHub Action
Você pode executar o `gosec` como uma GitHub action da seguinte forma:
Use a tag versionada com `@master`, que está fixada na
última versão estável. Isso proporcionará um comportamento estável.
```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: ./...
```
#### Escaneando Projetos com Módulos Privados
Se o seu projeto importa módulos Go privados, você precisa
configurar a autenticação para que o `gosec` possa buscar as
dependências. Defina as seguintes variáveis de ambiente no
seu workflow:
- `GOPRIVATE`: Uma lista separada por vírgulas de prefixos de caminhos de módulos
que devem ser considerados privados
(por exemplo, `github.com/your-org/*`).
- `GITHUB_AUTHENTICATION_TOKEN`: Um token do GitHub com acesso
de leitura aos seus repositórios privados.
```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: ./...
```
### Integrando com a verificação de código
Você pode [integrar ferramentas de análise de código de terceiros](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning)
com a verificação de código do GitHub enviando dados como arquivos SARIF.
O workflow mostra um exemplo de execução do `gosec` como uma etapa
em um workflow de ação do GitHub que gera o arquivo `results.sarif`.
Em seguida, o workflow envia o arquivo `results.sarif` para o
GitHub usando a ação `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
```
### Análise Go
O pacote `goanalysis` fornece um
[`golang.org/x/tools/go/analysis.Analyzer`](https://pkg.go.dev/golang.org/x/tools/go/analysis)
para integração com ferramentas que suportam a interface padrão de
análise Go, como a estrutura
[nogo](https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst)
do Bazel:
```starlark
nogo(
name = "nogo",
deps = [
"@com_github_securego_gosec_v2//goanalysis",
# add more analyzers as needed
],
visibility = ["//visibility:public"],
)
```
### Instalação Local
gosec requer Go 1.25 ou mais recente.
```bash
go install github.com/securego/gosec/v2/cmd/gosec@latest
```
## Início rápido
```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 ./...
```
### Códigos de saída
- `0`: a verificação terminou sem achados/erros não suprimidos
- `1`: pelo menos um achado não suprimido ou erro de processamento
- Use `-no-fail` para sempre retornar `0`
## Uso
O Gosec pode ser configurado para executar apenas um subconjunto de regras, para
excluir determinados caminhos de arquivo e para produzir relatórios em diferentes
formatos. Por padrão, todas as regras serão executadas sobre os arquivos de
entrada fornecidos. Para verificar recursivamente a partir do diretório atual, você
pode fornecer `./...` como argumento de entrada.
### Regras disponíveis
O gosec inclui regras nas seguintes categorias:
- `G1xx`: problemas gerais de codificação segura (por exemplo, credenciais
embutidas no código, uso inseguro, endurecimento de HTTP, segurança de cookies)
- `G2xx`: riscos de injeção na construção de consultas/templates/comandos
- `G3xx`: riscos de manipulação de arquivos e caminhos (permissões, travessia de
caminhos, arquivos temporários, extração de arquivos compactados)
- `G4xx`: fraquezas de criptografia e TLS
- `G5xx`: importações em lista de bloqueio
- `G6xx`: verificações de correção/segurança específicas de Go (por exemplo,
aliasing em range e limites de slice)
- `G7xx`: regras de análise de taint (injeção de SQL, injeção de comandos,
travessia de caminhos, SSRF, XSS, log, injeção de SMTP, SSTI, desserialização
insegura e redirecionamento aberto)
Para a lista completa, descrições das regras e configuração por regra,
consulte [RULES.md](https://github.com/securego/gosec/blob/master/RULES.md).
### Regras descontinuadas
- G105: Auditar o uso de math/big.Int.Exp -
[CVE corrigida](https://github.com/golang/go/issues/15184)
- G307: Adiar um método que retorna um erro - causando
mais inconvenientes do que corrigir um problema de segurança, apesar dos
detalhes deste
[post de blog](https://www.joeshaw.org/dont-defer-close-on-writable-files/)
### Selecionando regras
Por padrão, o gosec executará todas as regras sobre os caminhos de arquivo
fornecidos. No entanto, é possível selecionar um subconjunto de regras a
executar por meio da flag `-include=`, ou especificar um conjunto de regras para
excluir explicitamente usando a flag `-exclude=`.
```bash
# Run a specific set of rules
$ gosec -include=G101,G203,G401 ./...
# Run everything except for rule G303
$ gosec -exclude=G303 ./...
```
### Mapeamento CWE
Cada problema detectado pelo `gosec` é mapeado para um
[CWE (Common Weakness Enumeration)](http://cwe.mitre.org/data/index.html)
que descreve, em termos mais genéricos, a vulnerabilidade. O
mapeamento exato pode ser encontrado
[aqui](https://github.com/securego/gosec/blob/master/issue/issue.go#L50).
### Configuração
Uma série de configurações globais pode ser fornecida em um arquivo
de configuração da seguinte forma:
```JSON
{
"global": {
"nosec": "enabled",
"audit": "enabled"
}
}
```
- `nosec`: esta configuração substituirá todas as diretivas `#nosec`
definidas em toda a base de código
- `audit`: executa em modo de auditoria, que habilita verificações adicionais
que, para a análise normal de código, poderiam ser intrusivas demais
```bash
# Run with a global configuration file
$ gosec -conf config.json .
```
### Exclusões de Regras Baseadas em Caminho
Repositórios grandes com múltiplos componentes podem precisar de regras de
segurança diferentes para caminhos diferentes. Use `exclude-rules` para
suprimir regras específicas para caminhos específicos.
**Arquivo de Configuração:**
```json
{
"exclude-rules": [
{
"path": "cmd/.*",
"rules": ["G204", "G304"]
},
{
"path": "scripts/.*",
"rules": ["*"]
}
]
}
```
**Flag de 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" ./...
```
| Campo | Tipo | Descrição |
|-------|------|-------------|
| `path` | string (regex) | Regex comparado com os caminhos dos arquivos |
| `rules` | []string | IDs de regras a excluir. `*` para todas |
#### Configuração de regras
Algumas regras também aceitam flags de configuração; essas flags estão
documentadas em
[RULES.md](https://github.com/securego/gosec/blob/master/RULES.md).
#### Versão do Go
Algumas regras exigem uma versão específica do Go, que é obtida
a partir do arquivo de módulo Go presente no projeto. Se essa versão
não for encontrada, será usado como fallback a versão do runtime do Go.
A versão do módulo Go é analisada usando o comando `go list`,
o que em alguns casos pode causar degradação de desempenho. Nessa
situação, a versão do módulo Go pode ser facilmente fornecida
definindo a variável de ambiente
`GOSECGOVERSION=go1.21.1`.
### Dependências
O gosec carrega pacotes usando módulos Go. Na maioria dos projetos,
as dependências são resolvidas automaticamente durante a verificação.
Se faltarem dependências, execute:
```bash
go mod tidy
go mod download
```
### Excluindo arquivos e pastas de teste
O gosec ignorará arquivos de teste em todos os pacotes e quaisquer
dependências no seu diretório vendor.
A verificação de arquivos de teste pode ser habilitada com a seguinte
flag:
```bash
gosec -tests ./...
```
Também pastas adicionais podem ser excluídas da seguinte forma:
```bash
gosec -exclude-dir=rules -exclude-dir=cmd ./...
```
### Excluindo arquivos gerados
O gosec pode ignorar arquivos Go gerados com o comentário de código gerado padrão.
```
// Code generated by some generator DO NOT EDIT.
```
```bash
gosec -exclude-generated ./...
```
### Correção automática de vulnerabilidades
O gosec pode sugerir correções com base em recomendações de IA. Ele
chamará uma API de IA para receber uma sugestão para um achado de segurança.
Você pode habilitar esse recurso fornecendo os seguintes argumentos
de linha de comando:
- `ai-api-provider`: o nome do provedor da API de IA.
Provedores suportados:
- **Atlas Cloud**: `atlas` (modelo padrão
`deepseek-ai/deepseek-v4-flash`),
`atlas-deepseek-v4-flash`,
`atlas-qwen3-coder-next`, `atlas-kimi-k2.6`, ou
`atlas:<model-id>` para qualquer modelo de chat hospedado no Atlas Cloud.
O Atlas Cloud é um provedor compatível com OpenAI disponível em
[atlascloud.ai](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)
- **Gemini**: `gemini-3.1-pro-preview` (padrão),
`gemini-2.5-pro`, `gemini-2.5-flash`,
`gemini-2.5-flash-lite`
- **Claude**: `claude-sonnet-4-6` (padrão),
`claude-opus-4-7`, `claude-opus-4-6`,
`claude-sonnet-4-5`, `claude-opus-4-5`,
`claude-haiku-4-5`
- **OpenAI**: `gpt-5.4` (padrão), `gpt-5.4-mini`,
`gpt-5.4-nano`
- **OpenAI-compatível personalizado**: Qualquer nome de modelo personalizado
(requer `ai-base-url`)
- `ai-api-key` ou defina a variável de ambiente
`GOSEC_AI_API_KEY`: a chave para acessar a API de IA
- Para Gemini, você pode criar uma chave de API seguindo
[estas instruções](https://ai.google.dev/gemini-api/docs/api-key)
- Para Claude, obtenha sua chave de API no
[Anthropic Console](https://console.anthropic.com/)
- Para OpenAI, obtenha sua chave de API na
[OpenAI Platform](https://platform.openai.com/api-keys)
- `ai-base-url`: (opcional) URL base personalizada para
APIs compatíveis com OpenAI (por exemplo, Azure OpenAI, LocalAI,
Ollama)
- O Atlas Cloud usa `https://api.atlascloud.ai/v1` por padrão,
portanto `ai-base-url` é opcional para o provedor `atlas`
integrado
- `GOSEC_AI_PROVIDER`: (opcional) variável de ambiente
alternativa a `ai-api-provider`
- `GOSEC_AI_BASE_URL`: (opcional) variável de ambiente
alternativa a `ai-base-url`
- `ai-skip-ssl`: (opcional) ignora a verificação do certificado SSL
para a API de IA (útil para certificados autoassinados)
> 🎁 **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)** é uma plataforma de inferência de IA multimodal completa que oferece aos desenvolvedores uma única API de IA para acessar APIs de geração de vídeo, geração de imagens e LLM. Em vez de gerenciar múltiplas integrações de fornecedores, você se conecta uma vez e obtém acesso unificado a mais de 300 modelos selecionados em todas as modalidades.
>
> Confira a nova promoção do plano de codificação do Atlas Cloud para um acesso à API mais econômico: [https://www.atlascloud.ai/console/coding-plan](https://www.atlascloud.ai/console/coding-plan)
**Exemplos:**
```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 \
./...
```
### Anotando código
Como acontece com todas as ferramentas de detecção automatizada, haverá casos de
falsos positivos. Nos casos em que o gosec reporta uma falha que
foi verificada manualmente como sendo segura, é possível
anotar o código com um comentário que começa com `#nosec`.
O comentário `#nosec` deve ter o formato
`#nosec [RuleList] [-- Justification]`.
O comentário `#nosec` precisa ser colocado na linha onde o
aviso é reportado.
```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)
}
}
```
Quando um falso positivo específico tiver sido identificado e verificado
como seguro, você pode querer suprimir apenas essa única regra (ou um
conjunto específico de regras) dentro de uma seção de código, enquanto
continua a procurar por outros problemas. Para fazer isso, você pode listar
a(s) regra(s) a serem suprimidas dentro da anotação `#nosec`,
ex.: `/* #nosec G401 */` ou `//#nosec G201 G202 G203`
Você pode colocar o texto de descrição ou justificativa para a
anotação. A justificativa deve vir após a(s) regra(s) a
suprimir e começar com dois ou mais hífens,
ex.: `//#nosec G101 G102 -- This is a false positive`
Alternativamente, o gosec também suporta a diretiva `//gosec:disable`,
que funciona de forma semelhante ao `#nosec`:
```go
//gosec:disable G101 -- This is a false positive
```
Em alguns casos, você também pode querer revisitar locais onde
anotações `#nosec` ou `//gosec:disable` foram usadas. Para
executar o scanner e ignorar quaisquer anotações `#nosec`, você pode fazer
o seguinte:
```bash
gosec -nosec=true ./...
```
#### Exigir IDs de regra e justificativas
Para evitar que as anotações suprimam inadvertidamente regras não relacionadas, ou que sejam adicionadas sem explicação, o gosec aceita duas flags opcionais. Ambas têm como padrão `false`, portanto os codebases existentes continuam funcionando sem alterações.
- `-nosec-require-rules` rejeita diretivas `#nosec` / `//gosec:disable` sem nenhuma regra listada.
- `-nosec-require-justification` rejeita diretivas que não contenham um `-- justification` após a lista de regras.
Quando habilitada, uma diretiva que falha na verificação deixa de suprimir qualquer achado e é reportada como erro na saída, juntamente com qualquer problema subjacente na linha.
```bash
gosec -nosec-require-rules -nosec-require-justification ./...
```
As mesmas opções podem ser definidas através do bloco de configuração global:
```json
{
"global": {
"nosec-require-rules": "enabled",
"nosec-require-justification": "enabled"
}
}
```
### Rastreamento de supressões
Conforme descrito acima, podemos suprimir violações externamente
(usando `-include`/`-exclude`) ou inline (usando anotações `#nosec`).
Os metadados de supressão podem ser emitidos para auditoria.
Ative o rastreamento de supressões com `-track-suppressions`:
```bash
gosec -track-suppressions -exclude=G101 \
-fmt=sarif -out=results.sarif ./...
```
- Para supressões externas, o gosec registra informações de supressão
onde `kind` é `external` e `justification` é
`Globally suppressed.`.
- Para supressões inline, o gosec registra informações de supressão
onde `kind` é `inSource` e `justification` é o texto
após dois ou mais travessões no comentário.
**Nota:** Apenas os formatos SARIF e JSON suportam o rastreamento
de supressões.
### Build tags
O gosec é capaz de passar suas
[Go build tags](https://pkg.go.dev/go/build/) para o analisador.
Elas podem ser fornecidas como uma lista separada por vírgulas da seguinte forma:
```bash
gosec -tags debug,ignore ./...
```
### Formatos de saída
gosec suporta `text`, `json`, `yaml`, `csv`, `junit-xml`,
`html`, `sonarqube`, `golint` e `sarif`. Por padrão,
os resultados serão reportados para stdout, mas também podem ser gravados em
um arquivo de saída. O formato de saída é controlado pela flag `-fmt`,
e o arquivo de saída é controlado pela flag `-out` da
seguinte forma:
```bash
# Write output in json format to results.json
$ gosec -fmt=json -out=results.json *.go
```
Use `-stdout` para imprimir os resultados enquanto também grava em `-out`.
Use `-verbose` para substituir o formato de stdout preservando o
formato do arquivo.
```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
```
**Nota:** o gosec gera o
[formato de importação de problemas genéricos](https://docs.sonarqube.org/latest/analysis/generic-issue/)
para o SonarQube, e um relatório precisa ser importado no SonarQube
usando
`sonar.externalIssuesReportPaths=path/to/gosec-report.json`.
## Padrões de uso comuns
```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 ./...
```
## Desenvolvimento
A documentação de desenvolvimento foi movida para
[DEVELOPMENT.md](https://github.com/securego/gosec/blob/master/DEVELOPMENT.md).
## Quem usa o gosec?
Esta é uma [lista](https://github.com/securego/gosec/blob/master/USERS.md) com alguns dos usuários do gosec.
## Patrocinadores
Apoie este projeto tornando-se um patrocinador. Seu logotipo
aparecerá aqui com um link para o seu site
<a href="https://github.com/mercedes-benz" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/2947/08b6f9da5faff0e986172b0c77fed0865a2cb26e6f8c58a8ae588c74bcf16f5f.png"></a>