POST Tag
POST Tag
Request used to create a new Tag for a given account
URL
https://REGION.rest.logs.insight.rapid7.com/management/tags
REGION is the data center for your account - e.g. "us" or "eu"
Method
POST
Authentication
Read Write key is required.
URL Params
None
Data Params
json
1{2"tag": {3"actions": [4{5"enabled": true,6"min_matches_count": 0,7"min_matches_period": "Hour",8"min_report_count": 1,9"min_report_period": "Hour",10"targets": [11{12"alert_content_set": {13"le_context": "true"14},15"params_set": {16"direct": "test@test.com",17"teams": "",18"users": ""19},20"type": "mailto"21}22],23"type": "Alert"24}25],26"labels": [27{28"color": "3498db",29"id": "a6b486c1-306f-4575-95cc-0eee40f8f7e6",30"name": "Test Label",31"reserved": false,32"sn": 102533}34],35"name": "Foo Bar Tag",36"patterns": [37"/Foo Bar/"38],39"sources": [40{41"id": "3358b7ee-9238-4181-ab80-afb026f38081"42}43],44"type": "Alert"45}46}
Success Response
Code 201Content:
json
1{2"tag": {3"type": "Alert",4"id": "d3132c7a-f9d1-4485-9898-3a2bd2959a05",5"name": "Foo Bar Tag",6"sources": [7{8"id": "3358b7ee-9238-4181-ab80-afb026f38081",9"retention_period": "default",10"token": "993fcb68-2775-4f44-94b3-b8612d9213ef",11"name": "My Web Log",12"stored_days": []13}14],15"actions": [16{17"id": "139b4be1-3069-425e-afa4-66a66d8196dc",18"min_matches_count": 0,19"min_report_count": 1,20"min_matches_period": "Hour",21"min_report_period": "Hour",22"targets": [23{24"id": null,25"type": "Mailto",26"params_set": {27"direct": "test@test.com",28"teams": "",29"users": ""30},31"alert_content_set": {32"le_context": "true"33}34}35],36"enabled": true,37"type": "Alert"38}39],40"patterns": [41"TEST"42],43"labels": [44{45"id": "a6b486c1-306f-4575-95cc-0eee40f8f7e6",46"sn": 1025,47"name": "Test Label",48"color": "3498db",49"reserved": false50}51]52}53}
Error Response
Sample Call
python
1import requests2import json34API_KEY = '00112233-4455-6677-8899-aabbccddeeff'567data ={"tag":{"actions":[{"enabled":True,"min_matches_count":0,"min_matches_period":"Hour","min_report_count":1,"min_report_period":"Hour","targets":[{"alert_content_set":{"le_context":"true"},"params_set":{"direct":"test@test.com","teams":"","users":""},"type":"mailto"}],"type":"Alert"}],"labels":[{"color":"3498db","id":"a6b486c1-306f-4575-95cc-0eee40f8f7e6","name":"Test Label","reserved":False,"sn":1025}],"name":"Foo Bar Tag","patterns":["/Foo Bar/"],"sources":[{"id":"3358b7ee-9238-4181-ab80-afb026f38081"}],"type":"Alert"}}89def handle_response(resp):10response = resp11if response.status_code >= 200:12print response.status_code13print response.text14return1516def make_request():17headers = {'Content-type': 'application/json', 'x-api-key': API_KEY}18body = json.dumps(data, separators=(',', ':'))19url = "https://us.rest.logs.insight.rapid7.com/management/tags"20req = requests.post(url, data=body, headers=headers)21return req2223def start():24req = make_request()25handle_response(req)2627if __name__ == '__main__':28start()
SubType
Tags can be configured to use a subtype Alert such as an Inactivity Alert. To configure an Inactivity Alert the following params must be set.
Field | Value |
---|---|
type | Type of Alert to be set 'AlertNotify' |
sub_type | Subtype of alert to be set 'InactivityAlert' |
timeframe_value | Length of inactivity duration before an alert is triggered |
timeframe_period | Unit of time to be used Week , Day , Hour and Minute |
The full payload with add target is shown below.
json
1{2"tag": {3"type": "AlertNotify",4"patterns": [],5"actions": [6{7"type": "Alert",8"enabled": true,9"targets": [10{11"type": "mailto",12"params_set": {13"direct": "foobar@gmail.com",14"users": "",15"teams": ""16},17"alert_content_set": {18"le_context": "true"19}20}21],22"min_report_count": 1,23"min_report_period": "Hour"24}25],26"sources": [27{28"id": "9fce33ff-bf5c-4c13-aecd-d8295ed0743a"29}30],31"timeframe_value": 7,32"timeframe_period": "Day",33"name": "MyInactivityAlert",34"sub_type": "InactivityAlert"35}36}
Targets
Targets are defined as an endpoint that an action will communicate with if an Alert is triggered. The available targets include,
- Slack
- Hipchat
- PagerDuty
- Webhook
Email Target
To configure your Tag to trigger an email alert add the following target in your actions
array object.
json
1"type": "mailto",2"params_set": {3"direct": "foobar@gmail.com, foobar2@gmail.com",4"users": "AdminSteve",5"teams": "Team1"6},7"alert_content_set": {8"le_context": "true"9}10}]
Email targets can be configured to send to a comma separate list of emails, usernames or teams.
You can also enable or disable whether log context should appear in the Email Alert by enabling/disabling le_context
Slack Target
To configure your Tag to trigger a Slack alert add the following target in your actions
array object.
json
1"targets": [2{3"type": "slack",4"params_set": {5"url": "https://hooks.slack.com/services/T012345/B01234"6},7"alert_content_set": {8"le_context": "true"9}10}11]
You can also enable or disable whether log context should appear in the Slack alert by enabling/disabling le_context
PagerDuty Target
To configure your Tag to trigger a PagerDuty alert add the following target in your actions
array object.
json
1"targets": [2{3"type": "pagerduty",4"params_set": {5"service_key": "a0978e46-d67d-4308-a672-dfc2debc3afe",6"description": "A PagerDuty Alert"7},8"alert_content_set": {9"le_context": "true"10}11}12],
You can also enable or disable whether log context should appear in the PagerDuty later by enabling/disabling le_context
Webhook Target
To configure your Tag to trigger a Webhook alert add the following target in your actions
array object.
json
1"targets": [2{3"type": "webhook",4"params_set": {5"url": "http://requestb.in/te2zfpte"6},7"alert_content_set": {8"le_context": "true"9}10}11]
You can also enable or disable whether log context should appear in the Webhook by enabling/disabling le_context