O processo de análise de requisitos de segurança pode ser uma tarefa árdua. Neste artigo, veremos como a automação por meio de script em Python pode ser um grande aliado neste processo. Abordaremos ainda informações extras de como obter informações da API da Conviso Platform
Você também pode ouvir esse conteúdo:
Vamos mostrar ainda como podemos validar automaticamente requisitos de uma “análise de requisitos” (Project com tipo Requirements), na Conviso Platform frente a vulnerabilidades (vulnerabilities) já encontradas nos ativos relacionados a estes requisitos. Esse processo traz muita agilidade na análise da modelagem de ameaças para ativos que já estão na esteira de desenvolvimento.
É uma dica muito útil para security champions, desenvolvedores, analistas de segurança, ethical hackers, enfim… para quem estiver validando requisitos de segurança de aplicações.
A principal vantagem é a otimização do trabalho de análise manual pela redução do número de requisitos validados automaticamente.
O que é preciso:
- Acesso à API da Conviso Platform;
- Conhecimento das identificações da análises na plataforma;
- Ambiente para rodar script em Python;
No decorrer do artigo, utilizaremos a validação da análise gerada pelo “Threat Modeling”, ou ainda, a análise de ameaças. Vamos lá?

Entendendo o contexto
Neste momento, precisamos entender o contexto dessa automação. Vamos partir de um cenário em que estamos com uma aplicação operacional e realizamos uma modelagem de ameaças que gerou requisitos de segurança para esta aplicação. Sendo assim, em seguida falaremos mais sobre a modelagem de ameaças como a origem dos requisitos de segurança. Explicarei também a origem das vulnerabilidades, para então realizarmos a análise dos requisitos de maneira automatizada comparando com as vulnerabilidades encontradas nos ativos do escopo.
O que são requisitos de segurança
Os requisitos de segurança geralmente têm origem na modelagem de ameaças (Threat Modeling).
A Conviso Platform, por meio do produto Secure by Design, apoia os analistas de segurança na modelagem de ameaças, gerando requisitos automaticamente de acordo com o padrão de ataque (Mitre CAPEC) combinado ao item de arquitetura. O resultado é um projeto (Project do tipo Threat Modeling) com os requisitos de segurança específicos para os itens de arquitetura definidos na modelagem.

Importante citar que os requisitos gerados tem como base o ASVS. Você pode ler mais sobre ASVS no link oficial do projeto em: OWASP Application Security Verification Standard | OWASP Foundation
Sobre Vulnerabilidades
Já as vulnerabilidades podem ser oriundas de diversas fontes. Possivelmente em uma esteira de desenvolvimento automatizada o maior número de vulnerabilidades será de testes automatizados, estamos falando de SCA e SAST, mas as vulnerabilidades pode também ter sua origem de análises manuais, como pentest. Essas vulnerabilidades podem ser cadastradas manualmente ou de integrações com ferramentas de gerenciamento de demandas (Bug Tracker).

No caso de ferramentas de análise automática de código (SAST) vale a pena citar que é fornecido por meio do produto Secure Pipeline da Conviso Platform. No entanto, cada esteira pode ter o seu fornecedor. Inclusive, você sabia que a Conviso Platform oferece, além da orquestração ASTs, integração com as principais soluções de mercado?

Um overview sobre análise automatizada
A lógica que vamos utilizar para realizar a análise é baseada nas seguintes premissas:
- A própria OWASP informa que os requisitos de nível 1 do ASVS podem ser validados de maneira automática;
- Por meio do ASVS temos o requisito (controle) associado ao CWE (fraqueza);
- As vulnerabilidades cadastradas possuem o index CWE;
Logo, podemos dizer que se encontramos uma vulnerabilidade na aplicação, isso significa que não estamos aplicando o controle adequado! Portanto, o requisito relacionado à vulnerabilidade não está implantado.
O que não significa dizer que se não encontramos vulnerabilidades, estamos de acordo com o requisito. Afinal, isso apenas é verdade para os requisitos de nível 1 do ASVS.
Executando a automação
1º passo: Conseguir credenciais – API Key
Para poder utilizar a API, precisamos da credencial. Isso é feito pela chave da API.
No canto superior direito: usuário > menu “Edit Profile”:

- Aba “API Key” > botão “Generate” > “Confirma”:

2º passo: Obtendo identificação do projeto e da companhia
- Este ID pode ser observado na plataforma na URL do navegador quando acessamos a análise:

No exemplo da imagem acima o código do projeto é o 2983
E o código do companhia é o 277
3º passo: Executando nosso script
Chegou a hora de utilizarmos o nosso script em Python!
- O script que utilizamos está disponível em nosso repositório.
- Para executar, faça da forma que já lhe for habitual. Em nosso caso, utilizamos o Python no Windows, rodando no Visual Code.
- Ao abrir o projeto, No Visual Code o projeto deve ficar assim:

Observações: Validar a URL do ambiente de acordo com o uso que será feito!
- Uma vez que o script utiliza as credenciais das variáveis de ambiente é preciso configurar as variáveis:
- i) CONVISO_PLATFORM_URI, Url da API (para produção = https://app.convisoappsec.com/graphql);
- ii) CONVISO_PLATFORM_TOKEN, é a API Key gerada conforme passo “Conseguir credenciais – API Key”.
- Além do Python instalado, precisamos também do: i) Pandas; ii) Requests e iii) Openpyxl. Os comandos abaixo devem ser suficientes:
pip3 install pandas
pip3 install requests
pip install openpyxl
- Uma vez que as configurações estiverem corretas para o ambiente do projeto com o Python, já podemos executar. Como, por exemplo, por meio do “Run Python file” (menu superior a direita). Observe imagem abaixo. Mais uma vez, sinta-se à vontade para realizar essa atividade como preferir.

