AegisLog-AI - Open-source, terminal-first defensive security for

项目说明

<di="center">

<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/aegislog-readme-dark.png">
<img src="src/aegislog/assets/aegislog-logo.png" alt="AegisLog logo" width="380">
</picture>

AegisLog

Defensive Log In & E Analysis Platform

LOCAL-FIRST · READ-ONLY · DETERMINISTIC · E · EXPLAINABLE

![CI]()
![Security]()
![Latest release]()

O · Architecture · Detection · Monitoring · Reports · Installation · Security

MADE BY HR-PRESENTS

</div>

> [!IMPORTANT]
> Read-only in boundary
>
> AegisLog reads selected logs and accessible nati, analyzes them locally, and writes in reports and requested local state. It does not change source logs, accounts, services, firewall rules, or host security settings. Findings support human in; they do not authorize remediation.

Start here

New to log in? Follow the fi beginner guide, then try the downloadable synthetic demo pack. The pack includes checked expected results and a no-matching-findings comparison fixture.

Who it helps: IT administrators in service problems, support engineers re application logs, and security analysts triaging accessible local e. AegisLog provides local in and reporting; a managed SIEM, EDR, fleet agent or automated remediation service requires other tooling.

| Input | What AegisLog handles | Co limit |
| --- | --- | --- |
| Text logs | Syslog, ISO service records, common web access logs and Windows collector text | Unknown text may use generic fallback rules |
| Structured records | Known JSON/JSONL message, Docker, ECS, Suricata EVE, Zeek connection and network-flow fields; corresponding CS | Arbitrary JSON/CSV is not uni understood; recognized parsing does not imply a detection rule |
| Nati | Windows System/Application/Security, Linux journald, Docker logs where a | OS, permissions, source a, time window and event caps apply |
| Folders | Disco readable text candidates, then analyze selected files separately | Bounded discovery; binary/EVTX, compressed and unsupported encodings require appropriate export/con |

Check the report's recognized-record counts, retained e and collection limits. No matching rules does not establish a clean system. Rarity scores describe the sample, not attack probability.

First-user feedback checklist · Launch announcement draft

O

AegisLog is a terminal-first defensive log in platform for local files, nati, and live log streams.

It combines bounded ingestion, format recognition, deterministic rules, authentication correlation, incident grouping, rarity context, e review, and local HTML reporting. Users can in one file, scan a folder, inspect accessible computer logs, or monitor supported sources from their existing terminal.

The supported file workflow recognizes selected layouts in:

Nati support Windows Event Logs, Linux journald, and Docker logs where the required tools and access are a. Format-specific co and fallback behavior are described in Compatibility.

> [!NOTE]
> E by design
>
> Findings come from supplied files or explicitly selected telemetry sources. Bundled demonstrations are synthetic. Recognizing a record format does not guarantee that every relevant threat has a matching detection rule.

What AegisLog Does

AegisLog helps answer four practical questions: what happened in the a logs, which records deser, how the retained e relates, and what to inspect next. It supports security in and e operational troubleshooting from the same terminal.

A user can begin with an existing application log, inspect accessible operating-system events without preparing a file, scan a folder of logs, or watch new events arrive. The result is an e in with readable local reports and explicit co limits.

Choose an In

Platform Architecture

The in pipeline keeps e collection, analysis, and presentation separate.

Source sizes, retained excerpts, truncation, and collection limits affect the e a for analysis. Reports disclose these limits rather than presenting a bounded sample as a complete history.

Collection and Trust Boundaries

AegisLog reads from selected sources and writes its own reports or requested in state. The analysis pipeline provides no automatic source-editing or host-remediation action.

E Workflow

1. Select a file, folder, nati, or li.
2. Review physical-line, record, recognized-format, and retention counts.
3. Inspect findings, incident groups, e, and in guidance.
4. Open the summary or full retained-e report.
5. the lead against surrounding telemetry before taking action.

> [!TIP]
> How to interpret a result
>
> Se, confidence, incident grouping, and rarity help prioritize review. They do not independently prove an attack, attribution, or a shared root cause.

Core capabilities

