Usage Guide

This comprehensive guide covers all aspects of using the Linux Security Audit Project, from basic commands to advanced workflows.

Command-Line Syntax

Basic Syntax

python3 linux_security_audit.py [OPTIONS]

All Available 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
`--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

Help and Information

Display help information:

python3 linux_security_audit.py --help

List available modules:

python3 linux_security_audit.py --list-modules

Module Selection

Available Modules

The project includes 8 security framework modules:

Module	Full Name	Check Count	Description
`Core`	Core Security Baseline	150+	Industry best practices and OS-specific security guidance
`CIS`	CIS Benchmarks	200+	Center for Internet Security benchmark compliance
`CISA`	CISA Guidance	140+	Cybersecurity and Infrastructure Security Agency best practices
`ENISA`	ENISA Guidelines	135+	European Union Agency for Cybersecurity standards
`ISO27001`	ISO/IEC 27001	145+	International information security management standard
`NIST`	NIST Frameworks	160+	NIST 800-53, CSF 2.0, and 800-171 controls
`NSA`	NSA Hardening	155+	National Security Agency security configuration guides
`STIG`	DISA STIGs	180+	Defense Information Systems Agency Security Technical Implementation Guides

Module Selection Examples

Run All Modules (Default)

sudo python3 linux_security_audit.py
# or explicitly
sudo python3 linux_security_audit.py -m All

Use Case: Comprehensive security assessment
Time: 3-5 minutes
Checks: 1,100+ security checks

Run Single Module

# 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 NIST

Use Case: Focused assessment on specific framework
Time: 20-45 seconds per module
Checks: 130-200 per module

Run Multiple Specific Modules

# 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,CIS

Note: Module names are case-insensitive. Use commas with no spaces.

Module Selection Strategy

For Initial Assessment

sudo python3 linux_security_audit.py -m Core,CIS

Start with Core and CIS for fundamental security posture.

For Compliance Audits

# 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

For Continuous Monitoring

# Lightweight daily checks
sudo python3 linux_security_audit.py -m Core,CISA

# Weekly comprehensive
sudo python3 linux_security_audit.py -m All

Output Formats

HTML (Default)

Interactive browser-based report with rich features.

sudo python3 linux_security_audit.py -f HTML
# or
sudo python3 linux_security_audit.py  # HTML is default

Features:

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).html

CSV

Comma-separated values for spreadsheet analysis.

sudo python3 linux_security_audit.py -f CSV -o security-audit.csv

Structure:

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.csv

JSON

Structured data format for automation and APIs.

sudo python3 linux_security_audit.py -f JSON -o security-audit.json

Structure:

{
  "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).json

XML

Extensible Markup Language for enterprise tools.

sudo python3 linux_security_audit.py -f XML -o security-audit.xml

Structure:

<?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.xml

Console

Direct terminal output without file creation.

sudo python3 linux_security_audit.py -f Console

Features:

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>&1

Remediation Options

Understanding Remediation

Remediation 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

Interactive Remediation

Review and approve each fix individually with detailed information.

sudo python3 linux_security_audit.py --remediate

Workflow:

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

Status-Filtered Remediation

Remediate only issues with specific status levels.

Remediate Only FAIL Status

Critical security issues only:

sudo python3 linux_security_audit.py --remediate-fail

Use Cases:

Focus on critical vulnerabilities
Quick security wins
Pre-production hardening
Compliance requirement fixes

Remediate Only WARNING Status

Best practice violations:

sudo python3 linux_security_audit.py --remediate-warning

Use Cases:

Post-critical remediation
Configuration optimization
Security posture improvement
Non-urgent hardening

Remediate Only INFO Status

Informational recommendations:

sudo python3 linux_security_audit.py --remediate-info

Use Cases:

Optional security enhancements
Future-proofing configurations
Documentation and awareness

Automated Remediation

Automatically apply fixes without prompting for each issue.

sudo python3 linux_security_audit.py --auto-remediate

Workflow:

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.

Combining Filters with Auto-Remediation

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-remediate

Use Cases:

Staged remediation approach (FAIL first, then WARNING, then INFO)
Risk-based prioritization
Minimizing system changes

Selective Remediation (From JSON Export)

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
Run Selective Remediation:

sudo python3 linux_security_audit.py --auto-remediate --remediation-file Selected-Report-20250107-143022.json

Example 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

Advanced Usage Patterns

Pattern 1: Baseline and Trend Analysis

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 files

Pattern 2: Pre/Post Remediation Comparison

Document 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 reports

Pattern 3: Multi-System Auditing

Audit 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 results

Pattern 4: Compliance-Specific Audits

Focus 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).html

Pattern 5: Scheduled Automated Audits

Set 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>&1

Systemd 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=journal

Timer 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.target

Enable timer:

sudo systemctl daemon-reload
sudo systemctl enable security-audit.timer
sudo systemctl start security-audit.timer

Pattern 6: Development to Production Pipeline

Integrate 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)"

Pattern 7: Emergency Security Response

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

Integration Scenarios

SIEM Integration (Splunk, QRadar)

# 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).json

Configuration Management (Ansible)

Ansible 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

Ticketing System Integration

# 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

GRC Platform Integration

# 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

Best Practices

Before Running Audits

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

During Execution

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

Report Management

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

Remediation Safety

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

Continuous Improvement

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

Common Usage Patterns Summary

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

Getting More Help

Detailed Module Information: Module Documentation
Output Format Details: Output Reference
Framework Standards: Framework Reference
Common Issues: Troubleshooting Guide
Questions: FAQ

← Back to Quick Start | Home | Next: Output Reference →

Usage Guide

Usage Guide

Table of Contents

Command-Line Syntax

Basic Syntax

All Available Options

Help and Information

Module Selection

Available Modules

Module Selection Examples

Run All Modules (Default)

Run Single Module

Run Multiple Specific Modules

Module Selection Strategy

For Initial Assessment

For Compliance Audits

For Continuous Monitoring

Output Formats

HTML (Default)

CSV

JSON

XML

Console

Remediation Options

Understanding Remediation

Interactive Remediation

Status-Filtered Remediation

Remediate Only FAIL Status

Remediate Only WARNING Status

Remediate Only INFO Status

Automated Remediation

Combining Filters with Auto-Remediation

Selective Remediation (From JSON Export)

Advanced Usage Patterns

Pattern 1: Baseline and Trend Analysis

Pattern 2: Pre/Post Remediation Comparison

Pattern 3: Multi-System Auditing

Pattern 4: Compliance-Specific Audits

Pattern 5: Scheduled Automated Audits

Pattern 6: Development to Production Pipeline

Pattern 7: Emergency Security Response

Integration Scenarios

SIEM Integration (Splunk, QRadar)

Configuration Management (Ansible)

Ticketing System Integration

GRC Platform Integration

Best Practices

Before Running Audits

During Execution

Report Management

Remediation Safety

Continuous Improvement

Common Usage Patterns Summary

Getting More Help

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally