CloudCheck

[!TIP] UPDATE 01-2026: Now supports REST API!

[!NOTE] UPDATE 12-2025: Now supports government agencies (DoD, FBI, UK MoD, RU FSO)!

[!IMPORTANT] UPDATE 12-2025: Now rewritten in Rust!

CloudCheck is a simple Rust tool to check whether an IP address or hostname belongs to a cloud provider. It includes:

• A Rust CLI
• A Rust library
• Python bindings

Cloud Provider Signatures

The latest cloud provider signatures are available in cloud_providers_v3.json, which is updated daily via CI/CD. Domains associated with each cloud provider are fetched dynamically from the v2fly community repository, and CIDRs are fetched from ASNDB.

Used by BBOT and BBOT Server.

CLI Usage

# installation
cargo install cloudcheck

# lookup command
cloudcheck lookup 8.8.8.8
# output:
[
  {
    "name": "Google",
    "tags": ["cloud"],
    "short_description": "A suite of cloud computing services provided by Google",
    "long_description": "Google Cloud Platform provides infrastructure, platform, and software services for businesses and developers"
  }
]

cloudcheck lookup asdf.amazon.com
# output:
[
  {
    "name": "Amazon",
    "tags": ["cloud"],
    "short_description": "A comprehensive cloud computing platform provided by Amazon",
    "long_description": "Amazon Web Services offers infrastructure services, storage, and computing power"
  }
]

# serve command - start REST API server
cloudcheck serve
# Server listening on http://127.0.0.1:8080
# Swagger UI available at http://127.0.0.1:8080/swagger-ui
# OpenAPI spec available at http://127.0.0.1:8080/api-docs/openapi.json

# serve with custom host and port
cloudcheck serve --host 0.0.0.0 --port 3000

REST API

curl http://127.0.0.1:8080/8.8.8.8

Python Library Usage

# installation
pip install cloudcheck

import asyncio
from cloudcheck import CloudCheck

async def main():
    cloudcheck = CloudCheck()
    results = await cloudcheck.lookup("8.8.8.8")
    print(results) # [{'name': 'Google', 'tags': ['cloud']}]

asyncio.run(main())

Error Handling

import asyncio
from cloudcheck import CloudCheck, CloudCheckError

async def main():
    cloudcheck = CloudCheck()
    try:
        results = await cloudcheck.lookup("8.8.8.8")
        print(results)
    except CloudCheckError as e:
        print(f"Error: {e}")

asyncio.run(main())

Configuration

import asyncio
from cloudcheck import CloudCheck

async def main():
    # Custom configuration
    cloudcheck = CloudCheck(
        signature_url="https://example.com/custom.json",  # Custom signature URL
        max_retries=5,                                     # Max retry attempts (default: 10)
        retry_delay_seconds=2,                             # Delay between retries (default: 1)
        force_refresh=True                                 # Force fresh fetch (default: False)
    )
    results = await cloudcheck.lookup("8.8.8.8")
    print(results)

asyncio.run(main())

Rust Library Usage

# Add to Cargo.toml
[dependencies]
cloudcheck = "8.0"
tokio = { version = "1", features = ["full"] }

use cloudcheck::CloudCheck;

#[tokio::main]
async fn main() {
    let cloudcheck = CloudCheck::new();
    let results = cloudcheck.lookup("8.8.8.8").await.unwrap();
    println!("{:?}", results); // [CloudProvider { name: "Google", tags: ["cloud"] }]
}

Error Handling

use cloudcheck::CloudCheck;

#[tokio::main]
async fn main() {
    let cloudcheck = CloudCheck::new();
    match cloudcheck.lookup("8.8.8.8").await {
        Ok(results) => println!("{:?}", results),
        Err(e) => eprintln!("Error: {}", e),
    }
}

Configuration

use cloudcheck::CloudCheck;

#[tokio::main]
async fn main() {
    // Custom configuration
    let cloudcheck = CloudCheck::with_config(
        Some("https://example.com/custom.json".to_string()), // Custom signature URL
        Some(5),                                              // Max retry attempts (default: 10)
        Some(2),                                              // Delay between retries in seconds (default: 1)
        Some(true)                                            // Force fresh fetch (default: false)
    );
    
    match cloudcheck.lookup("8.8.8.8").await {
        Ok(results) => println!("{:?}", results),
        Err(e) => eprintln!("Error: {}", e),
    }
}

Update the JSON database

export BBOT_IO_API_KEY=<your-api-key>

uv sync
uv run cloudcheck_update/cli.py

Adding a new cloud provider

When adding a new cloud provider:

1. Create a new file in the cloudcheck/providers directory and name it whatever you want, e.g. amazon.py.

2. Inside that file, create a new class that inherits from BaseProvider.

3. Inside that class, fill out any of the following attributes that are relevant to your provider:

   • v2fly_company: The company name for v2fly domain fetching. This will dynamically fetch domains from the v2fly community repository, whose purpose is to keep track of domain ownership across different companies.
   • org_ids: A list of organization IDs from ASNDB. These are always preferable to hard-coded ASNs or CIDRs, since they are updated daily from live sources. Big companies like Amazon typically have one organization ID per Regional Internet Registries (ARIN, RIPE, APNIC, LACNIC, AFRINIC), and within that organization ID, they may have multiple ASNs.
   • asns: A list of ASNs, e.g. [12345, 67890]
   • cidrs: A list of CIDRs, e.g. ["1.2.3.4/32", "5.6.7.8/32"] (it's always preferred to use org_ids or if necessary asns over manually-specified CIDRs)
   • domains: A list of domains, e.g. ["amazon.com", "amazon.co.uk"] (it's always preferred to use v2fly_company instead of hard-coding domains)
   • tags: A list of tags for the provider. These are used in BBOT to tag IPs, DNS names etc. that match this provider. Examples: cloud, cdn, waf, etc.
   • regexes: A dictionary of regexes for the provider. These are used in BBOT to extract / validate cloud resources like storage buckets. Currently valid regexes are:
     • STORAGE_BUCKET_NAME: A regex for the name of a storage bucket (useful when brute-forcing bucket names, as you can discard invalid bucket names early).
     • STORAGE_BUCKET_HOSTNAME: A regex for the hostname of a storage bucket

   In addition to the above attributes, if you have a custom source of CIDRs or domains, you can override the fetch_cidrs() or fetch_domains() methods (which by default return an empty list) to go fetch your custom TXT/JSON file, etc.

Cloud Providers (60)

Development

Python

Setup

uv sync
uv run maturin develop --release

Running Tests

# python tests
uv run pytest test_cloudcheck.py -v

# docker tests
python test_docker.py

Linting

# Check for linting issues
uv run ruff check && uv run ruff format .

Rust

Running Tests

cargo test --verbose --all-features

Formatting

cargo fmt --all

cargo clippy --all-targets --all-features -- -D warnings