CSEC_PUBLIC/securityonion
1
0
Fork 0
mirror of https://github.com/Security-Onion-Solutions/securityonion.git synced 2025-12-10 03:02:58 +01:00
Code Issues Packages Projects Releases Wiki Activity

update documentation of core functionality

Browse Source
This commit is contained in:
m0duspwnens
2025-01-18 10:45:10 -05:00
parent 64c9230423
commit 9db3cd901c
4 changed files with 444 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
salt/manager/tools/sbin/so-salt-cloud
View File

@@ -6,13 +6,39 @@
# Elastic License 2.0.
"""
Script to assist with salt-cloud VM provisioning. This is intended to work with a libvirt salt-cloud provider.
Script for automated virtual machine provisioning and configuration in Security Onion's virtualization infrastructure.
This script integrates multiple components to provide a streamlined VM deployment process:
**Usage:**
python so-salt-cloud -p <profile> <vm_name> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>)
1. Salt Cloud Integration:
- Works with libvirt salt-cloud provider for VM creation
- Manages VM lifecycle from provisioning through configuration
- Handles profile-based deployment for consistent VM setups
2. Network Configuration Management:
- Supports both DHCP and static IPv4 networking
- Pre-configures network settings before VM deployment
- Integrates with qcow2.modify_network_config for image modification
- Ensures VMs boot with correct network configuration
3. Hardware Resource Management:
- Flexible CPU and memory allocation
- Advanced PCI device passthrough capabilities
- Controlled VM startup sequence
- Uses qcow2.modify_hardware_config for hardware settings
4. Security Integration:
- Automatic firewall rule configuration
- Integrates with so-firewall-minion for firewall setup on the manager
This script serves as the primary interface for VM deployment in Security Onion, coordinating
between salt-cloud, network configuration, hardware management, and security components to
ensure proper VM provisioning and configuration.
Usage:
so-salt-cloud -p <profile> <vm_name> (--dhcp4 | --static4 --ip4 <ip_address> --gw4 <gateway>)
[-c <cpu_count>] [-m <memory_amount>] [-P <pci_id>] [-P <pci_id> ...] [--dns4 <dns_servers>] [--search4 <search_domain>]
**Options:**
Options:
-p, --profile The cloud profile to build the VM from.
<vm_name> The name of the VM.
--dhcp4 Configure interface for DHCP (IPv4).
@@ -25,98 +51,131 @@ Script to assist with salt-cloud VM provisioning. This is intended to work with
-m, --memory Amount of memory to assign in MiB.
-P, --pci PCI hardware ID(s) to passthrough to the VM (e.g., 0000:00:1f.2). Can be specified multiple times.
**Examples:**
Examples:
1. **Static IP Configuration with Multiple PCI Devices:**
1. Static IP Configuration with Multiple PCI Devices:
```bash
python so-salt-cloud -p core-hype1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 \
Command:
so-salt-cloud -p sool9-hyper1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 \
--dns4 192.168.1.1,192.168.1.2 --search4 example.local -c 4 -m 8192 -P 0000:00:1f.2 -P 0000:00:1f.3
```
This command provisions a VM named `vm1_sensor` using the `core-hype1` profile with the following settings:
This command provisions a VM named vm1_sensor using the sool9-hyper1 profile with the following settings:
- Static IPv4 configuration:
- IP Address: `192.168.1.10/24`
- Gateway: `192.168.1.1`
- DNS Servers: `192.168.1.1`, `192.168.1.2`
- DNS Search Domain: `example.local`
- IP Address: 192.168.1.10/24
- Gateway: 192.168.1.1
- DNS Servers: 192.168.1.1, 192.168.1.2
- DNS Search Domain: example.local
- Hardware Configuration:
- CPUs: `4`
- Memory: `8192` MiB
- PCI Device Passthrough: `0000:00:1f.2`, `0000:00:1f.3`
- CPUs: 4
- Memory: 8192 MiB
- PCI Device Passthrough: 0000:00:1f.2, 0000:00:1f.3
2. **DHCP Configuration with Default Hardware Settings:**
2. DHCP Configuration with Default Hardware Settings:
```bash
python so-salt-cloud -p core-hype1 vm2_master --dhcp4
```
Command:
so-salt-cloud -p sool9-hyper1 vm2_master --dhcp4
This command provisions a VM named `vm2_master` using the `core-hype1` profile with DHCP for network configuration and default hardware settings.
This command provisions a VM named vm2_master using the sool9-hyper1 profile with DHCP for network configuration and default hardware settings.
3. **Static IP Configuration without Hardware Specifications:**
3. Static IP Configuration without Hardware Specifications:
```bash
python so-salt-cloud -p core-hype1 vm3_search --static4 --ip4 192.168.1.20/24 --gw4 192.168.1.1
```
Command:
so-salt-cloud -p sool9-hyper1 vm3_search --static4 --ip4 192.168.1.20/24 --gw4 192.168.1.1
This command provisions a VM named `vm3_search` with a static IP configuration and default hardware settings.
This command provisions a VM named vm3_search with a static IP configuration and default hardware settings.
4. **DHCP Configuration with Custom Hardware Specifications and Multiple PCI Devices:**
4. DHCP Configuration with Custom Hardware Specifications and Multiple PCI Devices:
```bash
python so-salt-cloud -p core-hype1 vm4_node --dhcp4 -c 8 -m 16384 -P 0000:00:1f.4 -P 0000:00:1f.5
```
Command:
so-salt-cloud -p sool9-hyper1 vm4_node --dhcp4 -c 8 -m 16384 -P 0000:00:1f.4 -P 0000:00:1f.5
This command provisions a VM named `vm4_node` using DHCP for network configuration and custom hardware settings:
This command provisions a VM named vm4_node using DHCP for network configuration and custom hardware settings:
- CPUs: `8`
- Memory: `16384` MiB
- PCI Device Passthrough: `0000:00:1f.4`, `0000:00:1f.5`
- CPUs: 8
- Memory: 16384 MiB
- PCI Device Passthrough: 0000:00:1f.4, 0000:00:1f.5
**Notes:**
5. Static IP Configuration with DNS and Search Domain:
- When using `--static4`, both `--ip4` and `--gw4` options are required.
- The script assumes the cloud profile name follows the format `basedomain-hypervisorname`.
- Hardware parameters (`-c`, `-m`, `-P`) are optional. If not provided, default values from the profile will be used.
- The `-P` or `--pci` option can be specified multiple times to pass through multiple PCI devices to the VM.
- The `vm_name` should include the role of the VM after an underscore (e.g., `hostname_role`), as the script uses this to determine the VM's role for firewall configuration.
Command:
so-salt-cloud -p sool9-hyper1 vm1_sensor --static4 --ip4 192.168.1.10/24 --gw4 192.168.1.1 --dns4 192.168.1.1 --search4 example.local
**Description:**
This command provisions a VM named vm1_sensor using the sool9-hyper1 profile with static IPv4 configuration:
The `so-salt-cloud` script automates the provisioning of virtual machines using SaltStack's `salt-cloud` utility. It performs the following steps:
- Static IPv4 configuration:
- IP Address: 192.168.1.10/24
- Gateway: 192.168.1.1
- DNS Server: 192.168.1.1
- DNS Search Domain: example.local
1. **Network Configuration:**
Notes:
- Modifies the network settings of the base QCOW2 image before provisioning.
- Supports both DHCP and static IPv4 configurations.
- Uses the `qcow2.modify_network_config` module via SaltStack to apply these settings on the target hypervisor.
- When using --static4, both --ip4 and --gw4 options are required.
- The script assumes the cloud profile name follows the format basedomain-hypervisorname.
- Hardware parameters (-c, -m, -P) are optional. If not provided, default values from the profile will be used.
- The -P or --pci option can be specified multiple times to pass through multiple PCI devices to the VM.
- The vm_name should include the role of the VM after an underscore (e.g., hostname_role), as the script uses this to determine the VM's role for firewall configuration.
2. **VM Provisioning:**
Description:
- Calls `salt-cloud` to provision the VM using the specified profile and VM name.
- The VM is provisioned but not started immediately to allow for hardware configuration.
The so-salt-cloud script automates the provisioning and configuration of virtual machines in Security Onion's infrastructure. It orchestrates multiple components to ensure proper VM setup and security configuration. The script executes in the following phases:
3. **Hardware Configuration:**
1. Network Configuration Phase:
- Pre-deployment network setup using qcow2.modify_network_config
- Supports both DHCP and static IPv4 configurations
- Modifies the base QCOW2 image directly to ensure network settings persist
- Handles DNS and search domain configuration for proper name resolution
- Validates network parameters before modification
- Ensures network settings are in place before VM creation
- Modifies the hardware settings of the newly defined VM.
- Supports specifying multiple PCI devices for passthrough.
- Uses the `qcow2.modify_hardware_config` module via SaltStack to adjust CPU count, memory allocation, and PCI device passthrough.
- Starts the VM after hardware modifications.
2. VM Provisioning Phase:
- Leverages salt-cloud for consistent VM deployment
- Uses predefined profiles for standardized configurations
- Manages the VM lifecycle through libvirt
- Prevents automatic VM start to allow hardware configuration
- Validates profile and VM name format
- Extracts role information from VM name for security configuration
4. **Firewall Configuration:**
3. Hardware Configuration Phase:
- Configures VM hardware through qcow2.modify_hardware_config
- Manages CPU allocation based on host capabilities
- Handles memory assignment in MiB units
- Supports multiple PCI device passthrough for advanced networking
- Validates hardware parameters against host resources
- Controls VM startup sequence after configuration
- Monitors the output of `salt-cloud` to extract the VM's IP address.
- Calls the `so-firewall-minion` script to apply firewall rules based on the VM's role.
4. Security Integration Phase:
- Monitors salt-cloud output for VM IP address assignment
- Extracts role information from VM name
- Launches so-firewall-minion in a separate thread for non-blocking operation
- Configures role-based firewall rules automatically
- Ensures security policies are in place before VM is accessible
- Logs all security-related operations for audit purposes
**Exit Codes:**
The script implements extensive error handling and logging throughout each phase:
- Validates all input parameters before execution
- Provides detailed error messages for troubleshooting
- Logs operations to both file and console
- Handles process interruption gracefully
- Ensures atomic operations where possible
- Maintains audit trail of all configuration changes
- `0`: Success
Integration points:
- Works with Security Onion's salt-cloud provider
- Interfaces with qcow2 module for image and hardware management
- Coordinates with so-firewall-minion for security configuration
- Uses libvirt for VM management
- Leverages SaltStack for distributed execution
Exit Codes:
- 0: Success
- Non-zero: An error occurred during execution.
**Logging:**
Logging:
- Logs are written to `/opt/so/log/salt/so-salt-cloud.log`.
- Logs are written to /opt/so/log/salt/so-salt-cloud.log.
- Both file and console logging are enabled for real-time monitoring.
"""