Ansible Collection - Stormshield SNS

https://github.com/stormshield/ansible-sns-collection
Admin
This Ansible collection provides modules, roles, and playbooks to configure Stormshield SNS...
Tokens:21,011
Snippets:57
Trust Score:6
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### SNS NTP Role Configuration Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_ntp.rst

Demonstrates how to use the stormshield.sns.sns_ntp Ansible role to configure the system timezone, NTP servers, and manage reboots. It specifies the timezone, a list of NTP servers with optional keys, and a boolean flag for rebooting if needed.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_ntp
      timezone: "Europe/Paris"
      ntp_servers:
        - { host: "fr.pool.ntp.org"}
        - { host: "be.pool.ntp.org", key: "12345678"}
      reboot_if_needed: true
```

--------------------------------

### Configure DNS Servers with sns_dns Role

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_dns.rst

This example demonstrates how to use the `stormshield.sns.sns_dns` Ansible role to configure DNS servers on Stormshield SNS appliances. It specifies the target hosts and provides a list of DNS servers with their hostnames and IP addresses.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_dns
      dns_servers:
        - { host: "mydns1", ip: "10.0.0.1"}
        - { host: "mydns2", ip: "10.0.0.2"}
```

--------------------------------

### Install Stormshield SNS Python Library

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Installs the required Python library 'stormshield.sns.sslclient' on the Ansible host. This is a prerequisite for the collection's modules to function correctly.

```bash
pip install stormshield.sns.sslclient
```

--------------------------------

### SNS Appliance Inventory Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_firmware_update.rst

Example Ansible inventory defining SNS appliances, including connection details, host, user, password, SSL verification, architecture, model, and force_modify parameters.

```yaml
sns_appliances:
  hosts:
    appliance1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: password123
        sslverifyhost: False
      arch: amd64
      model: XL-VM
      force_modify: True

```

--------------------------------

### Install Python Library Dependency

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Installs the required Python library 'stormshield.sns.sslclient' on the Ansible host. This library is a prerequisite for the collection's modules to function correctly.

```bash
pip install stormshield.sns.sslclient
```

--------------------------------

### Install stormshield.sns Collection

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Installs the Stormshield SNS Ansible collection using ansible-galaxy. This is the primary method to get the collection onto your Ansible control node.

```bash
ansible-galaxy collection install stormshield.sns
```

--------------------------------

### Ansible Playbook Example for sns_ntp Role

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_ntp/README.md

An example Ansible playbook demonstrating how to use the sns_ntp role. It configures the system timezone, NTP servers, and the reboot behavior for Stormshield appliances.

```yaml
- hosts: sns_appliances
  roles:
    - role: sns_ntp
      timezone: "Europe/Paris"
      ntp_servers:
        - { host: "fr.pool.ntp.org"}
        - { host: "be.pool.ntp.org", key: "12345678"}
      reboot_if_needed: true
```

--------------------------------

### Ansible Inventory File Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Defines an Ansible inventory file for Stormshield SNS appliances. It specifies connection details, hostnames, usernames, passwords, and SSL verification settings.

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: secret
        sslverifyhost: false
```

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: VMSNSX08K000111
        ip: 10.0.0.254
        user: admin
        password: secret
        sslverifyhost: true
```

--------------------------------

### SNS Firmware Update Playbook Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_firmware_update.rst

Example Ansible playbook demonstrating the usage of the `stormshield.sns.sns_firmware_update` role for upgrading SNS VM firmware. It specifies the role, version, and system_clone parameter, recommending rolling updates.

```yaml
---
- hosts: sns_appliances
  serial: 1
  roles:
    - role: stormshield.sns.sns_firmware_update
      version: 4.1.0
      system_clone: False

```

--------------------------------

### Ansible Inventory Example with SNS Appliance Details

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_firmware_update/README.md

This example shows an Ansible inventory structure for SNS appliances. It includes host-specific variables like IP address, user credentials, and SSL verification settings, as well as appliance-specific details such as architecture, model, and a force modify flag.

```yaml
sns_appliances:
  hosts:
    appliance1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: password123
        sslverifyhost: False
      arch: amd64
      model: XL-VM
      force_modify: True

```

--------------------------------

### Example Playbook for SNS Alarm Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_alarm/README.md

