socialscan

Python library for accurately querying username and email usage on online platforms

1,464

186

1,464

View on GitHub

Top Related Projects

maigret

10,065

🕵️‍♂️ Collect a dossier on a person by username from thousands of sites

social-analyzer

11,432

API, CLI, and Web App for analyzing and finding a person's profile in 1000 social media \ websites

holehe

7,293

holehe allows you to check if the mail is used on different sites like twitter, instagram and will retrieve information on sites with the forgotten password function.

Quick Overview

SocialScan is a Python library and command-line tool for checking the availability of usernames and email addresses across various social media platforms and websites. It performs asynchronous checks to quickly determine if a given username or email is already registered or available on popular services like Twitter, Instagram, GitHub, and more.

Pros

Fast and efficient due to asynchronous checking
Supports both command-line usage and integration as a Python library
Checks multiple platforms simultaneously
Provides detailed results including availability and potential issues

Cons

May be affected by rate limiting on some platforms
Accuracy can vary depending on the target website's response
Limited to a predefined set of supported platforms
Potential for false positives or negatives due to website changes

Code Examples

Checking username availability:

from socialscan.util import Platforms, sync_execute_queries

results = sync_execute_queries(["username1", "username2"], Platforms.GITHUB)
for result in results:
    print(f"{result.query} on {result.platform}: {result.available}")

Checking email address availability:

from socialscan.util import Platforms, sync_execute_queries

results = sync_execute_queries(["email@example.com"], Platforms.TWITTER)
for result in results:
    print(f"{result.query} on {result.platform}: {result.available}")

Checking multiple platforms:

from socialscan.util import Platforms, sync_execute_queries

platforms = [Platforms.GITHUB, Platforms.TWITTER, Platforms.INSTAGRAM]
results = sync_execute_queries(["username"], platforms)
for result in results:
    print(f"{result.query} on {result.platform}: {result.available}")

Getting Started

To use SocialScan, first install it using pip:

pip install socialscan

Then, you can use it in your Python code:

from socialscan.util import Platforms, sync_execute_queries

usernames = ["username1", "username2"]
platforms = [Platforms.GITHUB, Platforms.TWITTER]

results = sync_execute_queries(usernames, platforms)
for result in results:
    print(f"{result.query} on {result.platform}: {'Available' if result.available else 'Taken'}")

Alternatively, you can use the command-line interface:

socialscan username1 username2 email@example.com

Competitor Comparisons

maigret

10,065

🕵️‍♂️ Collect a dossier on a person by username from thousands of sites

Pros of Maigret

Supports a much larger number of sites and platforms (2000+)
Provides more detailed output including profile information
Offers multiple output formats (TXT, CSV, HTML, JSON)

Cons of Maigret

Slower execution due to more comprehensive checks
More complex setup and dependencies
Potentially higher rate of false positives

Code Comparison

Socialscan:

async def query_username(username, site):
    url = site["url"].format(username=username)
    async with ClientSession() as session:
        response = await session.get(url)
        return site["check_func"](response)

Maigret:

async def request(self, method, url, **kwargs):
    attempts = kwargs.pop('attempts', self.retries)
    for attempt in range(attempts):
        try:
            async with self.session.request(method, url, **kwargs) as response:
                return response
        except Exception as e:
            if attempt == attempts - 1:
                raise e

Both projects use asynchronous HTTP requests, but Maigret implements a more robust retry mechanism and error handling. Socialscan's approach is simpler and more focused on username availability checks, while Maigret's code reflects its broader scope and more complex functionality.

social-analyzer

11,432

API, CLI, and Web App for analyzing and finding a person's profile in 1000 social media \ websites

Pros of social-analyzer

Supports a wider range of social media platforms (300+)
Provides more detailed analysis, including profile pictures and metadata
Offers a web interface in addition to CLI

Cons of social-analyzer

Slower execution due to more comprehensive analysis
More complex setup and dependencies
Potentially higher rate of false positives

