Changelog

Usage Guide

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

Table of Contents

• Command-Line Syntax
• Module Selection
• Output Formats
• Remediation Options
• Advanced Usage Patterns
• Integration Scenarios
• Best Practices

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
--parallel		Execute modules in parallel
--workers		Number of parallel workers	Auto
--perf-profile		Display performance statistics (renamed from --profile in v3.7)
--profile NAME		NEW v3.7 (expanded v3.9): Apply per-distribution audit profile (generic, rhel9, rhel8, ubuntu24, ubuntu22, debian12, alpine, suse15, kali, mxlinux, mint, zorin, elementary, almalinux, rocky, centos, centosstream, fedora)	none
--list-profiles		NEW v3.7: List all available distribution profiles
--split-reports		NEW v3.8: Generate a separate report per framework in reports/by-framework/, alongside the combined report
--split-only		NEW v3.8: Generate only the per-framework reports (skip the combined report)
--attack-surface		NEW v3.8: Generate an attack-surface assessment report (HTML + JSON) synthesizing exposure across all frameworks
--log-level		Set logging level (DEBUG/INFO/WARNING/ERROR)	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
--no-cache		Disable the per-process helper cache (v3.6)
--baseline		Path to a prior audit JSON for drift comparison (v3.7)
--rollback-path		Path to write the generated rollback script (v3.7)
--remediation-bundle		Apply a predefined remediation bundle (see --list-bundles) (v3.7)
--list-bundles		List available remediation bundles and exit (v3.7)
--asset-criticality		Asset criticality 1-10 for risk scoring (v3.7)	5
--show-risk-priority		Show the risk-prioritized findings list (v3.7)
--show-correlations		Show cross-framework correlations in output (v3.7)
--validate-results		Run strict result validation in the pipeline (v3.7)
--threshold		Compliance pass/fail threshold percentage (v3.5)	70.0

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 16 security framework modules:

Module	Full Name	Check Count	Description
Core	Core Security Baseline	185	Industry best practices, OS-specific hardening, and attack-surface hygiene
CIS	CIS Benchmarks	258	Center for Internet Security benchmark + Controls v8 IG3
CISA	CISA Guidance	196	CISA CPGs, ZTMM, KEV, Stop Ransomware, Secure by Design
ENISA	ENISA Guidelines	142	EU Agency for Cybersecurity + NIS2 + Cyber Resilience Act + DORA
ISO27001	ISO/IEC 27001:2022	147	Annex A controls + 27017/27018/27701
NIST	NIST Frameworks	234	NIST 800-53 R5, CSF 2.0, 800-171, 800-207, 800-161, SSDF 800-218
NSA	NSA Hardening	193	NSA guidance + CNSA 2.0 + K8s hardening + encrypted DNS + eBPF
STIG	DISA STIGs	205	Defense Information Systems Agency Security Technical Implementation Guides
ACSC	ACSC Essential Eight	69	Australian Cyber Security Centre Essential 8 + ISM (ML2/ML3)
CMMC	CMMC 2.0	94	CMMC 2.0 (L1/L2/L3) + NIST 800-171 Rev 3 + DFARS
DistBaseline	Distribution Baselines	90	Per-distro hardening (Ubuntu USG / RHEL / SUSE / Arch)
EDR	EDR / ATT&CK	87	EDR + MITRE ATT&CK + Sigma/YARA + cloud-native + forensics
GDPR	GDPR Technical Controls	75	GDPR Art 32 + ePrivacy + breach notification
HIPAA	HIPAA Security Rule	114	HIPAA Security Rule + 405(d) HICP + breach notification
PCI-DSS	PCI DSS v4.0.1	110	Payment Card Industry Data Security Standard (Req 1-12)
SOC2	AICPA SOC 2	98	SOC 2 Trust Service Criteria (CC1-CC9 + Availability/Confidentiality/PI/Privacy)

Module selectors are case-insensitive. The PCI-DSS module can be selected as PCIDSS, PCI-DSS, or PCI.

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: 2,297 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: 97-212 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

Distribution Profiles (v3.7)

Per-distribution profiles are filters that exclude inapplicable modules and category prefixes for a specific Linux distribution. Profiles are subtractive only - they never add or modify checks. The default behavior (no --profile flag) runs the full audit unchanged.

Available Profiles

sudo python3 linux_security_audit.py --list-profiles

