{"id":17526992,"url":"https://github.com/chrislee35/passivedns-client","last_synced_at":"2025-03-06T06:31:20.131Z","repository":{"id":677373,"uuid":"10433464","full_name":"chrislee35/passivedns-client","owner":"chrislee35","description":"passivedns-client provides a library and a query tool for querying several passive DNS providers","archived":false,"fork":false,"pushed_at":"2021-12-19T21:37:59.000Z","size":507,"stargazers_count":195,"open_issues_count":1,"forks_count":42,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-06-19T03:11:31.349Z","etag":null,"topics":["360cn","bfkit","circl","dnsdb","farsight","mnemonic","passive-dns","passivetotal","riskiq","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrislee35.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-02T06:40:15.000Z","updated_at":"2024-02-26T20:15:05.000Z","dependencies_parsed_at":"2022-08-16T10:40:26.246Z","dependency_job_id":null,"html_url":"https://github.com/chrislee35/passivedns-client","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrislee35%2Fpassivedns-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrislee35%2Fpassivedns-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrislee35%2Fpassivedns-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrislee35%2Fpassivedns-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrislee35","download_url":"https://codeload.github.com/chrislee35/passivedns-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":220753131,"owners_count":16697311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["360cn","bfkit","circl","dnsdb","farsight","mnemonic","passive-dns","passivetotal","riskiq","ruby"],"created_at":"2024-10-20T15:02:53.867Z","updated_at":"2024-10-20T15:07:13.906Z","avatar_url":"https://github.com/chrislee35.png","language":"Ruby","funding_links":[],"categories":["Ruby","Network Tools","Network","Tools"],"sub_categories":["Network Reconnaissance Tools","Network Tools"],"readme":"# PassiveDNS::Client\n\nThis rubygem queries the following Passive DNS databases:\n\n* CIRCL\n* DNSDB (FarSight)\n* OpenSource Context (OSC)\n* PassiveTotal\n* RiskIQ\n* VirusTotal\n\nPassive DNS is a technique where IP to hostname mappings are made by recording the answers of other people's queries.  \n\nThere is a tool included, pdnstool, that wraps a lot of the functionality that you would need.\n\nPlease note that use of any passive DNS database is subject to the terms of use of that passive DNS database.  Use of this script in violation of their terms is strongly discouraged.  Also, please do not add any obfuscation to try to work around their terms of service.  If you need special services, ask the providers for help/permission.  Remember, these passive DNS operators are my friends.  I don't want to have a row with them because some jerk used this library to abuse them.\n\nIf you like this library, please buy the Passive DNS operators a round of beers.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'passivedns-client'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install passivedns-client\n\n## Configuration\n\nFrom version 2.0.0 on, all configuration keys for passive DNS providers are in one configuration file.  By default the location of the file is $HOME/.passivedns-client .  The syntax of this file is as follows:\n\n\t[dnsdb]\n\tAPIKEY = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n\t[virustotal]\n\tAPIKEY = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n\t[passivetotal]\n\tUSERNAME = tom@example.com\n\tAPIKEY = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n\t[circl]\n\tUSERNAME = circl_user\n\tPASSWORD = circl_pass\n\t[riskiq]\n\tAPI_TOKEN = 0123456789abcdef\n\tAPI_PRIVATE_KEY = 01234567890abcdefghijklmnopqrstu\n  [osc]\n  APIKEY = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n\nCIRCL also can use and authorization token.  In that case, you should drop the USERNAME and PASSWORD options and change the section to something like the following:\n\n\t[circl]\n\tAUTH_TOKEN = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\n\n## Getting Access\n* CIRCL : https://www.circl.lu/services/passive-dns/\n* DNSDB (Farsight Security) : https://api.dnsdb.info/\n* OSC: https://oscontext.com/\n* PassiveTotal : https://www.passivetotal.org\n* RiskIQ : https://github.com/RiskIQ/python_api/blob/master/LICENSE\n* VirusTotal : https://www.virustotal.com\n\n## Usage\n\n\trequire 'passivedns/client'\n\n\tc = PassiveDNS::Client.new(['riskiq','dnsdb'])\n\tresults = c.query(\"example.com\")\n\n\nOr use the included tool...\n\n    Usage: bin/pdnstool [-d [cdprv]] [-g|-v|-m|-c|-x|-y|-j|-t] [-os \u003csep\u003e] [-f \u003cfile\u003e] [-r#|-w#|-v] [-l \u003ccount\u003e] [--config \u003cfile\u003e] \u003cip|domain|cidr\u003e\n    Passive DNS Providers\n      -dcdprv uses all of the available passive dns database\n      -dc use CIRCL\n      -dd use DNSDB\n      -dp use PassiveTotal\n      -dr use RiskIQ\n      -dv use VirusTotal\n      -dvr uses VirusTotal and RiskIQ (for example)\n\n    Output Formatting\n      -g link-nodal GDF visualization definition\n      -z link-nodal graphviz visualization definition\n      -m link-nodal graphml visualization definition\n      -c CSV\n      -x XML\n      -y YAML\n      -j JSON\n      -t ASCII text (default)\n      -s \u003csep\u003e specifies a field separator for text output, default is tab\n\n    State and Recursion\n      -f[file] specifies a sqlite3 database used to read the current state - useful for large result sets and generating graphs of previous runs.\n      -r# specifies the levels of recursion to pull. **WARNING** This is quite taxing on the pDNS servers, so use judiciously (never more than 3 or so) or find yourself blocked!\n      -w# specifies the amount of time to wait, in seconds, between queries (Default: 0)\n      -l \u003ccount\u003e limits the number of records returned per passive dns database queried.\n\n    Specifying a Configuration File\n      --config \u003cfile\u003e specifies a config file. default: /home/chris/.passivedns-client\n\n    Getting Help\n      -h hello there.  This option produces this helpful help information on how to access help.\n      -v debugging information\n\n## Writing Your Own Database Adaptor\n\n  module PassiveDNS #:nodoc: don't document this\n    # The Provider module contains all the Passive DNS provider client code\n    module Provider\n      # Queries OSContext's passive DNS database\n      class MyDatabaseAdaptor \u003c PassiveDB\n        # Sets the modules self-reported name to \"OSC\"\n\t\t    def self.name\n\t\t      \"MyPerfectDNS\" # short, proper label\n\t\t    end\n\t\t    #override\n\t\t    def self.config_section_name\n\t\t      \"perfect\" # very short label to use in the configuration file\n\t\t    end\n\t\t    #override\n\t\t    def self.option_letter\n\t\t      \"p\" # single letter to specify the option for the command line tool\n\t\t    end\n\n\t\t    attr_accessor :debug\n\n  \t\t\tdef initialize(options={})\n  \t\t\t  @debug = options[:debug] || false\n  \t\t\t  # please include a way to change the base URL, HOST, etc., so that people can test\n  \t\t\t  # against a test/alternate version of your service\n  \t\t      @base = options[\"URL\"] || \"http://myperfectdns.example.com/pdns.cgi?query=\"\n  \t\t\t  @apikey = options[\"APIKEY\"] || raise(\"APIKEY option required for #{self.class}\")\n  \t\t\tend\n\n  \t\t\t# override\n  \t\t\tdef lookup(label, limit=nil)\n  \t\t\t\t$stderr.puts \"DEBUG: #{self.class.name}.lookup(#{label})\" if @debug\n  \t\t\t\trecs = []\n  \t\t\t\tTimeout::timeout(240) {\n  \t\t\t\t\tt1 = Time.now\n  \t\t\t\t\t# TODO: your code goes here to fetch the data from your service\n  \t\t\t\t\t# TODO: don't forget to impose the limit either during the fetch or during the parse phase\n  \t\t\t\t\tresponse_time = Time.now - t1\n  \t\t\t\t\t# TODO: parse your data and add PDNSResult objects to recs array\n  \t\t\t\t\trecs \u003c\u003c PDNSResult.new(self.class.name, response_time, rrname ,\n  \t\t\t\t\t\trdata, rrtype, ttl, first_seen, last_seen, count )\n  \t\t\t\t}\n  \t\t\t\trecs\n  \t\t\trescue Timeout::Error =\u003e e # using the implied \"begin/try\" from the beginning of the function\n  \t\t\t\t$stderr.puts \"#{self.class.name} lookup timed out: #{label}\"\n  \t\t\tend\n      end\n\t\tend\n\tend\n\n## Passive DNS - Common Output Format\n\nThere is an RFC, \u003ca href='http://tools.ietf.org/html/draft-dulaunoy-kaplan-passive-dns-cof-01'\u003ePassive DNS - Common Output Format\u003c/a\u003e, and a proof of concept implementation, \u003ca href='https://github.com/adulau/pdns-qof-server'\u003epdns-qof-server\u003c/a\u003e, that describes a recommened JSON format for passive DNS data.  passivedns-client is very close to supporting it, but since I've never enteracted with a true implementation of this RFC, I can't attest that I could correctly parse it.  I think they way that they can encode multiple results into one record would actually break what I have right now.\n\nRight now, I'm in a wait and see mode with how this progresses before I start supporting yet another format or request that other providers start to adhere to a common output format.  If you have thoughts on the matter, I would love to discuss.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\u003ca href='mailto:github@chrisleephd[dot]us[stop here]xxx'\u003e\u003cimg src='http://chrisleephd.us/images/github-email.png?passivedns-client'\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrislee35%2Fpassivedns-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrislee35%2Fpassivedns-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrislee35%2Fpassivedns-client/lists"}