Open Source SAST com Horusec

Horusec é uma ferramenta de Análise Estática de Segurança de Aplicações (SAST) que auxilia no processo de desenvolvimento seguro de software. Projeto todo conduzido e mantido pelo pessoal da ZupIT.

Desenvolvido com o objetivo de identificar vulnerabilidades em código-fonte de forma automatizada, o Horusec se destaca por sua eficiência e integração com diversas tecnologias.

Além disso, a documentação oficial do Horusec é abrangente e detalhada, fornecendo guias passo a passo para instalação, configuração e uso da ferramenta. Há também tutoriais e exemplos práticos que ajudam os usuários a entender melhor como tirar proveito das funcionalidades oferecidas.

Visão Geral | Horusec

Principais Funcionalidades

Análise de Código: O Horusec realiza uma análise detalhada do código-fonte, identificando possíveis vulnerabilidades que podem comprometer a segurança da aplicação.
Integração Contínua: A ferramenta pode ser facilmente integrada em pipelines de integração contínua (CI/CD), permitindo que as análises de segurança sejam executadas automaticamente a cada nova atualização de código.
Relatórios Detalhados: Após a análise, o Horusec gera relatórios detalhados com todas as vulnerabilidades encontradas, nos formatos Sarif, Json, Texto ou para integração com Sonarqube, categorizando-as por nível de severidade e sugerindo possíveis correções.
Suporte a Múltiplas Linguagens: A ferramenta suporta uma ampla variedade de linguagens de programação e frameworks, tornando-a versátil para diferentes tipos de projetos.
Plataforma Web: As aplicações web do Horusec são uma extensão das funcionalidades da CLI para gerenciar as vulnerabilidades encontradas e, assim, realizar a classificação delas.

Benefícios do Uso do Horusec

Horusec tem sido amplamente adotado por equipes de desenvolvimento que buscam incorporar práticas de segurança em seu fluxo de trabalho. Aqui estão alguns exemplos de como a ferramenta pode ser utilizada:

Durante o Desenvolvimento: Desenvolvedores podem executar análises de segurança a qualquer momento do ciclo de desenvolvimento, identificando vulnerabilidades antes de enviar o código para o repositório compartilhado.
Em Pipelines de CI/CD: Integrar Horusec em pipelines de CI/CD garante que cada nova versão do software seja analisada quanto a vulnerabilidades, evitando que código inseguro chegue à produção.
Auditorias de Segurança: Equipes de segurança podem usar Horusec para realizar auditorias periódicas no código-fonte, identificando e corrigindo vulnerabilidades que possam ter sido introduzidas ao longo do tempo.

Casos de uso

Abordaremos alguns casos de uso mais comuns, lembrando que o objetivo destes tutoriais é para o uso local de desenvolvedores e em pipelines simples em Github Actions. Cenários mais complexos serão trazido mais adiante.

Nos laboratórios abaixo, utilizaremos os seguintes recursos:

Sistemas operacionais Windows, Linux e MacOS;
Docker Desktop para uso de containers;
Microsoft VsCode para visualização de códigos fontes;
Pyhton 3 para scripts auxiliares;
Código fonte de alguma aplicações para análise. Utilizaremos as seguintes:
- VamPI (Python) | erev0s
- VulnerableLightApp (.NET) | Michaël Vacarella

Horusec VsCode IDE Plugin

O plugin do Horusec pode ser encontrado na loja de extensões do VsCode. Apesar de há muito sem atualizações, tudo ainda funciona muito bem.

Procure pelo Horusec no Marketplace de plugins do VsCode.

Uma vez instalado, abra a pasta do seu projeto e execute o scan.

Análise no projeto em Python VamPI.

Análise no projeto em .NET VulnerableLightApp.

Instalação dos binários (Windows, Linux e Mac)

Para o uso com Docker, para as versões mais atuais do Docker Desktop é necessária a utilização da versão 2.9.0-beta.3.

Windows

Realize o download do binário do acessando o repositório no Github ou baixe via linha de comando.

Nos exemplos abaixo o teste é realizado em ambiente Windows, o que não muda nada para as demais arquiteturas.

#x64
curl "https://github.com/ZupIT/horusec/releases/download/v2.9.0-beta.3/horusec_windows_amd64.exe" -o "./horusec.exe"


#arm64
curl "https://github.com/ZupIT/horusec/releases/download/v2.9.0-beta.3/horusec_windows_arm64.exe" -o "./horusec.exe"

Linux e Mac

#Linux x64
wget https://github.com/ZupIT/horusec/releases/download/v2.9.0-beta.3/horusec_mac_amd64 -O horusec ; \
chmod +x horusec

