cloudcheck 8.1.2

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

CloudCheck

Python Version PyPI Rust Version Crates.io License Ruff Rust Tests Python Tests Pipeline Tests

UPDATE: Now rewritten in Rust, with over 20 new providers added!

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_v2.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

# usage
cloudcheck 8.8.8.8
# output:
{
  "name": "Google",
  "tags": [
    "cloud"
  ]
}

cloudcheck asdf.amazon.com
# output:
{
  "name": "Amazon",
  "tags": [
    "cloud"
  ]
}

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())

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"] }]
}

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 CIDRsor 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.

Supported cloud providers