Thanks to visit codestin.com
Credit goes to github.com

Skip to content

MalwareDataLab/autodroid-api

BranchesTags

Repository files navigation

Project logo

AutoDroid

Status

📝 Índice

📖 Sobre

Este repositório contém o código da API AutoDroid.

Motivação

Os Hackers do Mal estão utilizando técnicas de IA (Inteligência Artificial) para realizar "mutações" em malware, dificultando sua detecção, que afeta os usuários de computadores e dispositivos móveis, dentre outras tecnologias que possam estar sujeitas a ataque de malware, gerando um aumento do nível de proliferação de malware: um dos maiores desafios da segurança da informação.

Os Hackers do Bem podem enfrentar esta proliferação de malwares utilizando ferramentas de IA como o DroidAugmentor para que a detecção dos malwares "mutantes" seja amplamente aprimorada.

Todavia ferramentas tais como a DroidAugmentor manualmente pode ser uma tarefa muito complexa e nada escalável, criando uma grande barreira de aprendizagem e utilização da ferramenta.

Encapsular aplicativos em contêineres Docker pode ser uma solução para esse problema, mas ainda é um processo muito manual e não é muito fácil de gerenciar.

Solução

Ao oferecer ferramentas como a DroidAugmentor como um serviço, torna sua execução escalável, de fácil aprendizado e com melhor aproveitamento para experimentação.

A AutoDroid é uma aplicação que visa oferecer aplicações como a DroidAugmentor como um serviço, tornando sua execução escalável, de fácil aprendizado e com melhor aproveitamento para experimentação.

✨ Visão Geral do Projeto

O serviço proposto se trata da etapa de expansão de Dataset na pipeline de AutoML, conforme apresentado em DroidAugmentor.

Overview

O projeto é composto por diversas partes, com o objetivo final de oferecer uma ferramenta escalável para executar instâncias da DroidAugmentor.

Overview

🏦 Arquitetura

Esta aplicação é uma API REST/GraphQL construída usando Typescript com Node.js, Express e TypeGraphQL.

Seguindo o modelo C4, a arquitetura do back-end é apresentada a seguir:

Visão de sistema: be-system

Visão de contêiner: be-container

Visão de componente: be-component

Entidades

  • User: representa um usuário da aplicação. Nenhum dado pessoal é coletado, é apenas um identificador anônimo.
  • File: representa um arquivo, que pode ser um dataset ou resultado de processamento, por exemplo.
  • Processor: representa um processador que será usado para processar um conjunto de dados. É uma imagem Docker que será usada para processar a solicitação de processamento do usuário com os parâmetros fornecidos.
  • Dataset: representa um conjunto de dados que será usado por um processador, é um arquivo que será usado como entrada para o processador.
  • Processing: representa uma solicitação de processamento feita por um usuário. É uma solicitação para processar um conjunto de dados usando um processador com os parâmetros fornecidos. Todo o ciclo de vida do processamento está disponível nesta entidade, incluindo o status de execução e seu resultado.
  • Worker: representa uma instância da aplicação Worker, que é responsável por processar os jobs em background.

Estrutura do código

A estrutura interna é apresentada em estrutura do código e guiada pelo documento de Guidelines de Código.

A proposta de arquitetura do back-end é baseada em DDD e Clean Architecture. É guiada por princípios de SOLID e visa a separação de responsabilidades, facilitando a manutenção e evolução do código. Além disso, é proposto o método de desenvolvimento TDD para garantir a qualidade do código guiado por testes.

⛏️ Tecnologias Utilizadas

Geral

É importante mencionar as demais ferramentas que serão utilizadas nas duas partes do projeto:

💻 Ambiente do Usuário

O ambiente do usuário final (utilizador) deverá ter um dispositivo (seja fixo ou móvel) com acesso à internet e com ao menos uma ferramenta de navegação para acessar a versão web do produto ou um cliente de API REST/GraphQL (ex.: curl, httpie, postman, insomnia) previamente instalado em seu dispositivo.