Code Comparison

socialscan:

async def query_username(username, site):
    url = site['uri'].format(username=username)
    async with session.get(url, **site['request_kwargs']) as res:
        if res.status == 200:
            return 'TAKEN'
        elif res.status == 404:
            return 'AVAILABLE'
        else:
            return 'UNKNOWN'

social-analyzer:

def find_username_normal(req):
    detection_level = req["detection_level"]
    content = req["content"]
    if detection_level == "normal":
        detections_count = 0
        for detection in req["detections"]:
            if detection["found"]:
                detections_count += 1
        if detections_count >= 1:
            return True
    return False

Both projects aim to analyze social media usernames, but social-analyzer offers more comprehensive analysis at the cost of complexity and speed. socialscan focuses on quick availability checks, while social-analyzer provides deeper insights into user profiles across a broader range of platforms.

holehe

7,293

holehe allows you to check if the mail is used on different sites like twitter, instagram and will retrieve information on sites with the forgotten password function.

Pros of holehe

Supports a larger number of websites and services (over 120)
Provides more detailed information, including account creation date for some services
Actively maintained with regular updates and new features

Cons of holehe

Slower execution due to more comprehensive checks
May trigger rate limiting or IP blocks on some services due to intensive querying

Code comparison

socialscan:

async def query_email(email):
    results = await asyncio.gather(*(site.check_email(email) for site in SITES.values()))
    return [result for result in results if result is not None]

holehe:

def check_email(email):
    modules = import_submodules('holehe.modules')
    websites = get_functions(modules)
    async_results = []
    for website in websites:
        async_results.append(await website(email))
    return async_results

Both projects use asynchronous programming to perform multiple checks concurrently, but holehe's approach allows for more dynamic loading of modules and easier extensibility.

GHunt

15,492

🕵️‍♂️ Offensive Google framework.

Pros of GHunt

More comprehensive OSINT tool, focusing on Google accounts
Provides detailed information like profile picture, gaia ID, and last login
Offers a command-line interface for advanced users

Cons of GHunt

Requires more setup and dependencies
Limited to Google accounts, unlike Socialscan's broader platform coverage
May require frequent updates due to Google's API changes

Code Comparison

GHunt (Python):

def check_email(email):
    client = GHuntClient()
    result = client.check_email(email)
    return result.to_dict()

Socialscan (Python):

async def check_email(email):
    platform = PlatformChecker(Platforms.GITHUB)
    result = await platform.check(email)
    return result.available, result.valid

GHunt provides more detailed results specific to Google accounts, while Socialscan offers a simpler interface for checking availability across multiple platforms. GHunt's code is more complex due to its focus on extracting detailed information, whereas Socialscan's code is more straightforward and easier to integrate into other projects.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

socialscan

socialscan offers accurate and fast checks for email address and username usage on online platforms.

Given an email address or username, socialscan returns whether it is available, taken or invalid on online platforms.

Features that differentiate socialscan from similar tools (e.g. knowem.com, Namechk, and Sherlock):

100% accuracy: socialscan's query method eliminates the false positives and negatives that often occur in similar tools, ensuring that results are always accurate.
Speed: socialscan uses asyncio along with aiohttp to conduct all queries concurrently, providing fast searches even with bulk queries involving hundreds of usernames and email addresses. On a test computer with average specs and Internet speed, 100 queries were executed in ~4 seconds.
Library / CLI: socialscan can be executed through a CLI, or imported as a Python library to be used with existing code.
Email support: socialscan supports queries for both email addresses and usernames.

The following platforms are currently supported:

	Username	Email
Instagram	âï¸	âï¸
Twitter	âï¸	âï¸
GitHub	âï¸	âï¸
Tumblr	âï¸	âï¸
Lastfm	âï¸	âï¸
Snapchat	âï¸
GitLab	âï¸
Reddit	âï¸
Yahoo	âï¸
Pinterest		âï¸
Firefox		âï¸

