DShield documentation

A Pythonic interface to the Internet Storm Center / DShield API.

Return Format

Just like the DShield API itself, all functions in this library are able to return data in a variety of formats. By default, the library will convert data returned from the API to a native object, either a dict or a list depending on the function. You can change this behavior by specifying the return_format when calling a function. Valid values for the return_format parameter are: dshield.XML, dshield.JSON, dshield.TEXT, and dshield.PHP. When any of these formats are used, the function will return a string containing the raw data from the API.

To give a simple example:

>>> import dshield
>>> dshield.infocon()
{'status': 'green'}
>>> dshield.infocon(dshield.JSON)
'{"status":"green"}'

Functions

The docstrings for these functions are for the most part taken directly from the official API documentation.

dshield.backscatter(date=None, rows=None, return_format=None)

Returns possible backscatter data.

This report only includes “syn ack” data and is summarized by source port.

Parameters:
  • date – optional string (in Y-M-D format) or datetime.date() object
  • rows – optional number of rows returned (default 1000)
Returns:

list – backscatter data.
dshield.handler(return_format=None)

Returns the name of the handler of the day.

dshield.infocon(return_format=None)

Returns the current infocon level (green, yellow, orange, red).

dshield.ip(ip_address, return_format=None)

Returns a summary of the information our database holds for a particular IP address (similar to /ipinfo.html).

In the returned data:

Count: (also reports or records) total number of packets blocked from this IP. Attacks: (also targets) number of unique destination IP addresses for these packets.

Parameters:ip_address – a valid IP address
dshield.port(port_number, return_format=None)

Summary information about a particular port.

In the returned data:

Records: Total number of records for a given date. Targets: Number of unique destination IP addresses. Sources: Number of unique originating IPs.

Parameters:port_number – a string or integer port number
dshield.portdate(port_number, date=None, return_format=None)

Information about a particular port at a particular date.

If the date is ommited, today’s date is used.

Parameters:
  • port_number – a string or integer port number
  • date – an optional string in ‘Y-M-D’ format or datetime.date() object
dshield.topports(sort_by=None, limit=None, date=None, return_format=None)

Information about top ports for a particular date with return limit.

Parameters:
  • sort_by – one of ‘records’, ‘targets’, ‘sources’
  • limit – number of records to be returned
  • date – an optional string in ‘Y-M-D’ format or datetime.date() object
dshield.topips(sort_by=None, limit=None, date=None, return_format=None)

Information about top ports for a particular date with return limit.

Parameters:
  • sort_by – one of ‘records’, ‘attacks’
  • limit – number of records to be returned
  • date – an optional string in ‘Y-M-D’ format or datetime.date() object
dshield.sources(sort_by=None, limit=None, date=None, return_format=None)

Information summary from the last 30 days about source IPs with return limit.

Parameters:
  • sort_by – one of ‘ip’, ‘count’, ‘attacks’, ‘firstseen’, ‘lastseen’
  • limit – number of records to be returned (max 10000)
  • date – an optional string in ‘Y-M-D’ format or datetime.date() object
dshield.porthistory(port_number, start_date=None, end_date=None, return_format=None)

Returns port data for a range of dates.

In the return data:

Records: Total number of records for a given date range. Targets: Number of unique destination IP addresses. Sources: Number of unique originating IPs.

Parameters:
  • port_number – a valid port number (required)
  • start_date – string or datetime.date(), default is 30 days ago
  • end_date – string or datetime.date(), default is today
dshield.asnum(number, limit=None, return_format=None)

Returns a summary of the information our database holds for a particular ASNUM (similar to /asdetailsascii.html) with return limit.

Parameters:limit – number of records to be returned (max 2000)
dshield.dailysummary(start_date=None, end_date=None, return_format=None)

Returns daily summary totals of targets, attacks and sources. Limit to 30 days at a time. (Query 2002-01-01 to present)

In the return data:

Sources: Distinct source IP addresses the packets originate from. Targets: Distinct target IP addresses the packets were sent to. Reports: Number of packets reported.

Parameters:
  • start_date – string or datetime.date(), default is today
  • end_date – string or datetime.date(), default is today
dshield.daily404summary(date, return_format=None)

Returns daily summary information of submitted 404 Error Page Information.

Parameters:date – string or datetime.date() (required)
dshield.daily404detail(date, limit=None, return_format=None)

Returns detail information of submitted 404 Error Page Information.

Parameters:
  • date – string or datetime.date() (required)
  • limit – string or int, limit for number of returned items
dshield.glossary(term=None, return_format=None)

List of glossary terms and definitions.

Parameters:term – a whole or parital word to “search” in the API
dshield.webhoneypotsummary(date, return_format=None)

API data for Webhoneypot: Web Server Log Project.

Parameters:date – string or datetime.date() (required)
dshield.webhoneypotbytype(date, return_format=None)

API data for Webhoneypot: Attack By Type. We currently use a set of regular expressions to determine the type of attack used to attack the honeypot. Output is the top 30 attacks for the last month.

Parameters:date – string or datetime.date() (required)

Exceptions

class dshield.Error

Custom exception class.

Indices and tables