From d1b28cf0d41542d1e7d27b31f60128b01299733a Mon Sep 17 00:00:00 2001 From: Purple Date: Sun, 18 Jan 2026 12:14:59 +0000 Subject: [PATCH] Update README and add proprietary license - Rename to ISP IP Manager - Add copyright notice and closed-source declaration - Document webhook improvements (immediate mode, queue management) - Document user authentication and RBAC features - Document cache busting for JavaScript files - Add BunnyCDN setup instructions with regional endpoints - Add troubleshooting for common webhook issues - Add proprietary LICENSE file Co-Authored-By: Claude Opus 4.5 --- LICENSE | 33 ++++ README.md | 444 +++++++++++++++--------------------------------------- 2 files changed, 152 insertions(+), 325 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6776a57 --- /dev/null +++ b/LICENSE @@ -0,0 +1,33 @@ +PROPRIETARY SOFTWARE LICENSE + +Copyright (c) 2025 Purple Computing Ltd. All rights reserved. + +This software and associated documentation files (the "Software") are the +proprietary and confidential property of Purple Computing Ltd. + +NOTICE: All information contained herein is, and remains the property of +Purple Computing Ltd and its suppliers, if any. The intellectual and +technical concepts contained herein are proprietary to Purple Computing Ltd +and its suppliers and may be covered by UK and Foreign Patents, patents in +process, and are protected by trade secret or copyright law. + +RESTRICTIONS: +- You may not copy, modify, merge, publish, distribute, sublicense, and/or + sell copies of the Software without explicit written permission from + Purple Computing Ltd. +- You may not reverse engineer, decompile, or disassemble the Software. +- You may not use the Software for any purpose other than that for which + it was originally licensed. + +UNAUTHORIZED COPYING, MODIFICATION, DISTRIBUTION, OR USE OF THIS SOFTWARE +IS STRICTLY PROHIBITED. + +For licensing inquiries, contact: info@purplecomputing.com + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +PURPLE COMPUTING LTD BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF +OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e23f0db..4771d77 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,47 @@ -# Geofeed Manager +# 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 -- **Authentication** - Secure login with environment-based credentials +- **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 to your geofeed with detailed history +- **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** - Debounced n8n webhooks for on-demand CDN updates +- **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) @@ -46,7 +68,7 @@ A complete solution for managing RFC 8805 compliant IP geolocation feeds (geofee ### 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 (✗) +- Displays all 11 security flags with checkmarks and crosses - Shows record timestamps (created, updated, enriched) ### IP Registry Integration @@ -56,26 +78,10 @@ A complete solution for managing RFC 8805 compliant IP geolocation feeds (geofee - Security flags for: Abuser, Attacker, Bogon, Cloud Provider, Proxy, Relay, Tor, Tor Exit, VPN, Anonymous, Threat - Manual enrichment option for existing entries -### Authentication -- Secure login page with session-based authentication -- Credentials configured via environment variables -- Automatic session timeout after 24 hours - -### Webhook System -- On-demand webhook notifications to n8n (replaces hourly polling) -- Debouncing to batch multiple changes and reduce API calls -- Queue status monitoring in the Advanced tab - -### UI Improvements -- Dark mode with automatic OS detection -- Mobile Safari optimizations with safe area support -- Client logo management with grid display -- Wider table layout for better data visibility - ## Directory Structure ``` -geofeed-manager/ +ip-manager/ ├── database/ │ ├── schema.sql # Database schema │ └── import_csv.php # CSV import utility (CLI) @@ -84,7 +90,12 @@ geofeed-manager/ │ ├── api.php # RESTful API endpoints │ ├── login.php # Authentication page │ ├── index.php # Main web interface -│ ├── error.log # PHP error log (auto-created) +│ ├── 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 @@ -102,7 +113,7 @@ The application automatically pulls code from the Git repository on startup - no ```env # Git Repository -GIT_REPO=https://git.prpl.tools/PurpleComputing/geofeed-manager.git +GIT_REPO=https://git.prpl.tools/PurpleComputing/ip-manager.git GIT_BRANCH=main # Database @@ -111,10 +122,13 @@ DB_NAME=geofeed_manager DB_USER=geofeed DB_PASSWORD=your_secure_password -# Authentication +# 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 @@ -130,9 +144,9 @@ docker compose up -d 3. **Access the web interface** at `http://your-server:8080` -4. **Login** with your configured credentials (default: admin/changeme) +4. **Login** with your configured credentials or via Cloudflare Access -5. **Import your geofeed** via the Advanced tab in the UI +5. **Import your geofeed** via the Client Settings tab in Settings ### How It Works @@ -171,20 +185,27 @@ Or in Dokploy, just redeploy the service. ### Authentication -Authentication is required to access the application. Configure credentials via environment variables: +The application supports two authentication methods: -```env -AUTH_USERNAME=admin -AUTH_PASSWORD=your_secure_password -``` +**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 -**Default Credentials:** -- Username: `admin` -- Password: `changeme` +**2. Session-based Authentication (Fallback)** +- Used when Cloudflare Access headers are not present +- Configure via environment variables: + ```env + AUTH_USERNAME=admin + AUTH_PASSWORD=your_secure_password + ``` -> **Warning:** Change the default password immediately after deployment! Set `AUTH_PASSWORD` in your `.env` file or environment variables. +### User Roles -The login session expires after 24 hours of inactivity. +- **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 @@ -195,140 +216,67 @@ To enable automatic IP enrichment: ```env IPREGISTRY_API_KEY=your_api_key ``` - Or configure it in the Advanced tab of the web interface. -3. Enable auto-enrichment in the Advanced tab - -When enabled, new IP entries are automatically enriched with: -- Hostname (reverse DNS) -- ISP and organization name -- ASN information -- Connection type -- Timezone and coordinates -- Security flags (proxy, VPN, Tor, threat, etc.) + Or configure it in Settings > n8n Integration tab. +3. Enable auto-enrichment in the settings ### AWS Route53 Integration -Configure AWS credentials in the Advanced tab to enable PTR record checking: +Configure AWS credentials in the Settings > n8n Integration tab to enable PTR record checking: -1. Create an IAM user in AWS with `route53:ListHostedZones` and `route53:ListResourceRecordSets` permissions +1. Create an IAM user in AWS with Route53 read permissions 2. Generate an access key and secret key for the IAM user -3. In the Advanced tab, enter: - - **AWS Access Key ID** - Your IAM access key - - **AWS Secret Access Key** - Your IAM secret key - - **AWS Region** - Select your preferred region (Route53 is global, but a region is required for API signing) - - **Hosted Zone IDs** - Comma-separated list of Route53 hosted zone IDs (e.g., `Z1234567890ABC, Z0987654321DEF`) +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 -**IAM Policy Example:** -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "route53:ListHostedZones", - "route53:ListResourceRecordSets", - "route53:GetHostedZone" - ], - "Resource": "*" - } - ] -} -``` - ### Webhook Integration -Configure webhooks in the Advanced tab to notify n8n when data changes: +Configure webhooks in Settings > n8n Integration tab: 1. Enter your n8n webhook URL -2. Set the debounce delay (1-60 minutes) +2. Set the debounce delay (0 for immediate, 1-60 minutes for batched) 3. Enable webhook notifications -The system batches multiple changes within the debounce window to reduce API calls. +**Immediate Mode (delay = 0):** +- Webhooks are sent instantly when entries change +- Each change triggers a separate webhook +- Best for real-time updates -### n8n Workflow Setup +**Batched Mode (delay > 0):** +- Multiple changes within the delay window are consolidated +- Reduces API calls for bulk operations +- Webhooks process when the delay expires -1. In n8n, go to **Settings > Environment Variables** and add: - - `BUNNY_STORAGE_ZONE` - Your BunnyCDN storage zone name - - `BUNNY_API_KEY` - Your BunnyCDN Storage API key +### Webhook Queue Management -2. Create MySQL credentials in n8n: - - Go to **Credentials** - - Add new **MySQL** credential - - Configure with your database details - - Note the credential ID +The webhook queue can be managed from the n8n Integration tab: -3. Import the workflow: - - Go to **Workflows** - - Click **Import from File** - - Select `n8n/geofeed-export-workflow.json` - -4. Update credential references: - - Open the imported workflow - - For each MySQL node, select your MySQL credential - - Save the workflow - -5. Activate the workflow - it will trigger via webhook when data changes - -## Developer Tools - -Access developer tools via the **Developer** tab in the web interface. - -### Database Backup & Restore - -- **Download Full Backup** - Exports all data as a timestamped JSON file including: - - All geofeed entries with enrichment data - - Application settings - - Client logos - - Last 1000 audit log entries - -- **Import Backup** - Restore from a previously exported JSON file - - Validates backup structure before import - - Replaces all existing data - - Shows import summary with counts - -### Database Schema Sync - -Keep your database schema up-to-date with the latest code: - -1. Click **Check for Updates** to compare your database against the repository schema -2. View missing tables, columns, and indexes -3. Click **Apply Schema Updates** to add missing elements - -This is useful after pulling new code that includes database changes. - -### PHP Error Logs - -- View recent PHP errors directly in the browser -- Filter by number of lines (50, 100, 250, 500) -- Color-coded by severity (fatal, error, warning, notice) -- Clear logs with one click - -### System Information - -View current system status: -- App and PHP versions -- Server software and timezone -- Database statistics (entries, enriched count, settings, audit log size) -- Database size on disk +- **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 ``` -### Get Single Entry -``` -GET api.php?action=get&id=123 -``` - ### Create Entry ``` POST api.php?action=create @@ -378,148 +326,6 @@ Content-Type: application/json GET api.php?action=export&format=download ``` -### Get Statistics -``` -GET api.php?action=stats -``` - -### Enrich Single IP -``` -POST api.php?action=enrich_ip -Content-Type: application/json - -{ - "id": 123, - "csrf_token": "..." -} -``` - -### Enrich All Un-enriched IPs -``` -POST api.php?action=enrich_all -Content-Type: application/json - -{ - "csrf_token": "..." -} -``` - -### Database Backup -``` -GET api.php?action=database_backup -``` -Returns a JSON file download with full database backup. - -### Database Import -``` -POST api.php?action=database_import -Content-Type: application/json - -{ - "backup_data": { ... }, - "csrf_token": "..." -} -``` - -### Schema Check -``` -GET api.php?action=schema_check -``` -Returns missing tables, columns, and indexes compared to repository schema. - -### Schema Apply -``` -POST api.php?action=schema_apply -Content-Type: application/json - -{ - "csrf_token": "..." -} -``` - -### Error Logs -``` -GET api.php?action=error_logs&lines=100 -``` - -### Clear Error Logs -``` -POST api.php?action=error_logs_clear -Content-Type: application/json - -{ - "csrf_token": "..." -} -``` - -### System Info -``` -GET api.php?action=system_info -``` - -### AWS Settings -``` -GET api.php?action=aws_settings_get -``` -Returns current AWS Route53 configuration. - -``` -POST api.php?action=aws_settings_save -Content-Type: application/json - -{ - "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE", - "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", - "aws_region": "us-east-1", - "aws_hosted_zones": "Z1234567890ABC, Z0987654321DEF", - "csrf_token": "..." -} -``` - -### Test AWS Connection -``` -GET api.php?action=aws_test -``` -Tests AWS credentials and returns hosted zone count. - -### List AWS Hosted Zones -``` -GET api.php?action=aws_zones -``` -Returns list of configured hosted zones with their names and IDs. - -### List A Records -``` -GET api.php?action=aws_records&zone_id=Z1234567890ABC -``` -Returns all A records from the specified hosted zone. - -### PTR Lookup -``` -GET api.php?action=ptr_lookup&ip=192.168.1.1 -``` -Performs reverse DNS lookup and returns the PTR record for the given IP. - -### Get Whitelabel Settings -``` -GET api.php?action=whitelabel_get -``` -Returns current whitelabel configuration (company name, icon URL, favicon URL, default import URL). - -### Save Whitelabel Settings -``` -POST api.php?action=whitelabel_save -Content-Type: application/json - -{ - "company_name": "My Company", - "icon_url": "https://example.com/logo.svg", - "favicon_url": "https://example.com/favicon.ico", - "default_import_url": "https://example.com/geofeed.csv", - "csrf_token": "..." -} -``` - ## Geofeed Format (RFC 8805) Each line in the exported CSV follows this format: @@ -530,7 +336,7 @@ ip_prefix,country_code,region_code,city,postal_code Example: ```csv -# Geofeed - Generated by Geofeed Manager +# 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 @@ -541,8 +347,12 @@ Example: 1. Create a Storage Zone in BunnyCDN 2. Get your Storage API key from the FTP & API Access section -3. The workflow uploads to: `https://storage.bunnycdn.com/{zone}/geofeed.csv` -4. Your public URL will be: `https://{zone}.b-cdn.net/geofeed.csv` +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 @@ -557,62 +367,46 @@ Example: ## Troubleshooting ### Cannot login -- Verify AUTH_USERNAME and AUTH_PASSWORD environment variables are set -- Check container logs for authentication errors +- 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 the Advanced tab +- Check that auto-enrichment is enabled in Settings - Review error logs in the Developer tab for API errors -### Hostname not showing -- Hostname requires re-enriching entries (the API parameter was added recently) -- Click the globe icon on individual entries to re-enrich them - ### n8n workflow fails - Check that environment variables are set correctly - Verify MySQL credentials are configured - Check BunnyCDN API key permissions -### Web interface shows database error -- Verify database credentials in environment variables -- Ensure the database and tables exist -- Check MySQL/MariaDB is running -- Try running Schema Sync in the Developer tab - ### Missing columns after update - Go to Developer tab - Click "Check for Updates" - Apply any missing schema changes -### Dark mode not working -- Ensure your browser/OS has dark mode enabled -- Try clearing browser cache - -### AWS Route53 connection fails -- Verify your AWS Access Key ID and Secret Access Key are correct -- Ensure the IAM user has the required permissions (ListHostedZones, ListResourceRecordSets) -- Check that the hosted zone IDs are correct (format: Z followed by alphanumeric characters) -- Review error logs in the Developer tab for detailed error messages - -### PTR records showing as MISSING -- PTR records are managed by your IP provider (e.g., IPXO, your ISP, or cloud provider) -- Contact your IP provider to set up reverse DNS for your IP addresses -- PTR lookups use the server's DNS resolver - results may vary based on DNS propagation - -### PTR records showing as MISMATCH -- The PTR record exists but doesn't match the expected hostname -- Verify the PTR is set correctly with your IP provider -- Note: Trailing dots in hostnames are normalized during comparison - -## License - -MIT License - Feel free to use and modify as needed. - --- -Built with care by [Purple Computing](https://purplecomputing.com) +**Copyright (c) 2025 Purple Computing Ltd. All rights reserved.** + +Built by [Purple Computing](https://purplecomputing.com)