Prohori (প্রহরী)

A laptop-sized mini-SOC: from raw logs to detections, enriched incidents and analyst-ready reports, with honest machine-learning evaluation and a streaming data pipeline.

Prohori (প্রহরী) is Bengali for "guard". It is an open-source, defensive security-operations toolkit in Python that runs on a single laptop with free tools only, offline by default.

Status: alpha (v0.1.0). The batch core is complete: one command goes from a log file to scored incidents and shareable reports, and a labelled attack simulator measures the rules. Machine learning, the streaming pipeline and the LLM analyst follow in later releases. See the CHANGELOG and the roadmap.

60-second demo

pipx install prohori        # or: pip install prohori
prohori demo

The demo simulates an account takeover, an SSH brute force and a web scan, triages each one offline and writes an HTML report per incident to prohori-demo/. It needs no configuration and sends nothing over the network. Sample reports: Markdown, HTML (download and open it) and redacted.

Contents

• What it does
• Install
• Quick start
• Example: an account takeover
• Commands
• Built-in detection rules
• How well the rules work
• Privacy and safety
• Documentation
• Limitations
• Roadmap
• Development

What it does

flowchart LR
    A[Log files<br>auth.log, nginx, app JSON] --> B[parse<br>common event schema]
    B --> C[detect<br>15 YAML rules]
    C --> D[incidents<br>group, score, ATT&CK]
    E[enrich<br>GeoLite2, AbuseIPDB, VirusTotal] --> D
    D --> F[report<br>Markdown, HTML, JSON, CSV]

Prohori only recommends actions. It never blocks addresses, disables accounts or touches remote systems.

Install

Prohori needs Python 3.11 or newer. CI tests it on Linux and Windows; macOS should work but is not tested.

• From PyPI: pipx install prohori puts the prohori command in its own environment; pip install prohori works in any virtual environment. Local GeoLite2 support is an extra: pip install "prohori[geoip]".
• From source: install uv, then git clone https://github.com/UtshaBasak/Prohori.git && cd Prohori && uv sync, and run commands as uv run prohori .... The sample files used below are in the repository.

Quick start

Everything below runs offline on the synthetic samples in the repository (run from a clone).

uv run prohori triage samples/logs/account-takeover.jsonl -o triage/   # the whole pipeline
uv run prohori parse samples/logs/auth.log                      # normalise a log
uv run prohori detect samples/logs/auth.log                     # run the 15 rules
uv run prohori enrich 203.0.113.7 --offline                     # look up an IP (demo data)
uv run prohori incidents samples/logs/account-takeover.jsonl    # group alerts into incidents
uv run prohori report samples/incidents/INC-ee7c8818fbb34989.json -f html -o report.html
uv run prohori simulate account-takeover --seed 1 --out out/      # your own labelled attack

prohori triage writes triage/summary.md, triage/incidents.jsonl and an HTML report per incident. Open a report in a browser: one file, no scripts, no external resources. For your own logs, prohori triage /var/log/auth.log --year 2026 -o triage/ works the same way (add --redact-ips before sharing the output).

Example: an account takeover

samples/logs/account-takeover.jsonl is a synthetic attack on a web shop account: twelve wrong passwords from one IP in 33 seconds, a successful sign-in, two-step verification switched off and the bKash payout number changed. Prohori raises four alerts and joins them into one critical incident:

$ uv run prohori incidents samples/logs/account-takeover.jsonl     # first lines
INC-ee7c8818fbb34989  critical  score 100
+-------------------------------------------------------------------------------------------------+
| title       | Successful sign-in after many failures from one IP and 3 related alerts           |
| time (UTC)  | 2026-10-24 21:10:00 - 2026-10-24 21:13:10                                         |
| confidence  | high                                                                              |
| rules       | PRH-ACCT-001, PRH-AUTH-001, PRH-AUTH-003                                          |
| entities    | source.ip: 203.0.113.7                                                            |
|             | user.email_hash: 0cc175b9c0f1b6a831c399e269772661                                 |
|             | user.id: u-2001                                                                   |

Every point of the score is explained (from prohori report):

The report adds the timeline, the IP's enrichment, the ATT&CK techniques (T1110 Brute Force, T1078 Valid Accounts, T1098 Account Manipulation, T1556.006 Multi-Factor Authentication), recommended actions from the runbooks and the limitations, such as "single log source" and "enrichment is bundled demo data".

