Repository files navigation

Basic IP intelligence service
API docs » /env docs »

View Releases ·Report Bug ·Request Feature ·Docker Hub

IP Analyzer is a basicIP address intelligence service powered byWorkerman andMaxmind 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 byIPsum.

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. Youshould NOT rely solely on this service to get an accurate user location/origin or as a web application firewall (WAF)/Intrusion Prevention System (IPS).

• IPv4/IPv6 geographic intelligence byMaxmind GeoIP2
• Auto-reload MMDB database with a scheduled Cron pattern
• Fallback MMDB if primary MMDB is not readable/available (Optional)
• IPv4 threat level intelligence byIPsum (Optional)
• Redis integration/caching (Optional)

• PHP-CLI >= 7.4
• Composer >= 2.0
• Workerman >= 4.0
• Maxmind GeoIP2 PHP >= 2.12

Copy the example Docker compose file:

• docker-compose.yml

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

GEOIPUPDATE_ACCOUNT_ID=<YOUR_ACCOUNT_ID>GEOIPUPDATE_LICENSE_KEY=<YOUR_LICENSE_KEY>

You may comment out theip_analyzer service part first, usedocker compose up -d to startmaxmindinc/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 to0.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 theip_analyzer service part and rundocker compose up -d again to start the IP Analyzer service. The service will be available attcp://localhost:3000/ by default.

To test the IP Analyzer service, simple runecho '{"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 theenv documentation. You can view all available request and required schema in theAPI documentation.

For non-Docker installation, PHP >= 7.4 is required, with optional Sodium extension/OpenSSL support. Linux environment is recommended for production deployment. You may run the service locally on your MacOS/Windows machine for development, Windows with WSL is required to run the service and development tests. Please also note that this is a PHP CLI application, which does not require a web server or process manager such as PHP-FPM to function.

The free version of Maxmind GeoIP2 database is namedGeoLite2 which you can download manually or through Maxmind API. To install and update the Maxmind GeoIP2 database automatically, you should request an API key with yourMaxmind account. After you have acquired an API license key, follow the below steps to configure GeoIP download/update on your server (Maxmind instructions for reference)

The following steps are forUbuntu server:

sudo add-apt-repository ppa:maxmind/ppasudo apt updatesudo apt install geoipupdate

After you have installed the official Maxmind updater, you should found a default conf file at/etc/GeoIP.conf. Replace lines above theOPTIONAL line with your own account ID and license key.

# GeoIP.conf file for `geoipupdate` program, for versions >= 3.1.1.# Used to update GeoIP databases from https://www.maxmind.com.# For more information about this config file, visit the docs at# https://dev.maxmind.com/geoip/updating-databases?lang=en.# `AccountID` is from your MaxMind account.AccountID<YOUR_ACCOUNT_ID># `LicenseKey` is from your MaxMind accountLicenseKey<YOUR_KEY># `EditionIDs` is from your MaxMind account.EditionIDs GeoLite2-ASN GeoLite2-City GeoLite2-Country# The remaining settings are OPTIONAL....

Set a Cron job to update automatically

sudo crontab -e

For example:

# Run GeoIP database update at 02:15 every Sunday and Wednesday15 2** 0,3 /usr/bin/geoipupdate

Rungeoipupdate to download the database for the first time

sudo geoipupdate

After finishing Maxmind database setup, you may now installIP Analyzer service.

There are several ways to install IP Analyzer

• Docker (see aboveQuickstart)
• PHAR package (recommended for non-Docker system)
• ZIP release (without vendor and development files)
• Clone the project

If you are using the PHAR package, you might need to ensure the package binary is executable:

chmod +x /path/to/ip-analyzer.phar

If you are using the ZIP release or cloning the project, you will need to install vendor packages withComposer:

composer install

After downloading, create your own.env file by copying the example file:

• .env.example -> .env

Recommended file structure as follow:

.├── ...├── ip-analyzer             # Service root folder│   ├── blacklist             # IPsum txt save directory (Optional)│   ├── mmdb                  # Fallback mmdb directory│   ├── ...│   ├── .env                  # env configuration│   └── ip-analyzer.phar    # service executable / entry PHP script└── ...

Make sure MMDB and fallback directory is readable/writeable by PHP with appropriate permission. For security reasons, you should ensure the env is only readable by the service. (e.g. service started by root on a linux server)

chown root:root /path/to/.envchmod 600 /path/to/.env

While IP Analyzer is intended to be an internal service inside a trusted network, you should ensure the IP Analyzer files is placed under a publicly inaccessible directory on your server. For additional security, you may provide a password hash and SSL cert/key to enable password authentication and SSL on TCP connection respectively.