- Informe o ID do Projeto da Conviso Platform já obtido nos primeiros passos. Ver: “Obtendo identificação do projeto e da companhia”:

- Última entrada solicitada é justamente o ID da companhia. Também, anteriormente, ver Obtendo identificação do projeto e da companhia:

- Com as informações, o script vai cuidar de todo o processo, gerando uma planilha com o resultado da análise disponível na pasta do projeto, além de printar na tela o resultado. Como no exemplo:

4º passo: Interpretando o resultado
O resultado é disponibilizado no arquivo “Result.xlsx”:

Os possíveis resultados para os requisitos serão:
- Done: Para requisitos do ASVS de nível 1 que “não” foram encontradas vulnerabilidades;
- Not according: Para requisitos do ASVS de nível 1 que possui vulnerabilidades;
- non-automated: Para requisitos do ASVS de nível 2 ou 3.
Requisitos que não têm CWE relacionado não estão incluídos na análise.
Informações adicionais para manipulação manual
Vamos passar também algumas informações que podem ser úteis no processo de customização ou manutenção do script, ou ainda realizar a análise de forma manual.
Utilizando client Graphql, Altair para consumir API da Conviso Platform:
Instalar a extensão do Altair GraphQL Client no navegador:
O Altair é um cliente GraphQL para todas as plataformas. Usaremos a extensão para o navegador. No entanto, existe ainda a opção desktop. Assim como também pode ser usado outro GraphQL Client.
Confira as orientações:
- Caso ainda não tenha instalada, instalar a extensão no seu navegador. Pode procurar pela extensão no Chrome web store. No tempo que escrevemos este artigo utilizamos o link: Altair GraphQL Client – Chrome Web Store (google.com)
- Adicionar extensão da “chrome web store” > “Adicionar extensão”:

- Uma vez instalado, vamos configurar para consumir a API da Conviso:

Obter os requisitos via API
- Configurar a API Key no Altair. Menu a esquerda “Set Headers”> Add header > Save:
x-api-key: {{API_KEY}}

Para mais informações para uso das APIs da Conviso Platform, ver nossas documentações em: Getting Started | Conviso Platform Docs (convisoappsec.com).

- Testar a comunicação com a API. Para isso, utilize a URL de acesso as APIs: https://app.conviso.com.br/graphql e fazemos uma requisição.
Para acesso ao ambiente de homologação: https://homologa.convisoappsec.com/graphql
Caso tenha problemas com a API key, a resposta será:

No entanto, se tudo estiver certo, a resposta será:

- A requisição que precisamos fazer é para pegar os requisitos, “requirements”. Então, o request fica como o JSON abaixo. Claro que alterando o valor do “id” para o da análise correspondente:
{
project(id: 999) {
activities {
id
title
reference
status
description
justify
}
playbooks {
checklistTypeId
companyId
}
}
}
Para consultar a documentação da API, acesse o menu “Docs” e “Reload docs”:

- O resposta, ou seja, os requisitos da análise informada, podem ser salvos localmente realizando o “DOWNLOAD” do result:

O resultado pode ser manipulado em planilha ou com scripts no Python como fizemos de forma automatizada.
Obter as Vulnerabilidades via API
- Da mesma forma feita para obter o JSON com os requisitos da análise, faremos para obter as vulnerabilidades. Consumindo a API do Graphql da Conviso pelo Altair, agora com o request abaixo (trocando o id com a identificação do cliente):
assets(id: 999, page:1, limit:1000){
metadata{
currentPage
limitValue
totalCount
totalPages
}
collection{
id
name
projects{
pid
...VulnByAsset
}
}
}
}
fragment VulnByAsset on Project{
vulnerabilities{
title
vulnerabilityTemplate{
categoryList
reference
}
}
- Ao obter o resultado, também podemos fazer o download para processar com o Python (ou da forma que preferir):

Mais uma vez, lembramos que estes resultados podem ser manipulados em planilha ou com scripts no Python como fizemos de forma automatizada.
Conhecendo a fonte do OWASP ASVS
Neste processo, utilizamos a planilha do Application Security Verification Standard (ASVS) da OWASP na versão 4.0.2. porque é a versão que a Conviso Platform utiliza na lógica para gerar os requisitos. No momento ela está disponível pelo link:
A lógica empregada, conforme pode ser visto no script, é de posse do código ASVS do requisito ir na planilha do ASVS e pegar o código da CWE correspondente para comparar com as vulnerabilidades encontrada. Podemos aplicar isso em uma planilha com PROCV.
É possível ganhar muito tempo na análise de requisitos do nível 1 do ASVS com esta automação. Lembrando que, para isso, a análise estática precisa estar rodando nos ativos da aplicação. Assim, o analista consegue focar nos requisitos que de fato precisam de validação manual.
Além de realizar essa automação, mostramos também como é fácil utilizar a API GraphQL da Conviso Platform para evoluções e customização de acordo com a necessidade da sua esteira. Sendo assim, convidamos você também a contribuir com a comunidade em nosso repositório publico no GitHub da Conviso Lab. E fique atento – muitas novidades boas virão por aí!