📡 Ambiente do Servidor

  • Sistema operacional Linux (por exemplo, Ubuntu, Debian e outros...) (MacOS/Windows é experimental)
  • Virtualização habilitada na BIOS
  • Mínimo de 4GB de RAM
  • Mínimo de 10GB de espaço livre em disco, dependendo dos "processadores" disponíveis (para arquivos, resultados de processamento, banco de dados e imagens Docker)
  • Git instalado
  • Docker instalado

🚩 Antes de começar

Este projeto requer credenciais e chaves de acesso para a integração com serviços externos, sendo eles:

  • Firebase: autenticação/autorização
  • Google Cloud Storage: armazenamento de arquivos

O requisito "Google Cloud Storage" pode ser provido pela mesma conta do requisito "Firebase", tanto como pode ser uma conta/projeto Google distinto.

Firebase

  • Entre na conta Google que será utilizada para gerenciar o projeto.
  • Acesse o Firebase Console.
  • Crie um novo projeto ou utilize um projeto existente.
  • Inicie o Firebase Authentication.
  • Habilite o provedor de autenticação Email.
  • Habilite o provedor de autenticação Google.
  • Inicie o Firebase Storage.
  • Crie um novo bucket ou utilize um bucket existente, coletando o valor nome do bucket.
  • Crie a aplicação web e armazene os dados de configuração a serem usados pelo frontend posteriormente.
  • Crie uma conta de serviço (service account) para SDK Admin do Firebase.
  • Crie uma chave de acesso JSON para a conta de serviço e salve o arquivo em um local seguro.

Nota sobre o Firebase Storage: O Firebase pode solicitar um cartão de crédito para habilitar o Storage, mesmo que você não ultrapasse o limite gratuito. No momento da escrita desta documentação, o Firebase oferece 5GB de armazenamento gratuito, o que é mais que suficiente para executar esta aplicação. Para mais detalhes sobre preços e limites, consulte a documentação oficial do Firebase.

Para mais detalhes, foi desenvolvido o tutorial detalhado sobre como configurar o Firebase (Authentication + Storage) para a AutoDroid.

Google Cloud Storage

Variáveis de ambiente

Os campos das seções #General, #Database, #Non-relational database e # Redis estão configurados para funcionarem adequadamente em ambiente Docker, altere conforme necessário.

O campo CORS_ALLOWED_FROM é configurado para aceitar requisições de qualquer origem, altere conforme necessário.

