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/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/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 06c0387..d90bafb 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,20 @@ 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 +## Project Status + +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 designed around three ideas: +LogLens is built 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. @@ -33,7 +35,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 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`.