An example Ansible playbook demonstrating how to use the stormshield.sns.sns_alarm role to configure IPS alarms. It shows the structure for specifying protocols and their associated alarms, including context, ID, and level.

```ansible
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_alarm
      protocols:
        - protocol: http
          alarms:
            - { index: 1, context: "http:client:header", id: 67, level: ignore }
```

--------------------------------

### Ansible Collection Plugins Directory Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/plugins/README.md

Illustrates the typical organization of plugins within an Ansible collection. This structure helps in shipping various plugin types such as actions, callbacks, and modules.

```directory-structure
└── plugins
    ├── action
    ├── become
    ├── cache
    ├── callback
    ├── cliconf
    ├── connection
    ├── filter
    ├── httpapi
    ├── inventory
    ├── lookup
    ├── module_utils
    ├── modules
    ├── netconf
    ├── shell
    ├── strategy
    ├── terminal
    ├── test
    └── vars
```

--------------------------------

### Ansible Playbook Execution Output Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Shows a typical output from running an Ansible playbook against a Stormshield SNS appliance. It details task execution status (ok, changed) and provides a debug message with appliance information.

```text
PLAY [all] *****************************************************************************************************************

TASK [Gathering Facts] *****************************************************************************************************
ok: [utm1]

TASK [Get appliance information] *******************************************************************************************
changed: [utm1]

TASK [Extract version] *****************************************************************************************************
changed: [utm1]

TASK [Extract model] *******************************************************************************************************
changed: [utm1]

TASK [Get appliance name] **************************************************************************************************
changed: [utm1]

TASK [Extract system name] *************************************************************************************************
changed: [utm1]

TASK [debug] ***************************************************************************************************************
ok: [utm1] =>
  msg: 'Appliance: utm1, hostname: VMSNSX01A2083A9, model: EVAU, firmware version: 4.8.2'

PLAY RECAP *****************************************************************************************************************
utm1                       : ok=7    changed=5    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
```

--------------------------------

### Install Ansible Collection

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Installs the Stormshield SNS Ansible collection using ansible-galaxy. This command downloads and makes the collection's roles and modules available for use in playbooks.

```bash
ansible-galaxy collection install stormshield.sns
```

--------------------------------

### Create SNS Objects

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_object.rst

This playbook demonstrates how to create various types of objects (hosts, networks, netgroups, routers, geogroups, timeobjects, internet) on an SNS appliance using the stormshield.sns.sns_object Ansible role. It shows the structure for defining each object type with their respective parameters.

```yaml
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_object
      hosts :
        - { name: myhost, ip: 1.2.3.4, comment: "My comment"}
      networks:
        - { name: mynetwork, ip: 10.0.0.0, mask: 255.0.0.0 }
      netgroups:
        - { name: mygroup, members: [myhost, mynetwork] }
      routers:
        - { name: myrouter, gatewaythreshold: 1, gateways: [ { type: principalgateway, host: myhost1 }, { type: backupgateway, host: myhost2 } ] }
      geogroups:
        - { name: mygeogroup, members: ["eu:fr", "eu:de"] }
      timeobjects:
        - { name: mytime1, time: "08:00-12:00", weekday: "1;2;3;4;5" }
      internet:
        object: Network_internals
        operator: ne

```

--------------------------------

### sns_policy Role Configuration Example

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_policy.rst

This Ansible playbook demonstrates the configuration of filter and NAT policies using the `stormshield.sns.sns_policy` role. It shows how to define rules for traffic filtering and network address translation.

```yaml
- hosts: sns_appliances
  roles:
      - role: stormshield.sns.sns_policy
        activate: yes
        slot: 5
        filter:
          - { action: pass, srctarget: any, dsttarget: Firewall_out, dstport: ssh, comment: "Allow SSH"}
          - { action: block, srctarget: any, srcif: out, dsttarget: any }
          - { action: pass, srctarget: any, dsttarget: any, inspection: firewall }
        nat:
          - { action: nat, srctarget: network_in, dsttarget: Internet, dstif: out, natsrctarget: firewall_out, natsrcport: ephemeral_fw }

```

--------------------------------

### Example Playbook for sns_url Role

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_url/README.md

An example Ansible playbook demonstrating how to use the sns_url role to configure two URL filtering rules within a specific slot on Stormshield appliances.

