ip-manager/README.md

ISP IP Manager

A complete solution for managing RFC 8805 compliant IP geolocation feeds (geofeeds). This system provides a modern web interface for managing geofeed entries, stores data in MariaDB/MySQL, and automatically exports to BunnyCDN via n8n workflows.

Copyright (c) 2025 Purple Computing Ltd. All rights reserved.

This is proprietary closed-source software. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited.

Features

• Modern Apple-esque UI - Clean, responsive interface with dark mode support
• RFC 8805 Compliant - Generates valid geofeed CSV files per the specification
• Role-Based Access Control - Admin and staff roles with Cloudflare Access integration
• CRUD Operations - Create, read, update, and delete geofeed entries
• Search & Filter - Find entries by IP prefix, city, region, or country
• Audit Logging - Track all changes with user attribution (email-based)
• IP Enrichment - Automatic ISP, hostname, and security flag data via ipregistry.co
• Client Logos - Associate logo images with client shortnames
• Webhook Integration - Immediate or debounced n8n webhooks for CDN updates
• Mobile Optimized - Full mobile Safari support with PWA capabilities
• CSRF Protection - Secure form submissions
• Developer Tools - Database backup/restore, schema sync, and error log viewer
• PTR Record Management - AWS Route53 integration for checking reverse DNS records
• Cache Busting - Automatic JavaScript versioning for reliable deployments

What's New

Webhook System Improvements

• Immediate Webhooks - Set delay to 0 for instant webhook delivery when entries change
• Queue Management - Clear pending, failed, or all webhook history from the UI
• Automatic Processing - Webhooks now process automatically (no cron required for immediate mode)
• Queue Status - View pending, completed, and failed webhooks with HTTP status codes

User Management & Authentication

• Cloudflare Access Integration - Users authenticated via CF Access headers
• Database-Driven Roles - Admin users stored in admin_users table
• User Attribution - Audit log now shows user email instead of IP address
• Display Names - Optional display names for admin users

UI Improvements

• Client Settings Tab - Renamed from "Advanced" for clarity
• Cache Busting - JavaScript files now include version parameter to prevent stale caches
• Improved Error Handling - Better error messages for webhook failures

Whitelabel Settings

• Custom Branding - Customize the application with your company name and logo
• Webapp Icon - Set a custom header icon (SVG or PNG)
• Favicon - Set a custom browser favicon
• Default Import URL - Pre-populate the CSV import URL field
• Live Preview - See branding changes before saving

PTR Records Tab

• AWS Route53 Integration - Connect to your AWS account to list A records from hosted zones
• PTR Lookup - Check if PTR (reverse DNS) records match your forward DNS hostnames
• Bulk Checking - Check all PTR records in a zone with one click
• Status Indicators - Visual indicators for MATCH, MISMATCH, and MISSING PTR records
• Zone Selector - Easily switch between multiple hosted zones
• Auto-Select Single Zone - When only one zone is configured, it's automatically selected
• Local Caching - A records are cached locally for faster access

Developer Mode Tab

• Database Backup - Export full database backup as JSON (entries, settings, logos, audit log)
• Database Import - Restore from a previously exported backup file
• Schema Sync - Check for and apply missing database columns/tables from the repository
• PHP Error Logs - View, filter, and clear PHP error logs directly in the UI
• System Information - View app version, PHP version, database stats, and server info

Entry Details Modal

• Click the info (i) icon on any entry to view full details
• Shows all enrichment data including hostname, ISP, ASN, coordinates
• Displays all 11 security flags with checkmarks and crosses
• Shows record timestamps (created, updated, enriched)

IP Registry Integration

• Automatic IP enrichment when entries are created or imported
• Hostname lookup - Reverse DNS hostname for each IP
• ISP and organization data displayed in the table
• Security flags for: Abuser, Attacker, Bogon, Cloud Provider, Proxy, Relay, Tor, Tor Exit, VPN, Anonymous, Threat
• Manual enrichment option for existing entries

Directory Structure

ip-manager/
├── database/
│   ├── schema.sql          # Database schema
│   └── import_csv.php      # CSV import utility (CLI)
├── webapp/
│   ├── config.php          # Configuration & helpers
│   ├── api.php             # RESTful API endpoints
│   ├── login.php           # Authentication page
│   ├── index.php           # Main web interface
│   ├── settings.php        # Settings & admin interface
│   ├── includes/
│   │   ├── app.js          # Main application JavaScript
│   │   ├── auth.php        # Authentication & RBAC helpers
│   │   ├── header.php      # Page header
│   │   └── footer.php      # Page footer with cache-busted JS
│   └── .htaccess           # Security rules
├── n8n/
│   └── geofeed-export-workflow.json  # n8n workflow
├── docker-compose.yml      # Docker Compose configuration
└── .env.example            # Environment variables template

Installation (Docker / Dokploy)

The application automatically pulls code from the Git repository on startup - no local files needed!

Quick Start

1. Set environment variables in Dokploy (or create .env file):

