docs and galaxy publish workflow

.github/workflows/release.yaml

@@ -0,0 +1,57 @@
+name: Publish Ansible Collection
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # Trigger on version tags like x.x.x
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout the repository
+      - name: Check out the repository
+        uses: actions/checkout@v3
+
+      # Set up Python environment
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      # Install ansible-core
+      - name: Install Ansible
+        run: |
+          python -m pip install --upgrade pip
+          pip install ansible-core
+
+      # Build the collection
+      - name: Build Ansible Collection
+        run: |
+          ansible-galaxy collection build
+        # Capture the built file name
+        id: build
+
+      # Capture the tar.gz filename from the build output
+      - name: Get tar.gz filename
+        shell: bash
+        run: |
+          COLLECTION_FILE=$(ls *.tar.gz)
+          echo "COLLECTION_FILE=${COLLECTION_FILE}" >> $GITHUB_ENV
+
+      # Upload the collection file to the release
+      - name: Upload Release Asset
+        uses: actions/upload-release-asset@v1
+        with:
+          upload_url: "${{ github.event.release.upload_url }}"
+          asset_path: "${{ env.COLLECTION_FILE }}"
+          asset_name: "${{ env.COLLECTION_FILE }}"
+          asset_content_type: application/gzip
+
+      # Publish the collection to Ansible Galaxy
+      - name: Publish to Ansible Galaxy
+        env:
+          GALAXY_TOKEN: ${{ secrets.GALAXY_TOKEN }}
+        run: |
+          ansible-galaxy collection publish "${{ env.COLLECTION_FILE }}" --api-key $GALAXY_TOKEN

.gitignore

@@ -3,3 +3,4 @@ inventory.yml
 tests/output/
 tests/integration/inventory
 changelogs/.plugin-cache.yaml
+*.tar.gz

README.md

@@ -1,3 +1,32 @@
 # Ansible Collection - sophos.sophos_firewall