Profile	Applicable Distros	Excludes
generic	any	nothing (no-op; useful for explicit pipeline declarations)
rhel9	RHEL 9, AlmaLinux 9, Rocky 9, Oracle Linux 9, CentOS Stream 9	Snap, Ubuntu Pro, AppArmor (Debian) categories
rhel8	RHEL 8 family	Snap, Ubuntu Pro, AppArmor (Debian) categories
ubuntu24	Ubuntu 24.04	DNF, RPM, SELinux (RHEL-default) categories
kali	Kali Linux	DNF, RPM, SELinux, Ubuntu Pro, Snap categories
mxlinux	MX Linux	DNF, RPM, SELinux, Ubuntu Pro, Snap categories
mint	Linux Mint	DNF, RPM, SELinux (RHEL-default) categories
zorin	Zorin OS	DNF, RPM, SELinux (RHEL-default) categories
elementary	elementary OS	DNF, RPM, SELinux (RHEL-default) categories
almalinux	AlmaLinux 8/9	Snap, Ubuntu Pro, AppArmor (Debian), APT categories
rocky	Rocky Linux 8/9	Snap, Ubuntu Pro, AppArmor (Debian), APT categories
centos	CentOS Linux 7/8 (EOL)	Snap, Ubuntu Pro, AppArmor (Debian), APT categories
centosstream	CentOS Stream 9/10	Snap, Ubuntu Pro, AppArmor (Debian), APT categories
fedora	Fedora (current)	Snap, Ubuntu Pro, AppArmor (Debian), APT categories
ubuntu22	Ubuntu 22.04	DNF, RPM, SELinux (RHEL-default) categories
debian12	Debian 12	DNF, RPM, Snap, Ubuntu Pro, SELinux (RHEL-default) categories
alpine	Alpine Linux	DNF, RPM, Snap, Ubuntu Pro categories
suse15	SLES 15, openSUSE Leap 15	Snap, Ubuntu Pro, DNF, SELinux (RHEL-default) categories

Usage Examples

# Run audit with RHEL-9 profile (filters Debian/Ubuntu-specific noise)
sudo python3 linux_security_audit.py --profile rhel9

# Combine with module selection
sudo python3 linux_security_audit.py --modules CIS,STIG --profile ubuntu24

# Combine with parallel execution
sudo python3 linux_security_audit.py --parallel --profile debian12

# Inspect what a profile filters
sudo python3 linux_security_audit.py --list-profiles

Security and Validation

Profile names are validated against the regex ^[a-z][a-z0-9_-]{0,30}$ - injection attempts (--profile "rhel9; rm -rf /"), path traversal (--profile "../etc/passwd"), and unknown profile names are explicitly rejected with exit code 2. All profile data is hardcoded in shared_components/profiles.py; no external file loads, no eval, no JSON/YAML parsing is performed on user input.

Per-Framework Split Reports (v3.8)

When you audit many frameworks at once, the combined report is comprehensive but can become long and hard for a single audience to digest. The --split-reports flag generates one focused report per framework in reports/by-framework/, alongside the combined all-in-one report.

# Combined report PLUS one report per framework
sudo python3 linux_security_audit.py --modules CIS,STIG,PCIDSS,HIPAA --split-reports

# Only the per-framework reports (skip the combined one)
sudo python3 linux_security_audit.py --modules CIS,STIG,PCIDSS,HIPAA --split-only

# Works for any output format
sudo python3 linux_security_audit.py -f JSON --split-reports

Each split report contains only that framework's findings, with its own executive dashboard, compliance score, and remediation guidance - so the PCI-DSS team receives a PCI-DSS report, the HIPAA team receives a HIPAA report, and so on. Files are named <FRAMEWORK>-Audit-<host>-<timestamp>.<ext>.

