Enterprise Recon v1 API

Risk Scoring and Labeling

PRO This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your ER2 license, please contact Ground Labs Licensing. See Subscription License for more information.

Use this set of APIs to configure and get details on risk profiles and data type rules. See Risk Scoring and Labeling for more information.

List Risk Levels

Get detailed information for all or a specific risk level.

Request

GET

https://er-master:8339/v1/risk/levels/{level_id}

Authorization

Basic Authentication

Path Parameters

Parameter Data Type Description
level_id

string

Define this parameter to retrieve data for a specific risk level. If no value is specified, response returns data for all risk levels.

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/risk/levels
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/risk/levels' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
level_id

string

Unique risk level ID.
label

string

enum: Low Medium High

 Label for the risk level.
color

string

enum: #f44336 #ffa000 #8bc34a

 Color associated with the risk level.
priority

string

Pre-defined priority associated with the risk level.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "level_id": "1357066370714289807",
    "label": "High",
    "color": "#f44336",
    "priority": "1000000"
  },
  {
    "level_id": "1787705485000271818",
    "label": "Medium",
    "color": "#ffa000",
    "priority": "1000"
  },
  {
    "level_id": "1736476384795671267",
    "label": "Low",
    "color": "#8bc34a",
    "priority": "1"
  }
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}
404 Not Found

Returned if an invalid level_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'risk level' does not exist."
}

List Data Type Rules

Retrieve information for all or a specific data type rule.

Request

GET

https://er-master:8339/v1/datatypes/rules/{rule_id}

Authorization

Basic Authentication

Path Parameters

Parameter Data Type Description
rule_id

string

Define this parameter to retrieve data for a specific data type rule. If no value is specified, response returns data for all data type rules.

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/datatypes/rules
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/datatypes/rules' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
rule_id

string

Unique data type rule ID.
label

string

Label for the data type rule.
afconfig

string

Data types criteria or advanced filter rule (for ER2 built-in data types, custom data types and test data) defined for the risk profile. See Advanced Filters and Data Types Criteria for more information.
If there are multiple custom data types that share the same label / identifier for a given ER2 instance, these custom data types will be evaluated against the configured data type rules as a single data type.

Refer to your custom Data Type Profiles for details on the custom data types that are set up for your Master Server.
sealed

boolean

enum: true false

 If sealed=true, the data type rule (i) is used in at least one risk profile, and (ii) cannot be deleted.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "rule_id": "455572488728221120",
    "label": "PCI Compliance",
    "afconfig": "(MATCH(1, [American Express],[China Union Pay],[Diners Club],[Discover],[JCB],[Laser],[Maestro],[Mastercard],[Private Label Card],[Troy],[Visa]))",
    "sealed": true
  },
  {
    "rule_id": "1357066370714289807",
    "label": "Credentials",
    "afconfig": "([Credentials username]) AND ([Credentials password])",
    "sealed": false
  }
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid rule_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found. Specified 'data type rule' does not exist."
}

Update a Data Type Rule

Update an existing data type rule and its label.

Request

PUT

https://er-master:8339/v1/datatypes/rules/<rule_id>

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Path Parameters

Parameter Data Type Description
rule_id

string

Specify ID of data type rule to update or modify. rule_id is the response item from the /v1/datatypes/rules endpoint.

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
label

string

Label for the data type rule.
afconfig

string

Define the data types criteria or advanced filter rule (for ER2 built-in data types, custom data types and test data) for the risk profile. See Advanced Filters and Data Types Criteria for more information.
If there are multiple custom data types that share the same label / identifier for a given ER2 instance, these custom data types will be evaluated against the configured data type rules as a single data type.

Refer to your custom Data Type Profiles for details on the custom data types that are set up for your Master Server.

Data type rules created or modified via the API will not be rendered into its visual components when viewed in the Web Console.

Request Samples

HTTP 
PUT /v1/datatypes/rules/455572488728221120
{
  "label": "Credentials",
  "afconfig": "([Credentials username]) AND ([Credentials password])"
}
cURL 
curl --request PUT 'https://er-master:8339/v1/datatypes/rules/455572488728221120' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label": "Credentials",
  "afconfig": "([Credentials username]) AND ([Credentials password])"
}'

Response Samples

204 No Content
400 Bad Request

Returned if a required field(s) is not included in the request body.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Required path not present: '{fieldname}'"
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid rule_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found. Specified 'data type rule' does not exist."
}
422 Unprocessable Entity

Returned if an invalid value is provided in the request body.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid value for '{fieldname}', <error message>"
}

Delete a Data Type Rule

Delete an existing data type rule.

Request

DELETE

https://er-master:8339/v1/datatypes/rules/<rule_id>

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Path Parameters

Parameter Data Type Description
rule_id

string

Specify ID of data type rule to remove. rule_id is the response item from the /v1/datatypes/rules endpoint.
A data type rule cannot be deleted if it is used in at least one risk profile. Check the sealed response parameter from the /v1/datatypes/rules endpoint to determine if the data type rule can be removed.

Request Samples

HTTP 
DELETE /v1/datatypes/rules/455572488728221120
cURL 
curl --request DELETE 'https://er-master:8339/v1/datatypes/rules/455572488728221120' \
--user apiuser:password123

Response Samples

204 No Content
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid rule_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Resource not found. Specified 'data type rule' does not exist."
}
422 Unprocessable Entity

Returned if the data type rule is sealed and is used in at least one risk profile.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Data type rule is used in at least one risk profile."
}

Add a New Data Type Rule

Add a new data type rule.

Request

POST

https://er-master:8339/v1/datatypes/rules

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
label

string

Label for the data type rule.
afconfig

string

Define the data types criteria or advanced filter rule (for ER2 built-in data types, custom data types and test data) for the risk profile. See Advanced Filters and Data Types Criteria for more information.
If there are multiple custom data types that share the same label / identifier for a given ER2 instance, these custom data types will be evaluated against the configured data type rules as a single data type.

Refer to your custom Data Type Profiles for details on the custom data types that are set up for your Master Server.

Data type rules created or modified via the API will not be rendered into its visual components when viewed in the Web Console.

Request Samples

HTTP 
POST /v1/datatypes/rules
{
  "label": "Credentials",
  "afconfig": "([Credentials username]) AND ([Credentials password])"
}
cURL 
curl --request POST 'https://er-master:8339/v1/datatypes/rules' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label": "Credentials",
  "afconfig": "([Credentials username]) AND ([Credentials password])"
}'

Response Schema

201 Created
Response Item Data Type Description
rule_id

string

Data type rule ID assigned to the newly created data type rule.

Response Samples

201 Created 
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "rule_id": "12345678901234567890"
}
400 Bad Request

Returned if a required field(s) is not included in the request body.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Required path not present: '{fieldname}'"
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
422 Unprocessable Entity

Returned if an invalid value is provided in the request body.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid value for '{fieldname}', <error message>"
}

List Risk Profiles

Retrieve information about the risk level, data type rules and other details for all or a specific risk profile.

Request

GET

https://er-master:8339/v1/risk/profiles/{profile_id}

Authorization

Basic Authentication

Path Parameters

Parameter Data Type Description
profile_id

string

Define this parameter to retrieve data for a specific risk profile. If no value is specified, response returns data for all risk profiles.

Header Parameters

Parameter Data Type Description
Accept-Encoding

string

enum: gzip deflate

 Specify the compression algorithm to use on the response object.
Compressed content will not be returned for endpoints that return reports as files (e.g. PDF, CSV etc), endpoints that return binary files (e.g. Node Agent installers) or unsuccessful API calls.

Request Samples

HTTP 
GET /v1/risk/profiles
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/risk/profiles' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
profile_id

string

Unique risk profile ID.
label

string

Unique label for the risk profile.
level_id

string

Risk level ID associated with the risk profile. level_id is the response item from the /v1/risk/levels endpoint.
rule_id

string

Data type rule ID for the risk profile. rule_id is the response item from the /v1/datatypes/rules endpoint.
target

string <array>

List of Target IDs to map to the risk profile.
group

string <array>

List of Group IDs to map to the risk profile.
operation_status

string <array>

List of operation statuses that must be associated with the sensitive data location to be mapped to the risk profile.

See Operation Status for more information.
access

object <array>

List of users or groups with any form of permissions to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
access/username

string

Name of the user with any form of access permissions to the sensitive data location to be mapped to the risk profile. Returned if using the access filter.
access/type

string

enum: user group

 Indicates if the user is a single user or user group. Returned if using the access filter.
meta

object <array>

List of metadata values associated to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
meta/label

string

enum: Document Creator Document Created Document Modified Sender Date File Owner File Created File Modified

 Label for the metadata type. Returned if using the meta filter.
meta/value

string

Metadata value. Returned if label is File Owner, Document Creator, or Sender.

Example: "meta": [ { "label": "Document Creator", "value": "Administrator" } ]

meta/start_date

string <YYYYMMDD>

First day for the metadata date range. Returned if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the end_date parameter.

Example: To specify a 1-day range, set start_date = end_date. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210101" } ]

meta/end_date

string <YYYYMMDD>

Last day for the metadata date range. Returned if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the start_date parameter.

Example: To specify a 4-day range, set the start_date and end_date values as below. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210104" } ]

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "profile_id": "455572488728221120",
    "label": "PCI DSS Rules",
    "level_id": "1357066370714289807",
    "rule_id": "2516589672356416060",
    "target": [
      "3a4000743563929095752",
      "6173942191137960937"
    ],
    "group": [
      "253111184543318291",
      "group_id_2"
    ],
    "operation_status": [
      "Not Remediated",
      "Unable to mask"
    ],
    "access": [
      {
        "username": "Users",
        "type": "group"
      },
      {
        "username": "Admin",
        "type": "user"
      }
    ],
    "meta":   [
      {
        "label": "Document Modified",
        "start_date": "20210225",
      },
      {
        "label": "Document Modified",
        "end_date": "20210315",
      },
      {
        "label": "File Owner",
        "value": "Bruce Wayne"
      }
    ]
  }
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}
404 Not Found

Returned if an invalid profile_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'risk profile' does not exist."
}

Update a Risk Profile

Update the risk level, data type rules and other criteria for an existing risk profile. A risk profile must have at least one filter or criteria defined to be valid.

Request

PUT

https://er-master:8339/v1/risk/profiles/<profile_id>

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Path Parameters

Parameter Data Type Description
profile_id

string

Specify ID of risk profile to update or modify. profile_id is the response item from the /v1/risk/profiles endpoint.

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
label

string

Unique label for the risk profile.
level_id

string

Risk level ID associated with the risk profile. level_id is the response item from the /v1/risk/levels endpoint.
rule_id

string

Data type rule ID to be matched to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
target

string <array>

List of Target IDs to map to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
group

string <array>

List of Group IDs to map to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
operation_status

string <array>

List of operation statuses that must be associated with the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.

See Operation Status for more information.
access

object <array>

List of users or groups with any form of permissions to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
access/username

string

Name of the user with any form of access permissions to the sensitive data location to be mapped to the risk profile. Required if using the access filter.
access/type

string

enum: user group

 Specify the user type for the provided user name. Required if using the access filter.
meta

object <array>

List of metadata values associated to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
meta/label

string

enum: Document Creator Document Created Document Modified Sender Date File Owner File Created File Modified

 Label for the metadata type. Required if using the meta filter.
meta/value

string

Metadata value. Required if label is File Owner, Document Creator, or Sender.

Example: "meta": [ { "label": "Document Creator", "value": "Administrator" } ]

meta/start_date

string <YYYYMMDD>

First day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the end_date parameter.

Example: To specify a 1-day range, set start_date = end_date. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210101" } ]

meta/end_date

string <YYYYMMDD>

Last day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the start_date parameter.

Example: To specify a 4-day range, set the start_date and end_date values as below. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210104" } ]

Request Samples

HTTP 
PUT /v1/risk/profiles/455572488728221120
{
  "label": "PCI DSS Rules",
  "level_id": "1357066370714289807",
  "rule_id": "2516589672356416060",
  "target": [
    "3a4000743563929095752",
    "6173942191137960937"
  ],
  "group": [
    "253111184543318291",
    "group_id_2"
  ],
  "operation_status": [
    "Not Remediated",
    "Unable to mask"
  ],
  "access": [
    {
      "username": "Users",
      "type": "group"
    },
    {
      "username": "Admin",
      "type": "user"
    }
  ],
  "meta": [
    {
      "label": "Document Modified",
      "start_date": "20210225",
    },
    {
      "label": "Document Modified",
      "end_date": "20210315",
    },
    {
      "label": "File Owner",
      "value": "Bruce Wayne"
    }
  ]
}
cURL 
curl --request PUT 'https://er-master:8339/v1/risk/profiles/455572488728221120' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label": "PCI DSS Rules",
  "level_id": "1357066370714289807",
  "rule_id": "2516589672356416060",
  "target": [
    "3a4000743563929095752",
    "6173942191137960937"
  ],
  "group": [
    "253111184543318291",
    "group_id_2"
  ],
  "operation_status": [
    "Not Remediated",
    "Unable to mask"
  ],
  "access": [
    {
      "username": "Users",
      "type": "group"
    },
    {
      "username": "Admin",
      "type": "user"
    }
  ],
  "meta": [
    {
      "label": "Document Modified",
      "start_date": "20210225",
    },
    {
      "label": "Document Modified",
      "end_date": "20210315",
    },
    {
      "label": "File Owner",
      "value": "Bruce Wayne"
    }
  ]
}'

Response Samples

204 No Content
400 Bad Request

Returned if a required field(s) is not included in the request body.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Required path not present: '{fieldname}'"
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}
404 Not Found

Returned if an invalid profile_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'risk profile' does not exist."
}
409 Conflict

Returned if specified risk profile label is duplicated or not unique.

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: xxx
{
  "message": "Risk profile label exists. Please use a different label."
}
422 Unprocessable Entity

Returned if an invalid value is provided in the request body.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid value for '{fieldname}'."
}

Delete a Risk Profile

Delete an existing risk profile. When deleting a risk profile, the associated data type rule will also be deleted if the data type rule is not used in any other risk profile .

Request

DELETE

https://er-master:8339/v1/risk/profiles/<profile_id>

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Path Parameters

Parameter Data Type Description
profile_id

string

Specify ID of risk profile to remove. profile_id is the response item from the /v1/risk/profiles endpoint.

Request Samples

HTTP 
DELETE /v1/risk/profiles/455572488728221120
cURL 
curl --request DELETE 'https://er-master:8339/v1/risk/profiles/455572488728221120' \
--user apiuser:password123

Response Samples

204 No Content
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid profile_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'risk profile' does not exist."
}

Add a New Risk Profile

Add a new risk profile by defining the risk level, data type rules and other criteria for the risk profile. A risk profile must have at least one filter or criteria defined to be valid.

Request

POST

https://er-master:8339/v1/risk/profiles

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
label

string

Unique label for the risk profile.
level_id

string

Risk level ID associated with the risk profile. level_id is the response item from the /v1/risk/levels endpoint.
rule_id

string

Data type rule ID to be matched to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
target

string <array>

List of Target IDs to map to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
group

string <array>

List of Group IDs to map to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
operation_status

string <array>

List of operation statuses that must be associated with the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.

See Operation Status for more information.
access

object <array>

List of users or groups with any form of permissions to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
access/username

string

Name of the user with any form of access permissions to the sensitive data location to be mapped to the risk profile. Required if using the access filter.
access/type

string

enum: user group

 Specify the user type for the provided user name. Required if using the access filter.
meta

object <array>

List of metadata values associated to the sensitive data location to be mapped to the risk profile.

Optional parameter but at least one filter must be defined for the risk profile.
meta/label

string

enum: Document Creator Document Created Document Modified Sender Date File Owner File Created File Modified

 Label for the metadata type. Required if using the meta filter.
meta/value

string

Metadata value. Required if label is File Owner, Document Creator, or Sender.

Example: "meta": [ { "label": "Document Creator", "value": "Administrator" } ]

meta/start_date

string <YYYYMMDD>

First day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the end_date parameter.

Example: To specify a 1-day range, set start_date = end_date. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210101" } ]

meta/end_date

string <YYYYMMDD>

Last day for the metadata date range. Required if label is Document Created, Document Modified, Date, File Created, or File Modified, and must be paired with the start_date parameter.

Example: To specify a 4-day range, set the start_date and end_date values as below. "meta": [ { "label": "Document Modified", "start_date": "20210101" }, { "label": "Document Modified", "end_date": "20210104" } ]

Request Samples

HTTP 
POST /v1/risk/profiles
{
  "label": "PCI DSS Rules",
  "level_id": "1357066370714289807",
  "rule_id": "2516589672356416060",
  "target": [
    "3a4000743563929095752",
    "6173942191137960937"
  ],
  "group": [
    "253111184543318291",
    "group_id_2"
  ],
  "operation_status": [
    "Not Remediated",
    "Unable to mask"
  ],
  "access": [
    {
      "username": "Users",
      "type": "group"
    },
    {
      "username": "Admin",
      "type": "user"
    }
  ],
  "meta": [
    {
      "label": "Document Modified",
      "start_date": "20210225",
    },
    {
      "label": "Document Modified",
      "end_date": "20210315",
    },
    {
      "label": "File Owner",
      "value": "Bruce Wayne"
    }
  ]
}
cURL 
curl --request POST 'https://er-master:8339/v1/risk/profiles' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label": "PCI DSS Rules",
  "level_id": "1357066370714289807",
  "rule_id": "2516589672356416060",
  "target": [
    "3a4000743563929095752",
    "6173942191137960937"
  ],
  "group": [
    "253111184543318291",
    "group_id_2"
  ],
  "operation_status": [
    "Not Remediated",
    "Unable to mask"
  ],
  "access": [
    {
      "username": "Users",
      "type": "group"
    },
    {
      "username": "Admin",
      "type": "user"
    }
  ],
  "meta": [
    {
      "label": "Document Modified",
      "start_date": "20210225",
    },
    {
      "label": "Document Modified",
      "end_date": "20210315",
    },
    {
      "label": "File Owner",
      "value": "Bruce Wayne"
    }
  ]
}'

Response Schema

201 Created
Response Item Data Type Description
profile_id

string

Risk profile ID assigned to the newly created risk profile.

Response Samples

201 Created 
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "profile_id": "12345678901234567890"
}
400 Bad Request

Returned if a required field(s) is not included in the request body.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Required path not present: '{fieldname}'"
}

Returned if no filters (e.g. data type rules, targets, groups, access, metadata, operation status) are defined.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Please specify at least one criteria for the risk profile."
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid risk level ID, data type rule ID, Target ID, and/or Group ID is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified '{fieldname}' does not exist."
}
409 Conflict

Returned if specified risk profile label is duplicated or not unique.

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: xxx
{
  "message": "Risk profile label exists. Please use a different label."
}
422 Unprocessable Entity

Returned if an invalid value is provided in the request body.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Invalid value for '{fieldname}'."
}

Get Risk Profile Priority

Get the priority order for risk profiles. All existing risk profiles will be returned in the response.

Request

GET

https://er-master:8339/v1/risk/profiles/priority

Authorization

Basic Authentication

Request Samples

HTTP 
GET /v1/risk/profiles/priority
Accept: application/json
cURL 
curl --request GET 'https://er-master:8339/v1/risk/profiles/priority' \
--user apiuser:password123 \
--header "Accept: application/json"

Response Schema

200 OK
Response Item Data Type Description
[profile_id]

string <array>

List of risk profile IDs, sorted by priority. First risk profile in the array (index 0) is the profile with the highest priority.

Response Samples

200 OK 
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  "455572488728221120",
  "3a4000743563929095",
  "617394219113790937"
]
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Update Risk Profile Priority

Update the priority order for risk profiles. All existing risk profiles must be provided in the request body.

Request

PUT

https://er-master:8339/v1/risk/profiles/priority

Authorization

Basic Authentication

User Permissions

  • Global permissions: Global Admin, Risk Admin
  • Resource permissions: Not applicable

Header Parameters

Parameter Data Type Description
Content-Type

string

enum: application/json

 Media format of the data sent in the request body.

Request Schema

Parameter Data Type Description
[profile_id]

string <array>

List of risk profile IDs, sorted by priority. First risk profile in the array (index 0) is the profile with the highest priority.
All risk profiles must be provided in the request body when updating the priority of risk profiles.

Request Samples

HTTP 
PUT /v1/risk/profiles/priority
[
  "455572488728221120",
  "3a4000743563929095",
  "617394219113790937"
]
cURL 
curl --request PUT 'https://er-master:8339/v1/risk/profiles/priority' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '[
  "455572488728221120",
  "3a4000743563929095",
  "617394219113790937"
]'

Response Samples

204 No Content
400 Bad Request

Returned if the list of risk profile IDs provided in the request body is incomplete.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxx
{
  "message": "Please include all risk profiles in the request."
}
403 Forbidden

Returned if the Enterprise Recon appliance does not have the required PRO Edition license.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "This feature is only available in Enterprise Recon PRO Edition. To find out more about upgrading your license, please visit https://go.groundlabs.com/enterprise-recon-licensing."
}

Returned if a non-privileged user tries to make this request. For example, a user without Global Admin or Risk Admin permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: xxx
{
  "message": "Access denied."
}
404 Not Found

Returned if an invalid profile_id is provided in the request.

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: xxx
{
  "message": "Specified 'risk profile' does not exist."
}
422 Unprocessable Entity

Returned if duplicate risk profile IDs are provided in the request body.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: xxx
{
  "message": "Duplicate risk profile ID."
}