ecmchow/ip-analyzer repository overview

⁠IP Analyzer⁠

• env documentation⁠
• API documentation⁠

⁠Introduction

IP Analyzer⁠ is a basic IP address intelligence service powered by Workerman⁠ and Maxmind GeoLite2 database⁠.

It is designed to be a standalone and portable microservice to provide IP address intelligence across multiple applications/services, eliminating the need to initialize GeoIP2 database reader inside applications or in every API requests. While it runs on PHP CLI, it can be integrated with any backend stack that supports internal JSON/TCP communication. It also include a optional threat level indication provided by IPsum⁠.

Disclaimer: IP Analyzer is intended to be an internal service to provide basic IP intelligence for your applications, you should not disclose data from IP Analyzer/MaxMind database to the public unless you have acquired commercial license from MaxMind. You should NOT rely solely on this service to get an accurate user location/origin or as a web application firewall (WAF)/Intrusion Prevention System (IPS).

⁠Quickstart with Docker

Copy the example Docker compose file:

• docker-compose.yml⁠

Before starting the service, make sure you have a valid account with Maxmind GeoIP2⁠. We will use the maxmindinc/geoipupdate⁠ image to automatically download and update MMDB database. Create an .env file for maxmindinc/geoipupdate⁠ docker:

GEOIPUPDATE_ACCOUNT_ID=<YOUR_ACCOUNT_ID>
GEOIPUPDATE_LICENSE_KEY=<YOUR_ACCOUNT_ID>

You may comment out the ip_analyzer service part first, use docker compose up -d to start maxmindinc/geoipupdate and download the MMDB database. To avoid confusing the env file for docker compose and the IP Analyzer service, copy/rename the .env.example⁠ to .env.service and change the listening address to 0.0.0.0:

ANALYZER_ADDR = "0.0.0.0"
...
REDIS_ADDR = "0.0.0.0" ; if you are using Redis

Pass the service env file through the Docker volumes

  ip_analyzer:
  ...
    volumes:
      - /usr/share/GeoIP:/usr/share/GeoIP # MMDB directory
      - /path/to/your/.env.service:/var/www/ip-analyzer/.env # service env file

Un-comment the ip_analyzer service part and run docker compose up -d again to start the IP Analyzer service. The service will be available at tcp://localhost:3000/ by default.

To test the IP Analyzer service, simple run echo '{"ip":"128.101.101.101"}' | nc localhost 3000, you should see the following response:

{"status":"success","data":{"code":"NA","continent":"North America","iso":"US","country":"United States","isEU":false,"city":"Minneapolis","postal":"55414","div":"Minnesota","divIso":"MN","accuracy":10,"lat":44.9764,"long":-93.224,"timezone":"America\/Chicago"},"message":null}

For detailed service env configuration, please visit the env documentation⁠. You can view all available request and required schema in the API documentation⁠.