UpGuard Knowledge Base

UpGuard API

How to bulk import vendor information

Import data for your vendors with the UpGuard API. This guide includes sample scripts for Python and Ruby.

Written by Caitlin Postal

You can always work directly within the UpGuard platform, but there are some tasks that you might wish to complete via the command line. You can access a variety of information programmatically with our API, using the API key associated with your organization's account.

If you are setting up a new account with UpGuard or you have made major revisions to your list of vendors, then you might wish to import a list of vendors in bulk. While you can select individual vendors to start monitoring within the platform, you can also import a list of vendors programmatically with the UpGuard API. Adding vendors in this way will enable you and your team to start using UpGuard's features more quickly so that you can focus on ensuring security along your vendor supply chain rather than manual data input.

In this guide, you will import data for new vendors to UpGuard using a comma-separated value (CSV) format. You will choose from the provided options to interface with the UpGuard API through Python or Ruby scripts.

Prerequisites

An UpGuard account with an API key that you can authenticate with. Follow our tutorial on How to authenticate with your UpGuard API key to set one up. If you don't already have a account, sign up for a free trial.

Step 1 — Preparing your list of vendors

To import vendor data into the UpGuard platform through the API, you will need to supply it in CSV format, which you'll do in this step.

UpGuard uses vendors' primary domain names to identify any given vendor. Because some companies share similar names, the primary domain prevents ambiguity between companies with the same or similar names, such as Apple the technology company and Apple the record producer.

With the UpGuard public API, you can add and view vendor information by primary domain. You can provide your list of vendors with only the primary domains, but you may find it helpful to include both the name and domain for a vendor, such as in the following example:

vendor,domain
UpGuard,upguard.com
Google,google.com
auth0,auth0.com

The sample list includes the headers to specify what information will be imported, followed by three named vendors and their domains. Your vendors will likely differ.

If you maintain a list of your vendors and their domains in a spreadsheet, you can export that sheet to a CSV file for use in the next steps. Otherwise, you can prepare the list manually, supplying your vendors in place of the sample vendors in the previous example. Be sure to save the file in CSV format as you will use a CSV reader in the next step, and ensure that the file is saved in your Python environment directory.

Note: Take care with the structure of your CSV file. If you introduce additional spacing in the file, such as a space or indentation after the comma delimiter, the script will return an error about the hostname string.

With your vendor information prepared, you can next write the script that will take that data to UpGuard via the API.

Step 2 — Importing your vendor data

Proceed to the appropriate section to use Python or Ruby.

Option 1 — Importing vendor data using Python

You can use Python to automate tasks and create large scripts for sequential activities. If you are first getting started with Vendor Risk and adding multiple new vendors, you can streamline the onboarding process with a script to import your vendors. This bulk import process will be faster than adding each vendor manually.

To follow this tutorial with Python, you will need these additional prerequisites:

An UpGuard account with an API key that you can authenticate with. Follow our tutorial on How to authenticate with your UpGuard API key to set one up. If you don't already have a account, sign up for a free trial.
Python installed on your machine.

Activating your Python environment

In this section, you will activate a Python virtual environment that was set up with the . You can also use an alternative virtual environment, like PyCharm or Miniconda.

You can create as many virtual programming environments as you wish, which will keep your scripts in distinct folders. This tutorial will use a directory named environments. In your terminal, move to that directory:

$ cd environments

Activate the test environment, replacing test_env with the name you supplied for your virtual environment:

$ source test_env/bin/activate

The name of your test environment will appear as a prefix for your terminal prompt. In this example, the name is test_env:

(test_env) your_user@your_machine_name~/your_path

With the environment running, you can now create your list of vendors and prepare the script to import your vendors.

Creating and running a Python script to import vendor data

In this step, you will write a Python script to ingest the CSV file with your vendors and import that information to your UpGuard account.

First, use your preferred editor to create the script file. This example uses nano:

$ nano importVendors.py

Then add the script to the newly created file:

import csv
import requestsapi_key = "your_api_key"
headers = { "Authorization": api_key }
base_url = "https://cyber-risk.upguard.com/api/public"with open("your_vendor_file") as csvfile:
  lines = csv.reader(csvfile, delimiter=',')
  for row in lines:
    vendor = row[0]
    domain = row[1]
    if vendor == "vendor":
      continue
    url = base_url + "/vendor?hostname=" + domain + "&start_monitoring=true"
    response = requests.get(url, headers=headers)
    print(response.status_code)
    print(response.text)

First, you import the and modules. You will use the csv module to parse the CSV file with your vendor data and the requests module to receive responses from the UpGuard platform after the script runs.

