373 lines
12 KiB
Markdown
373 lines
12 KiB
Markdown
# Sophos XGS Ansible Project - Summary
|
|
|
|
## Project Statistics
|
|
|
|
- **Total Files**: 51
|
|
- **Total Lines of Code**: 3,809
|
|
- **Main Playbooks**: 2 (site.yml, baseline_import.yml)
|
|
- **Ansible Roles**: 8
|
|
- **Jinja2 Templates**: 14
|
|
- **Documentation Files**: 3 (README.md, QUICKSTART.md, PROJECT_SUMMARY.md)
|
|
- **Example Configurations**: 4 (fw-baseline, fw-branch1, fw-branch2, fw-sample1)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
sophos-xgs-ansible/
|
|
├── site.yml # Main configuration playbook
|
|
├── baseline_import.yml # WAF baseline export playbook
|
|
├── ansible.cfg # Ansible configuration
|
|
├── README.md # Complete documentation
|
|
├── QUICKSTART.md # Quick start guide
|
|
├── PROJECT_SUMMARY.md # This file
|
|
│
|
|
├── collections/
|
|
│ └── requirements.yml # Required Ansible collections
|
|
│
|
|
├── inventory/
|
|
│ ├── hosts.ini # Firewall inventory
|
|
│ ├── group_vars/
|
|
│ │ ├── all.yml # Global defaults
|
|
│ │ ├── sophos_firewalls.yml # Sophos-specific defaults
|
|
│ │ └── baseline_web.yml # Baseline WAF config (auto-generated)
|
|
│ └── host_vars/
|
|
│ ├── fw-baseline.yml # Baseline firewall config
|
|
│ ├── fw-branch1.yml # Branch 1 (with site-to-site VPN)
|
|
│ └── fw-branch2.yml # Branch 2 (with remote access VPN)
|
|
│
|
|
├── roles/
|
|
│ ├── sophos_common/ # Connectivity & validation
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── vars/main.yml
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_network/ # Network configuration
|
|
│ │ ├── tasks/
|
|
│ │ │ ├── main.yml
|
|
│ │ │ ├── interfaces.yml
|
|
│ │ │ ├── vlans.yml
|
|
│ │ │ ├── dhcp.yml
|
|
│ │ │ ├── dns.yml
|
|
│ │ │ └── routes.yml
|
|
│ │ ├── templates/
|
|
│ │ │ ├── interface.json.j2
|
|
│ │ │ ├── vlan.json.j2
|
|
│ │ │ ├── dhcp_server.json.j2
|
|
│ │ │ ├── dns_config.json.j2
|
|
│ │ │ └── static_route.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_firewall_rules/ # Firewall rule management
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── templates/firewall_rule.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_vpn_site_to_site/ # Site-to-site VPN
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── templates/ipsec_connection.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_vpn_remote_access/ # Remote access VPN
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── templates/remote_access_vpn.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_waf/ # Web application firewall
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── templates/
|
|
│ │ │ ├── waf_backend.json.j2
|
|
│ │ │ ├── waf_policy.json.j2
|
|
│ │ │ └── waf_exception.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ ├── sophos_device_access/ # Management access control
|
|
│ │ ├── tasks/main.yml
|
|
│ │ ├── templates/device_access_rule.json.j2
|
|
│ │ └── defaults/main.yml
|
|
│ │
|
|
│ └── sophos_snmp_logging/ # SNMP, syslog, NTP
|
|
│ ├── tasks/main.yml
|
|
│ ├── templates/
|
|
│ │ ├── snmp_config.json.j2
|
|
│ │ ├── syslog_server.json.j2
|
|
│ │ └── ntp_config.json.j2
|
|
│ └── defaults/main.yml
|
|
│
|
|
└── tests/
|
|
├── sample_config/
|
|
│ └── fw-sample1.yml # Sample configuration
|
|
└── linting/
|
|
├── ansible-lint.yml # Ansible linting rules
|
|
└── .yamllint # YAML linting rules
|
|
```
|
|
|
|
## Feature Coverage
|
|
|
|
### Network Configuration ✅
|
|
- Physical interface configuration (IP, zone, MTU, admin state)
|
|
- VLAN interface creation and management
|
|
- DHCP server configuration with reservations and custom options
|
|
- DNS forwarder configuration
|
|
- Static route management
|
|
|
|
### Security & Firewall ✅
|
|
- Layer 3/4 firewall rules with zone-based filtering
|
|
- Rule ordering control (top, bottom, position)
|
|
- Common baseline rules applied fleet-wide
|
|
- Per-firewall custom rules
|
|
|
|
### VPN ✅
|
|
- **Site-to-Site IPsec VPN**
|
|
- Phase 1 (IKE) configuration
|
|
- Phase 2 (IPsec) configuration
|
|
- Dead Peer Detection (DPD)
|
|
- NAT traversal support
|
|
|
|
- **Remote Access VPN**
|
|
- SSL VPN configuration
|
|
- User group authentication
|
|
- IP address pool management
|
|
- Split tunnel support
|
|
- DNS and routing for VPN clients
|
|
|
|
### Web Application Firewall (WAF) ✅
|
|
- Backend server configuration
|
|
- Protection policy management
|
|
- Virtual host/web policy configuration
|
|
- Exception/allow-list management
|
|
- **Baseline import functionality** (export from one firewall, apply to fleet)
|
|
|
|
### Management & Monitoring ✅
|
|
- Device access policies (HTTPS, SSH, SNMP, ping)
|
|
- SNMP configuration (v2c/v3, community strings, trap destinations)
|
|
- Syslog server configuration
|
|
- NTP time synchronization
|
|
|
|
## Key Design Features
|
|
|
|
### 1. Idempotency
|
|
All operations are designed to be safely re-runnable:
|
|
- API state checking before modifications
|
|
- `changed_when` conditions on all tasks
|
|
- Proper handling of create vs. update operations
|
|
|
|
### 2. Baseline Import System
|
|
Unique feature for WAF configuration:
|
|
- Export WAF config from baseline firewall via API
|
|
- Transform to structured YAML variables
|
|
- Commit to version control
|
|
- Apply as fleet-wide defaults
|
|
- Allow per-firewall overrides
|
|
|
|
### 3. Production-Ready
|
|
- Ansible Vault support for credentials
|
|
- Comprehensive error handling
|
|
- Retry logic for API calls
|
|
- Timeout configuration
|
|
- No-log for sensitive data
|
|
- Serial execution control
|
|
|
|
### 4. CI/CD Integration
|
|
- Check mode for dry-runs
|
|
- Tagging system for partial deployments
|
|
- Example GitLab CI configuration
|
|
- Ansible-lint and yamllint configurations
|
|
|
|
### 5. Comprehensive Documentation
|
|
- README with full usage guide
|
|
- QUICKSTART for rapid deployment
|
|
- Inline comments in all playbooks and roles
|
|
- Example configurations with realistic data
|
|
|
|
## Usage Examples
|
|
|
|
### Deploy Full Configuration
|
|
```bash
|
|
ansible-playbook -i inventory/hosts.ini site.yml
|
|
```
|
|
|
|
### Deploy to Specific Firewall
|
|
```bash
|
|
ansible-playbook -i inventory/hosts.ini site.yml --limit fw-branch1
|
|
```
|
|
|
|
### Deploy Specific Components
|
|
```bash
|
|
# Network only
|
|
ansible-playbook -i inventory/hosts.ini site.yml --tags network
|
|
|
|
# VPN only
|
|
ansible-playbook -i inventory/hosts.ini site.yml --tags vpn
|
|
|
|
# WAF only
|
|
ansible-playbook -i inventory/hosts.ini site.yml --tags waf
|
|
```
|
|
|
|
### Baseline Import Workflow
|
|
```bash
|
|
# 1. Export baseline WAF config
|
|
ansible-playbook -i inventory/hosts.ini baseline_import.yml
|
|
|
|
# 2. Review generated config
|
|
cat inventory/group_vars/baseline_web.yml
|
|
|
|
# 3. Commit to version control
|
|
git add inventory/group_vars/baseline_web.yml
|
|
git commit -m "Update baseline WAF configuration"
|
|
|
|
# 4. Apply to fleet
|
|
ansible-playbook -i inventory/hosts.ini site.yml --tags waf
|
|
```
|
|
|
|
### Secure Credentials
|
|
```bash
|
|
# Encrypt host variables
|
|
ansible-vault encrypt inventory/host_vars/fw-branch1.yml
|
|
|
|
# Run with vault password
|
|
ansible-playbook -i inventory/hosts.ini site.yml --ask-vault-pass
|
|
```
|
|
|
|
## Variable Schema
|
|
|
|
Complete variable documentation available in separate schema document. Key variable types:
|
|
|
|
- **Network**: `sophos_interfaces`, `sophos_vlans`, `sophos_dhcp_servers`, `sophos_dns`, `sophos_static_routes`
|
|
- **Firewall**: `sophos_firewall_rules`, `sophos_common_firewall_rules`
|
|
- **VPN**: `sophos_site_to_site_vpns`, `sophos_remote_access_vpn`
|
|
- **WAF**: `sophos_waf_backends`, `sophos_waf_policies`, `sophos_waf_virtual_hosts`, `sophos_waf_exceptions`
|
|
- **Management**: `sophos_common_device_access_policies`, `sophos_snmp`, `sophos_logging`, `sophos_ntp`
|
|
|
|
## Testing & Quality
|
|
|
|
### Linting
|
|
- ansible-lint configuration included
|
|
- yamllint configuration included
|
|
- Skips appropriate false-positives
|
|
|
|
### Sample Configurations
|
|
- fw-baseline: Baseline firewall with DMZ
|
|
- fw-branch1: Branch with site-to-site VPN, VLANs, DHCP options
|
|
- fw-branch2: Branch with remote access VPN
|
|
- fw-sample1: Minimal test configuration
|
|
|
|
### Validation
|
|
- Pre-flight connectivity checks
|
|
- Required variable validation
|
|
- API authentication testing
|
|
- Firmware version compatibility warnings
|
|
|
|
## Deployment Scenarios
|
|
|
|
### Scenario 1: New Firewall Fleet
|
|
1. Define inventory in `hosts.ini`
|
|
2. Create host_vars for each firewall
|
|
3. Run full site.yml deployment
|
|
4. Verify with check mode first
|
|
|
|
### Scenario 2: Existing Fleet with WAF
|
|
1. Define baseline firewall in inventory
|
|
2. Run baseline_import.yml to export WAF config
|
|
3. Review and commit baseline_web.yml
|
|
4. Deploy to remaining firewalls with site.yml
|
|
|
|
### Scenario 3: Incremental Updates
|
|
1. Modify specific variables in host_vars
|
|
2. Use tags to deploy only changed components
|
|
3. Use --limit to target specific firewalls
|
|
4. Review changes with --check first
|
|
|
|
### Scenario 4: CI/CD Pipeline
|
|
1. Commit changes to Git
|
|
2. CI pipeline validates with ansible-lint
|
|
3. CI runs check mode for preview
|
|
4. Manual approval required
|
|
5. CD applies changes to production
|
|
|
|
## API Integration
|
|
|
|
### Sophos XGS API
|
|
- Uses XML-based API via HTTPS
|
|
- Default port: 4444 (management interface)
|
|
- Authentication: Username/password or API key
|
|
- All operations via `uri` Ansible module
|
|
- XML templates in Jinja2 for all API calls
|
|
|
|
### Error Handling
|
|
- HTTP status code validation
|
|
- XML response parsing
|
|
- Retry logic with configurable delays
|
|
- Timeout protection
|
|
- Graceful failure modes
|
|
|
|
## Security Considerations
|
|
|
|
### Credentials Management
|
|
- Ansible Vault integration
|
|
- No-log for sensitive tasks
|
|
- Separate credentials per firewall
|
|
- Support for both password and API key auth
|
|
|
|
### Network Security
|
|
- API access over HTTPS only
|
|
- Certificate validation (configurable)
|
|
- Device access policies to restrict management
|
|
- Rate limiting via serial execution
|
|
|
|
### Audit Trail
|
|
- All changes logged by Sophos XGS
|
|
- Ansible execution logs
|
|
- Commit history in Git
|
|
- CI/CD pipeline logs
|
|
|
|
## Maintenance & Support
|
|
|
|
### Regular Maintenance Tasks
|
|
1. Update baseline WAF configuration monthly
|
|
2. Review firewall logs for errors
|
|
3. Rotate credentials quarterly
|
|
4. Update Ansible collections
|
|
5. Test in lab before production deployment
|
|
|
|
### Troubleshooting Resources
|
|
1. README.md troubleshooting section
|
|
2. Role task files (detailed comments)
|
|
3. Template files (show API structure)
|
|
4. Ansible verbose mode (-vvv)
|
|
5. Sophos XGS API documentation
|
|
|
|
## Future Enhancements
|
|
|
|
Potential additions for future versions:
|
|
- SD-WAN configuration
|
|
- Application control policies
|
|
- IPS signature management
|
|
- Certificate management
|
|
- User authentication (LDAP/RADIUS)
|
|
- High availability (HA) configuration
|
|
- Backup and restore automation
|
|
- Custom report generation
|
|
- Webhook integrations
|
|
|
|
## Version History
|
|
|
|
- **v1.0.0** (2025-12-09): Initial release
|
|
- Complete feature set
|
|
- 8 roles covering all major areas
|
|
- Baseline import functionality
|
|
- Comprehensive documentation
|
|
- Production-ready
|
|
|
|
## License & Credits
|
|
|
|
This project is provided as-is for network automation purposes.
|
|
|
|
**Created by**: Network Automation Team
|
|
**Date**: December 9, 2025
|
|
**Ansible Version**: 2.14+
|
|
**Sophos XGS Firmware**: 19.x, 20.x
|
|
|
|
---
|
|
|
|
**Ready for production deployment!**
|