From 3cd141e93b8fecf71666f33f3e624016fd2e5d9f Mon Sep 17 00:00:00 2001 From: stacknil Date: Thu, 19 Mar 2026 00:29:29 +0800 Subject: [PATCH 1/2] docs: tighten README and add MIT license --- AGENTS.md | 51 ++++++++++++--------------------------------------- LICENSE | 21 +++++++++++++++++++++ README.md | 24 ++++-------------------- 3 files changed, 37 insertions(+), 59 deletions(-) create mode 100644 LICENSE diff --git a/AGENTS.md b/AGENTS.md index b85ed4b..f34952d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,41 +1,14 @@ # AGENTS.md -## Project -LogLens is a defensive C++20 CLI for parsing Linux authentication logs and generating structured detection reports. - -## Priorities -1. Working MVP first -2. Clean modular C++20 -3. Safe public-repo content -4. Reproducible build and tests -5. Clear README and docs - -## Constraints -- Do not add offensive or exploitation functionality -- Do not use real IPs, secrets, usernames, or private infrastructure identifiers -- Prefer standard library over third-party dependencies -- Keep file structure simple -- Avoid unnecessary templates or meta-programming -- Avoid heavy regex-only designs if a clearer parser is possible -- Keep detection rules centralized and configurable - -## Code style -- C++20 -- Readable names -- Small functions -- Comments only where they add real value -- Fail gracefully on malformed log lines - -## Repository rules -- Always update README when adding user-visible features -- Add or update tests for parser and detector changes -- Preserve public-safe placeholders like 203.0.113.x and example-host -- Do not introduce large unrelated refactors - -## Task behavior -When given a task: -1. inspect repository state -2. explain plan briefly -3. implement in small steps -4. run build/tests if available -5. summarize created/modified files and remaining issues +## LogLens Repo Rules + +- Keep the repository defensive and public-safe. Do not add offensive, exploitation, persistence, or live attack functionality. +- Use only safe placeholders such as `203.0.113.x` and `example-host`. Never add real IPs, usernames, secrets, or private identifiers. +- Prefer standard C++20 and the standard library. Keep code modular, readable, and easy to extend. +- Keep detection rules centralized and configurable. Avoid large unrelated refactors. +- Fail gracefully on malformed log lines. +- Update README or docs for user-visible changes. +- Tests are required for code changes. Add or update parser/detector tests and run available build/tests when possible: + `cmake -S . -B build` + `cmake --build build` + `ctest --test-dir build --output-on-failure` diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3d2b178 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 stacknil + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index a023bef..beabb50 100644 --- a/README.md +++ b/README.md @@ -7,27 +7,11 @@ C++20 defensive log analysis CLI for Linux authentication logs, with parser cove It parses `auth.log` / `secure`-style syslog input and `journalctl --output=short-full`-style input, normalizes authentication evidence, applies configurable rule-based detections, and emits deterministic Markdown and JSON reports. -## Why this project exists +## Overview -Many small security tools can detect a handful of known log patterns. Fewer tools make their parsing limits visible. +LogLens is a defensive, public-safe repository for log parsing and detection engineering. It focuses on parser observability as well as detections: unsupported lines are surfaced as telemetry instead of being silently ignored. -LogLens is designed around three ideas: - -- detection engineering over offensive functionality -- parser observability over silent failure -- repository discipline over throwaway scripts - -The project reports suspicious login activity while also surfacing parser coverage, unknown-line buckets, CI status, and code scanning hygiene. - -## Scope - -LogLens is a defensive, public-safe repository. -It is intended for log parsing, detection experiments, and engineering practice. -It does not provide exploitation, persistence, credential attack automation, or live offensive capability. - ---- - -LogLens is a defensive C++20 CLI that parses Linux authentication logs and produces concise Markdown and JSON reports for suspicious authentication activity. The project is intended for portfolio-grade detection engineering work, not offensive security or attack automation. +The project does not provide exploitation, persistence, credential attack automation, or live offensive capability. ## Repository Checks @@ -36,7 +20,7 @@ LogLens includes two minimal GitHub Actions workflows: - `CI` builds and tests the project on `ubuntu-latest` and `windows-latest` - `CodeQL` runs GitHub code scanning for C/C++ on pushes, pull requests, and a weekly schedule -Both workflows are intended to stay stable enough to require on pull requests to `main`. The repository hardening note is in [`docs/repo-hardening.md`](./docs/repo-hardening.md). +Both workflows are intended to stay stable enough to require on pull requests to `main`. The repository hardening note is in [`docs/repo-hardening.md`](./docs/repo-hardening.md), and vulnerability reporting guidance is in [`SECURITY.md`](./SECURITY.md). ## Threat Model From feb8a232ece9dff3f7a780085ea6896ae116fc5c Mon Sep 17 00:00:00 2001 From: stacknil Date: Thu, 19 Mar 2026 00:44:19 +0800 Subject: [PATCH 2/2] docs: prepare v0.1.0 release notes --- CHANGELOG.md | 10 ++++++++++ README.md | 18 ++++++++++++++++-- docs/release-v0.1.0.md | 16 ++++++++++++++++ 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/release-v0.1.0.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2995156 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## v0.1.0 + +- Added parser support for `syslog_legacy` and `journalctl_short_full` authentication log input. +- Added rule-based detections for SSH brute force, multi-user probing, and bursty sudo activity. +- Added parser coverage telemetry, including parsed/unparsed counts and unknown-pattern buckets. +- Added repository automation and hardening with CI, CodeQL, pinned GitHub Actions, security policy, and Dependabot for workflow updates. diff --git a/README.md b/README.md index beabb50..5f6031e 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,23 @@ C++20 defensive log analysis CLI for Linux authentication logs, with parser cove It parses `auth.log` / `secure`-style syslog input and `journalctl --output=short-full`-style input, normalizes authentication evidence, applies configurable rule-based detections, and emits deterministic Markdown and JSON reports. -## Overview +## Project Status -LogLens is a defensive, public-safe repository for log parsing and detection engineering. It focuses on parser observability as well as detections: unsupported lines are surfaced as telemetry instead of being silently ignored. +LogLens is an MVP / early release. The repository is stable enough for public review, local experimentation, and extension, but the parser and detection coverage are intentionally narrow. + +## Why This Project Exists + +Many small security tools can detect a handful of known log patterns. Fewer tools make their parsing limits visible. + +LogLens is built around three ideas: + +- detection engineering over offensive functionality +- parser observability over silent failure +- repository discipline over throwaway scripts + +## Scope + +LogLens is a defensive, public-safe repository for log parsing and detection engineering. Unsupported lines are surfaced as telemetry instead of being silently ignored. The project does not provide exploitation, persistence, credential attack automation, or live offensive capability. diff --git a/docs/release-v0.1.0.md b/docs/release-v0.1.0.md new file mode 100644 index 0000000..e122bc1 --- /dev/null +++ b/docs/release-v0.1.0.md @@ -0,0 +1,16 @@ +# LogLens v0.1.0 + +LogLens v0.1.0 is the first public MVP release of the repository. + +## Highlights + +- Parses Linux authentication logs in both `syslog_legacy` and `journalctl_short_full` modes. +- Normalizes authentication evidence and applies configurable detections for SSH brute force, multi-user probing, and sudo burst activity. +- Reports parser coverage telemetry so unsupported lines are visible instead of silently ignored. +- Ships with deterministic Markdown and JSON reports, unit tests, CI, CodeQL, and baseline repository hardening. + +## Notes + +- This release is intentionally narrow in scope and focused on a clean, public-safe baseline. +- Parser coverage is limited to a small set of common `sshd`, `sudo`, and `pam_unix` patterns. +- Repository protections are designed for PR-based development with CI and CodeQL gating merges into `main`.