Skip to content

Commit 60f899a

Browse files
yatukyatuk
committed
feat(modules/ods): add On-Demand Scan support
1 parent 17fea06 commit 60f899a

13 files changed

Lines changed: 629 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Full docs are available at **[developer.crowdstrike.com/falcon-mcp](https://deve
4444
| [Intel](https://developer.crowdstrike.com/falcon-mcp/modules/intel/) | Research threat actors, IOCs, and intelligence reports |
4545
| [IOC](https://developer.crowdstrike.com/falcon-mcp/modules/ioc/) | Search, create, and remove custom indicators of compromise |
4646
| [NGSIEM](https://developer.crowdstrike.com/falcon-mcp/modules/ngsiem/) | Execute CQL queries against Next-Gen SIEM |
47+
| [On-Demand Scan](https://developer.crowdstrike.com/falcon-mcp/modules/ods/) | Search ODS results, launch and cancel scans, and manage scheduled scans |
4748
| [Policies](https://developer.crowdstrike.com/falcon-mcp/modules/policies/) | Search, create, update, and delete prevention, sensor update, firewall, device control, response, and content update policies; manage host-group assignment, enable/disable, and precedence |
4849
| [Quarantine](https://developer.crowdstrike.com/falcon-mcp/modules/quarantine/) | Search quarantine records, preview action counts, and release, unrelease, or delete quarantined files |
4950
| [Real Time Response](https://developer.crowdstrike.com/falcon-mcp/modules/rtr/) | Audit, summarize, and run read-only RTR triage workflows |

‎docs/modules/ods.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<!-- meta:title On-Demand Scan -->
2+
<!-- meta:description Search ODS results, launch and cancel scans, and manage scheduled scans. -->
3+
<!-- meta:section modules -->
4+
<!-- meta:link-base /falcon-mcp/ -->
5+
<!-- frontmatter:sidebar order:10 -->
6+
7+
Search ODS results, launch and cancel scans, and manage scheduled scans.
8+
9+
## API Scopes
10+
11+
- `On-demand scans (ODS):read`
12+
- `On-demand scans (ODS):write`
13+
14+
## Tools
15+
16+
### `falcon_search_ods_scans`
17+
18+
**Required scopes:** `On-demand scans (ODS):read`
19+
20+
Search ODS scans and return full scan entities with pagination.
21+
22+
**Example prompts:**
23+
24+
- "Show completed ODS scans that found malicious files"
25+
26+
### `falcon_search_ods_scan_hosts`
27+
28+
**Required scopes:** `On-demand scans (ODS):read`
29+
30+
Search per-host ODS scan results and return full metadata.
31+
32+
**Example prompts:**
33+
34+
- "Which hosts in scan scan-123 found malicious files?"
35+
36+
### `falcon_search_ods_malicious_files`
37+
38+
**Required scopes:** `On-demand scans (ODS):read`
39+
40+
Search malicious files found by ODS and return full file records.
41+
42+
**Example prompts:**
43+
44+
- "List quarantined files found by scan scan-123"
45+
46+
### `falcon_search_ods_scheduled_scans`
47+
48+
**Required scopes:** `On-demand scans (ODS):read`
49+
50+
Search scheduled ODS scans and return full schedule definitions.
51+
52+
**Example prompts:**
53+
54+
- "Show active scheduled ODS scans"
55+
56+
### `falcon_launch_ods_scan`
57+
58+
> [!NOTE]
59+
> This tool modifies data.
60+
61+
**Required scopes:** `On-demand scans (ODS):write`
62+
63+
Start an ODS scan against explicit hosts or host groups.
64+
65+
**Example prompts:**
66+
67+
- "Scan C:\Temp on host aid-123 without quarantining files"
68+
69+
### `falcon_cancel_ods_scans`
70+
71+
> [!CAUTION]
72+
> This tool performs destructive operations.
73+
74+
**Required scopes:** `On-demand scans (ODS):write`
75+
76+
Cancel active ODS scans by explicit scan ID.
77+
78+
**Example prompts:**
79+
80+
- "Cancel ODS scan scan-123"
81+
82+
### `falcon_schedule_ods_scan`
83+
84+
> [!NOTE]
85+
> This tool modifies data.
86+
87+
**Required scopes:** `On-demand scans (ODS):write`
88+
89+
Create a recurring or future ODS scan schedule.
90+
91+
**Example prompts:**
92+
93+
- "Schedule a daily scan of /tmp on this Linux host"
94+
95+
### `falcon_delete_ods_scheduled_scans`
96+
97+
> [!CAUTION]
98+
> This tool performs destructive operations.
99+
100+
**Required scopes:** `On-demand scans (ODS):write`
101+
102+
Delete ODS schedules by explicit IDs.
103+
104+
**Example prompts:**
105+
106+
- "Delete scheduled ODS scan schedule-123"
107+
108+
## Resources
109+
110+
- **`falcon://ods/scans/fql-guide`**: FQL guide for the falcon_search_ods_scans tool.
111+
- **`falcon://ods/scan-hosts/fql-guide`**: FQL guide for the falcon_search_ods_scan_hosts tool.
112+
- **`falcon://ods/malicious-files/fql-guide`**: FQL guide for the falcon_search_ods_malicious_files tool.
113+
- **`falcon://ods/scheduled-scans/fql-guide`**: FQL guide for the falcon_search_ods_scheduled_scans tool.

‎docs/modules/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ The Falcon MCP Server provides the following modules. Each module requires speci
2626
| [Intel](/falcon-mcp/modules/intel/) | `Actors (Falcon Intelligence):read`, `Indicators (Falcon Intelligence):read`, `Reports (Falcon Intelligence):read` | Accessing and analyzing CrowdStrike Falcon intelligence data |
2727
| [IOC](/falcon-mcp/modules/ioc/) | `IOC Management:read`, `IOC Management:write` | Searching, creating, and deleting custom IOCs using Falcon IOC Service Collection endpoints |
2828
| [NGSIEM](/falcon-mcp/modules/ngsiem/) | `NGSIEM:read`, `NGSIEM:write` | Running search queries against CrowdStrike's Next-Gen SIEM via the asynchronous job-based search API |
29+
| [On-Demand Scan](/falcon-mcp/modules/ods/) | `On-demand scans (ODS):read`, `On-demand scans (ODS):write` | Search ODS results, launch and cancel scans, and manage scheduled scans. |
2930
| [Policies](/falcon-mcp/modules/policies/) | `Content Update Policies:read`, `Device Control Policies:read`, `Firewall Management:read`, `Prevention Policies:read`, `Response Policies:read`, `Sensor Update Policies:read`, `Content Update Policies:write`, `Device Control Policies:write`, `Firewall Management:write`, `Prevention Policies:write`, `Response Policies:write`, `Sensor Update Policies:write` | This module provides a unified set of tools for managing CrowdStrike host-based policies across all six policy types — prevention, sensor_update, firewall, device_control, response, and content_update — behind a single `policy_type` discriminator |
3031
| [Quarantine](/falcon-mcp/modules/quarantine/) | `Quarantined Files:read`, `Quarantined Files:write` | Investigating quarantined files and applying quarantine actions during triage and remediation workflows |
3132
| [Recon](/falcon-mcp/modules/recon/) | `Monitoring rules (Falcon Intelligence Recon):read` | Searching Falcon Intelligence Recon notifications, monitoring rules, and exposed-data records |

‎falcon_mcp/common/api_scopes.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,19 @@
294294
# The key and the scope keep the API-side "AIDR" spelling on purpose: the MCP
295295
# tools are named "guardian", but the platform names this API surface AIDR.
296296
"aidr_events_query": ["AIDR:read"],
297+
# On-Demand Scan operations
298+
"query_scans": ["On-demand scans (ODS):read"],
299+
"get_scans_by_scan_ids_v2": ["On-demand scans (ODS):read"],
300+
"query_scan_host_metadata": ["On-demand scans (ODS):read"],
301+
"get_scan_host_metadata_by_ids": ["On-demand scans (ODS):read"],
302+
"query_malicious_files": ["On-demand scans (ODS):read"],
303+
"get_malicious_files_by_ids": ["On-demand scans (ODS):read"],
304+
"query_scheduled_scans": ["On-demand scans (ODS):read"],
305+
"get_scheduled_scans_by_scan_ids": ["On-demand scans (ODS):read"],
306+
"create_scan": ["On-demand scans (ODS):write"],
307+
"cancel_scans": ["On-demand scans (ODS):write"],
308+
"schedule_scan": ["On-demand scans (ODS):write"],
309+
"delete_scheduled_scans": ["On-demand scans (ODS):write"],
297310
}
298311

299312

‎falcon_mcp/dynamic.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ def search(
235235
self,
236236
query: str = "",
237237
module: str | None = None,
238-
limit: int = 50,
238+
limit: int = 75,
239239
tool_names: list[str] | None = None,
240240
) -> list[dict[str, Any]]:
241241
"""Return catalog entries, with the input schema only when tools are named.
@@ -550,9 +550,9 @@ async def _search_tools(
550550
Field(
551551
ge=1,
552552
le=500,
553-
description="Maximum number of results to return (default: 50, max: 500). Ignored when tool_names is given.",
553+
description="Maximum number of results to return (default: 75, max: 500). Ignored when tool_names is given.",
554554
),
555-
] = 50,
555+
] = 75,
556556
tool_names: Annotated[
557557
list[str] | None,
558558
Field(

‎falcon_mcp/filter_hints.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,24 @@
77
"""
88

99
FILTER_HINTS: dict[str, str] = {
10+
# === On-Demand Scan ===
11+
"falcon_search_ods_scans": (
12+
"Common fields: id, description, initiated_from, status, severity, "
13+
"filecount.scanned, filecount.malicious, scan_started_on, scan_completed_on, created_on. "
14+
"Ex: status:'completed'+filecount.malicious:>0"
15+
),
16+
"falcon_search_ods_scan_hosts": (
17+
"Common fields: id, scan_id, host_id, status, severity, filecount.malicious, "
18+
"started_on, completed_on, last_updated. Ex: scan_id:'<scan-id>'+filecount.malicious:>0"
19+
),
20+
"falcon_search_ods_malicious_files": (
21+
"Common fields: id, scan_id, host_id, filepath, filename, hash, severity, quarantined, "
22+
"last_updated. Ex: scan_id:'<scan-id>'+quarantined:true"
23+
),
24+
"falcon_search_ods_scheduled_scans": (
25+
"Common fields: id, description, status, schedule.start_timestamp, schedule.interval, "
26+
"created_on, last_updated, deleted. Ex: status:'active'+deleted:false"
27+
),
1028
# === AgentWorks ===
1129
"falcon_search_agentworks_agents": (
1230
"Common fields: template_id, active_version.model "

0 commit comments

Comments
 (0)