```yaml
- hosts: sns_appliances
  roles:
  - role: stormshield.sns.sns_url
    base: embedded
    slots:
      - index: 3
        name: myurlslot
        comment: "slot comment"
        rules:
          - { state: "On", action: block, urlgroup: ads, comment: "Block ads" }
          - { state: "On", action: pass, urlgroup: any }
```

--------------------------------

### SNS Backup Role: Backup Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_backup.rst

This playbook demonstrates backing up SNS appliance configurations using the `stormshield.sns.sns_backup` Ansible role. It specifies the `backup_path` for storing backups, the `backup` filename, and enables `timestamp_prefix` to prepend a timestamp to the backup file.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_backup
      backup_path: "/backup"
      backup: "{{ inventory_hostname }}.na"
      timestamp_prefix: true
```

--------------------------------

### Import SNS Objects from CSV

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_object.rst

This playbook demonstrates how to import objects into an SNS appliance from a CSV file using the stormshield.sns.sns_object Ansible role. The `csvfileimport` parameter specifies the path to the CSV file containing the object definitions.

```yaml
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_object
      csvfileimport:
        - /path/myobjects.csv

```

--------------------------------

### SNS Backup Role: Restore Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_backup.rst

This playbook demonstrates restoring SNS appliance configurations using the `stormshield.sns.sns_backup` Ansible role. It specifies the `backup_path` where backups are stored and the `restore` parameter with the name of the backup file to be restored.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_backup
      backup_path: "/backup"
      restore: "mybackup.na"
```

--------------------------------

### Backup SNS Configuration with Role

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

A playbook example demonstrating the use of the `stormshield.sns.backup` role to back up SNS appliance configurations. It specifies the backup path and filename.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.backup
      backup_path: "./backup"
      backup: "mybackup.na"
      timestamp_prefix: true
```

--------------------------------

### Ansible Playbook for SNS DNS Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_dns/README.md

An example Ansible playbook that applies the `stormshield.sns.sns_dns` role to configure DNS servers on target appliances. It specifies the DNS servers to be used via the `dns_servers` variable.

```YAML
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_dns
      dns_servers:
        - { host: "mydns1", ip: "10.0.0.1"}
        - { host: "mydns2", ip: "10.0.0.2"}
```

--------------------------------

### Configure Ansible Output

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Customizes Ansible's behavior by modifying the `~/.ansible.cfg` file. This example enables callback plugins for improved output formatting and suppresses certain warnings.

```text
[defaults]
bin_ansible_callbacks=True
stdout_callback = yaml
localhost_warning = false
display_skipped_hosts = false
```

--------------------------------

### Configure SNS Policy with Role

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

A playbook example for configuring network policies on SNS appliances using the `stormshield.sns.policy` role. It defines network objects and firewall rules.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.object
      hosts :
      - { name: intranet, ip: 192.168.2.1, comment: "Intranet server"}
      networks:
      - { name: usernetwork, ip: 192.168.1.0, mask: 255.255.255.0 }
    - role: stormshield.sns.policy
      activate: yes
      slot: 5
      filter:
      - { action: pass, srctarget: usernetwork, dsttarget: intranet, dstport: https, comment: "Intranet"}
      - { action: pass, srctarget: any, dsttarget: any, comment: "Warning, pass all example"}
```

--------------------------------

### Configure URL Filtering Rules

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_url.rst

This snippet demonstrates how to configure two URL filtering rules within a specific slot (index 3) using the `sns_url` Ansible role. It specifies blocking ads and allowing any URL.

```yaml
- hosts: sns_appliances
  roles:
  - role: stormshield.sns.sns_url
    base: embedded
    slots:
      - index: 3
        name: myurlslot
        comment: "slot comment"
        rules:
          - { state: "On", action: block, urlgroup: ads, comment: "Block ads" }
          - { state: "On", action: pass, urlgroup: any }

```

--------------------------------

### Example Playbook for SNS Backup

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_backup/README.md

This playbook demonstrates how to use the stormshield.sns.sns_backup Ansible role to back up a Stormshield Network Security appliance configuration. It specifies the target hosts, the role to apply, and custom variables like backup_path, backup filename, and timestamp_prefix.

```ansible
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_backup
      backup_path: "/backup"
      backup: "{{ inventory_hostname }}.na"
      timestamp_prefix: true
```

--------------------------------

