Automation of security requirements with the Conviso Platform API

The process of security requirements analysis can be an arduous task. In this article we will see how automation through Python scripting can be a great ally in this process.

You can also listen to this article:

We will also address how to get information from the Conviso Platform API and show how to automatically validate requirements from a “requirements analysis” on the Conviso Platform against vulnerabilities already found in assets related to these requirements. This process brings a lot of agility in analyzing threat modeling for assets that are already in the developmental pipeline.

It’s a very useful tip for security champions, developers, security analysts, and ethical hackers –  anyway, for anyone who is validating application security requirements. The main advantage is the optimization of manual analysis work by reducing the number of automatically validated requirements. What is required for this process: 

• Access to the Conviso Platform API; 
• Knowledge of the identification of the analysis on the platform; 
• Environment to run a script in Python.

For the purposes of this article, we will use the validation of the analysis generated by threat Modeling or even the threat analysis of threats. Are you ready?

A bit of context

At this point, we need to understand the context of this automation. Let’s start with a scenario in which we have an operational application and carry out a threat modeling that generates security requirements for this application. 

Next, we’ll address threat modeling as the source of security requirements. Then, I will explain the origin of the vulnerabilities, so that we can perform the  requirements analysis in an automated way, comparing them with the vulnerabilities found in the assets in scope.

What are security requirements?

Security requirements often come from Threat Modeling.  Secure by Design – a product within Conviso Platform –  supports security analysts in threat modeling, automatically generating requirements according to the attack pattern (Miter CAPEC) combined with the architecture item. 

The result is a project (a Threat Modeling type of Project) with specific security requirements for the architecture items defined in the modeling.

It’s important to mention that the generated requirements are based on ASVS. 

About Vulnerabilities

Vulnerabilities can come from a variety of sources. In an automated development pipeline, many might have their origins in automated tests. We are talking about SCA and SAST, but vulnerabilities can also have their origin in manual analysis, such as pen testing. These vulnerabilities can be registered manually or through integrations with demand management tools (Bug Tracker).

In the case of automatic code analysis tools (SAST), it is worth mentioning that it is provided by the Secure Pipeline – a product within the Conviso Platform. However, each pipeline can have its supplier. By the way, did you know that Conviso Platform offers, in addition to ASTs orchestration, integration with the main market solutions?

An overview of the automated analytics

The logic that we will use to perform the analysis is based on the following premises:

• OWASP itself reports that ASVS Level 1 requirements can be validated automatically;
• Through ASVS we have the requirement (control) associated with CWE (weakness);
• The registered vulnerabilities have the CWE index;

Therefore, we can say that if we find a vulnerability in the application, it means that we are not applying the proper control! Therefore, the vulnerability-related requirement is not implemented.

This is not to say that if we don’t find vulnerabilities, we are in compliance with the requirement. After all, this is only true for ASVS Level 1 requirements.

Running the automation

Step 1: Get credentials – API Key

To be able to use the API, we need the credential. This is done by the API key.

• In the upper right corner: user > “Edit Profile” menu:

• “API Key” tab > “Generate” button > “Confirm”:

Step 2: Getting the project and company identification

• This ID can be seen on the platform in the browser’s URL when we access the analysis:

In the example of the image above the project code is 2983

And the company code is 277

Step 3: Running the script

It’s time to use our Python script!

• The script we used is now available in our repository.
• To execute it, do it as it fits your routine, as you’re already used to. In our case, we use Python on Windows, running on Visual Code.
• When opening the project, In Visual Code the project should look like this:

Notes: Validate the environment URL according to the use that will be made! See CONVISO_PLATFORM_URI

• Since the script uses the credentials of the environment variables you need to set the variables: :
  • i) CONVISO_PLATFORM_URI,  API Url (for production = https://app.convisoappsec.com/graphql);
  • ii) CONVISO_PLATFORM_TOKEN, is the API Key generated according to step “Get Credentials – API Key”.

• In addition to Python installed, we also need: i) Pandas; ii) Requests and iii) Openpyxl. The commands below should be sufficient:

pip3 install pandas

pip3 install requests

pip install openpyxl

• Once the settings are correct for the project environment with Python, we are ready to run. And this can be done, for example, through the “Run Python file” (top right menu). Look at the image below. Again, feel free to do this activity however you like.

• Enter the Conviso Platform Project ID. It was already obtained in the first steps, so check “Obtaining project and company identification”:

• Last entry requested is precisely the company ID. Also, previously, see Getting Project and Company ID:

• With this information, the script will take care of the entire process, generating a spreadsheet with the result of the analysis available in the project folder, in addition to printing the result on the screen. As in the example:

Step 4: Interpreting the result

The result is available in the “Result.xlsx” file:

The possible outcomes for the requirements will be:

• Done: For ASVS Level 1 requirements that “no” vulnerabilities were found;
• Not according: For ASVS Level 1 requirements that have vulnerabilities;
• non-automated: For ASVS Level 2 or 3 requirements.

Requirements that do not have related CWEs are not included in the analysis.

Additional information for manual manipulation

We will also pass on some information that can be useful in the process of customizing or maintaining the script or even performing the analysis manually.

Using client Graphql, Altair to consume API from the Conviso Platform – Install the Altair GraphQL Client extension in the browser:

Altair is a GraphQL client for all platforms. We will use the browser extension. However, there is still a desktop option. Just as another GraphQL Client can be used.

Check the guidelines:

• If you don’t already have it installed, install the extension in your browser. You can search for the extension in the Chrome web store. At the time we wrote this article we used the link: Altair GraphQL Client – Chrome Web Store 
• Add extension from “chrome web store” > “Add extension”:

• Once installed, let’s configure it to consume Conviso’s API:

Get requirements via API

• Configure API Key on Altair. Left menu “Set Headers” > Add header > Save:

x-api-key: {{API_KEY}}

For more information on using Conviso Platform APIs, see our documentation at: Getting Started | Conviso Platform Docs (convisoappsec.com).

• Test communication with the API. For this, use the URL to access the APIs: https://app.conviso.com.br/graphql and make a request.
• For access to the homologation environment: https://homologa.convisoappsec.com/graphql
• If you have problems with the API key, the answer will be:

However, if everything’s ok, the answer will be:

• The request we need to make is to get the requirements, “requirements”. So the request looks like the JSON below. Of course, changing the value of “id” to that of the corresponding analysis:

{
  project(id: 999) {
    activities {
      id
      title
      reference
      status
      description
      justify
    }
    playbooks {
      checklistTypeId
      companyId
    }
  }
}

To consult the API’s documentation, make sure to access the “Docs” and “Reload docs” menu:

• The answer, that is, the requirements of the informed analysis, can be saved locally by performing the “DOWNLOAD” of the result:

The result can be manipulated in a spreadsheet, or with scripts in Python, as we chose to do – in an automated way.

How to get Vulnerabilities via API

• In the same way we did to get the JSON with the analysis requirements, we will do it to get the vulnerabilities. Consuming Conviso’s Graphql API by Altair, now with the request below (changing the id with the client’s ID):

	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
    }
  }

• Once the result is obtained, we can also download it to process with Python (or however you prefer):

Once again, we remind you that these results can be manipulated in a spreadsheet or with scripts in Python, as we did in an automated way.

Knowing the source of OWASP ASVS

In this process, we used the OWASP Application Security Verification Standard (ASVS) worksheet in version 4.0.2. because it is the version that Conviso Platform uses in the logic to generate the requirements. It is currently available via the link:

ASVS/OWASP Application Security Verification Standard 4.0.2-en.csv at v4.0.2 · OWASP/ASVS (github.com)

The logic employed, as can be seen in the script, is that the ASVS code of the requirement goes to the ASVS spreadsheet and gets the corresponding CWE code to compare with the vulnerabilities found. We can apply this in a worksheet with VLOOKUP.

You can save a lot of time in ASVS Level 1 requirements analysis with this automation. Remembering that, for this, the static analysis needs to be running on the application’s assets. Thus, the analyst is able to focus on the requirements that actually need manual validation.

In addition to performing this automation, we also show how easy it is to use Conviso Platform’s GraphQL API for evolution and customization according to the needs of your treadmill. Therefore, we also invite you to contribute to the community in our public repository on Conviso Lab’s GitHub. And stay tuned – lots of good news to come!