Bulk Export Vendor Information

• Overview
• Export with curl
• Export with Ruby
• Use your exported vendor data

Overview

You can see your monitored vendors' primary domains and current security ratings in the Vendors module. To use that data in other vendor assessment processes, export it from UpGuard's public API with the API key associated with your organization's account. Choose a method:

• curl: retrieve your vendors in the terminal, use jq to select each vendor's name, primary domain, security rating, and labels, and save them to a file.
• Ruby: run a short script that exports your vendors as a comma-separated value (CSV) file, with name, primary_domain, score, and labels columns.

Before you start, you need:

• An UpGuard account with an API key. To set one up, see How to authenticate with your UpGuard API key. If you don't have an account, sign up for a free trial.
• Vendors you're monitoring. To add vendors, see Monitor a new vendor or How to bulk import vendor information.

Export with curl

curl retrieves data from the internet in your terminal, and its options let you customize what it retrieves. You need curl and jq installed on your machine.

1. Open a terminal window and set your API key as a variable. Replace your_api_key with your API key:

$ API_KEY=your_api_key

With the variable set, you don't have to enter the key in every command.

2. Retrieve your monitored vendors:

$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors"

The -H flag sends your API key in the Authorization header. The /vendors path returns a list of your monitored vendors in JSON, with a variety of information about each one. The output may be long, depending on how many vendors you monitor.

3. Run the same command, piped to jq, to select each vendor's name, primary_domain, score, and labels:

$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors" | jq '.vendors[] | [.name, .primary_domain, .score, .labels]'

Each vendor is returned as an array in this format:

[
  "UpGuard",
  null,
  942,
  []
]

Here, the vendor is UpGuard, it has no associated domain (null), and its security rating is 942. Labels appear last. The empty brackets ([]) mean no labels are applied to UpGuard in the sample account.

4. Save the output to a file by redirecting it:

$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors" | jq '.vendors[] | [.name, .primary_domain, .score, .labels]' > exportedVendorData.csv

Your vendor data is saved in exportedVendorData.csv.

Export with Ruby

This method uses a short script to retrieve your vendor details. You can combine it with other Ruby code for your own needs. You need Ruby and two Ruby gems, httparty and json. Gems package third-party Ruby libraries.

1. Check whether Ruby is installed:

$ ruby -v

If it is, the output shows the version number, such as ruby 3.2.2. If you already have Ruby and both gems, skip to step 4.

2. If Ruby isn't installed, or you're on macOS with only the preinstalled version, install Ruby:

a. On macOS, install Ruby with Homebrew:

$ brew install ruby

After installation, follow the recommended steps so you can modify the new version.

b. On Linux or WSL, use your preferred package manager. For example, with the apt package manager:

$ sudo apt install ruby-full

Then run ruby -v again to confirm the install. The output shows the version number, such as ruby 3.2.2.

3. Install the httparty and json gems:

$ gem install httparty
$ gem install json

The terminal shows each gem being fetched and installed. To confirm, run gem list to see all the Ruby gems installed on your machine.

4. Create the script file in your preferred editor. This example uses nano:

$ nano exportVendors.rb

5. Add this script, replacing your_api_key with your API key:

require 'httparty'
require 'json'$api_key = "your_api_key"
$base_url = "https://cyber-risk.upguard.com/api/public"response = HTTParty.get("#{$base_url}/vendors",
                        :headers => { "Authorization" => $api_key })header_row = [ "name", "primary_domain", "score", "labels" ]
puts header_row.join(",")obj = JSON.parse(response.body)
obj["vendors"].each do |vendor|
    columns = [
        vendor["name"],
        vendor["primary_domain"],
        vendor["score"],
        vendor["labels"].join(",")
    ]    puts columns.join(",")
end

The script:

• Imports the httparty gem to make HTTP requests to the UpGuard API, and the json gem to parse the JSON payload returned with your vendor data.
• Sets $api_key to your API key and $base_url to the UpGuard public API endpoint.
• Sends a GET request to the /vendors path, with your API key in the Authorization header.
• Prints a CSV header row with the column names.
• Parses the response and, for each vendor you monitor, prints a comma-separated row with its name, primary_domain, score, and labels.

6. Save and close the file.

7. Run the script:

$ ruby exportVendors.rb

If you monitor a large number of vendors, it may take a long time to complete. The script prints your monitored vendors to the terminal in CSV format:

name,primary_domain,score,labels
Mock-vendor,fake_url.pretend,878,
UpGuard,upguard.com,942,

In this example, two vendors are returned, each with its domain and security rating. Mock-vendor is made up to show a second result. No labels appear because none are applied to these vendors.

8. To save the output to a file, redirect it with the > operator:

$ ruby exportVendors.rb > exportedVendorData.csv

The output is saved to exportedVendorData.csv instead of appearing in the terminal. You can use any file name.

9. Display the file in the terminal with cat:

$ cat exportedVendorData.csv

It shows the same output as step 7.

Your vendor data is saved in a file on your machine. Run the script whenever you need to export it again, or automate it as part of your own process.

Use your exported vendor data

Bring data about your monitored vendors into your wider vendor risk assessment process, and automate real-time updates so you can focus on remediating risks:

• Keep a record of every vendor. Cross-reference your monitored vendors with your existing vendor contracts, and bulk import missing vendors with the API or add them in the platform. You don't have to monitor every vendor you add. On paid plans, you can keep vendors you don't need to continuously monitor on the Not monitored tab, where they don't use a monitoring slot. See Vendor Risk: Not Monitored Vendors.
• Let monitoring do the tracking. When you monitor vendors in UpGuard, your team can focus on evaluating and protecting against risks instead of tracking each vendor's risks by hand. You can also run risk assessments on monitored vendors with an automated workflow. Monitoring a vendor you haven't monitored in the last 12 months uses a change. See Vendor Risk: Monitoring Slots and Change Limit.
• Create a vendor risk management plan. Share a vendor risk management plan with your stakeholders. Use real-time ratings and label outputs to show your company's vendor risk exposure. At each annual or semi-annual review, compare the previous plan's rating data with newly exported data to see how your risk exposure with your vendors is changing.
• Use security ratings in vendor evaluations. Include UpGuard security ratings in your vendor performance evaluations. An export gives you only the data you need for quick scans across your vendor portfolio. Evaluate it in UpGuard, and send it to your other business analytics platforms.
• Integrate UpGuard data with your workflows. Maintain your risk management lifecycle process both within the UpGuard platform and in your external workflow tools. Set up integrations to send notifications from UpGuard to other applications, such as Slack, Jira, and applications connected through Zapier.
• Evaluate vendor impact with labels. Apply labels to your vendors to quickly assess their impact on your organization. Labels can show a vendor's access, or other criteria you define for vendor and supplier risk. The default labels are In-Use, Business Data, Customer Data, Network Access, and Physical Access, and you can create custom labels.
• Scan your export by label and rating. Use labels to track which vendors affect specific parts of your supply chain, and build a risk mitigation strategy around them. In your exported data, find the vendors that need a follow-up conversation or a full risk assessment.