DShield API

Internet Storm Center / DShield API

We are using a simple REST API. The following functions are available:

Note: Output formats include xml (default), json, text and php. Just add on to the url as a parameter such as http://isc.sans.edu/api/handler?text

backscatter

Returns possible backscatter data. This report only includes "syn ack" data and is summarized by source port
Parameters: Date (in Y-M-D format), optional: number of rows returned (default 1000)

http://isc.sans.edu/api/backscatter/2011-12-01/10

<?xml version="1.0" encoding="UTF-8"?>
<backscatter>
 <sourceport> 6000 </sourceport>
 <count> 563542 </count>
 <sources> 518 </sources>
 <targets> 94654 </targets>
 </sourceport>
...
</backscatter>

handler

Returns the name of the handler of the day
No Parameters

http://isc.sans.edu/api/handler

<?xml version="1.0" encoding="UTF-8"?>
<handler>
 <name>Chris Mohan<name>
</handler>

infocon

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

http://isc.sans.edu/api/infocon

<?xml version="1.0" encoding="UTF-8"?>
<infocon>
 <status>green</status>
</infocon>

ip

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

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

http://isc.sans.edu/api/ip/70.91.145.10

<?xml version="1.0" encoding="UTF-8"?>
<ip>
 <number>70.91.145.10</number>
 <count>159</count>
 <attacks>5</attacks>
 <maxdate>2011-09-12</maxdate>
 <mindate>2011-03-09</mindate>
 <updated>2011-09-12 14:51:16</updated>
 <country>US</country>
 <as>33489</as>
 <asname>Some Internet Service Provider</asname>
 <network>70.91.144.0/21</network>
 <comment>some user provided comment</comment>
</ip>

port

Summary information about a particular port
Parameters: Port Number

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

http://isc.sans.edu/api/port/80

<?xml version="1.0" encoding="UTF-8"?>
<port>
 <number>80</number>
 <data>
  <date>2011-08-03</date>
  <records>183473</records>
  <targets>29763</targets>
  <sources>7565</sources>
  <tcp>152255</tcp>
  <udp>151</udp>
  <datein>2011-08-03</datein>
  <portin>80</portin>
 </data>
 <services>
  <udp>
   <service>www</service>
   <name>World Wide Web HTTP</name>
  </udp>
  <tcp>
   <service>www</service>
   <name>World Wide Web HTTP</name>
  </tcp>
 </services>
</port>

portdate

Information about a particular port at a particular date.
Paramters: Portnumber and Date. If the date is ommited, today's date is used.

http://isc.sans.edu/api/portdate/80/2011-07-23

<?xml version="1.0" encoding="UTF-8"?>
<portdate>
 <number>80</number>
 <data>
  <date>2011-07-23</date>
  <records>357466</records>
  <targets>22901</targets>
  <sources>10084</sources>
  <tcp>332172</tcp>
  <udp>233</udp>
  <datein>2011-07-23</datein>
  <portin>80</portin>
 </data>
</portdate>

topports

Information about top ports for a particular date with return limit.
Parameters: column to sort by (options: records, targets, sources), number of records to be returned and the date.

http://isc.sans.edu/api/topports/records/10/2011-07-23

<?xml version="1.0" encoding="UTF-8"?>
<topports>
 <port>
  <rank>1</rank>
  <targetport>445</targetport>
  <records>601032</records>
  <targets>77374</targets>
  <sources>70889</sources>
 </port>
...
</topports>

topips

Information about top IPs for a particular date with return limit.
Parameters: column to sort by (options: records, attacks), number of records to be returned and date.

http://isc.sans.edu/api/topips/records/10/2011-07-23

<?xml version="1.0" encoding="UTF-8"?>
<topips>
 <ipaddress>
  <rank>1</rank>
  <source>071.002.215.038</source>
  <reports>235744</reports>
  <targets>659</targets>
 </ipaddress>
...
<topips>

sources

Information summary from the last 30 days about source IPs with return limit.
Parameters: column to sort by (options: ip, count, attacks, firstseen, lastseen), number of records to be returned (max:10000) and date (limits to firstseen/lastseen if sorted by these).

http://isc.sans.edu/api/sources/attacks/100/2012-03-08

<?xml version="1.0" encoding="UTF-8"?>
<sources>
 <data>
  <ip> 202.121.166.203 </ip>
  <attacks> 109314 </attacks>
  <count> 199219 </count>
  <firstseen> 2011-11-04 </firstseen>
  <lastseen> 2012-03-09 </lastseen>
 </data>
...
<sources>

porthistory

Returns port data for a range of dates
Parameters: port number, start date and end date. Default start date is 30 days ago and the default end date is today. The port is required.

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