### Ansible Playbook: Create Objects on SNS Appliance

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_object/README.md

Example Ansible playbook demonstrating how to use the `stormshield.sns.object` role to create various network objects on a Stormshield Network Security appliance. It includes configurations for hosts, networks, netgroups, routers, geo groups, time objects, and internet object settings.

```ansible
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.object
      hosts :
        - { name: myhost, ip: 1.2.3.4, comment: "My comment"}
      networks:
        - { name: mynetwork, ip: 10.0.0.0, mask: 255.0.0.0 }
      netgroups:
        - { name: mygroup, members: [myhost, mynetwork] }
      routers:
        - { name: myrouter, gatewaythreshold: 1, gateways: [ { type: principalgateway, host: myhost1 }, { type: backupgateway, host: myhost2 } ] }
      geogroups:
        - { name: mygeogroup, members: ["eu:fr", "eu:de"] }
      timeobjects:
        - { name: mytime1, time: "08:00-12:00", weekday: "1;2;3;4;5" }
      internet:
        object: Network_internals
        operator: ne

```

--------------------------------

### Delete SNS Object

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_object.rst

This playbook demonstrates how to delete an object, specifically a network object, from an SNS appliance using the stormshield.sns.sns_object Ansible role by setting the `state` parameter to `absent`. The Internet object cannot be deleted.

```yaml
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_object
      state: absent
      networks :
        - { name: mynetwork }

```

--------------------------------

### Ansible Playbook: Import Objects from CSV

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_object/README.md

Example Ansible playbook demonstrating the use of the `stormshield.sns.object` role to import network objects from a CSV file. This is useful for bulk creation or updates of objects based on data defined in a CSV format.

```ansible
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.object

```

--------------------------------

### Ansible SNS Alarm Role Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/example_sns_alarm.rst

This snippet shows an Ansible playbook that utilizes the `stormshield.sns.sns_alarm` role. It configures a specific alarm (`http:client:header` with ID 67) on an SNS appliance to be ignored for profile 1. The role requires defining the protocol, alarm index, context, ID, level, and profile.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.sns_alarm
      protocols:
        - protocol: http
          alarms:
            - { index: 1, context: "http:client:header", id: 67, level: ignore }
```

--------------------------------

### Ansible Vault Encrypted Variable

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

An example of how to structure variables within an Ansible Vault encrypted file. This file is referenced in the main inventory to securely load sensitive information.

```yaml
---
utm1_password: "secret"
```

--------------------------------

### Ansible Playbook: Delete Object from SNS Appliance

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_object/README.md

Example Ansible playbook showing how to use the `stormshield.sns.object` role to delete a specific network object from a Stormshield Network Security appliance. It sets the `state` variable to `absent` and specifies the object to be removed, such as a network object.

```ansible
---
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.object
      state: absent
      networks :
        - { name: mynetwork }

```

--------------------------------

### Shell Commands for SNS Configuration Backup

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Demonstrates the necessary shell commands to prepare a local directory for backups, execute the Ansible playbook for configuration backup, and verify the resulting backup file, which includes a timestamp.

```shell
$ mkdir ./backup

$ ansible-playbook backup.yml

$ ls ./backup
20200520T175355_mybackup.na
```

--------------------------------

### Run SNS Backup Playbook

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Executes the playbook designed to back up SNS appliance configurations. It requires specifying the inventory file.

```bash
ansible-playbook -i ./inventory.yml backup.yml
```

--------------------------------

### Ansible Playbook for SNS Configuration Backup

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

This playbook uses the stormshield.sns.backup role to back up configurations from SNS appliances. It specifies the backup directory and filename, with an option to prepend a timestamp to the backup file.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.backup
      backup_path: "./backup"
      backup: "mybackup.na"
      timestamp_prefix: true
```

--------------------------------

### Ansible Configuration for Output

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Configures Ansible settings in `~/.ansible.cfg` to improve playbook output verbosity and control behavior. It enables callbacks, sets the stdout callback to 'yaml', and suppresses warnings.

```ini
[defaults]
bin_ansible_callbacks=True
stdout_callback = yaml
localhost_warning = false
display_skipped_hosts = false
```

--------------------------------

### Execute Ansible Playbook

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Executes an Ansible playbook using `ansible-playbook`. This command targets a specific inventory file and playbook, demonstrating how to run the collection's playbooks.

