docs(crowdstrike): name each tool and the API scope it needs - #464
Open
leet-c1 wants to merge 4 commits into
Open
docs(crowdstrike): name each tool and the API scope it needs#464leet-c1 wants to merge 4 commits into
leet-c1 wants to merge 4 commits into
Conversation
The page told admins to grant "Read access to Detections, Incidents, and Hosts", which does not map to the tools C1 actually exposes and leaves the most confusing case undocumented. Adds a Choose API scopes section mapping each tool group to its Falcon API scope, covering hosts, alerts, incidents, indicators of compromise, device control policies, Spotlight vulnerabilities, Falcon Intelligence, Zero Trust Assessment, Falcon Discover, and cloud misconfigurations. Calls out the trap behind a real support question: the cloud misconfiguration tools need CSPM registration, not Cloud Security API Detections. The two scopes authorize different Falcon APIs, so an admin who enables the latter sees 403s on those tools while everything else works. Also documents the write scopes the response tools need (Hosts and IOC Manager), since the previous text implied Read was sufficient for the whole surface, and notes that a read-only API client is a deliberate way to keep response actions unavailable. Scope edits apply on the next token request, so admins do not need to re-register the server.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The scope tables labelled their rows with invented category names — "Cloud misconfigurations (IOM)", "Threat actors, indicators, and reports", "Indicators of compromise" — none of which appear in the product, the server's tool list, or the Falcon console. A reader with 14 tools in front of them had no way to match a row to a tool, which is the one thing the table exists to do. Rows are now the tool names the server actually exposes, taken from the impl's own surface: list_hosts, list_alerts, list_incidents, list_ioc_indicators, list_device_control_policies, list_vulnerabilities, list_remediations, list_intel_actors, list_intel_indicators, list_intel_reports, list_zero_trust_assessments, list_discover_applications, list_ioms, list_iom_details, and the four write tools contain_host, lift_containment, hide_host and create_ioc_indicator. All 14 read tools are covered. The groupings are not editorial: they follow the CrowdStrike spec's own operation tags, so list_vulnerabilities and list_remediations share a row because both endpoints are tagged spotlight_vulnerabilities, and the three intel tools share one because all three are tagged intel. The note said the IOM tools need CSPM registration "not Cloud Security API Detections", naming a console string I had not verified, and referred to the tool as crowdstrike_list_ioms — a prefix this server does not apply. It now names list_ioms and list_iom_details and says what is actually checkable: the Cloud Security scope covers cloud groups and cloud risks, endpoints C1 does not expose, so it cannot make these two tools work. The CSPM registration mapping itself is evidence-based — both IOM endpoints are tagged cspm_registration in the spec. The reviewer note now says exactly which column is verified and which is not: the tool names are exact, the Falcon console scope labels still need a check against a real tenant.
leet-c1
changed the title
vipulgowda
approved these changes
Aug 25, 2026
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
mindymo
approved these changes
Aug 26, 2026
mindymo
left a comment
mindymo
left a comment
Collaborator
There was a problem hiding this comment.
Reviewed from a docs style perspective, and a few changes pushed. Good to go on my end, but not sure if the open questions need to be resolved before merge.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this fixes
The page told admins to grant "Read access to Detections, Incidents, and Hosts". The server exposes 14 read tools across nine different Falcon APIs, so that sentence leaves most of them unauthorized and names one product ("Detections") that no tool actually reads.
Changes
A
Choose API scopessection listing every tool by name against the Falcon API scope it needs —list_hosts,list_alerts,list_incidents,list_ioc_indicators,list_device_control_policies,list_vulnerabilities,list_remediations,list_intel_actors,list_intel_indicators,list_intel_reports,list_zero_trust_assessments,list_discover_applications,list_ioms,list_iom_details. All 14 are covered.The groupings are not editorial. They follow the CrowdStrike spec's own operation tags:
list_vulnerabilitiesandlist_remediationsshare a row because both endpoints are taggedspotlight_vulnerabilities, and the three intel tools share one because all three are taggedintel.The CSPM registration point, in a
<Note>.list_iomsandlist_iom_detailsneed CSPM registration; CrowdStrike's Cloud Security scope covers cloud groups and cloud risks — endpoints this server does not expose — so reaching for it by name will not make these two tools work. Both IOM endpoints are taggedcspm_registrationin the spec, which is where the mapping comes from.The write scopes, which the page previously implied were unnecessary.
contain_host,lift_containmentandhide_hostneed Write on Hosts;create_ioc_indicatorneeds Write on IOC Manager. Also states the useful inverse: leaving Write off is a deliberate way to keep the connection read-only, since those four tools then fail and the rest keep working.Scope-change timing — edits apply on the next token request, so admins do not need to re-register the server or reconnect.
Where this came from, accurately
A customer asked for IOM coverage and mentioned they would grant the Cloud Security API Detections read scope. Separately, they reported not seeing the IOM tools at all after syncing.
Those were two different problems and only one of them is a docs problem. The missing tools were a generator bug — a resource-type collision that dropped the endpoints before they ever reached the surface — fixed in
mcp-axiomaticand unrelated to scopes. The tools are also namedlist_iomsandlist_iom_details, not thelist_query_ioms/list_entity_iomsthe request guessed at, which is worth knowing if someone is searching their tool list for those strings.The scope guidance here is preventive rather than a post-mortem: the scope they named would not have authorized these tools, so it is documented before it costs anyone time. An earlier draft of this PR described an admin hitting 403s with every other tool working — that did not happen, and I have removed it.
Notes for review
REVIEWER NOTEin the page says so. The mapping behind each row is evidence-based (spec operation tags); it is the console's display strings that need a human with Falcon access.npx mint broken-linksreports 12 broken links in 5 files, all pre-existing (baton/bamboohr.mdximages,/docs-prefixed links inbaton/sendgrid.mdx,baton/twilio-segment-v2.mdxandindex.mdx, and theconnector-template.mdxplaceholder). None are on this page.docs.json, so the nav is unchanged. Both in-page links to#choose-api-scopesresolve.