securego/gosecVerificador de seguridad de Go
# gosec - Comprobador de seguridad para Go
Inspecciona el código fuente en busca de problemas de seguridad escaneando el AST de Go
y la representación de código SSA.
<img src="https://assets.kitploit.com/production/public/readmes/2947/83d294db3a312bcea542b6eb8261128e6f09b50a95271788fe301e164b1655b1.png" width="320">
## Enlaces rápidos
- [GitHub Action](#github-action)
- [Instalación local](#local-installation)
- [Inicio rápido](#quick-start)
- [Patrones de uso comunes](#common-usage-patterns)
- [Selección de reglas](#selecting-rules)
- [Formatos de salida](#output-formats)
## Características
- **Reglas basadas en patrones** para detectar problemas de seguridad comunes
en código Go
- **Analizadores basados en SSA** para conversiones de tipos, límites de slices
y problemas criptográficos
- **Análisis de taint** para rastrear el flujo de datos desde la entrada del usuario hasta
funciones peligrosas (inyección SQL, inyección de comandos, path
traversal, SSRF, XSS, inyección de logs, inyección SMTP, SSTI,
deserialización insegura, redirección abierta)
## Licencia
Licenciado bajo la Apache License, Version 2.0 (la "Licencia").
No puede usar este archivo excepto en cumplimiento con la Licencia.
Puede obtener una copia de la Licencia
[aquí](http://www.apache.org/licenses/LICENSE-2.0).
## Estado del proyecto
[](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)
## Instalación
### GitHub Action
Puede ejecutar `gosec` como una GitHub action de la siguiente manera:
Use la etiqueta versionada con `@master`, que está fijada a la
última versión estable. Esto proporcionará un comportamiento estable.
```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: ./...
```
#### Escaneo de proyectos con módulos privados
Si tu proyecto importa módulos Go privados, necesitas
configurar la autenticación para que `gosec` pueda obtener las
dependencias. Establece las siguientes variables de entorno en
tu flujo de trabajo:
- `GOPRIVATE`: Una lista separada por comas de prefijos de rutas de módulos
que deben considerarse privados
(por ejemplo, `github.com/your-org/*`).
- `GITHUB_AUTHENTICATION_TOKEN`: Un token de GitHub con acceso de lectura
a tus repositorios 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: ./...
```
### Integración con el escaneo de código
Puedes [integrar herramientas de análisis de código de terceros](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning)
con el escaneo de código de GitHub subiendo datos como archivos SARIF.
El flujo de trabajo muestra un ejemplo de ejecución de `gosec` como un paso
en un flujo de trabajo de GitHub Actions que genera el archivo `results.sarif`.
A continuación, el flujo de trabajo sube el archivo `results.sarif` a
GitHub usando la acción `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álisis de Go
El paquete `goanalysis` proporciona un
[`golang.org/x/tools/go/analysis.Analyzer`](https://pkg.go.dev/golang.org/x/tools/go/analysis)
para la integración con herramientas que admiten la interfaz de análisis
estándar de Go, como el framework
[nogo](https://github.com/bazelbuild/rules_go/blob/master/go/nogo.rst)
de Bazel:
```starlark
nogo(
name = "nogo",
deps = [
"@com_github_securego_gosec_v2//goanalysis",
# add more analyzers as needed
],
visibility = ["//visibility:public"],
)
```
### Instalación local
gosec requiere Go 1.25 o superior.
```bash
go install github.com/securego/gosec/v2/cmd/gosec@latest
```
## Inicio 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 salida
- `0`: el escaneo finalizó sin hallazgos/errores no suprimidos
- `1`: al menos un hallazgo no suprimido o error de procesamiento
- Use `-no-fail` para devolver siempre `0`
## Uso
Gosec se puede configurar para ejecutar solo un subconjunto de reglas, para
excluir ciertas rutas de archivos y para producir informes en diferentes
formatos. Por defecto, todas las reglas se ejecutarán contra los archivos de
entrada proporcionados. Para escanear de forma recursiva desde el directorio
actual, puede proporcionar `./...` como argumento de entrada.
### Reglas disponibles
gosec incluye reglas en estas categorías:
- `G1xx`: problemas generales de codificación segura (por ejemplo, credenciales
codificadas de forma rígida, uso inseguro, endurecimiento de HTTP, seguridad de cookies)
- `G2xx`: riesgos de inyección en la construcción de consultas/plantillas/comandos
- `G3xx`: riesgos de manejo de archivos y rutas (permisos, recorrido de rutas,
archivos temporales, extracción de archivos)
- `G4xx`: debilidades de criptografía y TLS
- `G5xx`: importaciones en lista de bloqueo
- `G6xx`: comprobaciones de corrección/seguridad específicas de Go (por ejemplo,
alias de rango y límites de slices)
- `G7xx`: reglas de análisis de contaminación (inyección SQL, inyección de
comandos, recorrido de rutas, SSRF, XSS, inyección de log, inyección de SMTP,
SSTI, deserialización insegura y redirección abierta)
Para obtener la lista completa, las descripciones de las reglas y la
configuración por regla, consulte [RULES.md](https://github.com/securego/gosec/blob/master/RULES.md).
### Reglas retiradas
- G105: Auditar el uso de math/big.Int.Exp -
[CVE corregido](https://github.com/golang/go/issues/15184)
- G307: Diferir un método que devuelve un error - causa más inconvenientes que
corregir un problema de seguridad, a pesar de los detalles de esta
[publicación de blog](https://www.joeshaw.org/dont-defer-close-on-writable-files/)
### Selección de reglas
Por defecto, gosec ejecutará todas las reglas contra las rutas de archivos
proporcionadas. Sin embargo, es posible seleccionar un subconjunto de reglas
para ejecutar mediante el flag `-include=`, o especificar un conjunto de reglas
para excluir explícitamente usando el flag `-exclude=`.
```bash
# Run a specific set of rules
$ gosec -include=G101,G203,G401 ./...
# Run everything except for rule G303
$ gosec -exclude=G303 ./...
```
### Mapeo de CWE
Cada problema detectado por `gosec` se mapea a un
[CWE (Common Weakness Enumeration)](http://cwe.mitre.org/data/index.html)
que describe en términos más genéricos la vulnerabilidad. El
mapeo exacto se puede encontrar
[aquí](https://github.com/securego/gosec/blob/master/issue/issue.go#L50).
### Configuración
Se pueden proporcionar una serie de ajustes globales en un archivo
de configuración de la siguiente manera:
```JSON
{
"global": {
"nosec": "enabled",
"audit": "enabled"
}
}
```
- `nosec`: esta configuración sobrescribirá todas las directivas `#nosec`
definidas en todo el código base
- `audit`: se ejecuta en modo auditoría, lo que habilita comprobaciones adicionales
que para el análisis de código normal podrían ser demasiado intrusivas
```bash
# Run with a global configuration file
$ gosec -conf config.json .
```
### Exclusiones de reglas basadas en rutas
Los repositorios grandes con múltiples componentes pueden necesitar diferentes
reglas de seguridad para diferentes rutas. Utilice `exclude-rules` para
suprimir reglas específicas para rutas específicas.
**Archivo de configuración:**
```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 | Descripción |
|-------|------|-------------|
| `path` | string (regex) | Regex que se compara con las rutas de archivo |
| `rules` | []string | IDs de reglas a excluir. `*` para todas |
#### Configuración de reglas
Algunas reglas también aceptan indicadores de configuración; estos indicadores están
documentados en
[RULES.md](https://github.com/securego/gosec/blob/master/RULES.md).
#### Versión de Go
Algunas reglas requieren una versión específica de Go que se obtiene
del archivo de módulo de Go presente en el proyecto. Si esta versión
no se puede encontrar, se usará como alternativa la versión del entorno de ejecución de Go.
La versión del módulo de Go se analiza mediante el comando `go list`
lo que en algunos casos puede provocar una degradación del rendimiento. En
esta situación, la versión del módulo de Go se puede proporcionar fácilmente
estableciendo la variable de entorno
`GOSECGOVERSION=go1.21.1`.
### Dependencias
gosec carga los paquetes usando módulos de Go. En la mayoría de los proyectos,
las dependencias se resuelven automáticamente durante el escaneo.
Si faltan dependencias, ejecute:
```bash
go mod tidy
go mod download
```
### Exclusión de archivos y carpetas de prueba
gosec ignorará los archivos de prueba en todos los paquetes y cualquier
dependencia en tu directorio vendor.
El escaneo de archivos de prueba se puede habilitar con el siguiente
flag:
```bash
gosec -tests ./...
```
También se pueden excluir carpetas adicionales de la siguiente manera:
```bash
gosec -exclude-dir=rules -exclude-dir=cmd ./...
```
### Exclusión de archivos generados
gosec puede ignorar archivos Go generados con el comentario de código generado predeterminado.
```
// Code generated by some generator DO NOT EDIT.
```
```bash
gosec -exclude-generated ./...
```
### Corrección automática de vulnerabilidades
gosec puede sugerir correcciones basadas en recomendaciones de IA. Llamará a una API de IA para recibir una sugerencia sobre un hallazgo de seguridad.
Puedes habilitar esta función proporcionando los siguientes argumentos de línea de comandos:
- `ai-api-provider`: el nombre del proveedor de la API de IA.
Proveedores compatibles:
- **Atlas Cloud**: `atlas` (modelo predeterminado
`deepseek-ai/deepseek-v4-flash`),
`atlas-deepseek-v4-flash`,
`atlas-qwen3-coder-next`, `atlas-kimi-k2.6`, o
`atlas:<model-id>` para cualquier modelo de chat alojado en Atlas Cloud.
Atlas Cloud es un proveedor compatible con OpenAI disponible en
[atlascloud.ai](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)
- **Gemini**: `gemini-3.1-pro-preview` (predeterminado),
`gemini-2.5-pro`, `gemini-2.5-flash`,
`gemini-2.5-flash-lite`
- **Claude**: `claude-sonnet-4-6` (predeterminado),
`claude-opus-4-7`, `claude-opus-4-6`,
`claude-sonnet-4-5`, `claude-opus-4-5`,
`claude-haiku-4-5`
- **OpenAI**: `gpt-5.4` (predeterminado), `gpt-5.4-mini`,
`gpt-5.4-nano`
- **OpenAI-compatible personalizado**: Cualquier nombre de modelo personalizado
(requiere `ai-base-url`)
- `ai-api-key` o establece la variable de entorno
`GOSEC_AI_API_KEY`: la clave para acceder a la API de IA
- Para Gemini, puedes crear una clave de API siguiendo
[estas instrucciones](https://ai.google.dev/gemini-api/docs/api-key)
- Para Claude, obtén tu clave de API desde
[Anthropic Console](https://console.anthropic.com/)
- Para OpenAI, obtén tu clave de API desde
[OpenAI Platform](https://platform.openai.com/api-keys)
- `ai-base-url`: (opcional) URL base personalizada para
APIs compatibles con OpenAI (p. ej., Azure OpenAI, LocalAI,
Ollama)
- Atlas Cloud usa `https://api.atlascloud.ai/v1` de forma predeterminada,
por lo que `ai-base-url` es opcional para el proveedor `atlas`
integrado
- `GOSEC_AI_PROVIDER`: (opcional) variable de entorno
alternativa a `ai-api-provider`
- `GOSEC_AI_BASE_URL`: (opcional) variable de entorno
alternativa a `ai-base-url`
- `ai-skip-ssl`: (opcional) omitir la verificación del certificado SSL
para la API de IA (útil para certificados autofirmados)
> 🎁 **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=gosec)** es una plataforma de inferencia de IA multimodal completa que ofrece a los desarrolladores una única API de IA para acceder a la generación de video, la generación de imágenes y las APIs de LLM. En lugar de gestionar múltiples integraciones de proveedores, te conectas una vez y obtienes acceso unificado a más de 300 modelos seleccionados en todas las modalidades.
>
> Consulta la nueva promoción del plan de programación de Atlas Cloud para obtener un acceso a la API más económico: [https://www.atlascloud.ai/console/coding-plan](https://www.atlascloud.ai/console/coding-plan)
**Ejemplos:**
```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 \
./...
```
### Anotación del código
Como con todas las herramientas de detección automatizada, habrá casos de
falsos positivos. En los casos en que gosec reporte un fallo que
haya sido verificado manualmente como seguro, es posible
anotar el código con un comentario que comience con `#nosec`.
El comentario `#nosec` debe tener el formato
`#nosec [RuleList] [-- Justification]`.
El comentario `#nosec` debe colocarse en la línea donde se
reporta la advertencia.
```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)
}
}
```
Cuando se ha identificado un falso positivo específico y se ha verificado
que es seguro, es posible que desees suprimir únicamente esa regla (o un
conjunto específico de reglas) dentro de una sección de código, mientras
continúas escaneando en busca de otros problemas. Para hacer esto, puedes listar
la(s) regla(s) a suprimir dentro de la anotación `#nosec`,
p. ej.: `/* #nosec G401 */` o `//#nosec G201 G202 G203`
Puedes incluir el texto de descripción o justificación para la
anotación. La justificación debe ir después de la(s) regla(s) a
suprimir y comenzar con dos o más guiones,
p. ej.: `//#nosec G101 G102 -- This is a false positive`
Alternativamente, gosec también admite la directiva `//gosec:disable`,
que funciona de manera similar a `#nosec`:
```go
//gosec:disable G101 -- This is a false positive
```
En algunos casos, también puede querer revisar los lugares donde se han utilizado anotaciones `#nosec` o `//gosec:disable`. Para ejecutar el escáner e ignorar cualquier anotación `#nosec`, puede hacer lo siguiente:
```bash
gosec -nosec=true ./...
```
#### Requerir IDs de reglas y justificaciones
Para evitar que las anotaciones supriman inadvertidamente reglas no relacionadas, o que se añadan sin explicación, gosec acepta dos flags opcionales. Ambos tienen el valor predeterminado `false`, por lo que las bases de código existentes siguen funcionando sin cambios.
- `-nosec-require-rules` rechaza las directivas desnudas `#nosec` / `//gosec:disable` que no enumeran ningún ID de regla.
- `-nosec-require-justification` rechaza las directivas que no llevan una `-- justification` después de la lista de reglas.
Cuando están habilitadas, una directiva que no supera la comprobación ya no suprime ningún hallazgo y se reporta como un error en la salida, junto con cualquier problema subyacente en la línea.
```bash
gosec -nosec-require-rules -nosec-require-justification ./...
```
Las mismas opciones se pueden establecer mediante el bloque de configuración global:
```json
{
"global": {
"nosec-require-rules": "enabled",
"nosec-require-justification": "enabled"
}
}
```
### Seguimiento de supresiones
Como se describió anteriormente, podríamos suprimir infracciones de forma externa
(usando `-include`/`-exclude`) o en línea (usando anotaciones `#nosec`).
Los metadatos de supresión pueden emitirse para auditoría.
Habilite el seguimiento de supresiones con `-track-suppressions`:
```bash
gosec -track-suppressions -exclude=G101 \
-fmt=sarif -out=results.sarif ./...
```
- Para las supresiones externas, gosec registra la información de supresión
donde `kind` es `external` y `justification` es
`Globally suppressed.`.
- Para las supresiones en línea, gosec registra la información de supresión
donde `kind` es `inSource` y `justification` es el texto
después de dos o más guiones en el comentario.
**Nota:** Solo los formatos SARIF y JSON admiten el seguimiento
de supresiones.
### Etiquetas de compilación
gosec puede pasar tus
[etiquetas de compilación de Go](https://pkg.go.dev/go/build/) al analizador.
Se pueden proporcionar como una lista separada por comas de la siguiente manera:
```bash
gosec -tags debug,ignore ./...
```
### Formatos de salida
gosec admite `text`, `json`, `yaml`, `csv`, `junit-xml`,
`html`, `sonarqube`, `golint` y `sarif`. De forma predeterminada,
los resultados se informarán en stdout, pero también se pueden escribir en
un archivo de salida. El formato de salida se controla mediante el flag `-fmt`,
y el archivo de salida se controla mediante el flag `-out` de la
siguiente manera:
```bash
# Write output in json format to results.json
$ gosec -fmt=json -out=results.json *.go
```
Use `-stdout` para imprimir los resultados mientras también escribe `-out`.
Use `-verbose` para anular el formato de stdout mientras se conserva el
formato del archivo.
```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:** gosec genera el
[formato de importación de problemas genéricos](https://docs.sonarqube.org/latest/analysis/generic-issue/)
para SonarQube, y se debe importar un informe en SonarQube
usando
`sonar.externalIssuesReportPaths=path/to/gosec-report.json`.
## Patrones de uso comunes
```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 ./...
```
## Desarrollo
La documentación de desarrollo se trasladó a
[DEVELOPMENT.md](https://github.com/securego/gosec/blob/master/DEVELOPMENT.md).
## ¿Quién usa gosec?
Esta es una [lista](https://github.com/securego/gosec/blob/master/USERS.md) con algunos de los usuarios de gosec.
## Patrocinadores
Apoya este proyecto convirtiéndote en patrocinador. Tu logotipo aparecerá
aquí con un enlace a tu sitio web
<a href="https://github.com/mercedes-benz" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/2947/08b6f9da5faff0e986172b0c77fed0865a2cb26e6f8c58a8ae588c74bcf16f5f.png"></a>