When you first create your account in CyberRisk you can use the API to bulk import vendors you want to watch and monitor.

Overview

UpGuard CyberRisk provides a public API to enable you to add and view vendor information by primary domain. When you are first setting up your account it may be useful to bulk import a pre-existing list of vendors so you can get up and running quickly. This guide shows you how to leverage the API to import vendors from a CSV file.

Here we are going to:

  • Prepare our vendors into the correct format for bulk import,
  • Prepare a sample script to import the vendors via the API

Preparing your list of vendors

UpGuard CyberRisk uses the primary domain name of a vendor as a unique way to identify a vendor. This prevents any ambiguity that may arise between Apple the multi-national technology company and Apple, the record producer. So, when preparing your list of vendors you will need to assign each their primary domain name. Here’s an example of a prepare spreadsheet of some vendors of UpGuard.

Vendor Domain
Google google.com
auth0 auth0.com
Taco Bell tacobell.com

If you have your list of vendors and their domains in a spreadsheet, you can export to CSV for the next section. When importing vendors via the API, we only technically need the primary domain, but most customers also list the name of the vendor, so we’re going to use a vendor name and domain setup for the example shown on this page.

Locating your API Key

To access your API key, navigate to the Account Settings page in the top right menu.

w400

Then navigate to the API tab. If you have not generated an API key before, you can generate one by clicking generate one here.

w400

Building and Running the Import Script

Here we have provided a few sample scripts that can ingest the above two column CSV file format and import vendors into your account. You will need to substitute your own API Key into these scripts in place of the sample key. If you don’t see your preferred scripting language below, please contact UpGuard Support and we can add more examples to this page.

For more information on the endpoint we are using here, please visit Get vendor details.

Ruby

require 'httparty'
require 'csv'

$api_key = "1234-567-89..."
$base_url = "https://cyber-risk.upguard.com/api/public"

CSV.foreach("vendors.csv") do |row|
  vendor = row[0]
  domain = row[1]
  next if vendor == "vendor"  # trying to ignore the header first line of the CSV file

  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

Note: the line next if vendor == "vendor" is an attempt to not include the header row of the CSV file as an API lookup. You could additionally export your vendor list to CSV without the header vendor_name,domain row.

Bash/Curl

#!/bin/bash

API_KEY="1234-567-89..."

for d in `cat vendors.csv | awk -F "," '{print $NF}' | grep -vE "^domain$"
do
    curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendor?hostname=$d&start_monitoring=true"
done

Note: The grep -vE "^domain$" part of the script below is an attempt to ignore the header row of your CSV file. You could additionally not export spreadsheet headers to your CSV file or manually delete the header row before importing.

What Next?

For more information on viewing the security score and risks of particular vendors, please refer to our guide on Monitored Vendors.

If you would like to start sending Security Questionnaires to your vendors, please refer to our Vendor Questionnaires guide.

Tags: cyber risk