What Do the QueryStatus Enum Values Mean in Sherlock? A Complete Guide

Sherlock's QueryStatus enumeration defines five mutually exclusive states—CLAIMED, AVAILABLE, UNKNOWN, ILLEGAL, and WAF—that classify every username probe outcome, ensuring deterministic reporting across the tool's CLI and data exports.

When probing hundreds of social networks for username availability, Sherlock needs a strict classification system to interpret HTTP responses consistently. The QueryStatus enum values, defined in sherlock_project/result.py, serve as the single source of truth for categorizing each site query. These five enum values capture every possible outcome, from successful detection to firewall blocks, enabling reliable data processing throughout the sherlock-project/sherlock codebase.

Overview of the QueryStatus Enumeration

The QueryStatus class inherits from Python's standard Enum and lives in sherlock_project/result.py. It provides five mutually exclusive states that cover the entire spectrum of query outcomes:

class QueryStatus(Enum):
    CLAIMED   = "Claimed"   # Username Detected

    AVAILABLE = "Available" # Username Not Detected

    UNKNOWN   = "Unknown"   # Error Occurred While Trying To Detect Username

    ILLEGAL   = "Illegal"   # Username Not Allowable For This Site

    WAF       = "WAF"       # Request blocked by WAF (i.e. Cloudflare)

Each value represents an architectural intent for how the result should propagate through the scanning pipeline and final report generation.

Detailed Breakdown of Each QueryStatus Value

CLAIMED – Username Detected

The CLAIMED status indicates that Sherlock found conclusive evidence the username exists on the target site. This typically triggers on HTTP 200 responses containing profile-specific patterns, confirmed profile URLs, or site-specific "user found" cues. In sherlock_project/sherlock.py, this status is assigned after successful pattern matching against the response body or status code. The value propagates to the QueryResult object and ultimately appears in JSON/CSV exports as a confirmed claim.

AVAILABLE – Username Not Detected

When a site returns a 404 status, "username available" message, or lacks any profile indicators, Sherlock assigns the AVAILABLE status. This definitive negative result tells users the handle is unclaimed on that specific platform. The sherlock_project/notify.py module uses this status to print availability messages and color-code CLI output accordingly.

UNKNOWN – Error Occurred

The UNKNOWN status serves as both the default initialization value and the catch-all for unexpected failures. Before any HTTP request executes, sherlock_project/sherlock.py initializes query_status = QueryStatus.UNKNOWN. If network timeouts, parsing exceptions, or unhandled HTTP codes occur, the status remains UNKNOWN. This alerts users that the site could not be verified rather than falsely claiming availability or ownership.

ILLEGAL – Username Not Allowable

Sherlock validates usernames against site-specific regex patterns before issuing HTTP requests. When a handle contains illegal characters, violates length restrictions, or otherwise fails validation for a particular site, the ILLEGAL status is assigned immediately. This pre-emptive check in sherlock_project/sherlock.py prevents unnecessary network traffic and eliminates false positives from malformed queries.

WAF – Request Blocked by Web Application Firewall

The WAF status indicates the request was intercepted by a protective layer such as Cloudflare or another Web Application Firewall. Sherlock detects this by matching response headers or body content against known WAF signatures, typically accompanying HTTP 403 or 503 codes. Unlike UNKNOWN, this specific status informs users that the site actively blocks automated probing rather than experiencing a technical error.

How QueryStatus Is Assigned in the Source Code

The core logic in sherlock_project/sherlock.py determines which status applies through a cascading decision tree:

# Determine status after performing the HTTP request / pattern matching

if illegal_handle:
    query_status = QueryStatus.ILLEGAL
elif request_blocked_by_waf:
    query_status = QueryStatus.WAF
elif username_found:
    query_status = QueryStatus.CLAIMED
elif username_not_found:
    query_status = QueryStatus.AVAILABLE
else:
    query_status = QueryStatus.UNKNOWN

# Store the result for later aggregation

result = QueryResult(username, site_name, url, query_status, elapsed)
results[site_name] = {"status": result}

This exhaustive branching guarantees every site query maps to exactly one enum value, creating deterministic output for downstream consumers.

Working with QueryStatus in Practice

Developers extending Sherlock can instantiate QueryResult objects directly using these enum values:

from sherlock_project.result import QueryResult, QueryStatus

result = QueryResult(
    username="alice",
    site_name="Twitter",
    site_url_user="https://twitter.com/alice",
    status=QueryStatus.CLAIMED,
    query_time=0.42,
)
print(str(result))          # → Claimed

print(result.status)       # → QueryStatus.CLAIMED

The notification module (sherlock_project/notify.py) translates these states into human-readable messages:

if result.status == QueryStatus.CLAIMED:
    logger.info(f"[+] {site} – {username} is CLAIMED")
elif result.status == QueryStatus.AVAILABLE:
    logger.info(f"[-] {site} – {username} is AVAILABLE")
elif result.status == QueryStatus.ILLEGAL:
    logger.warning(f"[!] {site} – {username} is ILLEGAL")
elif result.status == QueryStatus.WAF:
    logger.warning(f"[!] {site} – Request blocked by WAF")
else:  # UNKNOWN

    logger.error(f"[?] {site} – Could not determine status")

Summary

• CLAIMED confirms username existence through positive HTTP response patterns detected in sherlock_project/sherlock.py.
• AVAILABLE indicates the username is unclaimed on the target platform, typically following 404 responses.
• UNKNOWN represents indeterminate results due to errors or timeouts, serving as the safe default initialization.
• ILLEGAL flags usernames violating site-specific format constraints before any network request occurs.
• WAF identifies requests blocked by protective firewalls like Cloudflare, distinguishing active blocking from technical failures.

These five QueryStatus enum values form an exhaustive classification system defined in sherlock_project/result.py, processed in sherlock_project/sherlock.py, and rendered through sherlock_project/notify.py.

Frequently Asked Questions

What is the default QueryStatus value before Sherlock makes a request?

Before any HTTP request or validation check occurs, the code initializes query_status = QueryStatus.UNKNOWN in sherlock_project/sherlock.py. This default ensures that if the program crashes or encounters an unhandled exception, the result clearly indicates an indeterminate state rather than a false positive or negative.

How does Sherlock detect WAF blocks versus regular errors?

Sherlock distinguishes WAF from UNKNOWN by pattern matching response headers and body content against known Web Application Firewall signatures, such as Cloudflare challenge pages or specific 403/503 response patterns. While UNKNOWN covers general network or parsing failures, WAF specifically indicates the site actively blocked automated access.

Can I add custom QueryStatus values to Sherlock?

While the QueryStatus enum in sherlock_project/result.py can technically be extended, the five existing values are architecturally exhaustive for the current scanning pipeline. Adding new states would require modifications to the decision logic in sherlock_project/sherlock.py and the notification handlers in sherlock_project/notify.py to maintain consistent reporting across the entire tool.

Where does Sherlock validate usernames for the ILLEGAL status?

Username validation against site-specific regex patterns occurs early in the scanning loop within sherlock_project/sherlock.py. If a handle fails to match the site's allowable character set or length requirements, the code immediately sets query_status = QueryStatus.ILLEGAL and skips the HTTP request entirely, optimizing performance and accuracy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}