...
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
Following is a sample session management template for REST API endpoint:
{
"name": "session",
"version": "2.0",
...
"session_duration": 60000
}
...
Note: The The login_template and logout_template lines specify the templates to be executed for login and logout.
The session_duration line specifies the length of the session. You must upload the login and logout templates and logout templates before configuring a session management template that refers them.
...
{
...
Following is a sample session management template for DXL endpoint:
{"name": "
...
session_tmplate",
...
"version": "
...
3.0",
...
"
...
type": "
...
DXL_ENDPOINT",
...
"
...
vendor_identifier": "
...
DXL",
...
"
...
"content_type": "text/xml",
...
dxl_keep_alive_interval": 60,
"dxl_topic": "/outbound/session"
}
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
{
"name": "login",
"version": "2.0",
"vendor_identifier": "Rapid7",
"type": "REST_EVENT",
"event_type": ["SESSION"],
"content_type": "text/xml",
"quoting": "XMLA",
"steps": [
...
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
{
"name": "action",
...
Following is a sample action template for DXL endpoint:
{
"vendor_identifier": "
...
DXL",
...
"version": "
...
3.0",
...
"
...
name": "
...
action
...
"
...
,
...
"
...
type": "
...
DXL_EVENT",
...
"event_type": [
"FIXED_ADDRESS_IPV4"
],
"
...
dxl_topic": "/outbound/action",
"steps": [
...
{
...
"
...
operation": "
...
DXL_SEND_EVENT",
...
"
...
name": "
...
send_ip",
...
"
...
"statements": [
{
"op": "!=",
...
body": "address ${E:A:
...
values{ipv4addr}}",
...
"
...
dxl_topic": "
...
},
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "DELETE"
}
],
...
/outbound/step"
}
]
}
Following is a sample action template for REST API endpoint:
{
"name": "action",
"vendor_identifier": "Rapid7",
"version": "2.0",
"content_type": "text/xml",
"action_type": "add network or remove IP",
"stopquoting": true
}
},
{
"XMLA",
"type": "REST_EVENT",
"event_type": [ "FIXED_ADDRESS_IPV4", "FIXED_ADDRESS_IPV6" ],
"steps": [
{
"name": "send SiteListingRequestcheck operation type",
"operation": "POSTCONDITION",
"body_list "condition": {
"statements": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteListingRequest session-id=\"${S::SESSID}\" />"
],
"parse": "XMLA"
},
{
"operation": "CONDITION",
"name": "send SiteListingRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteListingResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true,
"else_eval": "${XC:COPY:{L:site_list}:{P:PARSE}"
}
},
{
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
},
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "DELETE"
}
],
"condition_type": "AND",
"stop": true
}
},
{
"name": "send SiteListingRequest",
"operation": "POST",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteListingRequest session-id=\"${S::SESSID}\" />"
],
"parse": "XMLA"
},
{
"operation": "CONDITION",
"name": "check whether site list is emptysend SiteListingRequest (error check)",
"condition": {
"statements": [
{
"op": "!==",
"right": "${LP:L:site_listA:PARSE[[name]]}",
"left": "0SiteListingResponse"
}],
"condition_type {
"op": "AND!=",
"stopright": true
}
},
{
"operation": "VARIABLEOP",
"name": "get the next site",
"variable_ops": [{
"operation": "POP",
"type": "COMPOSITE",
"destination": "L:a_site",
"source": "L:site_list"
}]
"1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true,
"else_eval": "${XC:COPY:{L:site_list}:{P:PARSE}"
}
},
{
"operation": "CONDITION",
"name": "check whether site namelist is empty",
"condition": {
"statements": [{
"op": "!==",
"right": "${L:AL:a_site{{name}}site_list}",
"left": "${E:A:values{extattrs}{r7_site}{value}}0"
}],
"condition_type": "AND",
"next": "check whether site list is empty",
"else_eval": "${XC:COPY:{L:site_id}:{L:a_site{{id}}}}"
}
},
{
"parse": "XMLAstop": true
}
},
{
"operation": "VARIABLEOP",
"name": "get the next site",
"variable_ops": [{
"operation": "POP",
"operationtype": "POSTCOMPOSITE",
"namedestination": "send SiteConfigRequestL:a_site",
"body"source": "L:site_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteConfigRequest session-id=\"${S::SESSID}\" site-id=\"${L:A:site_id}\"/>"
]
},
{
"operation": "
}]
},
{
"operation": "CONDITION",
"name": "send SiteConfigRequest (error check)check site name",
"condition": {
"statements": [
{
"op": "!=",
"right": "${PL:A:PARSE[[name]]}",
"left": "SiteConfigResponse"
},
{
"op": "!=",
"right": "1",
"a_site{{name}}}",
"left": "${PE:A:PARSEvalues{extattrs}{successr7_site}{value}}"
}
],
"condition_type": "ORAND",
"next": "check whether site list is empty",
"else_eval": "${XC:COPY:{L:Sitesite_id}:{P:PARSE{SiteConfigResponseL:a_site{{id}}}}",
"error": true
}
},
{
"operationparse": "CONDITIONXMLA",
"nameoperation": "check operation type againPOST",
"conditionname": {
"statements"send SiteConfigRequest",
"body_list": [{
"op": "=="<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"right": "<SiteConfigRequest session-id=\"${S::SESSID}\" site-id=\"${EL:A:operationsite_typeid}\",/>"
"left": "INSERT"]
}],
"condition_type": "AND",
"eval":
"${XC:COPY:{L:network}:{E:values{network}}}${XC:NETWORKTORANGE:{L:network}:{L:range
}}",
"next": "insert network"
}
},
{
"operation": "{
"operation": "CONDITION",
"name": "remove ipsend SiteConfigRequest (error check)",
"condition": {
"statements": [
{
"op": "!==",
"right": "${EP:A:event_typePARSE[[name]]}",
"left": "FIXED_ADDRESS_IPV4SiteConfigResponse"
}],
"condition_type {
"op": "AND!=",
"evalright": "1",
"left": "${XCP:COPYA:PARSE{L:ip}:{E:values{ipv4addr{success}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
],
"condition_type": "OR",
"else_eval":
"${XC:COPY:{L:ipSite}:{EP:valuesPARSE{ipv6addrSiteConfigResponse}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
",
"error": true
}
},
{
"operation": "CONDITION",
"name": "jump to sendcheck operation type again",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"nexteval": "send SiteSaveRequest"
}
},
{
"operation": "VARIABLEOP",
"name": "insert network",
"variable_ops": [{
"operation": "PUSH",
"type": "COMPOSITE",
"source": "L:range
"${XC:COPY:{L:network}:{E:values{network}}}${XC:NETWORKTORANGE:{L:network}:{L:range
}}",
"destinationnext": "L:Site{Site}{Hosts}insert network"
}]
},
{
"parseoperation": "XMLACONDITION",
"operationname": "POSTremove ip",
"namecondition": "send SiteSaveRequest",
"body_list{
"statements": [{
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteSaveRequest session-id=\"${S::SESSID}\">",
"${L:x:Site}",
"</SiteSaveRequest>"
]
},
{
"operation": "CONDITION",
"name": "send SiteSaveRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteSaveResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true
"op": "==",
"right": "${E:A:event_type}",
"left": "FIXED_ADDRESS_IPV4"
}],
"condition_type": "AND",
"eval":
"${XC:COPY:{L:ip}:{E:values{ipv4addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}",
"else_eval":
"${XC:COPY:{L:ip}:{E:values{ipv6addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
},
{
"operation": "CONDITION",
"name": "check operation type once morejump to send",
"condition": {
"statements": [{
"op": "!==",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"stopnext": true
"send SiteSaveRequest"
}
},
{
"operation": "PUTVARIABLEOP",
"name": "add an attribute with WAPIinsert network",
"transportvariable_ops": [{
"pathoperation": "${E:A:values{_ref}}"}PUSH",
"wapitype": "v2.6COMPOSITE",
"bodysource": "{\"extattrs+\": {\"r7_added\": {\"value\": \"Added to the Rapid7 ${UT:A:TIME}\"}}}"
}
]
}
Action Template: Check Operation Type
{
"name": "check operation type",
L:range",
"destination": "L:Site{Site}{Hosts}"
}]
},
{
"parse": "XMLA",
"operation": "CONDITIONPOST",
"conditionname": {
"statements"send SiteSaveRequest",
"body_list": [
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
},
{
"op": "!=",
" "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteSaveRequest session-id=\"${S::SESSID}\">",
"${L:x:Site}",
"</SiteSaveRequest>"
]
},
{
"operation": "CONDITION",
"name": "send SiteSaveRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${EP:A:operation_typePARSE[[name]]}",
"left": "DELETESiteSaveResponse"
},
],
"condition_type {
"op": "AND!=",
"stopright": true
}
Note: The "check operation type
" step checks the operation type. If it is neither INSERT nor DELETE, the template execution stops.
Action Template: Get the List of Sites
{
"name": "send SiteListingRequest",
"operation": "POST",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteListingRequest session-id=\"${S::SESSID}\" />"
],
"parse": "XMLA"
},
{
"operation": "CONDITION",
"name": "send SiteListingRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteListingResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true,
"else_eval": "${XC:COPY:{L:site_list}:{P:PARSE}"
}
}
Note: The "send SiteListingRequest
" and "send SiteListingRequest (error check)
" steps request the list of sites on a Rapid7 server. If the response is successful, it copies the list to the L:site_list variable
.
Action Template: Locate the Site ID by Name
{
"operation": "CONDITION",
"name": "check whether site list is empty",
"condition": {
"statements": [{
"op": "==",
"right": "${L:L:site_list}",
"left": "0"
}],
"condition_type": "AND",
"stop": true
}
},
{
"operation": "VARIABLEOP",
"name": "get the next site",
"variable_ops": [{
"operation": "POP",
"type": "COMPOSITE",
"destination": "L:a_site",
"source": "L:site_list"
}]
},
{
"1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true
}
},
{
"operation": "CONDITION",
"name": "check operation type once more",
"condition": {
"statements": [{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"stop": true
}
},
{
"operation": "PUT",
"name": "add an attribute with WAPI",
"transport": {"path": "${E:A:values{_ref}}"},
"wapi": "v2.6",
"body": "{\"extattrs+\": {\"r7_added\": {\"value\": \"Added to the Rapid7 ${UT:A:TIME}\"}}}"
}
]
}
Action Template: Check Operation Type
{
"name": "check operation type",
"operation": "CONDITION",
"condition": {
"statements": [
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
},
{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "DELETE"
}
],
"condition_type": "AND",
"stop": true
}
...
Note: The "check operation type
" step checks the operation type. If it is neither INSERT nor DELETE, the template execution stops.
...
Action Template: Get the List of Sites
{
"name": "send SiteListingRequest",
"operation": "POST",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteListingRequest session-id=\"${S::SESSID}\" />"
],
"parse": "XMLA"
},
{
"operation": "CONDITION",
"name": "check site namesend SiteListingRequest (error check)",
"condition": {
"statements": [{
{
"op": "!=",
"right": "${LP:A:a_site{{name}}}",
PARSE[[name]]}",
"left": "SiteListingResponse"
},
{
"op": "!=",
"right": "1",
"left": "${EP:A:valuesPARSE{extattrs}{r7_sitesuccess}{value}}"
}
],
"condition_type": "ANDOR",
"nexterror": "check whether site list is empty"true,
"else_eval": "${XC:COPY:{L:site_idlist}:{L:a_site{{id}}}}"
}
}
NOTES:
...
P:PARSE}"
}
}
...
Note: The "send SiteListingRequest
" and "send SiteListingRequest (error check)
" steps request the list of sites on a Rapid7 server. If the response is successful, it copies the list to the L:site_list variable
.
...
Action Template: Locate the Site ID by Name
{
"operation": "CONDITION",
"name": "check whether site list is empty"
...
Action Template: Get Site Configuration
{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteConfigRequest",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteConfigRequest session-id=\"${S::SESSID}\" site-id=\"${L:A:site_id}\"/>"
]
},
{
...
,
"condition": {
"statements": [{
"op": "==",
"right": "${L:L:site_list}",
"left": "0"
}],
"condition_type": "AND",
"stop": true
}
},
{
"operation": "VARIABLEOP",
"name": "get the next site",
"variable_ops": [{
"operation": "POP",
"type": "COMPOSITE",
"destination": "L:a_site",
"source": "L:site_list"
}]
},
{
"operation": "CONDITION",
...
"name": "
...
check site name",
...
"condition": {
"statements": [{
...
"op": "!=",
...
"right": "${
...
L:A:
...
"left": "SiteConfigResponse"
},
{
"op": "!=",
"right": "1",
...
a_site{{name}}}",
"left": "${
...
E:A:
...
values{extattrs}{
...
r7_site}{value}}"
}
...
],
"condition_type":
...
"AND",
"next": "check whether site list is empty",
"else_eval": "${XC:COPY:{L:
...
site_id}:{
...
L:a_site{{id}}}}"
...
"error": true
...
}
}
Note: Once site-id
is known, steps "send SiteConfigRequest"
and "send SiteConfigRequest (error check)"
request and store the site configuration.
Action Template: Distinguish Between INSERT and DELETE
{
"operation": "CONDITION",
"name": "check operation type again",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"eval":
...
NOTES:
- The "
check whether site list is empty
", "get the next site
", and "check site name
" steps form a loop for finding the site with specific name in the list of sites. - The "
check whether site list is empty
" step checks to see if the list is empty. If it is empty, the site with the specific name is not found and the execution of the template stops. - In the "
get the next site
" step, one element is copied to theL:a_site
variable. - In the "
check site name
" step, the "name
" attribute of a site (${L:A:a_site{{name}}}
) is compared to the value of the "r7_site
" extensible attribute of the fixed address in(${E:A:values{extattrs}{r7_site}{value}})
. If they are the same, the site ID is stored to theL:site_id variable (${XC:COPY:{L:
...
site_id}:{
...
}}",
"next": "insert network"
}
}
Note: The "check operation type again" step determines the operation type. If the operation is "INSERT", the network of the inserted fixed address is copied to the L:network variable (${XC:COPY:{L:network}:{E:values{network}}}) and transformed to a Rapid7 range to the L:range variable (${XC:NETWORKTORANGE:{L:network}:{L:range}}). After the range is stored, the template execution jumps to the "insert network" step.
Action Template: Delete an IP Address
{
"operation": "CONDITION",
"name": "remove ip",
"condition": {
"statements": [{
"op": "==",
...
L:a_site{{id}}}})
. If they are not the same, the execution is continued by the "check whether site list is empty
" step.
Action Template: Get Site Configuration
{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteConfigRequest",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteConfigRequest session-id=\"${S::SESSID}\" site-id=\"${L:A:site_id}\"/>"
]
},
{
"operation": "CONDITION",
"name": "send SiteConfigRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${EP:A:event_typePARSE[[name]]}",
"left": "FIXED_ADDRESS_IPV4SiteConfigResponse"
}],
{
"condition_typeop": "AND!=",
"evalright":
"1",
"left": "${XCP:COPYA:PARSE{L:ip}:{E:values{ipv4addr{success}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
],
"condition_type": "OR",
"else_eval":
"${XC:COPY:{L:ipSite}:{EP:valuesPARSE{ipv6addrSiteConfigResponse}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
},
{
",
"error": true
}
}
...
Note: Once site-id
is known, steps "send SiteConfigRequest"
and "send SiteConfigRequest (error check)"
request and store the site configuration.
...
Action Template: Distinguish Between INSERT and DELETE
{
"operation": "CONDITION",
"name": "jump to sendcheck operation type again",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"nexteval": "send SiteSaveRequest"
}
}
NOTES:
...
"${XC:COPY:{L:network}:{E:values{
...
network}}}${XC:
...
NETWORKTORANGE:{L:
...
network}:{L:
...
range
}}
...
Action Template: Add an IP Range
Wiki Markup |
---|
\\
\{
"operation": "VARIABLEOP", "name": "insert network",
\\
\\
!worddav82aac1426f41e4bf41b080762501fdd1.png|height=20,width=11!
1830NIOS Administrator Guide (Rev. A)NIOS 8.1
Sample Templates
\\
\\
"variable_ops": \[\{ "operation": "PUSH",
"type": "COMPOSITE",
"source": "L:range",
"destination": "L:Site\{Site\}\{Hosts\}"
\}\]
\}
\\
The step "insert network" pushes the L:range to the list of site's "Hosts". Action Template: Saving New Configuration
\{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteSaveRequest", "body_list": \[
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>", "<SiteSaveRequest session-id=\"$\{S::SESSID\}\">", "$\{L:x:Site\}",
"</SiteSaveRequest>"
\]
\},
\{
"operation": "CONDITION",
"name": "send SiteSaveRequest (error check)", "condition": \{
"statements": \[
\{
"op": "!=",
"right": "$\{P:A:PARSE\[\[name\]\]\}", "left": "SiteSaveResponse"
\},
\{
"op": "!=",
"right": "1",
"left": "$\{P:A:PARSE\{\{success\}\}\}"
\}
\],
"condition_type": "OR", "error": true
\}
\}
\\
\\
*Note:* The "send SiteSaveRequest" and "send SiteSaveRequest (error check)" steps save new site configuration to the Rapid7 server.
\\
\\
\\ |
Action Template: Add Extensible Attributes Using WAPI
Wiki Markup |
---|
\\
\{
"operation": "CONDITION",
"name": "check operation type once more", "condition": \{
"statements": \[\{
"op": "!=",
"right": "$\{E:A:operation_type\}", "left": "INSERT"
\}\],
"condition_type": "AND", "stop": true
\}
\},
\\
\\
!worddav82aac1426f41e4bf41b080762501fdd1.png|height=20,width=11!
NIOS 8.1NIOS Administrator Guide (Rev. A) 1831
Using the RESTful API for Outbound Notifications
\\
\\
\{
"operation": "PUT",
"name": "add an attribute with WAPI", "transport": \{"path": "$\{E:A:values\{_ref\}\}"\}, "wapi": "v2.6",
"body": "\{\"extattrs+\": \{\"r7_added\": \{\"value\": \"Added to the Rapid7
\\
\\
*NOTES{*}:
$\{UT:A:TIME\}\"\}\}\}"
\} |
- The "check operation type once more" step determines the operation type. If the operation is not
"INSERT" (i.e. "DELETE"), the template execution stops.
- For the "INSERT" operation, the last step "add an attribute with WAPI" is executed. This step adds an extensible attribute "r7_added" to the fixed address through RESTful API. The value of the attribute has the current timestamp (${UT:A:TIME}).
Action Template: Add a Host Record
Wiki Markup |
---|
The following sample template, if assigned to a DHCP network notification rule, will insert a host record for any added network that matches the rule, with a hostname and domain name set by extensible attributes in the network.
Detailed explanations about this sample are included in [<span style="color: #0000ff"><em>Action</em></span> <span style="color: #0000ff"><em>Template</em></span> <span style="color: #0000ff"><em>with</em></span> <span style="color: #0000ff"><em>Comments:</em></span> <span style="color: #0000ff"><em>Add</em></span> <span style="color: #0000ff"><em>a</em></span> <span style="color: #0000ff"><em>Host</em></span> <span style="color: #0000ff"><em>Record</em></span> on page|Sample Templates#bookmark3425] [1833|Sample Templates#bookmark3425].
\{
"version": "1.0",
"name": "Insert host record",
"comment": "Will automatically insert a host record for new network insertions,
assumes the network has a 'Zone' extensible attribute, optionally a 'Hostname' extensible attribute as well",
"type": "REST_EVENT",
"event_type": \[ "NETWORK_IPV4"
\],
"action_type": "Insert a host record", "vendor_identifier": "WAPI 2.3", "transport": \{
"content_type": "application/json",
\},
"steps": \[
\{
"name": "stop if it is not a network insert", "operation": "CONDITION",
"condition": \{ "condition_type": "AND", "statements": \[
\{
"left": "$\{E:A:operation_type\}", "op": "!=",
"right": "INSERT"
\}
\],
"stop": true
\}
\},
\{
"name": "stop if we don't have the zone EA set, else save it", "operation": "CONDITION",
"condition": \{ "condition_type": "AND", "statements": \[
\\
\\
!worddav82aac1426f41e4bf41b080762501fdd1.png|height=20,width=11!
1832NIOS Administrator Guide (Rev. A)NIOS 8.1
Sample Templates
\\
\\
\{
"left": "$\{E:A:values\{extattrs\}\{Zone\}\{value\}\}", "op": "==",
"right": ""
\}
\],
"stop": true,
"else_eval": "$\{XC:COPY:\{L:ZONE\}:\{E:values\{extattrs\}\{Zone\}\{value\}\}\}"
\}
\},
\{
"name": "get the hostname or use a default value", "operation": "CONDITION",
"condition": \{ "condition_type": "AND", "statements": \[
\{
"left": "$\{E:A:values\{extattrs\}\{Hostname\}\{value\}\}", "op": "!=",
"right": ""
\}
\],
"eval": "$\{XC:COPY:\{L:HOSTNAME\}:\{E:values\{extattrs\}\{Hostname\}\{value\}\}\}",
"else_eval": "$\{XC:ASSIGN:\{L:HOSTNAME\}:\{S:defaulthostname\}\}"
\}
\},
\{
"name": "insert the host record with the next available IP", "operation": "POST",
"transport": \{
"path": "record:host"
\},
"body_list": \[
"\{",
"\"name\": \"$\{L:A:HOSTNAME\}.$\{L:A:ZONE\}\",",
"\"ipv4addrs\": \[\{\"ipv4addr\":
\"func:nextavailableip:$\{E:A:values\{network\}\}\"\}\],",
"\"comment\": \"Inserted via outbound\"", "\}"
\]
\}
\]
\}
\\ |
...
",
"next": "insert network"
}
}
...
Note: The "check operation type again
" step determines the operation type. If the operation is "INSERT
", the network of the inserted fixed address is copied to the L:network variable (${XC:COPY:{L:network}:{E:values{network}}}
) and transformed to a Rapid7 range to the L:range variable (${XC:NETWORKTORANGE:{L:network}:{L:range}})
. After the range is stored, the template execution jumps to the "insert network
" step.
...
Action Template: Delete an IP Address
{
"operation": "CONDITION",
"name": "remove ip",
"condition": {
"statements": [{
"op": "==",
"right": "${E:A:event_type}",
"left": "FIXED_ADDRESS_IPV4"
}],
"condition_type": "AND",
"eval":
"${XC:COPY:{L:ip}:{E:values{ipv4addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}",
"else_eval":
"${XC:COPY:{L:ip}:{E:values{ipv6addr}}}${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}}"
}
},
{
"operation": "CONDITION",
"name": "jump to send",
"condition": {
"statements": [{
"op": "==",
"right": "",
"left": ""
}],
"condition_type": "AND",
"next": "send SiteSaveRequest"
}
}
NOTES:
- If the operation is not "
INSERT
" (i.e. "DELETE
"), the "remove ip
" step is executed. The step determines the type of fixed address. The corresponding address ({E:values{ipv4addr}
} or{E:values{ipv6addr}}
) is copied to theL:ip
variable, and then theL:ip
address is removed from the list of hosts in the site(${XC:REMOVEIP:{L:ip}:{L:Site{Hosts}}})
. - The step "
jump to send
" skips the "inserting
" step and jumps directly to the "send SiteSaveRequest
" step.
Action Template: Add an IP Range
{
"operation": "VARIABLEOP",
"name": "insert network",
"variable_ops": [{
"operation": "PUSH",
"type": "COMPOSITE",
"source": "L:range",
"destination": "L:Site{Site}{Hosts}"
}]
}
The step "insert network" pushes the L:range to the list of site’s "Hosts".
Action Template: Saving New Configuration
{
"parse": "XMLA",
"operation": "POST",
"name": "send SiteSaveRequest",
"body_list": [
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
"<SiteSaveRequest session-id=\"${S::SESSID}\">",
"${L:x:Site}",
"</SiteSaveRequest>"
]
},
{
"operation": "CONDITION",
"name": "send SiteSaveRequest (error check)",
"condition": {
"statements": [
{
"op": "!=",
"right": "${P:A:PARSE[[name]]}",
"left": "SiteSaveResponse"
},
{
"op": "!=",
"right": "1",
"left": "${P:A:PARSE{{success}}}"
}
],
"condition_type": "OR",
"error": true
}
}
...
Note: The "send SiteSaveRequest
" and "send SiteSaveRequest (error check)
" steps save new site configuration to the Rapid7 server.
...
Action Template: Add Extensible Attributes Using WAPI
{
"operation": "CONDITION",
"name": "check operation type once more",
"condition": {
"statements": [{
"op": "!=",
"right": "${E:A:operation_type}",
"left": "INSERT"
}],
"condition_type": "AND",
"stop": true
}
},
{
"operation": "PUT",
"name": "add an attribute with WAPI",
"transport": {"path": "${E:A:values{_ref}}"},
"wapi": "v2.6",
"body": "{\"extattrs+\": {\"r7_added\": {\"value\": \"Added to the Rapid7 ${UT:A:TIME}\"}}}"
}
NOTES:
- The "
check operation type once more
" step determines the operation type. If the operation is not "INSERT
" (i.e. "DELETE
"), the template execution stops. - For the "
INSERT
" operation, the last step "add an attribute with WAPI
" is executed. This step adds an extensible attribute "r7_added
" to the fixed address through RESTful API. The value of the attribute has the current timestamp (${UT:A:TIME}
).
Action Template: Add a Host Record
The following sample template, if assigned to a DHCP network notification rule, will insert a host record for any added network that matches the rule, with a hostname and domain name set by extensible attributes in the network. Detailed explanations about this sample are included in Action Template with Comments: Add a Host Record.
{
"version": "1.0",
"name": "Insert host record",
"comment": "Will automatically insert a host record for new network insertions, assumes the network has a 'Zone' extensible attribute, optionally a 'Hostname' extensible attribute as well",
"type": "REST_EVENT",
"event_type": [
"NETWORK_IPV4"
],
"action_type": "Insert a host record",
"vendor_identifier": "WAPI 2.3",
"transport": {
"content_type": "application/json",
},
"steps":
[
{
"name": "stop if it is not a network insert",
"operation": "CONDITION",
"condition": {
"condition_type": "AND",
"statements": [
{
"left": "${E:A:operation_type}",
"op": "!=",
"right": "INSERT"
}
],
"stop": true
}
},
{
"name": "stop if we don't have the zone EA set, else save it",
"operation": "CONDITION",
"condition": {
"condition_type": "AND",
"statements": [
{
"left": "${E:A:values{extattrs}{Zone}{value}}",
"op": "==",
"right": ""
}
],
"stop": true,
"else_eval": "${XC:COPY:{L:ZONE}:{E:values{extattrs}{Zone}{value}}}"
}
},
{
"name": "get the hostname or use a default value",
"operation": "CONDITION",
"condition": {
"condition_type": "AND",
"statements": [
{
"left": "${E:A:values{extattrs}{Hostname}{value}}",
"op": "!=",
"right": ""
}
],
"eval":
"${XC:COPY:{L:HOSTNAME}:{E:values{extattrs}{Hostname}{value}}}",
"else_eval": "${XC:ASSIGN:{L:HOSTNAME}:{S:defaulthostname}}"
}
},
{
"name": "insert the host record with the next available IP",
"operation": "POST",
"transport": {
"path": "record:host"
},
"body_list": [
"{",
"\"name\": \"${L:A:HOSTNAME}.${L:A:ZONE}\",",
"\"ipv4addrs\": [{\"ipv4addr\":
\"func:nextavailableip:${E:A:values{network}}\"}],",
"\"comment\": \"Inserted via outbound\"",
"}"
]
}
]
}
Anchor | ||||
---|---|---|---|---|
|
The comments (labeled as Note:) embedded in the sample template explain the operation for each section of the template.
Note that the execution of this sample template will cause a single POST request to be sent with the following body for an insertion of a 10.0.0.0/24 network with the Zone extensible attribute set to test.com and the Hostname extensible attribute set to name
:
{"name": "name.test.com","ipv4addrs": [{"ipv4addr":
"func:nextavailableip:10.0.0.0/24"}],"comment": "Inserted via a template"}
...
Note: The preamble of the template specifies the version, version, name and other relevant fields.
...
{
"version": "1.0",
"name": "Insert host record",
"comment": "Will automatically insert a host record for new network insertions,assumes the network has a 'Zone' extensible attribute, optionally a 'Hostname' extensible attribute as well",
"type": "REST_EVENT",
...
Note: The event_type
field specifies that this template is used for IPv4 network events only.
...
"event_type": [
"NETWORK_IPV4"
],
...
Note: The action_type
and vendor_identifier
fields describe the template type and the vendor type.
...
"action_type": "Insert a host record",
"vendor_identifier": "WAPI 2.3",
...
Note: The following specifies that the template is going to send JSON to the server.
...
"transport": {
"content_type": "application/json",
},
...
Note: The following are steps that will be executed sequentially.
...
"steps":
[
...
Note: The first step will stop the execution, without an error, if the network event received is not an insertion – it could be a modify, for example.
...
{
"name": "stop if it is not a network insert",
"operation": "CONDITION",
"condition": {
...
Note: You can only one statement: either AND or OR would work.
...
"condition_type": "AND",
"statements": [
...
Note: The match is to check if operation_type
in the event is different from INSERT. It is a good practice to put the event variable on the left side so if it is not present in the event, the template would not fail.
...
{
"left": "${E:A:operation_type}",
"op": "!=",
"right": "INSERT"
}
],
...
Note: The directive that stops the execution if the condition matches.
...
"stop": true
}
},
...
Note: The second step will stop the execution if the inserted network does not have the Zone extensible attribute configured. If it has the extensible attribute, it will be put in a temporary local variable for easier access later on.
...
{
"name": "stop if we don't have the zone EA set, else save it",
"operation": "CONDITION",
"condition": {
...
Note: Similar to the previous section, we have only one statement, so either AND or OR would work. The condition ensures that the Zone extensible attribute is set to a value.
...
"condition_type": "AND",
"statements": [
{
...
Note: As previously mentioned, non-existent variable access in the left side of a condition will not cause an error, but instead return an empty value.
...
"left": "${E:A:values{extattrs}{Zone}{value}}",
"op": "==",
"right": ""
}
],
...
Note: If the extensible attribute is empty or nonexistent, the operation should stop here.
...
"stop": true,
...
Note: Otherwise, it will copy the zone value to the local ZONE variable.
...
"else_eval": "${XC:COPY:{L:ZONE}:{E:values{extattrs}{Zone}{value}}}"
}
},
...
Note: This step is similar to the zone step above. However, if the host name is not set, it will put a default host name in a local variable to provide the default.
...
{
"name": "get the hostname or use a default value",
"operation": "CONDITION",
"condition": {
"condition_type": "AND",
"statements": [
{
"left": "${E:A:values{extattrs}{Hostname}{value}}",
"op": "!=",
"right": ""
}
],
...
Note: This is executed if the extensible attribute is present, by copying its value to HOSTNAME.
...
"eval": "${XC:COPY:{L:HOSTNAME}:{E:values{extattrs}{Hostname}{value}}}",
...
Note: Otherwise, the following is executed if the extensible attribute is empty or not present, by assigning the defaulthostname
string instead.
...
"else_eval": "${XC:ASSIGN:{L:HOSTNAME}:{S:defaulthostname}}"
}
},
...
Note: This step will finally contact the endpoint and in this case insert the host.
...
{
"name": "insert the host record with the next available IP",
...
Note: This defines the HTTP operation to use.
...
"operation": "POST",
...
Note: The endpoint is configured starting with https://master_ip/.... The endpoint template overrides the path with /wapi/v2.3/ so by default all template requests would go to https://master_ip/wapi/v2.3/. In this step, we want to insert a host, so record:host
is appended to the URI above (no override is set here) to arrive to the valid RESTful URI https://master_ip/wapi/v2.3/record:host.
...
"transport": {
"path": "record:host"
},
...
Note: This is the text that will be sent to the server in the POST’s BODY.
...
"body_list": [
"{",
...
Note: This references the local variables that were previously assigned.
...
"\"name\": \"${L:A:HOSTNAME}.${L:A:ZONE}\",",
...
Note: This option signifies that the RESTful API will use the next available IP in the network as the address for this host.
...
"\"ipv4addrs\": [{\"ipv4addr\":
\"func:nextavailableip:${E:A:values{network}}\"}],",
...
Note: This is the comment stating that the action is done through the RESTful API template.
...
"\"comment\": \"Inserted via outbound\"",
"}"
]
}
]
}