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
Name
Type
Description
Responses
HTTP 200
Name
Type
Description
token
string
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
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
corp array
name
string
Identifying name of the corp
displayName
stringmin len 3 max len 100
Display name of the corp
smallIconURI
stringmax len 200
Small icon URI
created
string
Created RFC3339 date time
siteLimit
integer
Site limit
authType
string
Authentication method
sessionMaxAgeDashboard
integerdefault 2592000 min len 60 max len 31536000
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
name
string
Identifying name of the corp
displayName
stringmin len 3 max len 100
Display name of the corp
smallIconURI
stringmax len 200
Small icon URI
created
string
Created RFC3339 date time
siteLimit
integer
Site limit
authType
string
Authentication method
sessionMaxAgeDashboard
integerdefault 2592000 min len 60 max len 31536000
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
displayName
stringmin len 3 max len 100
Display name of the corp
smallIconURI
stringmax len 200
Small icon URI
sessionMaxAgeDashboard
integerdefault 2592000 min len 60 max len 31536000
Dashboard session timeout (seconds)
Request Example
{
"displayName": "Test Corporation1"
}
Responses
HTTP 200
Successful update
Name
Type
Description
name
string
Identifying name of the corp
displayName
stringmin len 3 max len 100
Display name of the corp
smallIconURI
stringmax len 200
Small icon URI
created
string
Created RFC3339 date time
siteLimit
integer
Site limit
authType
string
Authentication method
sessionMaxAgeDashboard
integerdefault 2592000 min len 60 max len 31536000
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
Name
Type
Description
message
string
Error message
Response Example
{"message":"Invalid displayName - must be between 3 and 100 characters."}
Get corp overview report
get /corps/{corpName}/reports/attacks
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
from
string default -7d
Number of days ago to begin the data window. Takes the format "-Nd" where N is the number of days (maximum 30).
until
string default now
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
Name
Type
Description
data
overviewSite array
name
string
Identifying name of the site
displayName
string
Display name of the site
totalCount
integer
Total number of requests
attackCount
integer
Number of malicious requests
blockedCount
integer
Number of malicious requests blocked
flaggedCount
integer
Number of malicious requests that would have been blocked in blocking mode
flaggedIPCount
integer
Number of IPs that triggered blocking events due to malicious signals
topAttackTypes
topAttackType array
tagName
string
Attack tag name
tagCount
integer
Number of instances of this attack tag
totalCount
integer
Total attack tags seen (note - requests can have multiple tags)
topAttackSources
topAttackSource array
countryCode
string
Two-letter ISO country code (note - empty for "Unknown", "private" for "Private Network"
countryName
string
Descriptive country name
requestCount
integer
Number of requests originating from this country
totalCount
integer
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
Name
Type
Description
message
string
Error message
Response Example
{"message":"Invalid parameter - from"}
List corp activity events
get /corps/{corpName}/activity
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
from
integer
The POSIX Unix time to start
until
integer
The POSIX Unix time to end
sort
one of (asc,desc) default desc
The sort order
since_id
string
The id of the last object in the set
max_id
string
The id of the last object in the set
limit
integer default 100 max 1000
The number of entries to be returned
page
integer
The page of the results - a maximum of 1000 requests in total will be returned
pretty
boolean
Pretty print the json output
events
one of (corpEvents,userEvents)
Filter on events
eventType
string
Filter on event type
Responses
HTTP 200
Name
Type
Description
totalCount
integer
Total number of matching documents
data
activityevent array
id
string
Unique ID of the activity event
eventType
string
Event type
msgData
object
Data used to format the message
attachments
tuple array
attachments
objectrequired
Title
string
Fields
tuple array
MarkdownFields
boolean
message
string
Message of the event
created
string
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 (test@test.net) enabled 2FA",
"attachments": [],
"created": "2018-04-12T01:00:33Z"
}
]
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{"message":"Invalid parameter - from"}
List users in corp
get /corps/{corpName}/users
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
expand
string
Expand hidden properties for nested object
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
corpUser array
name
string
Full name of the user
email
string
Email of the user
memberships
object
data
objectrequired
data
object array
role
string
uri
string
uri
string
Reference to site memberships of the user
role
string
Role of the user (owner, admin, user, observer)
status
string
Status of the user
mfaEnabled
boolean
Whether this user has two-factor auth enabled or not
authStatus
string
Auth-specific status of the user
corpAuthType
string
Corp auth type of the user
created
string
Created RFC3339 date time
apiUser
boolean
Is the user an API user
Response Example
{
"data": [
{
"name": "Test User",
"email": "test@test.net",
"announcements": {
"uri": "/api/v0/user/announcements"
},
"defaultDashboards": {
"uri": "/api/v0/user/defaultDashboards"
},
"memberships": {
"uri": "/api/v0/corps/testcorp/users/test@test.net/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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
userEmail
string required matching [0-9a-z_.-@]+
Query Parameters
Name
Type
Description
expand
string
Expand hidden properties for nested object
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
name
string
Full name of the user
email
string
Email of the user
memberships
object
data
objectrequired
data
object array
role
string
uri
string
uri
string
Reference to site memberships of the user
role
string
Role of the user (owner, admin, user, observer)
status
string
Status of the user
mfaEnabled
boolean
Whether this user has two-factor auth enabled or not
authStatus
string
Auth-specific status of the user
corpAuthType
string
Corp auth type of the user
created
string
Created RFC3339 date time
apiUser
boolean
Is the user an API user
Response Example
{
"name": "Test User",
"email": "test@test.net",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/test@test.net/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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
userEmail
string required matching [0-9a-z_.-@]+
Query Parameters
Name
Type
Description
expand
string
Expand hidden properties for nested object
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
role
string
Role of the user (owner, admin, user, observer)
memberships
object
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "www.mysite.com"
}
}, {
"site": {
"name": "www.myothersite.com"
}
}]
}
}
Responses
HTTP 200
Name
Type
Description
name
string
Full name of the user
email
string
Email of the user
memberships
object
data
objectrequired
data
object array
role
string
uri
string
uri
string
Reference to site memberships of the user
role
string
Role of the user (owner, admin, user, observer)
status
string
Status of the user
mfaEnabled
boolean
Whether this user has two-factor auth enabled or not
authStatus
string
Auth-specific status of the user
corpAuthType
string
Corp auth type of the user
created
string
Created RFC3339 date time
apiUser
boolean
Is the user an API user
Response Example
{
"name": "",
"email": "test@test.net",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/test@test.net/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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
userEmail
string required matching [0-9a-z_.-@]+
Responses
HTTP 204
Delete successful
Invite user to corp
post /corps/{corpName}/users/{userEmail}/invite
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
userEmail
string required matching [0-9a-z_.-@]+
Query Parameters
Name
Type
Description
expand
string
Expand hidden properties for nested object
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
role
string
Role of the user (owner, admin, user, observer)
memberships
object
Request Example
{
"role": "user",
"memberships": {
"data": [{
"site": {
"name": "www.mysite.com"
}
}, {
"site": {
"name": "www.myothersite.com"
}
}]
}
}
Responses
HTTP 200
Name
Type
Description
name
string
Full name of the user
email
string
Email of the user
memberships
object
data
objectrequired
data
object array
role
string
uri
string
uri
string
Reference to site memberships of the user
role
string
Role of the user (owner, admin, user, observer)
status
string
Status of the user
mfaEnabled
boolean
Whether this user has two-factor auth enabled or not
authStatus
string
Auth-specific status of the user
corpAuthType
string
Corp auth type of the user
created
string
Created RFC3339 date time
apiUser
boolean
Is the user an API user
Response Example
{
"name": "",
"email": "test@test.net",
"memberships": {
"uri": "/api/v0/corps/testcorp/users/test@test.net/memberships"
}
"role": "user",
"status": "active"
"mfaEnabled": false,
"corpAuthType": "builtin",
"authStatus": "none",
"created": "2014-12-09T10:43:54-08:00"
"apiUser": false
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{"message":"Invalid site"}
List rules in corp
get /corps/{corpName}/rules
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
totalCount
number
Total count of Corp Rules
data
corpRule array
id
string
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
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": "1.2.3.4/8"
}
],
"actions": [
{
"type": "block"
}
],
"reason": "foo",
"expiration": "",
"created": "2015-02-14T21:17:16Z",
"updated": "2015-02-14T21:17:16Z"
}
]
}
}
Create corp rule
post /corps/{corpName}/rules
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"siteNames": [
"www.mysite.com",
"www.myothersite.com"
],
"type": "signal",
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "1.2.3.4"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "5.6.7.8"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"enabled": true,
"reason": "test",
"signal": "SQLI",
"expiration": "",
"corpScope": "specificSites"
}
Responses
HTTP 200
Name
Type
Description
id
string
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"www.mysite.com",
"www.myothersite.com"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "1.2.3.4"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "5.6.7.8"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Get corp rule by id
get /corps/{corpName}/rules/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
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": "1.2.3.4/8"
}
],
"actions": [
{
"type": "block"
}
],
"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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Body (application/json)
Name
Type
Description
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
Request Example
{
"id": "5e1914acf13d663e6d0178ea",
"siteNames": [
"www.mysite.com",
"www.myothersite.com"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "6.7.8.9"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "5.6.7.8"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "Known malicious IPs",
"expiration": ""
}
Responses
HTTP 200
Name
Type
Description
id
string
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion)
corpScope
string
Whether the rule is applied to all sites or to specific sites. (global, specificSites)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
signal
string
The signal id of the signal being excluded
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
"id": "5e18ee76f13d66138c3e587c",
"siteNames": [
"www.mysite.com",
"www.myothersite.com"
],
"type": "signal",
"corpScope": "specificSites",
"enabled": true,
"groupOperator": "all",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "1.2.3.4"
},
{
"type": "group",
"groupOperator": "any",
"conditions": [
{
"type": "single",
"field": "ip",
"operator": "equals",
"value": "5.6.7.8"
}
]
}
],
"actions": [
{
"type": "excludeSignal"
}
],
"signal": "SQLI",
"reason": "test",
"expiration": ""
}
Delete rule from corp
delete /corps/{corpName}/rules/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 204
Delete successful
Get all lists
get /corps/{corpName}/lists
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Responses
HTTP 200
Name
Type
Description
data
list array
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
"data": [
{
"id": "corp.known-attackers",
"name": "Known Attackers",
"type": "ip",
"description": "Malicious IPs we're tracking",
"entries": [
"4.5.6.7",
"2.3.4.5",
"1.2.3.4"
],
"createdBy": "test@test.net",
"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": "test@test.net",
"created": "2018-08-03T20:50:54Z",
"updated": "2018-08-03T20:50:59Z"
}
]
}
Create list
post /corps/{corpName}/lists
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Body (application/json)
Name
Type
Description
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
Request Example
{
"name": "My New List",
"type": "ip",
"description": "Some IPs we're putting in a list",
"entries": [
"4.5.6.7",
"2.3.4.5",
"1.2.3.4"
]
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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": [
"4.5.6.7",
"2.3.4.5",
"1.2.3.4"
],
"createdBy": "test@test.net",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 400
Name
Type
Description
message
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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": [
"4.5.6.7",
"2.3.4.5",
"1.2.3.4"
],
"createdBy": "test@test.net",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T17:38:27Z"
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"id not found"}
Update list by id
patch /corps/{corpName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Body (application/json)
Name
Type
Description
description
stringmax len 140
Optional list description
entries
object
Request Example
{
"entries": {
"additions": [
"9.9.8.8"
],
"deletions": [
"4.5.6.7",
"1.2.3.4"
]
}
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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": [
"2.3.4.5",
"9.9.8.8"
],
"createdBy": "test@test.net",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"id not found"}
Replace list by id
put /corps/{corpName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Body (application/json)
Name
Type
Description
description
stringmax len 140
Optional list description
Request Example
{
"description": "Some IPs we're still putting in a list",
"entries": [
"4.5.6.7",
"1.2.3.4",
"9.8.7.6"
]
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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": [
"4.5.6.7",
"1.2.3.4",
"9.8.7.6"
],
"createdBy": "test@test.net",
"created": "2018-08-16T17:38:27Z",
"updated": "2018-08-16T21:43:08Z"
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"ID not found"}
Delete list
delete /corps/{corpName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 204
Successful removal from the list
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"ID not found"}
List corp integrations
get /corps/{corpName}/integrations
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Responses
HTTP 200
Name
Type
Description
data
integration array
id
string
Unique id of the integration
name
string
Integration name
type
string
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
url
string
Integration URL
fields
object,null
events
string array
Array of event types. Visit https://docs.signalsciences.net/integrations to find out which events the service you are connecting allows.
active
boolean
note
string
Integration note
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
lastStatusCode
number
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": "test@test.net",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
]
}
Create corp integration
post /corps/{corpName}/integrations
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Body (application/json)
Name
Type
Description
url
string
Integration URL
type
string
Corp integration types (mailingList, slack, microsoftTeams). Site integration types (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
events
string array
Array of event types. Visit https://docs.signalsciences.net/integrations to find out which events the service you are connecting allows.
note
string
Integration note
Request Example
{
"url":"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"type":"slack",
"events": [
"corpUpdated"
],
"note": ""
}
Responses
HTTP 200
Name
Type
Description
ID
string
Unique ID of the integration
Type
string
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
URL
string
Integration URL
ExtraFields
string,null
Events
string array
Array of event types. Visit https://docs.signalsciences.net/integrations to find out which events the service you are connecting allows.
Active
boolean
CreatedBy
string
Email address of the user that created the integration
CreatedByID
string
ID of the user that created the integration
Note
string
Integration note
Created
string
Created RFC3339 date time
LastStatusCode
number
Response Example
{
"ID": "5e2f5d17f13d66152d396956",
"Type": "slack",
"URL": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"ExtraFields": null,
"Events": [
"corpUpdated"
],
"Active": true,
"CreatedBy": "test@test.net",
"CreatedByID": "5e222f75f13d666c9eaec7d9",
"Note": "",
"Created": "2020-01-27T21:58:47.608359Z",
"LastStatusCode": 0
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{"message":"Validation failed"}
Get corp integration by id
get /corps/{corpName}/integrations/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
id
string
Unique id of the integration
name
string
Integration name
type
string
Corp integration types: (mailingList, slack, microsoftTeams). Site integration types: (mailingList, slack, datadog, generic, pagerduty, microsoftTeams, jira, opsgenie, victorops, pivotaltracker)
url
string
Integration URL
fields
object,null
events
string array
Array of event types. Visit https://docs.signalsciences.net/integrations to find out which events the service you are connecting allows.
active
boolean
note
string
Integration note
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
lastStatusCode
number
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": "test@test.net",
"created": "2015-02-14T21:17:16Z",
"lastStatusCode": 0
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"No integration with given id exists"}
Update corp integration by id
patch /corps/{corpName}/integrations/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
url
string
Integration URL
events
string array
Array of event types. Visit https://docs.signalsciences.net/integrations 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
Name
Type
Description
message
string
Error message
Response Example
{"message":"Validation failed"}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{"message":"No integration with given id exists"}
Delete corp integration
delete /corps/{corpName}/integrations/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 404
Name
Type
Description
message
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 200
Test successful
HTTP 500
Test failed
List Cloudwaf instances
get /corps/{corpName}/cloudwafInstances
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Responses
HTTP 200
Name
Type
Description
data
cloudwafInstanceResponse array
id
string
CloudWAF instance unique identifier.
name
string
Friendly name to identify a CloudWAF instance.
description
string
Friendly description to identify a CloudWAF instance.
region
string
Region the CloudWAF Instance is being deployed to.
tlsMinVersion
string
TLS minimum version.
workspaceConfigs
object array
siteName
string
Site name.
instanceLocation
string
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
routes
object array
id
string
Route unique identifier.
certificateIds
string array
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
string
Origin server URI.
passHostHeader
boolean
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).
tlsHostOverride
boolean
This settings tells the agent to ignore the hostname that is being passed. Host override for TLS going to the upstream. This makes SNI connections work (default: true).
connectionPooling
boolean
If disabled, opened connections will not be reused (default: true).
tlsInsecureSkipVerify
boolean
This setting is used to insecurely skip reverse proxy upstream TLS verification (default: true).
trustProxyHeaders
boolean
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: true)
deployment
object
status
string
Current status of the deployment
message
string
CloudWAF instance message
egressIPs
object array
ip
string
Egress IP address CloudWAF will be directing traffic to origin from.
status
string
EgressIP Status.
updatedAt
string
When EgressIP was last updated on.
dnsEntry
string
CloudWAF instance's DNS Entry.
useUploadedCertificates
boolean
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
createdBy
string
CloudWAF instance created by.
created
string
Timestamp for when deployment was created.
Create CloudWAF instance
post /corps/{corpName}/cloudwafInstances
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Body (application/json)
Name
Type
Description
name
stringrequired
Friendly name to identify a CloudWAF instance.
description
stringrequired
Friendly description to identify a CloudWAF instance.
region
stringrequired
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").
tlsMinVersion
stringrequired
TLS minimum version. Versions Available: "1.0", "1.2".
workspaceConfig
object arrayrequired
siteName
stringrequired
Site name.
instanceLocation
stringrequired
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
listenerProtocols
string arrayrequired
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
routes
object arrayrequired
certificateIds
string arrayrequired
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
stringrequired
Origin server URI.
passHostHeader
boolean
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).
Request Example
{
"name": "test",
"description": "test",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"workspaceConfigs": [
{
"siteName": "www.website.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id"],
"domains": ["www.website.com"],
"origin": "https://origin.website.com",
"passHostHeader": false
}
]
}
]
}
Responses
HTTP 200
Name
Type
Description
id
string
CloudWAF instance unique identifier.
name
string
Friendly name to identify a CloudWAF instance.
description
string
Friendly description to identify a CloudWAF instance.
region
string
Region the CloudWAF Instance is being deployed to.
tlsMinVersion
string
TLS minimum version.
workspaceConfigs
object array
siteName
string
Site name.
instanceLocation
string
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
routes
object array
id
string
Route unique identifier.
certificateIds
string array
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
string
Origin server URI.
passHostHeader
boolean
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).
tlsHostOverride
boolean
This settings tells the agent to ignore the hostname that is being passed. Host override for TLS going to the upstream. This makes SNI connections work (default: true).
connectionPooling
boolean
If disabled, opened connections will not be reused (default: true).
tlsInsecureSkipVerify
boolean
This setting is used to insecurely skip reverse proxy upstream TLS verification (default: true).
trustProxyHeaders
boolean
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: true)
deployment
object
status
string
Current status of the deployment
message
string
CloudWAF instance message
egressIPs
object array
ip
string
Egress IP address CloudWAF will be directing traffic to origin from.
status
string
EgressIP Status.
updatedAt
string
When EgressIP was last updated on.
dnsEntry
string
CloudWAF instance's DNS Entry.
useUploadedCertificates
boolean
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
createdBy
string
CloudWAF instance created by.
created
string
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.website.com"}
Get CloudWAF instance by id
get /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
deployment_id
string required
Responses
HTTP 200
Name
Type
Description
id
string
CloudWAF instance unique identifier.
name
string
Friendly name to identify a CloudWAF instance.
description
string
Friendly description to identify a CloudWAF instance.
region
string
Region the CloudWAF Instance is being deployed to.
tlsMinVersion
string
TLS minimum version.
workspaceConfigs
object array
siteName
string
Site name.
instanceLocation
string
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
routes
object array
id
string
Route unique identifier.
certificateIds
string array
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
string
Origin server URI.
passHostHeader
boolean
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).
tlsHostOverride
boolean
This settings tells the agent to ignore the hostname that is being passed. Host override for TLS going to the upstream. This makes SNI connections work (default: true).
connectionPooling
boolean
If disabled, opened connections will not be reused (default: true).
tlsInsecureSkipVerify
boolean
This setting is used to insecurely skip reverse proxy upstream TLS verification (default: true).
trustProxyHeaders
boolean
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: true)
deployment
object
status
string
Current status of the deployment
message
string
CloudWAF instance message
egressIPs
object array
ip
string
Egress IP address CloudWAF will be directing traffic to origin from.
status
string
EgressIP Status.
updatedAt
string
When EgressIP was last updated on.
dnsEntry
string
CloudWAF instance's DNS Entry.
useUploadedCertificates
boolean
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
createdBy
string
CloudWAF instance created by.
created
string
Timestamp for when deployment was created.
Response Example
{
"id": "id1",
"name": "website",
"description": "a website",
"region": "us-east-1",
"tlsMinVersion": "1.2",
"workspaceConfigs": [
{
"siteName": "www.website.com",
"instanceLocation": "direct",
"clientIPHeader": "",
"listenerProtocols": ["https"],
"routes": [
{
"certificateIds": ["id2"],
"domains": ["www.website.com"],
"origin": "https://www.origin.website.com",
"passHostHeader": false,
"id": "id3",
"tlsHostOverride": true,
"connectionPooling": true,
"tlsInsecureSkipVerify": true,
"trustProxyHeaders": true
}
]
}
],
"deployment": {
"status": "done",
"message": "",
"egressIPs": [
{
"ip": "10.10.100.100",
"status": "reachable",
"updatedAt": "2021-04-08T17:10:58Z"
}
],
"dnsEntry": "website12345.signalsciencescloud.net"
},
"useUploadedCertificates": true,
"createdBy": "user1@someone",
"created": "2021-04-08T15:50:46Z"
}
Update CloudWAF instance
put /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
deployment_id
string required
Body (application/json)
Name
Type
Description
name
stringrequired
Friendly name to identify a CloudWAF instance.
description
stringrequired
Friendly description to identify a CloudWAF instance.
region
stringrequired
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").
tlsMinVersion
stringrequired
TLS minimum version. Versions Available: "1.0", "1.2".
workspaceConfig
object arrayrequired
siteName
stringrequired
Site name.
instanceLocation
stringrequired
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
listenerProtocols
string arrayrequired
Specify the protocol or protocols required. ex. ["http", "https"], ["https"].
routes
object arrayrequired
id
string
Route unique identifier.
certificateIds
string arrayrequired
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
stringrequired
Origin server URI.
passHostHeader
boolean
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).
Responses
HTTP 200
Name
Type
Description
id
string
CloudWAF instance unique identifier.
name
string
Friendly name to identify a CloudWAF instance.
description
string
Friendly description to identify a CloudWAF instance.
region
string
Region the CloudWAF Instance is being deployed to.
tlsMinVersion
string
TLS minimum version.
workspaceConfigs
object array
siteName
string
Site name.
instanceLocation
string
Set instance location to "direct" or "advanced".
clientIPHeader
string
Specify the request header containing the client IP address, available when InstanceLocation is set to "advanced". Default: "X-Forwarded-For".
routes
object array
id
string
Route unique identifier.
certificateIds
string array
List of certificate IDs in string associated with request URI or domains. IDs will be available in certificate GET request.
origin
string
Origin server URI.
passHostHeader
boolean
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).
tlsHostOverride
boolean
This settings tells the agent to ignore the hostname that is being passed. Host override for TLS going to the upstream. This makes SNI connections work (default: true).
connectionPooling
boolean
If disabled, opened connections will not be reused (default: true).
tlsInsecureSkipVerify
boolean
This setting is used to insecurely skip reverse proxy upstream TLS verification (default: true).
trustProxyHeaders
boolean
If true, will trust proxy headers coming into the agent. If false, will ignore and drop those headers (default: true)
deployment
object
status
string
Current status of the deployment
message
string
CloudWAF instance message
egressIPs
object array
ip
string
Egress IP address CloudWAF will be directing traffic to origin from.
status
string
EgressIP Status.
updatedAt
string
When EgressIP was last updated on.
dnsEntry
string
CloudWAF instance's DNS Entry.
useUploadedCertificates
boolean
Represents if the user uploaded certificates should be used to create or update the cloudwaf instance.
createdBy
string
CloudWAF instance created by.
created
string
Timestamp for when deployment was created.
HTTP 400
Response Example
{"message": "An absolute URI including a scheme is required: unexpected origin, got = www.website.com"}
Delete CloudWAF instance
delete /corps/{corpName}/cloudwafInstances/{deployment_id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
deployment_id
string required
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
deployment_id
string required
Responses
HTTP 204
restart successful
List CloudWAF certificates
get /corps/{corpName}/cloudwafCerts
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Responses
HTTP 200
Name
Type
Description
data
cloudwafCertResponse array
id
string
CloudWAF certificate unique identifier
name
string
Friendly name to identify a CloudWAF certificate
certificateBody
string
Body of the certificate in PEM format
certificateChain
string
Certificate chain in PEM format
fingerprint
string
SHA1 fingerprint of the certififcate
expiresAt
string
TimeStamp for when certificate expires in RFC3339 date time format
status
string
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
createdBy
string
Email address of the user that created the certfificate
created
string
Created RFC3339 date time
updatedBy
string
Email address of the user that updated the certificate
updatedAt
string
Updated RFC3339 date time
Upload CloudWAF certificate
post /corps/{corpName}/cloudwafCerts
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Body (application/json)
Name
Type
Description
name
string
Friendly name to identify a CloudWAF certificate
privateKey
string
Private key of the certificate in PEM format - must be unencrypted
certificateBody
string
Body of the certificate in PEM format
certificateChain
string
Certificate chain in PEM format
Request Example
{
"name": "someCertificate",
"domains": [
"somewebsite.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
Name
Type
Description
id
string
CloudWAF certificate unique identifier
Response Example
{"id": "someCertificate-id" }
HTTP 400
Response Example
{"message":"someotherwebsite.com is not associated with the specified TLS certificate.: unexpected domain, got = someotherwebsite.com"}
Get CloudWAF certificate by id
get /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
CloudWAF certificate unique identifier
name
string
Friendly name to identify a CloudWAF certificate
certificateBody
string
Body of the certificate in PEM format
certificateChain
string
Certificate chain in PEM format
fingerprint
string
SHA1 fingerprint of the certififcate
expiresAt
string
TimeStamp for when certificate expires in RFC3339 date time format
status
string
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
createdBy
string
Email address of the user that created the certfificate
created
string
Created RFC3339 date time
updatedBy
string
Email address of the user that updated the certificate
updatedAt
string
Updated RFC3339 date time
Response Example
{
"id":"some-id",
"name":"website",
"domains":["website.com"],
"certificateBody":"-----BEGIN CERTIFICATE-----\n certificate body \n-----END CERTIFICATE-----",
"certificateChain":"",
"fingerprint": "",
"expiresAt":"2021-05-02T20:48:02Z",
"status":"active",
"createdBy":"user@somedomain.com",
"created":"2021-02-01T22:05:23Z",
"updatedBy":"user@somedomain.com",
"updatedAt":"2021-02-01T22:06:17Z"
}
Update CloudWAF certificate by id
put /corps/{corpName}/cloudwafCerts/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
Body (application/json)
Name
Type
Description
name
stringmin len 1
Friendly name to identify a CloudWAF certificate
Request Example
{
"name": "some name"
}
Responses
HTTP 200
Name
Type
Description
id
string
CloudWAF certificate unique identifier
name
string
Friendly name to identify a CloudWAF certificate
certificateBody
string
Body of the certificate in PEM format
certificateChain
string
Certificate chain in PEM format
fingerprint
string
SHA1 fingerprint of the certififcate
expiresAt
string
TimeStamp for when certificate expires in RFC3339 date time format
status
string
Current status of the certificate - could be one of "unknown", "active", "pendingverification", "expired", "error"
createdBy
string
Email address of the user that created the certfificate
created
string
Created RFC3339 date time
updatedBy
string
Email address of the user that updated the certificate
updatedAt
string
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@somedomain.com",
"created": "2021-01-28T20:34:06.952625Z",
"updatedBy": "user@somedomain.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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
id
string required
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
name
string
Filter on site name or display name
page
integer default 1
The page of the results
limit
integer default 10
The number of entries to be returned
agentLevel
one of (block,log,off)
Filter on agent mode
Responses
HTTP 200
Name
Type
Description
data
site array
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
created
string
Created RFC3339 date time
Response Example
{
“data”: [
{
“name”: “www.mysite.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.mysite.com/whitelist”
},
“blacklist”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/blacklist”
},
“events”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/events”
},
“requests”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/requests”
},
“redactions”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/redactions”
},
“suspiciousIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/suspiciousIPs”
},
“monitors”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/monitors”
},
“integrations”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/integrations”
},
“headerLinks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/headerLinks”
},
“agents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/agents”
},
“alerts”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/alerts”
},
“analyticsEvents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/analytics/events”
},
“topAttacks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/top/attacks”
},
“members”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/members”
}
}
]
}
Create site in corp
post /corps/{corpName}/sites
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
Request Example
{
'name": “www.mysite.com”,
“displayName”: “My Website1”,
“agentLevel”: “block”,
“blockDurationSeconds”: 259200
}
Responses
HTTP 200
Name
Type
Description
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
created
string
Created RFC3339 date time
Response Example
{
“name”: “www.mysite.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.mysite.com/whitelist”
},
“blacklist”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/blacklist”
},
“events”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/events”
},
“requests”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/requests”
},
“redactions”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/redactions”
},
“suspiciousIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/suspiciousIPs”
},
“monitors”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/monitors”
},
“integrations”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/integrations”
},
“headerLinks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/headerLinks”
},
“agents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/agents”
},
“alerts”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/alerts”
},
“analyticsEvents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/analytics/events”
},
“topAttacks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/top/attacks”
},
“tags”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/tags”
},
“rules”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/rules”
},
“members”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/members”
}
}
HTTP 400
Name
Type
Description
message
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
created
string
Created RFC3339 date time
Response Example
{
“name”: “www.mysite.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.mysite.com/whitelist”
},
“blacklist”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/blacklist”
},
“events”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/events”
},
“requests”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/requests”
},
“redactions”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/redactions”
},
“suspiciousIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/suspiciousIPs”
},
“rateLimitedIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/rateLimitedIPs”
},
“monitors”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/monitors”
},
“integrations”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/integrations”
},
“headerLinks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/headerLinks”
},
“agents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/agents”
},
“alerts”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/alerts”
},
“analyticsEvents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/analytics/events”
},
“topAttacks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/top/attacks”
},
“members”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/members”
}
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Update a site by name
patch /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
Request Example
{
“displayName”: “My Website1”,
“agentLevel”: “block”,
“blockDurationSeconds”: 259200
}
Responses
HTTP 200
Name
Type
Description
name
stringmin len 3 max len 100
Identifying name of the site
displayName
stringmin len 3 max len 100
Display name of the site
agentLevel
string
Agent action level - 'block', 'log' or 'off'
agentAnonMode
stringdefault off
Agent IP anonimization mode - 'EU' or 'off'
blockDurationSeconds
integerdefault 86400 max 31556900
Duration to block an IP in seconds
blockHTTPCode
integerdefault 406 min 100 max 599
HTTP response code to send when when traffic is being blocked
created
string
Created RFC3339 date time
Response Example
{
“name”: “www.mysite.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.mysite.com/whitelist”
},
“blacklist”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/blacklist”
},
“events”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/events”
},
“requests”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/requests”
},
“redactions”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/redactions”
},
“suspiciousIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/suspiciousIPs”
},
“rateLimitedIPs”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/rateLimitedIPs”
},
“monitors”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/monitors”
},
“integrations”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/integrations”
},
“headerLinks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/headerLinks”
},
“agents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/agents”
},
“alerts”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/alerts”
},
“analyticsEvents”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/analytics/events”
},
“topAttacks”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/top/attacks”
},
“tags”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/tags”
},
“rules”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/advancedRules”
},
“members”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/members”
}
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid block code - must be between 100 and 599”}
Delete site
delete /corps/{corpName}/sites/{siteName}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 204
Delete successful
List site activity events
get /corps/{corpName}/sites/{siteName}/analytics/events
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
from
integer
The POSIX Unix time to start
until
integer
The POSIX Unix time to end
sort
one of (asc,desc) default desc
The sort order
since_id
string
The id of the last object in the set
max_id
string
The id of the last object in the set
limit
integer default 100 max 1000
The number of entries to be returned
page
integer
The page of the results - a maximum of 1000 requests in total will be returned
pretty
boolean
Pretty print the json output
events
one of (alerts,audits,excludeAgentsOnline)
Filter on events
eventType
string
Filter on event type
Responses
HTTP 200
Name
Type
Description
totalCount
integer
Total number of matching documents
data
activityevent array
id
string
Unique ID of the activity event
eventType
string
Event type
msgData
object
Data used to format the message
attachments
tuple array
attachments
objectrequired
Title
string
Fields
tuple array
MarkdownFields
boolean
message
string
Message of the event
created
string
Created RFC3339 date time
Response Example
{
“totalCount”: 5,
“next”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.com/analytics/events?limit=1&page=2”
},
“data”: [
{
“id”: “558cf75c3dfaa4b9c2000001”,
“eventType”: “blacklistIP”,
“msgData”: {“ip”: “1.1.1.1”},
“message”: “User (test@test.net) blacklisted "1.1.1.1"”,
“created”: “2015-02-14T21:17:16Z”
}
]
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
List site members
get /corps/{corpName}/sites/{siteName}/members
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
siteMember array
role
string
Role of the user (owner, admin, user, observer)
user
object
apiUser
boolean
API user
authStatus
string
Auth status of the user
corpAuthType
string
Auth type of the corp
email
string
Email of the user
name
string
Name of the user
status
string
Status of the user
Response Example
{
“data”: [
{
“user”: {
“name”: “Test User”,
“email”: “test@test.net”,
“status”: “active”,
“authStatus”: “none”,
“corpAuthType”: “builtin”,
“apiUser”: false
},
“role”: “owner”
}
]
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Add members to site
post /corps/{corpName}/sites/{siteName}/members
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
Request Example
{
“members: [“test@test.net”]
}
Responses
HTTP 200
Name
Type
Description
data
siteMember array
role
string
Role of the user (owner, admin, user, observer)
user
object
apiUser
boolean
API user
authStatus
string
Auth status of the user
corpAuthType
string
Auth type of the corp
email
string
Email of the user
name
string
Name of the user
status
string
Status of the user
Response Example
{
“data”: [
{
“user”: {
“name”: “Test User”,
“email”: “test@test.net”,
“status”: “active”,
“authStatus”: “none”,
“corpAuthType”: “builtin”,
“apiUser”: false
},
“role”: “owner”
}
]
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid user”}
Get site member by email
get /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
siteMemberEmail
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
role
string
Role of the user (owner, admin, user, observer)
user
object
apiUser
boolean
API user
authStatus
string
Auth status of the user
corpAuthType
string
Auth type of the corp
email
string
Email of the user
name
string
Name of the user
status
string
Status of the user
Response Example
{
“user”: {
“name”: “Test User”,
“email”: “test@test.net”,
“status”: “active”,
“authStatus”: “none”,
“corpAuthType”: “builtin”,
“apiUser”: false
},
“role”: “owner”
},
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Delete from site members
delete /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
siteMemberEmail
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 204
Successful removal from the list
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Invite a site member
post /corps/{corpName}/sites/{siteName}/members/{siteMemberEmail}/invite
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
siteMemberEmail
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
role
stringmin len 1
Role of the user (owner, admin, user, observer)
Request Example
{
“role”: “observer”
}
Responses
HTTP 200
Name
Type
Description
role
string
Role of the user (owner, admin, user, observer)
user
object
apiUser
boolean
API user
authStatus
string
Auth status of the user
corpAuthType
string
Auth type of the corp
email
string
Email of the user
name
string
Name of the user
status
string
Status of the user
Response Example
{
“user”: {
“name”: “Test User”,
“email”: “test@test.net”,
“status”: “active”,
“authStatus”: “none”,
“corpAuthType”: “builtin”,
“apiUser”: false
},
“role”: “owner”
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
List rules in site
get /corps/{corpName}/sites/{siteName}/rules
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
totalCount
number
Total count of Site Rules
data
siteRule array
id
string
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for
duration
integer
Length of time in seconds to enforce the rule for once activated
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
“data”: {
“totalCount”: 1,
“data”: [
{
“id”: “5e191909c931498586c6f537”,
“siteNames”: [
“www.mysite.com”
],
“type”: “request”,
“enabled”: true,
“groupOperator”: “all”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “1.2.3.4/8”
}
],
“actions”: [
{
“type”: “block”
}
],
“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
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Body (application/json)
Name
Type
Description
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
duration
integer
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 3600)
signal
string
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
reason
string
Description of the rule
expiration
string
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”: “1.2.3.4”
},
{
“type”: “group”,
“groupOperator”: “any”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “5.6.7.8”
}
]
}
],
“actions”: [
{
“type”: “excludeSignal”
}
],
“enabled”: true,
“reason”: “Example site rule”,
“signal”: “SQLI”,
“expiration”: "”
}
Responses
HTTP 200
Name
Type
Description
id
string
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for
duration
integer
Length of time in seconds to enforce the rule for once activated
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
“id”: “5e321810f13d660ea4cd8d0f”,
“siteNames”: [
“www.mysite.com”
],
“type”: “signal”,
“enabled”: true,
“groupOperator”: “all”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “1.2.3.4”
},
{
“type”: “group”,
“groupOperator”: “any”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “5.6.7.8”
}
]
}
],
“actions”: [
{
“type”: “excludeSignal”
}
],
“signal”: “SQLI”,
“reason”: “Example site rule”,
“expiration”: “”,
“createdBy”: “test@test.net”,
“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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for
duration
integer
Length of time in seconds to enforce the rule for once activated
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
“id”: “5e321810f13d660ea4cd8d0f”,
“siteNames”: [
“www.mysite.com”
],
“type”: “signal”,
“enabled”: true,
“groupOperator”: “all”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “1.2.3.4”
},
{
“type”: “group”,
“groupOperator”: “any”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “5.6.7.8”
}
]
}
],
“actions”: [
{
“type”: “excludeSignal”
}
],
“signal”: “SQLI”,
“reason”: “Example site rule”,
“expiration”: “”,
“createdBy”: “test@test.net”,
“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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Body (application/json)
Name
Type
Description
siteNames
string array
Sites with the rule available. Rules with a global corpScope will return '[]'.
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for (default: 1, options: 1, 10)
duration
integer
Length of time in seconds to enforce the rule for once activated (default: 600, minimum: 300, maximum: 3600)
signal
string
The signal id of the signal being excluded (for rateLimit rules this is the signal to be attached)
reason
string
Description of the rule
expiration
string
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”: “6.7.8.9”
},
{
“type”: “group”,
“groupOperator”: “any”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “5.6.7.8”
}
]
}
],
“actions”: [
{
“type”: “excludeSignal”
}
],
“signal”: “SQLI”,
“reason”: “Known malicious IPs”,
“expiration”: ""
}
Responses
HTTP 200
Name
Type
Description
id
string
type
string
Type of rule (request, signal exclusion, rateLimit)
enabled
boolean
groupOperator
string
Conditions that must be matched when evaluating the request (all, any)
conditions
object array
type
string
(group, single)
groupOperator
string
type: group - Conditions that must be matched when evaluating the request (all, any)
field
string
type: single - (scheme, method, path, useragent, domain, ip, responseCode, agentname, paramname, paramvalue, country, name, valueString, valueIp, signalType)
operator
string
type: single - (equals, doesNotEqual, contains, doesNotContain, like, notLike, exists, doesNotExist, inList, notInList)
value
string
type: single - See request fields (https://docs.signalsciences.net/using-signal-sciences/features/rules/#request-fields)
actions
object array
For rateLimit rules an action with a valid type and signal is required, for all other rules only type is required
signal
string
For rateLimit rules, the signal to act upon when activating the rateLimit
type
string
(block, allow, exclude) (rateLimit rule valid values: logRequest, blockSignal)
rateLimit
object
threshold
integer
Requests counted before activating the rate limit
interval
integer
Length of time in minutes the threshold should be measured for
duration
integer
Length of time in seconds to enforce the rule for once activated
reason
string
Description of the rule
expiration
string
Date the rule will automatically be disabled. If rule is always enabled, will return empty string
createdBy
string
The user that created the rule
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
“id”: “5e321810f13d660ea4cd8d0f”,
“siteNames”: [
“www.mysite.com”
],
“type”: “signal”,
“enabled”: true,
“groupOperator”: “all”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “6.7.8.9”
},
{
“type”: “group”,
“groupOperator”: “any”,
“conditions”: [
{
“type”: “single”,
“field”: “ip”,
“operator”: “equals”,
“value”: “5.6.7.8”
}
]
}
],
“actions”: [
{
“type”: “excludeSignal”
}
],
“signal”: “SQLI”,
“reason”: “Known malicious IPs”,
“expiration”: “”,
“createdBy”: “test@test.net”,
“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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 204
Delete successful
List available rule templates
get /corps/{corpName}/sites/{siteName}/templates
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
template array
id
string
name
string
Name of templated rule
shortName
string
Display name of templated rule
description
string
Description of templated rule
fields
object array
name
string
Name of template field
type
string
Value type of template field
label
string
Short description for template field
placeholder
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
name
string
Name of templated rule
shortName
string
Display name of templated rule
description
string
Description of templated rule
fields
object array
name
string
Name of template field
type
string
Value type of template field
label
string
Short description for template field
placeholder
string
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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
List configured templated rules
get /corps/{corpName}/sites/{siteName}/configuredTemplates
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
configuredTemplate array
name
string
detections
configuredTemplateDetection array
id
string
name
string
Name of templated rule
enabled
boolean
A flag to toggle this detection
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
alerts
alert array
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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”: “test@sigsci.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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
name
string
Name of templated rule
shortName
string
Display name of templated rule
description
string
Description of templated rule
fields
object array
name
string
Name of template field
type
string
Value type of template field
label
string
Short description for template field
placeholder
string
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”: “test@sigsci.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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Update site template rule by name
post /corps/{corpName}/sites/{siteName}/configuredTemplates/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Body (application/json)
Name
Type
Description
alertAdds
configuredTemplateAlertAdd array
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integermin 1 max 10000
The number of occurrences of the tag in the interval needed to trigger the alert.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
alertDeletes
alert array
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
alertUpdates
alert array
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
detectionAdds
configuredTemplateDetectionAdd array
enabled
boolean
A flag to toggle this detection
detectionDeletes
configuredTemplateDetection array
id
string
name
string
Name of templated rule
enabled
boolean
A flag to toggle this detection
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
detectionUpdates
configuredTemplateDetection array
id
string
name
string
Name of templated rule
enabled
boolean
A flag to toggle this detection
createdBy
string
The email of the user that created the alert
created
string
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
Type
Description
name
string
detections
configuredTemplateDetection array
id
string
name
string
Name of templated rule
enabled
boolean
A flag to toggle this detection
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
alerts
alert array
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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”: “test@sigsci.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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Validation failed”}
Get all lists
get /corps/{corpName}/sites/{siteName}/lists
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Responses
HTTP 200
Name
Type
Description
data
list array
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
Last updated RFC3339 date time
Response Example
{
“data”: [
{
“id”: “site.known-attackers”,
“name”: “Known Attackers”,
“type”: “ip”,
“description”: “Malicious IPs we're tracking”,
“entries”: [
“4.5.6.7”,
“2.3.4.5”,
“1.2.3.4”
],
“createdBy”: “test@test.net”,
“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”: “test@test.net”,
“created”: “2018-08-03T20:50:54Z”,
“updated”: “2018-08-03T20:50:59Z”
}
]
}
Create list
post /corps/{corpName}/sites/{siteName}/lists
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Body (application/json)
Name
Type
Description
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
Request Example
{
“name”: “My New List”,
“type”: “ip”,
“description”: “Some IPs we're putting in a list”,
“entries”: [
“4.5.6.7”,
“2.3.4.5”,
“1.2.3.4”
]
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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”: [
“4.5.6.7”,
“2.3.4.5”,
“1.2.3.4”
],
“createdBy”: “test@test.net”,
“created”: “2018-08-16T17:38:27Z”,
“updated”: “2018-08-16T17:38:27Z”
}
HTTP 400
Name
Type
Description
message
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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”: [
“4.5.6.7”,
“2.3.4.5”,
“1.2.3.4”
],
“createdBy”: “test@test.net”,
“created”: “2018-08-16T17:38:27Z”,
“updated”: “2018-08-16T17:38:27Z”
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Update list by id
patch /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Body (application/json)
Name
Type
Description
description
stringmax len 140
Optional list description
entries
object
Request Example
{
“entries”: {
“additions”: [
“9.9.8.8”
],
“deletions”: [
“4.5.6.7”,
“1.2.3.4”
]
}
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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”: [
“2.3.4.5”,
“9.9.8.8”
],
“createdBy”: “test@test.net”,
“created”: “2018-08-16T17:38:27Z”,
“updated”: “2018-08-16T21:43:08Z”
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Replace list by id
put /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Body (application/json)
Name
Type
Description
description
stringmax len 140
Optional list description
Request Example
{
“description”: “Some IPs we're still putting in a list”,
“entries”: [
“4.5.6.7”,
“1.2.3.4”,
“9.8.7.6”
]
}
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the list
name
stringmin len 3 max len 32
Descriptive list name
type
string
List types (string, ip, country, wildcard)
description
stringmax len 140
Optional list description
createdBy
string
Email address of the user that created the item
created
string
Created RFC3339 date time
updated
string
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”: [
“4.5.6.7”,
“1.2.3.4”,
“9.8.7.6”
],
“createdBy”: “test@test.net”,
“created”: “2018-08-16T17:38:27Z”,
“updated”: “2018-08-16T21:43:08Z”
}
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
Delete list
delete /corps/{corpName}/sites/{siteName}/lists/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 204
Successful removal from the list
HTTP 404
Name
Type
Description
message
string
Error message
Response Example
{“message”:“ID not found”}
List alerts
get /corps/{corpName}/sites/{siteName}/alerts
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Responses
HTTP 200
Name
Type
Description
data
alert array
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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”: “test@test.net”,
“created”: “2020-02-13T23:23:03Z”,
“updated”: “2020-01-13T23:23:03Z”
}
]
}
Create alert
post /corps/{corpName}/sites/{siteName}/alerts
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Body (application/json)
Name
Type
Description
tagName
string
The name of the tag whose occurrences the alert is watching. Must match an existing tag
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integermin 1 max 10000
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
enabled
boolean
A flag to toggle this alert.
action
string
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
Name
Type
Description
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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”: “test@test.net”,
“created”: “2020-02-13T23:23:03Z”,
“updated”: “2020-01-13T23:23:03Z”
}
Get alert
get /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 200
Name
Type
Description
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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”: “test@test.net”,
“created”: “2020-02-13T23:23:03Z”,
“updated”: “2020-01-13T23:23:03Z”
}
Update alert
patch /corps/{corpName}/sites/{siteName}/alerts/{id}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Body (application/json)
Name
Type
Description
tagName
string
The name of the tag whose occurrences the alert is watching. Must match an existing tag
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integermin 1 max 10000
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
enabled
boolean
A flag to toggle this alert.
action
string
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
Name
Type
Description
id
string
Site-specific unique ID of the alert
tagName
string
The name of the tag whose occurrences the alert is watching.
longName
string
A human readable description of the alert. Must be between 3 and 25 characters.
type
string
Type of alert (siteAlert, template, rateLimit, siteMetric)
interval
integer
The number of minutes of past traffic to examine. Must be 1, 10 or 60.
threshold
integer
The number of occurrences of the tag in the interval needed to trigger the alert.
blockDurationSeconds
integer
The number of seconds this alert is active.
skipNotifications
boolean
A flag to disable external notifications - slack, webhooks, emails, etc.
enabled
boolean
A flag to toggle this alert.
action
string
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.
fieldName
string
createdBy
string
The email of the user that created the alert
created
string
Created RFC3339 date time
operator
string
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
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
id
string required
Responses
HTTP 204
Delete successful
Search requests
get /corps/{corpName}/sites/{siteName}/requests
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
page
integer
The page of the results - a maximum of 1000 requests in total will be returned
limit
integer default 100 max 1000
The number of entries to be returned
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
totalCount
integer
Total number of records matching the search
data
request array
id
string
Unique ID of the request
timestamp
string
Timestamp RFC3339 date time
serverHostname
string
Server hostname
serverName
string
Server name
uri
string
URI
path
string
Path
userAgent
string
User agent of the request
remoteIP
string
Remote IP address
remoteHostname
string
Remote hostname
remoteCountryCode
string
Remote country code
method
string
HTTP method e.g. PUT
protocol
string
HTTP protocol e.g. HTTP/1.1
responseCode
integer
HTTP response code
responseSize
integer
HTTP response size
responseMillis
integer
Response time in millis
agentResponseCode
integer
Agent response code
tags
object array
type
string
Type of tag
location
string
Where the tag was detected
value
string
Value
detector
string
Detector
Response Example
{
“totalCount”: 3,
“next”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.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,
“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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Get request by ID
get /corps/{corpName}/sites/{siteName}/requests/{requestID}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
requestID
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
id
string
Unique ID of the request
timestamp
string
Timestamp RFC3339 date time
serverHostname
string
Server hostname
serverName
string
Server name
uri
string
URI
path
string
Path
userAgent
string
User agent of the request
remoteIP
string
Remote IP address
remoteHostname
string
Remote hostname
remoteCountryCode
string
Remote country code
method
string
HTTP method e.g. PUT
protocol
string
HTTP protocol e.g. HTTP/1.1
responseCode
integer
HTTP response code
responseSize
integer
HTTP response size
responseMillis
integer
Response time in millis
agentResponseCode
integer
Agent response code
tags
object array
type
string
Type of tag
location
string
Where the tag was detected
value
string
Value
detector
string
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,
“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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Get request feed
get /corps/{corpName}/sites/{siteName}/feed/requests
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
data
request array
id
string
Unique ID of the request
timestamp
string
Timestamp RFC3339 date time
serverHostname
string
Server hostname
serverName
string
Server name
uri
string
URI
path
string
Path
userAgent
string
User agent of the request
remoteIP
string
Remote IP address
remoteHostname
string
Remote hostname
remoteCountryCode
string
Remote country code
method
string
HTTP method e.g. PUT
protocol
string
HTTP protocol e.g. HTTP/1.1
responseCode
integer
HTTP response code
responseSize
integer
HTTP response size
responseMillis
integer
Response time in millis
agentResponseCode
integer
Agent response code
tags
object array
type
string
Type of tag
location
string
Where the tag was detected
value
string
Value
detector
string
Detector
Response Example
{
“next”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.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,
“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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid timestamp param”}
HTTP 500
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Error performing search”}
HTTP 504
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Feed timeout exceeded”}
List events
get /corps/{corpName}/sites/{siteName}/events
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
from
integer
The POSIX Unix time to start
until
integer
The POSIX Unix time to end
sort
one of (asc,desc) default desc
The sort order
since_id
string
The id of the last object in the set
max_id
string
The id of the last object in the set
limit
integer default 100 max 1000
The number of entries to be returned
page
integer
The page of the results - a maximum of 1000 requests in total will be returned
pretty
boolean
Pretty print the json output
action
one of (flagged,info)
Filter based on action
tag
string min len 3 matching [a-zA-Z0-9_-]+
Filter based on tag
ip
string min len 7 max len 15
Filter based on IP
status
one of (active,expired)
Filter based on status
Responses
HTTP 200
Name
Type
Description
totalCount
integer
Total number of matching documents
data
event array
id
string
Unique ID of the event
timestamp
string
Timestamp RFC3339 date time
source
string
Source information
remoteCountryCode
string
Country code
remoteHostname
string
Remote hostname
action
string
Either “flagged” (IP is flagged and subsequent malicious requests will be blocked) or “info” (IP is flagged and subsequent requests will be logged).
reasons
object
Key attack type - value number of
requestCount
integer
Total number of requests
tagCount
integer
Total number of tags
window
integer
Time window in seconds where the items were detected
expires
string
Expires RFC3339 date time
expiredBy
string
email of the user if the event is expired manually
Response Example
{
“totalCount”: 5,
“next”: {
“uri”: “/api/v0/corps/testcorp/sites/www.mysite.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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Get event by ID
get /corps/{corpName}/sites/{siteName}/events/{eventID}
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
eventID
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
id
string
Unique ID of the event
timestamp
string
Timestamp RFC3339 date time
source
string
Source information
remoteCountryCode
string
Country code
remoteHostname
string
Remote hostname
action
string
Either “flagged” (IP is flagged and subsequent malicious requests will be blocked) or “info” (IP is flagged and subsequent requests will be logged).
reasons
object
Key attack type - value number of
requestCount
integer
Total number of requests
tagCount
integer
Total number of tags
window
integer
Time window in seconds where the items were detected
expires
string
Expires RFC3339 date time
expiredBy
string
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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
Expire an event by ID
post /corps/{corpName}/sites/{siteName}/events/{eventID}/expire
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
eventID
string required
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
Responses
HTTP 200
Name
Type
Description
id
string
Unique ID of the event
timestamp
string
Timestamp RFC3339 date time
source
string
Source information
remoteCountryCode
string
Country code
remoteHostname
string
Remote hostname
action
string
Either “flagged” (IP is flagged and subsequent malicious requests will be blocked) or “info” (IP is flagged and subsequent requests will be logged).
reasons
object
Key attack type - value number of
requestCount
integer
Total number of requests
tagCount
integer
Total number of tags
window
integer
Time window in seconds where the items were detected
expires
string
Expires RFC3339 date time
expiredBy
string
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
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
List suspicious IPs
get /corps/{corpName}/sites/{siteName}/suspiciousIPs
Request
URI Parameters
Name
Type
Description
corpName
string required matching [0-9a-z_.-]+
Corp shortname
siteName
string required matching [0-9a-z_.-]+
Query Parameters
Name
Type
Description
pretty
boolean
Pretty print the json output
limit
integer default 5 min 1 max 50
The number of IPs to be returned
Responses
HTTP 200
Name
Type
Description
data
suspiciousIP array
source
string
IP address
remoteCountryCode
string
Remote country code
remoteHostname
string
Remote hostname
percent
integer
Percent towards flagged threshold
tagName
string
Attack tag seen from this IP
shortName
string
Label for this attack tag
intervalStart
string
Beginning of most recent interval in which this attack was seen
timestamp
string
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”,
“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”,
“intervalStart”: “2016-08-09T17:05:17Z”,
“timestamp”: “2016-08-09T18:05:17Z”,
}
]
}
HTTP 400
Name
Type
Description
message
string
Error message
Response Example
{“message”:“Invalid site”}
List rate-limited IPs
get /corps/{corpName}/sites/{siteName}/rateLimitedIPs
Request
URI Parameters
Name
Type
Description
corpName