sentinellab - A defensive Python toolkit for analyzing logs, det

项目说明

SentinelLab

A local, defensive security-monitoring and incident-in toolkit.

> Scope & intent: SentinelLab is strictly for use against systems you are
> authorized to monitor, and ships only with synthetic/offline sample data.
> It contains no exploitation code, credential-theft logic, persistence
> or e techniques, malware behavior, or instructions for attacking
> real targets. Every network-facing feature (threat-intel enrichment) is
> offline-only by default and will never make a li unless you
> explicitly wire up and configure your own provider.

What it does

1. Ingests Apache/Nginx access logs, SSH auth logs, generic CSV logs, and
JSON event logs, streaming them into one normalized event schema.
2. Detects brute-force attempts, credential-stuffing-like patterns,
unusual login times, repeated 404/403 probing, path tra, suspicious
user agents, scanning behavior, and request-rate spikes - using
thresholds you can tune in config/thresholds.yaml.
3. Enriches IPs with offline sample reputation/ASN/country data and
allow/block lists (sentinellab/enrichment/data/*.json).
4. Correlates related alerts into incidents with a timeline and a
transparent, formula-based risk score.
5. Reports in Markdown, JSON, CSV, and a self-contained HTML report with
charts, se badges, timelines, and recommended actions.

Project layout

Why it's built this way

One normalized schema (models.py) means every parser converts *into*

a common shape, so detectors/correlator/reporters ne raw log
formats. Adding a new log source only means writing one new parser.

Rules are pure functions (events, config) -> list[Alert] with no

shared state and no network access, each returning a human-readable
reason - nothing is a black box, and thresholds live in YAML instead of
code so you can tune them without touching Python.

Enrichment is behind a Protocol (ThreatIntelProvider); the only

implementation shipped is MockProvider, which reads local JSON. This
keeps the whole toolkit offline-safe by construction, not by con.

Risk scoring is a plain weighted formula, and the exact arithmetic is

stored on the incident and printed in every report - fully auditable.

Streaming ingestion: parsers read files in line-chunks

(ingestion/base.py) instead of loading e into memory, so large
log files are handled gracefully.

Setup (macOS)

No paid APIs, no accounts, no network access required.

Quick start

Reports land in reports/report.{md,json,csv,html}. Open reports/report.html
in a browser for the full dashboard-style view.

Example output

Configuration

All thresholds live in config/thresholds.yaml (window sizes, minimum
counts, se cutoffs, tra/user-agent pattern lists). Pass a custom
copy with sentinellab analyze --config path/to/thresholds.yaml.

Filtering incidents by se

De

CI runs the same lint + test commands on Python 3.11 and 3.12 via
.github/workflows/ci.yml.

Extending SentinelLab

New log format: add a parser in sentinellab/ingestion/ implementing

can_parse/parse_file, and register it in normalizer.py.

New detection rule: add a function to detection/rules.py following

the (events, config) -> list[Alert] signature and append it to
ALL_RULES, plus a threshold block in config/thresholds.yaml.

New threat-intel provider: implement ThreatIntelProvider.lookup(ip).

If you build a li provider, wiring it in is an explicit,
separate step - SentinelLab will never do this automatically.

License

MIT.

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A defensive Python toolkit for analyzing logs, detecting suspicious activity, and generating security incident reports.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。