crowdstrike.falcon.case module – Manage Falcon cases

Note

This module is part of the crowdstrike.falcon collection (version 4.15.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install crowdstrike.falcon. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: crowdstrike.falcon.case.

New in crowdstrike.falcon 4.15.0

Synopsis

  • Create and update Falcon cases.

  • The same task creates the case when it is missing and updates it when it is different.

  • The API cannot delete a case. To end the work on a case, set status=closed.

  • Closing a case does not change the alerts in it. Use the alerts API to close them.

Requirements

The below requirements are needed on the host that executes this module.

  • Cases [READ, WRITE] API scope

  • CrowdStrike FalconPy >= 1.5.5

  • crowdstrike-falconpy >= 1.5.0

  • python >= 3.12

Parameters

Parameter

Comments

alerts

list / elements=string

The composite IDs of the alerts to add to the case as evidence.

The module only adds alerts. It does not remove an alert that is not in this list.

assigned_to_user_uuid

string

The UUID of the user that the case is assigned to.

An empty string removes the assignee.

auth

dictionary

The registered result of the crowdstrike.falcon.auth module, or a dictionary containing the access_token and cloud keys.

If provided, the client_id, client_secret, member_cid, and cloud options are ignored.

Useful when needing to make multiple API calls to avoid rate limiting issues.

access_token

string

The OAuth2 access token to use for authentication.

cloud

string

The CrowdStrike cloud region to use.

This can differ from the module’s cloud argument due to autodiscovery.

client_id

aliases: falcon_client_id

string

The CrowdStrike API client ID to use.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_ID environment variable can also be used.

client_secret

aliases: falcon_client_secret

string

The CrowdStrike API secret that corresponds to the client ID.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_SECRET environment variable can also be used.

cloud

string

The CrowdStrike cloud region to use.

All clouds are automatically discovered if not specified, except for the us-gov-1 cloud.

The FALCON_CLOUD environment variable can also be used.

Choices:

  • "us-1" ← (default)

  • "us-2"

  • "us-3"

  • "us-gov-1"

  • "us-gov-2"

  • "eu-1"

description

string

The description of the case.

An empty string clears the description.

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

id

string

The ID of the case to update.

The module fails when no case has this ID.

With id, name is the new name of the case.

member_cid

string

The CrowdStrike member CID for MSSP authentication.

See the Falcon documentation for more information about API clients.

The FALCON_MEMBER_CID environment variable can also be used.

name

string

The name of the case.

Required to create a case.

With no id, the module finds the case by this exact, case-sensitive name. It creates the case when no case has this name, and updates it when one case has it. It fails when more than one case has this name; give id in that case.

For a name with a single quote or a backslash, the module searches with the part of the name before that character, then compares the full names. It fails when the name starts with one of these characters; give id in that case.

The name search does not see a new case for about 20 seconds. A later task in the same play that changes this case should use the id from the case return value.

purge_tags

boolean

Remove the tags of the case that are not in tags.

With purge_tags=true and no tags, the module does not change the tags.

Choices:

  • false ← (default)

  • true

severity

integer

The severity of the case, from 1 to 100.

Required to create a case.

status

string

The status of the case.

A new case has the status new when this option is not set.

Choices:

  • "new"

  • "in_progress"

  • "reopened"

  • "closed"

tags

list / elements=string

The tags of the case.

Tags are case sensitive.

The module adds the tags that the case does not have.

With purge_tags=true, the module also removes the tags that are not in this list.

user_agent

string

Custom User-Agent string to use for requests to the API.

The user agent string is prepended to the default user agent string (crowdstrike-ansible/<version>).

See RFC 7231 for more information.

The FALCON_USER_AGENT environment variable can also be used.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platforms: all

Target OS/families that can be operated against

See Also

See also

crowdstrike.falcon.case_info

Get information about Falcon cases.

crowdstrike.falcon.host_contain

Contain or lift containment on Falcon hosts.

Case Management API reference

The CrowdStrike API operations that this module uses.

Examples

- name: Create a case with an alert as evidence
  crowdstrike.falcon.case:
    name: "Phishing investigation"
    description: "Investigate the phishing alerts of the finance team"
    severity: 50
    tags:
      - phishing
    alerts:
      - "0123456789abcdef0123456789abcdef:ind:fedcba9876543210fedcba9876543210-123456789012345"
  register: new_case

- name: Set the status to in_progress and add tags, by ID
  crowdstrike.falcon.case:
    id: "{{ new_case.case.id }}"
    status: in_progress
    tags:
      - finance

- name: Assign the case to a user
  crowdstrike.falcon.case:
    id: "{{ new_case.case.id }}"
    assigned_to_user_uuid: "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"

- name: Remove the assignee of the case
  crowdstrike.falcon.case:
    id: "{{ new_case.case.id }}"
    assigned_to_user_uuid: ""

- name: Close the case
  crowdstrike.falcon.case:
    id: "{{ new_case.case.id }}"
    status: closed

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

case

dictionary

The case after the change, read again from the API.

In check mode, the current case, or the wanted values with no id when the case does not exist.

Returned: success

analysis_results

dictionary

The analysis results of the case, by type.

Each type has a list of records.

Returned: success

assigned_to

dictionary

The user that the case is assigned to.

Returned: success

email

string

The email address of the user.

Returned: success

Sample: "analyst@example.com"

full_name

string

The full name of the user.

Returned: success

Sample: "Example Analyst"

uuid

string

The UUID of the user.

Returned: success

Sample: "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"

assigned_to_groups

list / elements=dictionary

The user groups that the case is assigned to.

Returned: success

cid

string

The customer ID that the case belongs to.

Returned: success

Sample: "0123456789abcdef0123456789abcdef"

consistency

dictionary

The consistency data of the case.

Returned: success

consistent

boolean

Whether the case data is consistent.

Returned: success

Sample: true

version

integer

The consistency version of the case.

Returned: success

Sample: 3

created_by

dictionary

The user that created the case.

Returned: success

email

string

The email address of the user.

Returned: success

Sample: "analyst@example.com"

full_name

string

The full name of the user.

Returned: success

Sample: "Example Analyst"

uuid

string

The UUID of the user.

Returned: success

Sample: "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"

created_timestamp

string

The time when the case was created.

Returned: success

Sample: "2026-11-18T21:43:48Z"

creation_actor

dictionary

The actor that created the case.

Returned: success

type

string

The type of the actor.

Returned: success

Sample: "user"

description

string

The description of the case.

Returned: success

Sample: "Investigate the phishing alerts of the finance team"

end_timestamp

string

The time when the case was closed.

Returned: success

Sample: "2026-11-18T22:05:00Z"

evidence

dictionary

The evidence of the case, by type.

Each type has a list of records.

Returned: success

id

string

The ID of the case.

Returned: success

Sample: "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d"

last_updated_by

dictionary

The user that last updated the case.

Returned: success

email

string

The email address of the user.

Returned: success

Sample: "analyst@example.com"

full_name

string

The full name of the user.

Returned: success

Sample: "Example Analyst"

uuid

string

The UUID of the user.

Returned: success

Sample: "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"

name

string

The name of the case.

Returned: success

Sample: "Phishing investigation"

read_only

dictionary

The read-only state of the case.

Returned: success

is_read_only

boolean

Whether the case is read only.

Returned: success

Sample: false

reference_id

string

The reference ID of the case.

Returned: success

Sample: "CASE-123"

severity

integer

The severity of the case.

Returned: success

Sample: 50

severity_info

dictionary

The severity details of the case.

Returned: success

level

string

The severity level of the case.

Returned: success

Sample: "Medium"

start_timestamp

string

The start time of the case.

Returned: success

status

string

The status of the case.

Returned: success

Sample: "closed"

tags

list / elements=string

The tags of the case.

Returned: success

Sample: ["malware"]

update_actor

dictionary

The actor that last updated the case.

Returned: success

type

string

The type of the actor.

Returned: success

Sample: "user"

updated_timestamp

string

The time when the case was last updated.

Returned: success

Sample: "2026-11-18T21:50:12Z"

version

integer

The version of the case.

Returned: success

Sample: 3

Authors

  • Carlos Matos (@carlosmmatos)