Threat Level: green Handler on Duty: Kevin Liston

SANS ISC DShield API


Sign Up for Free!   Forgot Password?
Log In or Sign Up for Free!

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

API Calls

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/daily404summary/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>

openiocsources

Returns firewall logs in OpenIOC format.
Parameters: Date, Records (Max: 1000), Page (For iterating beyond 1000 records)

  • Date: Y-m-d format of the day in which you wish to obtain firewall logs. Default is today's date.
  • Records: Number of firewall logs to be returned. Maximum of 1000 per request. Default is 100.
  • Page Page of records to be returned for Date, for iterating beyond 1000 record maximum per request. Default is 0.

For example, to obtain firewall logs 1000 through 2000 on 2014-08-01, send a request to http://isc.sans.edu/api/openiocsources/2014-08-01/1000/1.

Here is a simple example of the expected output:

http://isc.sans.edu/api/openiocsources/2014-08-01/1/0

<?xml version="1.0" encoding="UTF-8"?>
<ioc xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" id="44233BFE-2014-0821-3be61964f8a0" last-modified="2014-08-21T18:18:02Z" xmlns="http://schemas.mandiant.com/2010/ioc">
 <short_description>Firewall Logs</short_description>
 <description>Firewall logs from 2014-08-01</description>
 <authored_by>SANS Internet Storm Center</authored_by>
 <authored_date>2014-08-21T18:18:02Z</authored_date>
 <links />
 <definition>
  <Indicator operator="OR" id="44233BFE-2014-0821-3be61964f8a0">
   <Indicator operator="OR" id="44233BFE-2014-0821-1f0e79e965d2">
    <IndicatorItem id="44233BFE-2014-0821-75150a133199" condition="is">
     <Context document="PortItem" search="PortItem/CreationTime" type="mir" />
     <Content type="date">2014-08-01T00:00:00Z</Content>
    </IndicatorItem>
    <IndicatorItem id="44233BFE-2014-0821-08776eb79936" condition="is">
     <Context document="PortItem" search="PortItem/remoteIP" type="mir" />
     <Content type="IP">212.034.154.164</Content>
    </IndicatorItem>
    <IndicatorItem id="44233BFE-2014-0821-2449d037028d" condition="is">
     <Context document="PortItem" search="PortItem/localPort" type="mir" />
     <Content type="int">80</Content>
    </IndicatorItem>
    <IndicatorItem id="44233BFE-2014-0821-c4fca0bb8767" condition="is">
     <Context document="PortItem" search="PortItem/remotePort" type="mir" />
     <Content type="int">47783</Content>
    </IndicatorItem>
   </Indicator>
  </Indicator>
 </definition>
</ioc>