-
Notifications
You must be signed in to change notification settings - Fork 2
Usage Guide
This comprehensive guide covers all aspects of using the Linux Security Audit Project, from basic commands to advanced workflows.
- Command-Line Syntax
- Module Selection
- Output Formats
- Remediation Options
- Advanced Usage Patterns
- Integration Scenarios
- Best Practices
python3 linux_security_audit.py [OPTIONS]| Option | Short | Description | Default |
|---|---|---|---|
--modules |
-m |
Comma-separated list of modules to run | All |
--output-format |
-f |
Output format (HTML/CSV/JSON/XML/Console) | HTML |
--output-path |
-o |
Path for output file | Auto-generated |
--list-modules |
List all available modules and exit | ||
--parallel |
Execute modules in parallel | ||
--workers |
Number of parallel workers | Auto | |
--profile |
Display performance statistics | ||
--log-level |
Set logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL) | INFO |
|
--log-file |
Custom log file path | Auto (logs/) |
|
--json-log |
Enable JSON-structured log output | ||
--verbose |
-v |
Enable verbose console output | |
--quiet |
-q |
Suppress non-essential console output | |
--remediate |
Interactively remediate failed checks | ||
--remediate-fail |
Remediate only FAIL status issues | ||
--remediate-warning |
Remediate only WARNING status issues | ||
--remediate-info |
Remediate only INFO status issues | ||
--auto-remediate |
Automatically remediate without prompting | ||
--remediation-file |
JSON file with specific issues to remediate |
Display help information:
python3 linux_security_audit.py --helpList available modules:
python3 linux_security_audit.py --list-modulesThe project includes 8 security framework modules:
| Module | Full Name | Check Count | Description |
|---|---|---|---|
Core |
Core Security Baseline | 153 | Industry best practices and OS-specific security guidance |
CIS |
CIS Benchmarks | 212 | Center for Internet Security benchmark compliance |
CISA |
CISA Guidance | 147 | Cybersecurity and Infrastructure Security Agency best practices |
ENISA |
ENISA Guidelines | 97 | European Union Agency for Cybersecurity standards |
ISO27001 |
ISO/IEC 27001 | 115 | International information security management standard |
NIST |
NIST Frameworks | 172 | NIST 800-53, CSF 2.0, and 800-171 controls |
NSA |
NSA Hardening | 144 | National Security Agency security configuration guides |
STIG |
DISA STIGs | 167 | Defense Information Systems Agency Security Technical Implementation Guides |
sudo python3 linux_security_audit.py
# or explicitly
sudo python3 linux_security_audit.py -m AllUse Case: Comprehensive security assessment
Time: 3-5 minutes
Checks: 1,100+ security checks
# Core baseline security
sudo python3 linux_security_audit.py -m Core
# CIS Benchmarks only
sudo python3 linux_security_audit.py -m CIS
# NIST frameworks only
sudo python3 linux_security_audit.py -m NISTUse Case: Focused assessment on specific framework
Time: 20-45 seconds per module
Checks: 97-212 per module
# Compliance-focused (CIS, NIST, ISO27001)
sudo python3 linux_security_audit.py -m CIS,NIST,ISO27001
# Government/Critical Infrastructure (STIG, NSA, CISA)
sudo python3 linux_security_audit.py -m STIG,NSA,CISA
# Baseline + Compliance (Core, CIS)
sudo python3 linux_security_audit.py -m Core,CISNote: Module names are case-insensitive. Use commas with no spaces.
sudo python3 linux_security_audit.py -m Core,CISStart with Core and CIS for fundamental security posture.
# Financial/General: ISO27001, NIST, CIS
sudo python3 linux_security_audit.py -m ISO27001,NIST,CIS
# Government/Defense: STIG, NSA, NIST
sudo python3 linux_security_audit.py -m STIG,NSA,NIST
# European Organizations: ISO27001, ENISA, CIS
sudo python3 linux_security_audit.py -m ISO27001,ENISA,CIS# Lightweight daily checks
sudo python3 linux_security_audit.py -m Core,CISA
# Weekly comprehensive
sudo python3 linux_security_audit.py -m AllInteractive browser-based report with rich features.
sudo python3 linux_security_audit.py -f HTML
# or
sudo python3 linux_security_audit.py # HTML is defaultFeatures:
- Interactive filtering by status and module
- Sortable columns (click headers)
- Full-text search across all fields
- Dark/Light theme toggle
- Export selected issues to JSON
- Inline remediation commands
- Statistics dashboard
File Naming: Security-Audit-Report-YYYYMMDD-HHMMSS.html
Use Cases:
- Manual security reviews
- Management reporting
- Compliance documentation
- Interactive issue exploration
Example with Custom Path:
sudo python3 linux_security_audit.py -f HTML -o /var/reports/audit-$(date +%Y%m%d).htmlComma-separated values for spreadsheet analysis.
sudo python3 linux_security_audit.py -f CSV -o security-audit.csvStructure:
Module,Category,Status,Message,Details,Remediation,Timestamp
Core,Password Policy,Pass,Password aging is configured,...
Core,SSH Security,Fail,Root login is enabled,...Use Cases:
- Excel/Google Sheets analysis
- Data trending and graphing
- Custom reporting workflows
- Historical comparisons
Example for Tracking:
# Monthly security trends
sudo python3 linux_security_audit.py -f CSV -o /var/reports/$(date +%Y%m)-audit.csvStructured data format for automation and APIs.
sudo python3 linux_security_audit.py -f JSON -o security-audit.jsonStructure:
{
"execution_info": {
"hostname": "server01",
"os_version": "Linux 5.15.0",
"scan_date": "2025-01-07 14:30:22",
"duration": "0:03:45",
"modules_run": ["Core", "CIS", "NIST"],
"total_checks": 512,
"pass_count": 387,
"fail_count": 89,
"warning_count": 32,
"info_count": 4,
"error_count": 0
},
"results": [
{
"module": "Core",
"category": "SSH Security",
"status": "Fail",
"message": "Root login is enabled",
"details": "SSH configuration allows direct root login",
"remediation": "sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config && systemctl restart sshd",
"timestamp": "2025-01-07 14:30:25"
}
]
}Use Cases:
- SIEM integration
- Automation workflows
- API consumption
- Selective remediation (via --remediation-file)
- Custom analysis scripts
Example for SIEM:
# Daily feed for SIEM
sudo python3 linux_security_audit.py -f JSON -o /var/siem/feeds/security-$(hostname)-$(date +%Y%m%d).jsonExtensible Markup Language for enterprise tools.
sudo python3 linux_security_audit.py -f XML -o security-audit.xmlStructure:
<?xml version="1.0" encoding="UTF-8"?>
<security_audit>
<execution_info>
<hostname>server01</hostname>
<os_version>Linux 5.15.0</os_version>
<scan_date>2025-01-07 14:30:22</scan_date>
<total_checks>512</total_checks>
<pass_count>387</pass_count>
<fail_count>89</fail_count>
</execution_info>
<results>
<result>
<module>Core</module>
<category>SSH Security</category>
<status>Fail</status>
<message>Root login is enabled</message>
</result>
</results>
</security_audit>Use Cases:
- Enterprise security tools (Splunk, QRadar)
- GRC platforms
- Configuration management systems
- Legacy system integration
Example for Enterprise SIEM:
sudo python3 linux_security_audit.py -f XML -o /mnt/nfs/siem-intake/$(hostname)-audit.xmlDirect terminal output without file creation.
sudo python3 linux_security_audit.py -f ConsoleFeatures:
- Color-coded status (Pass=Green, Fail=Red, Warning=Yellow)
- Real-time display as checks execute
- Suitable for quick checks and terminal-only environments
- Can be redirected to text files
Use Cases:
- Quick security checks
- SSH sessions without file transfer
- Logging to text files via redirection
- Automated scripts with parsed output
Example with Redirection:
# Save console output to text file
sudo python3 linux_security_audit.py -f Console > audit-$(date +%Y%m%d).txt 2>&1Remediation allows you to automatically or interactively apply security fixes based on audit findings. All remediation requires root privileges.
Important Safety Notes:
- Always review remediation commands before applying
- Test in non-production environments first
- Have backups of critical configurations
- Document changes made during remediation
- Consider maintenance windows for production systems
Review and approve each fix individually with detailed information.
sudo python3 linux_security_audit.py --remediateWorkflow:
- Script performs full audit
- Presents each remediable issue one at a time
- Shows: Module, Category, Status, Message, Details, Remediation Command
- Prompts:
[y]es, [n]o, [s]kip remaining, [q]uit - Executes approved remediations
- Displays results for each action
Example Interaction:
====================================================================================================
Issue 1 of 156
====================================================================================================
Module: Core
Category: SSH Security
Status: Fail
Message: Root login is enabled
Details: SSH configuration allows direct root login (security risk)
Remediation Command:
sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config && systemctl restart sshd
Apply this remediation? [y]es, [n]o, [s]kip remaining, [q]uit: y
[+] Executing remediation...
[+] Remediation successful
Continue? Press Enter...
Use Cases:
- First-time remediations
- Learning remediation commands
- Selective manual approval
- High-security environments requiring human review
Remediate only issues with specific status levels.
Critical security issues only:
sudo python3 linux_security_audit.py --remediate-failUse Cases:
- Focus on critical vulnerabilities
- Quick security wins
- Pre-production hardening
- Compliance requirement fixes
Best practice violations:
sudo python3 linux_security_audit.py --remediate-warningUse Cases:
- Post-critical remediation
- Configuration optimization
- Security posture improvement
- Non-urgent hardening
Informational recommendations:
sudo python3 linux_security_audit.py --remediate-infoUse Cases:
- Optional security enhancements
- Future-proofing configurations
- Documentation and awareness
Automatically apply fixes without prompting for each issue.
sudo python3 linux_security_audit.py --auto-remediateWorkflow:
- Script performs full audit
- Identifies all remediable issues
- Displays summary of actions to be taken
- Prompts for final confirmation
- Executes all remediations automatically
- Displays summary of results
Example:
====================================================================================================
AUTOMATED REMEDIATION SUMMARY
====================================================================================================
Total Issues: 156
FAIL: 89 issues
WARNING: 52 issues
INFO: 15 issues
This will automatically execute 156 remediation commands.
[!] WARNING: This is an automated process. Ensure you understand the impact.
[!] Consider backing up critical configurations before proceeding.
Proceed with automated remediation? [yes/no]: yes
[*] Executing remediations...
[+] 1/156: Core - SSH Security: Root login disabled
[+] 2/156: Core - Firewall: UFW enabled and configured
[+] 3/156: CIS - Password Policy: Password aging configured
...
[+] 156/156: NIST - Audit Logging: Auditd configuration updated
====================================================================================================
REMEDIATION COMPLETE
====================================================================================================
Successful: 145 (93%)
Failed: 11 (7%)
Duration: 0:02:15
====================================================================================================
Use Cases:
- Pre-configured environments
- Automated deployment pipelines
- Bulk system hardening
- Emergency security responses
Safety: Includes final confirmation prompt before executing.
Focus automated remediation on specific status levels:
# Auto-fix only critical FAIL issues
sudo python3 linux_security_audit.py --remediate-fail --auto-remediate
# Auto-fix only WARNING best practices
sudo python3 linux_security_audit.py --remediate-warning --auto-remediateUse Cases:
- Staged remediation approach (FAIL first, then WARNING, then INFO)
- Risk-based prioritization
- Minimizing system changes
The most precise remediation method - fix only specific issues selected from the HTML report.
Workflow:
- Run Initial Audit:
sudo python3 linux_security_audit.py-
Review HTML Report:
- Open the generated HTML report in browser
- Review each finding
- Use checkboxes to select specific issues to remediate
- Click "Export Selected" button
-
Save JSON File:
- Browser downloads file:
Selected-Report-YYYYMMDD-HHMMSS.json - Contains only your selected issues
- Browser downloads file:
-
Run Selective Remediation:
sudo python3 linux_security_audit.py --auto-remediate --remediation-file Selected-Report-20250107-143022.jsonExample JSON Structure (exported selection):
{
"execution_info": {
"hostname": "server01",
"scan_date": "2025-01-07 14:30:22"
},
"results": [
{
"module": "Core",
"category": "SSH Security",
"status": "Fail",
"message": "Root login is enabled",
"remediation": "sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config && systemctl restart sshd"
}
]
}Use Cases:
- Surgical precision in remediation
- Change management requirements
- Testing specific fixes
- Phased remediation approach
- Multiple administrators dividing work
Benefits:
- Complete control over what gets fixed
- Visual review of each issue before selection
- Documentation of intentional changes
- Repeatable remediation sets
Establish security baseline and track changes over time.
# Initial baseline
sudo python3 linux_security_audit.py -f JSON -o /var/security/baseline.json
# Weekly audits
sudo python3 linux_security_audit.py -f JSON -o /var/security/audit-$(date +%Y%m%d).json
# Compare results
# Use custom scripts or tools to diff JSON filesDocument security improvements.
# Before remediation
sudo python3 linux_security_audit.py -o audit-before.html
# Apply fixes
sudo python3 linux_security_audit.py --remediate-fail --auto-remediate
# After remediation
sudo python3 linux_security_audit.py -o audit-after.html
# Compare statistics in both reportsAudit multiple systems centrally.
# On each system (via SSH or automation)
ssh user@server1 "sudo python3 /opt/security-audit/linux_security_audit.py -f JSON -o /tmp/audit.json"
scp user@server1:/tmp/audit.json ./server1-audit-$(date +%Y%m%d).json
# Repeat for all systems, then consolidate resultsFocus on specific compliance requirements.
# PCI-DSS focus
sudo python3 linux_security_audit.py -m CIS,NIST,Core -o pci-audit-$(date +%Y%m%d).html
# HIPAA focus
sudo python3 linux_security_audit.py -m NIST,ISO27001,Core -o hipaa-audit-$(date +%Y%m%d).html
# FedRAMP focus
sudo python3 linux_security_audit.py -m NIST,STIG,NSA -o fedramp-audit-$(date +%Y%m%d).htmlSet up regular security monitoring.
Cron Example (/etc/cron.d/security-audit):
# Daily audit at 2 AM
0 2 * * * root /usr/bin/python3 /opt/security-audit/linux_security_audit.py -f JSON -o /var/log/security/audit-$(date +\%Y\%m\%d).json >> /var/log/security/audit.log 2>&1
# Weekly comprehensive HTML report on Sundays at 3 AM
0 3 * * 0 root /usr/bin/python3 /opt/security-audit/linux_security_audit.py -o /var/reports/weekly-audit-$(date +\%Y\%m\%d).html >> /var/log/security/audit.log 2>&1Systemd Timer Example:
Service file (/etc/systemd/system/security-audit.service):
[Unit]
Description=Linux Security Audit
After=network.target
[Service]
Type=oneshot
ExecStart=/usr/bin/python3 /opt/security-audit/linux_security_audit.py -f JSON -o /var/log/security/audit-$(date +%%Y%%m%%d).json
StandardOutput=journal
StandardError=journalTimer file (/etc/systemd/system/security-audit.timer):
[Unit]
Description=Daily Security Audit Timer
Requires=security-audit.service
[Timer]
OnCalendar=daily
OnCalendar=02:00
Persistent=true
[Install]
WantedBy=timers.targetEnable timer:
sudo systemctl daemon-reload
sudo systemctl enable security-audit.timer
sudo systemctl start security-audit.timerIntegrate into CI/CD pipelines.
# In deployment script
#!/bin/bash
# Deploy application
deploy_application.sh
# Run security audit
sudo python3 /opt/security-audit/linux_security_audit.py -m Core,CIS -f JSON -o /tmp/post-deploy-audit.json
# Parse results
FAIL_COUNT=$(jq '.execution_info.fail_count' /tmp/post-deploy-audit.json)
# Fail pipeline if critical issues found
if [ "$FAIL_COUNT" -gt 10 ]; then
echo "Security audit failed with $FAIL_COUNT critical issues"
exit 1
fi
echo "Security audit passed with $FAIL_COUNT issues (acceptable threshold)"Rapid assessment during security incidents.
# Quick critical systems check
sudo python3 linux_security_audit.py -m Core,NSA,CISA -f Console | tee emergency-audit-$(date +%Y%m%d-%H%M%S).txt
# Immediate remediation of critical issues
sudo python3 linux_security_audit.py -m Core,NSA --remediate-fail --auto-remediate# Generate XML for SIEM ingestion
sudo python3 linux_security_audit.py -f XML -o /var/siem-feeds/security-audit-$(hostname)-$(date +%Y%m%d).xml
# Or JSON for modern SIEMs
sudo python3 linux_security_audit.py -f JSON -o /var/siem-feeds/security-audit-$(hostname)-$(date +%Y%m%d).jsonAnsible Playbook Example:
---
- name: Run Linux Security Audit
hosts: all
become: yes
tasks:
- name: Copy audit script
copy:
src: /path/to/linux_security_audit.py
dest: /tmp/linux_security_audit.py
mode: '0755'
- name: Copy security modules
copy:
src: "{{ item }}"
dest: /tmp/
with_fileglob:
- /path/to/module_*.py
- name: Run security audit
command: python3 /tmp/linux_security_audit.py -f JSON -o /tmp/audit.json
register: audit_result
- name: Fetch audit results
fetch:
src: /tmp/audit.json
dest: ./audit-results/{{ inventory_hostname }}-audit.json
flat: yes# Generate audit and parse failures
sudo python3 linux_security_audit.py -f JSON -o /tmp/audit.json
# Create tickets for each FAIL status issue
python3 - <<EOF
import json
import requests
with open('/tmp/audit.json') as f:
data = json.load(f)
for result in data['results']:
if result['status'] == 'Fail':
ticket = {
'title': f"{result['module']} - {result['category']}: {result['message']}",
'description': result['details'],
'priority': 'High',
'remediation': result['remediation']
}
# Post to ticketing API
requests.post('https://ticketing.example.com/api/tickets', json=ticket)
EOF# Generate compliance-focused reports
sudo python3 linux_security_audit.py -m CIS,NIST,ISO27001 -f CSV -o compliance-$(date +%Y%m%d).csv
# Upload to GRC platform via API or file transfer
curl -X POST -F "file=@compliance-$(date +%Y%m%d).csv" https://grc-platform.example.com/api/upload- Test in Non-Production First: Always test on development/staging systems before production
- Schedule Appropriately: Run during maintenance windows or low-usage periods
- Communicate: Inform relevant teams before running audits
- Backup Configurations: Back up critical config files before remediation
- Review Modules: Select appropriate modules for your environment and compliance needs
- Monitor Progress: Watch for errors or unexpected behavior
- Review Results: Don't blindly accept all findings - validate in your context
- Document Changes: Keep logs of all remediations applied
- Test After Remediation: Verify system functionality after applying fixes
- Staged Approach: Fix critical issues first, then warnings, then informational
- Consistent Naming: Use consistent filename conventions
- Centralized Storage: Store reports in a central, backed-up location
- Access Controls: Protect reports (contain security information)
- Retention Policy: Define how long to keep audit reports
- Regular Reviews: Schedule periodic review of audit trends
- Read First: Always read remediation commands before executing
- Understand Impact: Know what the remediation will change
- Test Individually: Test critical remediations one at a time
- Have Rollback Plan: Know how to undo changes if needed
- Document Everything: Keep detailed logs of what was changed and why
- Trend Analysis: Track metrics over time to measure improvement
- Adjust Baselines: Update expectations as security posture improves
- Learn Patterns: Understand recurring issues and address root causes
- Automate Where Safe: Automate known-safe remediations over time
- Share Knowledge: Document lessons learned and share with team
| Scenario | Command | Frequency | Output |
|---|---|---|---|
| Initial Security Baseline | sudo python3 linux_security_audit.py -m Core,CIS |
Once | HTML |
| Daily Monitoring | sudo python3 linux_security_audit.py -f JSON |
Daily (cron) | JSON |
| Weekly Compliance | sudo python3 linux_security_audit.py -m CIS,NIST,ISO27001 |
Weekly | HTML |
| Pre-Deployment Check | sudo python3 linux_security_audit.py -m Core,NSA |
Per-deployment | JSON/Console |
| Emergency Assessment | sudo python3 linux_security_audit.py -m Core,NSA -f Console |
As-needed | Console |
| SIEM Feed | sudo python3 linux_security_audit.py -f XML |
Daily | XML |
| Change Management |
sudo python3 linux_security_audit.py -o before.html + remediate + -o after.html
|
Per-change | HTML |
- Detailed Module Information: Module Documentation
- Output Format Details: Output Reference
- Framework Standards: Framework Reference
- Common Issues: Troubleshooting Guide
- Questions: FAQ
The v3.0 release adds nine new CLI flags that activate enhanced pipeline phases without changing existing behaviour. All v3 flags are optional; running without them produces the same output as v2.0.
Compare the current audit against a previously saved baseline JSON file. Produces a drift report classifying each finding as new failure, resolved, regression, improvement, etc.
# Generate the baseline
sudo python3 linux_security_audit.py -f JSON -o baseline-202604.json
# Later, compare
sudo python3 linux_security_audit.py --baseline baseline-202604.jsonGenerate a bash rollback script during remediation. Captures pre-modification state for sysctl, file content/permissions, services, and kernel modules. Run the generated script to undo all changes.
sudo python3 linux_security_audit.py --remediate-fail --rollback-path /var/lib/audit/rollback.shApply a named remediation bundle. Bundles group related fixes so you can apply a coherent set with one command. Run --list-bundles to see all available bundles.
sudo python3 linux_security_audit.py --remediation-bundle HardenSSH --auto-remediateSet the asset criticality for risk priority scoring. Higher values mean a finding on this system contributes more to the priority score. Default is 5.
# High-value production system
sudo python3 linux_security_audit.py --asset-criticality 9 --show-risk-priority
# Isolated build agent
sudo python3 linux_security_audit.py --asset-criticality 3 --show-risk-priorityDisplay risk priority scores (1-100) for each Fail/Warning finding, ranked highest first. Combines severity, exploitability, exposure, and asset criticality.
Display cross-framework control correlations for each result. Shows how a single finding maps to identifiers in CIS, NIST, STIG, ISO 27001, NSA, CISA, ENISA, PCI DSS, HIPAA, etc.
Run strict result validation. Reports any defects in module output (missing severity, malformed cross-references, control characters in messages).
List all available remediation bundles with their descriptions, included topics, prerequisites, and impact profiles. Exits without running an audit.
python3 linux_security_audit.py --list-bundlesSet the compliance score pass/fail threshold. Default is 70.0. Three scoring methods are computed: simple (pass percentage), weighted (severity-weighted), and severity-adjusted (weight × status credit).
sudo python3 linux_security_audit.py --threshold 85Linux Security Audit Project · Version 2.0 · MIT License
Repository · Releases · Issues · Pull Requests
Changelog · Contributing · Security Policy · License
Frameworks: Core · CIS · CISA · ENISA · ISO 27001 · NIST · NSA · STIG
Coverage: 8 Modules · 1,207 Automated Security Checks · 5 Native Output Formats · Zero External Dependencies
This documentation reflects Linux Security Audit Project v2.0 released 2026-03-02. For older versions, see the release tags.
Version 2.0 · 8 modules · 1,207 checks
Frameworks Covered
Core · CIS · CISA · ENISA · ISO 27001 · NIST · NSA · STIG
Output Formats
HTML · JSON · CSV · XML · Console
Status Values
Pass · Fail · Warning · Info · Error
Severity Levels
Critical · High · Medium · Low · Informational