Class: PassiveTotal::API

Inherits:
Object
  • Object
show all
Defined in:
lib/passivetotal/api.rb

Overview

The API class wraps the PassiveTotal.org web API for all the verbs that it supports See www.passivetotal.org/api/docs for the API documentation.

Constant Summary collapse

TLDS =

The TLDS array helps the interface detect valid domains. This list was generated by parsing the NS records from a zone transfer of the root The same list could have been downloaded from data.iana.org/TLD/tlds-alpha-by-domain.txt

"abb,abbott,abogado,ac,academy,accenture,accountant,accountants,active,actor,ad,ads,adult,ae,aeg,aero,af,afl,ag,agency,ai,aig,airforce,al,allfinanz,alsace,am,amsterdam,an,android,ao,apartments,aq,aquarelle,ar,archi,army,arpa,as,asia,associates,at,attorney,au,auction,audio,auto,autos,aw,ax,axa,az,azure,ba,band,bank,bar,barclaycard,barclays,bargains,bauhaus,bayern,bb,bbc,bbva,bd,be,beer,berlin,best,bf,bg,bh,bharti,bi,bible,bid,bike,bing,bingo,bio,biz,bj,black,blackfriday,bloomberg,blue,bm,bmw,bn,bnl,bnpparibas,bo,boats,bond,boo,boutique,br,bradesco,bridgestone,broker,brother,brussels,bs,bt,budapest,build,builders,business,buzz,bv,bw,by,bz,bzh,ca,cab,cafe,cal,camera,camp,cancerresearch,canon,capetown,capital,caravan,cards,care,career,careers,cars,cartier,casa,cash,casino,cat,catering,cba,cbn,cc,cd,center,ceo,cern,cf,cfa,cfd,cg,ch,channel,chat,cheap,chloe,christmas,chrome,church,ci,cisco,citic,city,ck,cl,claims,cleaning,click,clinic,clothing,cloud,club,cm,cn,co,coach,codes,coffee,college,cologne,com,commbank,community,company,computer,condos,construction,consulting,contractors,cooking,cool,coop,corsica,country,coupons,courses,cr,credit,creditcard,cricket,crown,crs,cruises,cu,cuisinella,cv,cw,cx,cy,cymru,cyou,cz,dabur,dad,dance,date,dating,datsun,day,dclk,de,deals,degree,delivery,democrat,dental,dentist,desi,design,dev,diamonds,diet,digital,direct,directory,discount,dj,dk,dm,dnp,do,docs,dog,doha,domains,doosan,download,drive,durban,dvag,dz,earth,eat,ec,edu,education,ee,eg,email,emerck,energy,engineer,engineering,enterprises,epson,equipment,er,erni,es,esq,estate,et,eu,eurovision,eus,events,everbank,exchange,expert,exposed,express,fail,faith,fan,fans,farm,fashion,feedback,fi,film,finance,financial,firmdale,fish,fishing,fit,fitness,fj,fk,flights,florist,flowers,flsmidth,fly,fm,fo,foo,football,forex,forsale,foundation,fr,frl,frogans,fund,furniture,futbol,fyi,ga,gal,gallery,garden,gb,gbiz,gd,gdn,ge,gent,genting,gf,gg,ggee,gh,gi,gift,gifts,gives,gl,glass,gle,global,globo,gm,gmail,gmo,gmx,gn,gold,goldpoint,golf,goo,goog,google,gop,gov,gp,gq,gr,graphics,gratis,green,gripe,gs,gt,gu,guge,guide,guitars,guru,gw,gy,hamburg,hangout,haus,healthcare,help,here,hermes,hiphop,hitachi,hiv,hk,hm,hn,hockey,holdings,holiday,homedepot,homes,honda,horse,host,hosting,hoteles,hotmail,house,how,hr,ht,hu,ibm,icbc,icu,id,ie,ifm,il,im,immo,immobilien,in,industries,infiniti,info,ing,ink,institute,insure,int,international,investments,io,iq,ir,irish,is,it,iwc,java,jcb,je,jetzt,jewelry,jlc,jll,jm,jo,jobs,joburg,jp,juegos,kaufen,kddi,ke,kg,kh,ki,kim,kitchen,kiwi,km,kn,koeln,komatsu,kp,kr,krd,kred,kw,ky,kyoto,kz,la,lacaixa,land,lasalle,lat,latrobe,law,lawyer,lb,lc,lds,lease,leclerc,legal,lgbt,li,liaison,lidl,life,lighting,limited,limo,link,lk,loan,loans,lol,london,lotte,lotto,love,lr,ls,lt,ltda,lu,lupin,luxe,luxury,lv,ly,ma,madrid,maif,maison,management,mango,market,marketing,markets,marriott,mba,mc,md,me,media,meet,melbourne,meme,memorial,men,menu,mg,mh,miami,microsoft,mil,mini,mk,ml,mm,mma,mn,mo,mobi,moda,moe,monash,money,montblanc,mormon,mortgage,moscow,motorcycles,mov,movie,movistar,mp,mq,mr,ms,mt,mtn,mtpc,mu,museum,mv,mw,mx,my,mz,na,nadex,nagoya,name,navy,nc,ne,nec,net,netbank,network,neustar,new,news,nexus,nf,ng,ngo,nhk,ni,nico,ninja,nissan,nl,no,np,nr,nra,nrw,ntt,nu,nyc,nz,office,okinawa,om,omega,one,ong,onl,online,ooo,oracle,org,organic,osaka,otsuka,ovh,pa,page,panerai,paris,partners,parts,party,pe,pf,pg,ph,pharmacy,philips,photo,photography,photos,physio,piaget,pics,pictet,pictures,pink,pizza,pk,pl,place,play,plumbing,plus,pm,pn,pohl,poker,porn,post,pr,praxi,press,pro,prod,productions,prof,properties,property,ps,pt,pub,pw,py,qa,qpon,quebec,racing,re,realtor,recipes,red,redstone,rehab,reise,reisen,reit,ren,rent,rentals,repair,report,republican,rest,restaurant,review,reviews,rich,ricoh,rio,rip,ro,rocks,rodeo,rs,rsvp,ru,ruhr,run,rw,ryukyu,sa,saarland,sale,samsung,sandvik,sandvikcoromant,sap,sarl,saxo,sb,sc,sca,scb,schmidt,scholarships,school,schule,schwarz,science,scor,scot,sd,se,seat,sener,services,sew,sex,sexy,sg,sh,shiksha,shoes,show,shriram,si,singles,site,sj,sk,ski,sky,skype,sl,sm,sn,sncf,so,soccer,social,software,sohu,solar,solutions,sony,soy,space,spiegel,spreadbetting,sr,st,starhub,statoil,study,style,su,sucks,supplies,supply,support,surf,surgery,suzuki,sv,swatch,swiss,sx,sy,sydney,systems,sz,taipei,tatar,tattoo,tax,taxi,tc,td,team,tech,technology,tel,telefonica,temasek,tennis,tf,tg,th,thd,theater,tickets,tienda,tips,tires,tirol,tj,tk,tl,tm,tn,to,today,tokyo,tools,top,toray,toshiba,tours,town,toys,tr,trade,trading,training,travel,trust,tt,tui,tv,tw,tz,ua,ug,uk,university,uno,uol,us,uy,uz,va,vacations,vc,ve,vegas,ventures,versicherung,vet,vg,vi,viajes,video,villas,vision,vista,vistaprint,vlaanderen,vn,vodka,vote,voting,voto,voyage,vu,wales,walter,wang,watch,webcam,website,wed,wedding,weir,wf,whoswho,wien,wiki,williamhill,win,windows,wme,work,works,world,ws,wtc,wtf,xbox,xerox,xin,xn--1qqw23a,xn--30rr7y,xn--3bst00m,xn--3ds443g,xn--3e0b707e,xn--45brj9c,xn--45q11c,xn--4gbrim,xn--55qw42g,xn--55qx5d,xn--6frz82g,xn--6qq986b3xl,xn--80adxhks,xn--80ao21a,xn--80asehdb,xn--80aswg,xn--90a3ac,xn--90ais,xn--9et52u,xn--b4w605ferd,xn--c1avg,xn--cg4bki,xn--clchc0ea0b2g2a9gcd,xn--czr694b,xn--czrs0t,xn--czru2d,xn--d1acj3b,xn--d1alf,xn--estv75g,xn--fiq228c5hs,xn--fiq64b,xn--fiqs8s,xn--fiqz9s,xn--fjq720a,xn--flw351e,xn--fpcrj9c3d,xn--fzc2c9e2c,xn--gecrj9c,xn--h2brj9c,xn--hxt814e,xn--i1b6b1a6a2e,xn--imr513n,xn--io0a7i,xn--j1amh,xn--j6w193g,xn--kcrx77d1x4a,xn--kprw13d,xn--kpry57d,xn--kput3i,xn--l1acc,xn--lgbbat1ad8j,xn--mgb9awbf,xn--mgba3a4f16a,xn--mgbaam7a8h,xn--mgbab2bd,xn--mgbayh7gpa,xn--mgbbh1a71e,xn--mgbc0a9azcg,xn--mgberp4a5d4ar,xn--mgbpl2fh,xn--mgbx4cd0ab,xn--mxtq1m,xn--ngbc5azd,xn--node,xn--nqv7f,xn--nqv7fs00ema,xn--nyqy26a,xn--o3cw4h,xn--ogbpf8fl,xn--p1acf,xn--p1ai,xn--pgbs0dh,xn--q9jyb4c,xn--qcka1pmc,xn--rhqv96g,xn--s9brj9c,xn--ses554g,xn--unup4y,xn--vermgensberater-ctb,xn--vermgensberatung-pwb,xn--vhquv,xn--vuq861b,xn--wgbh1c,xn--wgbl6a,xn--xhq521b,xn--xkc2al3hye2a,xn--xkc2dl3a5ee0h,xn--y9a3aq,xn--yfro4i67o,xn--ygbi2ammx,xn--zfr164b,xxx,xyz,yachts,yandex,ye,yodobashi,yoga,yokohama,youtube,yt,za,zip,zm,zone,zuerich,zw".split(/,/)

