Troubleshooting Guide

Troubleshooting Guide

This guide provides solutions to common issues encountered when using the Linux Security Audit Project, including error messages, unexpected behavior, and system-specific problems.

v3.7 Distribution Profiles Issues

Profile name rejected with [!] Invalid --profile value

The profile name validation regex is ^[a-z][a-z0-9_-]{0,30}$ and is intentionally strict. Common rejection causes:

• Uppercase letters - use rhel9 not RHEL9
• Special characters - ;, &, $, `, newlines, slashes are all rejected
• Leading hyphen or digit - must start with a lowercase letter
• Length over 31 chars - bounded to prevent resource exhaustion

Run --list-profiles to see all valid profile names.

Profile 'X' excluded all selected modules. Nothing to run.

This means the profile's exclude_modules list filtered out every module you selected. Either remove the --profile flag or pick different modules with --modules.

Profile applied but no categories filtered

This is normal for the generic profile (no exclusions) and for systems that don't have the excluded categories present anyway. Profiles are subtractive, so systems lacking the excluded categories see no change.

v3.6 Helper Caching Issues

Modules show stale results across multiple runs

The v3.6 cache lifetime is per-process. If you're calling main() repeatedly in a long-running supervisor, call shared_components.module_helpers.clear_caches() between runs to invalidate.

For one-shot CLI invocations (the typical case), the cache is automatically cleared because the process exits after each audit.

---

Table of Contents

• Quick Diagnostic Steps
• Common Issues
• Permission and Privilege Issues
• Module-Specific Issues
• Output and Reporting Issues
• Remediation Issues
• Performance Issues
• OS-Specific Issues
• Getting Additional Help

Quick Diagnostic Steps

When encountering issues, start with these basic diagnostic steps:

1. Verify Prerequisites

# Check Python version (requires 3.7+)
python3 --version

# Expected: Python 3.7.0 or higher

2. Verify File Integrity

# Check all module files exist
ls -l modules/module_*.py shared_components/audit_common.py

# Expected: 16 module files in modules/ and audit_common.py in shared_components/

3. Test Basic Execution

# List available modules (no privileges required)
python3 linux_security_audit.py --list-modules

# Run simple test
python3 linux_security_audit.py -m Core -f Console

4. Check for Error Messages

# Run with full error output
python3 linux_security_audit.py -m Core --verbose --log-level DEBUG 2>&1 | tee debug.log

# Check logs/ directory for structured log file
# Review debug.log and log file for specific errors

Common Issues

Issue: "No module named 'linux_security_audit'"

Symptom:

ImportError: No module named 'linux_security_audit'
ModuleNotFoundError: No module named 'linux_security_audit'

Cause: Module files trying to import from main script but can't find it.

Solutions:

1. Ensure all files in same directory:

ls -l linux_security_audit.py module_*.py
# All files should be in same directory

2. Run from project directory:

cd /path/to/Linux-Security-Audit-Project
python3 linux_security_audit.py

3. Don't install as package: This is not a pip-installable package, run directly from source.

Issue: "Permission denied" Errors

Symptom:

[Error] Permission denied accessing /etc/shadow
[Error] Permission denied reading /etc/ssh/sshd_config
Multiple checks showing "Error" status

Cause: Running without sufficient privileges.

Solutions:

Option 1: Run with sudo (Recommended):

sudo python3 linux_security_audit.py

Option 2: Accept limited results:

# Run without sudo - some checks will be limited
python3 linux_security_audit.py

The tool will indicate: [!] Running as: NON-ROOT (Limited)

What to expect:

• File permission checks may fail
• Service status checks may be limited
• Some security checks require root access
• Remediation is not available without root

Issue: "No modules found"

Symptom:

[!] No modules found. Cannot proceed.

Cause: Module files are missing or not in the expected location.

Solutions:

1. Verify module files exist:

ls module_*.py

Should show:

module_cis.py
module_cisa.py
module_core.py
module_enisa.py
module_iso27001.py
module_nist.py
module_nsa.py
module_stig.py

2. Re-download missing modules:

# Clone repository again
git clone https://github.com/Sandler73/Linux-Security-Audit-Project.git

3. Check file permissions:

# Modules must be readable
chmod 644 module_*.py

Issue: Module execution takes too long

Symptom:

• Script runs for 10+ minutes
• Appears to hang on specific module
• High CPU usage

Causes and Solutions:

Cause 1: Running all modules on first execution

# Solution: Run fewer modules
python3 linux_security_audit.py -m Core,CIS

Cause 2: System has many users/files

# Solution: Expected on large systems
# Wait for completion (typically 5-10 minutes max)

Cause 3: Network timeouts

# Solution: System may be trying to resolve hostnames
# Check /etc/hosts and DNS configuration

Monitoring progress:

# Run with visible output
python3 linux_security_audit.py -f Console

Issue: HTML report doesn't open automatically

Symptom:

[+] Report generated successfully
[!] Browser did not open automatically

Causes and Solutions:

Cause 1: No graphical environment

# Solution: Manually copy report to local system
scp user@server:/path/to/report.html .
# Open locally in browser

Cause 2: No default browser configured

# Solution: Open manually
firefox Security-Audit-Report-*.html
# or
google-chrome Security-Audit-Report-*.html

Cause 3: Running via SSH

# Solution: Use X11 forwarding
ssh -X user@server
python3 linux_security_audit.py

# Or copy report locally (preferred)

Issue: "Command not found" errors during checks

Symptom:

[Error] Command 'auditctl' not found
[Error] Command 'sestatus' not found

Cause: Required security tools not installed.

Solutions:

For auditd:

# Debian/Ubuntu
sudo apt-get install auditd

# RHEL/CentOS/Fedora
sudo yum install audit

For SELinux tools:

# RHEL/CentOS/Fedora
sudo yum install policycoreutils

# Ubuntu (AppArmor is default)
sudo apt-get install apparmor-utils

Note: These are expected on systems without these tools installed. The tool will mark these as "Error" status which is informational.

Permission and Privilege Issues

Issue: sudo password prompts during execution

Symptom:

[sudo] password for user:
[sudo] password for user:
[sudo] password for user:

Cause: Running with sudo python3 and checks are calling sudo again.

Solution:

Remove sudo from remediation commands when already running as root:

# Run as root directly
sudo python3 linux_security_audit.py

# Remediation commands will work without nested sudo

Issue: "Operation not permitted" even with sudo

Symptom:

[Error] Operation not permitted
[Error] Cannot modify /sys/...

Cause: SELinux, AppArmor, or kernel restrictions.

Solutions:

Check SELinux status:

sestatus

# If enforcing and causing issues:
sudo setenforce 0  # Temporary

Check AppArmor status:

sudo aa-status

# If AppArmor is blocking:
sudo aa-complain /path/to/script

Some operations require reboot: Kernel parameter changes often require reboot to take effect.

Issue: File permissions reset after reboot

Symptom:

• Fixed permissions during remediation
• After reboot, permissions revert

Cause: System has file permission management (systemd-tmpfiles, configuration management).

Solution:

Make changes persistent:

# For systemd-managed files
sudo systemctl edit service-name

# For configuration management
# Update Ansible/Puppet/Chef configurations

Module-Specific Issues

Core Module Issues

Issue: Package manager detection fails

Symptom:

[Error] Core - Package Management: Unknown package manager

Solution:

# Verify package manager
which apt yum dnf zypper pacman

# If multiple package managers exist, Core module uses first found

Issue: OS detection incorrect

Symptom:

[Warning] OS family detection uncertain

Solution:

# Check /etc/os-release
cat /etc/os-release

# Manually verify distribution
lsb_release -a

CIS Module Issues

Issue: Many CIS checks fail on minimal installation

Symptom:

CIS module shows 100+ failures
Most failures related to "not installed"

Cause: CIS Benchmarks assume certain packages/configurations.

Solution:

This is expected behavior:

• Minimal installations lack many CIS-recommended components
• Review failures and install required packages
• Prioritize CAT I (critical) findings

Issue: Partition checks fail

Symptom:

[Fail] CIS - Filesystem: Separate /tmp partition not found
[Fail] CIS - Filesystem: Separate /var partition not found

Cause: System doesn't have separate partitions.

Solution:

Option 1: Accept the finding (common on cloud/virtual systems)

Option 2: Implement during next OS installation

Option 3: Use bind mounts (partial mitigation):

# Create separate filesystem for /tmp
sudo mkdir /tmp_new
sudo mount -t tmpfs -o size=1G,nodev,nosuid,noexec tmpfs /tmp_new

NIST/STIG/NSA Module Issues

Issue: SELinux checks fail on non-RHEL systems

Symptom:

[Error] NSA - SELinux: SELinux not found
[Error] STIG - MAC: Mandatory Access Control not enabled

Cause: SELinux is RHEL-family specific.

Solution:

For Debian/Ubuntu: Use AppArmor checks instead

# Check AppArmor status
sudo aa-status

# These systems use AppArmor, not SELinux
# This is expected and correct

Issue: FIPS mode checks fail

Symptom:

[Fail] NSA - Cryptography: FIPS mode not enabled

Cause: FIPS mode not enabled (expected for non-government systems).

Solution:

For government/DoD systems: Enable FIPS mode:

# RHEL/CentOS
sudo fips-mode-setup --enable
sudo reboot

For commercial systems: FIPS mode is not required, finding can be ignored.

CISA Module Issues

Issue: KEV catalog checks report many vulnerabilities

Symptom:

[Fail] CISA - Vulnerability Management: 50+ KEV vulnerabilities found

Cause: System has unpatched known exploited vulnerabilities.

Solution:

Critical - Patch immediately:

# Update system
sudo apt update && sudo apt upgrade -y  # Debian/Ubuntu
sudo yum update -y                       # RHEL/CentOS

This is a serious security issue - KEV catalog contains actively exploited vulnerabilities.

Output and Reporting Issues

Issue: HTML report is blank or malformed

Symptom:

• HTML file opens but shows no content
• Report displays incorrectly
• JavaScript errors in browser console

Causes and Solutions:

Cause 1: Incomplete file write

# Check file size
ls -lh Security-Audit-Report-*.html

# Should be > 100KB for full report
# If < 10KB, file write was interrupted

Solution: Re-run audit

sudo python3 linux_security_audit.py

Cause 2: Browser compatibility

# Try different browser
firefox report.html
google-chrome report.html

Cause 3: File corruption

# Check file integrity
file Security-Audit-Report-*.html

# Should show: "HTML document, UTF-8 Unicode text"

Issue: CSV file has formatting issues in Excel

Symptom:

• Commas in wrong places
• Data in wrong columns
• Special characters display incorrectly

Solutions:

Excel import wizard:

1. Open Excel
2. File -> Import -> CSV
3. Select UTF-8 encoding
4. Choose comma as delimiter
5. Import

Use LibreOffice Calc:

# Better CSV handling than Excel
libreoffice --calc report.csv

Issue: JSON file won't parse

Symptom:

json.decoder.JSONDecodeError: Expecting value: line 1 column 1

Solutions:

Validate JSON:

# Check if valid JSON
python3 -m json.tool report.json

# Or use jq
jq . report.json

Check file encoding:

file report.json
# Should show: "JSON data, UTF-8 Unicode text"

Re-generate:

sudo python3 linux_security_audit.py -f JSON -o new-report.json

Issue: XML file validation errors

Symptom:

• XML parser rejects file
• SIEM won't ingest XML

Solutions:

Validate XML:

xmllint report.xml

# Or with Python
python3 -c "import xml.etree.ElementTree as ET; ET.parse('report.xml')"

Check for special characters:

# XML requires entity escaping
# The tool should handle this, but verify
grep -E '[<>&"]' report.xml

Remediation Issues

Issue: Remediation fails with "command not found"

Symptom:

[!] Remediation failed: command not found: systemctl

Cause: System doesn't have the required command.

Solutions:

Check init system:

# For systemd systems
which systemctl

# For SysVinit systems
which service

Modify remediation command:

# SysVinit alternative
sudo service sshd restart

Issue: Remediation breaks service

Symptom:

• Service won't start after remediation
• System becomes unreachable
• SSH connection drops

Prevention:

Always test in non-production first:

# Test on development system
sudo python3 linux_security_audit.py --remediate

Review remediation commands before executing:

# Run audit first
sudo python3 linux_security_audit.py

# Review HTML report
# Manually apply critical changes one at a time

Backup configurations:

# Before remediation
sudo cp -r /etc/ssh /etc/ssh.backup
sudo cp /etc/sysctl.conf /etc/sysctl.conf.backup

Recovery:

If SSH is still accessible:

# Restore backup
sudo cp -r /etc/ssh.backup /etc/ssh
sudo systemctl restart sshd

If SSH is broken:

# Connect via console (physical or virtual)
# Restore backup configurations
# Restart services

Issue: Remediation requires reboot

Symptom:

[!] Some changes require system reboot to take effect

Expected for:

• Kernel parameter changes (sysctl)
• SELinux mode changes
• Some PAM configuration changes

Solution:

Schedule reboot:

# Check what requires reboot
needs-restarting -r  # RHEL/CentOS
cat /var/run/reboot-required  # Ubuntu/Debian

# Schedule reboot
sudo shutdown -r +30 "System reboot for security updates"

Issue: Auto-remediation stops unexpectedly

Symptom:

[*] Executing remediation 45/156...
[!] Remediation stopped

Causes:

Cause 1: Command timeout

• Long-running commands may timeout
• Default timeout: 30 seconds

Cause 2: Fatal error

• One remediation command failed critically
• Script stopped to prevent further issues

Solution:

Review last successful remediation:

# Check which remediation was last
# Review its effect
# Manually complete remaining remediations

Performance Issues

Issue: High memory usage during execution

Symptom:

# Memory usage > 500MB
top -p $(pgrep -f linux_security_audit)

Causes and Solutions:

Cause 1: Large system (1000+ users, many files)

• Expected behavior
• Memory usage proportional to system size

Cause 2: All modules running simultaneously

# Solution: Run modules individually
python3 linux_security_audit.py -m Core
python3 linux_security_audit.py -m CIS
# etc.

Cause 3: Very large output files

# Solution: Use Console format for testing
python3 linux_security_audit.py -f Console

Issue: Script hangs on specific check

Symptom:

• Script stops progressing
• Last message shows specific module/check
• Ctrl+C doesn't work immediately

Solution:

Identify hanging check:

# Run in verbose mode (if available)
# Or trace with strace
sudo strace -f -t python3 linux_security_audit.py

Force timeout:

# Kill after 10 minutes
timeout 600 python3 linux_security_audit.py

Report issue:

• Note which check hangs
• Report on GitHub Issues
• Include OS version and system details

Issue: Slow filesystem checks

Symptom:

[*] Executing module: CIS
    Running filesystem checks... (5+ minutes)

Causes:

Cause 1: Large filesystem

• Searching for SUID/SGID files
• Searching for world-writable files
• Expected on systems with millions of files

Cause 2: Network filesystems

• NFS mounts slow down checks
• SMB shares cause timeouts

Solutions:

Exclude network mounts:

# Temporary unmount if possible
# Or accept longer execution time

Skip filesystem-intensive modules:

# Run without CIS module on large systems
python3 linux_security_audit.py -m Core,NIST,CISA

OS-Specific Issues

Ubuntu/Debian Issues

Issue: AppArmor checks fail

Symptom:

[Error] AppArmor profiles not loaded

Solution:

# Check AppArmor status
sudo aa-status

# If disabled
sudo systemctl enable apparmor
sudo systemctl start apparmor

Issue: unattended-upgrades not configured

Symptom:

[Fail] Automatic security updates not configured

Solution:

sudo apt install unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

RHEL/CentOS/Fedora Issues

Issue: SELinux checks fail unexpectedly

Symptom:

[Error] Cannot determine SELinux status

Solution:

# Check SELinux installation
rpm -q libselinux

# Install if missing
sudo yum install libselinux-utils

Issue: yum/dnf version confusion

Symptom:

[Error] Package manager command failed

Solution:

# RHEL 7/CentOS 7: Use yum
sudo yum update

# RHEL 8+/CentOS 8+/Fedora: Use dnf
sudo dnf update

# Script should auto-detect, but verify

Cloud/Virtual Machine Issues

Issue: Clock synchronization checks fail

Symptom:

[Fail] Time synchronization not configured

Cause: Cloud VMs often use different time sync.

Solution:

AWS EC2:

# Uses Amazon Time Sync Service
chronyc sources
# Should show: 169.254.169.123

Azure:

# Uses Azure Time Sync
chronyc sources

Solution: These are correct configurations, findings can be noted but not necessarily failures.

Minimal/Container Issues

Issue: Many services "not installed"

Symptom:

[Error] auditd not installed
[Error] AIDE not installed
[Error] rsyslog not installed

Cause: Minimal OS or container installation.

Solution:

For containers: This is expected and correct

• Containers should be minimal
• Install only required security tools
• Use host-level security monitoring

For minimal OS: Install required packages:

# Security essentials
sudo apt install auditd aide rsyslog fail2ban

# Or equivalent for your distribution

Getting Additional Help

Collecting Diagnostic Information

When reporting issues, include:

1. System Information:

# OS version
cat /etc/os-release
uname -a

# Python version
python3 --version

# Privileges
id

2. Error Output:

# Full error output
python3 linux_security_audit.py -m Core 2>&1 | tee error.log

3. Module List:

python3 linux_security_audit.py --list-modules

4. File Verification:

ls -lh linux_security_audit.py module_*.py

Debug Mode (Future Enhancement)

# If debug mode is implemented
export DEBUG=1
python3 linux_security_audit.py

Common Error Messages Reference

Error Message	Likely Cause	Solution
Permission denied	Not running as root	Use sudo
Module not found	Files not in same directory	Verify file locations
Command not found: X	Security tool not installed	Install package
No modules found	Module files missing	Re-download project
Timeout	Long-running command	Wait or investigate hanging process
Invalid JSON	Corrupted output file	Re-run audit
Cannot determine OS	Unusual distribution	Report as issue

Support Channels

GitHub Issues:

• Bug reports: https://github.com/Sandler73/Linux-Security-Audit-Project/issues
• Feature requests: Use "enhancement" label
• Questions: Use "question" label

Before Opening Issue:

1. Search existing issues
2. Try troubleshooting steps in this guide
3. Collect diagnostic information
4. Provide clear reproduction steps

Issue Template:

**Description**
Clear description of the issue

**Steps to Reproduce**
1. Step one
2. Step two
3. ...

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- OS: [e.g., Ubuntu 22.04]
- Python Version: [e.g., 3.10.12]
- Running as: [root/non-root]
- Module: [e.g., Core, CIS]

**Error Output**

Paste error output here

**Additional Context**
Any other relevant information

Quick Reference

Most Common Fixes:

1. Permission issues: Run with sudo
2. Module not found: Ensure all files in same directory
3. Slow execution: Run fewer modules at once
4. Service broken after remediation: Restore from backup
5. HTML report doesn't open: Manually open or copy to local system

When to Report Bug:

• Script crashes unexpectedly
• Incorrect security assessment
• Remediation command is wrong or dangerous
• Documentation is unclear or incorrect

When Not to Report:

• "Error" status for uninstalled packages (expected)
• "Fail" status for unconfigured security (that's the point)
• Slow execution on large systems (expected)
• Need sudo privileges (by design)

Additional Resources

• FAQ: Common questions
• Usage Guide: Proper usage instructions
• Module Documentation: Understanding check results
• Development Guide: For developers debugging issues

---

<- Back to Development Guide | Home | Next: FAQ ->