community.general.listen_ports_facts (8.5.0) — module

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands.

This module currently supports Linux only.

Requirements

• netstat or ss

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Gather facts on listening ports
  community.general.listen_ports_facts:

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: TCP whitelist violation
  ansible.builtin.debug:
    msg: TCP port {{ item.port }} by pid {{ item.pid }} violates the whitelist
  vars:
    tcp_listen_violations: "{{ ansible_facts.tcp_listen | selectattr('port', 'in', tcp_whitelist) | list }}"
    tcp_whitelist:
      - 22
      - 25
  loop: "{{ tcp_listen_violations }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: List TCP ports
  ansible.builtin.debug:
    msg: "{{ ansible_facts.tcp_listen  | map(attribute='port') | sort | list }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: List UDP ports
  ansible.builtin.debug:
    msg: "{{ ansible_facts.udp_listen | map(attribute='port') | sort | list }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: List all ports
  ansible.builtin.debug:
    msg: "{{ (ansible_facts.tcp_listen + ansible_facts.udp_listen) | map(attribute='port') | unique | sort | list }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Gather facts on all ports and override which command to use
  community.general.listen_ports_facts:
    command: 'netstat'
    include_non_listening: true

Inputs

    
command:
    choices:
    - netstat
    - ss
    description:
    - Override which command to use for fetching listen ports.
    - By default module will use first found supported command on the system (in alphanumerical
      order).
    type: str
    version_added: 4.1.0
    version_added_collection: community.general

include_non_listening:
    default: false
    description:
    - Show both listening and non-listening sockets (for TCP this means established connections).
    - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state),
      RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address)
      to the returned facts.
    type: bool
    version_added: 5.4.0
    version_added_collection: community.general

Outputs

ansible_facts:
  contains:
    tcp_listen:
      contains:
        address:
          description: The address the server is listening on.
          returned: always
          sample: 0.0.0.0
          type: str
        foreign_address:
          description: The address of the remote end of the socket.
          returned: if O(include_non_listening=true)
          sample: 10.80.0.1
          type: str
          version_added: 5.4.0
          version_added_collection: community.general
        name:
          description: The name of the listening process.
          returned: if user permissions allow
          sample: mysqld
          type: str
        pid:
          description: The pid of the listening process.
          returned: always
          sample: 1223
          type: int
        port:
          description: The port the server is listening on.
          returned: always
          sample: 3306
          type: int
        protocol:
          description: The network protocol of the server.
          returned: always
          sample: tcp
          type: str
        state:
          description: The state of the socket.
          returned: if O(include_non_listening=true)
          sample: ESTABLISHED
          type: str
          version_added: 5.4.0
          version_added_collection: community.general
        stime:
          description: The start time of the listening process.
          returned: always
          sample: Thu Feb  2 13:29:45 2017
          type: str
        user:
          description: The user who is running the listening process.
          returned: always
          sample: mysql
          type: str
      description: A list of processes that are listening on a TCP port.
      returned: if TCP servers were found
      type: list
    udp_listen:
      contains:
        address:
          description: The address the server is listening on.
          returned: always
          sample: 0.0.0.0
          type: str
        foreign_address:
          description: The address of the remote end of the socket.
          returned: if O(include_non_listening=true)
          sample: 10.80.0.1
          type: str
          version_added: 5.4.0
          version_added_collection: community.general
        name:
          description: The name of the listening process.
          returned: if user permissions allow
          sample: rsyslogd
          type: str
        pid:
          description: The pid of the listening process.
          returned: always
          sample: 609
          type: int
        port:
          description: The port the server is listening on.
          returned: always
          sample: 514
          type: int
        protocol:
          description: The network protocol of the server.
          returned: always
          sample: udp
          type: str
        state:
          description: The state of the socket. UDP is a connectionless protocol.
            Shows UCONN or ESTAB.
          returned: if O(include_non_listening=true)
          sample: UCONN
          type: str
          version_added: 5.4.0
          version_added_collection: community.general
        stime:
          description: The start time of the listening process.
          returned: always
          sample: Thu Feb  2 13:29:45 2017
          type: str
        user:
          description: The user who is running the listening process.
          returned: always
          sample: root
          type: str
      description: A list of processes that are listening on a UDP port.
      returned: if UDP servers were found
      type: list
  description: Dictionary containing details of TCP and UDP ports with listening servers
  returned: always
  type: complex