coffey-labs/cairnobs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add the community health files ahead of going public

Browse Source 
The repository has carried only a LICENSE and a README, which scores 42%
on GitHub's community profile against ihasmail's 85% and, more to the
point, leaves someone who finds a vulnerability with nowhere to send it
but a public issue.

SECURITY.md is the one that matters. It names cross-tenant data exposure
as the highest-severity class, since that is the guarantee this project
actually sells and the one hardest to be sure of. It also puts the two
knowingly unverified areas in front of a reporter -- Phase 4 beyond its
audit-logging guarantees, and the Windows agent, which has never run on
Windows -- so a finding there is not mistaken for a regression in a path
that was ever verified. And it declares the demo credential out of scope
explicitly: it is published on purpose, prefilled on the login page and
baked into the web bundle, so a report about it costs everyone time.

CONTRIBUTING.md is written for this tree rather than adapted loosely from
the other one: the storage/query split, PostgreSQL being control-plane
only, the enterprise/ module boundary core never imports across, and the
fact that the whole repository is AGPLv3 with no feature gate. Setup is
the compose path from the README, including COMPOSE_PROFILES, so the two
cannot drift into disagreeing.

CODE_OF_CONDUCT.md is Contributor Covenant 2.0, copied from ihasmail with
one fix: that copy never filled in the contact placeholder, so its
reporting sentence ends at "responsible for enforcement at ." -- a code of
conduct with no way to report anything. Worth fixing there too.

Signed-off-by: John Coffey <[email protected]>
This commit is contained in:
jcoffey-dev
2026-08-29 00:17:48 -07:00
parent 7b690ad694
commit 233e0779b7
3 changed files with 291 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODE_OF_CONDUCT.md
+128
View File
@@ -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.
CONTRIBUTING.md
+97
View File
@@ -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 <http://localhost:3000> 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.
SECURITY.md
+66
View File
@@ -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.