Commands

Commands that take a file also read standard input with -, and every command has --help. Exit codes are the same everywhere: 0 nothing found, 3 alerts or incidents found (--exit-zero turns this off for CI pipelines), 1 nothing could be processed and 2 invalid usage. The full reference is docs/CLI.md.

Built-in detection rules

ATT&CK tags are verified against the official Enterprise ATT&CK v20.0 data. Each rule has a runbook in src/prohori/runbooks/. Writing your own rules is covered in docs/RULES.md.

How well the rules work

prohori simulate writes each attack scenario in two variants: default, the attack the rules were designed for, and held-out, the same attack done the way a careful attacker would (slower, from more addresses, with a browser user agent, obfuscated, or at another hour). scripts/evaluate_rules.py runs all rules over five seeds of each and compares the alerts with the line labels.

Expected rules that missed in the held-out variants (runs missed out of runs):

• account-takeover: PRH-ACCT-001 3/5, PRH-AUTH-001 5/5
• admin-misuse: PRH-ADMIN-002 5/5
• credential-stuffing: PRH-AUTH-001 5/5, PRH-AUTH-002 5/5, PRH-AUTH-003 5/5
• password-spraying: PRH-AUTH-001 5/5
• ssh-bruteforce: PRH-AUTH-001 5/5
• web-scanning: PRH-WEB-003 5/5

PRH-ACCT-001 has low precision on purpose: it flags every sensitive change soon after a sign-in, including the owners' own. These are synthetic results written by the rules' author; the full per-rule table and caveats are in docs/SIMULATOR.md.

Privacy and safety

• Offline by default. Nothing leaves the machine unless you configure API keys and, for incidents, pass --online. Tests block real network access.
• Private, reserved and documentation IP addresses are never sent to outside services, even when keys are configured. VirusTotal keeps the addresses it is asked about, so querying is a deliberate choice.
• Logs are untrusted input. Parsers cap line lengths and strip control characters; reports escape every value for their format (HTML, Markdown, CSV formulas) and are tested with hostile input.
• Shareable reports. --redact / --redact-ips use keyed pseudonyms and fail closed.
• No secrets in the repository. API keys live in the environment or a git-ignored .env; gitleaks runs on every commit and in CI.
• Samples are synthetic and use documentation address ranges only.

Third-party data terms (MITRE ATT&CK, GeoLite2, AbuseIPDB, VirusTotal) are summarised in docs/LICENSES.md.

Documentation

Limitations

Prohori is honest about what it does not do:

• It reads logs after the fact. There is no live monitoring yet (the streaming pipeline is planned for v0.3.0), and it never blocks, disables or changes anything.
• Rules see only what the logs say. Request bodies, headers and encrypted traffic are not inspected; the web rules use the request line only.
• Thresholds can be evaded. The held-out evaluation shows that slow or widely distributed attacks stay under the brute-force and spraying thresholds; see How well the rules work.
• Some rules are noisy by design. PRH-ACCT-001 flags every sensitive change shortly after a sign-in, including the owner's own; incidents list such benign causes as limitations.
• The evaluation is synthetic and written by the rules' author. Test the rules on your own logs before relying on them.
• Enrichment free tiers are small and non-commercial, and reputation data is evidence, not proof.
• Supported formats are auth.log, nginx/Apache access logs and JSON Lines (built-in app layout or a field mapping). Windows event logs and cloud audit logs are not supported yet.

Roadmap

Development

uv sync                        # create .venv with the package and dev tools
uv run pre-commit install      # optional: run checks on every commit

uv run ruff check .            # lint
uv run ruff format --check .   # formatting
uv run mypy                    # strict type check
uv run pytest --cov            # tests with coverage (kept at 85 % or more)
uv run prohori rules test      # run every rule against its fixtures

CI runs on Linux and Windows with Python 3.11 to 3.14, plus CodeQL, secret scanning, parser fuzzing and the OpenSSF Scorecard. All GitHub Actions are pinned to commit SHAs. See CONTRIBUTING.md for conventions.

Security

To report a vulnerability, see SECURITY.md.

License

MIT. Third-party data has its own terms; see docs/LICENSES.md.