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

"aaa,aarp,abarth,abb,abbott,abbvie,abc,able,abogado,abudhabi,ac,academy,accenture,accountant,accountants,aco,actor,ad,adac,ads,adult,ae,aeg,aero,aetna,af,afamilycompany,afl,africa,ag,agakhan,agency,ai,aig,airbus,airforce,airtel,akdn,al,alfaromeo,alibaba,alipay,allfinanz,allstate,ally,alsace,alstom,am,amazon,americanexpress,americanfamily,amex,amfam,amica,amsterdam,analytics,android,anquan,anz,ao,aol,apartments,app,apple,aq,aquarelle,ar,arab,aramco,archi,army,arpa,art,arte,as,asda,asia,associates,at,athleta,attorney,au,auction,audi,audible,audio,auspost,author,auto,autos,avianca,aw,aws,ax,axa,az,azure,ba,baby,baidu,banamex,bananarepublic,band,bank,bar,barcelona,barclaycard,barclays,barefoot,bargains,baseball,basketball,bauhaus,bayern,bb,bbc,bbt,bbva,bcg,bcn,bd,be,beats,beauty,beer,bentley,berlin,best,bestbuy,bet,bf,bg,bh,bharti,bi,bible,bid,bike,bing,bingo,bio,biz,bj,black,blackfriday,blockbuster,blog,bloomberg,blue,bm,bms,bmw,bn,bnpparibas,bo,boats,boehringer,bofa,bom,bond,boo,book,booking,bosch,bostik,boston,bot,boutique,box,br,bradesco,bridgestone,broadway,broker,brother,brussels,bs,bt,budapest,bugatti,build,builders,business,buy,buzz,bv,bw,by,bz,bzh,ca,cab,cafe,cal,call,calvinklein,cam,camera,camp,cancerresearch,canon,capetown,capital,capitalone,car,caravan,cards,care,career,careers,cars,casa,case,cash,casino,cat,catering,catholic,cba,cbn,cbre,cbs,cc,cd,center,ceo,cern,cf,cfa,cfd,cg,ch,chanel,channel,charity,chase,chat,cheap,chintai,christmas,chrome,church,ci,cipriani,circle,cisco,citadel,citi,citic,city,cityeats,ck,cl,claims,cleaning,click,clinic,clinique,clothing,cloud,club,clubmed,cm,cn,co,coach,codes,coffee,college,cologne,com,comcast,commbank,community,company,compare,computer,comsec,condos,construction,consulting,contact,contractors,cooking,cookingchannel,cool,coop,corsica,country,coupon,coupons,courses,cpa,cr,credit,creditcard,creditunion,cricket,crown,crs,cruise,cruises,csc,cu,cuisinella,cv,cw,cx,cy,cymru,cyou,cz,dabur,dad,dance,data,date,dating,datsun,day,dclk,dds,de,deal,dealer,deals,degree,delivery,dell,deloitte,delta,democrat,dental,dentist,desi,design,dev,dhl,diamonds,diet,digital,direct,directory,discount,discover,dish,diy,dj,dk,dm,dnp,do,docs,doctor,dog,domains,dot,download,drive,dtv,dubai,duck,dunlop,dupont,durban,dvag,dvr,dz,earth,eat,ec,eco,edeka,edu,education,ee,eg,email,emerck,energy,engineer,engineering,enterprises,epson,equipment,er,ericsson,erni,es,esq,estate,et,etisalat,eu,eurovision,eus,events,exchange,expert,exposed,express,extraspace,fage,fail,fairwinds,faith,family,fan,fans,farm,farmers,fashion,fast,fedex,feedback,ferrari,ferrero,fi,fiat,fidelity,fido,film,final,finance,financial,fire,firestone,firmdale,fish,fishing,fit,fitness,fj,fk,flickr,flights,flir,florist,flowers,fly,fm,fo,foo,food,foodnetwork,football,ford,forex,forsale,forum,foundation,fox,fr,free,fresenius,frl,frogans,frontdoor,frontier,ftr,fujitsu,fun,fund,furniture,futbol,fyi,ga,gal,gallery,gallo,gallup,game,games,gap,garden,gay,gb,gbiz,gd,gdn,ge,gea,gent,genting,george,gf,gg,ggee,gh,gi,gift,gifts,gives,giving,gl,glade,glass,gle,global,globo,gm,gmail,gmbh,gmo,gmx,gn,godaddy,gold,goldpoint,golf,goo,goodyear,goog,google,gop,got,gov,gp,gq,gr,grainger,graphics,gratis,green,gripe,grocery,group,gs,gt,gu,guardian,gucci,guge,guide,guitars,guru,gw,gy,hair,hamburg,hangout,haus,hbo,hdfc,hdfcbank,health,healthcare,help,helsinki,here,hermes,hgtv,hiphop,hisamitsu,hitachi,hiv,hk,hkt,hm,hn,hockey,holdings,holiday,homedepot,homegoods,homes,homesense,honda,horse,hospital,host,hosting,hot,hoteles,hotels,hotmail,house,how,hr,hsbc,ht,hu,hughes,hyatt,hyundai,ibm,icbc,ice,icu,id,ie,ieee,ifm,ikano,il,im,imamat,imdb,immo,immobilien,in,inc,industries,infiniti,info,ing,ink,institute,insurance,insure,int,international,intuit,investments,io,ipiranga,iq,ir,irish,is,ismaili,ist,istanbul,it,itau,itv,jaguar,java,jcb,je,jeep,jetzt,jewelry,jio,jll,jm,jmp,jnj,jo,jobs,joburg,jot,joy,jp,jpmorgan,jprs,juegos,juniper,kaufen,kddi,ke,kerryhotels,kerrylogistics,kerryproperties,kfh,kg,kh,ki,kia,kim,kinder,kindle,kitchen,kiwi,km,kn,koeln,komatsu,kosher,kp,kpmg,kpn,kr,krd,kred,kuokgroup,kw,ky,kyoto,kz,la,lacaixa,lamborghini,lamer,lancaster,lancia,land,landrover,lanxess,lasalle,lat,latino,latrobe,law,lawyer,lb,lc,lds,lease,leclerc,lefrak,legal,lego,lexus,lgbt,li,lidl,life,lifeinsurance,lifestyle,lighting,like,lilly,limited,limo,lincoln,linde,link,lipsy,live,living,lixil,lk,llc,llp,loan,loans,locker,locus,loft,lol,london,lotte,lotto,love,lpl,lplfinancial,lr,ls,lt,ltd,ltda,lu,lundbeck,luxe,luxury,lv,ly,ma,macys,madrid,maif,maison,makeup,man,management,mango,map,market,marketing,markets,marriott,marshalls,maserati,mattel,mba,mc,mckinsey,md,me,med,media,meet,melbourne,meme,memorial,men,menu,merckmsd,mg,mh,miami,microsoft,mil,mini,mint,mit,mitsubishi,mk,ml,mlb,mls,mm,mma,mn,mo,mobi,mobile,moda,moe,moi,mom,monash,money,monster,mormon,mortgage,moscow,moto,motorcycles,mov,movie,mp,mq,mr,ms,msd,mt,mtn,mtr,mu,museum,music,mutual,mv,mw,mx,my,mz,na,nab,nagoya,name,natura,navy,nba,nc,ne,nec,net,netbank,netflix,network,neustar,new,news,next,nextdirect,nexus,nf,nfl,ng,ngo,nhk,ni,nico,nike,nikon,ninja,nissan,nissay,nl,no,nokia,northwesternmutual,norton,now,nowruz,nowtv,np,nr,nra,nrw,ntt,nu,nyc,nz,obi,observer,off,office,okinawa,olayan,olayangroup,oldnavy,ollo,om,omega,one,ong,onl,online,ooo,open,oracle,orange,org,organic,origins,osaka,otsuka,ott,ovh,pa,page,panasonic,paris,pars,partners,parts,party,passagens,pay,pccw,pe,pet,pf,pfizer,pg,ph,pharmacy,phd,philips,phone,photo,photography,photos,physio,pics,pictet,pictures,pid,pin,ping,pink,pioneer,pizza,pk,pl,place,play,playstation,plumbing,plus,pm,pn,pnc,pohl,poker,politie,porn,post,pr,pramerica,praxi,press,prime,pro,prod,productions,prof,progressive,promo,properties,property,protection,pru,prudential,ps,pt,pub,pw,pwc,py,qa,qpon,quebec,quest,racing,radio,raid,re,read,realestate,realtor,realty,recipes,red,redstone,redumbrella,rehab,reise,reisen,reit,reliance,ren,rent,rentals,repair,report,republican,rest,restaurant,review,reviews,rexroth,rich,richardli,ricoh,ril,rio,rip,ro,rocher,rocks,rodeo,rogers,room,rs,rsvp,ru,rugby,ruhr,run,rw,rwe,ryukyu,sa,saarland,safe,safety,sakura,sale,salon,samsclub,samsung,sandvik,sandvikcoromant,sanofi,sap,sarl,sas,save,saxo,sb,sbi,sbs,sc,sca,scb,schaeffler,schmidt,scholarships,school,schule,schwarz,science,scjohnson,scot,sd,se,search,seat,secure,security,seek,select,sener,services,ses,seven,sew,sex,sexy,sfr,sg,sh,shangrila,sharp,shaw,shell,shia,shiksha,shoes,shop,shopping,shouji,show,showtime,si,silk,sina,singles,site,sj,sk,ski,skin,sky,skype,sl,sling,sm,smart,smile,sn,sncf,so,soccer,social,softbank,software,sohu,solar,solutions,song,sony,soy,spa,space,sport,spot,sr,srl,ss,st,stada,staples,star,statebank,statefarm,stc,stcgroup,stockholm,storage,store,stream,studio,study,style,su,sucks,supplies,supply,support,surf,surgery,suzuki,sv,swatch,swiss,sx,sy,sydney,systems,sz,tab,taipei,talk,taobao,target,tatamotors,tatar,tattoo,tax,taxi,tc,tci,td,tdk,team,tech,technology,tel,temasek,tennis,teva,tf,tg,th,thd,theater,theatre,tiaa,tickets,tienda,tiffany,tips,tires,tirol,tj,tjmaxx,tjx,tk,tkmaxx,tl,tm,tmall,tn,to,today,tokyo,tools,top,toray,toshiba,total,tours,town,toyota,toys,tr,trade,trading,training,travel,travelchannel,travelers,travelersinsurance,trust,trv,tt,tube,tui,tunes,tushu,tv,tvs,tw,tz,ua,ubank,ubs,ug,uk,unicom,university,uno,uol,ups,us,uy,uz,va,vacations,vana,vanguard,vc,ve,vegas,ventures,verisign,versicherung,vet,vg,vi,viajes,video,vig,viking,villas,vin,vip,virgin,visa,vision,viva,vivo,vlaanderen,vn,vodka,volkswagen,volvo,vote,voting,voto,voyage,vu,vuelos,wales,walmart,walter,wang,wanggou,watch,watches,weather,weatherchannel,webcam,weber,website,wed,wedding,weibo,weir,wf,whoswho,wien,wiki,williamhill,win,windows,wine,winners,wme,wolterskluwer,woodside,work,works,world,wow,ws,wtc,wtf,xbox,xerox,xfinity,xihuan,xin,कॉम,セール,佛山,ಭಾರತ,慈善,集团,在线,한국,ଭାରତ,点看,คอม,ভাৰত,ভারত,八卦,ישראל,موقع,বাংলা,公益,公司,香格里拉,网站,移动,我爱你,москва,қаз,католик,онлайн,сайт,联通,срб,бг,бел,קום,时尚,微博,淡马锡,ファッション,орг,नेट,ストア,アマゾン,삼성,சிங்கப்பூர்,商标,商店,商城,дети,мкд,ею,ポイント,新闻,家電,كوم,中文网,中信,中国,中國,娱乐,谷歌,భారత్,ලංකා,電訊盈科,购物,クラウド,ભારત,通販,भारतम्,भारत,भारोत,网店,संगठन,餐厅,网络,ком,укр,香港,亚马逊,诺基亚,食品,飞利浦,台湾,台灣,手机,мон,الجزائر,عمان,ارامكو,ایران,العليان,اتصالات,امارات,بازار,موريتانيا,پاکستان,الاردن,بارت,بھارت,المغرب,ابوظبي,البحرين,السعودية,ڀارت,كاثوليك,سودان,همراه,عراق,مليسيا,澳門,닷컴,政府,شبكة,بيتك,عرب,გე,机构,组织机构,健康,ไทย,سورية,招聘,рус,рф,تونس,大拿,ລາວ,みんな,グーグル,ευ,ελ,世界,書籍,ഭാരതം,ਭਾਰਤ,网址,닷넷,コム,天主教,游戏,vermögensberater,vermögensberatung,企业,信息,嘉里大酒店,嘉里,مصر,قطر,广东,இலங்கை,இந்தியா,հայ,新加坡,فلسطين,政务,xxx,xyz,yachts,yahoo,yamaxun,yandex,ye,yodobashi,yoga,yokohama,you,youtube,yt,yun,za,zappos,zara,zero,zip,zm,zone,zuerich,zw".split(/,/)

