This guide explains how to set up your first API scan profile in Detectify. Our API scanning feature uses your API specification file to discover and test your endpoints for security vulnerabilities.
Before You Begin
You'll need two things to get started:
An API Specification File: We support OpenAPI v2 and v3. Your file can be in .json, .yaml, or .yml format, with a maximum size of 1 MB. The file must contain one or more server addresses in the servers field.
Authentication Details: If your API requires an API key, have the key's name (the header, query, or cookie name) and its value ready.
How to Set Up an API Scan
Step 1: Navigate to API Scanning
From the main navigation menu in your Detectify account, click the "API Scanning" item.
Step 2: Create a New Profile
On the API Scanning page, click the "Create API Scan Profile" button to start the setup process.
Step 3: Upload Your Specification File
Upload your prepared OpenAPI specification file. Our system will then parse the file and extract the server addresses from the servers field.
Important: We can only scan assets that have been verified in your Detectify account. If any of the server addresses from your file correspond to unverified assets, we will prompt you to add and verify them before you can proceed. You can only scan the server addresses found in the specification file.
Step 4: Configure Authentication
If your API is protected by an API key, you can configure it in this step.
Select where the API key is sent: Header, Query, or Cookie.
Enter the Name of the field (e.g., X-API-Key).
Enter the Value (the actual API key).
Step 5: Set a Scan Schedule
Next, set your recurring scan schedule. A toggle labeled "Scan every 3 days (Starting now)" is enabled by default.
With the toggle enabled: Your first scan will begin immediately after you create the profile. It will then run automatically every 3 days.
With the toggle disabled: A scan will not start automatically. After saving, you will need to start scans manually by clicking the "Scan once" button on the API scanning page. You can enable this at a later time by editing the profile.
Step 6: Configure and Test Operations
You will now see a list of all operations (endpoints) discovered in your specification file.
Select Operations: Choose which operations you want to include in the scan.
Configure Parameters: We pre-populate parameter fields using default values from your specification file, but you can configure them as needed.
Test Requests: For each operation, you can click the "Test Operation" button to send a single request and verify that your configuration is working correctly.
Important: We highly recommend configuring the parameter fields with the appropriate values for optimal API scan results. Without valid parameter values, we cannot generate functional API calls, which will significantly diminish the scan's effectiveness.
Step 7: Save Your Profile
Once you have configured your operations, click to save your profile and complete the setup.
Viewing Your Results
After a scan is complete, you can review its outcomes from the table on the API Scanning page. For each profile, there are two ways to see your results:
Open Vulnerabilities: To see the security issues that were actually found, click the link in the “Open vulnerabilities” column that takes you to the main "Vulnerabilities" page.
Vulnerabilities tested for: To see the full scope of the vulnerabilities tested for, click the link in the "Vulnerabilities tested for" column. You can click on any item in this list for details on the vulnerability, including its description, risk, remediation advice, and references.
Editing Your Profile
You can change your profile's configuration at any time. On the API Scanning page, find your profile in the list and use the options in the "Actions" column to edit it. You can modify all settings—such as authentication, scan schedule, and which operations to test—with one exception: the server address chosen during the initial setup cannot be changed.
FAQ
What can I expect from a Detectify API Scan?
Our API Scanner prioritizes quality results, a core principle at Detectify. It combines essential security hygiene checks with a broad range of advanced vulnerability assessments using Detectify’s proprietary fuzzing engines, ensuring we can continue innovating and widening our portfolio of payloads.
How does Detectify’s payload rotation functionality work for API Scanning?
In order to continue expanding our testing scope we will continuously try new payloads whenever we run an assessment as a part of the API Scanning process. What this means is that with time, we will continue trying new methods (or payloads) to exploit a vulnerability. How this works in practice is that for each vulnerability we have anywhere between a handful of methods up to 9.22E+20 ways of exploiting a vulnerability. As such, we select a smaller portion of the set of payloads used to exploit a vulnerability, and try new ones with each scan. In addition, if we produce a vulnerability using a particular payload, we will keep track of this and use it as input when we continue testing for the vulnerability going forward. If the new set of payloads are not generating the same vulnerability, we will test with the payload that produced it in the first place to ensure we do not miss out on any vulnerabilities.To continuously expand our testing scope, we will always try new payloads when running an assessment as part of the API Scanning process. This means that over time, we will continue to try new methods (or payloads) to exploit vulnerabilities. In practice, for each vulnerability, we have anywhere from a handful of methods up to 9.22E+20 ways of exploiting it.
We select a smaller portion of these payloads for each scan and try new ones regularly. If a particular payload successfully identifies a vulnerability, we track it and prioritize its use in future tests for that same vulnerability. This ensures that if new payloads don't reveal the same vulnerability, we re-test with the proven payload to avoid missing any potential issues.
How does Detectify handle changes created by scanning e.g. a POST endpoint?
Our API Scanner's vulnerability tests primarily use fuzzing. This means we utilize your profile configuration to call selected API operations with the provided information. If a POST endpoint is tested, data may be created in your systems. Currently, the API scanning process does not remove this created information. Therefore, it's crucial to consider which parts of your API you scan and the authentication rights provided. You can easily exclude highly sensitive endpoints when setting up your Detectify profile.
How can Detectify help me get an understanding of what APIs I should cover using API Scanning?
Through Surface Monitoring’s discovery process, you can get a good understanding of what APIs exist on your attack surface, especially using Detectify’s asset classification system that marks assets on your attack surface. This is a great way of getting some inspiration of what APIs you could cover deeper with our API Scanner.
How do I identify traffic coming from the API Scanner?
Traffic from our API Scanner originates from the same Detecitfy IPs as our other systems. As always, make sure to allowlist these IPs in your systems to ensure that Detectify can reach and test your environment correctly. The IPs are as follows:
52.17.9.21
52.17.98.131
In addition, traffic from our API Scanner can be identified by our user agent:
userAgent = "Mozilla/5.0 (compatible; Detectify; api-scanning)"
What kind of APIs can I scan?
Our API Scanner is designed to scan REST APIs using OpenAPI spec files from v2.0 and onwards as input.
Can I use short lived authentication such as OAuth in the API Scanner?
We do not currently support OAuth. While it is technically possible to bypass this limitation using our supported authentication methods (Cookie, Header, Query), we do not recommend it, as you would need to manually update these for every scan.
What kind of vulnerabilities are you checking for in the API Scanner?
You can find all vulnerabilities that have been checked for as a part of the API Scanner once your scan is completed. Some examples of categories of vulnerabilities that we look for are:
Server Side Request Forgery (SSRF)
SQL injections (SQLI)
NoSQL injections (NoSQLI)
Detailed Error Messages
Command Injections
Cross-Site Scripting (XSS)
XML External Entities (XXE)
SSL/TLS issues
Certificate issues
Server Side Template Injection (SSTI)
Path traversal
Remote File Inclusion (RFI)
Server-side Includes (SSI)
Edge-side Includes (ESI)
CRLF injection
Code injection (RCE)
LDAP injection
XPath injection
JSON injection
Memory leaks
Prompt injection
Why do I need to configure data to be used to call the endpoints when setting up the API Scan Profile?
In order to scan your API for vulnerabilities, we need to establish working API calls. When we have a working API call, we can then alter requests and as such test for vulnerabilities. Without it, it is only possible to look for shallow security issues and you would not get the full coverage. With this in mind, make sure that the information you provide is valid and up to date (e.g. authentication).
Is there a rate limit to the scanner and/or how much traffic can I expect?
We currently have no rate limiting in place for the API Scanner.
How long can we expect an API scan to take?
Scan time depends on the size of the API as well as the rate of our execution, but you should expect a scan to complete in around 15-20 minutes, if not faster. Because an API Scan does not involve any crawling and the scope being significantly smaller, the scan is significantly faster compared to the more complex operations involved in an Application Scan.