Integrando o Syhunt ao GitLab
As informações contidas neste documento se aplicam a versão 6.8.6 do Syhunt Hybrid.
Índice
Introdução
Iniciar varreduras do Syhunt a partir de um script CI YML no GitLab é simples e fácil, permitindo integrar as ferramentas de teste de segurança Syhunt Dynamic, Syhunt Code e Syhunt Mobile ao seu processo de entrega contínua e painel de segurança, agendar varreduras e mais. Você também pode configurar rastreadores de problemas no Syhunt, permitindo que vulnerabilidades sejam enviadas para a área de problemas de projetos.

O exemplo a seguir de script CI YML do Gitlab verificará o código-fonte do repositório atual, falhando o job se forem identificadas vulnerabilidades médias ou altas. Além disso, ele anexa um relatório de vulnerabilidade em PDF aos artefatos da tarefa de pipeline e adiciona as vulnerabilidades identificadas ao painel de segurança do GitLab.
syhunt_test:
script:
- Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf' -outputex 'gl-sast-report.json'
artifacts:
reports:
sast: gl-sast-report.json
paths:
- report.pdf
when: on_failure
tags:
- syhunt
Ativando o Syhunt Runner
O Syhunt Runner é um serviço de CI que receberá os comandos de varredura, executando as varreduras e comunicando os resultados da análise da segurança com o GitLab.
IMPORTANTE: Por motivos de segurança e desempenho, é recomendável que o Runner seja instalado em uma máquina virtual separada ou em uma máquina física dedicada.
- Primeiro, entre nas configurações do seu projeto GitLab e acesse as opções de CI (Continuous Integration):
- Clique em Settings (Configurações)
- Clique em CI / CD
- Expanda Runners
- Role para baixo até Set up a specific Runner manually (Configurar um Runner manualmente)
- Salve o token de registro em um local seguro. Você precisará mais tarde abaixo.
- Instale com as configurações padrão o Git for Windows, que pode ser baixado em https://gitforwindows.org/
- Instale com as configurações padrão o Syhunt Hybrid (syhunt-hybrid-7.0.15.0.exe)
- Faça o download e execute o Syhunt Runner (syhunt-runner-15.0.0.exe). Após iniciar a instalação, você será solicitado a fornecer as informações de registro do Runner.
- Cole o token de registro que você copiou no campo de texto do token e clique em Next (Avançar) para continuar e concluir a instalação.
Após concluir a instalação, retorne ao GitLab e à seção Runners em que estávamos e pressione F5 para atualizar a tela. O syhuntrunner agora deve estar registrado para este projeto. Você o verá listado em Runners activated for this project no final da página, como mostrado na imagem abaixo.

