API Introduction

The REST APIs provide programmatic access to read, write, update and delete Gauntlet.io data. Register applications, start scans, download reports, and more. The REST API identifies users using a combination of User ID and API Key; responses are available in JSON.

Important

  • All API calls examples use cURL, a well known linux program
  • Every API call described here must be preceded by the following address: https://api.gauntlet.io/api/v1
  • Every parameter should be encoded as UTF-8
  • Datetimes will be presented according to the time zone set of the caller account
  • Requests could be in JSON or x-www-form-urlencoded
  • Make sure to add the following headers in every request:
    • Accept: application/json (to explicity define that you want a JSON response)
    • Content-Type: application/json (if you are sending a JSON request)

 

Authentication / Authorization

In order to perform any call within our REST API, you need to provide credentials to be authenticated and authorized. Those credentials are your User ID, which is displayed in the API Keys page, the same page used to generate your API Keys. It's located in the right top menu, after your log in:

API Keys 1

Each API Key is composed by a Token (secret), Scope of Applications and Scope of Permissions (List of allowed methods per class). Our granular control enables you to restrict access for each API Key, thus minimizing credential breach impacts:

API Keys 2

 

Pagination

All requests to list a certain model (e.g., GET /organizations) are by default limited to show up to 25 records and the first page. To see more records, please send/modify the following GET parameters page and/or page_size.

 

Internal Application Scan

For some plans we also support internal scans. You are able to scan hosts within your private network. You'll need to do the following tasks prior to run the scan:

  1. Generate a SSH key pair for the server you want to scan
    • For Linux, just run "ssh-keygen -t rsa -b 4096". More details here.
    • For Windows, use PuTTYgen. Check out this article.
  2. Register the Public SSH Key in our platform. Just copy its contents, go to "Application -> Edit Profile" and paste in the textarea as below:
    SSH Keys

After completing such tasks, the behavior to start the scan is slightly different from non internal applications. These are the differences:

  1. After pressing the "Start Scan", you'll be asked to connect your private server to our Proxy Server. It means that your firewall must allow outbound connections for our servers on port 22. Currently our servers' IP addresses are dynamic, but we provide a unique name for you to use (e.g. my-server.proxy.gauntlet.io). The command to connect will be provided in the web interface as well.
  2. Then you need to connect to our servers and wait. We will detect that the connection was successful and proceed the scan as usual. It's important to note that if the connection between the servers goes down, the scan stops as well. That said you should not break this connection while the scan is being performed.

 

Models

Model is concept from the Model View Controller (MVC) Pattern, that in our case will represent entities that allow certain actions to be performed. That said, you'll find below all models that you can interact with, accompained by request and response examples.

 

User

See and update your account information, including the possibility to list and accept/reject invites and leave organizations.

Method Endpoint Body Parameters Description
GET /users/:id Show details of your account
PUT /users
  • full_name: string (optional)
  • language: string (optional)
  • avatar: file (optional)
  • time_zone: string (optional)
  • language: string (optional)
  • unconfirmed_email: email (optional)
  • password: string (optional)
  • password_confirmation: string (required if "password" is sent)
Update your account
GET /users/invites List all your invites
PUT /users/invites/:id status: string (required) Accept/Reject an Invite
DELETE /users/organizations/:id Leave an Organization

 

ApiKey

API Keys can also be managed through API calls. They are needed to perform API Calls and can be configured to have a limited scope, that is, call fewer methods, and to affect all or specific applications.

Method Endpoint Body Parameters Description
GET /api_keys List all API Keys
GET /api_keys/:id Show details of an API Key
POST /api_keys
  • name: string (required)
  • applications: array (optional)
    Default: all applications
  • scope: array (optional)
    Default: all methods
Create a new API Key
PUT /api_keys/:id
  • name: string (optional)
  • applications: array (optional)
  • scope: array (optional)
Update an API Key
DELETE /api_keys/:id Delete an API Key

 

Organization

Every user belong to one or more organizations. Organizations contain Memberships, Groups, Invites, Applications, Notifications, Policies and more.

Method Endpoint Body Parameters Description
GET /organizations List all Organizations
GET /organizations/:id Show details of an Organization
POST /organizations
  • name: string (required)
  • avatar: file (optional)
Create a new Organization
PUT /organizations/:id
  • name: string (optional)
  • avatar: file (optional)
Update an Organization
DELETE /organizations/:id Delete an Organization

 

Membership

Memberships are used to associate Users and Organizations. They're created when an Invite is accepted.

Method Endpoint Body Parameters Description
GET /memberships/:id Show details of a Membership
DELETE /memberships Bulk delete of Memberships

 

