Splunk Enterprise Security Ansible Collection

This is the Ansible Collection provided by the Ansible Security Automation Team for automating actions in Splunk Enterprise Security SIEM

This Collection is meant for distribution through Ansible Galaxy as is available for all Ansible users to utilize, contribute to, and provide feedback about.

Communication

• Join the Ansible forum:

  • Get Help: get help or help others.
  • Posts tagged with 'security': subscribe to participate in collection-related conversations.
  • Social Spaces: gather and interact with fellow enthusiasts.
  • News & Announcements: track project-wide announcements including social events.

• The Ansible Bullhorn newsletter: used to announce releases and important changes.

For more information about communication, see the Ansible communication guide.

Support

As a Red Hat Ansible Certified Content, this collection is entitled to support through Ansible Automation Platform (AAP).

If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there is community support available at no charge.

You can join us on #network:ansible.com room or the Ansible Forum Network Working Group.

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.15.0.

For collections that support Ansible 2.9, please ensure you update your network_os to use the fully qualified collection name (for example, cisco.ios.ios). Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Collection Content

Httpapi plugins

Name	Description
splunk.es.splunk	HttpApi Plugin for Splunk

Modules

Name	Description
splunk.es.adaptive_response_notable_event	Manage Splunk Enterprise Security Notable Event Adaptive Responses
splunk.es.correlation_search	Manage Splunk Enterprise Security Correlation Searches
splunk.es.correlation_search_info	Manage Splunk Enterprise Security Correlation Searches
splunk.es.data_input_monitor	Manage Splunk Data Inputs of type Monitor
splunk.es.data_input_network	Manage Splunk Data Inputs of type TCP or UDP
splunk.es.splunk_adaptive_response_notable_events	Manage Adaptive Responses notable events resource module
splunk.es.splunk_correlation_searches	Splunk Enterprise Security Correlation searches resource module
splunk.es.splunk_data_inputs_monitor	Splunk Data Inputs of type Monitor resource module
splunk.es.splunk_data_inputs_network	Manage Splunk Data Inputs of type TCP or UDP resource module

Supported connections

Use splunk modules with the httpapi connection plugin. Set certain attributes in the inventory as follows:

Example inventory.ini:

NOTE: The passwords should be stored in a secure location or an Ansible Vault

NOTE: the default port for Splunk's REST API is 8089

[splunk]
splunk.example.com

[splunk:vars]
ansible_network_os=splunk.es.splunk
ansible_user=admin
ansible_httpapi_pass=my_super_secret_admin_password
ansible_httpapi_port=8089
ansible_httpapi_use_ssl=yes
ansible_httpapi_validate_certs=True
ansible_connection=httpapi

Installing this collection

You can install the splunk collection with the Ansible Galaxy CLI:

ansible-galaxy collection install splunk.es

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: splunk.es

Using this collection

NOTE: For Ansible 2.9, you may not see deprecation warnings when you run your playbooks with this collection. Use this documentation to track when a module is deprecated.

An example of using this collection to manage a log source with Splunk Enterprise Security SIEM is as follows.

inventory.ini (Note the password should be managed by a Vault for a production environment.

[splunk]
splunk.example.com

[splunk:vars]
ansible_network_os=splunk.es.splunk
ansible_user=admin
ansible_httpapi_pass=my_super_secret_admin_password
ansible_httpapi_port=8089
ansible_httpapi_use_ssl=yes
ansible_httpapi_validate_certs=True
ansible_connection=httpapi

Using the modules with Fully Qualified Collection Name (FQCN)

With Ansible Collections there are various ways to utilize them either by calling specific Content from the Collection, such as a module, by its Fully Qualified Collection Name (FQCN) as we'll show in this example or by defining a Collection Search Path as the examples below will display.

We recommend the FQCN method but the shorthand options listed below exist for convenience.

splunk_with_collections_fqcn_example.yml

---
- name: demo splunk
  hosts: splunk
  gather_facts: false
  tasks:
    - name: test splunk_data_input_monitor
      splunk.es.data_input_monitor:
        name: "/var/log/demo.log"
        state: "present"
        recursive: true
    - name: test splunk_data_input_network
      splunk.es.data_input_network:
        name: "9001"
        protocol: "tcp"
        state: "absent"
    - name: test splunk_coorelation_search
      splunk.es.correlation_search:
        name: "Test Demo Coorelation Search From Playbook"
        description: "Test Demo Coorelation Search From Playbook, description."
        search: 'source="/var/log/snort.log"'
        state: "present"
    - name: test splunk_adaptive_response_notable_event
      splunk.es.adaptive_response_notable_event:
        name: "Demo notable event from playbook"
        correlation_search_name: "Test Demo Coorelation Search From Playbook"
        description: "Test Demo notable event from playbook, description."
        state: "present"
        next_steps:
          - ping
          - nslookup
        recommended_actions:
          - script

Define your collection search path at the Play level

Below we specify our collection at the Play level which allows us to use the splunk modules without specifying the need for the FQCN.

splunk_with_collections_example.yml

---
- name: demo splunk
  hosts: splunk
  gather_facts: false
  collections:
    - splunk.es
  tasks:
    - name: test splunk_data_input_monitor
      data_input_monitor:
        name: "/var/log/demo.log"
        state: "present"
        recursive: true
    - name: test splunk_data_input_network
      data_input_network:
        name: "9001"
        protocol: "tcp"
        state: "absent"
    - name: test splunk_coorelation_search
      correlation_search:
        name: "Test Demo Coorelation Search From Playbook"
        description: "Test Demo Coorelation Search From Playbook, description."
        search: 'source="/var/log/snort.log"'
        state: "present"
    - name: test splunk_adaptive_response_notable_event
      adaptive_response_notable_event:
        name: "Demo notable event from playbook"
        correlation_search_name: "Test Demo Coorelation Search From Playbook"
        description: "Test Demo notable event from playbook, description."
        state: "present"
        next_steps:
          - ping
          - nslookup
        recommended_actions:
          - script

Define your collection search path at the Block level

Below we use the block level keyword, we are able to use the splunk modules without the need for the FQCN.

splunk_with_collections_block_example.yml

---
- name: demo splunk
  hosts: splunk
  gather_facts: false
  tasks:
    - name: collection namespace block
      - name: test splunk_data_input_monitor
        data_input_monitor:
          name: "/var/log/demo.log"
          state: "present"
          recursive: true
      - name: test splunk_data_input_network
        data_input_network:
          name: "9001"
          protocol: "tcp"
          state: "absent"
      - name: test splunk_coorelation_search
        correlation_search:
          name: "Test Demo Coorelation Search From Playbook"
          description: "Test Demo Coorelation Search From Playbook, description."
          search: 'source="/var/log/snort.log"'
          state: "present"
      - name: test splunk_adaptive_response_notable_event
        adaptive_response_notable_event:
          name: "Demo notable event from playbook"
          correlation_search_name: "Test Demo Coorelation Search From Playbook"
          description: "Test Demo notable event from playbook, description."
          state: "present"
          next_steps:
            - ping
            - nslookup
          recommended_actions:
            - script
      collections:
        - splunk.es

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Splunk collection repository. See Contributing to Ansible-maintained collections for complete details.

You can also join us on:

• IRC - the #ansible-security irc.libera.chat channel

See the Ansible Community Guide for details on contributing to Ansible.

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Release notes

Release notes are available here.

Roadmap

More information

• Ansible network resources
• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.

Author Information

Ansible Security Automation Team