# Git Repository
GIT_REPO=https://git.prpl.tools/PurpleComputing/ip-manager.git
GIT_BRANCH=main

# Database
DB_ROOT_PASSWORD=your_secure_root_password
DB_NAME=geofeed_manager
DB_USER=geofeed
DB_PASSWORD=your_secure_password

# Authentication (fallback when Cloudflare Access not available)
AUTH_USERNAME=admin
AUTH_PASSWORD=your_secure_admin_password

# Admin Users (comma-separated emails for initial seeding)
ADMIN_EMAILS=admin@example.com,user@example.com

# IP Registry (optional - for IP enrichment)
IPREGISTRY_API_KEY=your_ipregistry_api_key

# Cloudflare Tunnel (optional)
CLOUDFLARE_TUNNEL_TOKEN=your_tunnel_token

2. Deploy with Docker Compose:

docker compose up -d

3. Access the web interface at http://your-server:8080

4. Login with your configured credentials or via Cloudflare Access

5. Import your geofeed via the Client Settings tab in Settings

How It Works

On startup, a git-sync container:

1. Clones the repository from Git
2. Copies webapp/ files to the PHP container volume
3. Copies database/schema.sql for MariaDB initialization
4. Exits after sync completes

The webapp and database containers then start with the synced code.

Updating Code

To pull the latest code from Git, simply restart the stack:

docker compose down
docker compose up -d

Or in Dokploy, just redeploy the service.

Schema Updates: After pulling new code, go to the Developer tab and click "Check for Updates" to apply any new database columns or tables.

Container Details

Service	Port	Description
webapp	8080	PHP web interface
mariadb	3306	MariaDB database (exposed for n8n)
git-sync	-	Pulls code on startup, then exits
cloudflared	-	Cloudflare Tunnel (optional)
phpmyadmin	8081	Database admin (optional, use --profile admin)

Configuration

Authentication

The application supports two authentication methods:

1. Cloudflare Access (Recommended)

• Users are authenticated via Cloudflare Access headers
• Email is read from CF-Access-Authenticated-User-Email header
• Roles are determined by the admin_users database table

2. Session-based Authentication (Fallback)

• Used when Cloudflare Access headers are not present
• Configure via environment variables:

  AUTH_USERNAME=admin
  AUTH_PASSWORD=your_secure_password
  

User Roles

• Admin - Full access to all features including user management and danger zone
• Staff - Standard access to geofeed management features

Admin users are stored in the admin_users table and can be managed via the Users tab in Settings.

IP Registry Integration

To enable automatic IP enrichment:

1. Sign up for a free API key at ipregistry.co
2. Set the API key via environment variable:

   IPREGISTRY_API_KEY=your_api_key
   

   Or configure it in Settings > n8n Integration tab.
3. Enable auto-enrichment in the settings

AWS Route53 Integration

Configure AWS credentials in the Settings > n8n Integration tab to enable PTR record checking:

1. Create an IAM user in AWS with Route53 read permissions
2. Generate an access key and secret key for the IAM user
3. Enter AWS credentials in the settings
4. Click "Test Connection" to verify credentials
5. Go to the PTR tab to view A records and check PTR status

Webhook Integration

Configure webhooks in Settings > n8n Integration tab:

1. Enter your n8n webhook URL
2. Set the debounce delay (0 for immediate, 1-60 minutes for batched)
3. Enable webhook notifications

Immediate Mode (delay = 0):

• Webhooks are sent instantly when entries change
• Each change triggers a separate webhook
• Best for real-time updates

Batched Mode (delay > 0):

• Multiple changes within the delay window are consolidated
• Reduces API calls for bulk operations
• Webhooks process when the delay expires

Webhook Queue Management

The webhook queue can be managed from the n8n Integration tab:

• View Status - See pending, completed, and failed webhooks
• Clear Pending - Remove webhooks waiting to be sent
• Clear Failed - Remove failed webhook records
• Clear All - Remove entire webhook history

API Reference

Authentication

All API endpoints (except export and webhook_process) require authentication.

Webhook Queue Clear

POST api.php?action=webhook_queue_clear
Content-Type: application/json

{
  "clear_type": "pending|failed|all",
  "csrf_token": "..."
}

List Entries

GET api.php?action=list&page=1&limit=25&search=term&country=GB&sort=ip|custom

Create Entry

POST api.php?action=create
Content-Type: application/json

{
  "ip_prefix": "192.168.1.0/24",
  "country_code": "GB",
  "region_code": "GB-ENG",
  "city": "London",
  "postal_code": "EC1A 1BB",
  "client_short_name": "acme",
  "notes": "Main office",
  "csrf_token": "..."
}

Update Entry

POST api.php?action=update
Content-Type: application/json

{
  "id": 123,
  "ip_prefix": "192.168.1.0/24",
  "country_code": "GB",
  "region_code": "GB-ENG",
  "city": "Manchester",
  "postal_code": "M1 1AA",
  "csrf_token": "..."
}

Delete Entry

POST api.php?action=delete
Content-Type: application/json

{
  "id": 123,
  "csrf_token": "..."
}