Instance Method Summary collapse

Constructor Details

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

initialize a new PassiveTotal::API object username: the email address associated with your PassiveTotal API key. apikey: is 64-hexcharacter string endpoint: base URL for the web service, defaults to api.passivetotal.org/v2/



31
32
33
34
35
36
37
38
 
# File 'lib/passivetotal/api.rb', line 31

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

Instance Method Details

#account ⇒ Object

Account : Get account details your account.



41
42
43
 
# File 'lib/passivetotal/api.rb', line 41

def 
  get('account')
end

#account_history ⇒ Object Also known as: history

Account History : Get history associated with your account.



46
47
48
 
# File 'lib/passivetotal/api.rb', line 46

def 
  get('account/history')
end

#account_organization ⇒ Object Also known as: organization

Account organization : Get details about the organization your account is associated with.



54
55
56
 
# File 'lib/passivetotal/api.rb', line 54

def 
  get('account/organization')
end

#account_organization_teamstream ⇒ Object Also known as: teamstream

Account organization teamstream : Get the teamstream for the organization your account is associated with.



62
63
64
 
# File 'lib/passivetotal/api.rb', line 62

def 
  get('account/organization/teamstream')
end

#account_sources(source) ⇒ Object Also known as: sources

Account sources : Get source details for a specific source.