```bash
$ ansible-playbook -i ./inventory.yml stormshield.sns.sns_system_property
```

--------------------------------

### Execute Ansible Playbook

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Executes an Ansible playbook, specifying the inventory file and the playbook name. This command initiates the configuration or management tasks defined in the playbook.

```bash
ansible-playbook -i ./inventory.yml stormshield.sns.sns_system_property
```

--------------------------------

### Ansible Playbook for SNS Policy Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

This playbook configures network policies on SNS appliances using the stormshield.sns.object and stormshield.sns.policy roles. It defines network objects, IP addresses, and firewall rules with specified actions, source/destination targets, and ports.

```yaml
- hosts: sns_appliances
  roles:
    - role: stormshield.sns.object
      hosts :
      - { name: intranet, ip: 192.168.2.1, comment: "Intranet server"}
      networks:
      - { name: usernetwork, ip: 192.168.1.0, mask: 255.255.255.0 }
    - role: stormshield.sns.policy
      activate: yes
      slot: 5
      filter:
      - { action: pass, srctarget: usernetwork, dsttarget: intranet, dstport: https, comment: "Intranet"}
      - { action: pass, srctarget: any, dsttarget: any, comment: "Warning, pass all example"}
```

--------------------------------

### Build Ansible Collection

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/BUILD.md

Builds the Ansible collection using the `ansible-galaxy` command. The `--force` option ensures the collection is rebuilt even if it already exists.

```bash
ansible-galaxy collection build --force

```

--------------------------------

### Run SNS Policy Playbook

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Executes the playbook configured for SNS policy management. This command applies the defined network policies to the specified appliances.

```bash
ansible-playbook -i ./inventory.yml policy.yml
```

--------------------------------

### Configure Ansible Inventory

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Defines the inventory file for Ansible, specifying the Stormshield SNS appliances to be managed. It includes connection details like host IP, username, and password, with an option for SSL certificate verification.

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: secret
        sslverifyhost: false
```

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: VMSNSX08K000111
        ip: 10.0.0.254
        user: admin
        password: secret
        sslverifyhost: true
```

--------------------------------

### SNS DNS Role Variables

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_dns/README.md

Defines the DNS servers to be configured on Stormshield Network Security appliances. It expects a list of dictionaries, each containing a 'host' (object/host name) and an 'ip' address.

```YAML
dns_servers:
  - { host: "mydns1", ip: "10.0.0.1"}
  - { host: "mydns2", ip: "10.0.0.2"}
```

--------------------------------

### Ansible Inventory with Plaintext SNS Passwords

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

This snippet illustrates the initial structure of an Ansible inventory file where SNS appliance credentials, including passwords, are stored in plain text. This is a precursor to securing them with Ansible Vault.

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: 192.168.152.129
        user: admin
        password: secret
        sslverifyhost: false
```

--------------------------------

### Ansible Vault Usage for SNS Passwords

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/README.md

Demonstrates the process of securing SNS passwords using Ansible Vault. This involves creating an encrypted variable file, adding password entries, and referencing these variables in the inventory file for secure playbook execution.

```shell
mkdir -p groups_vars/sns_appliances
ansible-vault create groups_vars/sns_appliances/vault.yml

# Add entries to vault.yml:
---
utm1_password: "secret"

# Edit inventory to reference vault variable:
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: "{{utm1_password}}"
        sslverifyhost: false

# Run playbook with vault password prompt:
ansible-playbook -i inventory.yml --ask-vault-pass stormshield.sns.sns_system_property
```

--------------------------------

### Ansible Playbook for SNS Firmware Update

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_firmware_update/README.md

This playbook demonstrates how to use the 'sns_firmware_update' Ansible role to upgrade the firmware on SNS appliances. It specifies the target hosts and configures the role with a specific firmware version and backup setting.

```yaml
---
- hosts: sns_appliances
  serial: 1
  roles:
    - role: stormshield.sns.sns_firmware_update
      version: 4.1.0
      system_clone: False

```

--------------------------------

### Ansible Role: stormshield.sns.sns_alarm Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_alarm/README.md

Defines the structure for configuring IPS alarms using the stormshield.sns.sns_alarm Ansible role. It details the 'protocols' variable, which is a list of protocol configurations, each containing a list of alarm definitions with various options.

```APIDOC
Role Variables:
  protocols: List of protocol configurations.
    - protocol: <protocol name> (e.g., http, smtp, dns)
      alarms: List of alarm definitions for the protocol.
        - { index:<profile index>, id:<int>, context:(protocol|<ASQ context name>), options... }