Instance Method Summary collapse

Constructor Details

#initialize(apikey, endpoint = 'https://www.passivetotal.org/api/v1/') ⇒ API

initialize a new PassiveTotal::API object apikey: is 64-hexcharacter string endpoint: base URL for the web service, defaults to www.passivetotal.org/api/v1/



28
29
30
31
32
33
34
 
# File 'lib/passivetotal/api.rb', line 28

def initialize(apikey, endpoint = 'https://www.passivetotal.org/api/v1/')
  unless apikey =~ /^[a-fA-F0-9]{64}$/
    raise ArgumentError.new("apikey must be a 64 character hex string")
  end
  @apikey = apikey
  @endpoint = endpoint
end

Instance Method Details

#add_tag(query, tag) ⇒ Object

Add a user-tag to an IP or domain query: A domain or IP address to tag tag: Value used to tag query value. Should only consist of alphanumeric, underscores and hyphen values



164
165
166
167
168
 
# File 'lib/passivetotal/api.rb', line 164

def add_tag(query, tag)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  is_valid_with_error(__method__, [:tag], tag)
  post_tag("user/tag/add", query, tag)
end

#classification(query, set = nil) ⇒ Object

PassiveTotal uses the notion of classifications to highlight table rows a certain color based on how they have been rated. PassiveTotal::API#classification() queries if only one argument is given, and sets if both are given query: A domain or IP address to query set: classification label, one of [targeted, crime, multiple, benign]