Next, you set your UpGuard API key as the authorization for the public API. Be sure to update your_api_key with the alphanumeric string associated with your account.

Then, you add the lines that will read the CSV file to parse through your vendor list and provide the requisite information to your UpGuard account. Update your_vendor_file with the path to the CSV file you created in Step 1. Your script will open the CSV file you provide, using the csv.reader method to parse through the rows.

The for loop will iterate through the rows, extracting the vendor name and primary domain provided. The if block will skip any row that starts with vendor, excluding the header row of your CSV file from the API lookup. For all other rows, a URL is created by concatenating the base URL defined previously with the /vendor endpoint, the domain parameter, and a boolean value to start monitoring the vendor set to true. A GET request with the headers defined will call the API and return the response status code and text.

Save and close the file, ensuring that you have replaced the values for your_api_key and your_vendor_file.

With the script prepared, you can run it to import vendors via the API to start monitoring them with your UpGuard account.

Note: Before running the script, ensure that your CSV file of vendors does not introduce spacing after the comma delimiter. If there is additional spacing before the primary domain, the script will return an error about the hostname string.

Run the script:

$ python importVendors.py

Your terminal will return an output for each vendor, supplying additional information about the vendor's security rating and industry. For example, if you were to start monitoring UpGuard, you would receive a response similar to the following:

200
{"id":5951523917922304,"name":"UpGuard","primary_hostname":"upguard.com","score":942,"overallScore":942,"automatedScore":942,"categoryScores":{"websiteSecurity":936,"emailSecurity":950,"networkSecurity":948,"phishing":950,"brandProtection":950},"industry_sector":"Information Technology","industry_group":"Enterprise Software \u0026 Network Solutions"}

The first line returns the response code: in this case, a successful 200 response.

A JSON output follows with information for each vendor, including their overall score, individual scores in specific areas, and industry information. Because this information is developed through a proprietary system and UpGuard maintains customer confidentiality, this guide will not display additional output for other vendors. You can access this information from your UpGuard account, or you can sign up for a trial account to test it yourself.

Once you have imported your vendors, you can begin using the UpGuard platform to generate reports, send questionnaires to your vendors, and focus on making the internet a safer place overall. You can proceed past the Ruby option to learn more about how to use Vendor Risk with your imported vendor data.

Option 2 — Importing vendor data using Ruby

With Ruby, you can also create scripts to automate your activities. If you are first getting started with Vendor Risk and adding multiple new vendors, you can streamline the onboarding process with a script to import your vendors. This bulk import process will be faster than adding each vendor manually.

To follow this tutorial with Ruby, you will need these additional prerequisites:

Ruby installed on your machine.
Two Ruby gems installed on your machine: httparty and csv.

Preparing your Ruby environment

Before writing scripts in Ruby, you should ensure that you have the necessary prerequisites. If you have confirmed that you have Ruby and the required modules on your machine, you can proceed to the next section. Otherwise, follow the procedure in this section.

To begin, check if you have Ruby installed on your machine:

$ ruby -v

If Ruby is installed, you will receive an output with the version number, such as:

ruby 3.2.2

If Ruby is not installed, you will need to install it now.

For macOS, you can install Ruby with Homebrew:

$ brew install ruby

Note: macOS comes with a version of Ruby already installed. However, you will not be able to change anything with the pre-installed version, so you will not be able to install the required gems for this tutorial unless you install a separate version of Ruby. When you run brew install ruby, follow the recommended steps after installation to ensure that you can modify the new version.

For Linux or WSL, you can install Ruby with your preferred package manager. For example, you could use the to install Ruby with the following command:

$ sudo apt install ruby-full

Confirm that you have installed Ruby:

$ ruby -v

You will now receive an output with the version number, such as:

ruby 3.2.2

Next, you will install the httparty and csv gems. Gems package third-party Ruby libraries that empower you to create complex Ruby scripts.

Note: For macOS, ensure that you have installed a separate version of Ruby that you can modify. Otherwise, you may receive a permissions error that you cannot write to the Ruby directory.

You can use the Ruby Gem installer for both httparty and json:

$ gem install httparty
$ gem install csv

For each gem, you will receive a response in the terminal that the gem is being fetched and installed. To confirm the installations, you can the the command gem list to receive an output of all the Ruby gems that are installed locally on your machine.

Now that you have Ruby and the necessary gems installed on your machine, you can now create the script to retrieve risk details.

Creating and running a Ruby script to import vendor data