Alarm Definition Options:
  [action=(pass|block)]
    - Specifies the action to take for the alarm.
  [level=(minor|major|ignore)]
    - Sets the severity level of the alarm.
  [dump=(0|1)]
    - Enables or disables packet dumping for the alarm.
  [email=off | email=on emailduration=<seconds> emailcount=<int>]
    - Configures email notifications for the alarm, including duration and count.
  [blacklist=off | blacklist=on blduration=<minutes>]
    - Configures blacklisting for the source of the alarm, including duration.
  [comment=<string>]
    - Adds a descriptive comment to the alarm definition.
  [qid=<Queue name>]
    - Assigns the alarm to a specific queue.
  [ackqid=<Queue name>]
    - Assigns the alarm to a specific acknowledgement queue (available from 4.3.0).

Dependencies:
  None.
```

--------------------------------

### Ansible CSV File Import Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_object/README.md

This snippet demonstrates the configuration for importing CSV files within the Ansible SNS Collection. It specifies the path to the CSV file to be processed, typically used for data ingestion or object management tasks.

```YAML
csvfileimport:
  - /path/myobjects.csv
```

--------------------------------

### SNS Policy Rule Syntax and Parameters

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_policy/README.md

Specifies the syntax and available parameters for defining NAT and filter rules within the sns_policy Ansible role. This DSL allows detailed configuration of network traffic policies.

```APIDOC
SNS Policy Rule Tokens:

Rule Structure:
  ( position=<digit> | name=<string> )
  [state=(on|off)]
  [action=(pass|block|deleg|reset|log|decrypt|nat)]
  [loglevel=(none|log|minor|major)]
  [noconnlog=(|all|[disk],[syslog],[ipfix])]
  [count=(on|off)]
  [rate=(|<tcp>,<udp>,<icmp>,<request>)]
  [synproxy=(on|off)]
  [settos=(|<1-254>)]
  [qosid=(|<qid name>)]
  [ackqosid=(|<qid name>)] (Available from 4.3.0)
  [qosfairness=(|state|user|host)]
  [route=(|<objrouter>|<hostname>|<ipaddr>)]
  [inspection=(firewall|ids|ips)]
  [antivirus=(on|off)]
  [sandboxing=(on|off)]
  [antispam=(on|off)]
  [proxycache=(on|off)]
  [ftpfiltering=(on|off)]
  [urlfiltering=(|<0-9>)] (URL policy index)
  [mailfiltering=(|<0-9>)] (Mail policy index)
  [sslfiltering=(|<0-9>)] (SSL policy index)
  [fwservice=(|httpproxy|webportal)]
  [webportalexcept=(|urlgroup[,urlgroup[,urlgroup[,...]]])]
  [inbound=(|sip_udp)]
  [schedule=(anytime|<time object>)]
  [securityinspection=(|<0-9>)] (ASQ config index)
  [tos=(|<1-254>)]
  [ipstate=(on|off)]
  [ipproto=(any|<IP protocol name>)] (e.g., TCP, UDP, ICMP)
  [icmptype=(|<0-255>)]
  [icmpcode=(|<0-255>)]
  [proto=(auto|none|<app protocol name>)] (e.g., HTTP, FTP)
  [srcuser=(|any|unknown|[!]<user>|[!]<usergroup>)]
  [srcusertype=(|user|group)]
  [srcuserdomain=(|<domain name>)]
  [srcusermethod=(|plain|spnego|ssl|radius|kerberos|agent-ad|openvpn|ipsec|guest|agent-guard)]
  [srctarget=(any|[!]<objectname>[,<objectname>[,<objectname>[,...]]])]
  [srcportop=(eq|ne|gt|lt)]
  [srcport=(any|<objectservice>[,<objectservice>[,<objectservice>[,...]]])]
  [srcif=(any|<interface name>)]
  [srcgeo=(<objectgeo[|<objectgeo>[|...]]>)]
  [srciprep=(<objectiprep[|<objectiprep>[|...]]>)]
  [srchostrep=(<0-65535>)]
  [srchostrepop=(lt|gt)]
  [via=(any|sslvpn|httpproxy|ipsec|sslproxy|none)]
  [dsttarget=(any|[!]<objectname>[,<objectname>[,<objectname>[,...]]])]
  [dstportop=(eq|ne|gt|lt)]
  [dstport=(any|<objectservice>[,<objectservice>[,<objectservice>[,...]]])]
  [dstif=(any|<interface name>)]
  [dstgeo=(<objectgeo[|objectgeo[|...]]>)]
  [dstiprep=(<objectiprep[|objectiprep[|...]]>)]
  [dsthostrep=(<0-65535>)]
  [dsthostrepop=(lt|gt)]
  [natsrctarget=(|original|<object name>)] (empty value to disable nat on source)
  [natsrclb=(none|roundrobin|srchash|connhash|random)]
  [natsrcarp=(on|off)]
  [natsrcportop=(eq|ne|gt|lt)]
  [natsrcport=(original|<objectservice>|<port range>)]
  [natsrcportlb=(none|random)]
  [natdsttarget=(|original|<object name>)] (empty value to disable nat on destination)
  [natdstlb=(none|roundrobin|srchash|connhash|random)]
  [natdstarp=(on|off)]
  [natdstportop=(eq|ne|gt|lt)]
  [natdstport=(original|<objectservice>|<port range>)]
  [natdstportlb=(none|roundrobin|srchash|connhash|random)]
  [beforevpn=(on|off)]
  [enforceipsecforward=(on|off)]
  [enforceipsecreverse=(on|off)]
  [comment=<string>]
  [rulename=<string>]