78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/passivetotal/api.rb', line 78

def classification(query, set=nil)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  if set.nil?
    get(__method__, query)
  else
    is_valid_with_error(__method__, [:classification], set)
    post(__method__, query, set)
  end
end

#dynamic(query, set = nil) ⇒ Object

PassiveTotal allows users to notate if a domain is associated with a dynamic DNS provider. PassiveTotal::API#dynamic() queries if only one argument is given, and sets if both are given query: A domain to query set: String-boolean of “true” or “false”



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/passivetotal/api.rb', line 126

def dynamic(query, set=nil)
  is_valid_with_error(__method__, [:domain], query)
  query = normalize_domain(query)
  if set.nil?
    get(__method__, query)
  else
    is_valid_with_error(__method__, [:bool], set)
    post(__method__, query, set)
  end
end

#ever_compromised(query, set = nil) ⇒ Object

PassiveTotal allows users to notate if a domain or IP address have ever been compromised. These values aid in letting users know that a site may be benign, but it was used in an attack at some point in time. PassiveTotal::API#ever_compromised() queries if only one argument is given, and sets if both are given query: A domain or IP address to query set: String-boolean of “true” or “false”



109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/passivetotal/api.rb', line 109

def ever_compromised(query, set=nil)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  if set.nil?
    get(__method__, query)
  else
    is_valid_with_error(__method__, [:bool], set)
    post(__method__, query, set)
  end
