Mateusz Suski
70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# 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](./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](./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](./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](./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](./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](./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
|
|
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:
|
|
|
|
```text
|
|
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.
|