[Feature Request]: Add Exposure Management and External Attack Surface module

[yatuk]

Feature Description

Add an Exposure Management module for external attack surface investigation and management. The module should support searching and aggregating external assets, retrieving full asset records, browsing discovered subsidiaries, and managing manually supplied assets.

Proposed FalconPy operations:

• query_external_assets_v2
• get_external_assets
• aggregate_external_assets
• combined_ecosystem_subsidiaries
• post_external_assets_inventory_v1
• patch_external_assets
• delete_external_assets

Required OAuth scopes:

• Assets:read
• Assets:write for mutation tools

Proposed MCP tools:

• falcon_search_external_assets
• falcon_get_external_assets
• falcon_aggregate_external_assets
• falcon_search_ecosystem_subsidiaries
• falcon_add_external_assets
• falcon_update_external_assets
• falcon_delete_external_assets

Use Case

As a security analyst, I want an MCP client to investigate internet-facing assets and help prioritize external exposure without manually moving between inventory views.

Example workflows:

• Find internet-exposed assets seen during the last seven days.
• Group exposed assets by type, criticality, country, perimeter, or triage status.
• Identify assets associated with a discovered subsidiary.
• Add a domain or IP address for external scanning.
• Update asset criticality or triage metadata.
• Remove a manually managed asset that is no longer in scope.

Spotlight covers vulnerabilities and Discover covers internal asset inventory, but neither exposes the full external asset and subsidiary workflow.

Related Module/Area

New module needed

Proposed Solution

Implement an ExposureManagementModule using the existing BaseModule architecture.

Important implementation details:

• Use the v2 external asset query endpoint for after based pagination.
• Hydrate query IDs with get_external_assets and restore the query order before returning results.
• Return standard pagination envelopes and include FQL guidance on filter errors.
• Expose a terms aggregation tool using the shared aggregate helper.
• Preserve the subsidiary version_id parameter across pages to avoid stale inventory reads.
• Mark add and update tools as mutating, and mark delete as destructive.
• Add API scope mappings, FQL resources, dynamic-mode filter hints, tests, generated documentation, and README coverage.

Relevant analogous modules include discover.py for asset inventory, spotlight.py for cursor pagination, and quarantine.py for mutation annotations.

Alternatives Considered

The existing Discover and Spotlight modules can answer parts of an exposure question, but they cannot query external asset records, subsidiary relationships, or external asset triage state.

Additional Context

Falcon API reference:

https://developer.crowdstrike.com/api-reference/collections/exposure-management/