| Area | AegisLog |
|---|---|
| File in | Static analysis of supported log layouts with disclosed parsing co |
| Nati | Windows System/Application/Security, Linux journald, and Docker collectors |
| Guided computer checks | Disco sources and select a bounded native time window |
| Folder in | Bounded recursi, source selection, optional identical-content deduplication |
| Deterministic detection | Local rules and authentication-related correlation |
| Incident context | Grouped e, explanations, entities, and ATT&CK review context |
| Anomaly context | E rarity within retained e |
| Li | Read-only rolling file and nati views |
| Multi-source monitoring | Compare and correlate supported li |
| Security Workbench | E filtering, details, timeline, and supported exports |
| Reports | Light HTML reports with dark text, summaries, and full retained e |
| Batch reporting | Searchable folder o, source outcomes, and JSON manifest |
| Na | Back, Quit, report opening, and return to the existing terminal |
| Health checks | Runtime, configuration, detection engine, and collector a |

Detection and Analysis

Deterministic Rules

The local engine checks recognized e and supported text patterns for in leads, including authentication failures, pri activity, web-related signals, and operational errors. Findings retain e and explanation so an analyst can inspect why they appeared.

Operational errors are distinguished from security in leads. A service timeout may need troubleshooting without establishing malicious activity.

Authentication and Pri Context

Authentication correlation can group related failures into an in lead. Windows event identity and account context affect interpretation: event 4672 for exact built-in service SIDs is treated as informational baseline activity, while other pri logons may warrant review.

> [!NOTE]
> Context changes interpretation
>
> A Windows pri event is not automatically an attack. Confirm the account, session, surrounding events, and expected administrati.

Incident Correlation

Incident groups connect related retained e for in. Grouping does not establish a common cause, malicious intent, or confirmed compromise. Explanations and ATT&CK context remain review aids.

Rarity and Activity

Terminal activity charts show bounded retained timestamped e. Report timelines show up to 12 occupied UTC minute buckets, disclose skipped gaps and unresol, and avoid in missing time information. Rarity scores describe unusual event classes within the retained sample; they are not a trained attack classifier.

> [!WARNING]
> Unusual activity is a lead, not a
>
> A rare event may be benign. Zero findings may reflect limited rules, unsupported fields, missing e, or collection limits. It does not establish a clean system.

How Findings Gain Context

Rule matches identify supported conditions. Correlation adds relationships, while activity and rarity describe the a sample. The analyst reviews these signals together with co and source context.

Native Logs and Computer Checks

Choose C Check Computer to disco sources, then select a source and time window. Nati are bounded by both time and count; known file sources are analyzed as files rather than through that native time window.

| Source | Requirements and scope |
|---|---|
| Windows Event Logs | Read access to the selected System, Application, or Security channel |
| Linux journald | journalctl and permission to read the requested journal |
| Docker | Docker CLI, running engine, and access to the named container |
| Known system/application paths | Existing readable log files; discovery is not exhaustive |

Windows Security channel access may require an administrator terminal. Use ele only when you need a protected source. Docker is optional for ordinary file and Windows Event Log in.

Folder In

Choose F Scan Folder and enter a folder path. Discovery defaults to likely logs; other supported text candidates can be included explicitly. Select sources indi or use ALL.

The workflow:

Discovery stops at 200 candidates or 10,000 entries. Choose a smaller folder when those limits prevent complete discovery. Matching a file extension does not guarantee complete parser support.

Folder-to-Report Workflow

Relati paths remain even when identical content shares a report. Failed, cancelled, or pending items remain distinct from successfully analyzed e.

Li

02 Li watches appended file events. 03 Multi-Source compares supported li. 05 Nati watches supported nati.

Li use bounded rolling e. They do not create a complete historical archive and do not replace a centralized SIEM or endpoint agent. Security Workbench and li retain their documented line-oriented detection scope rather than uni structured-schema import.

Use B/Escape to stop a live view and Q to quit AegisLog. Quitting returns control to the terminal where it was started.

Reports and E

Reports use white document pages, black text and light sea-blue framing. Aligned metrics, boxed findings and side rules separate obser, recommended review and retained e. The summary links to the full in record; every retained detector excerpt keeps its e reference. Full-report page count grows with e. Supporting activity distributions and rarity context can be expanded in the browser and are omitted from the compact print layout with an explicit notice.

Each in provides a short summary and a separate full retained-e HTML report. Reports use a company-facing layout with a larger transparent AegisLog logo, black body text, light sea-blue accents, a compact metrics strip, specific issue labels, and separate e and recommended-review areas. The short summary puts priority findings before supporting activity and collection scope; raw structured e stays in the complete report. The full report uses four in na choices, avoids repeated rule labels, and puts source identity and processing statistics in a technical appendix. The closing signature reads MADE BY HR-PRESENTS. Distribution bars include obser; timelines appear only when the retained timestamps support them.

| Report | Purpose |
|---|---|
| In summary | Compact o, priority findings, co, and next steps |
| Full retained-e report | Detailed retained findings and supporting references |
| Folder o | Batch outcomes, per-source context, search, and source appendix |
| JSON exports/manifest | Supported machine-readable in and batch context |

Use R Reports from the terminal to browse sa and batch o. Completed workflows provide report/folder opening actions where supported.

Expanded supporting distributions align Categories, Log levels, and Services side by side on wide screens. Narrow screens stack these panels; the compact print layout omits optional supporting panels with an explicit notice.

Report Na

Printing and PDF

Use Print summary / Save PDF for the o or Print complete report / Save PDF for the full retained-e document. Disable browser Headers and footers to remo dates and local file URLs.

> [!IMPORTANT]
> A report preser analysis, not every original event
>
> Keep original logs separately. Retention limits and omitted or truncated e are disclosed. A PDF summary is not a substitute for the full report or the original source.

Installation

Current Release

The in impro are documented in In workflows: grouped triage, explicit Windows session context, Docker/ECS message adapters, searchable sa, collection progress, signal comparisons, export preview, runtime diagnostics and opt-in release checks. These changes, the appro report design and the repository audit fixes are included in the v2.1.17 Windows and Python downloads. Source/output collision checks, consistent incident IDs, custom-rule report inclusion and bounded ingestion impro reliability.

The latest release also preser collection scope in both reports, impro pagination and explains explicit shadow-copy storage-limit obser.

Recent reliability fixes preser e boundaries, redact credential-key , handle live path rotation and enforce baseline scope matching. Windows detection quality includes explicit group-SID classification, target-host correlation boundaries and clearer heuristic scores. See Detection co.

v2.1.17 is the published stable release, built from 63448e60ab2c905355d6dda8bab2837a7a106058.

Download the Windows ZIP, standalone executable, Python wheel, or source package from the release page. Matching SHA-256 files are included.

> [!NOTE]
> Windows signing status
>
> The Windows executable is unsigned. SmartScreen or endpoint-security reputation warnings may appear. the published checksum; build pro is separate from Authenticode signing.

The release also bounds baseline reads to 2 MB and isolated Windows wheel installations on Python 3.10 and 3.14. See the remaining handoff for owner-controlled branch protection, independently labeled real-world e and physical-PC acceptance checks.

Windows Standalone

Download AegisLog.exe from the release page, then run from its folder:

Extract the Windows ZIP before using its packaged files.

Install a Terminal Command

With Python 3.10+ a, install pipx once:

Close and reopen your terminal so PATH changes take effect. Then install the published wheel:

Use py instead of python if that is the Python command a on your Windows installation.

> [!TIP]
> Command not recognized?
>
> Reopen the terminal after ensurepath. In Windows Command Prompt, you can also run "%USERPROFILE%\.local\bin\aegislog.exe" start directly. See Installation for PowerShell, upgrades, and uninstalling. Avoid combining pipx --force with --pip-args="--force-reinstall".

De Installation

This installs the checked-out source rather than the immutable published wheel. See upgrade guidance before changing an existing installation.

How to Use AegisLog

At aegis >, select a workflow or type a supported command.

| Choice | Workflow |
|---|---|
| 01 | ANALYZE a log file or the built-in demo |
| 02 / 03 | LI / multi-source monitoring |
| 04 / 05 | Nati / nati |
| 06 | INCIDENTS: review incident e |
| 07 / P | Demo / recorded replay |
| 08 / 09 | Health / command help |
| C / F | Guided computer check / folder scan |
| S | Security Workbench |
| R / A | Sa / workflow explanation |
| G | Optional beginner walkthrough with synthetic demo |
| B / Q | Back / Quit |

Choose G Beginner for the optional guided synthetic in and first-report walkthrough.

The D browser dashboard is removed. Terminal in panels remain; the CLI dashboard command renders a terminal in.

Common Commands

Replace example paths with your own accessible files. See the complete Command Reference.

Demonstration Data

Start aegislog start, choose 01 Analyze, and enter demo, or choose 07 Demo for the quick-start workflow.

The built-in authentication demo contains 7 records, 2 findings, and 2 incident groups: a HIGH authentication in lead and a MEDIUM operational error. These are synthetic training signals, not findings about the user's computer. Yearless syslog timestamps are not guessed; event order alone does not establish elapsed time.

