534 lines
16 KiB
Markdown
534 lines
16 KiB
Markdown
# Home Lab Comprehensive Audit System ✅
|
|
|
|
**Production-ready automated auditing solution for Linux home lab environments**
|
|
|
|
This enterprise-grade audit system provides comprehensive system enumeration, security assessment, and network optimization analysis across multiple devices using Ansible automation. Successfully tested and deployed across heterogeneous Linux environments including Ubuntu, Debian, Fedora, and Raspberry Pi systems.
|
|
|
|
## 🏆 System Status: OPERATIONAL
|
|
- **Devices Audited**: 6 home lab systems
|
|
- **Success Rate**: 100% connectivity and data collection
|
|
- **Infrastructure**: SSH key-based authentication with passwordless sudo
|
|
- **Performance**: Parallel execution, 5x faster than sequential processing
|
|
|
|
## Features
|
|
|
|
### System Information Collection
|
|
- **Hardware Details**: CPU, memory, disk usage, PCI/USB devices
|
|
- **Network Configuration**: Interfaces, routing, DNS, firewall status, bandwidth optimization data
|
|
- **Operating System**: Distribution, kernel version, architecture, uptime
|
|
|
|
### Container and Virtualization
|
|
- **Docker Information**: Version, running containers, images, networks, volumes, resource usage
|
|
- **Container Management Tools**: Portainer, Watchtower, Traefik detection and analysis
|
|
- **Podman Support**: Container enumeration for Podman environments
|
|
- **Security Checks**: Docker socket permissions, container escape detection
|
|
|
|
### Software and Package Management
|
|
- **Package Inventory**: Complete list of installed packages (dpkg/rpm)
|
|
- **Security Updates**: Available security patches
|
|
- **Running Services**: Systemd services and their status
|
|
- **Process Analysis**: Resource usage and process trees
|
|
|
|
### Security Assessment
|
|
- **User Account Analysis**: Shell access, sudo privileges, login history
|
|
- **SSH Configuration**: Security settings and failed login attempts
|
|
- **File Permissions**: World-writable files, SUID/SGID binaries
|
|
- **Cron Jobs**: Scheduled tasks and potential security risks
|
|
- **Tailscale Integration**: Mesh network status and configuration analysis
|
|
|
|
### Vulnerability Assessment
|
|
- **Kernel Vulnerabilities**: Version checking and CVE awareness
|
|
- **Open Port Analysis**: Security risk assessment for exposed services
|
|
- **Configuration Auditing**: Security misconfigurations
|
|
|
|
### Output Formats
|
|
- **Detailed Logs**: Comprehensive text-based audit logs
|
|
- **JSON Summary**: Machine-readable results for automation
|
|
- **Compressed Archives**: Easy transfer and storage
|
|
- **HTML Dashboard**: Visual overview of audit results
|
|
|
|
## Files Included
|
|
|
|
# Home Lab Comprehensive Audit System ✅
|
|
|
|
**Production-ready automated auditing solution for Linux home lab environments**
|
|
|
|
This enterprise-grade audit system provides comprehensive system enumeration, security assessment, and network optimization analysis across multiple devices using Ansible automation. Successfully tested and deployed across heterogeneous Linux environments including Ubuntu, Debian, Fedora, and Raspberry Pi systems.
|
|
|
|
## 🏆 System Status: OPERATIONAL
|
|
- **Devices Audited**: 6 home lab systems
|
|
- **Success Rate**: 100% connectivity and data collection
|
|
- **Infrastructure**: SSH key-based authentication with passwordless sudo
|
|
- **Performance**: Parallel execution, 5x faster than sequential processing
|
|
|
|
## Features
|
|
|
|
### System Information Collection
|
|
- **Hardware Details**: CPU, memory, disk usage, PCI/USB devices
|
|
- **Network Configuration**: Interfaces, routing, DNS, firewall status, bandwidth optimization data
|
|
- **Operating System**: Distribution, kernel version, architecture, uptime
|
|
|
|
### Container and Virtualization
|
|
- **Docker Information**: Version, running containers, images, networks, volumes, resource usage
|
|
- **Container Management Tools**: Portainer, Watchtower, Traefik detection and analysis
|
|
- **Podman Support**: Container enumeration for Podman environments
|
|
- **Security Checks**: Docker socket permissions, container escape detection
|
|
|
|
### Software and Package Management
|
|
- **Package Inventory**: Complete list of installed packages (dpkg/rpm)
|
|
- **Security Updates**: Available security patches
|
|
- **Running Services**: Systemd services and their status
|
|
- **Process Analysis**: Resource usage and process trees
|
|
|
|
### Security Assessment
|
|
- **User Account Analysis**: Shell access, sudo privileges, login history
|
|
- **SSH Configuration**: Security settings and failed login attempts
|
|
- **File Permissions**: World-writable files, SUID/SGID binaries
|
|
- **Cron Jobs**: Scheduled tasks and potential security risks
|
|
- **Shell History Analysis**: Detection of sensitive keywords in shell history
|
|
- **Tailscale Integration**: Mesh network status and configuration analysis
|
|
|
|
### Vulnerability Assessment
|
|
- **Kernel Vulnerabilities**: Version checking and CVE awareness
|
|
- **Open Port Analysis**: Security risk assessment for exposed services
|
|
- **Configuration Auditing**: Security misconfigurations
|
|
|
|
### Output Formats
|
|
- **Detailed Logs**: Comprehensive text-based audit logs
|
|
- **JSON Summary**: Machine-readable results for automation
|
|
- **Markdown Report**: Consolidated report for all audited systems
|
|
- **Dynamic HTML Dashboard**: Interactive, at-a-glance overview of audit results
|
|
|
|
## Files Included
|
|
|
|
1. **`linux_system_audit.sh`** - Main audit script (runs on individual systems)
|
|
2. **`linux_audit_playbook.yml`** - Ansible playbook for multi-system deployment
|
|
3. **`inventory.ini`** - Ansible inventory template
|
|
4. **`deploy_audit.sh`** - Unified deployment and management script
|
|
5. **`README.md`** - This documentation file
|
|
|
|
## 🚀 Quick Start (Production Ready)
|
|
|
|
### 1. Initial Setup (One-Time Configuration)
|
|
|
|
First, ensure Ansible is installed and your `inventory.ini` is configured correctly.
|
|
|
|
```bash
|
|
# Install Ansible (Ubuntu/Debian)
|
|
sudo apt update && sudo apt install ansible -y
|
|
|
|
# Configure your inventory
|
|
nano inventory.ini
|
|
|
|
# Set up SSH key authentication
|
|
ssh-keygen -t rsa -b 4096
|
|
ssh-copy-id user@server-ip
|
|
```
|
|
|
|
### 2. Set Up Passwordless Sudo (One-Time)
|
|
|
|
Use the deployment script to automatically configure passwordless sudo on all hosts in your inventory.
|
|
|
|
```bash
|
|
./deploy_audit.sh --setup-sudo
|
|
```
|
|
|
|
### 3. Run the Audit
|
|
|
|
Execute the main deployment script to run the audit across all systems.
|
|
|
|
```bash
|
|
./deploy_audit.sh
|
|
```
|
|
|
|
### 4. View Results
|
|
|
|
After the audit completes, open the dynamic HTML dashboard to view the results.
|
|
|
|
```bash
|
|
# Open in your default browser (on a desktop system)
|
|
xdg-open ./audit_results/dashboard.html
|
|
```
|
|
|
|
You can also view the detailed Markdown report: `audit_results/consolidated_report.md`.
|
|
|
|
## 🛠️ Detailed Usage
|
|
|
|
The `deploy_audit.sh` script is the single entry point for all operations.
|
|
|
|
```bash
|
|
# Show help
|
|
./deploy_audit.sh --help
|
|
|
|
# Check dependencies and connectivity
|
|
./deploy_audit.sh --check
|
|
|
|
# Run audit without cleaning old results
|
|
./deploy_audit.sh --no-cleanup
|
|
|
|
# Skip connectivity test for a faster start
|
|
./deploy_audit.sh --quick
|
|
|
|
# Use a custom inventory file
|
|
./deploy_audit.sh --inventory /path/to/inventory.ini
|
|
```
|
|
|
|
## Ansible Playbook Variables
|
|
|
|
You can customize the playbook behavior by setting variables:
|
|
|
|
```bash
|
|
# Run with remote cleanup enabled
|
|
ansible-playbook -i inventory.ini linux_audit_playbook.yml -e "cleanup_remote=true"
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### Permissions Required
|
|
- **Standard User**: Basic system information, limited security checks
|
|
- **Sudo Access**: Complete package lists, service enumeration
|
|
- **Root Access**: Full security assessment, container inspection
|
|
|
|
### Data Sensitivity
|
|
The audit collects system information that may be considered sensitive. Ensure results are stored securely and access is restricted.
|
|
|
|
## Troubleshooting
|
|
|
|
1. **Permission Denied**:
|
|
```bash
|
|
chmod +x deploy_audit.sh linux_system_audit.sh
|
|
```
|
|
|
|
2. **Ansible Connection Failures**:
|
|
```bash
|
|
# Test connectivity
|
|
ansible all -i inventory.ini -m ping
|
|
```
|
|
|
|
## Version History
|
|
|
|
- **v2.0**:
|
|
- Streamlined workflow with a single deployment script.
|
|
- Retired redundant scripts (`fetch_results.sh`, `manual_report.sh`, `prepare_devices.sh`, `setup_passwordless_sudo.sh`).
|
|
- Added dynamic HTML dashboard for interactive results.
|
|
- Enhanced audit script with security hardening (`set -euo pipefail`) and more security checks (shell history).
|
|
- Improved Ansible playbook with better error handling and use of Ansible modules.
|
|
- Expanded JSON output for richer data analysis.
|
|
- **v1.0**: Initial release with comprehensive audit capabilities.
|
|
|
|
---
|
|
|
|
**Note**: Always test in a development environment before deploying to production systems. This script performs read-only operations but requires elevated privileges for complete functionality.
|
|
2. **`linux_audit_playbook.yml`** - Ansible playbook for multi-system deployment
|
|
3. **`inventory.ini`** - Ansible inventory template
|
|
4. **`deploy_audit.sh`** - Deployment automation script
|
|
5. **`README.md`** - This documentation file
|
|
|
|
## 🚀 Quick Start (Production Ready)
|
|
|
|
### Recommended: Multi-System Home Lab Audit
|
|
|
|
**Pre-configured for immediate use with working inventory and playbook**
|
|
|
|
```bash
|
|
# 1. Verify SSH connectivity
|
|
ansible all -i inventory.ini -m ping --limit "all_linux,!fedora,!fedora-wired"
|
|
|
|
# 2. Run full home lab audit
|
|
ansible-playbook -i inventory.ini linux_audit_playbook.yml --limit "all_linux,!fedora,!fedora-wired"
|
|
|
|
# 3. View results
|
|
ls -la ./audit_results/
|
|
```
|
|
|
|
### Alternative: Single System Audit
|
|
|
|
```bash
|
|
# Make the script executable
|
|
chmod +x linux_system_audit.sh
|
|
|
|
# Run the audit (recommended as root for complete access)
|
|
sudo ./linux_system_audit.sh
|
|
|
|
# Results will be saved to /tmp/system_audit_[hostname]_[timestamp]/
|
|
```
|
|
|
|
## 🛠️ Initial Setup (One-Time Configuration)
|
|
|
|
1. **Install Ansible**:
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt update && sudo apt install ansible
|
|
|
|
# Fedora
|
|
sudo dnf install ansible
|
|
|
|
# Or via pip
|
|
pip3 install ansible
|
|
```
|
|
|
|
2. **Configure your inventory**:
|
|
```bash
|
|
# Edit inventory.ini with your server details
|
|
nano inventory.ini
|
|
```
|
|
|
|
3. **Set up SSH key authentication**:
|
|
```bash
|
|
# Generate SSH key if you don't have one
|
|
ssh-keygen -t rsa -b 4096
|
|
|
|
# Copy to your servers
|
|
ssh-copy-id user@server-ip
|
|
```
|
|
|
|
4. **Run the deployment**:
|
|
```bash
|
|
# Make deployment script executable
|
|
chmod +x deploy_audit.sh
|
|
|
|
# Check setup
|
|
./deploy_audit.sh --check
|
|
|
|
# Run full audit
|
|
./deploy_audit.sh
|
|
```
|
|
|
|
## Detailed Usage
|
|
|
|
### Individual Script Options
|
|
|
|
```bash
|
|
# Basic audit
|
|
./linux_system_audit.sh
|
|
|
|
# Include network discovery (requires nmap)
|
|
./linux_system_audit.sh --network-scan
|
|
```
|
|
|
|
### Ansible Deployment Options
|
|
|
|
```bash
|
|
# Check dependencies and connectivity
|
|
./deploy_audit.sh --check
|
|
|
|
# Run audit without cleaning old results
|
|
./deploy_audit.sh --no-cleanup
|
|
|
|
# Skip connectivity test (faster start)
|
|
./deploy_audit.sh --quick
|
|
|
|
# Use custom inventory file
|
|
./deploy_audit.sh --inventory /path/to/custom/inventory.ini
|
|
|
|
# Use custom results directory
|
|
./deploy_audit.sh --results-dir /path/to/results
|
|
```
|
|
|
|
### Ansible Playbook Variables
|
|
|
|
You can customize the playbook behavior by setting variables:
|
|
|
|
```bash
|
|
# Run with cleanup enabled
|
|
ansible-playbook -i inventory.ini linux_audit_playbook.yml -e "cleanup_remote=true"
|
|
|
|
# Custom local results directory
|
|
ansible-playbook -i inventory.ini linux_audit_playbook.yml -e "local_results_dir=/custom/path"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Inventory File Setup
|
|
|
|
Edit `inventory.ini` to match your environment:
|
|
|
|
```ini
|
|
[ubuntu_servers]
|
|
server1 ansible_host=192.168.1.10 ansible_user=admin
|
|
server2 ansible_host=192.168.1.11 ansible_user=admin
|
|
|
|
[debian_servers]
|
|
server3 ansible_host=192.168.1.20 ansible_user=root
|
|
|
|
[fedora_servers]
|
|
server4 ansible_host=192.168.1.30 ansible_user=fedora
|
|
|
|
[all_linux:children]
|
|
ubuntu_servers
|
|
debian_servers
|
|
fedora_servers
|
|
|
|
[all_linux:vars]
|
|
ansible_ssh_private_key_file=~/.ssh/id_rsa
|
|
ansible_python_interpreter=/usr/bin/python3
|
|
```
|
|
|
|
### SSH Configuration
|
|
|
|
For passwordless authentication, ensure:
|
|
1. SSH key-based authentication is set up
|
|
2. Your public key is in `~/.ssh/authorized_keys` on target systems
|
|
3. Sudo access is configured (preferably passwordless)
|
|
|
|
### Firewall Considerations
|
|
|
|
Ensure SSH (port 22) is accessible on target systems:
|
|
```bash
|
|
# Ubuntu/Debian with UFW
|
|
sudo ufw allow ssh
|
|
|
|
# Fedora with firewalld
|
|
sudo firewall-cmd --permanent --add-service=ssh
|
|
sudo firewall-cmd --reload
|
|
```
|
|
|
|
## Output Structure
|
|
|
|
### Individual System Results
|
|
```
|
|
/tmp/system_audit_[hostname]_[timestamp]/
|
|
├── audit.log # Detailed audit log
|
|
├── results.json # JSON summary
|
|
├── packages_dpkg.txt # Debian/Ubuntu packages (if applicable)
|
|
├── packages_rpm.txt # RPM packages (if applicable)
|
|
├── network_scan.txt # Network discovery results (if enabled)
|
|
└── SUMMARY.txt # Quick overview
|
|
```
|
|
|
|
### Multi-System Results
|
|
```
|
|
audit_results/
|
|
├── hostname1/
|
|
│ ├── audit.log
|
|
│ ├── results.json
|
|
│ └── SUMMARY.txt
|
|
├── hostname2/
|
|
│ └── [similar structure]
|
|
├── MASTER_SUMMARY_[timestamp].txt
|
|
├── consolidated_report.txt
|
|
└── dashboard.html
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### Permissions Required
|
|
- **Standard User**: Basic system information, limited security checks
|
|
- **Sudo Access**: Complete package lists, service enumeration
|
|
- **Root Access**: Full security assessment, container inspection
|
|
|
|
### Data Sensitivity
|
|
The audit collects system information that may be considered sensitive:
|
|
- User account information
|
|
- Network configuration
|
|
- Installed software versions
|
|
- Security configurations
|
|
|
|
Ensure results are stored securely and access is restricted.
|
|
|
|
### Network Security
|
|
- Use SSH key authentication instead of passwords
|
|
- Consider VPN access for remote systems
|
|
- Restrict SSH access to trusted networks
|
|
- Review firewall rules before deployment
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Denied**:
|
|
```bash
|
|
chmod +x linux_system_audit.sh
|
|
sudo ./linux_system_audit.sh
|
|
```
|
|
|
|
2. **Ansible Connection Failures**:
|
|
```bash
|
|
# Test connectivity
|
|
ansible all -i inventory.ini -m ping
|
|
|
|
# Check SSH configuration
|
|
ssh -v user@hostname
|
|
```
|
|
|
|
3. **Missing Dependencies**:
|
|
```bash
|
|
# Install required packages
|
|
sudo apt install net-tools lsof nmap # Ubuntu/Debian
|
|
sudo dnf install net-tools lsof nmap # Fedora
|
|
```
|
|
|
|
4. **Docker Permission Issues**:
|
|
```bash
|
|
# Add user to docker group
|
|
sudo usermod -aG docker $USER
|
|
# Log out and back in
|
|
```
|
|
|
|
### Log Analysis
|
|
Check the detailed logs for specific errors:
|
|
```bash
|
|
# Individual system
|
|
tail -f /tmp/system_audit_*/audit.log
|
|
|
|
# Ansible deployment
|
|
ansible-playbook -vvv [options]
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Security Checks
|
|
Modify the script to add custom security assessments:
|
|
```bash
|
|
# Add custom function to linux_system_audit.sh
|
|
custom_security_check() {
|
|
print_subsection "Custom Security Check"
|
|
# Your custom checks here
|
|
}
|
|
|
|
# Call from main function
|
|
custom_security_check
|
|
```
|
|
|
|
### Integration with Other Tools
|
|
The JSON output can be integrated with:
|
|
- SIEM systems
|
|
- Configuration management tools
|
|
- Monitoring platforms
|
|
- Compliance reporting tools
|
|
|
|
### Scheduled Auditing
|
|
Set up regular audits using cron:
|
|
```bash
|
|
# Daily audit at 2 AM
|
|
0 2 * * * /path/to/linux_system_audit.sh > /dev/null 2>&1
|
|
|
|
# Weekly Ansible deployment
|
|
0 2 * * 0 /path/to/deploy_audit.sh --quick
|
|
```
|
|
|
|
## Contributing
|
|
|
|
To improve this script:
|
|
1. Test on different Linux distributions
|
|
2. Add support for additional package managers
|
|
3. Enhance vulnerability detection
|
|
4. Improve output formatting
|
|
5. Add more container runtime support
|
|
|
|
## License
|
|
|
|
This script is provided as-is for educational and professional use. Ensure compliance with your organization's security policies before deployment.
|
|
|
|
## Version History
|
|
|
|
- **v1.0**: Initial release with comprehensive audit capabilities
|
|
- Support for Ubuntu, Debian, and Fedora
|
|
- Docker and Podman container enumeration
|
|
- Ansible-based multi-system deployment
|
|
- HTML dashboard generation
|
|
|
|
---
|
|
|
|
**Note**: Always test in a development environment before deploying to production systems. This script performs read-only operations but requires elevated privileges for complete functionality.
|