Skip to main content

Custom IOA

Custom IOA is the Falcon Custom IOA collection for this CID. Paths are under /ioarules/…. Pattern catalogs, query-rule-groups-full, POST rules/GET/v1, update-rules-v2, validate, Falcon field_values / disposition_id / ruletype_id / comment / rulegroup_version, and IOA exclusions (/policy/entities/ioa-exclusions) are not implemented.

This collection is not CrowdStrike production. It does not call Falcon cloud.

RPC field notes: CustomIoaService. REST schemas: API reference. Filter syntax: FQL.

These curls use Host: crowdstrike-api.localhost against Compose Traefik on :8088. If the hostname already resolves to Traefik, you can omit the Host header and call http://crowdstrike-api.localhost instead.

Auth​

Every call needs a console session or a Bearer token:

  • Cookie cs_console from CreateSession (POST /identity/entities/sessions/v1)
  • Authorization: Bearer with custom-ioa:read for query and get
  • custom-ioa:write for create, patch, and delete

A session cookie bypasses OAuth scopes. Seed client cs-local-hosts (hosts:read only) cannot query rule groups or rules (403). Unit tests use a client named cs-local-ioa; that client is not in the production seed. There is no seeded client with custom-ioa:read — use the console cookie, or a client you created with that scope.

HTTP paths​

MethodPathUse
GET/ioarules/queries/rule-groups/v1Query group ids. Query: filter, limit, offset, sort (name.asc / name.desc / platform.asc / enabled.asc and matching .desc). Empty filter returns all ids.
GET/ioarules/entities/rule-groups/v1?ids=Get groups. Missing id → 200 with only found resources.
POST/ioarules/entities/rule-groups/v1Create group. Body { "name", "description", "platform" } at the top level. Empty name → 400. Unknown platform → 400. Success 201. Starts enabled true.
PATCH/ioarules/entities/rule-groups/v1Update group. Body { "id", "name", "description", "enabled" }.
DELETE/ioarules/entities/rule-groups/v1?ids=Delete groups (cascade rules).
GET/ioarules/queries/rules/v1Query rule ids. Query: filter, limit, offset, sort (name.asc / name.desc / pattern_severity.asc / enabled.asc / rulegroup_id.asc and matching .desc). Empty filter returns all ids.
GET/ioarules/entities/rules/v1?ids=Get rules. Missing id → 200 with only found resources.
POST/ioarules/entities/rules/v1Create rule. Body { "name", "description", "rulegroup_id", "pattern_severity" } at the top level. Empty name → 400. Unknown pattern_severity or rulegroup_id → 400. Success 201. Starts enabled true.
PATCH/ioarules/entities/rules/v1Update rule. Body { "id", "name", "description", "pattern_severity", "enabled" }.
DELETE/ioarules/entities/rules/v1?ids=Delete rules.

Allowed FQL properties for groups: name, platform, enabled (match is lowercase). For rules: name, pattern_severity, enabled, rulegroup_id (match is lowercase). Unknown property or invalid filter → 400.

platform must be windows, mac, or linux. pattern_severity must be low, medium, high, or critical. Unknown platform or pattern_severity → 400.

Group JSON: id, name, description, platform, enabled. Create group ids are ioag- plus 16 hex.

Rule JSON: id, name, description, rulegroup_id, pattern_severity, enabled. Create rule ids are ioar- plus 16 hex.

Seed rule groups​

idnameplatformenabled
ioag-windowsWindows lab IOAwindowstrue

Seed rules​

idnamerulegroup_idpattern_severityenabled
ioar-windows-1Lab processioag-windowsmediumtrue
curl -sS -c cookies.txt -H 'Host: crowdstrike-api.localhost' \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"FalconLocal!1","cloud":"us-1"}' \
http://127.0.0.1:8088/identity/entities/sessions/v1

Empty filter returns at least the seed id ioag-windows. platform:'windows' returns that group:

curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/queries/rule-groups/v1?filter=platform:%27windows%27'

Invalid FQL is 400:

curl -sS -o /dev/null -w '%{http_code}\n' \
-H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/queries/rule-groups/v1?filter=not-fql'
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/entities/rule-groups/v1?ids=ioag-windows'
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"name":"Lab IOA","description":"lab","platform":"windows"}' \
http://127.0.0.1:8088/ioarules/entities/rule-groups/v1

Success is 201. The new id is in resources. Empty name → 400. Falcon comment / field_values / ruletype_id are not implemented — send fields at the top level.

curl -sS -X PATCH -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"id":"ioag-windows","name":"Windows lab IOA","description":"patched","enabled":true}' \
http://127.0.0.1:8088/ioarules/entities/rule-groups/v1
curl -sS -X DELETE -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/entities/rule-groups/v1?ids=<group-id>'

Deleting a group also deletes its rules.

Empty filter returns at least the seed id ioar-windows-1. rulegroup_id:'ioag-windows' returns the seed rule:

curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/queries/rules/v1?filter=rulegroup_id:%27ioag-windows%27'
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/entities/rules/v1?ids=ioar-windows-1'
curl -sS -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"name":"Lab command","description":"lab","rulegroup_id":"ioag-windows","pattern_severity":"medium"}' \
http://127.0.0.1:8088/ioarules/entities/rules/v1

Success is 201. The new id is in resources. Empty name → 400.

curl -sS -X PATCH -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"id":"ioar-windows-1","name":"Lab process","description":"patched","pattern_severity":"medium","enabled":true}' \
http://127.0.0.1:8088/ioarules/entities/rules/v1
curl -sS -X DELETE -H 'Host: crowdstrike-api.localhost' -b cookies.txt \
'http://127.0.0.1:8088/ioarules/entities/rules/v1?ids=<rule-id>'

Create, patch, and delete need custom-ioa:write (or a session). A token with only custom-ioa:read → 403 on those methods.

Pattern catalogs, query-rule-groups-full, POST rules/GET/v1, update-rules-v2, validate, field_values, and IOA exclusions are not implemented. Intel actors are a separate /intel/… collection (not Custom IOA): Intel actors.

Query (Bearer)​

TOKEN='<access_token from a client with custom-ioa:read>'
curl -sS -H 'Host: crowdstrike-api.localhost' \
-H "Authorization: Bearer ${TOKEN}" \
'http://127.0.0.1:8088/ioarules/queries/rule-groups/v1'

custom-ioa:read → 200. A token without that scope (including hosts:read only) → 403. Missing or revoked token → 401.

OAuth2 mint/revoke: OAuth2. Accessible scopes: API clients.