splunk.es.splunk_investigation module – Manage Splunk Enterprise Security investigations

Note

This module is part of the splunk.es collection (version 5.1.0).

You might already have this collection installed if you are using the ansible package. 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 splunk.es.

To use it in a playbook, specify: splunk.es.splunk_investigation.

New in splunk.es 5.1.0

Synopsis

  • This module allows for creation and update of Splunk Enterprise Security investigations.

  • When investigation_ref_id is not provided, a new investigation is created.

  • When investigation_ref_id is provided, the module will update the existing investigation.

  • Update operations can modify all fields except name.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

api_app

string

The app portion of the Splunk API path for the investigations endpoint.

Override this if your environment uses a different app name.

Default: "missioncontrol"

api_namespace

string

The namespace portion of the Splunk API path.

Override this if your environment uses a different namespace.

Default: "servicesNS"

api_user

string

The user portion of the Splunk API path.

Override this if your environment requires a different user context.

Default: "nobody"

description

string

The description of the investigation.

disposition

string

The disposition of the investigation.

Can be updated on existing investigations.

Choices:

  • "unassigned"

  • "true_positive"

  • "benign_positive"

  • "false_positive"

  • "false_positive_inaccurate_data"

  • "other"

  • "undetermined"

finding_ids

list / elements=string

List of finding IDs (event_ids) to attach to the investigation.

When updating, findings are added to the investigation via a separate API call.

Finding IDs can only be added, removal is not supported.

investigation_ref_id

string

Reference ID of an existing investigation.

If provided, the module will update the existing investigation.

If not provided, a new investigation is created.

When updating, all fields except name can be modified.

investigation_type

string

The type of the investigation.

If not specified, the default investigation type is used.

Can be updated on existing investigations.

name

string

The name of the investigation.

Required when creating a new investigation (without investigation_ref_id).

Cannot be updated after creation.

Note that names are not unique - multiple investigations can have the same name.

owner

string

The owner of the investigation.

Use admin for the administrator user.

Use unassigned to leave the investigation unassigned.

Can be updated on existing investigations.

sensitivity

string

The sensitivity of the investigation.

Can be updated on existing investigations.

Choices:

  • "white"

  • "green"

  • "amber"

  • "red"

  • "unassigned"

status

string

The status of the investigation.

Can be updated on existing investigations.

Choices:

  • "unassigned"

  • "new"

  • "in_progress"

  • "pending"

  • "resolved"

  • "closed"

urgency

string

The urgency of the investigation.

Can be updated on existing investigations.

Choices:

  • "informational"

  • "low"

  • "medium"

  • "high"

  • "critical"

  • "unknown"

Examples

# Create a new investigation
- name: Create an investigation
  splunk.es.splunk_investigation:
    name: "Security Incident 2026-01"
    description: "Investigation into suspicious login activity"
    status: new
    owner: admin
    urgency: high
    sensitivity: amber
    disposition: undetermined

# Create an investigation with findings attached
- name: Create investigation with findings
  splunk.es.splunk_investigation:
    name: "Malware Investigation"
    description: "Investigation into potential malware detection"
    status: new
    owner: admin
    urgency: critical
    sensitivity: red
    finding_ids:
      - "A265ED94-AE9E-428C-91D2-64BB956EB7CB@@notable@@62eaebb8c0dd2574fc0b3503a9586cd9"

# Create an investigation with a specific type
- name: Create investigation with investigation type
  splunk.es.splunk_investigation:
    name: "Phishing Investigation"
    description: "Investigation into phishing attempt"
    status: new
    owner: admin
    urgency: high
    investigation_type: "phishing"

# Update an existing investigation status
- name: Update investigation status
  splunk.es.splunk_investigation:
    investigation_ref_id: "inv-12345-abcde"
    status: in_progress
    owner: analyst1

# Update investigation disposition
- name: Close investigation as resolved
  splunk.es.splunk_investigation:
    investigation_ref_id: "inv-12345-abcde"
    status: resolved
    disposition: true_positive
    urgency: low

# Add findings to an existing investigation
- name: Add findings to investigation
  splunk.es.splunk_investigation:
    investigation_ref_id: "inv-12345-abcde"
    finding_ids:
      - "B376FE05-BF9F-539D-A2E3-75CC067FC8DC@@notable@@73fbccc9d1ee3685gd1c4614b0697de0"

Return Values

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

Key

Description

changed

boolean

Whether any changes were made.

Returned: always

Sample: true

investigation

dictionary

The investigation result containing before/after states.

Returned: always

Sample: {"after": {"description": "Investigation into suspicious login activity", "disposition": "undetermined", "investigation_type": "phishing", "name": "Security Incident 2026-01", "owner": "admin", "sensitivity": "amber", "status": "new", "urgency": "high"}, "before": null}

after

dictionary

The investigation state after module execution.

Returned: always

before

dictionary

The investigation state before module execution (if existed).

Returned: when investigation existed

msg

string

Message describing the result.

Returned: always

Sample: "Investigation created/updated successfully"

Authors

  • Ron Gershburg (@rgershbu)