File Search Guide

Endpoint: /search-by-file

Required Permissions: search-by-file

Overview

The File Search endpoint allows you to search for compromised credentials based on file names. This endpoint is particularly useful for tracking sensitive files, configuration files, and credential stores that may have been exposed.

Use Cases

Track sensitive file exposure
Monitor configuration files
Detect credential store leaks
Track source code exposure
Identify data breaches

Request Format

{
    "file_name": "aws-credentials",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z",
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "cursor": "base64_encoded_cursor"
}

Required Parameters

Parameter	Type	Description	Example
file_name	string	Name of file to search for	"aws-key"

Optional Parameters

Parameter	Type	Description	Default
start_date	datetime	Start date for search	null
end_date	datetime	End date for search	null
sort_by	string	Sort field (date_compromised/date_uploaded)	"date_compromised"
sort_direction	string	Sort direction (asc/desc)	"desc"
cursor	string	Pagination cursor	null

Common Search Patterns

1. Cloud Credentials

{
    "file_name": "aws key",
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

2. Configuration Files

{
    "file_name": "config.yaml",
    "start_date": "2024-01-01T00:00:00Z"
}

3. Key Files

{
    "file_name": "id_rsa",
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

Best Practices

1. File Name Selection

Use exact file names
Consider extensions
Include common variations
Track related files

2. Search Strategy

// Critical file monitoring
{
    "file_name": "database.config",
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

// Historical analysis
{
    "file_name": "secrets.yml",
    "start_date": "2023-01-01T00:00:00Z",
    "end_date": "2023-12-31T23:59:59Z"
}

Implementation Examples

Basic File Search

async function searchFile(fileName) {
    return await api.post('/search-by-file', {
        file_name: fileName,
        sort_by: 'date_compromised',
        sort_direction: 'desc'
    });
}

Paginated Search

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

Critical Files Monitoring

async function monitorCriticalFiles() {
    const criticalFiles = [
        "wp-config.php",
        ".env",
        "id_rsa",
        "credentials.json"
    ];
    return Promise.all(
        criticalFiles.map(file => searchFile(file))
    );
}

Common File Patterns to Monitor

1. Configuration Files

.env
config.json
settings.yaml
wp-config.php

2. Credential Files

credentials.json
aws-credentials
azure.config
gcp-key.json

3. Key Files

id_rsa
private.key
cert.pem
keystore.jks

Error Handling

Common Errors

Status	Cause	Solution
400	Invalid file name	Validate input
400	Invalid date format	Use ISO 8601
408	Request timeout	Implement retry
429	Rate limit exceeded	Add backoff

Search Optimization

1. File Name Optimization

Use specific names
Include extensions
Consider variations
Track patterns

2. Date Range Usage

Set appropriate ranges
Use recent dates first
Split large ranges
Track temporal patterns

3. Performance Tips

Implement caching
Use pagination
Handle timeouts
Batch related searches

Monitoring Strategies

1. Real-time Monitoring

{
    "file_name": "secrets.yaml",
    "sort_by": "date_compromised",
    "sort_direction": "desc"
}

2. Historical Analysis

{
    "file_name": "database.config",
    "start_date": "2023-01-01T00:00:00Z",
    "end_date": "2023-12-31T23:59:59Z"
}

Integration Tips

1. SIEM Integration

Forward findings
Create alerts
Track patterns
Monitor volumes

2. DevSecOps Integration

Monitor CI/CD files
Track config files
Alert on exposures
Automate responses

3. Incident Response

Document findings
Track remediation
Update policies
Monitor effectiveness

Security Considerations

1. File Pattern Management

Document patterns
Review regularly
Update monitoring
Track effectiveness

2. Access Control

Limit access
Audit searches
Monitor usage
Secure results

3. Data Protection

Encrypt findings
Secure storage
Control access
Set retention

Best Practices for Scale

1. Large Environments

Batch processing
Result aggregation
Efficient filtering
Resource management

2. Performance

Optimize searches
Cache results
Handle timeouts
Monitor usage

3. Maintenance

Update patterns
Clean old results
Monitor effectiveness
Adjust monitoring