Technology Stack

| Layer | Technology |
|---|---|
| Runtime | Python 3.10+ |
| Command interface | Typer |
| Terminal presentation | Rich |
| Analysis | Local Python parsers, rules, correlation, and bounded state |
| Reports | Local HTML, CSS, and Ja |
| Optional in storage | SQLite |
| Windows packaging | Standalone executable release workflow |
| Testing and linting | pytest and Ruff |
| Security checks | Bandit and dependency auditing |

Repository Structure

| Location | Purpose |
|---|---|
| src/aegislog/ | CLI, parsing, detection, collectors, in, and reporting |
| tests/ | Automated regression and behavior checks |
| docs/ | User guides, architecture, compatibility, security, and release guidance |
| docs/assets/ | Logo and documented reference previews |
| e/ | Synthetic labeled regression e |
| .github/workflows/ | CI, security, packaging, and release workflows |
| pyproject.toml | Python package metadata and tool configuration |
| SECURITY.md | Security reporting policy |
| CHANGELOG.md | Release history |

Automated Tests

With de dependencies installed:

Python 3.10–3.13 are covered by CI. Python 3.14 was exercised by the owner but is not yet in that matrix.

> [!NOTE]
> Tests implementation behavior
>
> Synthetic e measure regression consistency. Passing tests do not establish independently real-world precision, recall, or uni detection co.

Security and Responsible Use

AegisLog treats log-deri as untrusted input. Normal presentation uses terminal sanitization, HTML escaping, and best-effort common-secret redaction. Bounded ingestion limits retained e and o input handling.

Analyze only sources you are authorized to access. Sanitize examples before sharing reports or filing public issues; redaction does not guarantee that every sensiti has been removed. Install only trusted custom regex packs, which are local configuration rather than an execution-time sandbox.

Custom rule safeguards: packs are limited to 1 MB, 32 files, 100 rules per pack and 200 rules total. Patterns retain literals, anchors, character classes, dot tokens and alternatives; groups, repetition, lookarounds and backreferences are rejected before execution to avoid backtracking stalls. Escaped metacharacters remain literal. Invalid packs are reported and skipped atomically. Existing packs using unsupported constructs must be rewritten; --no-plugins disables custom rules. These restrictions do not affect built-in detectors.

The supported public product uses deterministic local analysis. AI Analyst and remote model workflows are not part of the supported public product surface. There is no automatic remediation or host-control workflow.

Read Security, Threat Model, Privacy, and No Auto-Remediation. Report through the private route described in the security policy.

Important Limitations

See Compatibility, Limitations, and the Roadmap for released scope and planned work.

Documentation

| Document | Purpose |
|---|---|
| Installation | Standalone, pipx, upgrades, and |
| User Guide | In workflows |
| Reports | Reading, printing, co, and report design |
| Commands | CLI reference |
| Demo | Synthetic demonstration workflows |
| Architecture | Pipeline and trust boundaries |
| Detection Pipeline | Detection behavior |
| Compatibility | Formats and co limits |
| Troubleshooting | Installation and runtime issues |
| Testing | guidance |
| Release Notes | Published v2.1.17 changes |
| Roadmap | Released capabilities and future priorities |
| Documentation Index | Complete documentation directory |

Design Principles

| Principle | What it means |
|---|---|
| Defensive | In e and support review |
| Local-first | Keep supported analysis and reporting local |
| Read-only | Preser logs and host configuration |
| Deterministic | Make detection behavior inspectable and testable |
| Explainable | Retain reasons, e, context, and limitations |
| Human-directed | Lea decisions with authorized people |

Contributing and Feedback

Read Contributing and the Code of Conduct. Keep changes focused and include relevant .

Report a bug or request a feature. Include your and a sanitized reproducible example. Ne credentials, customer information, or sensiti logs.

License

AegisLog is released under the MIT License.

<di="center">

<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/aegislog-readme-dark.png">
<img src="src/aegislog/assets/aegislog-logo.png" alt="AegisLog logo" width="220">
</picture>

AegisLog

LOCAL-FIRST · READ-ONLY · DETERMINISTIC · E · EXPLAINABLE

Defensive Log In · Nati · Monitoring · E Reports

MADE BY HR-PRESENTS

</div>

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source, terminal-first defensive security for local-first log analysis, monitoring, and incident investigation.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

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

使用与学习建议

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

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

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

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

免责声明

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