MembershipsGroup

MembershipsGroup are used to associate Memberships and Groups.

Method Endpoint Body Parameters Description
POST /memberships_groups Bulk create Memberships
DELETE /memberships_groups Bulk delete Memberships

 

Group

Group is a collection of Memberships that could have its permissions managed.

Method Endpoint Body Parameters Description
GET /groups?organization_id=:id List all Groups
GET /groups/:id Show details of a Group
POST /groups
  • name: string (required)
  • organization_id: integer (required)
  • avatar: file (optional)
  • application_scope: array (optional)
    Default: All Applications
  • permission_scope: array (optional)
    Default: All Permissions
Create a new Group
PUT /groups/:id
  • name: string (optional)
  • avatar: file (optional)
  • application_scope: array (optional)
    Default: All Applications
  • permission_scope: array (optional)
    Default: All Permissions
Update a Group
DELETE /groups/:id Delete a Group

 

Invite

Invites, when accepted, generates a Membership, which is an association between a User and an Organization. To accept an invite, one must call User#update_invite, and to list them, use User#list_invites.

Method Endpoint Body Parameters Description
GET /invites?organization_id=:id List all Invites
POST /invites
  • email: string (required)
  • organization_id: integer (required)
Create a new Invite
DELETE /invites/:id Delete an Invite

 

Custom Report

Custom reports could be generated to show a list of vulnerabilities related to a specific group of assets. Such report could be managerial or technical, html or pdf and will be sent to the user's account email.

Method Endpoint Body Parameters Description
POST /reports/custom
  • organization_id: integer (required)
  • report[applications]: array (required)
  • report[applications_tags]: array (required)
  • report[applications_tags]: array (required)
  • report[scanners]: array (required)
  • report[include_manual_issues]: boolean (required)
  • report[severity]: string (required)
  • report[severity_levels]: array (required)
  • report[business_criticalities]: array (required)
  • report[report_template_id]: string (required)
  • report[report_format_id]: string (required)
Create a new Custom Report and send link to requester's email.

 

Certificate Expiration Policy

Policy to manage the minimum quantity of days or months to trigger events that will be used to notify stakeholders regarding the expiration of HTTPS Certificates.

Method Endpoint Body Parameters Description
GET /certificate_expiration_policies?organization_id=:id&status=(Enabled|Disabled) List all Policies
GET /certificate_expiration_policies/:id Show details of a Policy
POST /certificate_expiration_policies
  • status: string (required)
  • days: integer (required)
  • business_criticality: string (required)
  • escalation_level: string (required)
  • organization_id: integer (required)
Create a new Policy
PUT /certificate_expiration_policies/:id
  • status: string (optional)
  • days: integer (optional)
  • business_criticality: string (optional)
  • escalation_level: string (optional)
Update a Policy
DELETE /certificate_expiration_policies/:id Delete a Policy

 

Max Classification Time Policy

Policy to manage the maximum time to classify issues with "Undefined" technical severity and "Undefined" business severity.

Method Endpoint Body Parameters Description
GET /max_classification_time_policies?organization_id=:id List all Policies
GET /max_classification_time_policies/:id Show details of a Policy
POST /max_classification_time_policies
  • technical_severity: integer (required)
  • business_severity: integer (required)
  • status: string (required)
  • time_unit: string (required)
  • business_criticality: string (required)
  • escalation_level: string (required)
  • organization_id: integer (required)
Create a new Policy
PUT /max_classification_time_policies/:id
  • technical_severity: integer (optional)
  • business_severity: integer (optional)
  • status: string (optional)
  • time_unit: string (optional)
  • business_criticality: string (optional)
  • escalation_level: string (optional)
Update a Policy
DELETE /max_classification_time_policies/:id Delete a Policy

 

Max Fix Time Policy

Policy to manage the maximum time to fix issues based on their business severity.

Method Endpoint Body Parameters Description
GET /max_fix_time_policies?organization_id=:id List all Policies
GET /max_fix_time_policies/:id Show details of a Policy
POST /max_fix_time_policies
  • critical: integer (required)
  • high: integer (required)
  • medium: integer (required)
  • low: integer (required)
  • status: string (required)
  • time_unit: string (required)
  • business_criticality: string (required)
  • escalation_level: string (required)
  • organization_id: integer (required)
Create a new Policy
PUT /max_fix_time_policies/:id
  • critical: integer (optional)
  • high: integer (optional)
  • medium: integer (optional)
  • low: integer (optional)
  • status: string (optional)
  • time_unit: string (optional)
  • business_criticality: string (optional)
  • escalation_level: string (optional)
