Before you can coordinate best practices for your organization's security plan, you need to know the full extent of external risks facing your organization but identifying these risks manually can be time-consuming and labor-intensive. With UpGuard BreachSight, you gain insight to your organization's risk profile and the cybersecurity risk factors in your publicly accessible information.

Using the UpGuard API, you can retrieve available risks within the platform, including a list of active risks detected for your account. You can always evaluate your risk profile directly within the UpGuard platform. With the UpGuard API, you can retrieve the same information from the command line and incorporate it into your security hardening process.

In this guide, you will retrieve only those risks detected for your account. You will choose from the provided options to interface with the UpGuard API through curl, Python, or Ruby.

You can use the curl command to retrieve information from the internet directly within your command line terminal. You supply the options necessary to retrieve specific information against an existing URL. In this option, you will run curl against the UpGuard API to authenticate with your UpGuard account and retrieve risk details for your account.

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

In this step, you will run a curl command to retrieve your account's active risks 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:

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:

You set a custom header with the --header flag, specifying that your terminal 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 /risks path will return a list of risks detected for your account, 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 risk, which you can then apply transformations to sort. Your output may be quite lengthy.

You'll receive an output similar to this example but with risks for your account:

You can also pipe the output through jq to pretty-print the response in a more readable format:

The CSV format will be parsed into a JSON array:

The PHP end-of-life finding is an example for one risk that might be associated with accounts. Your list of risks will differ.

Returning all risks detected for your account is a crucial step in planning your security updates. If you only want to retrieve information for a specific risk in the list, you can supply additional parameters, which you will do next.

When you are coordinating your risk remediation plan, you may wish to evaluate a specific risk. The UpGuard API provides a distinct path for calling specific risk details, so you will modify the curl command in this step to retrieve information for only one risk. This step will proceed with the end-of-life PHP vulnerability returned in the previous step.

First, note the id string for the given risk. The risk_id for the sample PHP risk is end_of_life_product_provisional:cpe:/a:php:php.

You'll be sending a request to the available risks endpoint (/available_risks/v2) and appending the specific risk ID to the URL:

You've revised the URL to point to the available risks metadata and, more specifically, to an individual risk ID.

If you don't use jq to transform the data, it will return in a comma-separated format. If you pipe the output through jq, you will receive a readable response in your terminal:

The remediation attribute provides information about the type of risk and a recommendation for risk remediation, which may be beneficial as you plan your risk management process. For more information on each of the risk details, move section titled Evaluating risk details.

If you are interested in automating this GET request as a Python or Ruby script, follow the procedure in the next section.

With Python, you can work quickly and automate tasks like GET requests. Python's precise syntax enables you to create custom scripts that can complete complex actions consistently. As you evaluate risks and vulnerabilities in your software supply chain, you may want to build systems to complete tasks quickly and efficiently in a sequential order. In this section, you will build two short scripts to retrieve risk details from UpGuard, but you can combine this script with other Python syntax to accommodate your larger needs.

To follow this tutorial with Python, you will need Python installed on your machine with a virtual environment set up.

In this step, you will activate a Python virtual environment that was set up with the venv module. 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:

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

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

With the environment running, you can now create and run a script to retrieve risk details.

In this step, you will create and run a Python script to retrieve the risks detected for your account.

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

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

First, you import the requests library, which you will use to send a GET request.

Then, you set three variables that will be used in the script. Be sure to update your_api_key with the alphanumeric string associated with your account so that the api_key variable can be called to authorize your request.

Note: For an added layer of security, you can set your API key in a .env file in the root directory of your Python environment and call that file within the script using a package such as python-dotenv, which will ensure that your API key is not stored in the script. We have not evaluated the security of external packages like python-dotenv, and you should consult with your security team regarding the introduction of any new tooling.

Finally, you define the GET request with two arguments: the base_url endpoint directing to the /risks path and authorization using your API key as a headers variable. The response will be stored in the response variable. The status_code and text attributes of the response object will be printed to your terminal window.

Save and close the file, then run the script:

You'll receive a CSV response similar to this output but with risks detected for your account:

The first line returns the status code for the ping. This output returns 200 for a successful request.

Note: If you receive a 422 error response, review the error message to update your parameters. A 500 error response returns when a system error occurs. In that case, review the error message and try again later.

The subsequent array provides details for the risks detected for your account. The sample output provides details for only one risk but your response will likely include more.

To pretty-print the output, you'll update the Python script. Open the script file:

You'll be modifying the response output to use the json module:

You add the json module to your import syntax. The variables and GET request remain as written, storing the response in a response variable.

You then modify the output as a formatted_string variable. You use the formatted_string variable to prettify the JSON output in a human-readable format. The json.dumps() function will apply a JSON transformation to the response output with an indentation of four spaces. You can set other formatting needs if you wish. When you print attributes of the response, you swap the text attribute for the new formatted string variable, which moves the response text into a JSON array.

Save and close the updated file, then run it:

