Enterprise Recon v1 API

Enterprise Recon v1 API

PII PRO ER2 API Framework is only available in Enterprise Recon PII and PRO Editions. To find out more about upgrading your ER2 license, please contact Ground Labs Licensing. See Subscription License for more information.

Introduction

Enterprise Recon PII and PRO are shipped with a comprehensive RESTful API framework that provides direct access to key resources and data sets in the Master Server, giving you the flexibility to transform how your organization interacts with ER2.

Using the ER2 API, you can generate custom reports that display scan results to suit your organization's specific requirements, or retrieve detailed information on match locations to perform custom remediation actions on non-compliant Targets. Business as usual (BAU) compliance processes can also be automated. For example, develop a script to easily add thousands of Targets to the Master Server via the API, or export weekly activity logs to monitor Master Server events.

Overview

This document assumes that you are familiar with the Enterprise Recon 2.10.0 (ER2) appliance. This document describes the endpoints, parameters, requests, responses and other details for each available ER2 API resource.

JSON is the default output format for all API resources; if other media types are supported, this will be stated in the documentation.

If absolute synchronicity is required for your application, PUT and POST requests should be validated with a feedback GET call to ensure the previous add, update or delete operation has completed successfully.

For detailed information on Enterprise Recon 2.10.0 features and functions, see Enterprise Recon User Guide .

Enable the API

To enable the ER2 API service:

  1. Log into the ER2 Web Console.
  2. From the top navigation bar, go to the System > Server Information page.
  3. Go to the API Config section.
  4. Set the toggle button to On for Allow API Access.

  5. In the Port Number field, specify a TCP port number for the ER2 API service. The default TCP port number is 8339.

  6. Click Confirm.
  7. (Optional) To change the TCP port number, set the toggle button to Off for Allow API Access. Repeat step 5 and step 6.

To disable the ER2 API service:

  1. Log into the ER2 Web Console.
  2. From the top navigation bar, go to the System > Server Information page.
  3. Go to the API Config section.
  4. Set the toggle button to Off for Allow API Access.

API Access

The URL to access the ER2 API is the host name or IP address of your Master Server, on the TCP port specified when enabling the API service. For example: https://er2-master:8339.

You will need to enable SSL on your Master Server, and specify your user name and password for server authentication (see Authorization).

The Global and Resource Permissions assigned to a user will determine the resources and data that a user can access via the API. See User Permissions for more information.

URL Encoding of Path and Query Parameters

If an API call contains unsafe or reserved characters (as defined by the IETF) in the path or query parameter(s), these characters must be URL-encoded using a percentage % character followed by its two-character hex value. Common unsafe or reserved characters that must be encoded in the URL include the whitespace   (%20), plus + (%2B), and ampersand & (%26) characters.

For example, to use the file_name query parameter to filter the List Objects with Matches API results for a file name that contains whitespaces and the plus sign (e.g. "doc A+B.txt"), the API request would need to be URL-encoded as below:

curl --request GET 'https://er-master:8339/v1/targets/4759598330602895744/matchobjects?file_name=doc%20A%2BB.txt' \
--user apiuser:password123 \
--header "Accept: application/json"

Using the Documentation

Reference documentation for each API endpoint consists of the following sections:

  1. Resource Description
  2. Endpoints and Methods
  3. Parameters
  4. Request Schemas and Examples
  5. Response Schemas and Examples

Resource Description

This section describes the purpose and type of information that can be returned or updated with the API.

API Resource Description section

Endpoints and Methods

The section describes the resource URL, and indicates the methods (e.g. GET, PUT, DEL, POST) available to interact with the resource.

API Endpoints and Methods section

  • To indicate required path parameters in the resource URL, angle brackets < > are used.
  • To indicate optional path parameters in the resource URL, curly brackets { } are used.

Parameters

This section describes the options that can be passed with the endpoint to customize or filter the response.

There are three types of parameters:

  • Path Parameters
  • Query Parameters
  • Header Parameters

All parameters are optional unless the tag is explicitly indicated below the parameter.

API Parameters section
Not all parameter types are applicable to all endpoints.

Request Schemas and Examples

This section describes the request body schema and provides a payload example for the endpoint.

API Request Schema and Examples section

Here are the example values used in the cURL sample command lines for this document:

  • ER2 Master Server host name or IP address: https://er-master
  • Port number: 8339
  • Username: apiuser
  • Password: password123

Response Schemas and Examples

This section describes the response body schema and provides successful (and failed) response examples for the endpoint.

API Response Schema and Examples section

Authorization

Security Scheme: Basic

Type: HTTP

Credentials:

  • Non-active directory user: <username>:<password>
    Example: apiUser:apiUserPassw0rd

  • Active directory user: <domain>\<username>:<password>
    Example: example.com\user1:user1Passw0rd

HTTP Request Methods

The ER2 APIs support the following HTTP request methods:

  1. GET : Use GET requests to retrieve resource data or information.
  2. POST : Use POST requests to create or add new resources.

  3. PUT : Use PUT requests to modify or update existing resources. For PUT requests, all fields will be cleared and replaced with what is inside the request body.

  4. DELETE : Use DELETE requests to delete resources.

Refer to each individual resource to determine which HTTP request methods are supported.

HTTP Status Codes

The ER2 API supports standard HTTP status codes. Here are the list of error codes:

  • 100 Continue
  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 406 Not Acceptable
  • 408 Request Timeout
  • 411 Length Required
  • 413 Payload Too Large
  • 414 URI Too Long
  • 415 Unsupported Media Type
  • 417 Expectation Failed
  • 422 Unprocessable Entity
  • 500 Internal Server Error
  • 501 Not Implemented
  • 503 Service Unavailable
  • 505 HTTP Version Not Supported

Changelog

Enterprise Recon 2.10.0 Update

Enterprise Recon 2.9.0 Update

  • GET /v1/schedules: Fixed issue where "scheduled" instead of "paused" would be returned for the value of the status field in the response schema of scan schedules that started and paused automatically while at least one other scan was still in the "paused" state.
  • POST PUT /v1/datatypes/rules: Custom data types can now be added as part of the Data Type criteria / rules when creating and/or modifying Risk Profiles. See Risk Scoring and Labeling API for more information.
  • Fixed issue where UTF-16 encoded supplementary characters (e.g. the musical symbol G Clef "𝄞", mathematical symbol "∂", emojis like "🚀", "🏠", etc...) in the location path for any Microsoft 365 cloud Targets would be displayed as question marks in the path and location fields in the response schema of various endpoints.
  • POST /v1/targets/probing: Fixed issue where probing teams that contained special characters (e.g. "#", "%", "&", etc...) in the name would result in the "404 Not Found: Specified group does not appear to exist." error for Microsoft Teams Targets.
  • PUT /v1/licenses: Updated response samples to return "422 Unprocessable Entity" when uploading (i) an expired or an invalid ER2 license file, or (ii) an ER2 license file that has been previously uploaded.
  • POST /v1/targets: Updated the description for the name field in the request body schema to include support for Box Inc Target.
  • POST PUT /v1/credentials: Updated the description for multiple fields in the request body schema to include support for Box Inc Targets.
  • GET /v1/schedules: Updated response schema to return bulk download information when enabled for supported cloud Targets in a scan schedule.
  • POST PUT /v1/schedules: Added support for enabling the bulk download feature when adding or modifying a scan schedule with supported cloud Targets.
  • GET /v1/targets/<target_id>/rawisolated/<report_id>: Fixed issue where the value of the match_locations field could be more than the value of the scanned_locations field in the response schema for the Raw Isolated Report of Target locations with archive and / or MS Excel file formats.
  • Definitions - Credential Types - Added Box Inc to the list of supported type values for Box Inc Targets.
  • Definitions - ER2 Event Classes - Updated the list of event values for ER2.
  • Definitions - Protocols - Added boxinc to the list of supported protocol values for Box Inc Targets.

Enterprise Recon 2.8.0 Update

  • POST /v1/query: Updated query filters, request body, and response schema to support Enterprise Recon PRO Edition features.
  • POST /v1/query: Added support for specifying the filter value for metadata labels, values, and dates when creating a new Master Server Query.
  • POST /v1/query: Updated response samples to return "400 Bad Request" when the value of the meta->label field is Document Created, Document Modified, Date, File Created, or File Modified, but either the meta->start_date or the meta->end_date field value is not specified in the request body.
  • POST /v1/query: Updated response samples to return "403 Forbidden" when the request body contains ER2 PRO-specific keys, but the Enterprise Recon appliance does not have the required PRO Edition license.
  • POST /v1/query: Updated response samples to return "404 Not Found" when the values specified in the request body for the risk_profile_id, target_id, and group_id fields are invalid.
  • POST /v1/query: Updated response samples to return "422 Unprocessable Entity" when the values specified for the content_type, prefix, operation_status, order, direction, and classification_mip->method fields are invalid or have unsupported format.
  • POST /v1/query: Updated response samples to return "422 Unprocessable Entity" when (i) there is a specified value in the request body for the meta->label field but no corresponding value specified for meta->value, (ii) there are duplicate values for the same metafield, or (iii) the specified values in the request body for the meta fields are invalid.
  • GET /v1/query/<query_id>/targets/<target_id>/locations/<location_id>: Added the risk key in the "200 OK" response sample.
  • POST /v1/targets/probing: Fixed issue for OneDrive Business Targets where invalid Microsoft 365 domains specified in the path field of the request body could be probed but would display an empty list or a list of security groups.
  • POST PUT GET DEL /v1/risk: Newly added APIs for creating risk rules and configuring risk profiles. See Risk Scoring and Labeling API for more information.
  • POST PUT GET DEL /v1/datatypes/rules: Newly added APIs for creating and configuring data type rules for risk profiles. See Risk Scoring and Labeling API for more information.
  • POST PUT /v1/targets: Updated the description for the name field in the request body schema to include support for Microsoft Teams and Microsoft OneNote Targets.
  • POST PUT /v1/credentials: Updated the description for multiple fields in the request body schema to include support for Microsoft OneNote and Microsoft Teams Targets.
  • Definitions - Protocols - Added msonenote and msteams to the list of supported protocol values for Microsoft OneNote and Microsoft Teams Targets.
  • Definitions - Credential Types - Added Microsoft OneNote and Microsoft Teams to the list of supported type values for Microsoft OneNote and Microsoft Teams Targets.

Enterprise Recon 2.7.0 Update

  • PUT /v1/licenses: Updated response samples to return "400 Bad Request" when uploading an expired or an invalid ER2 license file.
  • PUT /v1/licenses: Updated response samples to return "422 Unprocessable Entity" when uploading a new valid ER2 license file with a smaller data allowance limit than the already-consumed data.
  • POST PUT /v1/schedules: Added support for setting the Partial Salesforce object scanning value when adding or modifying a scan schedule with Salesforce Target.
  • GET /v1/schedules: Updated response schema to return Partial Salesforce object scanning information when configured for a Salesforce Target in a scan schedule.
  • GET /v1/schedules: Updated the response samples to include scan schedules with Salesforce Target where the max_salesforce_records field / Partial Salesforce object scanning parameter is configured.
  • Definitions - Operation Status - Updated the list of supported ER2 operation statuses.
  • Definitions - Platforms - Updated the list of possible platform values for ER2.

Enterprise Recon 2.6.1 Update

  • GET /v1/targets/<target_id>/<report_type>: Renamed the timestamp field to report_id, and updated the data type for report_id from "number" to "string". This update addresses the issue in Distributed Scans that would occur in certain scenarios where (i) Isolated Reports were not generated for all scan locations, or (ii) the Target's scan history and generated Isolated Reports were corrupted, and all fields in the scan result reflected zero (0) for the impacted scan locations. In some cases, the "This report has old format and is not supported" error would be returned when attempting to download Raw Isolated Reports for Distributed Scans on multiple locations.

Enterprise Recon 2.6.0 Update

  • POST PUT /v1/filters /v1/datatypes/profiles: Added support for validating negative input values when adding or updating a global filter.
  • GET /v1/schedules: Fixed issue where incorrect values were returned for the targets.locations.name field in the response schema for certain protocols.
  • POST PUT /v1/credentials: Updated description for the fields in the request body schema.
  • GET /v1/targets/<target_id>/remediationlogs: Appended the "marked" label to the remediation_status in the response schema for locations where the remediation action (Mark Locations for Compliance Report) had been completed.

Enterprise Recon 2.5.0 Update

  • DEL /v1/targets/<target_id>/remediation/<job_id>: This API has been removed and is no longer available as of Enterprise Recon 2.5.0.
  • POST PUT /v1/targets/<target_id>: Updated description for the platform field.
  • GET /v1/targets/<target_id>/rawisolated/<report_id>: Updated description for the match_data_limit query parameter, and match_locations_overflow field.
  • Definitions - Platforms - Updated the list of possible platform values for ER2.
  • Definitions - Metadata - Updated the list of possible meta values for ER2.

Enterprise Recon 2.4 Update

  • DEL /v1/targets/<target_id>/remediation/<job_id>: This API has been deprecated and will be removed in a future release of Enterprise Recon.
  • POST PUT /v1/schedules/<schedule_id>: Added support for setting Match Detail value when adding or modifying a scan schedule.

  • GET /v1/schedules/<schedule_id>: Updated response schema to return Match Detail information of the scan schedule.

  • POST PUT GET /v1/classification/mip: Newly added APIs for configuring the Data Classification with MIP feature, and for performing classification actions. See Data Classification with MIP API for more information.
  • GET /v1/targets/<target_id>/matchobjects: Updated response schema to return Classification and Access Control information.
  • GET /v1/targets/<target_id>/matchobjects/<object_id>: Updated response schema to return Classification and Access Control information.
  • POST GET /v1/query: Updated query filters and response schema to support Classification and Access Control features.
  • POST PUT /v1/credentials: Updated description for username and password fields.
  • POST /v1/targets: Updated description for the name field, and improved response time when adding new Targets using this API.
  • Definitions - Operation Status - Renamed section from "Remediation Status" to "Operation Status" and updated the list of supported ER2 operation statuses.

Enterprise Recon 2.3.1 Update

  • POST PUT /v1/users /v1/users/me: Added support for validating password complexity rules when adding or updating a user account. See Password Policy for more information.
  • GET /v1/datatypes/profiles: Updated query parameter from profile_name to profile_label.

Enterprise Recon 2.3 Update

Enterprise Recon 2.2 Update

  • DEL POST /v1/users : Added support for adding a new user, and deleting an existing user account.
  • GET /v1/licenses : Minor updates to response schema, with attribution key added to datausage object.
  • GET /v1/server : Added the Master Server version and public_key in the response.
  • GET PUT DEL POST /v1/agentgroups : Added support for creating Agent Groups to be used to run Distributed Scans. The API also allows you to remove and rename Agent Groups, as well as add and remove specific Node Agents from the selected Agent Group. See Agent Groups and Distributed Scan for more information.
  • PUT POST /v1/datatypes/profiles/<profile_id> : Added support for validating custom data type expressions when creating or updating a data type profile.
  • Definitions - Metadata : Updated list of metadata values captured by ER2.

It is important that you read and understand the Guide, which has been prepared for your gainful and reasonable use of the Enterprise Recon API service. Use of ER2 API and these documents reasonably indicate that you have agreed to the terms outlined in this section.

While APIs documented here are supported for Enterprise Recon version 2.10.0, an API is not guaranteed to remain available or unchanged for future releases of ER2. Reasonable care has been taken to make sure that the information provided in this document is accurate and up-to-date; in no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with these documents. If you have any questions about this documentation, please reach out to our Ground Labs Support Team.

Examples used are meant to be illustrative; users' experience with the API service may vary. No part of this document may be reproduced or transmitted in any form or by means, electronic or mechanical, for any purpose, without the express written permission of the authors or the copyright holders.

THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. ALL EXPRESS OR IMPLIED REPRESENTATIONS, CONDITIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE DETERMINED TO BE ILLEGAL.