Gerenciamento de Alertas de Segurança do GitHub

O que Gerenciamento de Alertas de Segurança do GitHub faz?

Visão Geral

Use esta skill quando um usuário pedir para inspecionar ou gerenciar alertas de segurança de repositórios GitHub, incluindo:

• alertas de code scanning
• alertas do Dependabot
• alertas de malware do Dependabot
• alertas de secret scanning
• locais de alertas de secret scanning
• histórico de varredura de secret scanning
• visão geral das configurações de segurança do repositório
• inspeção bruta da API de segurança do GitHub em vários repositórios
• exportação em massa de alertas para triagem offline ou fluxos de relatórios
• mutação em massa de alertas para fluxos de limpeza de alto volume

O auxiliar integrado é independente de repositório:

• aponte --repo para qualquer checkout local
• deixe-o detectar automaticamente owner/repo e o host GitHub a partir do repositório remoto
• ou passe --repository owner/repo explicitamente
• autentique-se via variável de ambiente em vez de colocar um token na linha de comando
• opcionalmente, substitua a URL base da API ou web para ambientes personalizados

Compatibilidade

Requer Python 3. Usa a API REST do GitHub diretamente com um token fornecido por meio de uma variável de ambiente como GITHUB_TOKEN ou GH_TOKEN. Suporta GitHub.com e derivação padrão da URL base da API do GHES a partir dos repositórios remotos git, com um fallback para API bruta para qualquer coisa ainda não encapsulada.

Dicas de Invocação

Use repo quando o alvo for um checkout local, padrão para .. Use valores opcionais repository, api_base_url, web_base_url e token_env quando a detecção automática não for suficiente. Comandos comuns incluem 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 e api-call.

Modelo de Segurança

Não cole tokens do GitHub em argumentos de comando. Não use --show-secret-values a menos que o usuário peça explicitamente valores secretos não editados e confirme o risco de exposição. Prefira metadados de alerta editados, locais de segredos, validade e estado de resolução. Se a saída não editada for necessária para remediação, não cole material secreto em bate-papo, comentários de issues, PRs, commits, logs ou relatórios salvos.

Padrão preferido:

$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText

Se um repositório usar um nome de variável de ambiente diferente, exporte essa variável primeiro ou passe o nome da variável com --token-env.

Exemplos:

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

Opções de CLI Compartilhadas

• repo: caminho dentro do checkout do repositório alvo (padrão .)
• repository: substituição explícita opcional de owner/repo
• api_base_url: substituição explícita opcional da URL base da API
• web_base_url: substituição explícita opcional da URL base da web para links renderizados
• token_env: nome opcional da variável de ambiente contendo o token; repetível para fallbacks
• json: sinalizador opcional de saída legível por máquina

Nota Importante sobre Alertas de Malware

O GitHub exibe descobertas de malware como alertas de malware do Dependabot.

O GitHub não fornece uma família separada de alertas de repositório com sua própria superfície REST dedicada. O auxiliar integrado trata, portanto, o malware como um subconjunto filtrado dos alertas do Dependabot e faz referência cruzada do GHSA de aviso de cada alerta com o Banco de Dados de Avisos do GitHub para identificar avisos cujo tipo é malware.

Isso significa que:

• list-malware, show-malware e update-malware são sustentados por APIs de alerta do Dependabot
• a classificação de malware é mais forte no GitHub.com, onde o endpoint do banco de dados de avisos está disponível
• se a consulta do tipo de aviso não estiver disponível no host alvo, o auxiliar relata esse estado em vez de adivinhar silenciosamente

Início Rápido

1. Inspecione o estado de segurança atual

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" summary --repo "."

2. Veja a visão geral das configurações de segurança do repositório

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."

2.5 Exporte os conjuntos completos de alertas para triagem em massa

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json

3. Exemplo de listagem de Code Scanning

Usa as entradas compartilhadas repo, repository, api_base_url, web_base_url, token_env e json, além de filtros de code scanning como state, severity, tool_name, tool_guid, ref e pr. Gera code_scanning_alerts como texto renderizado ou JSON legível por máquina.

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

3.5 Descartar ou reabrir alertas em massa

python "<caminho-para-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 "Reviewed and intentionally dismissed." --limit 10 --dry-run --json

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Accepted until the next dependency refresh." --limit 25 --dry-run --json

python "<caminho-para-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 ou reabrir um alerta de code scanning

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after manual review." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open

5. Exemplo de listagem do Dependabot

Usa as entradas compartilhadas repo, repository, api_base_url, web_base_url, token_env e json, além de filtros do Dependabot como state, severity, ecosystem, package, manifest, has, assignee e scope. Gera dependabot_alerts como texto renderizado ou JSON legível por máquina.

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

6. Descartar ou reabrir um alerta do Dependabot

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted until next quarterly upgrade." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open

7. Exemplo de listagem de malware

Usa as entradas compartilhadas repo, repository, api_base_url, web_base_url, token_env e json, além de filtros de malware baseados no Dependabot, como state, severity, ecosystem, package, manifest e has. Gera malware_alerts e quaisquer lookup_failures da classificação do tipo de aviso.

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

8. Exemplo de listagem de Secret Scanning

Usa as entradas compartilhadas repo, repository, api_base_url, web_base_url, token_env e json, além de filtros de secret scanning como state, secret_type, resolution, assignee, validity e sinalizadores de vazamento ou multi-repositório. Gera secret_scanning_alerts com valores secretos editados por padrão.

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

Os valores secretos são ocultados por padrão. Mantenha esse padrão a menos que o usuário confirme explicitamente que a saída não editada de segredos é necessária.

9. Resolver ou reabrir um alerta de Secret Scanning

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revoked and rotated." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open

10. Mostrar locais de segredos e histórico de varredura

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

11. Use o fallback da API bruta para qualquer coisa ainda não encapsulada

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

Fluxo de Trabalho

1. Resolva a autenticação de forma segura.
   • Prefira uma variável de ambiente como GITHUB_TOKEN.
   • Se necessário, carregue-a de um gerenciador de segredos para uma variável de ambiente primeiro.
   • Nunca imprima o token em logs ou na saída do chat.
2. Resolva o repositório alvo.
   • Prefira --repo e detecção automática a partir do repositório remoto git.
   • Recorra a --repository owner/repo quando o checkout local não estiver disponível ou for não padrão.
3. Inspecione as descobertas atuais.
   • Execute summary primeiro.
   • Use export-alerts quando precisar de um snapshot JSON multi-superfície mais completo para triagem em massa ou relatórios externos.
   • Use os comandos list/show para a família de alertas de seu interesse.
   • Use repo-security-overview quando a pergunta for sobre ativação ou configurações de segurança disponíveis.
4. Classifique as descobertas.
   • Corrija defeitos reais no código ou na configuração de dependências quando apropriado.
   • Descarte apenas quando tiver uma justificativa clara.
   • Reabra alertas quando o descarte ou resolução anterior não for mais válido.
   • Use bulk-update-alerts quando um repositório tiver dezenas ou centenas de alertas já revisados e mal-triados que precisam da mesma ação.
5. Aplique mutações com cuidado.
   • Prefira --dry-run primeiro para alterações arriscadas.
   • Adicione um comentário curto e acionável de descarte ou resolução.
   • Lembre-se de que operações de escrita precisam das permissões GitHub correspondentes.
6. Verifique o estado pós-alteração.
   • Execute novamente o comando list/show relevante.
   • Para correções de código ou dependência, aguarde o próximo ciclo de análise do GitHub se esperar que o alerta desapareça naturalmente.

Recursos Inclusos

Script auxiliar

scripts/manage_github_security_alerts.py é o auxiliar independente de repositório para alertas de segurança de repositórios GitHub.

Comandos suportados:

• 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 implementação:

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

Exemplos:

python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
python "<caminho-para-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 "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after review." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted temporarily." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revoked and rotated." --dry-run
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
python "<caminho-para-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json