Os campos da seção #Providers são obrigatórios para o funcionamento da aplicação e devem ser preenchidos com os valores coletados anteriormente.

  • (Obrigatório) Preencha os campos FIREBASE_AUTHENTICATION_PROVIDER_PROJECT_ID, FIREBASE_AUTHENTICATION_PROVIDER_CLIENT_EMAIL e FIREBASE_AUTHENTICATION_PROVIDER_PRIVATE_KEY com os valores da conta de serviço do Firebase.
  • (Obrigatório) Preencha os campos GOOGLE_STORAGE_PROVIDER_PROJECT_ID, GOOGLE_STORAGE_PROVIDER_CLIENT_EMAIL e GOOGLE_STORAGE_PROVIDER_PRIVATE_KEY e GOOGLE_STORAGE_PROVIDER_BUCKET_NAME com os valores da conta de serviço do Google Cloud Storage (ou Firebase Storage, com o nome do bucket coletado em Criação → Storage sem o prefixo gs://).

Os campos #Feature devem ser ajustados conforme suas preferências para o funcionamento.

  • (Obrigatório) Preencha o campo ADMIN_EMAILS com os emails dos administradores separados por vírgula.
  • (Obrigatório) O campo JOBS_ENABLED deve ser preenchido com true para habilitar o processamento de jobs em background.
  • (Obrigatório) Os campos WORKER_REFRESH_TOKEN_SECRET e WORKER_ACCESS_TOKEN_SECRET são obrigatórios e devem ser preenchidos com valores aleatórios para garantir a segurança da aplicação.

Os campos opcionais podem ficar vazios (exemplo: CAMPO=, deixando nenhum valor após o sinal de igualdade =), caso não deseje especificar um valor

  • (Opcional) Preencha o campo SENTRY_DSN com a chave fornecida pelo Sentry caso desejado.
  • (Opcional) Preencha os campos STORAGE_PROVIDER_PUBLIC_READ_URL_EXPIRATION, STORAGE_PROVIDER_PUBLIC_WRITE_URL_EXPIRATION, WORKER_REFRESH_TOKEN_EXPIRATION, WORKER_ACCESS_TOKEN_EXPIRATION, PROCESSING_DEFAULT_KEEP_UNTIL e PROCESSING_ALLOWED_KEEP_UNTIL_EXTEND conforme a especificação da biblioteca ms.

🏁 Primeiros Passos

Estas instruções irão ajudá-lo a obter uma cópia deste projeto e executá-lo em sua máquina local para fins de desenvolvimento e teste. Consulte deployment para obter informações sobre como implantar o projeto em ambiente produtivo.

Verifique se você atende aos requisitos do ambiente do servidor antes de começar.

Execute todos os passos de antes de começar. Salve todos certificados e chaves de acesso em um local seguro.

Existem duas maneiras de instalar esta aplicação: utilizando o Docker (recomendado) ou manualmente.

Instalação via Docker (recomendado)

Usando o terminal, clone este repositório em sua máquina local usando o Git:

git clone https://github.com/MalwareDataLab/AutoDroid.git

Navegue até a pasta do repositório:

cd autodroid

Atualize o repositório sempre, utilizando:

git pull

Inicie o projeto:

docker compose up --build

Este script irá iniciar a aplicação usando o Docker compose. A inicialização da aplicação pode levar alguns minutos, dependendo da sua conexão com a internet e do tamanho dos "processadores" fornecidos. O terminal deve ser mantido aberto durante a execução da aplicação.

Se a inicialização for bem-sucedida, você verá algumas mensagens no console, como por exemplo:

autodroid_api_gateway_prod  | 🆗 Database connection success.
autodroid_api_gateway_prod  | 🆗 Redis default connection success.
autodroid_api_gateway_prod  | 🆗 Image someImage:latest loaded.
autodroid_api_gateway_prod  | 🆗 Docker dataset processor provider connection success.
autodroid_api_gateway_prod  | 🆗 Processing background jobs on @autodroid/api.
autodroid_api_gateway_prod  | ⚡️ @autodroid/api production version X using Node.js X running at port 3333 with PID X.

Prossiga para a seção utilização para obter informações sobre como usar a aplicação.

Para parar a aplicação, pressione Ctrl + C no terminal ou execute docker compose down na raiz deste repositório, caso esteja executando a aplicação em modo destacado.

Uma pasta ./runtime será criada na raiz deste repositório para armazenar os arquivos temporários da aplicação. Pode ser necessário permissões de superusuário para acessar, modificar ou excluir esta pasta.

Instalação Manual

Um guia para configurar o projeto manualmente está disponível no guia de configuração manual.

📱 Utilização

Esta aplicação fornece uma API REST/GraphQL no ambiente Docker compose.

Por padrão, estará disponível em sua máquina local nos seguintes URLs:

Esta URL estará disponível até que a aplicação seja interrompida.

Para usar a API diretamente, você pode seguir as instruções na documentação da API ou pode usar ferramentas de cliente HTTP como Postman ou Insomnia.

Todas as rotas, queries e mutations da API estão disponíveis nesta coleção do Postman.

Usuário/Autorização

Esta aplicação usa autenticação através do provedor Firebase, sendo necessário o envio do header Authorization em cada requisição, com o respectivo valor Bearer ${token}.

Processador

O processador é uma aplicação (imagem Docker) a ser registrada pelo adminsitrador para ser utilizada pelos usuários para processar conjuntos de dados. Exemplo de requisição.

Dataset

O arquivo de conjunto de dados pode ser enviado pelo usuário usando a API. O arquivo de conjunto de dados deve ser um arquivo válido com um tipo MIME válido, de acordo com a configuração do processador.

Há um dataset de exemplo na pasta ./docs/samples deste repositório que você pode usar para testar a aplicação.

O envio é feito por URL assinada, a funcionalidade de Create dataset irá fornecer uma upload_url, para onde o arquivo de fato deverá ser enviado. Exemplo de requisições.

Processamento

Obtidos o processor_id e dataset_id a partir da criação dos dois passos anteriores, o usuário pode solicitar o processamento do conjunto de dados, seja com os parâmetros predefinidos ou customizados. Exemplo de requisição.

O resultado pode ser obtido através do download do arquivo zip fornecido pelo campo public_url após a conclusão do processamento (campo status). Exemplo de requisição.

Worker

O worker é uma aplicação (imagem Docker) que será utilizada para processar os jobs em background. O worker é uma aplicação separada da API e deve ser configurada para funcionar corretamente.

Inicialmente o administrador cria um WorkerRegistrationToken onde o campo token será utilizado para autenticar a aplicação com o backend. Exemplo de requisição.

Siga as instruções em worker para a instalação e configuração do worker.

Fluxo comum

O fluxograma a seguir descreve o fluxo comum da aplicação:

Fluxo comum

✅ Testes

Para executar os testes, por favor execute o comando abaixo:

yarn test

A cobertura de código e outros relatórios serão gerados na pasta ./test/outputs.

🎯 Demonstração

Foi disponibilizado um script de demonstração ponta-a-ponta para a aplicação, que pode ser executado com o comando (após realizar a configuração solicitada em antes de começar):

./demo.sh

🚀 Deployment

Esta aplicação está pronta para implantação com Docker e docker compose.

Para disponibilizar esta aplicação em ambiente produtivo:

Realize o download na pasta desejada:

git clone https://github.com/MalwareDataLab/AutoDroid.git

Atualize o repositório utilizando:

git pull

Complete os mesmos processos citados anteriormente em antes de começar.

Realize o processo de construção da imagem Docker utilizando:

docker compose build --no-cache

Depois que a aplicação for construída, preencha e verifique o arquivo docker-compose.yml com suas variáveis de ambiente (conforme especificado em antes de começar) e execute o seguinte comando:

docker compose up -d

A aplicação estará disponível na porta 3333 (configuração padrão), para alterar, modifique o arquivo docker-compose.yml e reinicie a aplicação utilizando o comando docker compose restart.

Configure sua rede local e as portas do firewall para permitir o acesso à aplicação.

Verifique as restrições da sua rede local e ISP.

🔃 Atualizando

O docker compose está instrumentado com a ferramenta watchtower para atualizações automáticas.

Para realizar atualização manual, execute o seguinte comando:

docker compose down
docker compose pull
docker compose up -d

🔧 Solução de Problemas

O Docker é incrível, mas às vezes pode ser um pouco complicado. Alguns erros podem ocorrer durante a execução da aplicação, e alguns deles podem estar relacionados ao Docker.

Erros antes da inicialização

Se você estiver enfrentando alguns erros antes da inicialização da aplicação, verifique os seguintes itens:

  • Verifique se a máquina atende aos requisitos.
  • Verifique se todos os passos especificados em antes de começar foram completados, refaça-os se necessário.
  • Verifique se seu usuário possui permissões de uso ao Docker, executando o comando docker run --rm hello-world:latest.
  • Realize os processos de pós-instalação do Docker, conforme documentação oficial.

Limpando o ambiente do Docker

Se você estiver enfrentando alguns erros relacionados ao Docker, você pode tentar limpar o ambiente do Docker executando os seguintes comandos:

# Pare todos os containers
docker compose down
docker stop $(docker ps -q)

# Remova todos os arquivos da pasta runtime
sudo rm -rf ./.runtime

# Remova todas as imagens relacionadas a este projeto
docker rmi $(docker images -q -f "reference=autodroid_*")

# Reinicie o serviço de rede
sudo systemctl restart NetworkManager.service

# (Opcional) Limpe o ambiente do Docker
docker system prune -a

Verificando as etapas de inicialização

Se você estiver enfrentando alguns erros durante a inicialização da aplicação, você pode verificar as etapas da inicialização executando os seguintes comandos:

# Tente usar qualquer imagem do Docker Hub que não esteja em sua máquina para verificar se o Docker instalado está funcionando como esperado
docker rmi hello-world
docker run --rm hello-world:latest

# Tente construir a aplicação manualmente, em caso de erro, envie a mensagem de erro para o mantenedor do projeto
docker compose build --no-cache

Persistindo o erro, entre em contato com o mantenedor do projeto.

📖 Referências

LAVIOLA, Luiz Felipe; PAIM, Kayuã Oleques; KREUTZ, Diego; MANSILHA, Rodrigo Brandão. AutoDroid: disponibilizando a ferramenta DroidAugmentor como serviço. In: ESCOLA REGIONAL DE REDES DE COMPUTADORES (ERRC), 20. , 2023, Porto Alegre/RS. Anais [...]. Porto Alegre: Sociedade Brasileira de Computação, 2023 . p. 145-150. DOI: https://doi.org/10.5753/errc.2023.929.

LAVIOLA, Luiz Felipe; GASPAR DINIZ NOGUEIRA, Angelo; KREUTZ, Diego; BRANDÃO MANSILHA, Rodrigo. Cloud AutoDroid: uma Arquitetura de Backend para Executar Serviços de IA Generativa na Nuvem. In: ESCOLA REGIONAL DE ENGENHARIA DE SOFTWARE (ERES), 8. , 2024, Santiago/RS. Anais [...]. Porto Alegre: Sociedade Brasileira de Computação, 2024 . p. 258-267. DOI: https://doi.org/10.5753/eres.2024.4302.

CASOLA, Karina; PAIM, Kayuã Oleques; MANSILHA, Rodrigo Brandão; KREUTZ, Diego. DroidAugmentor: uma ferramenta de treinamento e avaliação de cGANs para geração de dados sintéticos. In: SALÃO DE FERRAMENTAS - SIMPÓSIO BRASILEIRO DE SEGURANÇA DA INFORMAÇÃO E DE SISTEMAS COMPUTACIONAIS (SBSEG), 23. , 2023, Juiz de Fora/MG. Anais [...]. Porto Alegre: Sociedade Brasileira de Computação, 2023 . p. 57-64. DOI: https://doi.org/10.5753/sbseg_estendido.2023.235793.

NOGUEIRA, Angelo Gaspar Diniz; PAIM, Kayua Oleques; BRAGANÇA, Hendrio; MANSILHA, Rodrigo; KREUTZ, Diego. MalSynGen: redes neurais artificiais na geração de dados tabulares sintéticos para detecção de malware. In: SALÃO DE FERRAMENTAS - SIMPÓSIO BRASILEIRO DE SEGURANÇA DA INFORMAÇÃO E DE SISTEMAS COMPUTACIONAIS (SBSEG), 24. , 2024, São José dos Campos/SP. Anais [...]. Porto Alegre: Sociedade Brasileira de Computação, 2024 . p. 129-136. DOI: https://doi.org/10.5753/sbseg_estendido.2024.243359.

About

API Gateway of the Malware DataLab platform

malwaredatalab.github.io/

Topics

nodejs api graphql redis typescript mongodb postgresql apigateway prisma apolloserver vitest genai

Resources

Readme

Code of conduct

Code of conduct
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 22

v0.7.4 Latest
Jul 16, 2025
+ 21 releases

Packages

No packages published

Contributors 2

  •  
  •  

Languages