Export CSV

GET api.php?action=export&format=download

Geofeed Format (RFC 8805)

Each line in the exported CSV follows this format:

ip_prefix,country_code,region_code,city,postal_code

Example:

# Geofeed - Generated by ISP IP Manager
# Format: ip_prefix,country_code,region_code,city,postal_code
192.168.1.0/24,GB,GB-ENG,London,EC1A 1BB
10.0.0.0/8,US,US-CA,San Francisco,94105
2001:db8::/32,DE,DE-BY,Munich,80331

BunnyCDN Setup

1. Create a Storage Zone in BunnyCDN
2. Get your Storage API key from the FTP & API Access section
3. Use the regional endpoint URL (e.g., uk.storage.bunnycdn.com for UK)
4. Configure the n8n HTTP Request node with:
   • Method: PUT
   • URL: https://uk.storage.bunnycdn.com/{zone}/geofeed.csv
   • Headers: AccessKey: your-storage-password, Content-Type: application/octet-stream
5. Your public URL will be: https://{zone}.b-cdn.net/geofeed.csv

Security Considerations

• Always use HTTPS in production (use Cloudflare Tunnel or reverse proxy)
• Change the default admin password immediately
• Keep your database credentials secure
• The application uses session-based authentication with CSRF protection
• IP Registry API keys are stored securely and masked in the UI
• Input validation is performed on all fields
• Error logs are protected from direct web access via .htaccess

Troubleshooting

Cannot login

• Verify Cloudflare Access is configured correctly
• Check AUTH_USERNAME and AUTH_PASSWORD environment variables
• Clear browser cookies and try again

Webhooks not sending

• Ensure webhook URL is configured and enabled
• Set delay to 0 for immediate delivery
• Check the webhook queue status for errors
• Verify n8n workflow is active and in "Production" mode

Webhook shows as failed

• Check the HTTP response code in the queue status
• 404 - Webhook URL not found or n8n workflow not active
• 401/403 - Authentication issue with the webhook endpoint

Stale JavaScript (old version running)

• The app includes automatic cache busting via version parameters
• If issues persist, clear browser cache or use incognito mode
• Redeploy the application to trigger a new git pull

Import fails with "Invalid IP prefix"

Ensure your IP prefixes are in valid CIDR notation (e.g., 192.168.1.0/24)

IP enrichment not working

• Verify your ipregistry.co API key is valid
• Check that auto-enrichment is enabled in Settings
• Review error logs in the Developer tab for API errors

n8n workflow fails

• Check that environment variables are set correctly
• Verify MySQL credentials are configured
• Check BunnyCDN API key permissions

Missing columns after update

• Go to Developer tab
• Click "Check for Updates"
• Apply any missing schema changes

Licensing

ISP IP Manager uses a tiered licensing system. Each deployment requires a valid license key.

License Tiers

Feature	Trial	Basic	Professional	Enterprise
Duration	14 days	1 year	1 year	Perpetual
Max Entries	100	500	2,500	Unlimited
Max Users	2	5	15	Unlimited
Basic CRUD	✓	✓	✓	✓
CSV Export	✓	✓	✓	✓
Webhooks	✗	✓	✓	✓
Audit Log	✗	✓	✓	✓
IP Enrichment	✗	✗	✓	✓
Whitelabel	✗	✗	✓	✓
PTR Records	✗	✗	✓	✓
API Access	✗	✗	✗	✓
Priority Support	✗	✗	✗	✓

License Key Format

License keys follow the format: IPMAN-XXXX-XXXX-XXXX-XXXX

The first character after IPMAN- determines the license tier:

• B - Basic license
• P - Professional license
• E - Enterprise license
• Any other character - Trial license

Activating a License

1. Navigate to Settings > License tab
2. Enter your license key in the format IPMAN-XXXX-XXXX-XXXX-XXXX
3. Enter your company/licensee name
4. Enter your billing email address
5. Click Activate License

The license status will update immediately showing your tier and usage limits.

Customer Deployment

Each ISP customer deploys their own dedicated instance:

1. Provision Infrastructure

   • Deploy using Docker Compose or Dokploy
   • Configure MariaDB database
   • Set up Cloudflare Access for authentication (recommended)

2. Configure Environment

   DB_NAME=geofeed_manager
   DB_USER=geofeed
   DB_PASSWORD=secure_password
   ADMIN_EMAILS=admin@customer-isp.com
   

3. Activate License

   • Provide the customer with their license key
   • Customer activates via Settings > License tab
   • License determines available features and limits

4. Optional Integrations

   • Webhooks (Basic+): Configure n8n for CDN automation
   • IP Enrichment (Professional+): Add ipregistry.co API key
   • PTR Records (Professional+): Configure AWS Route53 credentials
   • Whitelabel (Professional+): Customize branding with customer logo

Generating License Keys

Contact Purple Computing for license key generation:

• Email: info@purplecomputing.com
• Include: Customer name, email, desired tier

---

Copyright (c) 2025 Purple Computing Ltd. All rights reserved.

Built by Purple Computing