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