+This collection provides modules for working with Sophos Firewall running SFOS 18.0+. The modules leverage the [sophosfirewall-python](https://sophosfirewall-python.readthedocs.io) SDK to perform operations on the firewall using the embedded [XML API](https://docs.sophos.com/nsg/sophos-firewall/21.0/API/index.html).
+
+For installation and usage details, please see the [Documentation](https://sophosfirewall-ansible.readthedocs.io)
+
+
+## Contributing
+This is an open source project and we welcome contributions from the community. To get started, fork this repository and perform development in the fork. The following guidelines should be followed:
+
+- This project uses [Semantic Versioning](https://semver.org)
+- When adding new modules, increment the `MINOR` version
+- When making bug fixes, increment the `PATCH` version
+- When adding new modules, configure the `version_added` field to the new version the module will be added to
+- Update the `version` field in `galaxy.yml` to the new version
+- In the `changelogs/fragments` directory, add a file named `x.y.z.yaml` where x.y.z indicates the version
+- The file should have at a minimum, a `release_summary` field for example:
+```yaml
+release_summary: |
+  This release introduces new modules for working with the X feature on Sophos Firewall
+```
+- Github Actions will take care of updating the documentation and changelog automatically upon PR merge
+
+### Tests
+When adding a new module, integration tests should be written and stored under the `tests/integration` directory. Each module should have a directory in the `targets` folder, and a `main.yml` file implementing the test cases. Tests can be run against a physical or virtual Sophos Firewall appliance. To run these tests against your own firewall, a file `integration_config.yml` must be created in the `tests` directory. An file `integration.yml.template` file is provided as an example. The variables in the example file should be replaced with the actual values, and the file renamed to `integration.yml`.  Once these steps are complete, tests for a specific module can be run using `ansible-test integration [module_name]`:
+
+```bash
+ansible-test integration sfos_syslog -v
+```
+
+
+
 
-Documentation for the collection.

docs/conf.py

@@ -30,6 +30,8 @@
 html_use_index = False
 html_copy_source = False
 
+html_static_path = ['static']
+
 # See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping for the syntax
 intersphinx_mapping = {
     'python': ('https://docs.python.org/2/', (None, '../python2.inv')),

docs/docsite/config.yml

@@ -0,0 +1,2 @@
+changelog:
+  write_changelog: true

docs/docsite/extra-docs.yml

@@ -0,0 +1,5 @@
+sections:
+  - title: Installation and Setup
+    toctree:
+      - installation
+      - setup

docs/docsite/rst/installation.rst

@@ -0,0 +1,29 @@
+.. _ansible_collections.sophos.sophos_firewall.docsite.installation:
+
+Installation
+============
+
+Prerequisites
+-------------
+The following must be installed prior to installing the module:
+
+* Python 3.11+
+* Ansible 2.16+
+* sophosfirewall-python 0.1.56+
+
+The sophosfirewall-python module can be installed with ``pip``:
+
+.. code-block:: bash
+
+    $ pip install sophosfirewall-python
+
+Install
+-------
+The Sophos Firewall Ansible Collection can be installed using the ``ansible-galaxy`` command-line utility:
+
+.. code-block:: bash
+
+    $ ansible-galaxy collection install sophos.sophos_firewall
+
+
+

docs/docsite/rst/setup.rst

@@ -0,0 +1,11 @@
+.. _ansible_collections.sophos.sophos_firewall.docsite.setup:
+
+Setup
+=====
+Prior to using the Ansible modules, the firewall must be set up to allow access to the API
+from the IP address of the system running Ansible.
+
+In the firewall dashboard, navigate to **Backup & firmware** and click on the **API** tab.
+Check the box to enable API Configuration, and add the Ansible controller to the Allowed IP address field.
+
+.. image:: ../../_static/images/setup.jpg

docs/rst/changelog.rst

@@ -0,0 +1,63 @@
+=====================================
+Sophos.Sophos\_Firewall Release Notes
+=====================================
+
+.. contents:: Topics
+
+v1.2.0
+======
+
+Release Summary
+---------------
+
+This release adds modules for working with IPS and Syslog settings
+
+New Modules
+-----------
+
+- sophos.sophos_firewall.sfos_ips - Manage IPS protection (Protect > Intrusion Protection > IPS policies).
+- sophos.sophos_firewall.sfos_syslog - Manage Syslog servers (Configure > System services > Log settings).
+
+v1.1.0
+======
+
+Release Summary
+---------------
+
+This release contains new modules for working with the SNMP agent and SNMPv3 users on Sophos Firewall
+
+New Modules
+-----------
+
+- sophos.sophos_firewall.sfos_snmp_agent - Manage SNMP Agent (System > Administration > SNMP).
+- sophos.sophos_firewall.sfos_snmp_user - Manage SNMPv3 User (System > Administration > SNMP).
+
+v1.0.0
+======
+
+Release Summary
+---------------
+
+This is the first proper release of the ``sophos.sophos_firewall`` collection.
+
+New Modules
+-----------
+
+- sophos.sophos_firewall.sfos_admin_settings - Manage Admin and user settings (System > Administration).
+- sophos.sophos_firewall.sfos_atp - Manage Active Threat Protection (Protect > Active threat response > Sophos X-Ops threat feeds).
+- sophos.sophos_firewall.sfos_backup - Manage Backup settings (System > Backup & firmware).
+- sophos.sophos_firewall.sfos_device_access_profile - Manage Device Access Profiles (System > Profiles > Device Access).
+- sophos.sophos_firewall.sfos_dns - Manage DNS settings (Configure > Network > DNS).
+- sophos.sophos_firewall.sfos_firewall_rule - Manage Firewall Rules (Protect > Rules & policies).
+- sophos.sophos_firewall.sfos_fqdn_host - Manage FQDN hosts (System > Hosts & services > FQDN host).
+- sophos.sophos_firewall.sfos_fqdn_hostgroup - Manage FQDN Host Groups (System > Hosts & services > FQDN host group).
+- sophos.sophos_firewall.sfos_ip_host - Manage IP Host (System > Hosts & services > IP host).
+- sophos.sophos_firewall.sfos_ip_hostgroup - Manage IP Hostgroup (System > Hosts & services > IP host group).
+- sophos.sophos_firewall.sfos_malware_protection - Manage Malware Protection (Configure > System services > Malware protection).
+- sophos.sophos_firewall.sfos_service - Manage Service (System > Hosts and services > Services).
+- sophos.sophos_firewall.sfos_service_acl_exception - Manage Local Service Exception ACL Rules (System > Administration > Device Access).
+- sophos.sophos_firewall.sfos_servicegroup - Manage Service Group (System > Hosts and services > Service Group).
+- sophos.sophos_firewall.sfos_time - Manage Date and Time settings (System > Administration > Time).
+- sophos.sophos_firewall.sfos_user - Manage Users (Configure > Authentication > Users).
+- sophos.sophos_firewall.sfos_xmlapi - Use the XML API to get, create, update, or delete settings on Sophos Firewall.
+- sophos.sophos_firewall.sfos_zone - Manage Zones (Configure > Network > Zones).

docs/rst/docsite/installation.rst

@@ -0,0 +1,29 @@
+.. _ansible_collections.sophos.sophos_firewall.docsite.installation:
+
+Installation
+============
+
+Prerequisites
+-------------
+The following must be installed prior to installing the module:
+
+* Python 3.11+
+* Ansible 2.16+
+* sophosfirewall-python 0.1.56+
+
+The sophosfirewall-python module can be installed with ``pip``:
+
+.. code-block:: bash
+
+    $ pip install sophosfirewall-python
+
+Install
+-------
+The Sophos Firewall Ansible Collection can be installed using the ``ansible-galaxy`` command-line utility:
+
+.. code-block:: bash
+
+    $ ansible-galaxy collection install sophos.sophos_firewall
+
+
+

docs/rst/docsite/setup.rst

@@ -0,0 +1,11 @@
+.. _ansible_collections.sophos.sophos_firewall.docsite.setup:
+
+Setup
+=====
+Prior to using the Ansible modules, the firewall must be set up to allow access to the API
+from the IP address of the system running Ansible.
+
+In the firewall dashboard, navigate to **Backup & firmware** and click on the **API** tab.
+Check the box to enable API Configuration, and add the Ansible controller to the Allowed IP address field.
+
+.. image:: ../../_static/images/setup.jpg

docs/rst/index.rst

@@ -7,7 +7,7 @@
 Sophos.Sophos_Firewall
 ======================
 
-Collection version 1.0.0
+Collection version 1.2.0
 
 .. contents::
    :local:
@@ -16,7 +16,7 @@ Collection version 1.0.0
 Description
 -----------
 
-This Ansible collection contains modules for working with Sophos Firewall \<https://www.sophos.com/en-us/products/next-gen-firewall\>
+This Ansible collection contains modules for working with Sophos Firewall (https://www.sophos.com/en-us/products/next-gen-firewall)
 
 **Author:**
 
@@ -31,9 +31,6 @@ This Ansible collection contains modules for working with Sophos Firewall \<http
   - title: "Issue Tracker"
     url: "https://github.com/sophos/sophosfirewall-ansible/issues"
     external: true
-  - title: "Homepage"
-    url: "http://example.com"
-    external: true
   - title: "Repository (Sources)"
     url: "https://github.com/sophos/sophosfirewall-ansible"
     external: true
@@ -44,6 +41,23 @@ This Ansible collection contains modules for working with Sophos Firewall \<http
 .. toctree::
     :maxdepth: 1
 
+Changelog
+---------
+
+.. toctree::
+    :maxdepth: 1
+
+    changelog
+
+Installation and Setup
+----------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    docsite/installation
+    docsite/setup
+
 Plugin Index
 ------------
 

docs/rst/sfos_admin_settings_module.rst

@@ -22,7 +22,7 @@ sophos.sophos_firewall.sfos_admin_settings module -- Manage Admin and user setti
 .. Collection note
 
 .. note::
-    This module is part of the `sophos.sophos_firewall collection <https://galaxy.ansible.com/ui/repo/published/sophos/sophos_firewall/>`_ (version 1.0.0).
+    This module is part of the `sophos.sophos_firewall collection <https://galaxy.ansible.com/ui/repo/published/sophos/sophos_firewall/>`_ (version 1.2.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.
@@ -1529,9 +1529,6 @@ Collection links
   - title: "Issue Tracker"
     url: "https://github.com/sophos/sophosfirewall-ansible/issues"
     external: true
-  - title: "Homepage"
-    url: "http://example.com"
-    external: true
   - title: "Repository (Sources)"
     url: "https://github.com/sophos/sophosfirewall-ansible"
     external: true