Background

Other similar tools check username availability by requesting the profile page of the username in question and based on information like the HTTP status code or error text on the requested page, determine whether a username is already taken. This is a naive approach that fails in the following cases:

Reserved keywords: Most platforms have a set of keywords that they don't allow to be used in usernames
(A simple test: try checking reserved words like 'admin' or 'home' or 'root' and see if other services mark them as available)
Deleted/banned accounts: Deleted/banned account usernames tend to be unavailable even though the profile pages might not exist

Therefore, these tools tend to come up with false positives and negatives. This method of checking is also dependent on platforms having web-based profile pages and cannot be extended to email addresses.

socialscan aims to plug these gaps by directly querying the registration servers of the platforms instead, retrieving the appropriate CSRF tokens, headers, and cookies.

Installation

pip

> pip install socialscan

Install from source

> git clone https://github.com/iojw/socialscan.git  
> cd socialscan  
> pip install .

Usage

usage: socialscan [list of usernames/email addresses to check]

optional arguments:
  -h, --help            show this help message and exit
  --platforms [platform [platform ...]], -p [platform [platform ...]]
                        list of platforms to query (default: all platforms)
  --view-by {platform,query}
                        view results sorted by platform or by query (default:
                        query)
  --available-only, -a  only print usernames/email addresses that are
                        available and not in use
  --cache-tokens, -c    cache tokens for platforms requiring more than one
                        HTTP request (Snapchat, GitHub, Instagram. Lastfm &
                        Tumblr), reducing total number of requests sent
  --input input.txt, -i input.txt
                        file containg list of queries to execute
  --proxy-list proxy_list.txt
                        file containing list of HTTP proxy servers to execute
                        queries with
  --verbose, -v         show query responses as they are received
  --show-urls           display profile URLs for usernames on supported platforms
                        (profiles may not exist if usernames are reserved or belong to deleted/banned accounts)
  --json json.txt       output results in JSON format to the specified file
  --version             show program's version number and exit

As a library

socialscan can also be imported into existing code and used as a library.

v1.0.0 introduces the async method execute_queries and the corresponding synchronous wrapper sync_execute_queries that takes a list of queries and optional list of platforms and proxies, executing all queries concurrently. The method then returns a list of results in the same order.

from socialscan.util import Platforms, sync_execute_queries

queries = ["username1", "email2@gmail.com", "mail42@me.com"]
platforms = [Platforms.GITHUB, Platforms.LASTFM]
results = sync_execute_queries(queries, platforms)
for result in results:
    print(f"{result.query} on {result.platform}: {result.message} (Success: {result.success}, Valid: {result.valid}, Available: {result.available})")

Output:

username1 on GitHub: Username is already taken (Success: True, Valid: True, Available: False)
username1 on Lastfm: Sorry, this username isn't available. (Success: True, Valid: True, Available: False)
email2@gmail.com on GitHub: Available (Success: True, Valid: True, Available: True)
email2@gmail.com on Lastfm: Sorry, that email address is already registered to another account. (Success: True, Valid: True, Available: False)
mail42@me.com on GitHub: Available (Success: True, Valid: True, Available: True)
mail42@me.com on Lastfm: Looking good! (Success: True, Valid: True, Available: True)

Text file input

For bulk queries with the --input option, place one username/email on each line in the .txt file:

username1
email2@mail.com
username3

Donations

If you find this tool useful and would like to support its continued development, you can donate here. Thank you for your support.

BTC: bc1qwrnukyc6xh9aygu5ps2geh8stmvagsj5u4v7j6
ETH: 0x45a0F91666391078eA521A6123559E49DAb1275f

Contributing

Errors, suggestions or want a site added? Submit an issue.

PRs are always welcome ð

Please ensure that the code is formatted with black using the config in pyproject.toml before submitting a PR.

License

MPL 2.0

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot