Accessing the API
Base URL
https://dashboard.signalsciences.net/api/v0
Examples
For examples on how to authenticate against and use the API, see Using our API.
Auth
Log into the API
post /auth
Request
Form Parameters
Responses
HTTP 200
Token to be used in subsequent requests for authentication
Response Example
{
"token": "a3024fcf-0c8a-43d8-b70b-ed537fe50650"
}
HTTP 401
Login failed
Log out the session
get /auth/logout
Request
No request parameters.
Responses
HTTP 302
Redirects to the login page
Corps
List corps
get /corps
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"data": [
{
"name": "testcorp",
"displayName": "Test Corporation",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
]
}
Get corp by name
get /corps/{corpName}
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"name": "testcorp",
"displayName": "Test Corporation",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
Update corp by name
patch /corps/{corpName}
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Body (application/json)
Display name of the corp
Small icon URI
Dashboard session timeout (seconds)
Request Example
{
"displayName": "Test Corporation1"
}
Responses
HTTP 200
Successful update
Identifying name of the corp
Display name of the corp
Small icon URI
Created RFC3339 date time
Site limit
Authentication method
Dashboard session timeout (seconds)
Response Example
{
"name": "testcorp",
"displayName": "Test Corporation1",
"smallIconURI": "",
"created": "2014-12-09T10:43:54-08:00",
"siteLimit": 5,
"sites": {
"uri": "/api/v0/corps/testcorp/sites"
},
"authType": "builtin",
"sessionMaxAgeDashboard": 2592000,
}
HTTP 400
Failed due to data input
Error message
Response Example
{"message":"Invalid displayName - must be between 3 and 100 characters."}
Get corp overview report
get /corps/{corpName}/reports/attacks
Request
Query Parameters
Pretty print the json output
Number of days ago to begin the data window. Takes the format "-Nd" where N is the number of days (maximum 30).
Number of days ago to end the data window. Takes the format "-Nd" where N is the number of days (maximum 30).
Responses
HTTP 200
Identifying name of the site
Display name of the site
Total number of requests
Number of malicious requests
Number of malicious requests blocked
Number of malicious requests that would have been blocked in blocking mode
Number of IPs that triggered blocking events due to malicious signals
Attack tag name
Number of instances of this attack tag
Total attack tags seen (note - requests can have multiple tags)
Two-letter ISO country code (note - empty for "Unknown", "private" for "Private Network"
Descriptive country name
Number of requests originating from this country
Total attack requests
Response Example
{
"data": [
{
"name":"www.example.com",
"displayName":"Example Site",
"totalCount":49285068291,
"blockedCount":29184,
"flaggedCount":0,
"attackCount":43129,
"previousPeriodAttackCount": 40218,
"previousPeriodBlockedCount": 39190,
"flaggedIPCount":15,
"topAttackTypes":[
{
"tagName":"Attack Tooling",
"tagCount":32551,
"totalCount":49712
},
{
"tagName":"CMDEXE",
"tagCount":5065,
"totalCount":49712
},
{
"tagName":"XSS",
"tagCount":4383,
"totalCount":49712
}
],
"topAttackSources":[
{
"countryCode":"CA",
"countryName":"Canada",
"requestCount":12414,
"totalCount":43129
},
{
"countryCode":"private",
"countryName":"Private Network",
"requestCount":6204,
"totalCount":43129
},
{
"countryCode":"",
"countryName":"",
"requestCount":5322,
"totalCount":43129
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid parameter - from"}
List corp activity events
get /corps/{corpName}/activity
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
The sort order
The id of the last object in the set
The id of the last object in the set
The number of entries to be returned per page
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
Pretty print the json output
Filter on events
Filter on event type
Responses
HTTP 200
Total number of matching documents
Unique ID of the activity event
Event type
Data used to format the message
Message of the event
Created RFC3339 date time
Response Example
{
"totalCount": 5,
"next": {
"uri": "/api/v0/corps/testcorp/activity?limit=1&page=2"
},
"data": [
{
"id": "random-uuid-string",
"eventType": "userMultiFactorAuthEnabled",
"msgData": {},
"message": "User (user@example.com) enabled 2FA",
"attachments": [],
"created": "2018-04-12T01:00:33Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid parameter - from"}
List users in corp
get /corps/{corpName}/users
Request
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"data": [
{
"name": "Test User",
"email": "user@example.com",
"announcements": {
"uri": "/api/v0/user/announcements"
},
"defaultDashboards": {
"uri": "/api/v0/user/defaultDashboards"
},
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00",
}
]
}
Get corp user by email
get /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "Test User",
"email": "user@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
Update corp user by email
patch /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "staging"
}
}, {
"site": {
"name": "production"
}
}]
}
}
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "",
"email": "user@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
Delete user from corp
delete /corps/{corpName}/users/{userEmail}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Invite user to corp
post /corps/{corpName}/users/{userEmail}/invite
Request
Query Parameters
Expand hidden properties for nested object
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "staging"
}
}, {
"site": {
"name": "production"
}
}]
}
}
Responses
HTTP 200
Full name of the user
Email of the user
Reference to site announcements of the user
Reference to default dashboards of the user
Reference to site memberships of the user
Role of the user (owner, admin, user, observer)
Status of the user
Whether this user has two-factor auth enabled or not
Auth-specific status of the user
Corp auth type of the user
Created RFC3339 date time
Is the user an API user
Response Example
{
"name": "",
"email": "example@example.com",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/user@example.com/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List rules in corp
get /corps/{corpName}/rules
Request
Query Parameters
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
The number of entries to be returned per page
Pretty print the json output
Responses
HTTP 200
Total count of Corp Rules
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": [
{
"id": "5e191909c931498586c6f537",
"siteNames": [],
"type": "request",
"corpScope": "global",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.1/8"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "foo",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
]
}
}
Create corp rule
post /corps/{corpName}/rules
Request
Query Parameters
Pretty print the json output
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"siteNames": [
"staging",
"production"
],
"type": "signal",
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.204"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.123"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"enabled": true,
"reason": "test",
"signal": "SQLI",
"expiration": "",
"corpScope": "specificSites"
}
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.31"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.63"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Get corp rule by id
get /corps/{corpName}/rules/{id}
Request
URI Parameters
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": {
"id": "5e191909c931498586c6f537",
"siteNames": [],
"type": "request",
"corpScope": "global",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.1/8"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "foo",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
}
}
Update corp rule
put /corps/{corpName}/rules/{id}
Request
URI Parameters
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"id": "5e1914acf13d663e6d0178ea",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.76"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.156"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion)
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
(block, allow, exclude)
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
The signal id of the signal being excluded
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"staging",
"production"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.101"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.86"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"requestlogging": "sampled",
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Delete rule from corp
delete /corps/{corpName}/rules/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Get all lists
get /corps/{corpName}/lists
Request
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": [
{
"id": "corp.known-attackers",
"name": "Known Attackers",
"type": "ip",
"description": "Malicious IPs we're tracking",
"entries": [
"198.51.100.165",
"233.252.0.215",
"192.0.2.186"
],
"createdBy": "user@example.com",
"created": "2018-08-06T18:57:55Z",
"updated": "2018-08-13T15:26:01Z"
},
{
"id": "corp.ofac-countries",
"name": "OFAC Countries",
"type": "country",
"description": "Countries on the OFAC list",
"entries": [
"MM",
"CI",
"CU",
"IR",
"KP",
"SY"
],
"createdBy": "user@example.com",
"created": "2018-08-03T20:50:54Z",
"updated": "2018-08-03T20:50:59Z"
}
]
}
Create list
post /corps/{corpName}/lists
Request
Body (application/json)
Descriptive list name
List types (string, ip, country, wildcard, signal)
Optional list description
List entries
Request Example
{
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 400
Error message
Response Example
{"message":"List cannot be deleted because a rule uses it"}
Get list by id
get /corps/{corpName}/lists/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"192.0.2.186",
"198.51.100.138",
"233.252.0.174"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 404
Error message
Response Example
{"message":"id not found"}
Update list by id
patch /corps/{corpName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List additions
List deletions
Request Example
{
"entries": {
"additions": [
"192.0.2.19"
],
"deletions": [
"192.0.2.186",
"233.252.0.174"
]
}
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"198.51.100.138",
"192.0.2.19"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"id not found"}
Replace list by id
put /corps/{corpName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List entries
Request Example
{
"description": "Some IPs we're still putting in a list",
"entries": [
"192.0.2.186",
"233.252.0.174",
"198.51.100.193"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "corp.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"192.0.2.186",
"233.252.0.174",
"198.51.100.193"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete list
delete /corps/{corpName}/lists/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List corp integrations
get /corps/{corpName}/integrations
Request
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "556a8abb3dfaa4ff28000002",
"name": "Slack message",
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"fields": null,
"events": [
"corpUpdated"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
]
}
Create corp integration
post /corps/{corpName}/integrations
Request
Body (application/json)
Integration URL
Corp integration types (mailingList, slack, microsoftTeams). Site integration types (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Request Example
{
"url":"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"type":"slack",
"events": [
"corpUpdated"
],
"note": ""
}
Responses
HTTP 200
Unique ID of the integration
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Email address of the user that created the integration
ID of the user that created the integration
Integration note
Created RFC3339 date time
Response Example
{
"ID": "5e2f5d17f13d66152d396956",
"Type": "slack",
"URL": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"ExtraFields": null,
"Events": [
"corpUpdated"
],
"Active": true,
"CreatedBy": "user@example.com",
"CreatedByID": "5e222f75f13d666c9eaec7d9",
"Note": "",
"Created": "2020-01-27T21:58:47.608359Z",
"LastStatusCode": 0
}
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
Get corp integration by id
get /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "556a8abb3dfaa4ff28000002",
"name": "Slack message",
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"fields": null,
"events": [
"corpUpdated"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Update corp integration by id
patch /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Request Example
{
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": ["listCreated", "corpUpdated"]
}
Responses
HTTP 204
Successful update
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Delete corp integration
delete /corps/{corpName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Test corp integration by id
post /corps/{corpName}/integrations/{id}/test
Request
URI Parameters
Responses
HTTP 200
Test successful
HTTP 500
Test failed
List CloudWAF instances
get /corps/{corpName}/cloudwafInstances
Request
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
Create CloudWAF instance
post /corps/{corpName}/cloudwafInstances
Request
Body (application/json)
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.(Supported region: "us-east-1", "us-west-1", "af-south-1", "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-west-1", "eu-west-2", "eu-west-3", "sa-east-1", "us-east-2", "us-west-2").
TLS minimum version. Versions Available: "1.0", "1.2".
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers. (default: false)
List of domain or request URIs, up to 100 entries.
Request Example
{
"name": "test",
"description": "test",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"useUploadedCertificates": true,
"workspaceConfigs": [
{
"siteName": "www.example.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id"],
"domains": ["www.example.com"],
"origin": "https://origin.example.com",
"passHostHeader": false,
"connectionPooling": true,
"trustProxyHeaders": false
}
]
}
]
}
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.example.com"}
Get CloudWAF instance by id
get /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
Response Example
{
"id": "id1",
"name": "website",
"description": "a website",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"useUploadedCertificates": true,
"workspaceConfigs": [
{
"siteName": "www.example.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id2"],
"domains": ["www.example.com"],
"origin": "https://www.origin.example.com",
"passHostHeader": false,
"id": "id3",
"connectionPooling": true,
"trustProxyHeaders": false
}
]
}
],
"deployment": {
"status": "done",
"message": "",
"egressIPs": [
{
"ip": "233.252.0.152",
"status": "reachable",
"updatedAt": "2021-04-08T17:10:58Z"
}
],
"dnsEntry": "example.signalsciencescloud.net"
},
"useUploadedCertificates": true,
"createdBy": "user@example.com",
"created": "2021-04-08T15:50:46Z"
}
Update CloudWAF instance
put /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Body (application/json)
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.(Supported region: "us-east-1", "us-west-1", "af-south-1", "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-north-1", "eu-west-1", "eu-west-2", "eu-west-3", "sa-east-1", "us-east-2", "us-west-2").
TLS minimum version. Versions Available: "1.0", "1.2".
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers. (default: false)
List of domain or request URIs, up to 100 entries.
Responses
HTTP 200
CloudWAF instance unique identifier.
Friendly name to identify a CloudWAF instance.
Friendly description to identify a CloudWAF instance.
Region the CloudWAF Instance is being deployed to.
TLS minimum version.
Allows switching between using an uploaded certificate or using the default certificate. When disabled, the default certificate is used.
Site name.
Set instance location to "direct" or "advanced".
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
Specify the protocol or protocols required.
Route unique identifier.
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
Origin server URI.
Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation). If using Heroku or Server Name Indications (SNI), this must be disabled(default: false).
List of domain or request URIs, up to 100 entries.
If disabled, opened connections will not be reused (default: true).
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: false)
Current status of the deployment
CloudWAF instance message
Egress IP address CloudWAF will be directing traffic to origin from.
EgressIP Status.
When EgressIP was last updated on.
CloudWAF instance's DNS Entry.
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
CloudWAF instance created by.
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.example.com"}
Delete CloudWAF instance
delete /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Responses
HTTP 204
delete successful
HTTP 400
Response Example
{"message":"cannot delete with pending instance"}
Restart CloudWAF instance
post /corps/{corpName}/cloudwafInstances/{deployment_id}/restart
Request
URI Parameters
Responses
HTTP 204
restart successful
List CloudWAF certificates
get /corps/{corpName}/cloudwafCerts
Request
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Upload CloudWAF certificate
post /corps/{corpName}/cloudwafCerts
Request
Body (application/json)
Friendly name to identify a CloudWAF certificate
List of domains - deprecated
Private key of the certificate in PEM format - must be unencrypted
Body of the certificate in PEM format
Certificate chain in PEM format
Request Example
{
"name": "someCertificate",
"domains": [
"example.com"
],
"privateKey": "-----BEGIN PRIVATE KEY-----\n someCertificate private key \n-----END PRIVATE KEY-----\n",
"certificateBody": "-----BEGIN CERTIFICATE-----\n someCertificate certificate body \n-----END CERTIFICATE-----\n",
"certificateChain": ""
}
Responses
HTTP 201
CloudWAF certificate unique identifier
Response Example
{"id": "someCertificate-id" }
HTTP 400
Response Example
{"message":"example.net is not associated with the specified TLS certificate.: unexpected domain, got = example.net"}
Get CloudWAF certificate by id
get /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Response Example
{
"id":"some-id",
"name":"website",
"domains":["example.com"],
"certificateBody":"-----BEGIN CERTIFICATE-----\n certificate body \n-----END CERTIFICATE-----",
"certificateChain":"",
"fingerprint": "",
"expiresAt":"2021-05-02T20:48:02Z",
"status":"active",
"createdBy":"user@example.com",
"created":"2021-02-01T22:05:23Z",
"updatedBy":"user@example.com",
"updatedAt":"2021-02-01T22:06:17Z"
}
Update CloudWAF certificate by id
put /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Body (application/json)
Friendly name to identify a CloudWAF certificate
Request Example
{
"name": "some name"
}
Responses
HTTP 200
CloudWAF certificate unique identifier
Friendly name to identify a CloudWAF certificate
Common name of the uploaded certificate
Subject alternative names from the uploaded certificate
List of domains - deprecated
Body of the certificate in PEM format
Certificate chain in PEM format
SHA1 fingerprint of the certififcate
TimeStamp for when certificate expires in RFC3339 date time format
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
Email address of the user that created the certfificate
Created RFC3339 date time
Email address of the user that updated the certificate
Updated RFC3339 date time
Response Example
{
"id": "some-id",
"name": "some certificate",
"domains": [
"website"
],
"certificateBody": "-----BEGIN CERTIFICATE-----\n some certificate certificate body\n-----END CERTIFICATE-----\n",
"certificateChain": "-----BEGIN CERTIFICATE-----\n some certificate certificate chain\n-----END CERTIFICATE-----\n",
"fingerprint": "",
"expiresAt": "2022-01-28T20:32:47Z",
"status": "active",
"createdBy": "user@example.com",
"created": "2021-01-28T20:34:06.952625Z",
"updatedBy": "user@example.com",
"updatedAt": "2021-03-10T17:51:17.540049Z"}
HTTP 400
Response Example
{"message":"name cannot be empty"}
Delete CloudWAF certificate by id
delete /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
HTTP 400
Response Example
{"message":"certificate f179ae5fd6d8b5f742753e7019936d7e58e5c5bf used in deployments: cert is in use"}
Sites
List sites in corp
get /corps/{corpName}/sites
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Filter on site name or display name
The page of the results
The number of entries to be returned
Filter on agent mode
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Response Example
{
"data": [
{
"name": "www.example.com",
"displayName": "My Website",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 86400,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
]
}
Create site in corp
post /corps/{corpName}/sites
Request
URI Parameters
Corp shortname
Query Parameters
Pretty print the json output
Body (application/json)
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Request Example
{
'name": "www.example.com",
"displayName": "Example Website",
"agentLevel": "block",
"blockDurationSeconds": 259200,
"blockHTTPCode": 302,
"blockRedirectURL": "/blocked/"
}
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Response Example
{
"name": "www.example.com",
"displayName": "My Website1",
"agentLevel": "block",
"blockHTTPCode": 302,
"blockDurationSeconds": 259200,
"blockRedirectURL": "/blocked/",
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"tags": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/tags"
},
"rules": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rules"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
HTTP 400
Error message
Response Example
{"message":"Invalid block code - must be between 100 and 599"}
Get site by name
get /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Response Example
{
"name": "www.example.com",
"displayName": "My Website",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 86400,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"rateLimitedIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rateLimitedIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
}
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Update a site by name
patch /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Request Example
{
"displayName": "My Website1",
"agentLevel": "block",
"blockDurationSeconds": 259200,
"attackThresholds": [
{
"interval": 1,
"threshold": 25
},
{
"interval": 10,
"threshold": 60
},
{
"interval": 60,
"threshold": 100
}
]
}
Responses
HTTP 200
Identifying name of the site
Display name of the site
Agent action level - 'block', 'log' or 'off'
Agent IP anonimization mode - 'EU' or 'off'
Duration to block an IP in seconds
HTTP response code to send when when traffic is being blocked
URL to redirect to when blockHTTPCode is 301 or 302
Created RFC3339 date time
Reference to the site's suspicious IPs
Reference to the site's analytics events
Attack threshold parameters for system site alerts
Number of minutes during which attack signals per IP address are counted
Number of attack signals per IP address that must be detected during the interval before the related IP address is flagged
Determines whether to instantly block requests tagged with at least one attack signal
Response Example
{
"name": "www.example.com",
"displayName": "My Website1",
"agentLevel": "block",
"blockHTTPCode": 406,
"blockDurationSeconds": 259200,
"created": "2014-12-09T10:43:54-08:00",
"whitelist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/whitelist"
},
"blacklist": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/blacklist"
},
"events": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events"
},
"requests": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests"
},
"redactions": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/redactions"
},
"suspiciousIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/suspiciousIPs"
},
"rateLimitedIPs": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/rateLimitedIPs"
},
"monitors": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/monitors"
},
"integrations": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/integrations"
},
"headerLinks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/headerLinks"
},
"agents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/agents"
},
"alerts": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/alerts"
},
"analyticsEvents": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events"
},
"topAttacks": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/top/attacks"
},
"tags": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/tags"
},
"rules": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/advancedRules"
},
"members": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/members"
},
"attackThresholds": [
{
"interval": 1,
"threshold": 25
},
{
"interval": 10,
"threshold": 60
},
{
"interval": 60,
"threshold": 100
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid block code - must be between 100 and 599"}
Delete site
delete /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Delete successful
Deploy site to edge
put /corps/{corpName}/sites/{siteName}/edgeDeployment
Configure the Next-Gen WAF site for Edge Deployment.
Request
Headers
Fastly API key with write access to the Fastly service. This field is only required if you are linking Compute services to the Next-Gen WAF.
Must be 'application/json'
Body (application/json)
List of Compute services. This field is only required if you are linking Compute services to the Next-Gen WAF.
Request Example
{"authorizedServices": ["SU1Z0isxPaozGVKXdv0eY"]}
Responses
HTTP 200
Initialization successful
Remove an Edge Deployment
delete /corps/{corpName}/sites/{siteName}/edgeDeployment
Remove the Edge Deployment of a Next-Gen WAF Site. It does not affect other Site configurations or prevent the Site from being re-deployed to the edge again later.
Request
Headers
Must be 'application/json'
Responses
HTTP 200
Edge Deployment successfully removed
List site activity events
get /corps/{corpName}/sites/{siteName}/analytics/events
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
The sort order
The id of the last object in the set
The id of the last object in the set
The number of entries to be returned per page
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
Pretty print the json output
Filter on events
Filter on event type
Responses
HTTP 200
Total number of matching documents
Unique ID of the activity event
Event type
Data used to format the message
Message of the event
Created RFC3339 date time
Response Example
{
"totalCount": 5,
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/analytics/events?limit=1&page=2"
},
"data": [
{
"id": "558cf75c3dfaa4b9c2000001",
"eventType": "blacklistIP",
"msgData": {"ip": "192.0.2.149"},
"message": "User (user@example.com) blacklisted \"192.0.2.149\"",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Create or Update Delivery Integration
put /corps/{corpName}/sites/{siteName}/deliveryIntegration/{fastlySID}
Connect this site to a Delivery service to protect traffic going to origin. Deploys or updates latest VCL and configuration to the Delivery service. Copies backends from the Delivery service to the Edge Deployment. These configurations are needed to forward traffic to the WAF. Note that the changes to the Fastly service will be activated unless the `activateVersion` field is passed as `false`.
Request
URI Parameters
Fastly service ID
Headers
Fastly API key with write access to the Fastly service
Must be 'application/json'
Body (application/json)
Optional percent of requests that should be inspected by Next-Gen WAF
Optional flag that indicates whether the VCL version should be activated (true) or not activated (false)
Request Example
{
"percentEnabled": 0,
"activateVersion": true
}
Responses
HTTP 200
Service configuration successful
Detach Edge Deployment Service
delete /corps/{corpName}/sites/{siteName}/deliveryIntegration/{fastlySID}
Stop securing the given Delivery service and disconnect the Fastly service from this Edge Deployment.
Request
URI Parameters
Fastly service ID
Headers
Fastly API key with write access to the Fastly service
Must be 'application/json'
Responses
HTTP 200
Service detachment successful
Update Edge Deployment Backends
put /corps/{corpName}/sites/{siteName}/deliveryIntegration/{fastlySID}/backends
Check if any changes were made to the Fastly service's backends and updates the Edge Deployment if necessary. Note that the Fastly service must already be configured for Edge Deployment.
Request
Headers
Fastly API key with read access to the Fastly service
Must be 'application/json'
Responses
HTTP 200
Backend syncing successful
List site members
get /corps/{corpName}/sites/{siteName}/members
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"data": [
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Add members to site
post /corps/{corpName}/sites/{siteName}/members
Request
Query Parameters
Pretty print the json output
Body (application/json)
List of existing user email addresses
Request Example
{
"members: ["user@example.com"]
}
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"data": [
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid user"}
Get site member by email
get /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
},
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete from site members
delete /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Invite a site member
post /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}/invite
Request
Query Parameters
Pretty print the json output
Body (application/json)
Role of the user (owner, admin, user, observer)
Request Example
{
"role": "observer"
}
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"user": {
"name": "Example User",
"email": "user@example.com",
"status": "active",
"authStatus": "none",
"corpAuthType": "builtin",
"apiUser": false
},
"role": "owner"
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List rules in site
get /corps/{corpName}/sites/{siteName}/rules
Request
Query Parameters
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
The number of entries to be returned per page
Pretty print the json output
Responses
HTTP 200
Total count of Site Rules
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint))
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": {
"totalCount": 1,
"data": [
{
"id": "5e191909c931498586c6f537",
"siteNames": [
"www.example.com"
],
"type": "request",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.100"
}
],
"actions": [
{
"type": "block"
}
],
"requestlogging": "sampled",
"reason": "test",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
]
}
}
Create site rule
post /corps/{corpName}/sites/{siteName}/rules
Request
Query Parameters
Pretty print the json output
Body (application/json)
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit. Can be set to ALL-REQUESTS to act upon all requests from a client.
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 86400)
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"type": "signal",
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.136"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.212"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"enabled": true,
"reason": "Example site rule",
"signal": "SQLI",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint))
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.136"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "233.252.0.212"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Example site rule",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:41:04Z"
}
Get site rule by id
get /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint))
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "192.0.2.137"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Example site rule",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:41:04Z"
}
Update site rule
put /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Body (application/json)
Sites with the rule available. Rules with a global corpScope will return '[]'.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint)
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit. Can be set to ALL-REQUESTS to act upon all requests from a client.
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 86400)
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"id": "5e321810f13d660ea4cd8d0f",
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.177"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": ""
}
Responses
HTTP 200
Sites with the rule available.
Type of rule (request, signal exclusion, rateLimit)
Conditions that must be matched when evaluating the request (all, any)
(group, single, multival)
type: group - Conditions that must be matched when evaluating the request (all, any)
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueInt, valueIp, signalType, ja3Fingerprint))
type: multival - (postParameter, queryParameter, requestCookie, requestHeader, responseHeader, signal)
type: single - (equals, doesNotEqual, contains, doesNotContain, greaterEqual, lesserEqual, like, notLike, exists, doesNotExist, matches, doesNotMatch, inList, notInList)
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
For rateLimit rules, the signal to act upon when activating the rateLimit
(block, allow, exclude, browserChallenge, verifyToken) (rateLimit rule valid values: logRequest, blockSignal, browserChallenge, verifyToken)
URL to redirect to when blockHTTPCode is 301 or 302
HTTP response code for blocked requests (default: 406)
Allows switching between a non-interactive and interactive browser challenge. Only valid with the browserChallenge action type.
Indicates whether to store the logs for requests that match the rule's conditions (sampled) or not store them (none). This field is only available for request rules.
Requests counted before activating the rate limit
Length of time in minutes the threshold should be measured for
Length of time in seconds to enforce the rule for once activated
Description of the rule
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
The user that created the rule
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "5e321810f13d660ea4cd8d0f",
"siteNames": [
"www.example.com"
],
"type": "signal",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "198.51.100.177"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "203.0.113.247"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": "",
"createdBy": "user@example.com",
"created": "2020-01-29T23:41:04Z",
"updated": "2020-01-29T23:45:21Z"
}
Delete rule from site
delete /corps/{corpName}/sites/{siteName}/rules/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
List available rule templates
get /corps/{corpName}/sites/{siteName}/templates
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"data": [
{
"id": "LOGINATTEMPT",
"name": "LOGINATTEMPT",
"shortName": "Login Attempts",
"description": "Indicates a login attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/auth/*"
}
]
},
{
"id": "REGATTEMPT",
"name": "REGATTEMPT",
"shortName": "Registration Attempts",
"description": "Indicates a registration attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/register/*"
}
]
}
]
}
Get rule template by id
get /corps/{corpName}/sites/{siteName}/templates/{id}
Request
URI Parameters
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"id": "LOGINATTEMPT",
"name": "LOGINATTEMPT",
"shortName": "Login Attempts",
"description": "Indicates a login attempt",
"fields": [
{
"name": "path",
"type": "string",
"label": "If a request's POST path equals",
"placeholder": "/auth/*"
}
]
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List configured templated rules
get /corps/{corpName}/sites/{siteName}/configuredtemplates
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"data": [
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
]
}
Get configured template rule by id
get /corps/{corpName}/sites/{siteName}/configuredtemplates/{id}
Request
URI Parameters
Responses
HTTP 200
Name of templated rule
Display name of templated rule
Description of templated rule
Name of template field
Value type of template field
Short description for template field
Placeholder value for template field
Response Example
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Update site template rule by name
post /corps/{corpName}/sites/{siteName}/configuredtemplates/{id}
Request
URI Parameters
Body (application/json)
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
A flag to toggle this detection
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Request Example
{
"alertAdds": [
{
"action": "info",
"enabled": true,
"interval": 1,
"skipNotifications": false,
"longName": "LOGINATTEMPT-50-in-1",
"threshold": 50
}
],
"alertDeletes": [],
"alertUpdates": [],
"detectionAdds": [
{
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
]
}
],
"detectionDeletes": [],
"detectionUpdates": []
}
Responses
HTTP 200
Name of templated rule
A flag to toggle this detection
The email of the user that created the alert
Created RFC3339 date time
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"name": "LOGINATTEMPT",
"detections": [
{
"id": "5e4d815ac931492a13d95e60",
"name": "LOGINATTEMPT",
"enabled": true,
"fields": [
{
"name": "path",
"value": "/auth/*"
}
],
"created": "2020-02-19T10:41:30-08:00",
"createdBy": "user@example.com"
}
],
"alerts": [
{
"id": "5e4d815ac931492a13d95e62",
"tagName": "LOGINATTEMPT",
"longName": "LOGINATTEMPT-50-in-1",
"type": "template",
"interval": 1,
"threshold": 50,
"skipNotifications": false,
"enabled": true,
"action": "info",
"fieldName": "remoteIP",
"createdBy": "",
"created": "2020-02-19T18:41:30Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Validation failed"}
Get all lists
get /corps/{corpName}/sites/{siteName}/lists
Request
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"data": [
{
"id": "site.known-attackers",
"name": "Known Attackers",
"type": "ip",
"description": "Malicious IPs we're tracking",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-06T18:57:55Z",
"updated": "2018-08-13T15:26:01Z"
},
{
"id": "site.ofac-countries",
"name": "OFAC Countries",
"type": "country",
"description": "Countries on the OFAC list",
"entries": [
"MM",
"CI",
"CU",
"IR",
"KP",
"SY"
],
"createdBy": "user@example.com",
"created": "2018-08-03T20:50:54Z",
"updated": "2018-08-03T20:50:59Z"
}
]
}
Create list
post /corps/{corpName}/sites/{siteName}/lists
Request
Body (application/json)
Descriptive list name
List types (string, ip, country, wildcard, signal)
Optional list description
List entries
Request Example
{
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 400
Error message
Response Example
{"message":"List cannot be deleted because a rule uses it"}
Get list by id
get /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"203.0.113.247",
"198.51.100.177",
"192.0.2.137"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Update list by id
patch /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List additions
List deletions
Request Example
{
"entries": {
"additions": [
"203.0.113.6"
],
"deletions": [
"203.0.113.247",
"192.0.2.137"
]
}
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"198.51.100.177",
"203.0.113.6"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Replace list by id
put /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Body (application/json)
Optional list description
List entries
Request Example
{
"description": "Some IPs we're still putting in a list",
"entries": [
"203.0.113.247",
"192.0.2.137",
"192.0.2.223"
]
}
Responses
HTTP 200
Site-specific unique ID of the list
Descriptive list name
List types (string, ip, country, wildcard)
Optional list description
List entries
Email address of the user that created the item
Created RFC3339 date time
Last updated RFC3339 date time
Response Example
{
"id": "site.my-new-list",
"name": "My New List",
"type": "ip",
"description": "Some IPs we're still putting in a list",
"entries": [
"203.0.113.247",
"192.0.2.137",
"192.0.2.223"
],
"createdBy": "user@example.com",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Error message
Response Example
{"message":"ID not found"}
Delete list
delete /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Error message
Response Example
{"message":"ID not found"}
List alerts
get /corps/{corpName}/sites/{siteName}/alerts
Request
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
data: [
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
]
}
Create alert
post /corps/{corpName}/sites/{siteName}/alerts
Request
Body (application/json)
The name of the tag whose occurrences the alert is watching. Must match an existing tag
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Request Example
{
"tagName": "custom-tag",
"longName": "Example Alert",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged"
}
Responses
HTTP 201
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
Get alert
get /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "5e45dc78c931491dc923e4a6",
"tagName": "site.example-signal-tag",
"longName": "Alert",
"type": "siteAlert",
"interval": 1,
"threshold": 10,
"skipNotifications": false,
"enabled": true,
"action": "flagged",
"fieldName": "remoteIP",
"createdBy": "user@example.com",
"created": "2020-02-13T23:23:03Z",
"updated": "2020-01-13T23:23:03Z"
}
Update alert
patch /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Body (application/json)
The name of the tag whose occurrences the alert is watching. Must match an existing tag
A human readable description of the alert. Must be between 3 and 25 characters.
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
Request Example
{
"tagName": "custom-tag",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged"
}
Responses
HTTP 200
Site-specific unique ID of the alert
The name of the tag whose occurrences the alert is watching.
A human readable description of the alert. Must be between 3 and 25 characters.
Type of alert (siteAlert, template, rateLimit, siteMetric)
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
The number of occurrences of the tag in the interval needed to trigger the alert.
The number of seconds this alert is active.
A flag to disable external notifications - slack, webhooks, emails, etc.
A flag to toggle this alert.
A flag that describes what happens when the alert is triggered. 'info' creates an incident in the dashboard. 'flagged' creates an incident and blocks traffic for 24 hours.
The email of the user that created the alert
Created RFC3339 date time
Response Example
{
"id": "random-uuid-string",
"siteId": "site-id-hex",
"tagName": "custom-tag",
"interval": 1,
"threshold": 10,
"enabled": true,
"action": "flagged",
"created": "2015-02-14T21:17:16Z"
}
Delete alert
delete /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
Search requests
get /corps/{corpName}/sites/{siteName}/requests
Request
Query Parameters
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
The number of entries to be returned per page
Pretty print the json output
Responses
HTTP 200
Total number of records matching the search
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"totalCount": 3,
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/requests?limit=1&page=1"
},
"data": [
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"responseMillis": 0,
"agentResponseCode": 200,
"summation": {
"attrs": {
"bot_j": "2bab0327a296230f9f6427341e716ea0",
},
},
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get request by ID
get /corps/{corpName}/sites/{siteName}/requests/{requestID}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"agentResponseCode": 200,
"summation": {
"attrs": {
"bot_j": "2bab0327a296230f9f6427341e716ea0",
},
},
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get request feed
get /corps/{corpName}/sites/{siteName}/feed/requests
Request
Query Parameters
Pretty print the json output
The POSIX Unix time to start. Has restrictions - see Extracting Your Data.
Responses
HTTP 200
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/feed/requests?next=cXVlcnlUaGVuRmV0Y2g7Mjs4NDM6cGhsQU1DdHRUTWEtWTJNdFRucVpDZzs4NDI6cGhsQU1DdHRUTWEtWTJNdFRucVpDZzswOw=="
},
"data": [
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"responseMillis": 0,
"agentResponseCode": 200,
"summation": {
"attrs": {
"bot_j": "2bab0327a296230f9f6427341e716ea0",
},
},
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid timestamp param"}
HTTP 500
Error message
Response Example
{"message":"Error performing search"}
HTTP 504
Error message
Response Example
{"message":"Feed timeout exceeded"}
Retrieve a paginated feed
post /corps/{corpName}/sites/{siteName}/feed/requests
Request
Query Parameters
Pretty print the json output
Form Parameters
Must be 'application/x-www-form-urlencoded'
Responses
HTTP 200
Unique ID of the request
Timestamp RFC3339 date time
Server hostname
Server name
URI
Path
User agent of the request
Remote IP address
Remote hostname
Remote country code
HTTP method e.g. PUT
HTTP protocol e.g. HTTP/1.1
HTTP response code
HTTP response size
Response time in millis
Agent response code
Type of tag
Where the tag was detected
Value
Detector
Response Example
{
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/feed/requests?next=cXVlcnlUaGVuRmV0Y2g7Mjs4NDM6cGhsQU1DdHRUTWEtWTJNdFRucVpDZzs4NDI6cGhsQU1DdHRUTWEtWTJNdFRucVpDZzswOw=="
},
"data": [
{
"id": "54871be4f749437f4f00008d",
"serverHostname": "local",
"remoteIP": "95.128.246.44",
"remoteHostname": "95-128-246-44.avk-com.ru",
"remoteCountryCode": "RU",
"userAgent": "Mozilla/5.00 (Nikto/2.1.5) (Evasions:None) (Test:000691)",
"timestamp": "2014-12-09T15:57:24Z",
"method": "PUT",
"serverName": "",
"protocol": "HTTP/1.1",
"path": "/help/../../../../../../../../../../../../../../../../etc/shadow",
"uri": "",
"responseCode": 503,
"responseSize": 88336,
"responseMillis": 0,
"agentResponseCode": 200,
"summation": {
"attrs": {
"bot_j": "2bab0327a296230f9f6427341e716ea0",
},
},
"tags": [
{
"type": "HTTP503",
"location": "HTTP",
"value": "503",
"detector": "bogus"
},
{
"type": "SANS",
"location": "HTTP",
"value": "95.128.246.44",
"detector": "bogus"
},
{
"type": "SQLI",
"location": "QUERYSTRING",
"value": "foo=1 OR 1",
"detector": "bogus"
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid timestamp param"}
HTTP 500
Error message
Response Example
{"message":"Error performing search"}
HTTP 504
Error message
Response Example
{"message":"Feed timeout exceeded"}
List events
get /corps/{corpName}/sites/{siteName}/events
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
The sort order
The id of the last object in the set
The id of the last object in the set
The number of entries to be returned per page
The page of the results. Each page is limited to 1,000 requests, and a maximum of 10,000 requests in total will be returned.
Pretty print the json output
Filter based on action
Filter based on tag
Filter based on IP
Filter based on status
Responses
HTTP 200
Total number of matching documents
Unique ID of the event
Timestamp RFC3339 date time
Source information
Country code
Remote hostname
Either "flagged" (IP is flagged and subsequent malicious requests will be blocked) or "info" (IP is flagged and subsequent requests will be logged).
Key attack type - value number of
Total number of requests
Total number of tags
Time window in seconds where the items were detected
Expires RFC3339 date time
email of the user if the event is expired manually
Response Example
{
"totalCount": 5,
"next": {
"uri": "/api/v0/corps/testcorp/sites/www.example.com/events?limit=1&page=2"
},
"data": [
{
"id": "54de69dcba53b02fbf000018",
"timestamp": "2015-02-13T21:17:16Z",
"source": "162.245.23.109",
"remoteCountryCode": "AU",
"remoteHostname": "",
"userAgents": [
"Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0)"
],
"action": "flagged",
"type": "attack",
"reasons": {
"SQLI": 99
},
"requestCount": 1,
"tagCount": 1,
"window": 60,
"expires": "2015-02-14T21:17:16Z",
"expiredBy": ""
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get event by ID
get /corps/{corpName}/sites/{siteName}/events/{eventID}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the event
Timestamp RFC3339 date time
Source information
Country code
Remote hostname
Either "flagged" (IP is flagged and subsequent malicious requests will be blocked) or "info" (IP is flagged and subsequent requests will be logged).
Key attack type - value number of
Total number of requests
Total number of tags
Time window in seconds where the items were detected
Expires RFC3339 date time
email of the user if the event is expired manually
Response Example
{
"id": "54de69dcba53b02fbf000018",
"timestamp": "2015-02-13T21:17:16Z",
"source": "162.245.23.109",
"remoteCountryCode": "AU",
"remoteHostname": "",
"userAgents": [
"Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0)"
],
"action": "flagged",
"type": "attack",
"reasons": {
"SQLI": 99
},
"requestCount": 1,
"tagCount": 1,
"window": 60,
"expires": "2015-02-14T21:17:16Z",
"expiredBy": ""
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Expire an event by ID
post /corps/{corpName}/sites/{siteName}/events/{eventID}/expire
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the event
Timestamp RFC3339 date time
Source information
Country code
Remote hostname
Either "flagged" (IP is flagged and subsequent malicious requests will be blocked) or "info" (IP is flagged and subsequent requests will be logged).
Key attack type - value number of
Total number of requests
Total number of tags
Time window in seconds where the items were detected
Expires RFC3339 date time
email of the user if the event is expired manually
Response Example
{
"id": "54de69dcba53b02fbf000018",
"timestamp": "2015-02-13T21:17:16Z",
"source": "162.245.23.109",
"remoteCountryCode": "AU",
"remoteHostname": "",
"userAgents": [
"Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0)"
],
"action": "flagged",
"type": "attack",
"reasons": {
"SQLI": 99
},
"requestCount": 1,
"tagCount": 1,
"window": 60,
"expires": "2015-02-14T21:17:16Z",
"expiredBy": ""
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List suspicious IPs
get /corps/{corpName}/sites/{siteName}/suspiciousIPs
Request
Query Parameters
Pretty print the json output
The number of IPs to be returned
Responses
HTTP 200
IP address
Remote country code
Remote hostname
Percent towards flagged threshold
Attack tag seen from this IP
Label for this attack tag
Beginning of most recent interval in which this attack was seen
Time of most recent attack
Response Example
{
"data": [
{
"source": "95.128.246.44",
"percent": 20,
"remoteCountryCode": "RU",
"remoteHostname": "95-128-246-44.avk-com.ru",
"tagName": "USERAGENT",
"shortName": "Attack Tooling",
"reasons": {
"USERAGENT": 99
},
"intervalStart": "2016-08-09T17:05:17Z",
"timestamp": "2016-08-09T18:05:17Z",
},
{
"source": "95.128.246.45",
"percent": 6,
"remoteCountryCode": "RU",
"remoteHostname": "95-128-246-45.avk-com.ru",
"tagName": "SQLI",
"shortName": "SQLI",
"reasons": {
"SQLI": 2,
"TRAVERSAL": 1,
"XSS": 4
},
"intervalStart": "2016-08-09T17:05:17Z",
"timestamp": "2016-08-09T18:05:17Z",
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
List rate-limited IPs
get /corps/{corpName}/sites/{siteName}/rateLimitedIPs
Request
Query Parameters
Pretty print the json output
The IP address used to filter results
The maximum number of IPs to be returned per page
The page number of the results
signal ID
Responses
HTTP 200
Created RFC3339 date time
Signal name
IP address
RFC3339 date time when the rule will automatically be disabled. If rule is always enabled, will return empty string
Response Example
{
"data": [
{
"id": "558cde3f3dfaa4a82900000a",
"ip": "95.128.246.44",
"siteID": "cb8cde3f3dfaa4a82900d00b",
"signal": "signal nickname",
"created": "2016-08-09T17:05:17Z",
"expires": "2017-08-09T17:05:17Z",
},
{
"id": "fd8cde3f3dfaa4a82900200f",
"ip": "95.128.246.45",
"siteID": "668cde3f3dfaa4a829000110c",
"signal": "another signal nickname",
"created": "2016-08-09T17:05:17Z",
"expires": "2017-08-09T17:05:17Z",
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get whitelist
get /corps/{corpName}/sites/{siteName}/whitelist
Request
Responses
HTTP 200
Unique ID of the tag
IP address
Expires RFC3339 date time, or empty for does not expire
Note associated with the tag
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "558cde3f3dfaa4a82900000a",
"source": "192.0.2.16",
"expires": "2014-12-19T21:28:54-08:00",
"note": "Sample",
"createdBy": "user@example.com",
"created": "2014-12-11T22:51:56-08:00"
}
]
}
Add to whitelist
put /corps/{corpName}/sites/{siteName}/whitelist
Request
Body (application/json)
IP address
Note associated with the tag
Optional RFC3339-formatted datetime in the future. Omit this paramater if it does not expire.
Request Example
{
"source": "203.0.113.101",
"note": "Example note"
}
Responses
HTTP 200
Unique ID of the tag
IP address
Expires RFC3339 date time, or empty for does not expire
Note associated with the tag
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "558cde293dfaa4a829000009",
"source": "192.0.2.16",
"expires": "",
"note": "Example Note",
"createdBy": "user@example.com",
"created": "2014-12-11T22:51:56-08:00"
}
HTTP 400
Error message
Response Example
{"message":"Invalid IP address"}
Delete from whitelist
delete /corps/{corpName}/sites/{siteName}/whitelist/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Could not find the id
Error message
Response Example
{"message":"Not found"}
Get blacklist
get /corps/{corpName}/sites/{siteName}/blacklist
Request
Responses
HTTP 200
Unique ID of the tag
IP address
Expires RFC3339 date time, or empty for does not expire
Note associated with the tag
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "558cde293dfaa4a829000009",
"source": "192.0.2.16",
"expires": "2014-12-19T21:28:54-08:00",
"note": "Sample",
"createdBy": "user@example.com",
"created": "2014-12-11T22:51:56-08:00"
}
]
}
Add to blacklist
put /corps/{corpName}/sites/{siteName}/blacklist
Request
Body (application/json)
IP address
Note associated with the tag
Optional RFC3339-formatted datetime in the future. Omit this paramater if it does not expire.
Request Example
{
"source": "203.0.113.101",
"note": "Example note"
}
Responses
HTTP 200
Unique ID of the tag
IP address
Expires RFC3339 date time, or empty for does not expire
Note associated with the tag
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "558cde3f3dfaa4a82900000a",
"source": "192.0.2.16",
"expires": "",
"note": "Example Note",
"createdBy": "user@example.com",
"created": "2014-12-11T22:51:56-08:00"
}
HTTP 400
Error message
Response Example
{"message":"Invalid IP address"}
Delete from blacklist
delete /corps/{corpName}/sites/{siteName}/blacklist/{id}
Request
URI Parameters
Responses
HTTP 204
Successful removal from the list
HTTP 404
Could not find the id
Error message
Response Example
{"message":"Not found"}
List redactions
get /corps/{corpName}/sites/{siteName}/redactions
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Total count of Redactions
Unique identifier for the redaction
Field name
Type of redaction (0: Request Parameter, 1: Request Header, 2: Response Header)
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"totalCount" : 1,
"data": [
{
"id": "0a54cf363621",
"field": "privateField",
"redactionType": 0,
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Add to redactions
post /corps/{corpName}/sites/{siteName}/redactions
Request
Query Parameters
Pretty print the json output
Body (application/json)
Field name
Type of redaction (0: Request Parameter, 1: Request Header, 2: Response Header)
Request Example
{
"field": "privateField",
"redactionType": 2,
}
Responses
HTTP 200
Total count of Redactions
Unique identifier for the redaction
Field name
Type of redaction (0: Request Parameter, 1: Request Header, 2: Response Header)
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"totalCount" : 1,
"data": [
{
"id": "0a54cf363622",
"field": "privateField",
"redactionType": 2,
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Update a redaction
patch /corps/{corpName}/sites/{siteName}/redactions/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Field name
Type of redaction (0: Request Parameter, 1: Request Header, 2: Response Header)
Request Example
{
"redactionType": 1,
}
Responses
HTTP 200
Unique identifier for the redaction
Field name
Type of redaction (0: Request Parameter, 1: Request Header, 2: Response Header)
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "0a54cf363622",
"field": "privateField",
"redactionType": 1,
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"Not found"}
Delete from redactions
delete /corps/{corpName}/sites/{siteName}/redactions/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"Not found"}
List agents
get /corps/{corpName}/sites/{siteName}/agents
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Whether agent was seen in past 5 minutes
RPC Address
Command line arguments
Commit SHA of current build
Counter of connections dropped by agent
Gauge of simultaneous connections
Counter of total connections
Number of requests in last interval
Decision time in ms, 50th percentile
Decision time in ms, 95th percentile
Decision time in ms, 99th percentile
Configuration flag for on/off
Timestamp of last rules update in RFC3339
Timestamp of last heartbeat in RFC3339
GOMAXPROCS setting
Name
Byte tally of read requests (GET)
Counter of total RPC PostRequests
Counter of total RPC PreRequests
Counter of total RPC UpdateRequests
Counter of rule updates
Agent status (online/offline)
Agent's UTC Time
Agent's timezone
Agent's timezone offset
Number of failures trying to send data since last successful send
Byte size of last message uploaded to Signal Sciences platform
Counter of uptime in seconds
Current version
Byte tally of write requests (POST, PUT, etc)
Gauge of CPU usage by agent
Processor architecture
Median host clock skew (in seconds) over the past 5 minutes
Gauge of CPU usage
CPU clock speed
Instance type
Number of CPUs
OS
Host's IP address
Module server version
Module version
Counter of garbage collection time
Gauge of bytes allocated for agent
Counter of garbage collections
Gauge of current number of goroutines
Response Example
{
"data": [
{
"agent.active": true,
"agent.addr": "unix:/var/run/sigsci.sock",
"agent.args": "/opt/sigsci/sbin/sigsci-agent ",
"agent.build_id": "6c105c9719172e5257255f996a8b9475b33b57ff",
"agent.connections_dropped": 0,
"agent.connections_open": 0,
"agent.connections_total": 419038,
"agent.current_requests": 50,
"agent.decision_time_50th": 0.8043622142857145,
"agent.decision_time_95th": 6.895777,
"agent.decision_time_99th": 9.037322,
"agent.enabled": true,
"agent.last_rule_update": "2016-01-25T15:40:59Z",
"agent.last_seen": "2016-01-25T14:42:30Z",
"agent.max_procs": 1,
"agent.name": "testAgent",
"agent.read_bytes": 308250973,
"agent.rpc_postrequest": 8582,
"agent.rpc_prerequest": 409140,
"agent.rpc_updaterequest": 1315,
"agent.rule_updates": 158,
"agent.status": "online",
"agent.timestamp": 1453736459,
"agent.timezone": "UTC",
"agent.timezone_offset": 0,
"agent.upload_metadata_failures": 0,
"agent.upload_size": 2524,
"agent.uptime": 491731,
"agent.version": "1.8.5758",
"agent.write_bytes": 8492498,
"host.agent_cpu": 0.23333318319915222,
"host.architecture": "amd64",
"host.clock_skew": 15,
"host.cpu": 0,
"host.cpu_mhz": 2500,
"host.instance_type": "c3.large",
"host.num_cpu": 1,
"host.os": "Ubuntu 14.04.3 LTS",
"host.remote_addr": "123.123.97.219",
"module.server": "go1.5.3",
"module.version": "1.0",
"runtime.gc_pause_millis": 2505.317246,
"runtime.mem_size": 8837480,
"runtime.num_gc": 6540,
"runtime.num_goroutines": 12
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Agent Details
get /corps/{corpName}/sites/{siteName}/agents/{agentName}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Whether agent was seen in past 5 minutes
RPC Address
Command line arguments
Commit SHA of current build
Counter of connections dropped by agent
Gauge of simultaneous connections
Counter of total connections
Number of requests in last interval
Decision time in ms, 50th percentile
Decision time in ms, 95th percentile
Decision time in ms, 99th percentile
Configuration flag for on/off
Timestamp of last rules update in RFC3339
Timestamp of last heartbeat in RFC3339
GOMAXPROCS setting
Name
Byte tally of read requests (GET)
Counter of total RPC PostRequests
Counter of total RPC PreRequests
Counter of total RPC UpdateRequests
Counter of rule updates
Agent status (online/offline)
Agent's UTC Time
Agent's timezone
Agent's timezone offset
Number of failures trying to send data since last successful send
Byte size of last message uploaded to Signal Sciences platform
Counter of uptime in seconds
Current version
Byte tally of write requests (POST, PUT, etc)
Gauge of CPU usage by agent
Processor architecture
Median host clock skew (in seconds) over the past 5 minutes
Gauge of CPU usage
CPU clock speed
Instance type
Number of CPUs
OS
Host's IP address
Module server version
Module version
Counter of garbage collection time
Gauge of bytes allocated for agent
Counter of garbage collections
Gauge of current number of goroutines
Response Example
{
"agent.active": true,
"agent.addr": "unix:/var/run/sigsci.sock",
"agent.args": "/opt/sigsci/sbin/sigsci-agent ",
"agent.build_id": "6c105c9719172e5257255f996a8b9475b33b57ff",
"agent.connections_dropped": 0,
"agent.connections_open": 0,
"agent.connections_total": 419038,
"agent.current_requests": 50,
"agent.decision_time_50th": 0.8043622142857145,
"agent.decision_time_95th": 6.895777,
"agent.decision_time_99th": 9.037322,
"agent.enabled": true,
"agent.last_rule_update": "2016-01-25T15:40:59Z",
"agent.last_seen": "2016-01-25T14:42:30Z",
"agent.max_procs": 1,
"agent.name": "testAgent",
"agent.read_bytes": 308250973,
"agent.rpc_postrequest": 8582,
"agent.rpc_prerequest": 409140,
"agent.rpc_updaterequest": 1315,
"agent.rule_updates": 158,
"agent.status": "online",
"agent.timestamp": 1453736459,
"agent.timezone": "UTC",
"agent.timezone_offset": 0,
"agent.upload_metadata_failures": 0,
"agent.upload_size": 2524,
"agent.uptime": 491731,
"agent.version": "1.8.5758",
"agent.write_bytes": 8492498,
"host.agent_cpu": 0.23333318319915222,
"host.architecture": "amd64",
"host.clock_skew": 15,
"host.cpu": 0,
"host.cpu_mhz": 2500,
"host.instance_type": "c3.large",
"host.num_cpu": 1,
"host.os": "Ubuntu 14.04.3 LTS",
"host.remote_addr": "123.123.97.219",
"module.server": "go1.5.3",
"module.version": "1.0",
"runtime.gc_pause_millis": 2505.317246,
"runtime.mem_size": 8837480,
"runtime.num_gc": 6540,
"runtime.num_goroutines": 12
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get agent logs by agent name
get /corps/{corpName}/sites/{siteName}/agents/{agentName}/logs
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
the agent's parent Corp
the agent's parent Site
host name
level of severity
description of event
RFC3339 formatted timestamp of event
Response Example
{
"corp": "sigsci",
"site": "dashboard",
"logs": [
{
"hostName": "localhost",
"logLevel": "INFO",
"message": "1 rules updated",
"createdAt": "2016-01-29T20:00:30Z"
}
]
}
List agent keys
get /corps/{corpName}/sites/{siteName}/agentKeys
Fetches a list of all Agent Keys for a site. A site should only have one set of agent keys, and is limited to a maximum of two. The second set is used to ensure agent key rotation can be rolled back if needed, but the old agent keys should be deleted upon successful rotation and deployment of updated agents.
Request
Query Parameters
Pretty print the json output
Filters based on if the agent keys are the Site's primary agent keys
Responses
HTTP 200
Agent configuration accesskeyid value
Agent configuration secretaccesskey value
The primary agent keys for the Site in the cloud-hosted collection and analysis system. The primary agent keys should be used to configure the agent.
Created RFC3339 date time
Updated RFC3339 date time
Response Example
{
"data": [
{
"accessKey": "d217f023-616e-4389-a230-1665c7c44010",
"secretKey": "rNs7ti7dvbt0k2Ob4qCCL-Prob5QIRSNOyyp3cj79vs",
"isPrimary": true,
"created": "2020-01-26T17:10:29.771Z",
"updated": "2020-01-26T17:10:29.772Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Site not found"}
HTTP 500
Error message
Response Example
{"message":"internal error"}
Create Agent Keys
post /corps/{corpName}/sites/{siteName}/agentKeys
Creates new, non-primary agent keys for a site. A site should only have one set of agent keys, and is limited to a maximum of two.
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Agent configuration accesskeyid value
Agent configuration secretaccesskey value
The primary agent keys for the Site in the cloud-hosted collection and analysis system. The primary agent keys should be used to configure the agent.
Created RFC3339 date time
Updated RFC3339 date time
Response Example
{
"accessKey": "d217f023-616e-4389-a230-1665c7c44010",
"secretKey": "rNs7ti7dvbt0k2Ob4qCCL-Prob5QIRSNOyyp3cj79vs",
"isPrimary": true,
"created": "2020-01-26T17:10:29.771Z",
"updated": "2020-01-26T17:10:29.772Z"
}
HTTP 400
Error message
Response Example
{"message":"agent keys max count of 2 reached"}
HTTP 404
Error message
Response Example
{"message":"not found"}
HTTP 500
Error message
Response Example
{"message":"internal error"}
Get Agent Keys by accessKey
get /corps/{corpName}/sites/{siteName}/agentKeys/{accessKey}
Fetches agent keys by the accessKey.
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Agent configuration accesskeyid value
Agent configuration secretaccesskey value
The primary agent keys for the Site in the cloud-hosted collection and analysis system. The primary agent keys should be used to configure the agent.
Created RFC3339 date time
Updated RFC3339 date time
Response Example
{
"accessKey": "d217f023-616e-4389-a230-1665c7c44010",
"secretKey": "rNs7ti7dvbt0k2Ob4qCCL-Prob5QIRSNOyyp3cj79vs",
"isPrimary": true,
"created": "2020-01-26T17:10:29.771Z",
"updated": "2020-01-26T17:10:29.772Z"
}
HTTP 400
Error message
Response Example
{"message":"Site not found"}
HTTP 404
Error message
Response Example
{"message":"not found"}
HTTP 500
Error message
Response Example
{"message":"internal error"}
Delete agent keys
delete /corps/{corpName}/sites/{siteName}/agentKeys/{accessKey}
Deletes the agent keys with the given accessKey. Will fail if the agent keys are the site's primary agent keys.
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful deletion of the agent keys
HTTP 400
Error message
Response Example
{"message":"cannot delete site's primary agent key"}
HTTP 404
Error message
Response Example
{"message":"not found"}
HTTP 500
Error message
Response Example
{"message":"internal error"}
Make agent keys primary
post /corps/{corpName}/sites/{siteName}/agentKeys/{accessKey}/makePrimary
RPC call that updates a site's primary agent keys. Agents will stop receiving configuration updates after a new set of agent keys are made primary, and will begin receiving them again when the site's agents are properly configured and started with the new agent keys.
Request
Responses
HTTP 204
Successfully set agent keys as site's primary agent keys
HTTP 400
Error message
Response Example
{"message":"Site not found"}
HTTP 404
Error message
Response Example
{"message":"not found"}
HTTP 500
Error message
Response Example
{"message":"internal error"}
Get site's primary agent keys
get /corps/{corpName}/sites/{siteName}/keys
Fetches the site's primary agent keys.
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
site name
access key
secret key
Response Example
{
"name": "www.example.com",
"accessKey": "b7e03c6e-09db-4306-a69d-06a88d4b1d1e",
"secretKey": "dzXOIhudazcfIQFpVu5069bMHO7I4vavDKIRV3Xsx8B",
}
List site integrations
get /corps/{corpName}/sites/{siteName}/integrations
Request
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "556a8abb3dfaa4ff28000002",
"name": "Slack message",
"type": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": [
"webhookEvents"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Create site integration
post /corps/{corpName}/sites/{siteName}/integrations
Request
Body (application/json)
Integration URL
Corp integration types (mailingList, slack, microsoftTeams). Site integration types (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Request Example
{
"url":"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"type":"generic",
"events": [
"webhookEvents"
],
"note": ""
}
Responses
HTTP 200
Integration URL
Corp integration types (mailingList, slack, microsoftTeams). Site integration types (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Response Example
{
"data": [
{
"id": "5e2f5d8cf13d66152d396959",
"name": "Generic webhook",
"type": "generic",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"fields": null,
"events": [
"webhookEvents"
],
"active": true,
"note": "",
"createdBy": "user@example.com",
"created": "2020-01-27T22:00:44Z",
"lastStatusCode": 0
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get site integration by id
get /corps/{corpName}/sites/{siteName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique id of the integration
Integration name
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Integration note
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "556a8abb3dfaa4ff28000003",
"type": "generic",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": [
"webhookEvents"
],
"active": true,
"note": "Sample",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Update site integration by id
patch /corps/{corpName}/sites/{siteName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Body (application/json)
Integration URL
Array of event types. Visit our integrations documentation to find out which events the service you are connecting allows.
Request Example
{
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": ["flag", "loggingModeChanged"]
}
Responses
HTTP 204
Successful update
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Delete site integration
delete /corps/{corpName}/sites/{siteName}/integrations/{id}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"No integration with given id exists"}
Test site integration by id
post /corps/{corpName}/sites/{siteName}/integrations/{id}/test
Request
URI Parameters
Responses
HTTP 200
Test successful
HTTP 500
Test failed
List header links
get /corps/{corpName}/sites/{siteName}/headerLinks
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the header link
The type of header, either 'request' or 'response'
External link
Name of header link for display purposes
Name of header
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "558cf75c3dfaa4b9c2000001",
"type": "response",
"name": "X-Request-Id",
"linkName": "Kibana",
"link": "https://kibana.example.com/?q={{value}}",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Add to header links
post /corps/{corpName}/sites/{siteName}/headerLinks
Request
Query Parameters
Pretty print the json output
Body (application/json)
The type of header, either 'request' or 'response'
External link
Name of header link for display purposes
Name of header
Request Example
{
"type": "response",
"name": "X-SplunkRequest-Id",
"linkName": "Splunk",
"link": "https://splunk.example.com/?q={{value}}"
}
Responses
HTTP 200
Unique ID of the header link
The type of header, either 'request' or 'response'
External link
Name of header link for display purposes
Name of header
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "558cf75c3dfaa4b9c2000001",
"type": "response",
"name": "X-Request-Id",
"linkName": "Kibana",
"link": "https://kibana.example.com/?q={{value}}",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
},
{
"id": "558cf75c3dfaa4b9c2000002",
"type": "request",
"name": "X-SplunkRequest-Id",
"linkName": "Splunk",
"link": "https://splunk.example.com/?q={{value}}",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Get header link by ID
get /corps/{corpName}/sites/{siteName}/headerLinks/{headerLinkID}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the header link
The type of header, either 'request' or 'response'
External link
Name of header link for display purposes
Name of header
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"id": "558cf75c3dfaa4b9c2000001",
"type": "response",
"name": "X-Request-Id",
"linkName": "Kibana",
"link": "https://kibana.example.com/?q={{value}}",
"createdBy": "user@example.com",
"created": "2015-02-14T21:17:16Z"
},
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Delete from header links
delete /corps/{corpName}/sites/{siteName}/headerLinks/{headerLinkID}
Request
URI Parameters
Query Parameters
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
HTTP 404
Error message
Response Example
{"message":"No header link with given id exists"}
Get site monitors
get /corps/{corpName}/sites/{siteName}/monitors
Request
Query Parameters
Pretty print the json output
Responses
HTTP 200
Unique ID of the site monitor
URL for site monitor
Whether this site monitor is enabled or not
Email address of the user that created the item
Created RFC3339 date time
Response Example
{
"data": [
{
"id": "b7e03c6e-09db-4306-a69d-06a88d4b1d1e",
"url": "https://dashboard.signalsciences.net/corp/site/monitor/b7e03c6e-09db-4306-a69d-06a88d4b1d1e",
"share": true,
"createdBy": "user@example.com",
"created": "2014-12-09T10:43:54-08:00"
}
]
}
HTTP 400
Error message
Response Example
{"message":"Site not found"}
Generate site monitor URL
post /corps/{corpName}/sites/{siteName}/monitors
Request
Query Parameters
Pretty print the json output
The ID of the dashboard
Responses
HTTP 200
Role of the user (owner, admin, user, observer)
API user
Auth status of the user
Auth type of the corp
Email of the user
Name of the user
Status of the user
Response Example
{
"id": "bd0dee5e-0313-40c2-9396-21881b07a7db",
"url": "https://dashboard.signalsciences.net/corp/site/monitor/bd0dee5e-0313-40c2-9396-21881b07a7db",
"share": true,
"createdBy": "user@example.com",
"created": "2014-12-09T10:43:54-08:00"
}
HTTP 400
Error message
Response Example
{"message":"Site monitor not found"}
Update site monitor
put /corps/{corpName}/sites/{siteName}/monitors/{id}
Request
URI Parameters
Body (application/json)
The ID of the monitor
Shareable link enabled
Request Example
{
"id": "be9072f8-50d3-48f0-acaf-c270502aa834",
"share": true
}
Responses
HTTP 204
Site monitor updated
HTTP 400
Error message
Response Example
{"message":"Site monitor not found"}
HTTP 404
Error message
Response Example
{"message":"No monitor URL for site exists"}
Delete site monitor
delete /corps/{corpName}/sites/{siteName}/monitors/{id}
Request
URI Parameters
Responses
HTTP 204
Delete successful
List top attacks
get /corps/{corpName}/sites/{siteName}/top/attacks
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
Pretty print the json output
Field to group by
The number of results to be returned
Responses
HTTP 200
Total number of matching requests
Value
Label (more information about value)
Count of attacks seen from this country, IP, etc.
Response Example
{
"totalRequests": 1402,
"data": [
{
{
"value": "US",
"label": "United States",
"count": 306
},
{
"value": "JP",
"label": "Japan",
"count": 159
},
{
"value": "CZ",
"label": "Czech Republic",
"count": 150
}
]
}
]
}
HTTP 400
Error message
Response Example
{"message":"Invalid site"}
Send simulation
post /corps/{corpName}/sites/{siteName}/simulator
Request
Query Parameters
Pretty print the json output
Body (application/json)
Sample request to be sent to the simulator. Each HTTP header should be separated by a literal newline (\n) character
Sample response to be sent to the simulator. Each HTTP header should be separated by a literal newline (\n) character
Request Example
{
"sample_request": "POST /foobar?key1=value1 HTTP/1.1\nHost: sample.foo\nAccept-Encoding: gzip, deflate\nAccept-Language: en-us\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\nConnection: keep-alive\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 10000\nCookie:\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.6 Safari/605.1.15\nCache-Control: max-age=0\nX-Forwarded-For: 127.0.0.1\nX-Forwarded-Proto: https\n\npostkey1=value1&post2=value2",
"sample_response": "HTTP/1.1 200 OK\nServer: nginx\nDate: Fri, 21 Aug 2015 21:30:50 GMT\nContent-Type: text/html; charset=utf-8\nConnection: keep-alive\nContent-Length: 0\nx-xss-protection: 1; mode=block\nx-content-type-options: nosniff\npragma: no-cache\nx-frame-options: SAMEORIGIN\nStrict-Transport-Security: max-age=15552000; includeSubDomains\nX-Request-ID: 123456789"
}
Responses
HTTP 200
Response code returned from the WAF
Response code that would be returned to client
Size of response returned to client
Signal type
Location that caused the signal to be added
Name of the signal
Value that caused the signal to be added
Detection mechanism that added the signal
Whether the value was redacted or not
Response Example
{
"data": {
"waf_response": 406,
"response_code": 406,
"response_size": 20,
"signals": [
{
"type": "BLOCKED",
"location": "",
"name": "",
"value": "406",
"detector": "6529987e8332b901d40cfd14",
"redaction": 0
}
]
}
}
HTTP 400
Error message
Response Example
{"message":"Test error: unexpected EOF"}
Timeseries
Get timeseries request info
get /corps/{corpName}/sites/{siteName}/timeseries/requests
Request
Query Parameters
The POSIX Unix time to start
The POSIX Unix time to end
Pretty print the json output
Filter based on N request tags
Rollup interval in seconds e.g. 60 = 1 minute interval
Desired output format
Responses
HTTP 200
Type
The POSIX Unix time to start
The POSIX Unix time to end
Increment (in seconds) of each point
Sum of all the points
Count of all the points
Response Example
[
{
"type": "SQLI",
"from": 1429835400,
"until": 1429836300,
"inc": 300,
"data": [3,2,0,6],
"summaryCount": 11,
"totalPoints": 4,
},
{
"type": "XSS",
"from": 1429835400,
"until": 1429836300,
"inc": 300,
"data": [1,7,1,0],
"summaryCount": 9,
"totalPoints": 4,
}
]