70
71
72
 
# File 'lib/passivetotal/api.rb', line 70

def (source)
  get('account/sources', {'source' => source})
end

#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



192
193
194
195
196
 
# File 'lib/passivetotal/api.rb', line 192

def add_tag(query, tag)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  is_valid_with_error(__method__, [:tag], tag)
  post('actions/tags', { 'query' => query, 'tags' => [tag] })
end

#bulk_classification(query) ⇒ Object

Get the classification for a query in bulk query: An array of domains or IP address to query



225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/passivetotal/api.rb', line 225

def bulk_classification(query)
  if query.class != Array
    query = [query]
  end
  query.map do |q|
    is_valid_with_error(__method__, [:ipv4, :domain], q)
    if domain?(q)
      q = normalize_domain(q)
    end
    q
  end
  get_with_data('actions/bulk/classification', { 'query' => query })
end

#bulk_enrichment(query) ⇒ Object

Enrichment bulk : Enrich each of the given queries with metadata query: An array of domains or IP addresses to query



116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/passivetotal/api.rb', line 116

def bulk_enrichment(query)
  if query.class != Array
    query = [query]
  end
  query.map do |q|
    is_valid_with_error(__method__, [:ipv4, :domain], q)
    if domain?(q)
      q = normalize_domain(q)
    end
    q
  end
  get_with_data('enrichment/bulk', { 'query' => query })
