DDoS Events

Get DDoS Events

This API is very useful and can be leveraged to obtain alert in near real-time. Furthermore, this API also can be used to obtain history attack events.

URL

https://api.ddosmon.net/open/event/ddos

Request

  • Method: GET

Parameters

Three parameters can be combined to meet different needs.

Name Types Required Description Example
last number false Last N days events, default 30 days ?last=7
start date-time false Return events after this time ?start=2017-03-30 00:00:00
end date-time false Return events befor this time ?end=2017-03-30 01:00:00
  • last
    must be 1 <= last <= 365
  • start, end support multiple date-time formation:
* 2017-03-30
* 2017-03-30 00:00:00 (timezone be UTC)
* 2017-03-30T00:00:00+00:00

Full Example

curl -i -X GET  \
     -H "X-NISS-AuthToken:13f9c3c0-ea2b-403b-ba47-599f2a8fdf08"  \
     -H "X-NISS-AuthEmail:example@example.com"  \
     https://api.ddosmon.net/open/event/ddos/?start=2017-03-30 00:00:00&end=2017-03-30 01:00:00

How obtain alert in near real-time?

You can request this API per five minutes and set start be ten minutes ago. In this approach, you need to pay attention that sequence twice request may return the same event and you need handle this situation in your case.

Response

{
  "data": [
    {
      "_id": "5821a46ae5e0f1bea7534b72",
      "cts": "2017-03-08T10:09:18+00:00",
      "curavg_bps": 1651,
      "curavg_flows": 24,
      "curavg_pps": 24,
      "deviate": 24,
      "domain": "",
      "ip": "1.1.1.1",
      "site": "1.1.1.0/24"
    },
    {
      "_id": "58b01347e5e0f17de68a55c3",
      "attack_type": "tcp@attack@syn_flood_target",
      "cts": "2017-03-24T11:04:38+00:00",
      "curavg_bps": 1434,
      "curavg_flows": 16,
      "curavg_pps": 16,
      "deviate": 16,
      "domain": "www.example.com",
      "ip": "2.2.2.2",
      "site": "*.example.com"
    }
  ]
}

The response field:

Field Description
_id The unique event ID, will be used in get-attack-details API
cts Event be detcted time
curavg_bps Bytes per minute
curavg_flows Flows per minute
curavg_pps Packets per minute
deviate Spike deviation during attack happend compared with pacific traffic
ip Victim IP
domain Host name resolving to victim ip during attack happen
site The monitoring object that matched with victim IP
attack_type Attack vector, this field maybe null. If attack_type be null means anomaly traffic spike be detected however unknown attack type

Get Attack Details

URL

https://api.ddosmon.net/open/event/ddos/detail/<_id>

Request

  • Method: GET

_id is specified event id that returned from previous API get-ddos-events list. If _id is invalid, will return a empty list.

{
  "data": {}
}

Full Example

curl -i -X GET \
     -H "X-NISS-AuthToken:13f9c3c0-ea2b-403b-ba47-599f2a8fdf08"  \
     -H "X-NISS-AuthEmail:example@example.com"  \
     https://api.ddosmon.net/open/event/ddos/detail/5821a46ae5e0f1bea7534b72

Response

{
  "data": {
    "_id": "5821a46ae5e0f1bea7534b72",
    "cts": "2016-11-08T10:09:18+00:00",
    "curavg_bps": 1651,
    "curavg_flows": 24,
    "curavg_pps": 24,
    "dac": [
      {
        "a": {
          "1.1.1.1": "2016-11-03T07:34:46+00:00"
        },
        "cname": {},
        "domain": "hn4-store2.lol.qq.com"
      },
      {
        "a": {
          "1.1.1.1": "2016-11-07T16:03:41+00:00"
        },
        "cname": {
          "es3.pengyou.qq.com": "2016-11-07T16:14:56+00:00"
        },
        "domain": "es3.pengyou.com"
      },
      {
        "a": {
          "1.1.1.1": "2016-11-07T16:15:00+00:00"
        },
        "cname": {},
        "domain": "adver.pengyou.com"
      }
    ],
    "deviate": 24,
    "domain": "",
    "dstport": [
      {
        "Bytes": 1494,
        "Flows": 23,
        "Item": 80,
        "Packets": 23,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 157,
        "Flows": 1,
        "Item": 8000,
        "Packets": 1,
        "Prots": {
          "17": {}
        }
      }
    ],
    "flags": [
      {
        "Bytes": 1494,
        "Flows": 23,
        "Item": 2,
        "Packets": 23,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 157,
        "Flows": 1,
        "Item": 0,
        "Packets": 1,
        "Prots": {
          "17": {}
        }
      }
    ],
    "ip": "1.1.1.1",
    "proto": [
      {
        "Bytes": 1494,
        "Flows": 23,
        "Item": 6,
        "Packets": 23,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 157,
        "Flows": 1,
        "Item": 17,
        "Packets": 1,
        "Prots": {
          "17": {}
        }
      }
    ],
    "site": "1.1.1.0/24",
    "srcport": [
      {
        "Bytes": 56,
        "Flows": 1,
        "Item": 51313,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 62,
        "Flows": 1,
        "Item": 31338,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 49288,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 38455,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 13465,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 40151,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 65046,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 66,
        "Flows": 1,
        "Item": 30718,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      },
      {
        "Bytes": 157,
        "Flows": 1,
        "Item": 16664,
        "Packets": 1,
        "Prots": {
          "17": {}
        }
      },
      {
        "Bytes": 56,
        "Flows": 1,
        "Item": 58847,
        "Packets": 1,
        "Prots": {
          "6": {}
        }
      }
    ]
  }
}

This API return attack details and various kind traffic statistics such as top ip , port, protocol, tcp flags and so on.

Some fields has been explained at previous get-ddos-events API, and will be omitted at here.

  • dac
    The DNS snapshort against victim IP. In this case, the victim IP is 1.1.1.1
{
    "a": {
      "1.1.1.1": "2016-11-07T16:03:41+00:00"
    },
    "cname": {
      "es3.pengyou.qq.com": "2016-11-07T16:14:56+00:00"
    },
    "domain": "es3.pengyou.com"
},
es3.pengyou.com CNAME es3.pengyou.qq.com
es3.pengyou.qq.com A 1.1.1.1
  • dstport
    Traffic statistic as destination port, the Item field is the port number.
  • srcport
    Traffic statistic as source port, the Item field is the port number.
  • srcip
    Traffic statistic as source ip, the Item field is the source IP, you need convert from int network address to readable dotted-decimal IP address
  • proto
    Traffic statistic as destination protocol, the Item field is the protocol number, such as 6 means TCP, 17 means UDP.
  • flags
    Traffic statistic as tcp flags, the Item field is the tcp flag, you need convert tcp flags from decimal number to readalbe character. Here is a demo script written in Python
    TCP_FLAGS = {
    'F': 0x01,   #FIN
    'S': 0x02,   #SYN
    'R': 0x04,   #RST
    'P': 0x08,   #PSH
    'A': 0x10,   #ACK
    'U': 0x20,   #URG
    'E': 0x40,   #ECE
    'C': 0x80,   #CWR
}

def flags2Str(flags):

    flags = int(flags)
    fs = [k for k, v in TCP_FLAGS.items() if v & flags]
    fs = [s if s in fs else '.' for s in TCP_FLAGS_SLOT]
    return "".join(fs)

Note: all these statistics data can sort as Flows field, bigger number means higher rate.