How to request a report via the UpGuard API

Request a report to be delivered from the UpGuard platform.

Written by Kurt Brown

UpGuard contains an extensive library of report templates that are accessible through the UI. This article explains the steps to follow to access these reports via our API.

In this tutorial, you will request a specific report through the command line. You will then use the response to verify the report status and to access and download the generated report content via PDF. You can choose from the provided options to interface with the UpGuard API through curl or you can use these guidelines to help implement the API call through other means.

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 an account, sign up for a free trial.
If you are planning on requesting reports via the API, your API key needs to have write access allocated to it.
Depending on the report content you request, you will also need to provide
- Vendors that you are currently monitoring. Follow our guide on how to add vendors within the platform or the API, and optionally vendors allocated to portfolios
- Domains that you are currently monitoring within Breachsight. Follow our guide on how to add domains within the platform or the API, and optionally domains grouped into asset portfolios.
Familiarity with the UpGuard API. In this tutorial, you will use the query parameters to request a report and optionally to check the status of the request.
Either an email address to receive the generated PDF or a Webhook URL to be invoked. If neither is provided you will need to use a script to poll the status of the report generation and download the PDF once the report is complete.

API definition and parameters

This API asynchronously queues a report for exporting. To use this API, first call this endpoint with the type of report you wish to generate and any other filtering parameters. You can optionally specify a list of email addresses (to receive a copy of the final report via email), or a URL that will receive a POST request when the export completes.

When a report request is queued, you will receive a unique queued_report_id. Use this ID to check the status of the export using the reports/status endpoint.

report_type - Required - The type of report to export. Note that each report type may require different parameters to be specified in the request.
email_addresses - Optionally email the generated report to the specified addresses
post_webhook_url - Optionally specify a URL that will receive a POST request when the report is ready.
asset_portfolio_names - Filter by asset portfolio names. Case-sensitive. Optional. Applicable only when report_type is BreachSightSummaryPDF or BreachSightDetailedPDF.
vendor_portfolio_names - Filter by vendor portfolio names. Case-sensitive. Optional. Applicable only when report_type is BoardSummaryPDF, BoardSummaryPPTX, or VendorRiskExecutiveSummaryPDF.
vendor_id - ID of the vendor to generate the report for. Either this or vendor_primary_hostname is required when report_type is VendorSummaryPDF or VendorDetailedPDF.
vendor_primary_hostname - Primary hostname of the vendor to generate the report for. Either this or vendor_id is required when report_type is VendorSummaryPDF or VendorDetailedPDF.
custom_report_uuid - If the report type you've selected is CustomPDF, then the unique identifier for the required custom report should be supplied. Use the /reports/custom API endpoint to determine the unique identifier for your desired report
filename_prefix - Provide up to 20 characters of text that you would like the report filename to start with. Typically replaces the report name as the filename prefix.
wait_for_data - When vendors have been newly monitored, there is a certain period of time before a comprehensive set of data has been collected. For vendor report requests, then parameter indicates that the system should wait for comprehensive data collection before generating the report.

There are three ways to access the generated report content. The response to the report request will provide a queued_report_id that can be used to call the /reports/status API endpoint. Once the report is complete the response to this API call will contain a URL that can be used to access the report content. Additionally, two parameters can be used to optionally set the report destination:

email_addresses - upon completion, the exported PDF will be sent to these email addresses
post_webhook_url - upon completion, this URL will be called with the PDF delivered inside the HTTP content. The HTTP content will contain a JSON body containing a URL to download the report, in the following format:
```
{ 
    "queued_report_id": "string", 
    "download_url": "url", 
    "download_url_expires": "string" 
} 
```

The report_type (and custom_report_uuid) parameters will dictate which report is generated. There are a variety of reports available via the platform, with some requiring additional parameters.

BoardSummaryPDF - Operational awareness at the highest level, showing key factors of your overall security posture. This report optionally supports the use of the vendor_portfolio_names parameter.
BoardSummaryPPTX - PowerPoint presentation showing key factors of your overall security posture. This report optionally supports the use of the vendor_portfolio_names parameter.
BreachSightSummaryPDF - Quickly understand your attack surface with this executive-level summary. This report optionally supports the use of the asset_portfolio_names parameter.
BreachSightDetailedPDF - Drill down into the important details of your attack surface with this highly customizable report. This report optionally supports the use of the asset_portfolio_names parameter.
VendorRiskExecutiveSummaryPDF - Gain insight into your entire vendor portfolio with this executive-level summary showing current postures, high-level trends, and areas for improvement. This report optionally supports the use of the vendor_portfolio_names parameter.
VendorSummaryPDF - Understand a vendor's cyber risk at a glance with this executive summary. This report requires either a vendor_id or a vendor_primary_hostname to be provided to identify the target Vendor.
VendorDetailedPDF - Drill down into the specifics of a vendor's risk profile with this highly customizable report. This report requires either a vendor_id or a vendor_primary_hostname to be provided to identify the target Vendor.
VendorRiskAssessmentPDF - Visualize a comprehensive picture of risk for any vendor with a completed UpGuard Risk Assessment. This report requires either a vendor_id or a vendor_primary_hostname to be provided to identify the target Vendor, and request will generate the last published risk assessment report
VendorDetailedPDF - Drill down into the specifics of a vendor's risk profile with this highly customizable report. This report requires either a vendor_id or a vendor_primary_hostname to be provided to identify the target Vendor.
CustomPDF - Generate one of your custom report templates. This template can be vendor-specific, and is identified via the value given in parameter custom_report_uuid.
VendorRiskProfileXLSX: Summarizes the risks detected for a specific vendor in excel format.
VendorVulnsOverviewXLSX - Lists the vulnerabilities found for a specific vendor in excel format
VendorDomainListPDF - Lists the domains for a specific vendor, their associated IP addresses and their status.

Example — Using curl to request a report

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 request a report to be queued.

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

curl installed on your machine.
jq, a command-line JSON processing tool, installed on your machine.

Step 1 — Requesting a report

In this step, you will run a curl command to request a report directly within the command line. In this example, we will request the Vendor Detailed Report for a Vendor with a domain of example.com.

Open a terminal window and set the API key, providing the unique alphanumeric string for your 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 retrieve information from UpGuard:

$ curl --request GET \ --header "Authorization: $API_KEY" \ --url "https://cyber-risk.upguard.com/api/public/reports/queue?report_type=VendorDetailedPDF&vendor_primary_hostname=example.com"

You run a GET request that will authenticate using your API variable and retrieve information from the /reports/queue path to run the report of type report_type for the vendor specified by the vendor_primary_hostname parameter. This example retrieves information for example.com, but you can supply a different vendor domain or a vendor_id instead.

You'll receive a response similar to the following:

{"queued_report_id": "1cf1b1ad-2db8-4c3f-9b7f-9e61ee932dd6"}

Once you have a queued_report_d, you can check the status of the request and obtain the download URL using the method described in Step 2 of our tutorial.

Step 2 — Get the status of an export Report

Once you have queued a report for execution there are a variety of delivery methods. The report may be emailed to the email addresses specified, delivered via a URL within the webhook activation, or by using the URL within this API call.

In this step, you will retrieve and download the report content programmatically with the UpGuard API.

There is 1 query parameter to provide when retrieving the report status:

queued_report_id: the id returned in the response in Step 1.

$ curl --request GET \ --header "Authorization: $API_KEY" \ --url "https://cyber-risk.upguard.com/api/public/reports/status?queued_report_id=1cf1b1ad-2db8-4c3f-9b7f-9e61ee932dd6"

Whilst the report is still queued, you will receive a response similar to the following:

{
    "status": "pending"
}

Once the report is complete, you'll receive a response similar to the following:

{
    "status": "completed",
    "download_url": "https://cyber-risk.upguard.com/api/public/reports/download?id=1cf1b1ad-2db8-4c3f-9b7f-9e61ee932dd6"
    "download_url_expires": "2024-03-13T01:59:57Z"
}

The URL contained within download_url can be used to access the content.