end

#bulk_malware(query) ⇒ Object

malware bulk: get sample information based from domains query: An array of domains or IP addresses to query



396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/passivetotal/api.rb', line 396

def bulk_malware(query)
  if query.class != Array
    query = [query]
  end
  query.map do |q|
    is_valid_with_error(__method__, [:ipv4, :domain], q)
    if domain?(q)
      q = normalize_domain(q)
    end
    q
  end
  get_with_data('enrichment/bulk/malware', { 'query' => query })
end

#bulk_osint(query) ⇒ Object

osint bulk : Enrich each of the given queries with metadata query: An array of domains or IP addresses to query



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

def bulk_osint(query)
  if query.class != Array
    query = [query]
  end
  query.map do |q|
    is_valid_with_error(__method__, [:ipv4, :domain], q)
    if domain?(q)
      q = normalize_domain(q)
    end
    q
  end
  get_with_data('enrichment/bulk/osint', { 'query' => query })
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



210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/passivetotal/api.rb', line 210

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('actions/classification', {'query' => query})
  else
    is_valid_with_error(__method__.to_s, [:classification], set)
    post('actions/classification', { 'query' => query, 'classification' => set })
  end
end

#components(query) ⇒ Object

PassiveTotal tracks some interesting metadata about a host query: a hostname or ip address



