# boikzdev/linux-security-auditor architecture

> Architecture diagram of the GitHub repository boikzdev/linux-security-auditor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boikzdev/linux-security-auditor
- Repository: https://github.com/boikzdev/linux-security-auditor

## Overview

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.

Main entry points: [`scripts/audit.sh`](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/audit.sh) (Audit entry), [`scripts/config_audit.sh`](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/config_audit.sh) (Config audit), [`python/report_generator.py`](https://github.com/boikzdev/linux-security-auditor/blob/main/python/report_generator.py) (Report gen), [`python/analyzer.py`](https://github.com/boikzdev/linux-security-auditor/blob/main/python/analyzer.py) (Analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_shell["Shell audits"]
  node_n_audit_sh["Audit entry<br/>bash orchestrator<br/>[audit.sh]"]
  node_n_config_audit["Config audit<br/>bash check<br/>[config_audit.sh]"]
  node_n_log_analysis["Log analysis<br/>bash check<br/>[log_analysis.sh]"]
  node_n_port_scanner["Port scan<br/>bash check<br/>[port_scanner.sh]"]
  node_n_hardening["Hardening<br/>bash remediation<br/>[hardening.sh]"]
end

subgraph group_g_python["Python pipeline"]
  node_n_log_parser["Log parser<br/>python parser<br/>[log_parser.py]"]
  node_n_analyzer{{"Analyzer<br/>python scoring<br/>[analyzer.py]"}}
  node_n_report_gen["Report gen<br/>python renderer"]
end

subgraph group_g_policy["Policy & templates"]
  node_n_security_standards["Standards<br/>yaml policy"]
  node_n_audit_profiles["Profiles<br/>yaml policy"]
  node_n_template["Report template<br/>html template"]
  node_n_html_pdf["HTML/PDF report<br/>artifact"]
end

subgraph group_g_delivery["Delivery & automation"]
  node_n_docker["Dockerfile<br/>container build"]
  node_n_makefile["Makefile<br/>automation"]
  node_n_workflow["CI workflow<br/>github actions<br/>[security-audit.yml]"]
  node_n_docs["Docs<br/>documentation<br/>[USAGE.md]"]
end

node_n_audit_sh -->|"dispatches"| node_n_config_audit
node_n_audit_sh -->|"dispatches"| node_n_log_analysis
node_n_audit_sh -->|"dispatches"| node_n_port_scanner
node_n_audit_sh -->|"invokes"| node_n_hardening
node_n_config_audit -->|"checks against"| node_n_security_standards
node_n_config_audit -->|"parameterized by"| node_n_audit_profiles
node_n_log_analysis -->|"feeds"| node_n_log_parser
node_n_log_parser -->|"inputs"| node_n_analyzer
node_n_port_scanner -->|"findings to"| node_n_analyzer
node_n_analyzer -->|"outputs"| node_n_report_gen
node_n_report_gen -->|"renders with"| node_n_template
node_n_report_gen -->|"produces"| node_n_html_pdf
node_n_docker -->|"runs"| node_n_audit_sh
node_n_makefile -->|"orchestrates"| node_n_audit_sh
node_n_workflow -->|"automates"| node_n_audit_sh
node_n_docs -.->|"explains"| node_n_hardening
node_n_docs -.->|"documents"| node_n_audit_sh

click node_n_audit_sh "https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/audit.sh"
click node_n_config_audit "https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/config_audit.sh"
click node_n_log_analysis "https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/log_analysis.sh"
click node_n_port_scanner "https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/port_scanner.sh"
click node_n_hardening "https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/hardening.sh"
click node_n_log_parser "https://github.com/boikzdev/linux-security-auditor/blob/main/python/log_parser.py"
click node_n_analyzer "https://github.com/boikzdev/linux-security-auditor/blob/main/python/analyzer.py"
click node_n_report_gen "https://github.com/boikzdev/linux-security-auditor/blob/main/python/report_generator.py"
click node_n_security_standards "https://github.com/boikzdev/linux-security-auditor/blob/main/configs/security_standards.yaml"
click node_n_audit_profiles "https://github.com/boikzdev/linux-security-auditor/blob/main/configs/audit_profiles.yaml"
click node_n_template "https://github.com/boikzdev/linux-security-auditor/blob/main/templates/report_template.html"
click node_n_docker "https://github.com/boikzdev/linux-security-auditor/tree/main/Dockerfile"
click node_n_makefile "https://github.com/boikzdev/linux-security-auditor/tree/main/Makefile"
click node_n_workflow "https://github.com/boikzdev/linux-security-auditor/blob/main/.github/workflows/security-audit.yml"
click node_n_docs "https://github.com/boikzdev/linux-security-auditor/blob/main/docs/USAGE.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_audit_sh,node_n_config_audit,node_n_log_analysis,node_n_port_scanner,node_n_hardening toneBlue
class node_n_log_parser,node_n_analyzer,node_n_report_gen toneAmber
class node_n_security_standards,node_n_audit_profiles,node_n_template,node_n_html_pdf toneMint
class node_n_docker,node_n_makefile,node_n_workflow,node_n_docs toneRose
```

## Components

### Shell audits

Host-facing Bash orchestration and checks

- [Audit entry](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/audit.sh): bash orchestrator · Main entry point that dispatches audit modes · `scripts/audit.sh`
- [Config audit](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/config_audit.sh): bash check · SSH, firewall, and permissions inspection · `scripts/config_audit.sh`
- [Log analysis](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/log_analysis.sh): bash check · Suspicious activity and failed-login analysis · `scripts/log_analysis.sh`
- [Port scan](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/port_scanner.sh): bash check · Open-port discovery and exposure mapping · `scripts/port_scanner.sh`
- [Hardening](https://github.com/boikzdev/linux-security-auditor/blob/main/scripts/hardening.sh): bash remediation · Remediation guidance and optional system changes · `scripts/hardening.sh`

### Python pipeline

Parsing, scoring, and report generation

- [Log parser](https://github.com/boikzdev/linux-security-auditor/blob/main/python/log_parser.py): python parser · Parses raw log content into structured events · `python/log_parser.py`
- [Analyzer](https://github.com/boikzdev/linux-security-auditor/blob/main/python/analyzer.py): python scoring · Performs anomaly detection and risk scoring · `python/analyzer.py`
- [Report gen](https://github.com/boikzdev/linux-security-auditor/blob/main/python/report_generator.py): python renderer · Converts audit results into final reports · `python/report_generator.py`

### Policy & templates

Audit baselines and presentation layer

- [Standards](https://github.com/boikzdev/linux-security-auditor/blob/main/configs/security_standards.yaml): yaml policy · Security baselines and compliance targets · `configs/security_standards.yaml`
- [Profiles](https://github.com/boikzdev/linux-security-auditor/blob/main/configs/audit_profiles.yaml): yaml policy · Audit profile knobs and run-time presets · `configs/audit_profiles.yaml`
- [Report template](https://github.com/boikzdev/linux-security-auditor/blob/main/templates/report_template.html): html template · Presentation template for generated reports · `templates/report_template.html`
- **HTML/PDF report**: artifact · Generated audit output for human review

### Delivery & automation

Container, CI, and local automation

- [Dockerfile](https://github.com/boikzdev/linux-security-auditor/tree/main/Dockerfile): container build · Containerized execution path for reproducible runs · `Dockerfile`
- [Makefile](https://github.com/boikzdev/linux-security-auditor/tree/main/Makefile): automation · Local targets for install, audit, report, test, and docker · `Makefile`
- [CI workflow](https://github.com/boikzdev/linux-security-auditor/blob/main/.github/workflows/security-audit.yml): github actions · Automated security audit pipeline in GitHub Actions · `.github/workflows/security-audit.yml`
- [Docs](https://github.com/boikzdev/linux-security-auditor/blob/main/docs/USAGE.md): documentation · Usage, hardening, and troubleshooting guides · `docs/USAGE.md`

## Connections

- Audit entry → Config audit: dispatches · Runs configuration checks as one audit mode
- Audit entry → Log analysis: dispatches · Runs log-focused analysis when requested
- Audit entry → Port scan: dispatches · Runs port exposure checks when requested
- Audit entry → Hardening: invokes · Provides remediation path after findings
- Config audit → Standards: checks against · Uses policy baselines for evaluation
- Config audit → Profiles: parameterized by · Behavior varies by audit profile
- Log analysis → Log parser: feeds · Raw logs are structured before analysis
- Log parser → Analyzer: inputs · Parsed events become analysis input
- Port scan → Analyzer: findings to · Exposure results contribute to scoring
- Analyzer → Report gen: outputs · Risk and anomaly results drive reporting
- Report gen → Report template: renders with · Uses the HTML report template
- Report gen → HTML/PDF report: produces · Emits the final human-readable artifact
- Dockerfile → Audit entry: runs · Container provides an isolated execution environment
- Makefile → Audit entry: orchestrates · Convenience targets wrap the main audit entry
- CI workflow → Audit entry: automates · CI executes the audit pipeline
- Docs → Hardening: explains · Docs describe remediation workflow
- Docs → Audit entry: documents · Usage guidance centers on the main entry point