{
    "info": {
        "author": "Suriyan Laohaprapanon, Gaurav Sood",
        "author_email": "suriyant@gmail.com, gsood07@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3.5",
            "Topic :: Scientific/Engineering :: Information Analysis",
            "Topic :: Software Development :: Libraries :: Python Modules",
            "Topic :: Utilities"
        ],
        "description": "Know Your IP\r\n------------\r\n\r\n.. image:: https://travis-ci.org/themains/know_your_ip.svg?branch=master\r\n    :target: https://travis-ci.org/themains/know_your_ip\r\n.. image:: https://ci.appveyor.com/api/projects/status/qfvbu8h99ymtw2ub?svg=true\r\n    :target: https://ci.appveyor.com/project/themains/know_your_ip\r\n.. image:: https://img.shields.io/pypi/v/know_your_ip.svg\r\n    :target: https://pypi.python.org/pypi/know_your_ip\r\n.. image:: https://readthedocs.org/projects/know_your_ip/badge/?version=latest\r\n    :target: http://know_your_ip.readthedocs.io/en/latest/?badge=latest\r\n    :alt: Documentation Status\r\n\r\nGet data on IP addresses. Learn where they are located (lat/long,\r\ncountry, city, time zone), whether they are blacklisted or not (by\r\n`abuseipdb <http://http://www.abuseipdb.com>`__,\r\n`virustotal <http://www.virustotal.com>`__,\r\n`ipvoid <http://ipvoid.com/>`__, etc.) and for what (and when they were\r\nblacklisted), which ports are open, and what services are running (via\r\n`shodan <http://shodan.io>`__), and what you get when you ping or issue\r\na traceroute. \r\n\r\nIf you are curious about potential application of the package, we have a\r\n`presentation <https://github.com/themains/know_your_ip/tree/master/know_your_ip/presentation/kip.pdf>`__ on \r\nits use in cybersecurity analysis workflow.\r\n\r\nYou can use the package in two different ways. You can call it from the shell, or you can\r\nuse it as an external library. From the shell, you can run ``know_your_ip``. It takes a csv \r\nwith a single column of IP addresses (sample input file: `input.csv <know_your_ip/examples/input.csv>`__), \r\ndetails about the API keys (in `know_your_ip.cfg <know_your_ip/know_your_ip.cfg>`__) \r\nand which columns you would like from which service (in `this example columns.txt <know_your_ip/columns.txt>`__), \r\nand appends the requested results to the IP list (sample output file: `output.csv <know_your_ip/examples/output.csv>`__). \r\nThis simple setup allows you to mix and match easily. \r\n\r\nIf you want to use it as an external library, the package also provides that. The function ``query_ip`` relies\r\non the same config files as ``know_your_ip`` and takes an IP address. We illustrate its use below. You can \r\nalso get data from specific services. For instance, if you only care about getting the MaxMind data, \r\nuse ``maxmind_geocode_ip``. If you would like data from the abuseipdb, call the ``abuseipdb_api`` function, etc. \r\nThese functions still rely on the global config and columns files. For examples of how to use the package, \r\nsee `example.py <know_your_ip/examples/example.py>`__ or the jupyter notebook `example.ipynb <know_your_ip/examples/example.ipynb>`__.\r\n\r\nBrief Primer on Functionality\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n-  **Geocoding IPs**: There is no simple way to discern the location of\r\n   an IP. The locations are typically inferred from data on delay and\r\n   topology along with information from private and public databases.\r\n   For instance, one algorithm starts with a database of locations of\r\n   various 'landmarks', calculates the maximum distance of the last\r\n   router before IP from the landmarks using Internet speed, and builds\r\n   a boundary within which the router must be present and then takes the\r\n   centroid of it. The accuracy of these inferences is generally\r\n   unknown, but can be fairly \\`poor.' For instance, most geolocation\r\n   services place my IP more than 30 miles away from where I am. \r\n   Try http://www.geoipinfo.com/.\r\n\r\n   The script provides hook to `Maxmind City Lite\r\n   DB <http://dev.maxmind.com/geoip/geoip2/geolite2/>`__. It expects a\r\n   copy of the database to be in the folder in which the script is run.\r\n   To download the database, go\r\n   `here <http://dev.maxmind.com/geoip/geoip2/geolite2/>`__. The\r\n   function ``maxmind_geocode_ip`` returns city, country, lat/long etc.\r\n\r\n-  **Timezone**: In theory, there are 24 time zones. In practice, a few\r\n   more. For instance, countries like India have half-hour offsets.\r\n   Theoretical mappings can be easily created for lat/long data based on\r\n   the 15 degrees longitude span. For practical mappings, one strategy\r\n   is to map (nearest) city to time zone (recall the smallish lists that\r\n   you scroll though on your computer's time/date program.) There are a\r\n   variety of services for getting the timezone, including, but not\r\n   limited to,\r\n\r\n   -  `Time and Date <http://www.timeanddate.com/news/time/>`__\r\n   -  `City Time Zone <http://www.citytimezones.info/index.htm>`__\r\n   -  `Edval <http://www.edval.biz/mapping-lat-lng-s-to-timezones>`__\r\n   -  `Geonames <http://www.geonames.org/export/ws-overview.html>`__\r\n   -  `Worldtime.io <http://worldtime.io/>`__\r\n   -  `Twinsun.com <http://www.twinsun.com/tz/tz-link.htm>`__\r\n\r\nFor its ease, we choose a `Python hook to nodeJS lat/long to\r\ntimezone <https://github.com/pegler/>`__. To get the timezone, we first\r\nneed to geocode the IP (see above). The function ``tzwhere_timezone`` takes \r\nlat/long and returns timezone.\r\n\r\n-  **Ping**: Sends out a ICMP echo request and waits for the reply.\r\n   Measures round-trip time (min, max, and mean), reporting errors and\r\n   packet loss. If there is a timeout, the function produces nothing. If \r\n   there is a reply, it returns::\r\n\r\n    packets_sent, packets_received, packets_lost, min_time, \r\n    max_time, avg_time\r\n\r\n-  **Traceroute**: Sends a UDP (or ICMP) packet. Builds the path for how\r\n   the request is routed, noting routers and time.\r\n\r\n-  **Backgrounder**:\r\n\r\n   -  `censys.io <http://censys.io>`__: Performs ZMap and ZGrab scans of\r\n      IPv4 address space. To use censys.io, you must first register.\r\n      Once you register and have the API key, put in\r\n      `here <./know_your_ip/know_your_ip.cfg>`__. The function takes an IP and returns\r\n      asn, timezone, country etc. For a full list, see\r\n      https://censys.io/ipv4/help.\r\n\r\n   -  `shodan.io <http://shodan.io>`__: Scans devices connected to the\r\n      Internet for services, open ports etc. You must register to use\r\n      shodan.io. Querying costs money. Once you register and have the\r\n      API key, put in `here <./know_your_ip/know_your_ip.cfg>`__. The script implements\r\n      two API calls: shodan/host/ip and shodan/scan. The function takes\r\n      a list of IPs and returns\r\n\r\n-  **Blacklists and Backgrounders**: The number of services that\r\n   maintain blacklists is enormous. Here's a list of some of the\r\n   services: TornevallNET, BlockList\\_de, Spamhaus, MyWOT, SpamRATS,\r\n   Malc0de, SpyEye, GoogleSafeBrowsing, ProjectHoneypot, etc. Some of\r\n   the services report results from other services as part of their\r\n   results. In this script, we implement hooks to the following three:\r\n\r\n   -  `virustotal.com <http://virustotal.com>`__: A Google company that\r\n      analyzes and tracks suspicious files, URLs, and IPs. You must\r\n      register to use virustotal. Once you register and have the API\r\n      key, put in `here <./know_your_ip/know_your_ip.cfg>`__. The function implements\r\n      retrieving IP address reports method.\r\n\r\n   -  `abuseipdb.com <http://abuseipdb.com>`__: Tracks reports on IPs.\r\n      You must register to use the API. Once you register and have the\r\n      API key, put in `here <./know_your_ip/know_your_ip.cfg>`__. There is a limit of\r\n      5k pings per month. The function that we implement here is a\r\n      mixture of API and scraping as the API doesn't return details of\r\n      the reports filed.\r\n\r\n   -  `ipvoid.com <http://ipvoid.com>`__: Tracks information on IPs.\r\n      There is no API. We scrape information about IPs including status\r\n      on various blacklist sites.\r\n\r\nQuery Limits\r\n~~~~~~~~~~~~\r\n\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| Service       | Query Limits       | More Info                                                                           |\r\n+===============+====================+=====================================================================================+\r\n| Censys.io     | 120/5 minutes      | `Censys Acct. <https://censys.io/account>`__                                        |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| Virustotal    | 4/minute           | `Virustotal API Doc. <https://www.virustotal.com/en/documentation/public-api/>`__   |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| AbuseIPDB     | 2500/month         | `AbuseIPDB FAQ <http://www.abuseipdb.com/faq.html>`__                               |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| IPVoid        | \\-                 |                                                                                     |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| Shodan        | \\-                 |                                                                                     |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n| \\-----------  | \\----------------  | \\-----------                                                                        |\r\n+---------------+--------------------+-------------------------------------------------------------------------------------+\r\n\r\nInstallation\r\n---------------\r\n\r\nThe script depends on some system libraries. Currently ``traceroute`` uses\r\noperating system command ``traceroute`` on Linux and ``tracert`` on\r\nWindows.\r\n\r\nPing function is based on a pure python ping implementation using raw\r\nsocket and you must have root (on Linux) or Admin (on Windows) privileges to run\r\n\r\n::\r\n\r\n    # Install package and dependencies\r\n    pip install know_your_ip\r\n\r\n    # On Ubuntu Linux (if traceroute command not installed)\r\n    sudo apt-get install traceroute \r\n\r\nNote: If you use anaconda on Windows, it is best to install Shapely via:\r\n\r\n::\r\n\r\n    conda install -c scitools shapely \r\n\r\nGetting KYIP Ready For Use\r\n----------------------------\r\n\r\nTo use the software, you need to take care of three things. You need to fill out\r\nthe API keys in the config file, have a copy of MaxMind db if you want to use MaxMind,\r\nand pick out the columns you want in the columns.txt file:\r\n\r\n-  In the config file (default: ``know_your_ip.cfg``), there are\r\n   settings grouped by function.\r\n-  For Maxmind API, the script expects a copy of the database to be in\r\n   the folder specify by ``dbpath`` in the config file. To download the\r\n   database, go `here <http://dev.maxmind.com/geoip/geoip2/geolite2/>`__\r\n-  In the columns file (default: ``columns.txt``), there are the data\r\n   columns to be output by the script. We may have more than one columns\r\n   file but only one will be use by setting the ``columns`` variable in\r\n   ``output`` section.\r\n-  One more thing re. MaxMind--- you can comment out line 118 and 119 in \r\n   `know_your_ip.py` if you don't have a userid or API Key as \r\n   Maxmind is also available for free. (see `issue <https://github.com/themains/know_your_ip/issues/1>`__)\r\n\r\nConfiguration File\r\n~~~~~~~~~~~~~~~~~~~\r\n\r\nMost of functions make calls to different public REST APIs and hence require an API key and/or username.\r\nYou can register to get the API keys at the following URLs:\r\n\r\n    * `GeoNames <http://www.geonames.org/login>`__\r\n    * `AbuseIPDB <https://www.abuseipdb.com/register>`__\r\n    * `Censys <https://censys.io/register>`__\r\n    * `Shodan <https://account.shodan.io/registe>`__\r\n    * `VirusTotal <https://www.virustotal.com/en/documentation/virustotal-community/>`__\r\n\r\n    See `this example know_your_ip.cfg </know_your_ip/know_your_ip.cfg>`__\r\n\r\n    We can also select the data columns which will be outputted to the CSV file in the text file.\r\n    To take out that column from the output file, add ``#`` at the start of line in the text file ``columns.txt``.\r\n\r\n    See `this example columns.txt <know_your_ip/columns.txt>`__\r\n\r\n\r\nUsing KYIP\r\n------------\r\n\r\nFrom the command line\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n::\r\n\r\n    usage: know_your_ip [-h] [-f FILE] [-c CONFIG] [-o OUTPUT] [-n MAX_CONN]\r\n                        [--from FROM_ROW] [--to TO] [-v] [--no-header]\r\n                        [ip [ip ...]]\r\n\r\n    Know Your IP\r\n\r\n    positional arguments:\r\n    ip                    IP Address(es)\r\n\r\n    optional arguments:\r\n    -h, --help            show this help message and exit\r\n    -f FILE, --file FILE  List of IP addresses file\r\n    -c CONFIG, --config CONFIG\r\n                            Configuration file\r\n    -o OUTPUT, --output OUTPUT\r\n                            Output CSV file name\r\n    -n MAX_CONN, --max-conn MAX_CONN\r\n                            Max concurrent connections\r\n    --from FROM_ROW       From row number\r\n    --to TO               To row number\r\n    -v, --verbose         Verbose mode\r\n    --no-header           Output without header at the first row\r\n\r\n::\r\n\r\n    know_your_ip -file input.csv\r\n\r\nAs an External Library\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nPlease also look at `example.py <know_your_ip/examples/example.py>`__ or the jupyter notebook \r\n`example.ipynb <know_your_ip/examples/example.ipynb>`__.\r\n\r\nAs an External Library with Pandas DataFrame\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n::\r\n\r\n    import pandas as pd\r\n    from know_your_ip import load_config, query_ip\r\n\r\n    df = pd.read_csv('know_your_ip/examples/input.csv', header=None)\r\n\r\n    args = load_config('know_your_ip/know_your_ip.cfg')\r\n\r\n    odf = df[0].apply(lambda c: pd.Series(query_ip(args, c)))\r\n\r\n    odf.to_csv('output.csv', index=False)\r\n\r\nDocumentation\r\n-------------\r\n\r\nFor more information, please see `project documentation <http://know-your-ip.readthedocs.io/en/latest/>`__.\r\n\r\nAuthors\r\n----------\r\n\r\nSuriyan Laohaprapanon and Gaurav Sood\r\n\r\nContributor Code of Conduct\r\n---------------------------------\r\n\r\nThe project welcomes contributions from everyone! In fact, it depends on\r\nit. To maintain this welcoming atmosphere, and to collaborate in a fun\r\nand productive way, we expect contributors to the project to abide by\r\nthe `Contributor Code of\r\nConduct <http://contributor-covenant.org/version/1/0/0/>`__.\r\n\r\nLicense\r\n----------\r\n\r\nThe package is released under the `MIT\r\nLicense <https://opensource.org/licenses/MIT>`__.\r\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/themains/know_your_ip",
        "keywords": "ip geoip ipvoid abuseip shodan virustotal blacklisted geolocation cybersecurity",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "know_your_ip",
        "package_url": "https://pypi.org/project/know_your_ip/",
        "platform": "",
        "project_url": "https://pypi.org/project/know_your_ip/",
        "project_urls": {
            "Homepage": "https://github.com/themains/know_your_ip"
        },
        "release_url": "https://pypi.org/project/know_your_ip/0.1.8/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Get data on IP addresses",
        "version": "0.1.8"
    },
    "last_serial": 4266861,
    "releases": {
        "0.1.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "45ce9a84300bcc7a38e9a668fc83f3b7",
                    "sha256": "2742272acd7f0e1162e990e8bfd9aaada8c6c8bc084f671b85b0909581260850"
                },
                "downloads": -1,
                "filename": "know_your_ip-0.1.4.zip",
                "has_sig": false,
                "md5_digest": "45ce9a84300bcc7a38e9a668fc83f3b7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20566902,
                "upload_time": "2018-01-24T13:48:12",
                "url": "https://files.pythonhosted.org/packages/6d/83/59d8c0b99ce47831fbba7a5c940961d0714384e6422d52d71aefc0574e49/know_your_ip-0.1.4.zip"
            }
        ],
        "0.1.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cd5531002dbb1ad82c55c740534643d5",
                    "sha256": "ccb54c24a237387c4fab428abcac566a2f3c209f9b55f5c2b7e1d777cf5f7307"
                },
                "downloads": -1,
                "filename": "know_your_ip-0.1.5.zip",
                "has_sig": false,
                "md5_digest": "cd5531002dbb1ad82c55c740534643d5",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20568969,
                "upload_time": "2018-02-04T00:20:14",
                "url": "https://files.pythonhosted.org/packages/01/5e/0652f10ebc5be874f8fc8e50f3dad32b3126c3afff5990e50349aad9021a/know_your_ip-0.1.5.zip"
            }
        ],
        "0.1.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "71c68af893b9fe0cc698853b97d89bc9",
                    "sha256": "bc61cba7fa27dbb85766f1da8e38245cb3a7a678f7912bcf2b1c9110c6eb1d5c"
                },
                "downloads": -1,
                "filename": "know_your_ip-0.1.6.tar.gz",
                "has_sig": false,
                "md5_digest": "71c68af893b9fe0cc698853b97d89bc9",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20486408,
                "upload_time": "2018-08-18T03:39:38",
                "url": "https://files.pythonhosted.org/packages/3d/86/b8c7db2230c8619de8e4914c8927df047ae284f91cda367f20e7ea399288/know_your_ip-0.1.6.tar.gz"
            }
        ],
        "0.1.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2a365087850b9555265d9a404e6e927d",
                    "sha256": "fb477428dca14a0d864b714cf4e787c08445f9195dc884a0a79e85b161abe695"
                },
                "downloads": -1,
                "filename": "know_your_ip-0.1.7.tar.gz",
                "has_sig": false,
                "md5_digest": "2a365087850b9555265d9a404e6e927d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20486469,
                "upload_time": "2018-08-18T03:53:05",
                "url": "https://files.pythonhosted.org/packages/9a/b0/95d6a8db5ffda6c6c46c9e79f6adae1a2b63dd2f5904d06ddb4e254c9fe0/know_your_ip-0.1.7.tar.gz"
            }
        ],
        "0.1.8": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8e091b5818e90a20647764c3a4d67433",
                    "sha256": "a6d3f56916482bad2f9a66de25041f251fa2d641646483a28cd3a4ac69d0a464"
                },
                "downloads": -1,
                "filename": "know_your_ip-0.1.8.tar.gz",
                "has_sig": false,
                "md5_digest": "8e091b5818e90a20647764c3a4d67433",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20486513,
                "upload_time": "2018-09-12T23:21:41",
                "url": "https://files.pythonhosted.org/packages/75/14/d791f98ce62e64aca09a0279f31c10dd5d21a95b4c646f9623b90f5e60b1/know_your_ip-0.1.8.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8e091b5818e90a20647764c3a4d67433",
                "sha256": "a6d3f56916482bad2f9a66de25041f251fa2d641646483a28cd3a4ac69d0a464"
            },
            "downloads": -1,
            "filename": "know_your_ip-0.1.8.tar.gz",
            "has_sig": false,
            "md5_digest": "8e091b5818e90a20647764c3a4d67433",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 20486513,
            "upload_time": "2018-09-12T23:21:41",
            "url": "https://files.pythonhosted.org/packages/75/14/d791f98ce62e64aca09a0279f31c10dd5d21a95b4c646f9623b90f5e60b1/know_your_ip-0.1.8.tar.gz"
        }
    ]
}