Designing an API Integration Product Requirement Document
Introduction
This article goes straight to the point- below, I provide a basic PRD describing how cyber security firm Palo Alto should integrate VirusTotal (VT) into their XSOAR platform. Hopefully this example will give you a feel for how a technical PRD should look like.
A brief explanation of XSOAR: XSOAR is a threat intelligence management platform. Basically, this product is deployed for large organizations, connects to their existing cyber defense tools, and helps Security Analysts on SOC teams manage all kinds of cyber security threats on one platform. This is done with the help of automated detection and playbooks that can be created in order to dictate how to handle different threat scenarios.
VirusTotal Integration into XSOAR PRD Example
Background
Palo Alto’s mission is to be the cybersecurity partner of choice, protecting our digital way of life.
VirusTotal aggregates many antivirus products and online scan engines to check for viruses or malicious URLs. This powerful service can greatly help our clients by further protecting them, and therefore aligns well with our mission.
In order to better protect our clients, we feel that integrating VirusTotal into XSOAR will help mitigate even more threats than ever before, and will greatly improve our product.
Objective
Seamlessly integrate VirusTotal into XSOAR to allow system analysis and automated threat response to improve the efficiency of SOC teams by leveraging VirusTotal’s capabilities.
Success metrics
Users
The users are security analysts who are part of a SOC team
Terminology
VT: VirusTotal
VT License
We will be using the public API only
Requirements/Use Cases
Note: ‘Scan’ and ‘Get report’ will be used interchangeably in this section. e.g., scanning means the ability to scan a resource and also to see the result
Design
Configuration
An API key is needed, after it is obtained through registration to VT, it should be included in all request headers. Each client should insert their key into the VT key field in our system to allow communication.
API Commands
The following VT commands should be used:
For complete documentation, please see https://developers.virustotal.com/reference
Response Codes
When interacting with the API, if the request was correctly handled by the server and no errors were produced, a 200 HTTP status code will be returned. The body of the response will usually be a JSON object (except for file downloads) that will contain at least the following two properties:
- response_code: if the item you searched for was not present in VirusTotal’s dataset this result will be 0. If the requested item is still queued for analysis it will be -2. If the item was indeed present and it could be retrieved it will be 1. Any other case is detailed in the full reference.
- verbose_msg: provides verbose information regarding the response_code property.
In case of an error you can get any of the following status codes:
In case we get a bad response code, the system should notify the user with the reason and log the response.
Information and screens to be Displayed to Analysts
For scanning a file/url/domain/IP, the user should see a similar screen to this (exclude search tab):
After entering the resource, we should get a screen that displays the detailed info of the resource (Detection provider results, resource details, community comments, etc.)
The data for this screen can be extracted from the ‘total’ and ‘scans’ fields.
After clicking details, we should see something similar to this:
The details should be extracted from the appropriate JSON per resource type.
Examples:
For a file, these details should include: MD5, SHA-1, etc.
For a URL, URL Categories, general info, response content, etc.
The same can be said for domain and IP.
When clicking the comment tab we should see the different comments that exist for the resource. Example screen:
Regarding the rest of the requirements in the requirement section, the user should be able to view UI commands in the standard fashion when interacting with our system (alerts, playbooks, history, etc.)
A Brief Review of What I Did in this PRD
A PRD’s layout and basic structure can be generated in Confluence, which isn’t too hard to set up if it’s your first time.
The structure I chose here is:
- Background/Overview — A general background that gives some context to the document and what we’re trying to do
- Goals — Describe what the company is trying to achieve with this product
- Use cases/User stories — Important to describe what functionality is required and to help the developers understand the user needs. It’s important to use a structured user story approach for clarity, and to prioritize them for engineering. Here, I used the MoSCoW method
- Actual API technical design which answers the criteria of the user stories — this document doesn’t dive into extreme detail, but things such as timeouts, or really diving into the different types of flows for the requests and responses are important here.
- UX screens and flows
That’s it, I hope you found this article useful!
