Nick2bad4u/Github-Security-CodeScanning-Alerts-Skill

Gestión de Alertas de Seguridad de GitHub

Resumen

Usa esta habilidad cuando un usuario pida inspeccionar o gestionar las alertas de seguridad de un repositorio de GitHub, incluyendo:

• alertas de code scanning
• alertas de Dependabot
• alertas de malware de Dependabot
• alertas de secret scanning
• ubicaciones de alertas de secret scanning
• historial de escaneo de secretos
• resumen de configuración de seguridad del repositorio
• inspección directa de la API de seguridad de GitHub en varios repositorios
• exportación masiva de alertas para triaje fuera de línea o flujos de informes
• mutación masiva de alertas para limpieza de gran volumen

El asistente incluido es independiente del repositorio:

• apunta --repo a cualquier clon local
• detecta automáticamente owner/repo y el host de GitHub desde el remoto git
• o pasa --repository owner/repo explícitamente
• autentica mediante variable de entorno en lugar de poner un token en la línea de comandos
• opcionalmente, sobrescribe la URL base de la API o web para entornos personalizados

Compatibilidad

Requiere Python 3. Usa la API REST de GitHub directamente con un token proporcionado a través de una variable de entorno como GITHUB_TOKEN o GH_TOKEN. Soporta GitHub.com y la derivación estándar de la URL base de la API de GHES desde los remotos git, con un mecanismo de respaldo de API sin procesar para cualquier cosa que no esté cubierta.

Sugerencias de invocación

Usa repo cuando el destino sea un clon local, por defecto .. Usa los valores opcionales repository, api_base_url, web_base_url y token_env cuando la detección automática no sea suficiente. Los comandos comunes incluyen summary, export-alerts, bulk-update-alerts, repo-security-overview, list-code-scanning, show-code-scanning, update-code-scanning, list-dependabot, show-dependabot, update-dependabot, list-malware, show-malware, update-malware, list-secret-scanning, show-secret-scanning, update-secret-scanning, list-secret-locations, secret-scan-history y api-call.

Modelo de seguridad

No pegues tokens de GitHub en los argumentos de comandos. No uses --show-secret-values a menos que el usuario solicite explícitamente valores secretos sin redactar y confirme el riesgo de exposición. Prefiere metadatos de alertas redactados, ubicaciones de secretos, validez y estado de resolución. Si se requiere salida sin redactar para la corrección, no pegues material secreto en el chat, comentarios de incidencias, PRs, commits, registros o informes guardados.

Patrón preferido:

$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText

Si un repositorio usa un nombre de variable de entorno diferente, exporta esa variable primero o pasa el nombre de la variable con --token-env.

Ejemplos:

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --token-env GITHUB_TOKEN

Opciones CLI compartidas

• repo: ruta dentro del clon del repositorio de destino (por defecto .)
• repository: sobrescritura explícita opcional de owner/repo
• api_base_url: sobrescritura explícita opcional de la URL base de la API
• web_base_url: sobrescritura explícita opcional de la URL base web para enlaces renderizados
• token_env: nombre opcional de variable de entorno que contiene el token; repetible para mecanismos de respaldo
• json: bandera opcional de salida legible por máquina

Nota importante sobre alertas de malware

GitHub muestra hallazgos de malware como alertas de malware de Dependabot.

GitHub no proporciona una familia separada de alertas de repositorio con su propia superficie REST dedicada. Por lo tanto, el asistente trata el malware como un subconjunto filtrado de alertas de Dependabot y compara el GHSA de cada aviso de alerta con la Base de Datos de Avisos de GitHub para identificar avisos cuyo tipo es malware.

Eso significa:

• list-malware, show-malware y update-malware se basan en las APIs de alertas de Dependabot
• la clasificación de malware es más sólida en GitHub.com, donde el endpoint de la base de datos de avisos está disponible
• si la búsqueda del tipo de aviso no está disponible en el host de destino, el asistente informa ese estado en lugar de adivinar en silencio

Inicio rápido

1. Inspeccionar el estado de seguridad actual

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" summary --repo "."

2. Ver el resumen de configuración de seguridad del repositorio

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."

2.5 Exportar todos los conjuntos de alertas para triaje masivo

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json

3. Ejemplo de listado de code scanning

Usa las entradas compartidas repo, repository, api_base_url, web_base_url, token_env y json, además de filtros de code scanning como state, severity, tool_name, tool_guid, ref y pr. Devuelve code_scanning_alerts como texto renderizado o JSON legible por máquina.

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --severity high,error

3.5 Cerrar o reabrir alertas en masa

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Revisado y descartado intencionalmente." --limit 10 --dry-run --json

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Aceptado hasta la próxima actualización de dependencias." --limit 25 --dry-run --json

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface secret-scanning --select-state open --target-state resolved --resolution used_in_tests --limit 25 --dry-run --json

4. Descartar o reabrir una alerta de code scanning

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "Falso positivo tras revisión manual." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open

5. Ejemplo de listado de Dependabot

Usa las entradas compartidas repo, repository, api_base_url, web_base_url, token_env y json, además de filtros de Dependabot como state, severity, ecosystem, package, manifest, has, assignee y scope. Devuelve dependabot_alerts como texto renderizado o JSON legible por máquina.

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --has patch

6. Descartar o reabrir una alerta de Dependabot

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Aceptado hasta la próxima actualización trimestral." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open

7. Ejemplo de listado de malware

Usa las entradas compartidas repo, repository, api_base_url, web_base_url, token_env y json, además de filtros de malware basados en Dependabot como state, severity, ecosystem, package, manifest y has. Devuelve malware_alerts y cualquier lookup_failures de la clasificación del tipo de aviso.

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --state open

8. Ejemplo de listado de secret scanning

Usa las entradas compartidas repo, repository, api_base_url, web_base_url, token_env y json, además de filtros de secret scanning como state, secret_type, resolution, assignee, validity y banderas de fuga o multi-repositorio. Devuelve secret_scanning_alerts con valores secretos redactados por defecto.

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open

Los valores secretos están ocultos por defecto. Mantén ese valor predeterminado a menos que el usuario confirme explícitamente que la salida sin redactar de secretos es necesaria.

9. Resolver o reabrir una alerta de secret scanning

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revocado y rotado." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open

10. Mostrar ubicaciones de secretos e historial de escaneo

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "."

11. Usar el mecanismo de respaldo de API sin procesar para cualquier cosa no cubierta

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/code-scanning/default-setup

Flujo de trabajo

1. Resuelve la autenticación de forma segura.
   • Prefiere una variable de entorno como GITHUB_TOKEN.
   • Si es necesario, cárgalo desde un gestor de secretos a una variable de entorno primero.
   • Nunca imprimas el token en registros o salida del chat.
2. Resuelve el repositorio de destino.
   • Prefiere --repo y la detección automática desde el remoto git.
   • Recurre a --repository owner/repo cuando el clon local no esté disponible o no sea estándar.
3. Inspecciona los hallazgos actuales.
   • Ejecuta summary primero.
   • Usa export-alerts cuando necesites una instantánea JSON más completa de múltiples superficies para triaje masivo o informes externos.
   • Usa los comandos list/show para la familia de alertas que te interesa.
   • Usa repo-security-overview cuando la pregunta sea sobre habilitación o configuraciones de seguridad disponibles.
4. Clasifica los hallazgos.
   • Corrige defectos reales en el código o la configuración de dependencias cuando sea apropiado.
   • Descarta solo cuando tengas una justificación clara.
   • Reabre alertas cuando el descarte o resolución anterior ya no sea válido.
   • Usa bulk-update-alerts cuando un repositorio tenga docenas o cientos de alertas ya revisadas y mal clasificadas que necesiten la misma acción.
5. Aplica las mutaciones con cuidado.
   • Prefiere --dry-run primero para cambios arriesgados.
   • Añade un comentario corto y procesable de descarte o resolución.
   • Recuerda que las operaciones de escritura necesitan los permisos correspondientes de GitHub.
6. Verifica el estado posterior al cambio.
   • Vuelve a ejecutar el comando list/show pertinente.
   • Para correcciones de código o dependencias, espera al siguiente ciclo de análisis de GitHub si esperas que la alerta desaparezca naturalmente.

Recursos incluidos

Script auxiliar

scripts/manage_github_security_alerts.py es el asistente independiente del repositorio para alertas de seguridad de repositorios de GitHub.

Comandos soportados:

• summary
• export-alerts
• bulk-update-alerts
• repo-security-overview
• list-code-scanning
• show-code-scanning
• update-code-scanning
• list-dependabot
• show-dependabot
• update-dependabot
• list-malware
• show-malware
• update-malware
• list-secret-scanning
• show-secret-scanning
• update-secret-scanning
• list-secret-locations
• secret-scan-history
• api-call

Módulos de implementación:

• github_security_api.py
• github_security_cli.py
• github_security_common.py
• github_security_operations.py
• github_security_render.py

Ejemplos:

python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Revisado y descartado intencionalmente." --limit 10 --dry-run --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "Falso positivo tras revisión." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Aceptado temporalmente." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revocado y rotado." --dry-run
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
python "<ruta-al-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json