splunk.es.splunk_finding module – Manage Splunk Enterprise Security findings

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_finding.

New in splunk.es 5.1.0

Synopsis

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

  • When ref_id is not provided, a new finding is always created (no idempotency check).

  • When ref_id is provided, the module will check if the finding exists and update it.

  • Update operations use a different API endpoint and only support updating owner, status, urgency, and disposition.

  • Tested against Splunk Enterprise Server with Splunk Enterprise Security installed.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

api_app

string

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

Override this if your environment uses a different app name.

Default: "SplunkEnterpriseSecuritySuite"

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

Description of the finding.

Required when creating a new finding.

disposition

string

Disposition of the finding.

Can be updated on existing findings.

Choices:

  • "unassigned"

  • "true_positive"

  • "benign_positive"

  • "false_positive"

  • "false_positive_inaccurate_data"

  • "other"

  • "undetermined"

entity

string

The risk object (entity) associated with the finding.

Required when creating a new finding.

entity_type

string

The type of the risk object (entity).

Required when creating a new finding.

Choices:

  • "user"

  • "system"

fields

list / elements=dictionary

List of custom fields to add to the finding.

Only used when creating new findings.

name

string / required

Name of the custom field.

value

string / required

Value of the custom field.

finding_score

integer

The risk score for the finding.

Required when creating a new finding.

owner

string

Owner of the finding.

Use admin for the administrator user.

Use unassigned to leave the finding unassigned.

Can be updated on existing findings.

ref_id

string

Reference ID (finding ID / event_id) of an existing finding.

Format is typically uuid@@notable@@time{timestamp} (e.g., 2008e99d-af14-4fec-89da-b9b17a81820a@@notable@@time1768225865).

If provided, the module will verify the finding exists and update it.

If not provided, a new finding is created.

When updating, only owner, status, urgency, and disposition can be modified.

security_domain

string

Security domain for the finding.

Required when creating a new finding.

Choices:

  • "access"

  • "endpoint"

  • "network"

  • "threat"

  • "identity"

  • "audit"

status

string

Status of the finding.

Can be updated on existing findings.

Choices:

  • "unassigned"

  • "new"

  • "in_progress"

  • "pending"

  • "resolved"

  • "closed"

title

string

Title of the finding.

Required when creating a new finding (without ref_id).

urgency

string

Urgency level of the finding.

Can be updated on existing findings.

Choices:

  • "informational"

  • "low"

  • "medium"

  • "high"

  • "critical"

Examples

# Create a new finding (no ref_id - always creates new)
- name: Create a finding
  splunk.es.splunk_finding:
    title: "Suspicious Login Activity"
    description: "Multiple failed login attempts detected"
    security_domain: access
    entity: "testuser"
    entity_type: user
    finding_score: 50
    owner: admin
    status: new
    urgency: high
    disposition: undetermined

# Create a finding with custom fields
- name: Create a finding with custom fields
  splunk.es.splunk_finding:
    title: "Malware Detection"
    description: "Potential malware detected on endpoint"
    security_domain: endpoint
    entity: "server01"
    entity_type: system
    finding_score: 80
    owner: admin
    status: new
    urgency: critical
    disposition: true_positive
    fields:
      - name: custom_col_a
        value: "value1"
      - name: custom_col_b
        value: "value2"

# Update an existing finding by ref_id (only owner, status, urgency, disposition can be updated)
- name: Update finding status
  splunk.es.splunk_finding:
    ref_id: "2008e99d-af14-4fec-89da-b9b17a81820a@@notable@@time1768225865"
    status: resolved
    disposition: true_positive

# Update finding owner
- name: Assign finding to admin
  splunk.es.splunk_finding:
    ref_id: "2008e99d-af14-4fec-89da-b9b17a81820a@@notable@@time1768225865"
    owner: admin

# Create a finding with custom API path (for non-standard environments)
- name: Create a finding with custom API path
  splunk.es.splunk_finding:
    title: "Custom Environment Finding"
    description: "Finding created with custom API path"
    security_domain: network
    entity: "firewall01"
    entity_type: system
    finding_score: 60
    api_namespace: "{{ es_namespace | default('servicesNS') }}"
    api_user: "{{ es_user | default('nobody') }}"
    api_app: "{{ es_app | default('SplunkEnterpriseSecuritySuite') }}"

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

finding

dictionary

The finding result containing before/after states.

Returned: always

Sample: {"after": {"description": "Multiple failed login attempts detected", "disposition": "undetermined", "entity": "testuser", "entity_type": "user", "finding_score": 50, "owner": "admin", "security_domain": "access", "status": "new", "title": "Suspicious Login Activity", "urgency": "high"}, "before": null}

after

dictionary

The finding state after module execution.

Returned: always

before

dictionary

The finding state before module execution (if existed).

Returned: when finding existed

msg

string

Message describing the result.

Returned: always

Sample: "Finding created/updated successfully"

Authors

  • Ron Gershburg (@rgershbu)