You'll receive a newly formatted JSON array for the output:

To send the output to a new file, append the command with an output redirection to a file using the > operator:

With this redirection, the output will be saved to a file named getRisks.txt (but you can supply whatever file name you like) instead of displaying in your terminal. You can run cat to display the new file in the terminal in order to confirm the redirection, or you can access the file in your machine's document structure as needed.

Risk detection for your account follows the scanning protocols that UpGuard has in place, including port scanning and risk data collection, so you may opt to run a risk detection script periodically. Assessing risks detected on a regular cadence will ensure that you can prioritize according to your remediation process.

In this step, you retrieved information for all risks detected for your account. Next, you'll retrieve details for one specific risk by its risk identification label.

If you know the risk id for a particular risk, you can retrieve the details quickly with a call to the UpGuard API. In this step, you'll retrieve information for the same sample risk that has been used throughout this guide: the PHP end-of-life provisional risk.

You'll create a new scripting file. Provide any name that you will remember; this example uses getOneRisk.py:

You'll use the same script as in the previous step, updating it to include a parameter query and a different URL endpoint:

Be sure to supply your unique alphanumeric API key.

You add a new params variable with the risk_id query. In this example, you provide the string for the PHP end-of-life risk, but you can optionally supply a different risk_id string. You also update the GET request to call the /available_risks/risk path and include the params variable in the call.

Save and close the file, then run the script. You'll receive an output with the status_code followed by the risk details:

You can modify the file with the same adjustments as in the previous step in order to prettify the JSON output. You can also append the command with the redirection operator to save the output to a named file.

If you are interested in automating this GET request as a Ruby script, follow the procedure in the next section. Otherwise, proceed to the Evaluating risk details section for more information on the details that return.

You can use Ruby to process data retrieved from the web. Like Python, Ruby can be helpful in automating tasks with a logical script. As you evaluate risks and vulnerabilities in your software supply chain, you may want to build systems to complete tasks quickly and efficiently in a sequential order. In this section, you will build two short scripts to retrieve risk 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:

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:

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

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

For macOS, you can install Ruby with Homebrew:

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:

Confirm that you have installed Ruby:

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

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:

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.

Note: The pp gem comes packaged with Ruby. If you installed a fresh version of Ruby, you can run gem list to confirm that pp is available. Otherwise, run gem install pp to ensure it is available.

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

In this step, you will create and run a Ruby script to retrieve the risks detected for your account.

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

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

First, you define the three gems that will be used in this script: - httparty to run the GET request. - json to parse the response output. - pp to pretty-print the output in a readable format.

Note: You can optionally omit the pp gem and provide a standard puts or print method to return the response output. If you make this adjustment, the output will return in a CSV format rather than a readable JSON array.

You then set two variables: one for your unique alphanumeric API key and one for the public API endpoint.

Next, you define the GET request to point to the /risks path on the endpoint, calling your API key to authorize the request.

Finally, you parse the response output and pretty-print it to your terminal.

Save and close the file, then run it:

You'll receive a response similar to following (truncated for length):

Note: If you modify the line from pp to a puts or print method, your output will be in a CSV format.

Now that you can retrieve all risks for your account, you'll create another risk to return details for one specific risk.

When you know the risk id for a particular risk, you can retrieve the details quickly with a call to the UpGuard API. In this step, you'll retrieve information for the same sample risk that has been used throughout this guide: the PHP end-of-life provisional risk.

You'll create a new scripting file. Provide any name that you will remember:

You'll use the same script as in the previous step, updating it to include a parameter query and a different URL endpoint:

You set the parameter and then call it in the GET request.

Save and close the file, then run it:

You'll receive an output for the specified risk:

Note: The current Ruby script will output the data in a readable JSON array. You can optionally replace the pp method with a puts or print method, which will return the output in a CSV format.

You can redirect the output while running the script to save it to a new file, or you can update the script to save the response to a file.

The remediation attribute provides information about the type of risk and a recommendation for risk remediation, which may be beneficial as you plan your risk management process. In the next section, you will review the various attributes for details.

For each individual risk, the response details will include an array containing some of available attribute responses. You can use these details to coordinate your risk remediation plan and otherwise provision security updates to your supply chain. This section will explain the aspects of the response schema, using the PHP end-of-life risk as the example risk.

The response schema may include any of the following 11 attributes when retrieving all active risks for your account:

For example, the following output indicates the PHP end-of-life risk when it appears in a list of risks:

This particular risk is a high severity vulnerability in the Website Security category and impacts the sample hostname warning.be. The resulting recommendation would be to assess and update the PHP version associated with that domain.

When retrieving only one specific risk, the response schema may include these additional attributes:

Retrieving details for only the specific sample risk will return an output like the following:

This response includes more information on the risk type, indicates that the risk is unique rather than generic, and provides a recommendation for risk mitigation.

Retrieving details for specific risks can support your risk remediation planning and organizational processes.

To learn more about risk management with UpGuard, read these articles next: