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": 1025
33
      }
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": false
50
      }
51
    ]
52
  }
53
}

Error Response

Sample Call

python
1
import requests
2
import json
3
4
API_KEY = '00112233-4455-6677-8899-aabbccddeeff'
5
6
7
data ={"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"}}
8
9
def handle_response(resp):
10
    response = resp
11
    if response.status_code >= 200:
12
        print response.status_code
13
        print response.text
14
        return
15
16
def make_request():
17
    headers = {'Content-type': 'application/json', 'x-api-key': API_KEY}
18
    body = json.dumps(data, separators=(',', ':'))
19
    url = "https://us.rest.logs.insight.rapid7.com/management/tags"
20
    req = requests.post(url, data=body, headers=headers)
21
    return req
22
23
def start():
24
    req = make_request()
25
    handle_response(req)
26
27
if __name__ == '__main__':
28
    start()

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.

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,

• Email
• 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