Username Search Guide

Endpoint: /search-by-login/usernames

Required Permissions: search-by-login

Overview

The Username Search endpoint enables searching for compromised credentials using usernames. This endpoint is valuable for identifying credential exposures across various services and domains where specific usernames are used.

Use Cases

Track username compromise across multiple services
Monitor corporate username patterns
Investigate potential account takeovers
Identify credential reuse
Track compromised service accounts

Request Format

{
    "logins": [
        "admin_user",
        "service_account"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "types": [
        "employees",
        "users"
    ],
    "domains": [
        "example.com"
    ],
    "keywords": [
        "vpn",
        "admin"
    ],
    "keywords_match": "any",
    "filter_credentials": true,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
}

Required Parameters

Parameter	Type	Description	Constraints
logins	array[string]	List of usernames to search	1-50 usernames

Optional Parameters

Parameter	Type	Default	Description
sort_by	string	"date_compromised"	Sort results by "date_compromised" or "date_uploaded"
sort_direction	string	"desc"	Sort direction: "asc" or "desc"
types	array[string]	all types	Filter by "employees", "users", or "third_parties"
domains	array[string]	[]	Filter results by specific domains
keywords	array[string]	[]	Filter URLs containing specific keywords
keywords_match	string	"any"	Match "any" or "all" keywords
filter_credentials	boolean	true	Return only matched credentials
start_date	datetime	null	Filter results after this date
end_date	datetime	null	Filter results before this date

Response Structure

{
    "data": [
        {
            "stealer": "string",
            "date_compromised": "2024-02-27T10:53:48.989Z",
            "date_uploaded": "2024-02-27T10:53:48.989Z",
            "stealer_family": "string",
            "ip": "string",
            "computer_name": "string",
            "operating_system": "string",
            "credentials": [
                {
                    "url": "string",
                    "domain": "string",
                    "username": "string",
                    "password": "string",
                    "type": "employee"
                }
            ]
        }
    ],
    "nextCursor": "base64_encoded_cursor"
}

Response Fields

Field	Type	Required	Description
stealer	string	Yes	Unique identifier of the stealer
date_compromised	datetime	Yes	Date when credentials were compromised
date_uploaded	datetime	Yes	Date when data was uploaded to our system
stealer_family	string	No	Family/type of the stealer malware
ip	string	No	IP address of the compromised machine
computer_name	string	No	Name of the compromised computer
operating_system	string	No	OS of the compromised machine
credentials	array	Yes	Array of compromised credentials
nextCursor	string	No	Pagination cursor for next page

Best Practices

1. Username Preparation

Remove leading/trailing whitespace
Consider case sensitivity
Group similar usernames
Check for common variations

2. Search Optimization


{
"logins": ["admin_user"],
"filter_credentials": true,
"types": ["employees"],
"keywords": ["admin", "portal"],
"keywords_match": "all"
}

3. Common Username Patterns

Service accounts: svc_ followed by service name (e.g., svc_backup, svc_jenkins)
Admin accounts: admin_ followed by department/function (e.g., admin_it, admin_finance)
System accounts: system_ or sys_ followed by application name (e.g., system_db, sys_monitor)
Generic accounts: backup_ followed by scope (e.g., backup_prod, backup_dev)

Note: Our search does not support wildcards. The examples above show common prefixes - you'll need to search for complete usernames.

Search Strategies

1. Service Account Monitoring

{
    "logins": [
        "svc_backup",
        "svc_admin"
    ],
    "types": [
        "employees"
    ],
    "keywords": [
        "admin",
        "backup",
        "storage"
    ],
    "keywords_match": "any"
}

2. Admin Account Search

{
    "logins": [
        "admin",
        "administrator"
    ],
    "domains": [
        "internal.company.com"
    ],
    "types": [
        "employees"
    ],
    "keywords": [
        "portal",
        "admin",
        "manage"
    ],
    "keywords_match": "any"
}

3. Generic Account Pattern

{
    "logins": [
        "backup",
        "readonly",
        "monitor"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "start_date": "2024-01-01T00:00:00Z"
}

Error Handling

Common Errors

Status	Cause	Solution
400	Empty username	Validate input before sending
400	Too many usernames	Reduce batch size to ≤50
408	Request timeout	Reduce batch size or retry
429	Rate limit exceeded	Implement backoff strategy

Implementation Examples

Basic Search

async def search_usernames(usernames):
    return await api.post('/search-by-login/usernames', {
        'logins': usernames,
        'filter_credentials': True,
        'sort_by': 'date_compromised'
    })

Paginated Search

async def get_all_results(usernames):
    results = []
    cursor = None
    while True:
        response = await search_usernames(usernames, cursor)
        results.extend(response.data)
        if not response.nextCursor:
            break
        cursor = response.nextCursor
    return results

Pattern Search

async def search_pattern(pattern, domain):
    usernames = generate_username_variations(pattern)
    return await search_usernames(
        usernames[:50],  # Respect limit
        domains=[domain],
        types=["employees"]
    )

Security Best Practices

1. Input Validation

Validate username format
Check for malicious patterns
Limit username length
Remove special characters

2. Result Handling

Encrypt sensitive data
Limit access to results
Implement audit logging
Set data retention policies

3. Rate Limiting

Implement client-side limits
Use exponential backoff
Cache frequent searches
Monitor usage patterns

Monitoring and Alerts

1. Critical Patterns

Monitor admin account exposure
Track service account compromises
Alert on sensitive system accounts
Watch for pattern-based attacks

2. Volume Monitoring

Track search volumes
Monitor error rates
Alert on unusual patterns
Track response times

3. Result Analysis

Group similar compromises
Track compromise patterns
Monitor credential reuse
Analyze temporal patterns

Integration Tips

1. Automation

Schedule regular searches
Automate response actions
Integrate with SIEM
Set up alerting workflows

2. Result Processing

Deduplicate findings
Correlate across searches
Track historical data
Generate reports

3. Performance

Implement caching
Use batch processing
Handle timeouts gracefully
Monitor API limits