end

#metadata(query) ⇒ Object

Metadata describes the item being queried and includes many of the options available inside of the action API calls. query: A domain or IP address to query



38
39
40
41
42
43
44
 
# File 'lib/passivetotal/api.rb', line 38

def metadata(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get(__method__, query)
end

#passive(query) ⇒ Object

Passive provides a complete passive DNS picture for a domain or IP address including first/last seen values, deconflicted values, sources used, unique counts and enrichment for all values. query: A domain or IP address to query



48
49
50
51
52
53
54
 
# File 'lib/passivetotal/api.rb', line 48

def passive(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get(__method__, query)
end

#remove_tag(query, tag) ⇒ Object

Remove a user-tag to an IP or domain query: A domain or IP address to remove a tag from tag: Value used to tag query value. Should only consist of alphanumeric, underscores and hyphen values



173
174
175
176
177
 
# File 'lib/passivetotal/api.rb', line 173

def remove_tag(query, tag)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  is_valid_with_error(__method__, [:tag], tag)
  post_tag("user/tag/remove", query, tag)
end

#sinkhole(query, set = nil) ⇒ Object

PassiveTotal allows users to notate if an IP address is a known sinkhole. These values are shared globally with everyone in the platform. PassiveTotal::API#sinkhole() queries if only one argument is given, and sets if both are given query: An IP address to set as a sinkhole or not set: String-boolean of “true” or “false”



95
96
97
98
99
100
101
102
103
 
# File 'lib/passivetotal/api.rb', line 95

def sinkhole(query, set=nil)
  is_valid_with_error(__method__, [:ipv4], query)
  if set.nil?
    get(__method__, query)
  else
    is_valid_with_error(__method__, [:bool], set)
    post(__method__, query, set)
  end
end

#ssl_certificate(query) ⇒ Object

PassiveTotal collects and provides SSL certificates as an enrichment point when possible. Beyond the certificate data itself, PassiveTotal keeps a record of the IP address of where the certificate was found and the time in which it was collected. query: An IP address or SHA-1 hash to query



181
182
183
184
185
186
187
188
 
# File 'lib/passivetotal/api.rb', line 181

def ssl_certificate(query)
  is_valid_with_error(__method__, [:ipv4, :hash], query)
  if ipv4?(query)
    get("ssl_certificate/ip_address", query)
  elsif hash?(query)
    get("ssl_certificate/hash", query)
  end
end

#subdomains(query) ⇒ Object

Subdomains provides a comprehensive view of all known subdomains for a registered domain with associated passive DNS information. This call is best used to understand the activity of a particular domain over a period of time. Passive DNS information is only deconflicted at the subdomain level, not across the entire domain. query: A domain to query



58
59
60
61
62
 
# File 'lib/passivetotal/api.rb', line 58

def subdomains(query)
  is_valid_with_error(__method__, [:domain], query)
  query = normalize_domain(query)
  get(__method__, query)
end

#tags(query) ⇒ Object

PassiveTotal uses three types of tags (user, global, and temporal) in order to provide context back to the user. query: A domain or IP address to query



156
157
158
159
 
# File 'lib/passivetotal/api.rb', line 156

def tags(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  get("user/tags", query)
end

#unique(query) ⇒ Object

Each domain or IP address with results has a unique set of resolving items. This call provides those unique items and a frequency count of how often they show up in sorted order. query: A domain or IP address to query



66
67
68
69
70
71
72
 
# File 'lib/passivetotal/api.rb', line 66

def unique(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get(__method__, query)
end

#watching(query, set = nil) ⇒ Object

PassiveTotal allows users to “watch” domains or IP addresses in order to get notified of any changes. PassiveTotal::API#watching() queries if only one argument is given, and sets if both are given query: A domain or IP address to query set: String-boolean of “true” or “false”



141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/passivetotal/api.rb', line 141

def watching(query, set=nil)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  if set.nil?
    get(__method__, query)
  else
    is_valid_with_error(__method__, [:bool], set)
    post(__method__, query, set)
  end
end