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)