```

--------------------------------

### Run Playbook with Vault Password Prompt

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Executes an Ansible playbook while prompting the user for the Ansible Vault master password. This is necessary to decrypt the sensitive variables used in the playbook or inventory.

```bash
ansible-playbook -i inventory.yml --ask-vault-pass stormshield.sns.sns_system_property
```

--------------------------------

### Ansible Playbook for SNS Policy Configuration

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_policy/README.md

This playbook demonstrates how to use the sns_policy Ansible role to configure filter and NAT policies on Stormshield appliances. It shows variable usage for activating policies, setting slots, and defining filter/NAT rules.

```yaml
- hosts: sns_appliances
  roles:
      - role: stormshield.sns.sns_policy
        activate: yes
        slot: 5
        filter:
          - { action: pass, srctarget: any, dsttarget: Firewall_out, dstport: ssh, comment: "Allow SSH"}
          - { action: block, srctarget: any, srcif: out, dsttarget: any }
          - { action: pass, srctarget: any, dsttarget: any, inspection: firewall }
        nat:
          - { action: nat, srctarget: network_in, dsttarget: Internet, dstif: out, natsrctarget: firewall_out, natsrcport: ephemeral_fw }
```

--------------------------------

### Ansible Role Variables for sns_url

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_url/README.md

Defines the configurable parameters for the sns_url Ansible role, covering base URL database, URL/CN group definitions, category group management, filtering rules, and block page uploads.

```APIDOC
base: cloud|embedded
  - Description: Choose between downloadable embedded URL database or extended web control cloud service.
  - Type: string
  - Allowed Values: ["cloud", "embedded"]
```

```APIDOC
urlgroups:
  - name: <urlgroup name>
    comment: <comment>
    urls: [ { url: <url>, comment: <comment> }, ... ]
  - Description: Define URL groups with associated URLs and comments.
  - Type: list of dictionaries
```

```APIDOC
cngroups:
  - name: <urlgroup name>
    comment: <comment>
    cns: [ { cn: <url>, comment: <comment> }, ... ]
  - Description: Define CN (Common Name) groups with associated CNs and comments.
  - Type: list of dictionaries
```

```APIDOC
urlcategorygroups:
  - name: <category group>
    comment: <comment>
    members: [ <urlgroup>, ... ]
    mode: <add|del|reset>
  - Description: Define URL category groups, referencing existing URL groups.
  - Type: list of dictionaries
  - Mode Parameter:
    - add: Adds members to an existing group.
    - reset: Empties the group before adding members (default).
    - del: Removes members from the group.
