passivetotal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 466cf1dbb64b1dd6a08c99f7fe7b704abd5174f7
+  data.tar.gz: 7d83f321c9d76c14fa90ab614a44a60dbb2aa1bf
+SHA512:
+  metadata.gz: 30b2003a7f8a0336eb11110e3fbce59a9a0ddeb62493c0ad9c1244d1f44226d16a8f8fafeda08296e5e34b756baf0cfea7cabde3792d9ea311f8fdf6b88cc63f
+  data.tar.gz: 3b0127725ccba2de6fe62a8baf99aefaa18f4dc032fa5b32a47a9160398e37f1e905c280f7b4e24971589ef26ca3fbcd7d24f9212a3b058fe8959e9a6d49f760

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.1
+before_install: gem install bundler -v 1.10.5

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in passivetotal.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 chrislee35
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# PassiveTotal
+
+The PassiveTotal gem is (currently) a thin wrapper around PassiveTotal.org's Web-based API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'passivetotal'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install passivetotal
+
+## Command Line Tool
+
+Included in the gem is a command-line tool, passivetotal, with the following usage:
+
+	Usage: passivetotal [-h] [-v] [-k <apikey>] [[-m|-p|-c|-t|-e|-w] <ip or dom>] [[-s|-d] <dom>] [-x <ip>] [-l <ip or hash>] [-i <value>]
+	-h                Help
+	-v                Verbose output
+	-k <apikey>       Sets the APIKEY, defaults to the environment variable PASSIVETOTAL_APIKEY
+	ACTIONS (You have to select one, last one wins)  -m <ip or dom>  Queries metadata for given IP or domain
+	  -p <ip or dom>  Queries passive DNS data for given IP or domain
+	  -c <ip or dom>  Queries (or sets) the classification for a given IP or domain
+	  -t <ip or dom>  Queries (adds or removes) the tags associated with a given IP or domain
+	                  * To remove a tag, prepend a dash, '-' to the tag name when using the -i option
+	  -e <ip or dom>  Queries (or sets) the ever compromised flag on a given IP or domain
+	  -w <ip or dom>  Queries (or sets) the watched flag on a given IP or domain
+	  -s <dom>        Queries the subdomains for a given domain
+	  -d <dom>        Queries (or sets) if a domain is a dynamic DNS domain
+	  -x <ip>         Queries (or sets) if a given IP is a sinkhole
+	  -l <ip or hash> Queries for SSL Certificates/IP addresses associated with a given IP or SHA-1 hash
+	SETTING VALUES  -i <value>      Sets the value, used in conjuntion with -c, -t, -e, -w, -d, or -x
+	                  Valid values for -i depend on what it's used with:
+	                  -c : targeted, crime, multiple, benign
+	                  -t : <a tag name consisting of characters: [a-zA-Z_]>
+	                  -e, -w, -d, -x: true, false
+
+## Usage
+
+    # Initialize the API wrapper with an apikey (using the default endpoint URL of https://www.passivetotal.org/api/v1/)
+    pt = PassiveTotal::API.new(apikey)
+    # Create an array to shove results into
+    res = []
+    # query metadata for the domain, www.passivetotal.org
+    res << @pt.metadata('www.passivetotal.org')
+    # query metadata for the ipv4 address, 107.170.89.121
+    res << @pt.metadata('107.170.89.121')
+    # query passive DNS results for the domain, www.passivetotal.org
+    res << @pt.passive('www.passivetotal.org')
+    # query passive DNS results for the ipv4 address, 107.170.89.121
+    res << @pt.passive('107.170.89.121')
+    # query for subdomains of passivetotal.org
+    res << @pt.subdomains('passivetotal.org')
+    # query for unique IPv4 resolutions of passivetotal.org
+    res << @pt.unique('passivetotal.org')
+    # query for the classification of www.passivetotal.org
+    res << @pt.classification('www.passivetotal.org')
+    # set the classification of www.passivetotal.org as benign
+    res << @pt.classification('www.passivetotal.org', 'benign')
+    # query for the tags associated with www.chrisleephd.us
+    res << @pt.tags('www.chrisleephd.us')
+    # add the "cool" tag to www.chrisleephd.us
+    res << @pt.add_tag('www.chrisleephd.us', 'cool')
+    # remove the "cool" tag from www.chrisleephd.us (aww, I was cool for a few milliseconds :( )
+    res << @pt.remove_tag('www.chrisleephd.us', 'cool')
+    # query if 107.170.89.121 is a sinkhole
+    res << @pt.sinkhole('107.170.89.121')
+    # set 107.170.89.121 as not a sinkhole
+    res << @pt.sinkhole('107.170.89.121', false)
+    # query if www.passivetotal.org has ever been listed as compromised
+    res << @pt.ever_compromised('www.passivetotal.org')
+    # set the ever_compromised flag for www.passivetotal.org to false to indicate that it was never compromised or that it is in sole control of a malicious actor.
+    res << @pt.ever_compromised('www.passivetotal.org', false)
+    # check if www.passivetotal.org is a dynamic dns domain/host
+    res << @pt.dynamic('www.passivetotal.org')
+    # flag www.passivetotal.org as not a dynamic dns domain/host
+    res << @pt.dynamic('www.passivetotal.org', false)
+    # check if www.passivetotal.org is being watched
+    res << @pt.watching('www.passivetotal.org')
+    # unwatch www.passivetotal.org
+    res << @pt.watching('www.passivetotal.org', false)
+    # list SSL certificates associated with IPV4 address 104.131.121.205
+    res << @pt.ssl_certificate('104.131.121.205')
+    # list sites associated with SSL certificates with SHA-1 hash of e9a6647d6aba52dc47b3838c920c9ee59bad7034
+    res << @pt.ssl_certificate('e9a6647d6aba52dc47b3838c920c9ee59bad7034')
+    # dump all this glorious information to feast your eyes upon
+    pp res
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/chrislee35/passivetotal.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/passivetotal

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'passivetotal/cli'
+puts PassiveTotal::CLI.run(ARGV)