http://isc.sans.edu/api/porthistory/80/2011-07-20/2011-07-23

<porthistory>
 <portinfo>
  <date>2011-01-20</date>
  <records>378520</records>
  <targets>33664</targets>
  <sources>15460</sources>
  <tcp>309213</tcp>
  <udp>722</udp>
 </portinfo>
...
 <portinfo>
  <date>2011-01-23</date>
  <records>357466</records>
  <targets>22901</targets>
  <sources>10084</sources>
  <tcp>332172</tcp>
  <udp>233</udp>
 </portinfo>
 <startdate>2011-07-20</startdate>
 <enddate>2011-07-23</enddate>
 <port>80</port>
</porthistory>

asnum

Returns a summary of the information our database holds for a particular ASNUM (similar to /asdetailsascii.html) with return limit.
Parameters: asnum, number of records to be returned (max:2000)

http://isc.sans.edu/api/asnum/10/4837

<?xml version="1.0" encoding="UTF-8"?>
<asnum>
 <data>
  <number>4837</number>
  <ip>221.192.003.231</ip>
  <reports>3</reports>
  <targets>3<targets>
  <firstseen>2010-01-12</maxdate>
  <lastseen>2012-01-23</mindate>
  <updated>2012-01-23 03:18:02</updated>
 </data>
...
 <data>
  <number>4837</number>
  <ip>221.010.175.094</ip>
  <reports>5,008</reports>
  <targets>4,307<targets>
  <firstseen></maxdate>
  <lastseen>2012-01-13</mindate>
  <updated>2012-01-21 05:56:28</updated>
 </data>
</asnum>

dailysummary

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

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

http://isc.sans.edu/api/dailysummary/2012-05-01/2012-05-03

<?xml version="1.0" encoding="UTF-8"?>
<dailysummary>
 <daily>
  <date> 2012-05-01 </date>
  <sources> 429855 </sources>
  <targets> 173302 </targets>
  <reports> 13513903 </reports>
 </daily>
...
 <daily>
  <date> 2012-05-03 </date>
  <sources> 474285 </sources>
  <targets> 157945 </targets>
  <reports> 9872377 </reports>
 </daily>
</dailysummary>

404Project Daily Summary

Returns daily summary information of submitted 404 Error Page Information.
Parameters: date

http://isc.sans.edu/api/daily404/2012-02-23

<?xml version="1.0" encoding="UTF-8"?>
<daily404summary>
  <date> 2012-02-23 </date>
  <authors> 26 </authors>
  <urls> 3673 </urls>
  <user_agents> 886 <user_agents>
  <sources> 2316</sources>
  <reports> 14406 </reports>
</daily404summary>

404Project Details

Returns detail information of submitted 404 Error Page Information.
Parameters: date, limit

http://isc.sans.edu/api/daily404detail/2012-02-23/10

<?xml version="1.0" encoding="UTF-8"?>
<daily404detail>
 <data>
  <url> /robots.txt </url>
  <user_agent> Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm) </user_agent>
  <source> 207.46.13.147 </source>
 <data>
...
</daily404detail>

glossary

List of glossary terms and definitions
Alternatively, append a whole or parital word to "search" in API - http://isc.sans.edu/api/glossary/data

http://isc.sans.edu/api/glossary

<?xml version="1.0" encoding="UTF-8"?>
<glossary>
 <item>
  <term> 3-WAY HANDSHAKE </date>
  <definition> Machine A sends a packet with a SYN flag set to Machine B. B acknowledges A's SYN with a SYN/ACK. A acknowledges B's SYN/ACK with an ACK. </records>
 </item>
 ...
</glossary>

webhoneypotsummary

API data for Webhoneypot: Web Server Log Project.
Parameters: date

http://isc.sans.edu/api/webhoneypotsummary/2012-12-10

<?xml version="1.0" encoding="UTF-8"?>
<webhoneypotsummary>
  <day> 2012-12-10 </day>
  <reports> 17 </reports>
  <authors> 2 </authors>
  <targets> 2 </targets>
  <sources> 4 </sources>
</webhoneypotsummary>

webhoneypotbytype

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.

http://isc.sans.edu/api/webhoneypotbytype

<?xml version="1.0" encoding="UTF-8"?>
<webhoneypotbytype>
 <item>
  <reports> 278 </reports>
  <type> Generic index.php RFI </type>
  <cve>  </cve>
 </item>
 ...
 <item>
  <reports> 127 </reports>
  <type> Falcon Series One errors.php RFI </type>
  <cve> 20076488  </cve>
 </item>
</webhoneypotsummary>