#Mac M1/M2
wget https://github.com/ZupIT/horusec/releases/download/v2.9.0-beta.3/horusec_mac_arm64 -O -O horusec ; \
chmod +x horusec

Se preferir, mova os arquivos em seguida para a pasta de binários:

sudo mv horusec /usr/local/bin/

Horusec CLI sem Docker (Binário)

O Horusec foi muitas possibilidades de configuração, caso queira gerar um arquivo com todas as possibilidades de condifuração, execute com a opção generate.

.\horusec.exe generate

O arquivo horusec-config.json será gerado, como o abaixo.

Horusec CLI com Docker (Binário)

Nada muda muito do exemplo acima (sem Docker), com excessão da permanência padrão da opção de uso de todos os recursos dependentes do Docker.

horusec start -G -o="sarif" -O="horusec_report.sarif" -p="vulnerable_apps/VulnerableLightApp"

Comparação entre o uso sem e com o Docker.

Utilizando as outras engines solicitadas via Docker, foram encontradas 13 vulnerabilidades, enquanto com as engines padrões apenas 3. As engines default do Horusec são as seguintes:

horusec-csharp
horusec-kotlin
horusec-java
horusec-kubernetes
horusec-leaks
horusec-javascript
horusec-dart
horusec-nginx

Na página de documentação deles é possível visualizar a lista das ferramentas auxiliares, linguagens cobertas e suas versões.

Horusec Docker

Para começar, entre no diretório do projeto a ser analisado e execute o seguinte comando:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
        -v $(pwd):/src/horusec \
        horuszup/horusec-cli:v2.9.0-beta.3 horusec start -p /src/horusec -P $(pwd)

Você pode encorpar seu script com diversas variáveis, isso será muito útil para a as integrações nas pipelines. Copie e cole o script abaixo em seu terminal caso esteja em ambiente Linux ou Mac:

#CRIA PASTA DE RELATÓRIO
mkdir reports; \

#CONFIGURAÇÃO DE PARÂMETROS DO HORUSEC
#image="0xtiago/horusec-cli"; \
image="horuszup/horusec-cli:v2.9.0-beta.3"; \
severity_exception="LOW,UNKNOWN,INFO"; \
report_type="json"; \
report_directory="reports" ;\
report_file="horusec_report.json" ;\
ignore="**/tmp/**,
	      **/.vscode/**,\
				**/.venv/**, \
				**/.env/**, \
				**/tests/**, \
				**/test/**, \
				**/test/, \
				**/*.Tests/**, \
				**/*.Test/**, \
				**/test_*, \
				**/appsettings.*.json, \
				**/bin/Debug/*/appsettings.*.json, \
				**/*.yml, \
				**/bin/Debug/*/appsettings.json, \
				**/*.sarif" ;\


# EXECUTA CONTAINER DO HORUSEC REMOVENDO-O AO FIM DA EXECUÇÃO
docker pull $image ;\
docker run --rm \
	-v /var/run/docker.sock:/var/run/docker.sock \
	-v $(pwd):/src/horusec $image horusec start \
	-p /src/horusec -P $(pwd) \
	-o="$report_type" \
	-O="/src/horusec/$report_directory/$report_file" \
	-s=$severity_exception \
	--ignore=$ignore \
	--information-severity=true

Em Mac ou Linux, pode executar diretamente o seguinte script em seu terminal:

bash <(curl -s https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_linux.sh)

Se estiver em ambiente Windows, basta copiar e copiar o seguinte script no powershell:

# CONFIGURAÇÃO DE PARÂMETROS DO HORUSEC
$image = "horuszup/horusec-cli:v2.9.0-beta.3"
$severity_exception = "LOW,UNKNOWN,INFO"
$report_type = "json"
$report_directory = "reports"
$report_path = "reports/horusec_report.json"
$ignore = @(
    "**/tmp/**",
    "**/.vscode/**",
    "**/.venv/**",
    "**/.env/**",
    "**/tests/**",
    "**/test/**",
    "**/test/",
    "**/*.Tests/**",
    "**/*.Test/**",
    "**/test_*",
    "**/appsettings.*.json",
    "**/bin/Debug/*/appsettings.*.json",
    "**/*.yml",
    "**/bin/Debug/*/appsettings.json",
    "**/*.sarif"
) -join ','

# CRIA PASTA DE RELATÓRIO
if (-Not (Test-Path -Path reports)) {
    New-Item -ItemType Directory -Path $report_directory
}