data/lib/passivetotal.rb

@@ -0,0 +1,6 @@
+require "passivetotal/version"
+require "passivetotal/api"
+
+module PassiveTotal
+  # Your code goes here...
+end

data/lib/passivetotal/api.rb

@@ -0,0 +1,309 @@
+require 'net/http'
+require 'net/https'
+require 'openssl'
+require 'json'
+require 'passivetotal/version'
+
+# DESCRIPTION: rubygem for querying PassiveTotal.org's web API
+
+module PassiveTotal # :nodoc:
+  
+  class InvalidAPIKeyError < ArgumentError; end
+  
+  # The API class wraps the PassiveTotal.org web API for all the verbs that it supports
+  # See https://www.passivetotal.org/api/docs for the API documentation.
+  class API
+    # 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 http://data.iana.org/TLD/tlds-alpha-by-domain.txt
+    TLDS = "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(/,/)
+    
+    # initialize a new PassiveTotal::API object
+    # apikey: is 64-hexcharacter string
+    # endpoint: base URL for the web service, defaults to https://www.passivetotal.org/api/v1/
+    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
+    
+    # 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
+    def metadata(query)
+      is_valid_with_error(__method__, [:ipv4, :domain], query)
+      if domain?(query)
+        query = normalize_domain(query)
+      end
+      get(__method__, query)
+    end
+    
+    # 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
+    def passive(query)
+      is_valid_with_error(__method__, [:ipv4, :domain], query)
+      if domain?(query)
+        query = normalize_domain(query)
+      end
+      get(__method__, query)
+    end
+
+    # 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
+    def subdomains(query)
+      is_valid_with_error(__method__, [:domain], query)
+      query = normalize_domain(query)
+      get(__method__, query)
+    end
+
+    # 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
+    def unique(query)
+      is_valid_with_error(__method__, [:ipv4, :domain], query)
+      if domain?(query)
+        query = normalize_domain(query)
+      end
+      get(__method__, query)
+    end
+    
+    # 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]
+    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
+    
+    # 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"
+    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
+    
+    # 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"
+    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
+    
+    # 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"
+    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
+    
+    # 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"
+    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
+    
+    # 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
+    def tags(query)
+      is_valid_with_error(__method__, [:ipv4, :domain], query)
+      get("user/tags", query)
+    end
+
+    # 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
+    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
+    
+    # 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
+    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
+    
+    # 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
+    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
+
+    private
+    
+    # returns true if the given string is a dotted quad IPv4 address
+    def ipv4?(ip)
+      if ip =~ /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/
+        return true
+      end
+      false
+    end
+    
+    # returns true if the given string looks like a domain and ends with a known top-level domain (TLD)
+    def domain?(domain)
+      return false if domain.nil?
+      domain = normalize_domain(domain)
+      domain =~ /^[a-zA-Z0-9\-\.]{3,255}$/ and TLDS.index(domain.split(/\./).last)
+    end
+    
+    # returns true if the given string looks like a SHA-1 hash, i.e., 40 character hex string
+    def hash?(hash)
+      return false if hash.nil?
+      if hash =~ /^[a-fA-F0-9]{40}$/
+        return true
+      end
+      false
+    end
+    
+    # returns true if the given string matches a valid classification
+    def classification?(c)
+      not ['targeted', 'crime', 'multiple', 'benign'].index(c).nil?
+    end
+    
+    # returns true is the given object matches true or false
+    def bool?(b)
+      not ['true', 'false'].index(b.to_s).nil?
+    end
+    
+    # returns true if the given string looks like a valid tag
+    def tag?(t)
+      return false if t.nil?
+      if t =~ /^[a-zA-Z][\w\_\-]+[a-zA-Z]$/
+        return true
+      end
+      false
+    end
+    
+    # lowercases and removes a trailing period (if one exists) from a domain name
+    def normalize_domain(domain)
+      return domain.downcase.gsub(/\.$/,'')
+    end
+
+    # helper function to perform an HTTP GET against the web API
+    def get(api, query)
+      params = { 'api_key' => @apikey, 'query' => query }
+      url2json(:GET, "#{@endpoint}#{api}", params)
+    end
+    
+    # helper function to perform an HTTP POST against the web API
+    def post(api, query, set)
+      params = { 'api_key' => @apikey, 'query' => query, api => set }
+      url2json(:POST, "#{@endpoint}#{api}", params)
+    end
+    
+    # helper function to perform an HTTP POST against the web API, but sets the parameter to 'tag' instead of the api name
+    def post_tag(api, query, set)
+      params = { 'api_key' => @apikey, 'query' => query, 'tag' => set }
+      url2json(:POST, "#{@endpoint}#{api}", params)
+    end
+
+    # main helper function to perform HTTP interactions with the web API.
+    def url2json(method, url, params)
+      if method == :GET
+        url << "?" + params.map{|k,v| "#{k}=#{v}"}.join("&")
+      end      
+			url = URI.parse url
+			http = Net::HTTP.new(url.host, url.port)
+			http.use_ssl = (url.scheme == 'https')
+			http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+			http.verify_depth = 5
+      request = nil
+      if method == :GET
+        request = Net::HTTP::Get.new(url.request_uri)
+      else
+        request = Net::HTTP::Post.new(url.request_uri)
+        request.set_form_data(params)
+      end
+      request.add_field("User-Agent", "Ruby/#{RUBY_VERSION} passivetotal rubygem v#{PassiveTotal::VERSION}")
+			t1 = Time.now
+			response = http.request(request)
+			delta = (Time.now - t1).to_f
+      data = JSON.parse(response.body)
+      return data
+    end
+    
+    # tests an item to see if it matches a valid type
+    def is_valid?(types, item)
+      types.each do |type|
+        if type == :ipv4
+          return true if ipv4?(item)
+        elsif type == :domain
+          return true if domain?(item)
+        elsif type == :hash
+          return true if hash?(item)
+        elsif type == :classification
+          return true if classification?(item)
+        elsif type == :tag
+          return true if tag?(item)
+        elsif type == :bool
+          return true if bool?(item)
+        end
+      end
+      return false
+    end
+    
+    # tests an item to see if it matches a valid type and raises an ArgumentError if invalid
+    def is_valid_with_error(methname, types, item)
+      valid = is_valid?(types, item)
+      unless valid
+        raise ArgumentError.new("#{methname} requires arguments of type: #{types.join(",")}")
+      end
+      valid
+    end
+
+  end
+end