If only a single framework is selected, no split is performed (the combined report already is that framework's report).

Attack Surface Assessment (v3.8)

The --attack-surface flag generates a separate assessment-based report that re-frames the audit findings around exposure rather than standards conformance. Where the compliance report answers "are we compliant with framework X?", the attack-surface report answers "where is this host exposed, and how badly?".

# Generate the attack-surface report alongside the normal report
sudo python3 linux_security_audit.py --attack-surface

# Combine with framework selection and split reports
sudo python3 linux_security_audit.py --modules CORE,CIS,STIG,NIST --attack-surface --split-reports

The report synthesizes exposure-relevant findings from every selected framework plus the host-facts registry into ten attack-surface domains:

1. Network Exposure - listeners, firewall posture, exposed services
2. Authentication & Access - SSH, PAM, MFA, password policy
3. Privilege & Escalation - sudo, SUID/SGID, capabilities
4. Filesystem Exposure - world-writable files, permissions, mounts
5. Service & Daemon Surface - running and legacy/cleartext services
6. Kernel & Boot Surface - kernel hardening, module policy, boot integrity
7. Container & Orchestration - Docker socket, Kubernetes exposure
8. Credential & Secret Exposure - keys and secrets at rest
9. Cryptographic Posture - FIPS, TLS, cipher strength
10. Detection & Response - audit/logging/FIM coverage (low coverage raises effective exposure because intrusions go unnoticed)

Each domain receives a severity-weighted exposure score (0-100, higher = more exposed) and rating (Minimal -> Low -> Moderate -> Elevated -> High), plus its top contributing findings. An overall exposure score and a cross-domain "Top Exposure Findings" table head the report. Output is written to reports/Attack-Surface-<host>-<timestamp>.html and .json.

The CORE module contributes dedicated attack-surface enumeration checks (category CORE - Attack Surface): external-facing TCP/UDP listeners, legacy/cleartext service binaries, SUID/SGID and world-writable exposure summaries, container-socket exposure, and kernel-module lockdown state. CORE is the right home for these because it is the only non-framework-tied module.

Note: The attack-surface score is an assessment aid, not a compliance score. It is derived from the same findings shown in the compliance report, reorganized by exposure.

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:

1. Script performs full audit
2. Presents each remediable issue one at a time
3. Shows: Module, Category, Status, Message, Details, Remediation Command
4. Prompts: [y]es, [n]o, [s]kip remaining, [q]uit
5. Executes approved remediations
6. 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:

1. Script performs full audit
2. Identifies all remediable issues
3. Displays summary of actions to be taken
4. Prompts for final confirmation
5. Executes all remediations automatically
6. 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:

1. Run Initial Audit:

sudo python3 linux_security_audit.py

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

3. Save JSON File:

   • Browser downloads file: Selected-Report-YYYYMMDD-HHMMSS.json
   • Contains only your selected issues

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

1. Test in Non-Production First: Always test on development/staging systems before production
2. Schedule Appropriately: Run during maintenance windows or low-usage periods
3. Communicate: Inform relevant teams before running audits
4. Backup Configurations: Back up critical config files before remediation
5. Review Modules: Select appropriate modules for your environment and compliance needs

During Execution

1. Monitor Progress: Watch for errors or unexpected behavior
2. Review Results: Don't blindly accept all findings - validate in your context
3. Document Changes: Keep logs of all remediations applied
4. Test After Remediation: Verify system functionality after applying fixes
5. Staged Approach: Fix critical issues first, then warnings, then informational

Report Management

1. Consistent Naming: Use consistent filename conventions
2. Centralized Storage: Store reports in a central, backed-up location
3. Access Controls: Protect reports (contain security information)
4. Retention Policy: Define how long to keep audit reports
5. Regular Reviews: Schedule periodic review of audit trends

Remediation Safety

1. Read First: Always read remediation commands before executing
2. Understand Impact: Know what the remediation will change
3. Test Individually: Test critical remediations one at a time
4. Have Rollback Plan: Know how to undo changes if needed
5. Document Everything: Keep detailed logs of what was changed and why

Continuous Improvement

1. Trend Analysis: Track metrics over time to measure improvement
2. Adjust Baselines: Update expectations as security posture improves
3. Learn Patterns: Understand recurring issues and address root causes
4. Automate Where Safe: Automate known-safe remediations over time
5. 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

---

v3.0 Pipeline Flags

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.

--baseline PATH

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

--rollback-path PATH

Generate 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.sh

--remediation-bundle NAME

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

--asset-criticality 1-10

Set 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-priority

--show-risk-priority

Display risk priority scores (1-100) for each Fail/Warning finding, ranked highest first. Combines severity, exploitability, exposure, and asset criticality.

--show-correlations

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.

--validate-results

Run strict result validation. Reports any defects in module output (missing severity, malformed cross-references, control characters in messages).

--list-bundles

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

--threshold N

Set 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 x status credit).

sudo python3 linux_security_audit.py --threshold 85

---

<- Back to Quick Start | Home | Next: Output Reference ->