```

```APIDOC
cncategorygroups:
  - name: <category group>
    comment: <comment>
    members: [ <cngroup>, ... ]
    mode: <add|del|reset>
  - Description: Define CN category groups, referencing existing CN groups.
  - Type: list of dictionaries
  - Mode Parameter:
    - add: Adds members to an existing group.
    - reset: Empties the group before adding members (default).
    - del: Removes members from the group.
```

```APIDOC
state: absent
  - Description: If set to 'absent', deletes the specified objects.
  - Type: string
  - Allowed Values: ["present", "absent"]
```

```APIDOC
urlfiltering:
  - index: <slot number>
    name: <slot name>
    comment: <slot comment>
    rules: [
      - [ruleid: <digit>]
        state: on|off
        action: pass|block|blockpage0|blockpage1|blockpage2|blockpage3
        urlgroup: <urlgroup object|urlcategory group object>
        [comment: <string>]
    ]
  - Description: Define URL filtering slots and rules. Each rule specifies state, action, and the URL group to apply.
  - Type: list of dictionaries
```

```APIDOC
sslfiltering:
  - index: <slot number>
    name: <slot name>
    comment: <slot comment>
    rules: [
      - [ruleid: <digit>]
        state: on|off
        action: pass|block|blockpage0|blockpage1|blockpage2|blockpage3
        cngroup: <cngroup object|cncategory group object>
        [comment: <string>]
    ]
  - Description: Define SSL filtering slots and rules. Each rule specifies state, action, and the CN group to apply.
  - Type: list of dictionaries
```

```APIDOC
blockpages:
  - index: 0
    file: <filepath>
    name: <page name>
  - index: 1
    file: <filepath>
    name: <page name>
  - Description: Upload HTML files for custom block pages. Supports indices 0 through 4.
  - Type: list of dictionaries
```

--------------------------------

### Encrypt Passwords with Ansible Vault

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Demonstrates using Ansible Vault to encrypt sensitive data like passwords within inventory files. This enhances security by protecting credentials from plain-text exposure.

```bash
mkdir -p groups_vars/sns_appliances
```

```bash
ansible-vault create groups_vars/sns_appliances/vault.yml
```

```bash
ansible-vault edit groups_vars/sns_appliances/vault.yml
```

--------------------------------

### Ansible Role sns_policy Parameters

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_policy/README.md

Defines the configurable parameters for the sns_policy Ansible role. These variables control the slot configuration, activation status, and the mode of operation (add, reset, delete) for policies.

```APIDOC
Ansible Role sns_policy Parameters:

slot: ""
  - Description: Slot name.
  - Type: string
  - Default: ""

comment: ""
  - Description: Slot description.
  - Type: string
  - Default: ""

filter: []
  - Description: Filter rules configuration.
  - Type: list
  - Default: []

nat: []
  - Description: NAT rules configuration.
  - Type: list
  - Default: []

scope: local|global
  - Description: Use global or local slot.
  - Type: string
  - Default: "local"

slot: 0-10
  - Description: Slot number.
  - Type: integer
  - Default: 5

activate: yes|no
  - Description: Activate the slot.
  - Type: boolean
  - Default: "yes"

mode: add|reset|del
  - Description: Operation mode: 'reset' flushes rules before adding, 'add' inserts rules, 'del' deletes specified rules.
  - Type: string
  - Default: "reset"
```

--------------------------------

### Use Encrypted Password in Inventory

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/docs/docsite/rst/usage.rst

Shows how to reference an Ansible Vault encrypted variable within the inventory file. The password for the appliance is dynamically loaded from the encrypted vault.

```yaml
sns_appliances:
  hosts:
    utm1:
      ansible_connection: local
      appliance:
        host: 10.0.0.254
        user: admin
        password: "{{utm1_password}}"
        sslverifyhost: false
```

--------------------------------

### Ansible SNS NTP Role Variables

Source: https://github.com/stormshield/ansible-sns-collection/blob/main/roles/sns_ntp/README.md

Defines configurable variables for the sns_ntp Ansible role, including timezone, NTP server configuration, and reboot behavior. These variables control the NTP service state, server list, and whether a reboot is necessary for timezone updates.

```yaml
timezone: "Europe/Paris"

ntp_state: 1

ntp_servers:
  - { host: "fr.pool.ntp.org"}
  - { host: "be.pool.ntp.org", key: "12345678"}

reboot_if_needed: true
```
Tokens:
Raw