For detailed environment configuration, please view theenv documentation

After setting up the environment variables, you may start the service on your server terminal.

If you are using PHAR package, navigate to the folder containing the PHAR package

php ip-analyzer.phar start -d

If you install with ZIP release or by cloning the project, navigate to the project folder:

php start-analyzer.php start -d

IP Analyzer supportsRedis out-of-the-box (Tested with Redis >= 5.0). Make sure you have Redis extension enabled in your PHP config, and you may provide Redis connection details in the env.

IP Analyzer will store the following JSON-serialized data with a key prefix defined in env (REDIS_KEY_PREFIX):

• Service status (IP analyze success/failed count)
• Result caching (optional withREDIS_CACHE_RESULT in env)

IPsum is a daily updated list of suspicious/malicious IPv4 addresses with a score indicating how many blacklists it's on. IP Analyzer supports parsing theIPsum list out-of-the-box and use the score to enrich IP analysis result as a threat level number.

To use IPsum list as a simple IP threat intelligence provider, you may runcomposer run ipsum to download and save the txt file to./blacklist/ipsum.txt. Enable IPsum integration in env (IPSUM_ENABLE) and specify a scheduled automatic download/reload of updated IPsum list with a Cron expression (IPSUM_UPDATE_CRON). You should also save the IPsum list on installation/first use and ensure IP Analyzer has read/write access to it.

Addsudo to the following command if the service started/managed by root. To automate and better manage your service on a linux server, please view theSystemd Service section.

Replaceip-analyzer.phar withstart-analyzer.php if you are not using PHAR package or running shell inside Docker container.

Start, stop or restart service (-d to daemonize service, i.e. keep running service after you quit terminal)

php ip-analyzer.phar start -dphp ip-analyzer.phar restart -dphp ip-analyzer.phar stop

Start, restart service with custom env path

php ip-analyzer.phar start -d --env /path/to/envphp ip-analyzer.phar restart -d --env /path/to/env

Reloading service (see notes)

php ip-analyzer.phar reload

Monitoring service

php ip-analyzer.phar statusphp ip-analyzer.phar connections

Notes: Usereload instead ofrestart for a smooth service reload. However only files loaded dynamically afteronWorkerStart event will be reloaded. If you change anything that is declared beforeonWorkerStart such as service address/port or SSL connection settings, you must restart the service to apply changes.

The service accepts TCP request with JSON encoded payload. All payload will pass through basic validation. You can view all available request and required schema in theAPI documentation.

This is a basic request for getting IP address info

{"ip":"128.101.101.101"}

Service response

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

Please seeMaxmind API docs for details on these returned data

If you have enabled the IPsum integration, athreat number will be included in analysis result. The greater the number, the higher chance it might be a credible threat.

{"status":"success","data": {..."threat":5    },"message":null}

You can use any client that can manage TCP connection. The following examples assumed your service is running on 127.0.0.1:3000

• PHP Client
• NodeJS Client
• Shell script

(Linux system only): You can create a service script to let systemd manage and start IP Analyzer automatically on boot.

E.g. /etc/systemd/system/ip-analyzer.service

[Unit]Description=IPAnalyzer ServiceAfter=network.targetStartLimitBurst=5StartLimitIntervalSec=20[Service]Type=forkingExecStart=/usr/bin/php /path/to/ip-analyzer.phar start -dExecReload=/usr/bin/php /path/to/ip-analyzer.phar reloadExecStop=/usr/bin/php /path/to/ip-analyzer.phar stopRestart=alwaysRestartSec=5PrivateTmp=trueRemainAfterExit=yes[Install]WantedBy=multi-user.target

You should reduce and adjust the RestartSec, StartLimitBurst, StartLimitIntervalSec value accordingly if the mail sending service is mission critical.

Reload the service files and starting the service.

sudo systemctl daemon-reloadsudo systemctl start ip-analyzersudo systemctl status ip-analyzer

To enable or disable the service on system reboot

sudo systemctl enable ip-analyzersudo systemctl disable ip-analyzer

To restart or reload the service

sudo systemctl restart ip-analyzersudo systemctl reload ip-analyzer

(Linux system only): Since Workerman generated log does not rotate automatically, it is a good idea to uselogrotate to prevent it from eating up your server storage.

E.g. /etc/logrotate.d/ip-analyzer

/path/to/ip-analyzer/ip-analyzer-workerman.log {  rotate 14  daily  compress  missingok  notifempty  create 0644 root root}

Detailed changes for each release are documented in therelease notes.

Please make sure to read theContributing Guide before making a pull request.

Eric Chow

This project is licensed under theMIT License

Copyright (c) 2022, Eric Chow