Update a Policy
DELETE /max_fix_time_policies/:id Delete a Policy

 

Max Issues Policy

Policy to manage the maximum amount of issues per a given business severity level.

Method Endpoint Body Parameters Description
GET /max_issues_policies?organization_id=:id List all Policies
GET /max_issues_policies/:id Show details of a Policy
POST /max_issues_policies
  • critical: integer (required)
  • high: integer (required)
  • medium: integer (required)
  • low: integer (required)
  • status: string (required)
  • business_criticality: string (required)
  • escalation_level: string (required)
  • organization_id: integer (required)
Create a new Policy
PUT /max_issues_policies/:id
  • critical: integer (optional)
  • high: integer (optional)
  • medium: integer (optional)
  • low: integer (optional)
  • status: string (optional)
  • business_criticality: string (optional)
  • escalation_level: string (optional)
Update a Policy
DELETE /max_issues_policies/:id Delete a Policy

 

Minimum Scan Policy

Policy to manage minimum amount of scans that an application should go through in a certain period of time.

Method Endpoint Body Parameters Description
GET /minimum_scan_policies?organization_id=:id List all Policies
GET /minimum_scan_policies/:id Show details of a Policy
POST /minimum_scan_policies
  • value: integer (required)
  • scan_type: string (required)
  • status: string (required)
  • time_unit: string (required)
  • business_criticality: string (required)
  • escalation_level: string (required)
  • organization_id: integer (required)
Create a new Policy
PUT /minimum_scan_policies/:id
  • scan_type: string (optional)
  • value: integer (optional)
  • status: string (optional)
  • time_unit: string (optional)
  • business_criticality: string (optional)
  • escalation_level: string (optional)
Update a Policy
DELETE /minimum_scan_policies/:id Delete a Policy

 

Asset

Before scanning for vulnerabilities, you need to register a server or an application and verify its ownership.

Method Endpoint Body Parameters Description
GET /applications?organization_id=:id List all Applications
GET /applications/:id Show details of an Application
POST /applications
  • name: string (required)
  • url: string (required)
  • application_type: string (required)
  • organization_id: integer (required)
  • description: string (optional)
  • sync_issues_severities: boolean (optional)
    Default: false
  • business_criticality: string (optional)
    Default: Medium
  • internal: boolean (optional)
    Default: false
  • self_signed_certificate: (optional)
    Default: false
  • ssh_key: string (optional)
  • tags: array (optional)
