IP/CIDR Search Guide

Endpoint: /search-by-ip

Required Permissions: search-by-ip

Overview

The IP/CIDR Search endpoint allows you to search for compromises associated with specific IP addresses or CIDR ranges. This endpoint is crucial for identifying compromises within your network infrastructure or investigating specific IP-based incidents.

Use Cases

Monitor corporate network compromises
Investigate security incidents
Track compromises across IP ranges
Identify affected infrastructure
Analyze remote work exposure

Request Format

IP Addresses Search

{
    "ips": [
        "67.181.31.229",
        "187.156.204.104"
    ],
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "filter_credentials": true,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
}

CIDR Range Search

{
    "cidr": "45.166.26.62/28",
    "sort_by": "date_compromised",
    "sort_direction": "desc",
    "filter_credentials": true,
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z"
}

Required Parameters (One of)

Parameter	Type	Description	Constraints
ips	array[string]	List of IP addresses	1-50 IPs, IPv4 format
cidr	string	CIDR range	Valid CIDR 21-32

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"
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"
}

Best Practices

1. IP Address Format

Use IPv4 format only
Validate IP addresses before sending
Remove duplicates
Consider private vs public IPs

2. CIDR Range Tips

Use appropriate subnet sizes (/21-/32)
Consider network boundaries
Split large ranges into smaller chunks
Monitor response times for large ranges

Implementation Examples

Basic IP Search

async def search_ips(ips):
    return await api.post('/search-by-ip', {
        'ips': ips,
        'sort_by': 'date_compromised',
        'sort_direction': 'desc'
    })

CIDR Range Search

async def search_cidr(cidr_range):
    return await api.post('/search-by-ip', {
        'cidr': cidr_range,
        'filter_credentials': True
    })

Paginated Search

async def get_all_results(ips=None, cidr=None):
    cursor = None
    results = []
    while True:
        payload = {'cursor': cursor}
        if ips:
            payload['ips'] = ips
        if cidr:
            payload['cidr'] = cidr
        response = await api.post('/search-by-ip', payload)
        results.extend(response.data)
        if not response.nextCursor:
            break
        cursor = response.nextCursor
    return results

Error Handling

Common Errors

Status	Cause	Solution
400	Invalid IP format	Validate IP format
400	Invalid CIDR range	Check CIDR notation
400	Too many IPs	Reduce batch size to ≤50
408	Request timeout	Reduce CIDR range size

Security Best Practices

1. Input Validation

Validate IP format
Check CIDR range boundaries
Sanitize inputs
Validate network ownership

2. Network Security

Monitor sensitive IP ranges
Track changes over time
Alert on critical infrastructure
Document searched ranges

3. Data Handling

Encrypt sensitive data
Implement access controls
Log search patterns
Set retention policies

Performance Optimization

1. CIDR Searches

Start with smaller ranges
Split large ranges
Cache frequent searches
Monitor timeouts

2. Batch Processing

Group related IPs
Implement rate limiting
Use pagination
Handle partial results

Monitoring and Alerts

1. Critical Infrastructure

Monitor key IP ranges
Track compromise patterns
Alert on new findings
Monitor search volumes

2. Result Analysis

Group related compromises
Track temporal patterns
Identify attack patterns
Monitor credential exposure

Integration Tips

1. SIEM Integration

Forward results to SIEM
Correlate with other data
Create alerts
Track incidents

2. Automation

Schedule regular scans
Automate responses
Update IP inventories
Generate reports

3. Compliance

Document searches
Track sensitive assets
Maintain audit logs
Report on findings