$ ansible-doc -t module cisco.sccfm.add_asa_shun
> MODULE cisco.sccfm.add_asa_shun (sccfm-ansible/plugins/modules/add_asa_shun.py)
Adds shun entries on one or more ASA devices managed by SCC Firewall
Manager.
Use `source_ip' for a single entry, or `entries' to add multiple
entries in a single API call (more efficient than looping).
Executes `shun <source_ip>' to block all future connections from
that host.
Optionally specify a connection tuple (`dest_ip', `source_port',
`dest_port', `protocol') to additionally drop an existing connection
immediately.
`source_ip' and `entries' are mutually exclusive.
Devices can be selected by a Lucene query or by specifying a list of
UIDs.
See
https://developer.cisco.com/docs/cisco-security-cloud-control-firewall-manager/execute-cli-command/
for API documentation.
OPTIONS (= indicates it is required):
- api_token API token for SCCFM.
set_via:
env:
- name: SCCFM_API_TOKEN
default: null
no_log: true
type: str
- dest_ip Destination IP of a specific connection to drop
immediately.
Required when specifying `source_port', `dest_port', or
`protocol'.
Only valid when using `source_ip' (not `entries').
default: null
type: str
- dest_port Destination port of the connection to drop.
Requires `dest_ip'.
Only valid when using `source_ip' (not `entries').
default: null
type: int
- entries List of shun entries to add in a single transaction.
Mutually exclusive with `source_ip'.
Each entry must have `source_ip' and may optionally
include `dest_ip', `source_port', `dest_port', and
`protocol'.
default: null
elements: dict
type: list
suboptions:
- dest_ip Destination IP of a specific connection to drop
immediately.
default: null
type: str
- dest_port Destination port of the connection to drop
(requires dest_ip).
default: null
type: int
- protocol Protocol of the connection to drop — tcp or udp
(requires dest_ip).
choices: [tcp, udp]
default: null
type: str
= source_ip The source IP address to block.
type: str
- source_port Source port of the connection to drop
(requires dest_ip).
default: null
type: int
- limit Maximum number of devices to return when using `query'.
Ignored when using `uids'.
default: 50
type: int
- offset Pagination offset when using `query'.
Ignored when using `uids'.
default: 0
type: int
- protocol Protocol of the connection to drop (tcp or udp).
Requires `dest_ip'.
Only valid when using `source_ip' (not `entries').
choices: [tcp, udp]
default: null
type: str
- query Lucene query to filter ASA devices.
Mutually exclusive with `uids'.
The query is automatically combined with `deviceType:ASA'.
default: null
type: str
- region SCCFM region (int, us, eu, apj, au, uae, in, or ci).
set_via:
env:
- name: SCCFM_REGION
default: null
type: str
- source_ip The source IP address of the attacking host to block.
Mutually exclusive with `entries'.
default: null
type: str
- source_port Source port of the connection to drop.
Requires `dest_ip'.
Only valid when using `source_ip' (not `entries').
default: null
type: int
- uids List of device UIDs to add the shun on.
Mutually exclusive with `query'.
default: null
elements: str
type: list
AUTHOR: Cisco SCCFM Team
EXAMPLES:
# Example 1: Shun a single source IP on devices matching a query
- name: Block attacker on production ASAs
cisco.sccfm.add_asa_shun:
query: "name:prod-* AND connectivityState:ONLINE"
source_ip: "10.99.99.99"
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
# Example 2: Shun with connection tuple to drop an existing connection
- name: Block attacker and drop active connection
cisco.sccfm.add_asa_shun:
uids:
- "12345678-1234-1234-1234-123456789abc"
source_ip: "10.99.99.99"
dest_ip: "10.1.1.1"
source_port: 555
dest_port: 666
protocol: tcp
# Example 3: Shun multiple IPs in a single transaction (recommended for bulk)
- name: Block multiple attackers in one API call
cisco.sccfm.add_asa_shun:
query: "connectivityState:ONLINE"
entries:
- source_ip: "203.0.113.40"
- source_ip: "203.0.113.50"
dest_ip: "10.1.1.1"
source_port: 555
dest_port: 443
protocol: tcp
- source_ip: "203.0.113.60"
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
# Example 4: Using module_defaults (recommended)
- name: Add shun entries
hosts: localhost
gather_facts: false
module_defaults:
group/cisco.sccfm.all:
region: "{{ sccfm_region }}"
api_token: "{{ sccfm_api_token }}"
tasks:
- name: Shun attacker IP
cisco.sccfm.add_asa_shun:
query: "connectivityState:ONLINE"
source_ip: "10.99.99.99"
RETURN VALUES:
- results List of CLI execution results per device.
elements: dict
returned: success
type: list
contains:
- device_uid The UID of the device.
type: str
- error_msg Error message if execution failed on this device
(None if successful).
type: str
- result The CLI command output.
type: str
- script The script that was executed.
type: str