Python Operational Tools

This directory contains small Python utilities that support operational analysis in infra-run.

Python is used here only when it adds practical value over Bash: parsing structured or noisy input, producing repeatable reports, comparing evidence, or emitting machine-readable output for later automation. Shell remains the default choice for direct host checks and simple command wrappers.

Tools

Tool	Path	Purpose	Typical use	Example command
incident-log-summary	incident-log-summary	Summarize configured incident patterns from one local log file.	First-pass incident notes from system or application logs.	`python3 incident_log_summary.py --file examples/system-messages.log`
log-diff-checker	log-diff-checker	Compare configured patterns before and after a change.	Post-change review for new, increased, decreased, resolved, or unchanged log symptoms.	`python3 log_diff_checker.py --before examples/pre-change.log --after examples/post-change.log`
auth-log-audit	auth-log-audit	Summarize SSH, sudo, su, and PAM findings from local authentication logs.	Authentication incident review or access-control evidence gathering.	`python3 auth_log_audit.py --file examples/sample-auth.log`
jvm-log-analyzer	jvm-log-analyzer	Summarize JVM exceptions, stack traces, HTTP 5xx entries, database issues, and TLS symptoms.	Java application support, restart review, or incident handoff evidence.	`python3 jvm_log_analyzer.py --file examples/sample-jvm-app.log`
journal-analyzer	journal-analyzer	Summarize exported `journalctl` text for failed units, restart loops, OOM events, and service warnings.	Linux service incident review or patching/change evidence.	`python3 journal_analyzer.py --file examples/sample-journal.log`
known-error-matcher	known-error-matcher	Match local logs against a JSON known-error catalog.	Connect known symptoms to severity, category, samples, and runbook references.	`python3 known_error_matcher.py --file examples/sample-app.log --patterns patterns.json`

Expected Use Cases

Log parsing for incident review.
Markdown or text report generation from collected evidence.
Change evidence helpers for pre-check and post-check notes.
Incident summary builders from sanitized inputs.
Structured output for automation, such as JSON where useful.

Standards

Use the Python standard library only unless a later tool clearly justifies another dependency.
Keep tools read-only by default.
Do not perform destructive actions.
Use argparse for command-line interfaces.
Produce predictable text output suitable for terminal review and change notes.
Support text, Markdown, and JSON output where useful for terminal review, tickets, or local automation.
Use an OK, WARNING, CRITICAL, and UNKNOWN status model for findings.
Handle malformed input, permission problems, and runtime errors defensively.
Return meaningful exit codes.
Keep each tool small, focused, and easy to review.

Exit Codes

0 - OK, no findings, or successful validation.
1 - Operational findings detected.
2 - Invalid input, missing dependency, permission issue, or runtime error.

Validation

From the repository root:

bash scripts/check-python.sh
bash scripts/validate-repo.sh

The checks use python3 -m py_compile and do not require external Python dependencies.

Expected Tool Structure

Future tools should use a small self-contained layout:

tool-name/
  tool_name.py
  README.md
  examples/
    sample-input.log
    sample-report.md

Do not add package metadata, framework scaffolding, or external dependency files unless a future tool has a specific operational reason.

3.8 KiB Raw Permalink Blame History