From 8d696908aacd2c1aa3f6c4eaf67f85ff672ac273 Mon Sep 17 00:00:00 2001 From: keirsalterego Date: Sat, 23 May 2026 23:08:42 +0530 Subject: [PATCH] docs: rewrite QUICKSTART and CONTRIBUTING for OSS contributors Both docs previously targeted operators integrating a real EDR with a managed Vyrox dashboard at app.vyrox.dev. That dashboard does not exist yet and the docs were aspirational. QUICKSTART now walks an OSS contributor from git clone to a signed execution request hitting a local proxy in about ten minutes. No EDR account, no Discord, no Python runtime, no Docker. Just cargo and bash. Covers: - Building the proxy with cargo - Running it with DRY_RUN=true (the default) so no real EDR call is possible - Signing a /execute payload with openssl + curl - Inspecting the resulting audit JSONL entry - Running the simulator in --dry-run to see the wire format - Common failure modes (401, 410, missing env) CONTRIBUTING is now an actual contributor workflow doc instead of a two-line "open a PR". Covers: - The three repositories that accept outside contributions - Branch and commit naming conventions - What we will merge and what we will not (with concrete examples from past review threads) - Local test commands per repo - Code style rules including the no-em-dash discipline that drove this rewrite - Reviewer expectations on both public and private PRs - The three documentation rules: document what is, quote the file, update docs in the same PR Cross-refs to ARCHITECTURE.md, AUDIT_CHAIN.md, ADAPTERS.md resolve once those land via PRs #8, #9, #10. --- CONTRIBUTING.md | 175 +++++++++++++++++++++++++++++------ QUICKSTART.md | 238 ++++++++++++++++++++++++++++++++---------------- 2 files changed, 307 insertions(+), 106 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e20fd57..6824134 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,45 +1,166 @@ -# Contributing to Vyrox Docs +# Contributing -## Before You Open a PR +This document tells you what we will merge, what we will not, and what +the review will check. -This repository is in alpha. Bug reports and documentation corrections are welcome from anyone. +We accept contributions to three public repositories: `vyrox-proxy`, +`vyrox-simulator`, and this docs repo. The private monorepo is not +open to outside contributors today; once a public adapter or feature +needs private-side wiring, a Vyrox maintainer takes it from there. -Code-adjacent documentation changes are accepted when they improve technical accuracy and reduce ambiguity. +## Before you start -## Development Setup +If your patch is more than a hundred lines or changes a contract, +open an issue or a draft PR first. Five minutes of "is this the +shape you want" saves a week of "we cannot merge this because the +wrong abstraction". + +If you found a vulnerability, do not open a PR. See +[`SECURITY.md`](SECURITY.md) for the disclosure path. + +## Workflow + +Standard GitHub flow on every repo: + +``` +fork ─▶ feature branch ─▶ commits ─▶ PR against main ─▶ review ─▶ squash merge +``` + +Branch names: `feat/`, `fix/`, `docs/`, +`chore/`, `test/`. The prefix matches the conventional +commit type below. + +Commit messages: Conventional Commits. + +``` +feat(adapters): add acme webhook adapter +fix(proxy): release nonce claim on audit-write failure +docs(threat-model): document A8 worker-to-bot HMAC + +Multi-line bodies are welcome. Wrap at 72. +``` + +If your PR has more than one logical change, split it. Reviewers can +hold one shape in their head at a time. Two unrelated changes in one +PR usually means one gets merged and the other gets nitpicked +forever. + +## What we will merge + +- Bug fixes with a regression test that would have caught the bug. +- New EDR adapters following the contract in + [`ADAPTERS.md`](ADAPTERS.md), with the five required failure-mode + tests. +- Documentation corrections backed by source. Quote the file and the + line you read. +- Test coverage on existing code, especially around the six critical + rules in [`ARCHITECTURE.md`](ARCHITECTURE.md#critical-rules). +- Performance improvements with benchmarks attached. We do not merge + "should be faster" without numbers. +- Refactors that reduce surface area. We do not merge refactors that + add surface area; those start as design discussions. + +## What we will not merge + +- Marketing copy presented as architecture fact. "Best in class" + belongs on a landing page, not in the docs. +- Security guidance that weakens controls. If your PR makes the HMAC + check optional, removes the replay window, or short-circuits the + audit write, the answer is no, even if the test suite passes. +- Auto-generated docs that drift from the code. The OpenAPI spec is + not the source of truth; the route handlers are. +- Code style PRs that touch hundreds of files. Run `ruff` or + `cargo fmt` in your own branch; do not ship a workspace-wide + reformat. +- Adapter PRs that violate the four rules. See `ADAPTERS.md` for + what each rule is, in concrete terms. +- Changes that introduce a hard dependency on a paid SaaS provider + without an open-source alternative documented as the default. + +## Testing + +Every PR runs the full test suite in CI. Local commands: + +For `vyrox-proxy`: ```bash -# Clone repository -git clone https://github.com/vyrox-security/vyrox-docs.git -cd vyrox-docs +cargo test +cargo clippy -- -D warnings +cargo fmt --check +``` + +For `vyrox-simulator`: + +```bash +./run-tests.sh # if present, otherwise read scenarios/ and run a few +shellcheck simulate.sh scenarios/*.sh +``` + +For `vyrox-docs`: -# Optional markdown tooling -python -m pip install --upgrade pip -python -m pip install markdownlint-cli2 || true +```bash +markdownlint-cli2 "**/*.md" # if installed ``` -## Opening an Issue +We do not ship a private-side test harness in the public docs. If +your PR touches a contract documented here, write the test against +the public surface. The reviewer will run the matching private-side +test before merging. + +## Code style + +- Plain prose in docs. No em-dashes. No AI tells. Builder voice. + Concrete file paths and function names where they help the reader. +- Rust: `cargo fmt` defaults, `cargo clippy -- -D warnings` clean. +- Python (private side): `ruff` defaults, `mypy --strict` clean, type + hints on every public function. +- Shell: bash with `set -euo pipefail`. POSIX-compatible flags where + practical (the simulator runs on macOS and Linux). + +Tests follow the production code style. A test that would not pass +review for its prose does not get merged just because it is a test. + +## Reviewer expectations + +A reviewer on a public PR will: -Use the issue templates in `.github/ISSUE_TEMPLATE`. +- Read every line of the diff. We do not LGTM blocks of code we did + not read. +- Verify the test suite covers the failure mode the change was + supposed to fix. A bug fix without a regression test is sent back. +- Check the cross-references. If your PR changes a contract + documented here, the docs change ships in the same PR. +- Push back on scope. If the PR is doing two things, the reviewer + asks you to split it. -Do not report security vulnerabilities in public issues. Follow `SECURITY.md`. +A reviewer on a private-side PR (Vyrox staff only) does the same plus +the rule-1-through-6 checklist from `ARCHITECTURE.md`. -## Opening a Pull Request +## Documentation discipline -Use `.github/PULL_REQUEST_TEMPLATE.md`. +Three rules. -Every PR must include clear validation steps and, when applicable, updates to related docs. +- **Document what is, not what should be.** If the code does X, the + docs say X. Aspirational docs lead a new contributor to look at the + code, find it disagrees, and lose trust in everything else. +- **Quote the file when you make a claim.** "The proxy verifies HMAC + in constant time (`hmac::verify_signature` in + `vyrox-proxy/src/hmac.rs:140`)." A reader who wants to confirm has + exactly one place to look. +- **Update the docs in the same PR as the code.** Doc drift is a + one-way ratchet. We close it on every PR or it grows forever. -## Code Style +## Cross-references -- Write precise technical prose -- Prefer explicit examples over vague claims -- Keep command snippets runnable -- Commit messages follow Conventional Commits (`feat`, `fix`, `docs`, `test`, `chore`) +- [`QUICKSTART.md`](QUICKSTART.md) from `git clone` to a signed alert + in about ten minutes. +- [`ADAPTERS.md`](ADAPTERS.md) for the EDR adapter contract. +- [`ARCHITECTURE.md`](ARCHITECTURE.md) for the system overview and the + six critical rules. +- [`SECURITY.md`](SECURITY.md) for the disclosure process. -## What We Will Not Merge +## Code of conduct -- Unverifiable technical claims -- Marketing language presented as architecture fact -- Security guidance that weakens controls -- Documentation-only changes that do not fix a concrete inaccuracy +See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Short version: be +direct, be technical, be respectful. We do not have time for the +opposite. diff --git a/QUICKSTART.md b/QUICKSTART.md index ca56bc4..4520405 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,116 +1,196 @@ -# Vyrox Quickstart Guide +# Quickstart -> **Time to complete:** ~15 minutes -> **Prerequisites:** CrowdStrike or SentinelOne subscription, Discord server +This walks an OSS contributor from `git clone` to a signed alert +hitting a local proxy. About ten minutes. No customer-side +credentials. No EDR account. Nothing leaves your machine. ---- +If you are an operator integrating a real EDR, see the design partner +playbook — your company contact has the link. The public docs cover +the open path only. -## What You'll Get +## What you need -- Automatic triage of every EDR alert -- Containment-ready verdicts in Discord -- Human approval workflow for CRITICAL/HIGH actions +- `git` +- `cargo` (Rust 1.75+ recommended; whatever the proxy's `Cargo.toml` + pins is fine) +- `bash`, `openssl`, `curl`. Standard on macOS and most Linuxes. +- About a hundred megabytes of disk for the Rust build cache. ---- +You do not need Python, Node, Docker, or a Discord account. -## Step 1: Get Your API Keys +## Step 1: Clone the open components -1. Log into your Vyrox dashboard at https://app.vyrox.dev -2. Navigate to **Settings → API Keys** -3. Create a new key pair: - - **Ingestion Key** — for your EDR webhook - - **HMAC Secret** — for request signing +Three repositories. Each clones into its own directory. ---- +```bash +git clone https://github.com/vyrox-security/vyrox-proxy.git +git clone https://github.com/vyrox-security/vyrox-simulator.git +git clone https://github.com/vyrox-security/vyrox-docs.git +``` -## Step 2: Configure CrowdStrike Webhook +The docs repo is this one. The other two are MIT licensed. -1. Open CrowdStrike Falcon console -2. Go to **Settings → Integrations → Webhooks** -3. Add new webhook: - - **URL:** `https://api.vyrox.dev/webhook/crowdstrike` - - **Authentication:** Custom header - - Key: `X-Vyrox-Signature` - - Value: HMAC-SHA256 of request body using your HMAC Secret -4. Select event types: - - `_detection_summary_event` (required) - - `incident_summary_event` (optional) +## Step 2: Build the proxy -**Note:** If using Falcon Next-Gen AV, add the webhook to **Cloud Matches** in Sensor Policy. +```bash +cd vyrox-proxy +cargo build +``` ---- +First build pulls the dependency tree (about ninety crates). Future +builds are quick. The final binary is at +`target/debug/vyrox-proxy`. -## Step 3: Configure SentinelOne Webhook +## Step 3: Run the proxy with DRY_RUN -1. Open SentinelOne console -2. Go to **Settings → Integrations → Webhooks** -3. Add new webhook: - - **URL:** `https://api.vyrox.dev/webhook/sentinelone` - - **Authentication:** Bearer token (use your Ingestion Key) -4. Select: - - `Threats` (all severities) - - `Agents` (status changes) +The proxy refuses to start without a HMAC secret. Generate one for +local use only; do not reuse it anywhere else. ---- +```bash +export VYROX_HMAC_SECRET=$(openssl rand -hex 32) +export AUDIT_LOG_PATH=./local-audit +export DRY_RUN=true +export BIND_ADDR=127.0.0.1:3000 -## Step 4: Install Discord Bot +mkdir -p "$AUDIT_LOG_PATH" +./target/debug/vyrox-proxy +``` -1. Open your Vyrox dashboard -2. Go to **Settings → Discord** -3. Click **Add to Server** -4. Select your Discord server and authorize -5. Run `/vyrox register` in your server to complete setup +The proxy listens on `127.0.0.1:3000`. `DRY_RUN=true` is the default +so even if you forget to set it, the proxy will not call any EDR API. ---- +Check it is alive in another shell: -## Step 5: Verify Integration +```bash +curl -s http://127.0.0.1:3000/health +# {"status":"ok"} +``` -Trigger a test alert in your EDR: -1. Open terminal on a monitored endpoint -2. Run: `powershell -Command "Invoke-WebRequest -Uri http://example.com"` +## Step 4: Fire a signed execution request -Within 30 seconds, Vyrox should ingest the event as a LOW severity alert. By default, LOW alerts are auto-dismissed and won't appear in Discord (see behavior table below). If you want a visible Discord message for verification, use Step 6 instead. +The proxy accepts `POST /execute` with an HMAC-SHA256 signed body. +Smallest valid request: ---- +```bash +SECRET="$VYROX_HMAC_SECRET" +TS=$(date +%s) +BODY=$(cat <