Export the name, primary domain, security rating, and labels for your monitored vendors by using the UpGuard API.
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.
By monitoring vendors in UpGuard, you have access to information about the vendor's primary domain and their current cybersecurity rating score. You can always access this information in the Vendors module, but you can also export the information from UpGuard's public API endpoint and then incorporate that information into other vendor assessment processes.
In this guide, you will export UpGuard data for your monitored vendors to a comma-separated value (CSV) format. You will choose from the provided options to interface with the UpGuard API through curl or Ruby. Finally, you will evaluate different options for using the data for your third-party risk management needs.
-
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.
-
Vendors that you are currently monitoring. Follow our guide on how to add vendors within the platform or via the API.
Option 1 — Exporting vendor information with curl
The curl command returns information from the internet in your command line terminal. By adding various options, you can customize what information is retrieved. In this section, you will run curl against the UpGuard API to authenticate with your UpGuard account and export information for the vendors you are currently monitoring.
To follow this section, you will need these additional prerequisites:
Step 1 — Retrieving vendor information with curl
In this step, you will run a curl command to retrieve your monitored vendor directly within the command line.
Open a terminal window and set the API key, providing the unique alphanumeric string for your personal API key where the sample below reads your_api_key:
$ API_KEY=your_api_key
Setting the API_KEY variable ensures that you can call it directly in future commands without providing the unique key in every command.
Run curl to pull information from your account:
$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors"
You set a custom header with the -H flag, specifying that your shell is authorized with the API key you provided earlier. Because you have already set the API_KEY variable with your unique key, you call the variable directly.
You then provide an endpoint within the UpGuard platform to generate a response. The /vendors path will return a list of your monitored vendors, but you can use any of the options available in our API documentation to test this feature. The base URL for all public endpoints is https://cyber-risk.upguard.com/api/public.
You'll receive a response in the form of a comma-separated value (CSV) list with all of the vendors you currently monitor and a variety of information related to each vendor, which you can then apply transformations to sort. Your output may be quite lengthy, depending on your list of vendors.
In the next step, you will save the vendor data to a new file with a jQuery transformation to organize it.
Step 2 — Saving the vendor data retrieved by curl
In this step, you will transform the data you just retrieved by applying a JSON transformation with jq . You'll then redirect the output to a file to save it for future reference.
Run the same curl command as in the previous step, and pipe the output into an array:
$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors" | jq '.vendors[] | [.name, .primary_domain, .score, .labels]'
With this jq command appended to the initial curl command, you create an array for the vendor information that is sorted by the name, primary_domain, score, and label properties.
You'll receive an output that follows this format:
[
"UpGuard",
null,
942,
[]
]
In this output, the vendor is UpGuard. There is no associated domain, so the response is null, while the current security rating follows (in this example, 942). If you have applied labels to your vendor, those will appear in the last line; because there are no labels applied to UpGuard in the sample account, the empty brackets ([]) load instead.
Save the transformed JSON data to a file by redirecting the output to a new, named file:
$ curl -H "Authorization: $API_KEY" "https://cyber-risk.upguard.com/api/public/vendors" | jq '.vendors[] | [.name, .primary_domain, .score, .labels]' > exportedVendorData.csv
You ran a jq command to organize this information from the command line and saved it for later use according to your business needs.
Option 2 — Exporting vendor information with Ruby
You can use Ruby to process data retrieved from the web. Ruby can be helpful in automating tasks with a custom script. In this section, you will build two short scripts to retrieve vendor details from UpGuard, but you can combine this script with other Ruby syntax to accommodate your larger needs.
To follow this tutorial with Ruby, you will need these additional prerequisites:
Step 1 — 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 Step 2. 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 apt package manager 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 json 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 json
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 export vendor information.
Step 2 — Exporting your vendor data with Ruby
In this step, you will create and run a Ruby script to generate and export a four-column CSV output with headers for name, primary_domain, score, and labels.
First, use your preferred editor to create the script file. This example uses nano:
$ nano exportVendors.rb
Add the following script, which will interface with the UpGuard API to return monitored vendors for your account:
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
To begin, you import the httparty gem to make HTTP requests to the UpGuard API, using your API key to authenticate with your account, and the json gem to parse the JSON payload that returns with your vendor data.
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 httparty gem to define the GET request, which will ping the /vendors path, with the variable containing your API key passed to the Authorization header.
You then define the output array. Because your script will generate a CSV output, you define the header row with the column names in a comma-separated format.
Finally, you use the json gem with a parse method to iterate over the array of vendors. For each vendor you are currently monitoring in UpGuard, the name, primary_domain, score, and labels will be stored in comma-separated columns array that prints to your terminal.
Save and close the file.
You are now ready to run it and export your vendor data:
$ ruby exportVendors.rb
If you are monitoring a large number of vendors, the script may take a long time to complete. You'll receive an output response with your monitored vendors in comma-separated format:
name,primary_domain,score,labels
Mock-vendor,fake_url.pretend,878,
UpGuard,upguard.com,942,
In this example, two vendors are returned: Mock-vendor and UpGuard. The information for Mock-vendor is made up for the purpose of displaying two vendor results. Each vendor includes their domain and security rating. In this case, the user running the script has not applied any labels to their monitored vendors so none appear.
The current Ruby script will only output the data in a CSV format. If you need to save the data in a file for later use, you can redirect the output while running the script.
To redirect the output in your terminal, append the command with an output redirection to a file using the > operator:
$ ruby exportVendors.rb > exportedVendorData.csv
In the previous step, the output would load directly in the terminal. With this redirection, the output will be saved to a file named exportedVendorData.csv (but you can supply whatever file name you like).
Run cat to display the file in the terminal:
$ cat exportedVendorData.csv
You will receive the same output as when the data is returned directly in the terminal:
name,primary_domain,score,labels
Mock-vendor,fake_url.pretend,878,
UpGuard,upguard.com,942,
You can now access this file in your machine's document structure as needed.
Note: Because the security score represents the score on the date of export, consider re-running the script to generate up-to-date information whenever you need to use security rating data outside the UpGuard platform.
You can now automate your vendor information process to export specified vendor data for use according to your business needs.
Using your exported vendor data
With the ability to access data about your monitored vendors, you can incorporate that data into your full vendor risk assessment process and automate real-time updates so you can focus on remediating risk exposures.
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 bulk import those vendors via the API or add vendors within the platform. 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 instant reports to understand a vendor's security risk exposure and conduct risk assessment with an automated workflow.
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.
Integrate UpGuard data with your workflows
Maintain your risk management lifecycle process both within the UpGuard platform and in your external workflow tools. You can set up integrations to send notifications from UpGuard to other applications, like Slack, Jira, and applications through Zapier. Integrations like these enable you to make the most use of your UpGuard account and the data you have access to.
Evaluate vendor impact with custom labels
The sample output in the previous steps did not include any labels applied to the vendors because the testing account did not incorporate labels. However, your third-party risk assessment processes for vendor and supplier risk benefits from clear labels that distinguish vendor access or other criteria you have defined.
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.
See also: