Assets Discovery Guide

Overview

The Assets Discovery endpoint helps you identify and monitor potential compromises across your domains. It provides detailed insights into compromised URLs, their frequency, and the types of compromises (employee or user) affecting your digital assets.

Use Cases

• Discover compromised corporate assets
• Monitor shadow IT and unknown applications
• Track employee and user exposure across domains
• Identify high-risk applications and services
• Map your organization's digital footprint

Request Format

{
    "domains": [
        "tesla.com",
        "teslamotors.net"
    ],
    "types": [
        "employees",
        "users"
    ],
    "keywords": [
        "sso",
        "oauth2"
    ],
    "keywords_match": "any",
    "cursor": "base64_encoded_cursor"
}

Request Parameters Explained

• domains: List of domains to analyze (required, max 500)
• types: Filter by compromise type (employees/users)
• keywords: Search for specific URL patterns
• keywords_match: Match 'any' or 'all' keywords
• cursor: Pagination token for large result sets

Understanding the Response

Each discovery result contains:

{
    "data": [
        {
            "_id": "6385de3f6dcd5e5341f8dcff",
            "url": "https://sso.tesla.com/adfs/ls",
            "domain": "tesla.com",
            "type": "employee",
            "last_uploaded_date": "2025-01-15T23:43:40.481Z",
            "occurrence": 174
        }
    ],
    "nextCursor": "base64_encoded_next_cursor" || null // null if no more results
}

Response Fields

• _id: Internal unique identifier used for pagination
• url: The complete URL where compromise occurred
• domain: Associated root domain
• type: Compromise type (employee/user)
• last_uploaded_date: Most recent compromise date
• occurrence: Number of times this URL was compromised
• nextCursor: Token for fetching next page of results (based on occurrence + _id combo)

Best Practices

1. Domain Management

• Start with your primary domains
• Include subdomains and related domains
• Consider regional domains
• Monitor acquired company domains

2. Type Filtering

• employees: Focus on corporate credential exposure
• users: Track customer/external user compromises
• Use both types for comprehensive monitoring

3. Keyword Strategy

{
    "keywords": [
        "admin",
        "portal",
        "auth",
        "login"
    ],
    "keywords_match": "any"
}

• Target critical systems
• Include common application paths
• Consider multiple languages
• Use all for specific combinations

4. Pagination

• Use cursor-based pagination for large datasets
• Store cursors for continuous monitoring
• Implement retry logic for timeouts

Common Search Patterns

1. Critical Infrastructure Discovery

{
    "domains": [
        "example.com"
    ],
    "keywords": [
        "vpn",
        "admin",
        "remote",
        "gateway"
    ],
    "keywords_match": "any"
}

2. Employee Access Monitoring

{
    "domains": [
        "example.com"
    ],
    "types": [
        "employees"
    ],
    "keywords": [
        "mail",
        "collaboration",
        "docs"
    ],
    "keywords_match": "any"
}

3. Customer Portal Security

{
    "domains": [
        "example.com"
    ],
    "types": [
        "users"
    ],
    "keywords": [
        "account",
        "portal",
        "login"
    ],
    "keywords_match": "any"
}

Risk Assessment Framework

High Risk Indicators

1. High occurrence counts
2. Critical system URLs
3. Admin/management interfaces
4. Recent upload dates
5. Multiple compromise types

Medium Risk Indicators

1. Moderate occurrence counts
2. Non-critical business applications
3. Older upload dates
4. Single compromise type

Low Risk Indicators

1. Low occurrence counts
2. Public-facing content
3. Old upload dates
4. Infrequent appearances

Implementation Strategy

1. Initial Discovery

1. List all known domains
2. Run broad search without keywords
3. Analyze results for patterns
4. Identify unknown assets

2) Continuous Monitoring

1. Schedule regular scans
2. Track new appearances
3. Monitor occurrence changes
4. Set up alerts for critical assets

3) Incident Response Integration

1. Automate discovery checks
2. Feed results to SIEM
3. Create incident tickets
4. Track remediation progress

Error Handling

• 400: Validate domain format and count
• 403: Check API key permissions
• 408: Implement backoff strategy
• 500: Retry with smaller scope

Performance Optimization

1. Batch domain requests
2. Cache frequent searches
3. Implement rate limiting
4. Use pagination for large results

Security Considerations

1. Secure API credentials
2. Limit access to results
3. Encrypt stored data
4. Audit search patterns

Integration Examples

Continuous Monitoring Script

async def monitor_domains(domains):
    cursor = None
    while True:
        try:
            response = await discovery_search(
                domains=domains,
                cursor=cursor
            )
            process_results(response.data)
            cursor = response.nextCursor
            if not cursor:
                break
        except TimeoutError:
            await asyncio.sleep(5)

Alert Integration

def analyze_discovery(results):
    for item in results:
        if item['occurrence'] > THRESHOLD:
            alert_security_team(item)
        if is_critical_asset(item['url']):
            create_incident_ticket(item)

Reporting Tips

1. Group findings by domain
2. Track occurrence trends
3. Highlight critical assets
4. Monitor type distribution
5. Calculate risk scores