Keyword Search Guide

Endpoint: /search-by-keyword

Required Permissions: search-by-keyword

Overview

The Keyword Search endpoint enables searching for compromised credentials using specific keywords. This endpoint is particularly useful for discovering compromises related to specific services, applications, or patterns across your infrastructure.

Use Cases

Discover compromised services
Track specific applications
Monitor sensitive systems
Identify shadow IT
Track credential exposure patterns

Request Format

{
    "keywords": [
        "vpn",
        "admin",
        "portal"
    ],
    "min_employees_compromised": 10,
    "max_employees_compromised": 100,
    "min_users_compromised": 5,
    "max_users_compromised": 50,
    "last_employee_compromised": "2024-01-01T00:00:00Z",
    "last_user_compromised": "2024-01-01T00:00:00Z",
    "last_employee_uploaded": "2024-01-01T00:00:00Z",
    "last_user_uploaded": "2024-01-01T00:00:00Z",
    "cursor": "base64_encoded_cursor"
}

Required Parameters

Parameter	Type	Description	Constraints
keywords	array[string]	List of keywords to search	1-10 keywords

Optional Parameters

Parameter	Type	Description	Example
min_employees_compromised	number	Minimum employee compromises	10
max_employees_compromised	number	Maximum employee compromises	100
min_users_compromised	number	Minimum user compromises	5
max_users_compromised	number	Maximum user compromises	50
last_employee_compromised	datetime	Last employee compromise date	"2024-01-01T00:00:00Z"
last_user_compromised	datetime	Last user compromise date	"2024-01-01T00:00:00Z"
last_employee_uploaded	datetime	Last employee upload date	"2024-01-01T00:00:00Z"
last_user_uploaded	datetime	Last user upload date	"2024-01-01T00:00:00Z"
cursor	string	Pagination cursor	base64 encoded string

Common Search Patterns

1. Critical Infrastructure

{
    "keywords": [
        "vpn",
        "gateway",
        "remote"
    ],
    "min_employees_compromised": 1
}

2. Admin Interfaces

{
    "keywords": [
        "admin",
        "manage",
        "console"
    ],
    "last_employee_compromised": "2024-01-01T00:00:00Z"
}

3. Cloud Services

{
    "keywords": [
        "aws",
        "azure",
        "cloud"
    ],
    "min_employees_compromised": 5
}

Best Practices

1. Keyword Selection

Use specific terms
Consider variations
Include common misspellings
Think about abbreviations

2. Search Strategy

//Broad search with filtering
{
    "keywords": [
        "mail"
    ],
    "min_employees_compromised": 10,
    "last_employee_compromised": "2024-01-01T00:00:00Z"
}

//Specific service search
{
    "keywords": [
        "salesforce",
        "crm"
    ],
    "min_users_compromised": 5
}

3. Result Analysis

Group related findings
Track temporal patterns
Monitor compromise volumes
Analyze service patterns

Implementation Examples

Basic Keyword Search

async function searchKeywords(keywords) {
    return await api.post('/search-by-keyword', {
        keywords,
        min_employees_compromised: 1
    });
}

Paginated Search

async function getAllResults(keywords) {
    let results = [];
    let cursor = null;
    while (true) {
        const response = await api.post('/search-by-keyword', {
            keywords,
            cursor
        });
        results = results.concat(response.data);
        if (!response.nextCursor) break;
        cursor = response.nextCursor;
    }
    return results;
}

Targeted Service Search

async function monitorCriticalServices() {
    const services = [
        ["vpn", "remote"],
        ["mail", "exchange"],
        ["admin", "portal"]
    ];
    const results = await Promise.all(
        services.map(keywords => searchKeywords(keywords))
    );
    return analyzeResults(results);
}

Error Handling

Common Errors

Status	Cause	Solution
400	Empty keywords	Provide at least one keyword
400	Too many keywords	Reduce to ≤10 keywords
408	Request timeout	Reduce search scope
429	Rate limit exceeded	Implement backoff

Search Optimization

1. Keyword Optimization

Use specific terms
Combine related keywords
Avoid generic terms
Consider context

2. Filter Optimization

Set appropriate thresholds
Use date ranges effectively
Combine filters logically
Monitor result volumes

3. Performance Tips

Batch related searches
Implement caching
Use pagination
Handle timeouts

Monitoring Strategies

1. Critical Services

{
    "keywords": [
        "vpn",
        "gateway"
    ],
    "min_employees_compromised": 1,
    "last_employee_compromised": "2024-01-01T00:00:00Z"
}

2. Shadow IT Discovery

{
    "keywords": [
        "cloud",
        "storage",
        "share"
    ],
    "min_employees_compromised": 5
}

3. Compliance Monitoring

{
    "keywords": [
        "gdpr",
        "pci",
        "hipaa"
    ],
    "min_employees_compromised": 1
}

Integration Tips

1. SIEM Integration

Forward results
Create alerts
Track patterns
Monitor volumes

2. Reporting

Group findings
Track trends
Generate summaries
Highlight critical issues

3. Automation

Schedule searches
Update keywords
Process results
Generate alerts

Security Considerations

1. Keyword Management

Document keywords
Review regularly
Update patterns
Track effectiveness

2. Access Control

Limit access
Audit searches
Monitor usage
Document findings

3. Data Protection

Secure storage
Encrypt results
Control access
Set retention

Best Practices for Scale

1. Large Deployments

Batch processing
Result aggregation
Efficient filtering
Resource management

2. Performance

Optimize searches
Cache results
Handle timeouts
Monitor usage

3. Maintenance

Update keywords
Clean old results
Monitor effectiveness
Adjust thresholds