O Syhunt já está pronto para ser chamado de scripts CI YML! Veja exemplos abaixo
Adicionando o Syhunt ao seu script CI YML
Se você não possui um arquivo CI YML em seu repositório, acesse Project overview (Visão Geral do Projeto) e clique Set up CI/CD (Configurar CI/CD). Isto criará um arquivo chamado .gitlab-ci.yml no repositório.
Exemplo de SAST - O exemplo a seguir de script CI YML do Gitlab verificará o código-fonte do repositório atual, falhando o job se forem identificadas vulnerabilidades médias ou altas. Além disso, ele anexa um relatório de vulnerabilidade em PDF aos artefatos da tarefa de pipeline e adiciona as vulnerabilidades identificadas ao painel de segurança do GitLab.
syhunt_test:
stage: test
script:
- Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf' -outputex 'gl-sast-report.json'
artifacts:
reports:
sast: gl-sast-report.json
paths:
- report.pdf
when: on_failure
tags:
- syhunt
Exemplo de DAST - O exemplo a seguir de script CI YML do Gitlab verificará a aplicação web no ar depois de entrar em produção, falhando o job se forem identificadas vulnerabilidades médias ou altas. Além disso, ele anexa um relatório de vulnerabilidades em PDF aos artefatos da tarefa de pipeline e adiciona as vulnerabilidades identificadas ao painel de segurança do GitLab.
production:
stage: deploy
script:
- Start-DynamicScan -target 'www.productionurl.com' -pfcond 'fail-if:risk=mediumup' -output 'report.pdf' -outputex 'gl-dast-report.json'
artifacts:
reports:
sast: gl-dast-report.json
paths:
- report.pdf
when: on_failure
tags:
- syhunt
only:
- tags
# Exemplo de SAST - Analisar diretório / repositório local
Start-CodeScan -pfcond "medium"
# Exemplo de SAST - Analisar um repositório GIT remoto
$MyProject = @{
target = 'https://github.com/syhunt/vulnphp.git';
branch = 'main';
pfcond = 'medium';
output = 'report.pdf'
}
Start-CodeScan @MyProject
# Exemplo de DAST - Analisar um URL
$MyWebsite= @{
target = 'https://www.somewebsite.com';
pfcond = 'medium';
output = 'report.pdf'
}
Start-DynamicScan @MyWebsite
Integrando o Syhunt ao Painel de Segurança do GitLab
Syhunt gerará um arquivo de relatório de vulnerabilidade compatível com GitLab se o parâmetro outputex estiver simplesmente definido como:
- SAST: gl-sast-report.json ou qualquernome.gls.json
- DAST: gl-dast-report.json ou qualquernome.gld.json
Lembre-se de adicionar o nome do arquivo ao artifacts.reports.sast ou artifacts.reports.dast do seu arquivo CI YML file como mostrado no primeiro exemplo acima.
No momento, o GitLab adicionará apenas pipelines bem-sucedidos ao painel de segurança e às áreas de relatório de vulnerabilidade de um projeto. Isto significa que se você quiser que todas as vulnerabilidades identificadas sejam exibidas no painel, você deve omitir o parâmetro pfcond da linha de script que chama o Syhunt. Como alternativa, se você fornecer uma condição de aprovação/reprovação alta e nenhuma vulnerabilidade alta for encontrada, todas as vulnerabilidades identificadas de medium a info serão exibidas no painel.
Isto não se aplica à aba Segurança de Pipelines, a aba Segurança sempre exibirá todas as vulnerabilidades seja o status sucesso ou falha - no entanto, se o pipeline falhou devido a uma condição de aprovação/reprovação correspondente, você poderá ver o GitLab mostrar inconsistentemente 0 (zero) vulnerabilidades enquanto lista logo abaixo as vulnerabilidades identificadas. Trata-se de um bug menor não resolvido pela equipe do GitLab.
Dica importante: Se esta é a primeira varredura em uma base de código grande é recomendável analisar sua aplicação sem a integração do painel ativada para garantir que você não tenha um grande número de vulnerabilidades. Se um grande número de vulnerabilidades for encontrado, aprimore o estado de segurança da aplicação corrigindo o lote inicial de vulnerabilidades relatadas pelo Syhunt e só então ative a integração com o painel.
Start-DynamicScan - Iniciando uma varredura dinâmica
O Syhunt Dynamic deve ser iniciado através da função Start-DynamicScan(). Os seguintes parâmetros devem ser fornecidos ao chamar a função Start-DynamicScan():
- target (obrigatório) - o URL alvo a ser analisado (ex. http://www.somesite.com)
- huntmethod (opcional) - o Método de Varredura a ser usado durante a análise. Se omitido, o método padrão será usado.
- pfcond (opcional) - permite que o script falhe com o código de saída adequado se uma determinada condição for atendida. Veja abaixo uma lista das condições de aprovação / reprovação disponíveis.
- tracker (opcional) - o nome do rastreador criado anteriormente ou um rastreador gerado dinamicamente para o qual será enviado um resumo das vulnerabilidades identificadas ao final da varredura. Exemplos
- output (opcional) - permite definir um nome de arquivo de relatório (por exemplo, report.pdf ou report.html).
- outputex (opcional) - permite definir um segundo nome de arquivo de saída (por exemplo, export.json).
- verbmode (opcional) - $ false por padrão. Se alterado para true, ativa o modo detalhado, permitindo que informações de erro e informações básicas sejam adicionadas ao console.
- genrep (opcional) - $ true por padrão. Se alterado para false, o Syhunt não gerará um arquivo de relatório.
- redirIO (opcional) - $ true por padrão. Se alterado para false, informações de status em tempo-real do scanner Syhunt não serão redirecionadas para o console.
- timelimit (opcional) - define o tempo máximo da varredura (padrão: sem limite). Caso o tempo seja atingido, a varredura é cancelada. Exemplos: 1d, 3h, 2h30m, 50m
Ao usar os parâmetros output ou outputex, todos os formatos de saída suportados pelo Syhunt estão disponíveis. O relatório ou exportação será salvo no diretório de trabalho atual, a menos que seja fornecido um nome de caminho completo.
Exemplos:
# Exemplo 1 - Analisar um URL com uma única linha
Start-DynamicScan -target 'https://www.somewebsite.com' -pfcond 'fail-if:risk=mediumup'
# Exemplo 2 - Analisar um URL
$MyWebsite= @{
target = 'https://www.somewebsite.com';
pfcond = 'medium';
output = 'report.pdf'
}
Start-DynamicScan @MyWebsite
Start-CodeScan - Iniciando uma varredura de código-fonte
O Syhunt Code deve ser iniciado através da função Start-CodeScan(). Os seguintes parâmetros podem ser fornecidos ao chamar a função Start-CodeScan(), sendo todas eles opcionais:
- target - o URL de um repositório GIT ou um diretório ou arquivo de código-fonte local a ser verificado. Se o parâmetro target for omitido, o diretório de trabalho atual será verificado.
- branch - a ramificação do repositório a ser analisada. Se o parâmetro branch for omitido, o branch padrão será analisado.
- huntmethod - o Método de Varredura a ser usado durante a análise. Se omitido, o método padrão será usado.
- pfcond - permite que o script falhe com o código de saída adequado se uma determinada condição for atendida. Veja abaixo uma lista das condições de aprovação / reprovação disponíveis.
- output - permite definir um nome de arquivo de relatório (por exemplo, report.pdf ou report.html).
- outputex - permite definir um segundo nome de arquivo de saída (por exemplo, export.json).
- verbmode - $ false por padrão. Se alterado para true, ativa o modo detalhado, permitindo que informações de erro e informações básicas sejam adicionadas ao console.
- genrep - $ true por padrão. Se alterado para false, o Syhunt não gerará um arquivo de relatório.
- redirIO - $ true por padrão. Se alterado para false, informações de status em tempo-real do scanner Syhunt não serão redirecionadas para o console.
- timelimit (opcional) - define o tempo máximo da varredura (padrão: sem limite). Caso o tempo seja atingido, a varredura é cancelada. Exemplos: 1d, 3h, 2h30m, 50m
Ao usar os parâmetros output ou outputex, todos os formatos de saída suportados pelo Syhunt estão disponíveis. O relatório ou exportação será salvo no diretório de trabalho atual, a menos que seja fornecido um nome de caminho completo.
Exemplos:
# Exemplo 1 - Analisando o diretório / repositório atual
Start-CodeScan -pfcond "medium"
# Exemplo 2 - Analisando um projeto GIT remoto
Start-CodeScan -target "https://github.com/someuser/somerepo.git" -huntmethod "normal" -pfcond "medium"
# Exemplo 3 - Analisando um diretório local específico
Start-CodeScan -target "C:\www\" -huntmethod "normal" -pfcond "medium"
Condições de Aprovação / Reprovação
A seguir estão as condições de aprovação / reprovação atualmente suportadas pelo Syhunt:
high
oufail-if:risk=high
- Falha se for encontrada uma vulnerabilidade ou ameaça de alto riscomedium
oufail-if:risk=mediumup
- Falha se for encontrada uma vulnerabilidade ou ameaça de risco Médio ou Altolow
oufail-if:risk=lowup
- Falha se for encontrada uma vulnerabilidade ou ameaça de risco Baixo, Médio ou Alto
Configurações avançadas do Runner
Atualize o valor de concurrent para Runners em C:\SyhuntRunner\config.toml para permitir vários jobs simultâneos, conforme detalhado em advanced configuration details.
Integrando com o Issues do GitLab
Configurar um rastreador de problemas é uma tarefa fácil e as vulnerabilidades podem ser enviadas para um projeto específico com o clique de um botão.

Em primeiro lugar, se ainda não o fez, você precisa criar um token de acesso pessoal com permissão de API no GitLab:
- Acesse o GitLab.
- Na parte superior do canto direito, clique no seu avatar e selecione Settings (Configurações).
- No menu User Settings, selecione Access Tokens (Tokens de Acesso).
- Escolha um nome e uma data opcional de expiração para o token a ser criado.
- Escolha o escopo API.
- Clique no botão Create personal access token (Criar token pessoal de acesso).
- Guarde o seu personal access token em algum lugar seguro. Uma vez que você deixe ou atualize a página, você não será capaz de acessar o token novamente.
Finalmente, você deve adicionar um rastreador do tipo GitLab:
- Clique no ícone Issue Trackers
na barra da tela inicial. A tela de rastreadores de problemas irá abrir.
- Clique no ícone Add Tracker
na barra da tela de reastreadores e escolha a opção do menu Add tracker: GitLab (Adicionar rastreador: GitLab).
- Digite um nome de referência para o novo rastreador (como NomeDoMeuProjeto) e pressione OK. Uma janela de preferências irá abrir.
- Digite o nome do projeto no GitLab. O formato precisa ser usuario/repositorio.
- Digite o URL do servidor GitLab. Por exemplo:
https://gitlab.com/
ou URL do seu próprio servidor. - Preencha seu personal access token do GitLab e clique no botão OK.
O rastreador está pronto! Clique com o botão direito do mouse no item que você acabou de editar na lista e clique na opção Submit Test Issue (Enviar Problema de Teste). Se você configurou tudo corretamente, um problema de teste deve ser criado em https://[gitlab_server]/[owner]/[repo]/issues
. Caso contrário, você verá uma mensagem de erro indicando o que precisa ser feito.
Para obter mais detalhes sobre como enviar vulnerabilidades ao rastreador GitLab, consulte: Enviando vulnerabilidades para um rastreador.

Para documentação adicional do produto, visite syhunt.com/docs/br