Bulk Upload Subnets to CleanBrowsing

Step 1: Understand the API Action

To bulk upload IP addresses, you will use the CleanBrowsing network/add API action. This action registers an IP address to your account so that DNS queries from that IP are filtered according to your profile settings.

API Endpoint

https://my.cleanbrowsing.org/api?apikey=[key]&action=network/add&ip_address=<IPv4>&profile_name=<name>&label=<label>

Parameters

Response Format

Success:

{"status": "success"}

Error:

{"status": "failed", "reason": "reason why"}

Step 2: Create the Python Script

Create a file named cleanbrowsing-upload.py and paste the following Python script. This script generates all IPs in a given CIDR range and registers each one with your CleanBrowsing account via the API.

import ipaddress
import requests

def generate_ips(cidr):
    """Generate all IP addresses in a CIDR range."""
    network = ipaddress.ip_network(cidr, strict=False)
    return [str(ip) for ip in network.hosts()]

def add_ip_to_network(api_key, ip, profile_name="default", label=""):
    """Add a single IP address to CleanBrowsing via the API."""
    url = "https://my.cleanbrowsing.org/api"
    params = {
        "apikey": api_key,
        "action": "network/add",
        "ip_address": ip,
        "profile_name": profile_name,
        "label": label
    }
    response = requests.get(url, params=params)
    print(f"{ip}: {response.text}")
    return response.json()

# Configuration
api_key = "your_api_key"
ip_range = "1.2.3.0/24"
profile = "default"
label = "bulk-upload"

# Generate and upload
ips = generate_ips(ip_range)
for ip in ips:
    add_ip_to_network(api_key, ip, profile, label)

Step 3: Set Your API Key

Replace 'your_api_key' in the script with your actual CleanBrowsing API key. You can find your API key in your CleanBrowsing dashboard:

1. Log in to my.cleanbrowsing.org.
2. Navigate to Settings or Account.
3. Locate the API Key section and copy your key.

Note: API access requires an active CleanBrowsing paid subscription.

Step 4: Set Your IP Range

Update the ip_range variable in the script with your actual subnet in CIDR notation. For example:

# A /24 subnet (254 usable IPs)
ip_range = "203.0.113.0/24"

# A /28 subnet (14 usable IPs)
ip_range = "198.51.100.0/28"

You can also customize the profile and label variables to associate the IPs with a specific filtering profile and descriptive label.

Step 5: Run the Script

Make sure you have Python 3 and the requests library installed, then execute the script:

# Install the requests library if needed
pip3 install requests

# Run the script
python3 cleanbrowsing-upload.py

Expected Output

For each IP in the subnet, you should see a success response:

1.2.3.1: {"status":"success", "notice":"New IP Address added to your account: 1.2.3.1"}
1.2.3.2: {"status":"success", "notice":"New IP Address added to your account: 1.2.3.2"}
1.2.3.3: {"status":"success", "notice":"New IP Address added to your account: 1.2.3.3"}
...

The script processes each IP individually with a corresponding success or error confirmation. If an IP is already registered, the API will return an appropriate error message.