diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..48d8417 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**johnellisATlinuxDOTcom**. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2593653 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# Contributing to Cairn OBS + +Thanks for your interest in contributing to **Cairn OBS** — open-core, Kubernetes-native log aggregation and observability. Contributions of all kinds are welcome: bug reports, feature requests, code, documentation, and testing. + +## Code of Conduct + +By participating in this project you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md). Be constructive, be patient with newcomers, and keep discussion focused on the project. + +## Before You Start + +- **Read [`docs/architecture.md`](docs/architecture.md) before changing any component.** The storage/query split in particular is deliberate: ClickHouse serves analytics, Tantivy serves full-text, and one query language compiles to a single plan across both. Changes that blur that line need discussion first. +- **PostgreSQL is control-plane only** — dashboards, panels, alert rules and state, notification targets, delivery log. Log data never touches it. That boundary is about transactional read-modify-write, not preference. +- **`enterprise/` is a separate Go module that core never imports from.** Since the Phase 6 relicensing that boundary is architectural rather than legal — it keeps core buildable and deployable standalone, and keeps tenant resolution server-side. Please don't reach across it. +- **The whole repository is AGPLv3, `enterprise/` included.** There is no feature gate and no paid tier holding code back. Anything you contribute is distributed under AGPL-3.0, including for hosted/SaaS deployments. + +## How to Contribute + +### Reporting Bugs + +Search [existing issues](https://github.com/LINUXexpert-org/cairnobs/issues) first. When filing a bug, include: + +- A clear, descriptive title +- Steps to reproduce, and expected vs. actual behaviour +- **Which component** — `agent`, `ingest`, `api`, `search`, `alerting`, `enterprise`, `web`, `cli`, `deploy` +- How you're running it: `docker compose`, the Helm chart, or something else, and which `COMPOSE_PROFILES` if compose +- Relevant logs from the component, and the query if the bug is in query behaviour +- Whether it reproduces from a clean `docker compose down -v && docker compose up` + +Two areas are known to be unverified rather than broken — Phase 4 (RBAC and tenant isolation) beyond its audit-logging guarantees, and the Windows agent, which has never run on real Windows. Both are called out in the README. Reports against them are welcome; please say that's what you were testing. + +### Suggesting Features + +Open an issue describing: + +- The problem you're trying to solve, not just the solution +- Where it sits relative to the architecture — which component owns it, and whether it crosses the storage/query split or the `enterprise/` boundary +- Roughly what it costs at volume, if it touches the ingest or query path. Cost-per-GB is a design goal, not an afterthought. + +For larger changes, open an issue to discuss the approach **before** submitting a pull request — this saves everyone time if the direction needs adjusting. + +### Submitting Pull Requests + +1. **Fork** the repository and create your branch from `main`. +2. **Name your branch** descriptively, e.g. `fix/tantivy-merge-stall` or `feat/alert-absence-rules`. +3. **Keep PRs focused** — one logical change per PR. +4. **Write clear commit messages** describing what changed and why. The "why" matters more than the "what"; the diff already says what. +5. **Add or update tests** in the component you touched. Each top-level directory carries its own unit tests. +6. **Update documentation** if your change affects setup, configuration, the query language, or user-facing behaviour. +7. **Open the pull request** against `main`, with a summary, any related issue numbers, screenshots for UI changes, and what you actually ran to check it. + +Please sign off your commits: `git commit -s` adds the `Signed-off-by` trailer, which is a statement that you have the right to submit the work under this project's licence. GitHub enforces it for commits made through the web interface; for everything else it is asked for rather than blocked. + +### CI + +Three workflows run on a pull request: + +- **License compliance** — the dependency licence inventory under `docs/compliance/` must stay accurate. A new dependency with an incompatible licence fails the build. +- **Security scan** +- **Web route check** — the route lists are kept honest against the actual SvelteKit routes, so an unrouted path answers 404 rather than rendering something. + +### Code Style + +- Match the existing formatting and naming conventions in the component you're editing. It's a polyglot tree: Rust in `agent` and `search`, Go in `ingest`, `api`, `alerting`, `enterprise` and `cli`, TypeScript and Svelte in `web`. +- `cargo fmt` and `gofmt` output is the standard; don't hand-format around them. +- Prefer clarity over cleverness. This is infrastructure people page on. +- Comment the non-obvious, especially anything about query planning, tenant scoping, or the exactly-once/at-least-once properties of the ingest path — those are easy to get subtly wrong and expensive to debug later. + +### Development Setup + +1. Clone your fork: + ```bash + git clone https://github.com/YOUR-USERNAME/cairnobs.git + cd cairnobs + ``` +2. Bring the stack up: + ```bash + docker compose up + ``` + The web UI is on and the API on `:8080`; alerting is on `:8081` and enterprise auth on `:8082`. The agent connects to ingest over mTLS gRPC on `:4317`. `search` publishes no host port — it's reachable only on the compose network. +3. `COMPOSE_PROFILES` in `.env` selects the query-serving binary: `single-tenant` (default) or `enterprise` for the multi-tenant path. They're mutually exclusive, the same choice Helm's `enterprise.enabled` flag makes for a real cluster. Override per invocation with `COMPOSE_PROFILES=enterprise docker compose up`. +4. Exercise the path you changed end to end — for ingest or query work that means getting a real log line in and querying it back, not just a passing unit test. + +## Review Process + +- A maintainer will review your PR and may request changes. +- Please respond to review feedback in a timely manner; PRs with no activity for an extended period may be closed, and can be reopened once updated. +- Once approved, a maintainer will merge the PR. + +## Reporting Security Issues + +Please **do not** open a public issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for how to report privately, and for what is in and out of scope — cross-tenant data exposure is the class we most want to hear about. + +## Questions? + +If you're unsure whether something is a good fit, open an issue and ask, or start a [discussion](https://github.com/LINUXexpert-org/cairnobs/discussions). Discussion before you invest time in a PR is welcome. + +Thanks again for helping improve Cairn OBS. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..093eba5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,66 @@ +# Security Policy + +## Supported Versions + +Cairn OBS is under active development. Security fixes are applied to the latest state of the `main` branch. Older tags/releases are not guaranteed to receive backported fixes. + +| Version | Supported | +| --------------- | ------------------ | +| `main` (latest) | :white_check_mark: | +| Older releases | :x: | + +## Reporting a Vulnerability + +**Please do not open a public GitHub issue for security vulnerabilities.** Public issues are visible to everyone, including potential attackers, before a fix is available. + +Instead, report security issues privately by emailing: + +**johnellisATlinuxDOTcom** + +Please include as much of the following as you can: + +- A description of the vulnerability and its potential impact +- Steps to reproduce, or a proof-of-concept +- The commit of Cairn OBS affected +- Which component it lives in — `agent`, `ingest`, `api`, `search`, `alerting`, `enterprise`, `web`, `cli` or the deployment charts — since they are separate binaries with separate trust boundaries +- Whether it needs an authenticated session, and if so at what role + +### What to Expect + +- **Acknowledgment:** You should receive a response within a few days confirming the report was received. +- **Assessment:** The issue will be triaged and its severity assessed. +- **Fix & disclosure:** Once a fix is ready it will be published on `main`. We'll coordinate with you on public disclosure timing and credit, if you'd like to be credited. + +### Scope + +In scope: + +- Authentication, session handling and token issuance in the control plane +- **Cross-tenant data exposure** — anything that lets a query, dashboard, alert rule or API call read data belonging to another tenant. This is the highest-severity class for this project. +- RBAC bypass: performing an action the signed-in role does not carry +- Query-language injection reaching ClickHouse or Tantivy, including through the SQL escape hatch, and anything that escapes the compiler's intended plan +- Log injection or parser flaws in the agent or ingest pipeline that lead to code execution, resource exhaustion, or forged records +- Credential or token exposure in logs, API responses, or the web bundle +- Dependency vulnerabilities that are actually exploitable in Cairn OBS's usage + +Out of scope: + +- The public demo's `demo` account credential, which is deliberately published — it is prefilled on the login page and baked into the web bundle, against a database that is wiped and reseeded on a schedule +- Findings against a deployment the reporter does not operate or have permission to test +- Vulnerabilities in ClickHouse, Redpanda, PostgreSQL or other third-party components with no demonstrated impact on Cairn OBS — please report those upstream +- Missing hardening with no demonstrated impact, and issues requiring physical access or an already-compromised host + +### A note on unverified components + +Two parts of the tree are known not to have been exercised, and are documented as such in the README: + +- **Phase 4** (RBAC, tenant isolation, per-tenant ClickHouse) compiles and is tested, but only its audit-logging guarantees were confirmed against a live database. +- **The Windows agent** (`EvtSubscribe`, ETW, service registration) has never run on real Windows. + +Reports against these are welcome and useful. Please say which one you were testing, so the finding is not mistaken for a regression in a verified path. + +## Disclosure Policy + +We follow coordinated disclosure: please give us a reasonable window to investigate and release a fix before any public disclosure. In turn, we'll keep you updated on progress and won't leave you waiting indefinitely. + +Thank you for helping keep Cairn OBS and the people running it safe.