359
360
361
362
363
364
365
 
# File 'lib/passivetotal/api.rb', line 359

def components(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('host-attributes/components', {'query' => query})
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: a boolean flag



262
263
264
265
266
267
268
269
270
271
 
# File 'lib/passivetotal/api.rb', line 262

def dynamic(query, set=nil)
  is_valid_with_error(__method__, [:domain], query)
  query = normalize_domain(query)
  if set.nil?
    get('actions/dynamic-dns', {'query' => query})
  else
    is_valid_with_error(__method__, [:bool], set)
    post('actions/dynamic-dns', { 'query' => query, 'status' => set })
  end
end

#enrichment(query) ⇒ Object Also known as: metadata

Enrichment : Enrich the given query with metadata query: A domain or IP address to query



103
104
105
106
107
108
109
 
# File 'lib/passivetotal/api.rb', line 103

def enrichment(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('enrichment', {'query' => query})
end

#ever_compromised(query, set = nil) ⇒ Object Also known as: compromised

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: a boolean flag



243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/passivetotal/api.rb', line 243

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('actions/ever-compromised', {'query' => query})
  else
    is_valid_with_error(__method__, [:bool], set)
    post('actions/ever-compromised', { 'query' => query, 'status' => set })
  end
end

#malware(query) ⇒ Object

malware: get sample information based from domain query: ip or domain



386
387
388
389
390
391
392
 
# File 'lib/passivetotal/api.rb', line 386

def malware(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('enrichment/malware', {'query' => query})
end

#monitor(query, set = nil) ⇒ Object Also known as: monitoring, watching

PassiveTotal allows users to notate if an ip or domain is “monitored”. PassiveTotal::API#monitor() queries if only one argument is given, and sets if both are given query: A domain to query set: a boolean flag



277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/passivetotal/api.rb', line 277

def monitor(query, set=nil)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  if set.nil?
    get('actions/monitor', {'query' => query})
  else
    is_valid_with_error(__method__, [:bool], set)
    post('actions/monitor', { 'query' => query, 'status' => set })
  end
end

#osint(query) ⇒ Object

osint: Get opensource intelligence data query: A domain or IP address to query



132
133
134
135
136
137
138
 
# File 'lib/passivetotal/api.rb', line 132

def osint(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('enrichment/osint', {'query' => 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



80
81
82
83
84
85
86
 
# File 'lib/passivetotal/api.rb', line 80

def passive(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('dns/passive', {'query' => query})
end

#passive_unique(query) ⇒ Object Also known as: unique

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



90
91
92
93
94
95
96
 
# File 'lib/passivetotal/api.rb', line 90

def passive_unique(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('dns/passive/unique', {'query' => 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



201
202
203
204
205
 
# File 'lib/passivetotal/api.rb', line 201

def remove_tag(query, tag)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  is_valid_with_error(__method__, [:tag], tag)
  delete('actions/tags', { 'query' => query, 'tags' => [tag] })
end

#reputation(query) ⇒ Object

whois: Get reputation data for a domain or IP address query: A domain or IP address to query



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

def reputation(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('reputation', {'query' => query})
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: a boolean flag



298
299
300
301
302
303
304
305
306
 
# File 'lib/passivetotal/api.rb', line 298

def sinkhole(query, set=nil)
  is_valid_with_error(__method__, [:ipv4], query)
  if set.nil?
    get('actions/sinkhole', {'query' => query})
  else
    is_valid_with_error(__method__, [:bool], set)
    post('actions/sinkhole', { 'query' => query, 'status' => set })
  end
end

#ssl_certificate(query, field = nil) ⇒ Object

ssl_certificate: returns details about SSL certificates query: SHA-1 has to query, or, if field is set, a valid value for that field field: the certificate field to query upon

certificate fields: issuer_surname, subject_organizationName, issuer_country, issuer_organizationUnitName, fingerprint, subject_organizationUnitName, serialNumber, subject_emailAddress, subject_country, issuer_givenName, subject_commonName, issuer_commonName, issuer_stateOrProvinceName, issuer_province, subject_stateOrProvinceName, sha1, sslVersion, subject_streetAddress, subject_serialNumber, issuer_organizationName, subject_surname, subject_localityName, issuer_streetAddress, issuer_localityName, subject_givenName, subject_province, issuer_serialNumber, issuer_emailAddress



347
348
349
350
351
352
353
354
355
 
# File 'lib/passivetotal/api.rb', line 347

def ssl_certificate(query, field=nil)
  if field.nil?
    is_valid_with_error(__method__, [:hash], query)
    get('ssl-certificate', {'query' => query})
  else
    is_valid_with_error(__method__, [:ssl_field], field)
    get_params('ssl-certificate/search', { 'query' => query, 'field' => field })
  end
end

#ssl_certificate_history(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: A SHA-1 hash to query



338
339
340
341
 
# File 'lib/passivetotal/api.rb', line 338

def ssl_certificate_history(query)
  is_valid_with_error(__method__, [:ipv4, :hash], query)
  get('ssl-certificate/history', {'query' => query})
end

#subdomains(query) ⇒ Object

subdomains: Get subdomains using a wildcard query query: A domain with wildcard, e.g., *.passivetotal.org



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

def subdomains(query)
  get('enrichment/subdomains', {'query' => query})
end

#tags(query, set = nil) ⇒ 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 set: if supplied, adds a tag to an entity



312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/passivetotal/api.rb', line 312

def tags(query, set=nil)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  if set.nil?
    get('actions/tags', {'query' => query})
  else
    is_valid_with_error(__method__, [:tag], set)
    post('actions/tag', { 'query' => query, 'tags' => [set] })
  end
end

#tags_search(query) ⇒ Object

Search Tags : Search for items based on tag value 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



328
329
330
331
332
333
334
 
# File 'lib/passivetotal/api.rb', line 328

def tags_search(query)
  is_valid_with_error(__method__, [:ipv4, :domain], query)
  if domain?(query)
    query = normalize_domain(query)
  end
  get('actions/tags/search', {'query' => query})
end

#trackers(query, type = nil) ⇒ Object

trackers: Get all tracking codes for a domain or IP address. query: ip or domain, or, if type is supplied, a valid tracker ID type: A valid tracker type to search:

tracker types: YandexMetricaCounterId, ClickyId, GoogleAnalyticsAccountNumber, NewRelicId, MixpanelId, GoogleAnalyticsTrackingId



371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/passivetotal/api.rb', line 371

def trackers(query, type=nil)
  if type.nil?
    is_valid_with_error(__method__, [:ipv4, :domain], query)
    if domain?(query)
      query = normalize_domain(query)
    end
    get('host-attributes/trackers', {'query' => query})
  else
    is_valid_with_error(__method__, [:tracker_type], type)
    get('trackers/search', {'query' => query, 'type' => type})
  end
end

#whois(query, field = nil) ⇒ Object

whois: Get WHOIS data for a domain or IP address query: ipv4, domain, or, if you specify a field, any value for that field field: field name to query if not the default ip/domain field

field names: domain, email, name, organization, address, phone, nameserver



166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/passivetotal/api.rb', line 166

def whois(query, field=nil)
  if field
    is_valid_with_error(__method__, [:whois_field], field)
    get('whois/search', {'field' => field, 'query' => query})
  else
    is_valid_with_error(__method__, [:ipv4, :domain], query)
    if domain?(query)
      query = normalize_domain(query)
    end
    get('whois', {'query' => query, 'compact_record' => 'false'})
  end
end