boikzdev/linux-security-auditor

1. Overall shape

This repository is a security auditing toolkit, not a monolithic app. Its architecture is split between Bash-based system interrogation/remediation and Python-based parsing, scoring, and report generation. The Bash side gathers host facts from Linux, and the Python side turns those findings into structured output and human-readable reports.

2. Primary execution entry point

The main runtime entry point is scripts/audit.sh. It acts as the orchestrator, dispatching to focused audit modules based on flags such as full audit, config-only, log-only, ports-only, or user/permission checks. This is the central coordination boundary for the whole system.

3. Shell audit modules

The scripts/ directory contains the operational subsystems:

- config_audit.sh for SSH, firewall, and permissions checks

- log_analysis.sh for suspicious activity and failed-login analysis

- port_scanner.sh for open-port discovery and exposure mapping

- hardening.sh for remediation guidance and optional system changes

These modules are the host-facing layer and are likely the only parts that touch live OS state directly.

4. Data collection and native tooling

The Bash modules rely on standard Linux utilities and optional security tools such as ss/netstat, grep/awk/sed, openssl, auditd, and nmap. This means the repository’s lower layer is a thin orchestration wrapper over native system inspection, rather than a large custom scanner implementation.

5. Python analysis layer

The python/ directory provides the post-processing pipeline:

- log_parser.py parses raw log content into structured events

- analyzer.py performs anomaly detection and risk/scoring logic

- report_generator.py converts audit results into final output

This creates a clean boundary between raw host evidence gathering and higher-level interpretation/reporting.

6. Report generation pipeline

The reporting path appears to consume audit results, likely in JSON form, and render them through templates/report_template.html. The template layer is separate from the reporting logic, which keeps presentation isolated from analysis. The README also indicates optional PDF generation via weasyprint, so output can be HTML-first with a PDF export path.

7. Configuration and policy inputs

configs/security_standards.yaml and configs/audit_profiles.yaml define the policy side of the system. These files provide audit baselines, compliance targets, and custom profile knobs, so the scanner behavior is driven by configuration rather than hardcoded rules alone. This is the main policy boundary in the architecture.

8. Artifacts and data flow

The main flow is:

Linux host state → Bash collectors → structured audit results → Python parsing/analyzer → HTML/PDF report.

The repository examples imply JSON as the intermediate exchange format, with generated reports as downstream artifacts. That makes the system easy to chain into automation, CI, or scheduled jobs.

9. Operational and deployment boundaries

The Dockerfile provides a containerized execution path for reproducible runs, while the Makefile offers local automation for install, audit, report, test, and docker targets. This suggests the toolkit can run either directly on a host or in an isolated container, depending on how much access to the system is needed.

10. CI/CD and quality gates

.github/workflows/security-audit.yml integrates the toolkit into GitHub Actions, indicating it is intended to run as an automated security gate in pipelines. The CI boundary likely exercises selected checks and report generation without requiring a full interactive environment.

11. Testing strategy

The tests/ directory focuses on Python units, especially test_analyzer.py and test_parser.py. That tells you the most testable logic lives in the parsing/scoring layer, while the Bash collectors are probably validated more through manual runs or CI execution than through deep unit isolation.

12. Documentation as part of the system

docs/USAGE.md, docs/HARDENING.md, and docs/TROUBLESHOOTING.md act as operational support for the toolchain. In architectural terms, they define intended workflows: audit, interpret findings, apply hardening, then re-audit to verify remediation.

13. Key architectural boundaries to diagram

A useful diagram should separate:

- host inspection/remediation scripts

- configuration/policy inputs

- Python analysis/reporting

- generated artifacts

- container/CI execution environments

The core design is a host-local security probe plus offline reporting pipeline, with policy and presentation externalized for maintainability.