data/lib/passivetotal/cli.rb

@@ -0,0 +1,158 @@
+require 'getoptlong'
+require 'passivetotal/api'
+
+module PassiveTotal # :nodoc:
+  # Handles all the command-line parsing and dispatching queries to the PassiveTotal::API instance
+  # CLInterface is aliased by CLI
+	class CLInterface
+    # parses the command line and yields an options hash
+    # === Default Options
+    # options = {
+    #   :method => :usage,
+    #   :query => nil,
+    #   :set => nil,
+    #   :debug => false,
+    #   :apikey => ENV['PASSIVETOTAL_APIKEY']
+    # }
+    def self.parse_command_line(args)
+      origARGV = ARGV.dup
+      ARGV.replace(args)
+      opts = GetoptLong.new(
+      	[ '--help', '-h', GetoptLong::NO_ARGUMENT ],
+      	[ '--debug', '-v', GetoptLong::NO_ARGUMENT ],
+        [ '--apikey', '-k', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--metadata', '-m', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--passive', '-p', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--subdomains', '-s', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--classification', '-c', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--tags', '-t', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--sinkhole', '-x', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--evercompromised', '-e', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--dynamic', '-d', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--watching', '-w', GetoptLong::REQUIRED_ARGUMENT ],
+      	[ '--sslcertificate', '-l', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--set', '-i', GetoptLong::REQUIRED_ARGUMENT ]
+      )
+      
+      options = {
+        :method => :usage,
+        :query => nil,
+        :set => nil,
+        :debug => false,
+        :apikey => ENV['PASSIVETOTAL_APIKEY']
+      }
+
+      opts.each do |opt, arg|
+        case opt
+        when '--help'
+          options[:method] = :usage
+        when '--debug'
+          options[:debug] = true
+        when '--apikey'
+          options[:apikey] = arg
+        when '--metadata'
+          options[:method] = :metadata
+          options[:query] = arg
+        when '--passive'
+          options[:method] = :passive
+          options[:query] = arg
+        when '--subdomains'
+          options[:method] = :subdomains
+          options[:query] = arg
+        when '--classification'
+          options[:method] = :classification
+          options[:query] = arg
+        when '--tags'
+          options[:method] = :tags
+          options[:query] = arg
+        when '--sinkhole'
+          options[:method] = :sinkhole
+          options[:query] = arg
+        when '--evercompromised'
+          options[:method] = :ever_compromised
+          options[:query] = arg
+        when '--dynamic'
+          options[:method] = :dynamic
+          options[:query] = arg
+        when '--watching'
+          options[:method] = :watching
+          options[:query] = arg
+        when '--sslcertificate'
+          options[:method] = :ssl_certificate
+          options[:query] = arg
+        when '--set'
+          options[:set] = arg.dup
+        else
+          options[:method] = :usage
+        end
+      end
+      
+      if options[:method] == :tags and options[:set]
+        if options[:set] =~ /^\-/
+          options[:set].gsub!(/^\-/,'')
+          options[:method] = :remove_tag
+        else
+          options[:method] = :add_tag
+        end
+      end
+      args = ARGV.dup
+      ARGV.replace(origARGV)
+
+      if options[:debug]
+        $stderr.puts "PassiveTotal CLI Options"
+        $stderr.puts "  apikey: #{options[:apikey]}"
+        $stderr.puts "  debug:  #{options[:debug]}"
+        $stderr.puts "  method: #{options[:method]}"
+        $stderr.puts "  query:  #{options[:query]}"
+        $stderr.puts "  set:    #{options[:set]}"
+      end
+      
+      return options
+    end
+    
+    # returns a string containing the usage information
+    def self.usage
+      help_text = "Usage: #{$0} [-h] [-v] [-k <apikey>] [[-m|-p|-c|-t|-e|-w] <ip or dom>] [[-s|-d] <dom>] [-x <ip>] [-l <ip or hash>] [-i <value>]\n"
+      help_text << "-h                Help\n"
+      help_text << "-v                Verbose output\n"
+      help_text << "-k <apikey>       Sets the APIKEY, defaults to the environment variable PASSIVETOTAL_APIKEY\n"
+      help_text << "ACTIONS (You have to select one, last one wins)"
+      help_text << "  -m <ip or dom>  Queries metadata for given IP or domain\n"
+      help_text << "  -p <ip or dom>  Queries passive DNS data for given IP or domain\n"
+      help_text << "  -c <ip or dom>  Queries (or sets) the classification for a given IP or domain\n"
+      help_text << "  -t <ip or dom>  Queries (adds or removes) the tags associated with a given IP or domain\n"
+      help_text << "                  * To remove a tag, prepend a dash, '-' to the tag name when using the -i option\n"
+      help_text << "  -e <ip or dom>  Queries (or sets) the ever compromised flag on a given IP or domain\n"
+      help_text << "  -w <ip or dom>  Queries (or sets) the watched flag on a given IP or domain\n"
+      help_text << "  -s <dom>        Queries the subdomains for a given domain\n"
+      help_text << "  -d <dom>        Queries (or sets) if a domain is a dynamic DNS domain\n"
+      help_text << "  -x <ip>         Queries (or sets) if a given IP is a sinkhole\n"
+      help_text << "  -l <ip or hash> Queries for SSL Certificates/IP addresses associated with a given IP or SHA-1 hash\n"
+      help_text << "SETTING VALUES"
+      help_text << "  -i <value>      Sets the value, used in conjuntion with -c, -t, -e, -w, -d, or -x\n"
+      help_text << "                  Valid values for -i depend on what it's used with:\n"
+      help_text << "                  -c : targeted, crime, multiple, benign\n"
+      help_text << "                  -t : <a tag name consisting of characters: [a-zA-Z_]>\n"
+      help_text << "                  -e, -w, -d, -x: true, false\n"
+      help_text
+    end
+    
+    # main method, takes command-line arguments and performs the desired queries and outputs
+    def self.run(args)
+      options = parse_command_line(args)
+      return usage() if options[:method] == :usage
+      pt = PassiveTotal::API.new(options[:apikey])
+      if pt.respond_to?(options[:method])
+        if options[:set]
+          data = pt.send(options[:method], options[:query], options[:set])
+        else
+          data = pt.send(options[:method], options[:query])
+        end
+        return JSON.pretty_generate(data['results'])
+      end
+      return ''
+    end
+  end
+  # Alias for the CLInterface class
+  CLI = PassiveTotal::CLInterface
+end

data/lib/passivetotal/version.rb

@@ -0,0 +1,3 @@
+module PassiveTotal
+  VERSION = "0.1.0"
+end

data/passivetotal.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'passivetotal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "passivetotal"
+  spec.version       = PassiveTotal::VERSION
+  spec.authors       = ["chrislee35"]
+  spec.email         = ["rubygems@chrislee.dhs.org"]
+
+  spec.summary       = %q{Wrapper library for PassiveTotal.org's W  eb API}
+  spec.description   = %q{PassiveTotal offers an extensive API for users of the platform that maps most major actions available in the web application to a corresponding call. There are two flavors of the API available for use, stable and current. In order to use the stable API, add the version indicator (vX) into the URL as documented below. If you would rather use the current API which includes new changes and experiments, replace the version indicator with "current".}
+  spec.homepage      = "https://github.com/chrislee35/passivetotal"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "json", "~> 1.8"
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

data/utils/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "passivetotal"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/utils/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: passivetotal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- chrislee35
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: PassiveTotal offers an extensive API for users of the platform that maps
+  most major actions available in the web application to a corresponding call. There
+  are two flavors of the API available for use, stable and current. In order to use
+  the stable API, add the version indicator (vX) into the URL as documented below.
+  If you would rather use the current API which includes new changes and experiments,
+  replace the version indicator with "current".
+email:
+- rubygems@chrislee.dhs.org
+executables:
+- passivetotal
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/passivetotal
+- lib/passivetotal.rb
+- lib/passivetotal/api.rb
+- lib/passivetotal/cli.rb
+- lib/passivetotal/version.rb
+- passivetotal.gemspec
+- utils/console
+- utils/setup
+homepage: https://github.com/chrislee35/passivetotal
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Wrapper library for PassiveTotal.org's W  eb API
+test_files: []