Create a new Application
POST /applications/:id/verify/:type Verify the ownership of an Application (Servers don't need this)
PUT /applications/:id
  • name: string (optional)
  • description: string (optional)
  • sync_issues_severities: boolean (optional)
  • self_signed_certificate: boolean (optional)
  • ssh_key: string (optional)
  • business_criticality: string (optional)
  • tags: array (optional)
Update an Application
DELETE /applications/:id Delete an Application

 

Certificate

After a HTTPS application be registered, from time to time a Gauntlet worker will run and collect information about its certificate. All certificates can be accessed through this API.

Method Endpoint Body Parameters Description
GET /certificates?organization_id=:id List all Certificates
GET /certificates/:id Show details of a Certificate

 

Issue

Issues are every single attention point given by a scanner. They may or may not become a vulnerability. And you can also create manual issues. A manual issue is treated differently from issues generated by scanners, as you'll see on the comments of request/response examples.

Method Endpoint Body Parameters Description
GET /issues?application_id=:id List all Issues
GET /issues/:id Show details of an Issue
POST /issues
  • application_id: integer (required)
  • title_en: string (required)
  • description_en: string (optional)
    Default: null
  • recommendations_en: string (optional)
    Default: null
  • category: string (optional)
    Default: Application
  • proof_request: string (optional)
    Default: null
  • proof_response: string
    Default: Undefined
  • raw_output_from_scanner: string (optional)
    Default: null
  • technical_severity: string (optional)
    Default: Undefined
  • business_severity: string (optional)
    Default: Undefined
  • original_severity: string (optional)
    Default: Undefined
  • source: string
    Default: Generic
  • affected_url: string
    Default: null
  • affected_parameter: string
    Default: null
  • affected_host: string
    Default: null
  • affected_ip: string
    Default: null
  • affected_port: string
    Default: null
  • affected_protocol: string
    Default: null
  • affected_query_string: string
    Default: null
  • affected_headers: string
    Default: null
  • affected_source_file: string
    Default: null
  • affected_line_numbers: array
    Default: null
  • references: array
    Default: []
  • cves: array
    Default: []
  • osvdb_ids: array
    Default: []
  • related_issues: array
    Default: []
  • tags: array
    Default: []
Create a new (Manual) Issue
PUT /issues/:id

For Manual Issues

  • title_en: string (required)
  • description_en: string (optional)
  • recommendations_en: string (optional)
  • category: string (optional)
  • proof_request: string (optional)
  • proof_response: string
  • raw_output_from_scanner: string (optional)
  • source: string
  • affected_url: string
  • affected_parameter: string
  • affected_host: string
  • affected_ip: string
  • affected_port: string
  • affected_protocol: string
  • affected_query_string: string
  • affected_headers: string
  • affected_source_file: string
  • affected_line_numbers: array
  • fixed: boolean (optional)
  • technical_severity: string (optional)
  • business_severity: string (optional)
  • false_positive: boolean (optional)
  • false_positive_set_by: integer (optional)
  • false_positive_created_at: date (optional)
  • references: array (optional)
  • cves: array (optional)
  • osvdb_ids: array (optional)
  • related_issues: array (optional)
  • tags: array (optional)

For Scanner Generated Issues

  • technical_severity: string (optional)
  • business_severity: string (optional)
  • false_positive: boolean (optional)
  • false_positive_set_by: integer (optional)
  • false_positive_created_at: date (optional)
  • references: array (optional)
  • cves: array (optional)
  • osvdb_ids: array (optional)
  • related_issues: array (optional)
  • tags: array (optional)
Update an Issue
PUT /issues Same as above (PUT /issues/:id) Bulk Update Issues

 

Source Code

Before scanning for vulnerabilities, you need to register a server or an application and verify its ownership.

Method Endpoint Body Parameters Description
GET /source_codes?application_id=:id List all Source Codes
GET /source_codes/:id Show details of a Source Code
POST /source_codes
  • source_code[name]: string (required)
  • source_code[language]: string (required)
  • source_code[application_id]: integer (required)
  • source_code[file]: file (required)
Create a new Source Code
PUT /source_codes/:id
  • source_code[name]: string (optional)
  • source_code[language]: string (optional)
Update a Source Code
DELETE /source_codes/:id Delete a Source Code

 

Report

After each completed scan, a report is generated in PDF. They are hosted in S3 and will be available through a temporary link that will last 60 minutes. After that you need to perform another call to get another link.

Method Endpoint Body Parameters Description
GET /reports?scan_id=:id
/reports?application_id=:id
/reports?organization_id=:id
List all Reports
GET /reports/:id Show details of a Report

 

Foreign Report

Before scanning for vulnerabilities, you need to register a server or an application and verify its ownership.

Method Endpoint Body Parameters Description
GET /foreign_reports?application_id=:id List all Foreign Reports
GET /foreign_reports/:id Show details of a Foreign Report
POST /foreign_reports
  • foreign_report[scanner_id]: integer (required)
  • foreign_report[application_id]: integer (required)
  • foreign_report[report]: file (required)
Create a new Foreign Report
DELETE /foreign_reports/:id Delete a Foreign Report

 

Scan Schedule

Before scheduling a scan you need to define a scan profile. Then you can schedule when an asset will be scanned.

Method Endpoint Body Parameters Description
GET /scan_schedules?application_id=:id List all Scan Schedules
GET /scan_schedules/:id Show details of a Scan Schedule
POST /scan_schedules
  • scan_schedule[user_hour]: integer (required)
  • scan_schedule[user_min]: integer (required)
  • scan_schedule[week_day]: integer (required)
  • scan_schedule[application_id]: integer (required)
  • scan_schedule[scan_profile_id]: integer (required)
  • scan_schedule[source_code_id]: integer (required)
  • scan_schedule[scan_type]: string (required)
  • scan_schedule[virtual_appliance_id]: integer (optional)
Create a new Scan Schedule
PUT /scan_schedules/:id
  • scan_schedule[user_hour]: integer (required)
  • scan_schedule[user_min]: integer (required)
  • scan_schedule[week_day]: integer (required)
  • scan_schedule[scan_profile_id]: integer (required)
  • scan_schedule[source_code_id]: integer (required when scan_type is "SAST")
  • scan_schedule[scan_type]: string (required)
  • scan_schedule[virtual_appliance_id]: integer (optional)
Update a Scan Schedule
DELETE /scan_schedules/:id Delete a Scan Schedule

 

Scan Profile

Before starting a scan you need to define a scan profile. In this profile you can configure how the scan should behave. It includes scan speed, start path, extra request headers, the scanners themselves and more.

Method Endpoint Body Parameters Description
GET /scan_profiles?application_id=:id
/scan_profiles?organization_id=:id
List all Scan Profiles
GET /scan_profiles/:id Show details of a Scan Profile
POST /scan_profiles
  • name: string (required)
  • organization_id: integer (required)
  • application_id: integer (optional)
  • scan_type: string (required)
  • start_path: string (required)
  • scanner_ids: array (required)
  • max_execution_time: integer (optional)
    Default: Infinity (null)
  • package_delay: integer (optional)
    Default: No Delay (null)
  • extra_request_headers: dictionary (optional)
    Default: {}
  • authentication: array (optional)
    Default: []
Create a new Scan Profile
PUT /scan_profiles/:id
  • name: string (optional)
  • application_id: integer (optional)
  • start_path: string (optional)
  • scanner_ids: array (optional)
  • max_execution_time: integer (optional)
  • package_delay: integer (optional)
  • extra_request_headers: dictionary (optional)
  • authentication: array (optional)
Update a Scan Profile
DELETE /scan_profiles/:id Delete a Scan Profile

 

Scan

An application can have many scans. Just the creation of a scan triggers its execution and create what we call "ScanScanners". Those "ScanScanners" represent instances of Scanners selected to perform the scan. For example, a request to scan an application that will run Wapiti and W3af will generate 2 ScanScanner records.

Method Endpoint Body Parameters Description
GET /scans?application_id=:id List all Scans
GET /scans/:id Show details of a Scan
POST /scans
  • application_id: integer (required)
  • scan_profile_id: array integer (required)
  • scan_type: string (required)
  • source_code_id: integer (required if scan_type is "SAST")
  • virtual_appliance_id: integer (optional)
Create/Start a new Scan
POST /scans/:id/stop
  • scan_scanner_ids: array (optional)
    Default: Stop all scanners
Stop Scanner(s)

 

ScanScanner

ScanScanner, as mentioned above, is an instance of each Scanner that will run against an application. With this information, you can track the individual progress of each scanner and their respective status.

Method Endpoint Body Parameters Description
GET /scan_scanners?scan_id=:id List all Scan Scanners
GET /scan_scanners/:id Show details of a Scan Scanner

 

Scanner

List all Gauntlet.io available scanners to use in your "scanner_ids" parameter before starting a scan.

Method Endpoint Body Parameters Description
GET /scanners List all Scanners
GET /scanners/:id Show details of a Scanner

 

Event

Events could trigger Notifications. It's important to know them before setting up a notification.

Method Endpoint Body Parameters Description
GET /events List all Events
GET /events/:id Show details of an Event

 

Notification

Notifications are the combination of triggered events with notification channels, such as e-mail. For a given event you can set up a channel to be notified.

Note: notifications can be global (for all apps within an organization) or per application / group of applications. To make it global, pass an empty array of applications on "application_ids" parameter.

Method Endpoint Body Parameters Description
GET /notifications?application_id=:id
/notifications?organization_id=:id
List all Notifications
GET /notifications/:id Show details of a Notification
POST /notifications
  • organization_id: integer (required)
  • channels: array (required)
  • status: string (optional)
    Default: disabled
  • email_individuals: string (optional)
    Default: ""
  • email_groups: array (optional)
    Default: []
  • event_ids: array (optional)
    Default: []
  • application_ids: array (optional)
    Default: []
Create a new Notification
PUT /notifications/:id
  • channels: array (optional)
  • status: string (optional)
  • email_individuals: string (optional)
  • email_groups: array (optional)
  • event_ids: array (optional)
  • application_ids: array (optional)
Update a Notification
DELETE /notifications/:id Delete a Notification

 

Arbitrary Function

Notifications are the combination of triggered events with notification channels, such as e-mail. For a given event you can set up a channel to be notified.

Method Endpoint Body Parameters Description
GET /arbitrary_functions?application_id=:id
/arbitrary_functions?organization_id=:id
List all Arbitrary Functions
GET /arbitrary functions/:id Show details of an Arbitrary Function
POST /arbitrary functions
  • arbitrary_function[organization_id]: integer (required)
  • arbitrary_function[application_id]: integer (required)
  • arbitrary_function[name]: string (required)
  • arbitrary_function[code]: string (required)
  • arbitrary_function[language]: string (required)
Create a new Arbitrary Function
PUT /arbitrary functions/:id
  • arbitrary_function[application_id]: integer (required)
  • arbitrary_function[name]: string (required)
  • arbitrary_function[code]: string (required)
  • arbitrary_function[language]: string (required)
Update an Arbitrary Function
DELETE /arbitrary functions/:id Delete an Arbitrary Function