Blog de Amazon Web Services (AWS)
Revise la seguridad de su repositorio con ASH
Por Alex García, Delivery Consultant de DevOps en AWS Professional Services y Nicolás Santisteban, Delivery Consultant de DevOps en AWS.
Automated Security Helper (ASH) es una herramienta de código abierto de AWS que analiza código fuente de aplicaciones, infraestructura como código, secretos y dependencias en busca de amenazas, patrones inseguros y vulnerabilidades. Con la CLI de ASH se obtiene un reporte con los resultados de un repositorio, sin instalar ni ejecutar varias herramientas de seguridad por separado. ASH puede usarse en el ambiente de desarrollo de cada persona, como un pre-commit hook o como etapa de un pipeline.
El siguiente diagrama resume el recorrido completo, desde su repositorio hasta la decisión del pipeline.
Figura 1: cómo funciona ASH.
ASH recibe el repositorio, lo analiza en modo contenedor con diez escáneres y entrega los reportes junto con un código de salida: 0 si no hay hallazgos accionables y 2 si los hay. Un pipeline continúa cuando el código es 0 y se detiene con cualquier otro valor. También conviene revisar que ningún escáner quede en estado MISSING, SKIPPED o ERROR.
Qué analiza ASH
ASH reúne diez escáneres de seguridad para revisar los siguientes elementos de un repositorio.
| Qué revisa | Escáneres |
|---|---|
| Código de aplicación | Bandit, Semgrep, Opengrep |
| Infraestructura como código (IaC) | Checkov, cfn-nag, cdk-nag |
| Secretos, como contraseñas o llaves escritas en el código | detect-secrets |
| Dependencias, es decir, las librerías que usan las aplicaciones | Grype, npm audit |
| Inventario de software (Software Bill of Materials, SBOM) | Syft |
ASH tiene tres modos de ejecución. El modo local usa las herramientas instaladas en el ambiente de desarrollo; ASH incluye por defecto Bandit, Checkov y Semgrep, y las demás se instalan por separado. El modo contenedor usa una imagen de contenedor que incluye las diez herramientas completas. El modo precommit ejecuta un subconjunto rápido previo a un commit. Los siguientes pasos usan el modo contenedor, pues evita instalar cada herramienta por separado.
Requisitos previos
- El manejador de paquetes uv, para instalar ASH.
- Un runtime de contenedores compatible, como Finch, Podman o Docker, con unos 4 GB libres para construir la imagen de ASH.
- Git, como herramienta de control de versiones.
- Windows Subsystem for Linux 2 (WSL2), si se trabaja con un equipo con Windows.
- jq, si quiere analizar la salida de los hallazgos de ASH de forma programática.
- Una terminal de comandos para poder acceder a su repositorio y ejecutar ASH.
Paso 1: Instalar ASH
Ejecute en una terminal los siguientes comandos de uv y de la CLI de ASH para instalar la versión 3.7.1 de ASH:
uv tool install git+https://github.com/awslabs/automated-security-helper.git@v3.7.1
ash --version
La salida debe mostrar awslabs/automated-security-helper v3.7.1. Si la salida es que no se encuentra el comando ash, ejecute uv tool update-shell y abra una terminal nueva para actualizar el PATH.
Paso 2: Realizar el primer escaneo de seguridad
En una terminal, ejecute los siguientes comandos de ASH para construir una vez la imagen y luego escanear el repositorio en modo contenedor; cambie mi-proyecto por el nombre de su carpeta:
ash build-image --no-run
ash --mode container --no-build --source-dir ./mi-proyecto --output-dir /tmp/ash/mi-proyecto
ASH usa el primer runtime de contenedores que encuentra instalado (Finch, Docker, nerdctl o Podman). Para usar uno en particular, se debe añadir el parámetro --oci-runner, por ejemplo --oci-runner podman.
Construir por primera vez la imagen toma varios minutos. Con el parámetro --no-run también se evita el escaneo de la carpeta desde la que se ejecuta.
Si al finalizar se genera un mensaje similar a ERROR Container execution failed with code 2, no es una falla de ASH: el escaneo terminó y detectó hallazgos, es decir, posibles problemas de seguridad que se deben revisar. En un pipeline, ese mismo código es el que detiene el flujo.
Paso 3: Consultar los resultados de los hallazgos
ASH guarda varios reportes en la carpeta que indique con --output-dir (en este ejemplo, /tmp/ash/mi-proyecto); si omite el parámetro, la carpeta por defecto es .ash/ash_output. Cada formato tiene un objetivo específico.
| Archivo | Reporter | Formato | Para qué sirve |
|---|---|---|---|
ash.summary.txt |
Text | Texto plano | Resumen ligero para consola/logs. |
ash.summary.md |
Markdown | Markdown | Resumen legible para documentación, comentarios de PR o README. |
ash.html |
HTML | HTML | Reporte interactivo en el navegador: búsqueda, filtros y detalle de cada hallazgo. |
ash.csv |
CSV | CSV | Datos tabulares (escáner, archivo, línea, severidad, regla, estado de supresión) para Excel/Sheets o dashboards. |
ash.flat.json |
Flat JSON | JSON | Estructura plana y simple de parsear para scripts e integraciones personalizadas. |
ash.sarif |
SARIF | JSON (SARIF) | Static Analysis Results Interchange Format, el formato estándar de interoperabilidad. |
ash.ghas.sarif |
GitHub GHAS | SARIF | SARIF optimizado para GitHub Advanced Security (Code Scanning). |
ash.gl-sast-report.json |
GitLab SAST | JSON | Reporte en el formato del Security Dashboard de GitLab para integrarlo como artefacto sast del pipeline. |
ash.gl-dependency-scanning-report.cdx.json |
GitLab CycloneDX | JSON (CycloneDX) | El mismo SBOM, pero nombrado como artefacto dependency_scanning de GitLab para su vista de dependencias. |
ash.cdx.json |
CycloneDX | JSON (CycloneDX) | SBOM (inventario de software): componentes, dependencias, licencias y mapeo de vulnerabilidades. |
ash.ocsf.json |
OCSF | JSON (OCSF) | Hallazgos en el esquema Open Cybersecurity Schema Framework, para data lakes de seguridad, SIEM y analítica. |
ash.junit.xml |
JUnit XML | XML | Resultados estilo pruebas (pass/fail por escáner) para motores de integración y entrega continuas (CI/CD), GitLab CI, GitHub Actions y gates de pipeline. |
ash.unused-suppressions.json |
Unused Suppressions | JSON | Lista las reglas de supresión que no coincidieron con ningún hallazgo (higiene de supresiones), para procesar automáticamente. |
ash.unused-suppressions.md |
Unused Suppressions | Markdown | La misma información de supresiones sin usar, pero en formato legible para revisión humana. |
Este es un extracto de ejemplo del resumen que genera ASH al escanear en modo contenedor un repositorio con código de aplicación, plantillas de AWS CloudFormation y dependencias. Muestra 5 de los 10 escáneres y 4 de las columnas del reporte:
Scanner Actionable Result Threshold
--------------- ---------- -------- ---------------
bandit 2 FAILED MEDIUM (global)
cfn-nag 10 FAILED MEDIUM (global)
checkov 33 FAILED MEDIUM (global)
grype 0 PASSED MEDIUM (global)
npm-audit 0 PASSED MEDIUM (global)
El estado final de cada escáner corresponde a una de las siguientes opciones.
| Estado | Qué significa |
|---|---|
| PASSED | No encontró hallazgos de severidad MEDIUM o mayor, el umbral predeterminado y es el resultado esperado. |
| FAILED | Encontró hallazgos de severidad MEDIUM o mayor. |
| MISSING | No se ejecutó porque faltan las herramientas. |
| SKIPPED | Se desactivó o se excluyó del escaneo. |
| ERROR | Falló al ejecutarse. |
Por ejemplo, al abrir el archivo ash.html, se puede seleccionar un hallazgo y muestra el nombre del archivo y la línea con el hallazgo, la idea es hacer el ajuste y repetir el escaneo.
Opcional: Implementar ASH a un pre-commit hook o a un pipeline de CI/CD
Para revisar el escaneo antes de cada commit, ASH ofrece un hook para la herramienta pre-commit, llamado ash-simple-scan; la configuración está en la sección Using ASH with pre-commit del repositorio de ASH.
Cualquier pipeline CI/CD puede ejecutar ASH como etapa con el comando indicado en el paso 2. Para incorporarlo a un pipeline se deben considerar los siguientes puntos al hacerlo por ejemplo en AWS CodeBuild:
- Si el código de salida es distinto a 0, se debe detener el pipeline, pues se encontró algún hallazgo o hubo un error.
- Conservar los reportes como artefactos del pipeline; quien revise un cambio podrá ver los hallazgos sin repetir el escaneo, lo cual es útil para equipos de desarrollo a fin de que puedan revisar localmente el código y realizar las soluciones.
Habilite el modo privilegiado del proyecto para usar contenedores en AWS CodeBuild.
A nivel organizativo, para una adopción gradual, se recomienda iniciar la implementación de ASH en el ambiente de desarrollo de cada integrante del equipo para detectar los hallazgos; después, implementarlo en los pipelines CI/CD.
Limpieza
ASH se puede desinstalar ejecutando el comando uv tool uninstall automated-security-helper.
Conclusión
Con un solo comando, ASH incluye múltiples utilidades de seguridad que revisan código de desarrollo, infraestructura como código, secretos y dependencias, y reúne los resultados en múltiples reportes.
El siguiente paso es ejecutar ASH en uno de sus repositorios y comenzar por el primer hallazgo. Consulte la documentación de ASH para configurar umbrales, supresiones y otros escáneres.
Autores
 |
Alex García es Delivery Consultant de DevOps en AWS Professional Services, con base en México. Ayuda a organizaciones de Latinoamérica a automatizar la entrega de software y la operación de sus plataformas en AWS, con experiencia en CI/CD, infraestructura como código, DevSecOps, modernización de aplicaciones y plataformas de IA generativa. LinkedIn |
 |
Nicolás Santisteban es Delivery Consultant de DevOps en AWS Professional Services ubicado en Bogotá, Colombia. Apoya y acompaña a las organizaciones en la automatización y mejoramiento del ciclo de vida del desarrollo del software (SDLC), la optimización de la nube en AWS y el mejoramiento de la observabilidad. Cuenta con experiencia en CI/CD, IaC, observabilidad, DevSecOps, Platform Engineering e inteligencia artificial generativa. LinkedIn |