# EXECUTA CONTAINER DO HORUSEC REMOVENDO-O AO FIM DA EXECUÇÃO
docker pull $image
docker run --rm `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -v ${PWD}:/src/horusec $image horusec start `
    -p /src/horusec -P ${PWD} `
    -o="$report_type" `
    -O="$report_directory/$report_path" `
    -s="$severity_exception" `
    --ignore="$ignore" `
    --information-severity=$true

Ou, pode executar diretamente o seguinte script em seu terminal algumas das alternativas abaixo:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_docker_windows.ps1" -OutFile "horusec_docker_windows.ps1"; .\horusec_docker_windows.ps1; Remove-Item "horusec_docker_windows.ps1"

Ou…

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_docker_windows.ps1'))

O Docker Hub atualmente possui políticas de limitação downloads (pulls) de imagens de container. Caso implemente integrações nas pipelines, é possível que você seja afetado devido às regras. Talvez seja necessária a assinatura do DockerHub ou criação dos próprios containers, uso de registries internos (Ex. AWS) e customização do script do Horusec para integrar estas novas imagens.

Valores do DockerHub no mês de 07/2024.

https://res.cloudinary.com/dtr6hzxnx/image/upload/v1721863692/blog/0783dc8d-b710-4031-b3aa-3843e617d520.png

Reports customizados

O Horusec por CLI possui tipos de relatório voltados para visualização em cli (text) ou para que sejam importados para outra soluções (json, sarif, sonarqube), porém não há opções visuais para para uso na pipeline como artefato ou localmente como nos exemplos anteriores. Para ajudar nesta necessidade, podemos adotar o uso de scrips customizados para tratar estas informações e converter para um markdown.

Dada a seguinte estrutura do json vigente na versão v2.9.0-beta.3, utilizaremos o Python 3 e a biblioteca grip para ajudar na visualização do Markdown.

{
  "version": "v2.9.0-beta.3",
  "id": "af2cf885-da12-4eaf-b277-bacb4b514efa",
  "repositoryID": "00000000-0000-0000-0000-000000000000",
  "repositoryName": "",
  "workspaceID": "00000000-0000-0000-0000-000000000000",
  "workspaceName": "",
  "status": "success",
  "errors": "",
  "createdAt": "2024-07-22T19:07:43.491963638Z",
  "finishedAt": "2024-07-22T19:07:50.525841211Z",
  "analysisVulnerabilities": [
    {
      "vulnerabilityID": "00000000-0000-0000-0000-000000000000",
      "analysisID": "af2cf885-da12-4eaf-b277-bacb4b514efa",
      "createdAt": "2024-07-22T19:07:50.525846794Z",
      "vulnerabilities": {
        "vulnerabilityID": "0e9ac1d1-d971-40b6-93ab-f049ac5c5c7d",
        "line": "12",
        "column": "21",
        "confidence": "MEDIUM",
        "file": "config.py",
        "code": "vuln_app.app.config['SECRET_KEY'] = 'random'",
        "details": "DESCRIÇÃO DA VULNERABILIDADE",
        "securityTool": "HorusecEngine",
        "language": "Leaks",
        "severity": "CRITICAL",
        "type": "Vulnerability",
        "commitAuthor": "-",
        "commitEmail": "-",
        "commitHash": "-",
        "commitMessage": "-",
        "commitDate": "-",
        "rule_id": "HS-LEAKS-25",
        "vulnHash": "9e117a0e8c29e2cfa26ebae8f4c2e40c97dbc0d408d0bc2b77809a127c4f7380",
        "deprecatedHashes": [
          "6ed75629a18be6d8b4b1303a4c6d3bc7adec12975e75351573d476206d6ccecb",
          "15b8662ec5d7866e1a8e32608dbfdd34c9d2f8d3f200a4572879fdb71b0f8679"
        ],
        "securityToolVersion": "",
        "securityToolInfoUri": ""
      }
    },
    {
      "vulnerabilityID": "00000000-0000-0000-0000-000000000000",
      "analysisID": "af2cf885-da12-4eaf-b277-bacb4b514efa",
      "createdAt": "2024-07-22T19:07:50.525851877Z",
      "vulnerabilities": {
        "vulnerabilityID": "29dca9c1-2af3-4909-8e6f-51bddfce806d",
        "line": "48",
        "column": "70",
        "confidence": "MEDIUM",
        "file": "models/user_model.py",
        "code": "payload = jwt.decode(auth_token, vuln_app.app.config.get('SECRET_KEY'), algorithms=[\"HS256\"])",
        "details": "DESCRIÇÃO DA VULNERABILIDADE",
        "securityTool": "HorusecEngine",
        "language": "Leaks",
        "severity": "CRITICAL",
        "type": "Vulnerability",
        "commitAuthor": "-",
        "commitEmail": "-",
        "commitHash": "-",
        "commitMessage": "-",
        "commitDate": "-",
        "rule_id": "HS-LEAKS-25",
        "vulnHash": "8f2fccfa6177367da180c79a2c6c9f030a338a8c464e08bda9483bca266b9276",
        "deprecatedHashes": [
          "ebc728f3e0cd90b6495ffc5b0adaa1d3f669b33a8d9e10f02830ff15f61918c2",
          "6073e224d1a70921ed541833dfc3a51a1123ba3e7df368054c8f027f23614eae"
        ],
        "securityToolVersion": "",
        "securityToolInfoUri": ""
      }
    }
  ]
}

Considerando que o horusec_report.json está no mesmo diretório de execução, você pode baixar o script horusec_json2md.py e executar passando os argumentos da seguinte forma:


#Baixe o script
wget https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_json2md/horusec_json2md.py ; 

pip install colorama

#Execute passando os argumentos com o local do json e o destino do markdown
./horusec_json2md.py horusec_report.json horusec_report.md

Opcionalmente, instale o colorama (pip install colorama) para exibir cores do output quando houver ou não vulnerabilidades.

Após a execução, você pode utilizar a biblioteca grip ou qualquer outra aplicação para visualizar o markdown, como o Typora ou o VsCode.

#Instale o grip
pip install grip

# Abra o markdown
grip horusec_report.md

# ou caso o seu ambiente nao encontro o grip apos a instação\
python -m grip horusec_report.md

Acesse a URL gerada pelo grip através do Flask:

http://localhost:6419/

Visualizando no VsCode:

Você pode visualizar um exemplo do markdown clicando aqui.

Para facilitar com one-liners, abaixo exemplos em Linux/Mac e Windows que utilizaremos mais tarde na documentação do report na pipeline, usando a mesma premissa que o arquivo json está no mesmo diretório de execução e o arquivo markdown será gerado no mesmo local:

#Linux ou Mac
wget -qO-  https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_json2md/horusec_json2md.py | python3 - horusec_report.json horusec_report.md

#Windows
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_json2md/horusec_json2md.py" -OutFile "horusec_json2md.py" ;  python horusec_json2md.py horusec_report.json horusec_report.md

Horusec em pipeline Github Actions

Assim como qualquer outra solução por linha de comando, podemos utilizar o Horusec nas pipelines de desenvolvimento.

No marketplace do Github há uma solução pronta, mas como quero customizar um pouco o processo, você pode utilizar como exemplo o script abaixo, onde o scan é realizado, é gerado um relatório em markdown do arquivo json, o artefato é disponibilizado como artefato e é adicionado ao sumário para analise imediata do desenvolvedor.

name: Run Horusec (SAST), Generate Script and Save Artifact

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  run-scripts:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: SAST - Horusec Run 🐞
        run: |
          curl -sL https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_docker_linux.sh| bash          

      - name: SAST - Horusec Report Generation 📊
        run: |
          cd reports
          curl -sL https://raw.githubusercontent.com/0xtiago/opensource-devsecops/main/tools/horusec/horusec_json2md/horusec_json2md.py  -o horusec_json2md.py 
          python3 horusec_json2md.py horusec_report.json horusec_report.md          

      - name: SAST - Horusec Upload Report Artifact 💾
        uses: actions/upload-artifact@v3
        with:
          name: SAST - Horusec Scan
          path: reports/horusec_report.md

      - name: SAST - Horusec Results In Summary 💁🏽
        run: cat reports/horusec_report.md >> $GITHUB_STEP_SUMMARY

Adicione o arquivo em .github/workflows/nome_do_workflow.yml na raiz do seu projeto mantido no Github. Aqui chamo meu arquivo de sast-horusec.yml

Abaixo um resumo do processo na pipeline.

Enfim….o mesmo blá blá blá do cara de segurança…. 🥱

A implementação de testes de segurança estática (SAST) é essencial para qualquer desenvolvedor comprometido com a criação de software seguro e confiável. Esses testes permitem a identificação precoce de vulnerabilidades no código-fonte, antes mesmo da execução do programa, garantindo a mitigação de riscos e a conformidade com normas de segurança. Além disso, ao integrar SAST no ciclo de desenvolvimento, os desenvolvedores podem melhorar continuamente suas práticas de codificação, reduzindo custos e evitando potenciais falhas de segurança que poderiam comprometer a integridade dos sistemas. Portanto, a adoção de SAST é um passo crucial para garantir a segurança e a robustez das aplicações modernas.

Outros artigos serão publicado por este que vos fala, complementando todo o ciclo de testes de segurança no deploy de uma aplicação.

Até mais.

👾

Referências

HackerWhale - Offensive Docker Image

Keep moving, fi duma égua!🙏

On this page:

comments powered by Disqus

👾

Eternal student.

Blog

Introdução