# auth-log-audit

`auth-log-audit` is a read-only Python CLI for reviewing local Linux authentication logs. It summarizes suspicious SSH, sudo, su, and PAM authentication patterns that may require operator review during incident response, hardening checks, or access-control evidence gathering.

The tool analyzes collected log files only. It does not modify logs, query remote systems, or prove compromise.

## When To Use

- During incident response when `/var/log/auth.log`, `/var/log/secure`, or an exported authentication log needs a quick first-pass summary.
- During Linux hardening or access review when repeated failures, invalid users, root login attempts, or sudo failures need to be surfaced.
- Before attaching authentication evidence to an incident, security, problem, or compliance review ticket.
- When JSON output is useful for local automation or repeatable reporting.

## What It Does

- Reads one local authentication log supplied with `--file`.
- Detects common SSH, sudo, su, and PAM authentication events.
- Extracts usernames, source IPs, authentication methods, services, timestamps, and sample raw lines where practical.
- Aggregates failed login counts by source IP and username.
- Flags suspicious source IPs and usernames when failed attempts meet the configured threshold.
- Produces text, Markdown, or JSON output.

## What It Does Not Do

- It does not detect breaches or prove compromise.
- It does not read remote systems or live journal streams.
- It does not modify logs, accounts, SSH configuration, sudoers, or host state.
- It does not query SIEM, SOC tooling, ELK, Zabbix, identity providers, or ticketing systems.
- It does not replace host-specific incident response, access review, or forensic procedures.
- It does not classify every vendor-specific authentication message.

## Supported Input Types

- Debian/Ubuntu-style `/var/log/auth.log`.
- RHEL/Oracle Linux-style `/var/log/secure`.
- Exported authentication logs with similar syslog-style lines.
- UTF-8 text input is expected. Invalid byte sequences are replaced during read so review can continue.

Empty, missing, unreadable, or non-file paths are rejected with exit code `2`.

## Supported Event Categories

SSH-related:

- Failed SSH password login.
- Failed SSH publickey login.
- Successful SSH login.
- Invalid user attempts.
- Root login attempts.
- Refused or disallowed user attempts.
- Disconnects after failed authentication where detectable.
- Too many authentication failures where detectable.

sudo and su-related:

- sudo command usage.
- sudo authentication failure.
- su session opened.
- su authentication failure.

Generic authentication:

- authentication failure.
- `pam_unix` authentication failure.
- Account locked messages where detectable.
- User not known to the underlying authentication module.

## Timestamp Handling

The scanner attempts to parse:

- `May 11 10:15:30`
- `2026-05-11 10:15:30`
- `2026-05-11T10:15:30`

Timestamp parsing is best-effort. Lines with unparseable timestamps are still analyzed, and first seen / last seen values are reported as `UNKNOWN` when no parseable event timestamps are found. Syslog timestamps without a year use the current local year internally while preserving the original timestamp shape in text and Markdown output.

## Suspicious Activity Model

Default threshold:

```text
--threshold-failed 5
```

The report classifies findings conservatively:

- `OK` - no suspicious findings.
- `WARNING` - repeated failed logins, invalid users, root login attempts below the threshold, or sudo authentication failures.
- `CRITICAL` - root login attempts above threshold, high-volume brute-force indicators, or multiple suspicious source IPs above threshold.

This status is a triage signal. It identifies suspicious authentication patterns that require review; it does not confirm a breach.

## Usage

```bash
cd infra-run/scripts/python/auth-log-audit

python3 auth_log_audit.py --file examples/sample-auth.log
python3 auth_log_audit.py --file examples/sample-secure.log
python3 auth_log_audit.py --file examples/sample-auth.log --format markdown
python3 auth_log_audit.py --file examples/sample-auth.log --format markdown --output auth-report.md
python3 auth_log_audit.py --file examples/sample-auth.log --format json
python3 auth_log_audit.py --file examples/sample-auth.log --top 10
python3 auth_log_audit.py --file examples/sample-auth.log --threshold-failed 5
python3 auth_log_audit.py --file examples/sample-auth.log --ignore-users monitoring,backup,ansible
```

Ignored users are excluded from suspicious username threshold findings. Their events are still counted in totals and can still appear in top-user summaries so operational context is not silently hidden.

## Output Formats

- `text` - default terminal-oriented report.
- `markdown` - incident or security ticket attachment format.
- `json` - structured output for local automation.

Use `--output <path>` to write the rendered report to a separate file. Without `--output`, the report is printed to stdout. The tool rejects an output path that resolves to the input log file.

## Exit Codes

- `0` - OK, no suspicious findings.
- `1` - Suspicious findings detected.
- `2` - Invalid input, unreadable file, bad argument, output write failure, or runtime error.

## Example Text Output

```text
Auth Log Audit
==============

Overall status: WARNING
First seen: May 11 09:58:12
Last seen: May 11 10:07:48

Top Source IPs by Failed Attempts
---------------------------------
- 203.0.113.50: 7
- 198.51.100.23: 1

Suspicious Source IPs
---------------------
- 203.0.113.50: 7

Operational Summary
-------------------
Overall status: WARNING
Total lines scanned: 15
Authentication events detected: 15
Failed logins: 8
Successful logins: 1
Invalid user attempts: 1
Root login attempts: 2
Sudo usage events: 1
Sudo authentication failures: 1
Suspicious source IPs: 1
Suspicious usernames: 0
Threshold used: 5
Ignored users: None
```

## Markdown Workflow

Generate a Markdown report from a collected authentication log and attach it to the incident or security ticket as supporting evidence:

```bash
python3 auth_log_audit.py \
  --file examples/sample-auth.log \
  --format markdown \
  --output auth-report.md
```

Review the report before attaching it. A `WARNING` or `CRITICAL` result should be reviewed with host access history, SSH configuration, sudo policy, user ownership, and any relevant monitoring evidence.

## Operational Limitations

- Pattern matching is intentionally simple and predictable.
- A single line may produce more than one event when PAM and service messages overlap.
- Syslog timestamps without a year are normalized internally with the current local year.
- Source IP extraction is IPv4-oriented.
- The tool compares counts, not rates, authentication windows, geolocation, or identity context.
- Large log files are read into memory; collect scoped extracts for very large incidents.
- Vendor-specific PAM modules or SSH daemon formats may need future patterns.

## Safety Notes

- The tool only reads the input log and optionally writes a separate report.
- The implementation uses the Python standard library only and does not require package installation.
- It does not require elevated privileges unless the chosen log path requires them.
- Do not include secrets, customer data, private hostnames, or unsanitized production details in portfolio examples.
- Treat operational findings as prompts that require review; the tool does not prove compromise or determine root cause automatically.