Password Search Guide

Endpoint: /search-by-password

Required Permissions: search-by-password

Overview

The Password Search endpoint allows you to search for compromised credentials using specific passwords. This endpoint is particularly useful for identifying weak password usage across your organization and detecting password reuse.

Use Cases

Detect common password usage
Find password reuse patterns
Identify weak passwords
Monitor default credentials
Track password policy violations

Request Format

{
    "passwords": [
        "Password123!",
        "Welcome2024"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "types": [
        "employees",
        "users"
    ],
    "domains": [
        "example.com"
    ],
    "filter_credentials": true,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
}

Required Parameters

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

Optional Parameters

Parameter	Type	Default	Description
sort_by	string	"date_compromised"	Sort by "date_compromised" or "date_uploaded"
sort_direction	string	"desc"	Sort direction: "asc" or "desc"
types	array[string]	all types	Filter by "employees", "users"
domains	array[string]	[]	Filter by specific domains
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

Common Password Patterns

1. Default Credentials

{
    "passwords": [
        "admin",
        "password",
        "default"
    ],
    "types": [
        "employees"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

2. Seasonal Passwords

{
    "passwords": [
        "Summer2024!",
        "Winter2024!"
    ],
    "domains": [
        "example.com"
    ],
    "types": [
        "employees"
    ]
}

3. Company-Specific

{
    "passwords": [
        "Company2024!",
        "Welcome@Company"
    ],
    "domains": [
        "company.com"
    ],
    "filter_credentials": true
}

Best Practices

1. Password Selection

Check common variations
Include seasonal patterns
Monitor default passwords
Track policy-compliant patterns

2. Search Strategy

Group related passwords
Monitor critical systems
Track temporal patterns
Analyze reuse patterns

3. Security Considerations

Handle passwords securely
Encrypt communications
Limit access to results
Document searches properly

Implementation Examples

Basic Password Search

async def search_passwords(passwords):
    return await api.post('/search-by-password', {
        'passwords': passwords,
        'sort_by': 'date_compromised',
        'filter_credentials': True
    })

Pattern Analysis

async def analyze_password_pattern(base_pattern):
    variations = generate_password_variations(base_pattern)
    results = await search_passwords(
        passwords=variations[:50],  # Respect limit
        types=['employees'],
        sort_by='date_compromised'
    )
    return analyze_results(results)

Continuous Monitoring

async def monitor_default_passwords():
    common_passwords = load_common_passwords()
    results = []
    for batch in chunk_list(common_passwords, 50):
        response = await search_passwords(
            passwords=batch,
            start_date=get_last_check_date()
        )
        results.extend(response.data)
    return analyze_findings(results)

Error Handling

Common Errors

Status	Cause	Solution
400	Empty password	Validate input
400	Too many passwords	Reduce batch size to ≤50
408	Request timeout	Reduce batch size
429	Rate limit exceeded	Implement backoff

Security Best Practices

1. Input Handling

Sanitize passwords
Remove sensitive data
Handle special characters
Validate input length

2. Result Processing

Encrypt findings
Secure storage
Limit access
Audit usage

3. Operational Security

Document searches
Track patterns
Monitor usage
Secure communications

Response Analysis

1. Pattern Detection

Password reuse
Common patterns
Policy violations
Temporal trends

2. Risk Assessment

Credential exposure
Account compromise
Password strength
Reuse impact

3. Remediation Planning

Password reset
Policy updates
User training
System hardening

Integration Tips

1. Password Policy Enforcement

Check against policy
Monitor violations
Track changes
Update requirements

2. Security Tools

SIEM integration
IDS/IPS updates
Access control
Threat intelligence

3. Incident Response

Alert generation
Case management
Response automation
Documentation

Performance Optimization

1. Search Efficiency

Batch requests
Cache results
Rate limiting
Error handling

2. Result Processing

Filter relevant data
Group findings
Analyze patterns
Generate reports

Monitoring and Alerts

1. Critical Findings

Default passwords
Policy violations
Mass reuse
New patterns

2. Metrics Tracking

Search volumes
Pattern frequency
Error rates
Response times

Compliance Considerations

1. Documentation

Search justification
Result handling
Access control
Audit trails

2. Data Protection

Password encryption
Secure storage
Access logging
Retention policies

3. Privacy

Data minimization
Purpose limitation
User notification
Rights management