In this section, you will create and run a Ruby script to upload your vendor data from the CSV file to your UpGuard account.

First, use your preferred editor to create the script file. This example uses nano:

$ nano importVendors.rb

Add the script, supplying your API key where the example reads your_api_key:

require 'httparty'
require 'csv'$api_key = "your_api_key"
$base_url = "https://cyber-risk.upguard.com/api/public" CSV.foreach("your_vendor_file") do |row|
  vendor = row[0]
  domain = row[1]
  next if vendor == "vendor"  response = HTTParty.get("#{$base_url}/vendor?hostname=#{domain}&start_monitoring=true", 
                         :headers => { "Authorization" => $api_key })   
  puts "#{vendor} (#{domain})"
  puts response.code
  puts response.body
end

To begin, you import the to make HTTP requests to the UpGuard API, using your API key to authenticate with your account, and the to read the CSV file with your vendor information.

Then, you set the $api_key and $base_url variables, supplying your unique alphanumeric code for your_api_key and pointing to the UpGuard public API endpoint.

Next, you use the csv gem to define the input array to supply the vendor name and domain information from your CSV file. Update your_vendor_file with the path to the CSV file you created in Step 1.

Note: If your CSV file includes a heading row (vendor_name,domain), include the next if clause to skip the file's header row during the API lookup. You can omit the next if line if your CSV file does not include the header row.

You use the httparty gem to define two actions. First, you set a GET request to ping the /vendors path, with the variable containing your API key passed to the Authorization header.

Then, you define a PUT method that will return the vendor name, domain, response cody, and response text to your terminal.

Save and close the file, then run it:

$ ruby importVendors.rb

For each new vendor you are adding, you'll receive a terminal response with vendor information in a JSON array. For example, adding UpGuard as a vendor will return the following response:

UpGuard (upguard.com)
200
{"id":5951523917922304,"name":"UpGuard","primary_hostname":"upguard.com","score":942,"overallScore":942,"automatedScore":942,"categoryScores":{"websiteSecurity":936,"emailSecurity":950,"networkSecurity":948,"phishing":950,"brandProtection":950},"industry_sector":"Information Technology","industry_group":"Enterprise Software \u0026 Network Solutions","labels":["test label"]}

The first line returns the vendor by their name and domain. The second line provides the status code for the PUT request: in this case, the 200 code for a successful response.

Now when you access the Vendors module within the UpGuard platform, you will note that all the vendors from your CSV import file have been added to your monitored vendors list.

Using your imported vendor data

By monitoring vendors in UpGuard, you and your team can focus on evaluating and protecting against risks instead of manually tracking individual vendor risk exposures. You can generate reports to understand a vendor's security risk exposure and conduct risk assessment with an automated workflow.

Ensure all vendors are monitored

Cross-reference your monitored vendors in UpGuard with your existing vendor contracts. If any existing vendors have not been added, you can use this same method to add them via the API or add vendors within the platform.

Create a vendor risk management plan

Create a vendor risk management plan to share with your stakeholders. The real-time ratings and label outputs can be used to demonstrate your company's vendor risk exposure. In your annual or semi-annual plan review, you can compare the previous plan's rating data with newly pulled data to evaluate how your security risk exposure is changing with your vendors.

Incorporate vendor security ratings into vendor evaluation

Incorporate UpGuard security ratings into your vendor performance evaluations. Exporting vendor data programmatically empowers you to access only the most salient data for quick scans across your vendor portfolio. You can evaluate that data with UpGuard and send that data to your other business analytics platforms.

Evaluate vendor impact with custom labels

When you apply labels to your vendors, you can make quick assessments about their impact on your organization. The default labels available within the UpGuard platform are In-Use, Business Data, Customer Data, Network Access, and Physical Access, but you can also create custom labels for other parameters.

With vendor labels, you can keep track of which vendors impact specific aspects of your supply chain and create a risk mitigation strategy around those aspects. With the exported vendor data, you can scan your vendors by their labels and ratings to identify which vendors will need follow-up conversations or fully-fledged risk assessments.

Tier your vendors with severity monitoring

Classify your vendors based on their risk exposure by configuring vendor tiers in UpGuard. The risk severity tiers enable you to sort your monitored vendors by their risk level and allocate the appropriate resources to vendor assessment and risk mitigation. When you categorize your vendors according to their risk severity, you can streamline assessments to focus on the vendors who are most critical to your business and ensure their compliance with regulatory standards. Vendor tiers are a useful tool for securing your supply chain against a variety of vulnerabilities because you can evaluate vendors according to their risk profile and public attack surface.