Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

docs(launch): in-repo launch kit + press kit (v8 G1)

Beenu Arora081b0e880aaa
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fde0a2b4..e4f63ee22 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **v8 G1 — launch kit (ships in-repo with the code).** New `marketing/launch/`:
+ a Show HN draft centered on `npx aisoc triage --demo`, a 90-second demo-video
+ shot list (CLI wow → replay permalink → self-play → mesh stats), Product Hunt
+ assets, six technical blog outlines (one per phase, each ending in a
+ reproducible command), and a **category-level** comparison dossier vs.
+ closed-source AI SOC products — deliberately **without naming any competitor**
+ (per project policy), with every AiSOC-side claim linked to code or a CI gate.
+ Plus a `docs/press/` kit (boilerplate, fast facts, logo kit, naming). All
+ materials are written to two rules — no superlatives, and synthetic-vs-measured
+ always labelled — and are linked from `CONTRIBUTING.md` for community
+ amplification. The launch-kit README points every claim back to the benchmark
+ page + claim-to-gate matrix so nothing ungated gets published.
- **v8 W4 — GitHub-native distribution (`aisoc-action`).** New
`packages/aisoc-action/` (Node20 JS action): triages the repo's **own**
security signals — Dependabot alerts, CodeQL/code-scanning findings, and
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e75ec7063..ba68f9bda 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -324,6 +324,17 @@ Please use the GitHub issue tracker. Include:
- Expected vs actual behavior
- Relevant logs
+## Help spread the word
+
+Amplification is a contribution too. The in-repo [launch kit](marketing/launch/)
+has ready-to-use materials — a Show HN draft, a demo-video shot list, Product
+Hunt copy, six technical blog outlines (each ending in a reproducible command),
+and a category-level comparison dossier — plus a [press kit](docs/press/) with
+boilerplate and the logo kit. Everything is written to two rules: no
+superlatives, and synthetic-vs-measured is always labelled. If you write about
+AiSOC, verify each claim against the [benchmark page](apps/docs/docs/benchmark.md)
+first.
+
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
diff --git a/docs/press/README.md b/docs/press/README.md
new file mode 100644
index 000000000..eb632c42d
--- /dev/null
+++ b/docs/press/README.md
@@ -0,0 +1,55 @@
+# AiSOC press kit
+
+Everything a writer, conference organizer, or partner needs to represent AiSOC
+accurately. Please keep quotes and stats consistent with the
+[benchmark page](../../apps/docs/docs/benchmark.md).
+
+## Boilerplate
+
+**One sentence:**
+
+> AiSOC is an open-source, self-hostable AI security operations center whose
+> agent decisions are logged step-by-step and replayable, gated by a public
+> eval harness, and MIT-licensed.
+
+**One paragraph:**
+
+> AiSOC is an open-source (MIT) AI SOC that ingests security events, correlates
+> them, runs AI-driven investigation, and surfaces the result in a SOC console.
+> Unlike closed-source AI SOC products, the agent and the substrate are open:
+> every prompt, tool call, piece of evidence, and rationale is stored in an
+> Investigation Ledger and replayable, and a public eval harness gates every
+> change. You can try it in 60 seconds with `npx aisoc triage --demo` — no
+> account, no Docker, no API key — or self-host the full stack so no data leaves
+> your perimeter.
+
+## Fast facts
+
+- **License:** MIT
+- **Try it:** `npx aisoc triage --demo` (deterministic, offline, <1s)
+- **Live demo:** https://tryaisoc.com
+- **Source:** https://github.com/beenuar/AiSOC
+- **Orchestrator:** ~600-line LangGraph in `services/agents/`
+- **Default response posture:** copilot / dry-run (human approval required)
+- **Data residency:** self-hosted; hosted-LLM evidence pseudonymized by default; air-gapped local-model path available
+
+## Logo kit
+
+Source marks live in the repo (SVG, scalable):
+
+- Logo mark: [`apps/web/public/logo-mark.svg`](../../apps/web/public/logo-mark.svg)
+- Social/OG card: [`apps/web/public/og-image.svg`](../../apps/web/public/og-image.svg)
+
+Usage: don't recolor the mark; keep clear space equal to the mark's height on
+all sides; on dark backgrounds use the mark as-is.
+
+## Naming
+
+- Product name is **AiSOC** (capital A-i-S-O-C). Not "AISOC", not "Aisoc".
+- Not affiliated with, and not to be compared by name to, any specific
+ commercial vendor in our materials.
+
+## Contact
+
+Open a [GitHub Discussion](https://github.com/beenuar/AiSOC/discussions) for
+press or partnership inquiries.
diff --git a/marketing/launch/README.md b/marketing/launch/README.md
new file mode 100644
index 000000000..160fdfb5c
--- /dev/null
+++ b/marketing/launch/README.md
@@ -0,0 +1,35 @@
+# AiSOC launch kit
+
+In-repo launch materials so they ship and version with the code. Everything
+here is written to two rules:
+
+1. **No superlatives, only sourced claims.** The audience is security
+ engineers; overreach burns trust.
+2. **Synthetic vs. measured is always labelled.** The `--demo` fixture is a
+ deterministic 200-alert synthetic set; substrate metrics come from the
+ CI-gated [eval harness](../../apps/docs/docs/benchmark.md). Never present the
+ demo's fixture numbers as measured production accuracy.
+
+## Contents
+
+| File | What it is |
+|---|---|
+| [`show-hn.md`](./show-hn.md) | Show HN post draft, centered on `npx aisoc triage --demo`. |
+| [`demo-video-shotlist.md`](./demo-video-shotlist.md) | 90-second demo video shot list. |
+| [`product-hunt.md`](./product-hunt.md) | Product Hunt tagline, description, first comment, gallery list. |
+| [`blog-outlines.md`](./blog-outlines.md) | Six technical blog outlines, each ending in a reproducible command. |
+| [`comparison-dossier.md`](./comparison-dossier.md) | Category-level comparison vs. closed-source AI SOC products (sourced, no vendor names). |
+| [`../../docs/press/README.md`](../../docs/press/README.md) | Press kit: boilerplate, logo kit, fast facts. |
+
+## Ground truth for every claim
+
+Before publishing anything here, re-check it against:
+
+- The benchmark page: `apps/docs/docs/benchmark.md` and the public scoreboard
+ `apps/docs/docs/benchmark-scoreboard.mdx`.
+- The claim-to-gate matrix: `docs/audit/CLAIM_TO_GATE_MATRIX.md` (every product
+ claim maps to a CI gate).
+- The detection truth table: `docs/detections/truth-table.md` (executable vs.
+ quarantined rule counts).
+
+If a claim isn't backed by one of those, cut it or soften it to what is.
diff --git a/marketing/launch/blog-outlines.md b/marketing/launch/blog-outlines.md
new file mode 100644
index 000000000..f7535f92e
--- /dev/null
+++ b/marketing/launch/blog-outlines.md
@@ -0,0 +1,67 @@
+# Six technical blog outlines
+
+Each maps to a shipped phase and ends with a reproducible command a reader can
+run. Keep them engineering-first; the CTA is "run this", not "book a demo".
+
+---
+
+## 1. "A verdict on every alert in 60 seconds, offline" (W1 — the CLI)
+
+- The problem: time-to-value for a SOC tool is measured in days.
+- The wedge: `npx aisoc triage --demo` — deterministic, zero-dep, <1s.
+- How the verdict engine works: the additive weight stack, the four bands, the
+ [0.05, 0.95] clamp, and why it's deliberately not a black box.
+- Parity: how the TS port is pinned to the Python server via a test.
+- The BYO-key LLM band, and why it's never proxied.
+- **Run it:** `npx aisoc triage --demo`
+
+## 2. "Publishing a redacted investigation replay" (W3 — the screenshot loop)
+
+- Why analysts don't share their work: it leaks environment detail.
+- The pre-publish redaction diff: what becomes `HOST_1` / `USER_2`, what stays
+ (public IOCs, ATT&CK techniques) and why.
+- The immutability guarantee (DB trigger) and the non-RLS public read.
+- The OG image pipeline for unfurls.
+- **Run it:** publish a demo run, open `tryaisoc.com/r/demo-lockbit`.
+
+## 3. "Grading your ATT&CK coverage in the browser" (W2 — the free tools)
+
+- Coverage as a self-check, not an audit — and being honest about that.
+- Parsing Sigma tags client-side; the prevalence-ranked catalog.
+- The A–F grade and the "top uncovered" list as a shareable artifact.
+- SEO as distribution: 30 programmatic format-pair pages.
+- **Run it:** paste your rules at `tryaisoc.com/tools/coverage`.
+
+## 4. "A GitHub Action that triages your own security alerts" (W4)
+
+- Dependabot/CodeQL/secret-scanning noise, and prioritization by exploitability.
+- Reusing the exact verdict engine (vendored, sync-gated) in CI.
+- Idempotent PR comments + the weekly posture digest with an A–F grade.
+- Why the deterministic floor matters in CI (no key, nothing leaves the runner).
+- **Run it:** add `uses: beenuar/aisoc-action@v1` to a workflow.
+
+## 5. "The SOC that attacks itself every night" (P2 — self-play purple team)
+
+- From test-runner to continuous adversary: LLM-planned chains from Atomic Red
+ Team + Caldera, scoped to a lab by a hard asset-tag guard (not a prompt).
+- The closed loop: emit telemetry → defense responds → score detected/missed →
+ auto-file eval-gated detection proposals for every miss.
+- Publishing the weekly self-play scoreboard: turning our own defense
+ improvement into a public time series.
+- **Run it:** `pnpm aisoc:selfplay` (canned 5-stage campaign, ~3 min).
+
+## 6. "Every install makes every other install smarter" (P1 — the mesh)
+
+- The one network effect a closed vendor can't credibly copy: it needs your
+ trust in the code.
+- What's shared (hashed IOC sightings, verdict signatures) and what never is
+ (entities, free text) — the k-anonymity threshold and per-instance signing.
+- `mesh preview`: see exactly what would leave before enabling anything.
+- The measured FP-suppression lift with mesh on vs. off, on the eval harness.
+- **Run it:** `mesh preview` on your instance; read `docs/architecture/mesh.md`.
+
+---
+
+**Rule:** before publishing any post, verify its headline claim against
+`apps/docs/docs/benchmark.md` and the claim-to-gate matrix. If a number isn't
+gated, don't print it.
diff --git a/marketing/launch/comparison-dossier.md b/marketing/launch/comparison-dossier.md
new file mode 100644
index 000000000..441070515
--- /dev/null
+++ b/marketing/launch/comparison-dossier.md
@@ -0,0 +1,58 @@
+# Comparison dossier — AiSOC vs. closed-source AI SOC products
+
+> **House rule:** this is a category-level comparison. We do **not** name
+> specific competitors — AiSOC is an open-source project and naming vendors we
+> can't fairly and verifiably characterize invites exactly the overreach we
+> criticize. Every AiSOC-side claim below links to code or a CI gate. Every
+> "closed-source" row is a structural statement about the proprietary,
+> cloud-only category, not a claim about any one product.
+
+## The one-line framing
+
+Closed-source AI SOC vendors ship working products. AiSOC's contribution is
+making the agent itself open, the per-step decision trail readable, and the
+substrate gated by a public eval harness on every PR. If those three properties
+matter to you, AiSOC is structurally different; if they don't, a managed vendor
+may be a fine choice.
+
+## Structural comparison
+
+| Dimension | AiSOC | Closed-source AI SOC (category) |
+|---|---|---|
+| License | MIT (agent + substrate + console) | Proprietary |
+| Deployment | Self-host anywhere; data stays in your perimeter | Vendor cloud (typically) |
+| Agent decision trail | Public Investigation Ledger: prompt, tool call, evidence, rationale, per step; replayable | Not published |
+| Eval transparency | Public harness gates every PR; synthetic-vs-measured labelled | Not published |
+| Verdict engine | Readable, deterministic-by-default scoring you can fork | Opaque |
+| Time-to-first-verdict | `npx aisoc triage --demo`, <1s, no key | Sales cycle → onboarding |
+| Data egress control | No callbacks; hosted-LLM evidence pseudonymized by default; air-gapped local-model path | Vendor-defined |
+| Cost | $0 self-host | Per-seat / per-GB / enterprise |
+
+## AiSOC claims — each backed by code or a gate
+
+| Claim | Evidence |
+|---|---|
+| Deterministic verdict engine, no LLM required | `services/agents/app/confidence/scoring.py`; CLI parity test `packages/aisoc-lite/src/verdict/stages.test.ts` |
+| Every agent step is logged + replayable | `services/api/app/models/investigation.py`; ledger API + `/r/<slug>` public replay |
+| Public eval harness gates PRs | `scripts/run_evals.py`; `.github/workflows/ci.yml` `p1-eval` job; `apps/docs/docs/benchmark.md` |
+| Copilot/dry-run default for response | autonomy policy; `AISOC_MATURITY_TIER`; `docs/audit/CLAIM_TO_GATE_MATRIX.md` |
+| Detection corpus honesty | `docs/detections/truth-table.md` (executable vs. quarantined counts) |
+| Pseudonymized egress / air-gapped path | `services/agents/app/privacy/redactor.py`; `docs/trust/data-flows.md` |
+
+## What AiSOC does NOT claim (say this out loud)
+
+- It is not claiming higher live-LLM accuracy than any vendor — the live-LLM
+ benchmark is a funded weekly job, not a per-PR gate; the per-PR gate is the
+ deterministic tier.
+- It does not auto-remediate by default — response is copilot/dry-run until an
+ operator configures autonomy per action.
+- The `--demo` fixture numbers are synthetic and demonstrate the mechanism, not
+ measured production performance.
+
+## How to use this dossier
+
+For a landing-page comparison table, use the "Structural comparison" rows
+verbatim — they're defensible without naming anyone. For analyst / procurement
+conversations, lead with the "claims backed by a gate" table: the differentiator
+isn't a feature checkbox, it's that every claim is falsifiable by running the
+repo.
diff --git a/marketing/launch/demo-video-shotlist.md b/marketing/launch/demo-video-shotlist.md
new file mode 100644
index 000000000..070108446
--- /dev/null
+++ b/marketing/launch/demo-video-shotlist.md
@@ -0,0 +1,25 @@
+# 90-second demo video shot list
+
+Goal: show the wow, then the depth, in 90 seconds. Screen-only, no talking-head
+required. Captions on. Each shot is a real command against `main`.
+
+| # | Time | Shot | On screen | Caption |
+|---|------|------|-----------|---------|
+| 1 | 0:00–0:12 | Cold terminal | `npx aisoc triage --demo` typed and run | "No install. No key. No Docker." |
+| 2 | 0:12–0:22 | Verdict table + headline fills in | The table + "triaged 200 alerts: 12 TP, 171 FP suppressed (85.5% noise), 17 need review — in 0.1s" | "A verdict on every alert, in under a second." |
+| 3 | 0:22–0:30 | `npx aisoc triage --demo --share` → open the SVG card | The report card | "Share the result — aggregate only, nothing leaks." |
+| 4 | 0:30–0:45 | Browser: open a public replay permalink `/r/demo-lockbit` | Animated playback: timeline scrubber, evidence cards, attack graph growing, verdict stamp | "Every agent decision is logged — and replayable." |
+| 5 | 0:45–0:58 | Scrub the replay timeline; hover a step to show the rationale | Step rationale + confidence | "Prompt, tool call, evidence, rationale — per step." |
+| 6 | 0:58–1:12 | Terminal: `pnpm aisoc:selfplay` (self-play campaign) — sped up | 5-stage attack chain running; detections firing; DAC proposals auto-filed | "It attacks itself nightly and files detections for every miss." |
+| 7 | 1:12–1:24 | Browser: the mesh/network stats page | Instances connected, signatures shared, community FP-suppression lift | "Every install makes every other install smarter." |
+| 8 | 1:24–1:30 | Repo landing + star button | github.com/beenuar/AiSOC | "MIT. Self-hostable. github.com/beenuar/AiSOC" |
+
+## Production notes
+
+- Record shot 1–3 with `asciinema` or a clean terminal at 16–18pt; the demo is
+ deterministic so re-takes are identical.
+- Shots 6–7 depend on P2 (self-play) and P1 (mesh) being merged; until then,
+ swap in the docker-compose demo landing on `/cases/INC-RT-001?tab=ledger`.
+- Keep total assets under `apps/web/public/demo/`; the README hero references
+ `demo/hero.gif` + the `.mp4`.
+- No fabricated dashboards — every screen must be a real run.
diff --git a/marketing/launch/product-hunt.md b/marketing/launch/product-hunt.md
new file mode 100644
index 000000000..780ca0e62
--- /dev/null
+++ b/marketing/launch/product-hunt.md
@@ -0,0 +1,68 @@
+# Product Hunt assets
+
+## Name
+
+AiSOC
+
+## Tagline (≤ 60 chars)
+
+```
+Open-source AI SOC you can read, fork, and self-host
+```
+
+Alternatives:
+- `Triage your security alerts in 60 seconds — open source`
+- `The AI SOC whose every decision is logged and replayable`
+
+## Description (≤ 260 chars)
+
+```
+AiSOC is an open-source, self-hostable AI security operations center. Triage a
+batch of alerts to verdicts in 60s with `npx aisoc triage --demo` — no key, no
+Docker. Every agent decision is logged and replayable. MIT-licensed: read,
+fork, or replace the agent.
+```
+
+## Maker's first comment
+
+```
+Hey PH 👋
+
+I built AiSOC because "AI SOC" products are all closed boxes — you can't see
+why the agent made a call, and you can't run the evals yourself.
+
+AiSOC is the opposite:
+• `npx aisoc triage --demo` gives you a verdict on 200 alerts in under a second,
+ deterministic, no key, no install.
+• Every agent step (prompt, tool call, evidence, rationale) is stored in an
+ Investigation Ledger and replayable — you can even publish a redacted replay
+ as a public link.
+• A public eval harness gates every PR, and it's honest about what's a real
+ measurement vs. a synthetic self-consistency check.
+• Free browser tools (rule translator, ATT&CK coverage grader) with no login.
+
+It's MIT-licensed and self-hostable — your data never leaves your perimeter
+(hosted-LLM evidence is pseudonymized by default; a local-model path is fully
+air-gapped).
+
+Would love feedback from anyone running a SOC. What would make you trust an
+open agent over a closed one?
+```
+
+## Gallery (in order)
+
+1. The `npx aisoc triage --demo` terminal result (the hero).
+2. A public investigation replay (`/r/demo-lockbit`) mid-scrub.
+3. The Investigation Ledger in the console.
+4. The ATT&CK coverage grader with an A–F grade card.
+5. The architecture diagram (from the README).
+
+## Topics
+
+Security · Developer Tools · Open Source · Artificial Intelligence
+
+## Links
+
+- Website: https://tryaisoc.com
+- GitHub: https://github.com/beenuar/AiSOC
+- Benchmark: https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/benchmark.md
diff --git a/marketing/launch/show-hn.md b/marketing/launch/show-hn.md
new file mode 100644
index 000000000..6861ca411
--- /dev/null
+++ b/marketing/launch/show-hn.md
@@ -0,0 +1,79 @@
+# Show HN draft
+
+> Review against the benchmark page before posting. Keep it plain — no
+> superlatives, no unbacked numbers.
+
+## Title
+
+```
+Show HN: AiSOC – open-source AI SOC; triage a batch of alerts in 60s with `npx aisoc`
+```
+
+## Body
+
+```
+Hi HN — I've been building AiSOC, an open-source, self-hostable AI SOC
+(security operations center). The whole thing is MIT-licensed: the agent, the
+detection substrate, and the console.
+
+The fastest way to see what it does, with zero setup:
+
+ npx aisoc triage --demo
+
+That runs a bundled, fully-deterministic 200-alert fixture through the same
+triage verdict engine the full stack uses, and prints a table of verdicts
+(escalate / review / suppress) plus a one-line summary. No account, no Docker,
+no API key, no network. It finishes in well under a second.
+
+Two things I wanted to get right, because they're what I'd want from a security
+tool:
+
+1. Deterministic by default. The verdict engine is a plain, readable scoring
+ function — no LLM call required. An LLM "band" is optional and only runs if
+ you pass your own API key, which is used to call the provider directly and is
+ never proxied through any server we run. Every "viral" surface (the CLI, the
+ free web tools, the shareable replays) works with zero keys.
+
+2. Honest evals. There's a public eval harness that gates every PR. It's
+ explicit about what's a real measurement vs. a substrate self-consistency
+ check over a synthetic dataset — the benchmark page spells out exactly what
+ each suite does and doesn't prove. The `--demo` number above is a synthetic
+ fixture demonstrating the mechanism, not a claim about your environment.
+
+The full stack (connectors → OCSF normalize → Kafka → fusion → auto-triage →
+governed response, with an Investigation Ledger that logs every agent prompt,
+tool call, and rationale) is a `docker compose up` away, and there's a
+zero-dependency Python sandbox (`pip install -e packages/aisoc-sandbox`) if you
+don't want Docker.
+
+Repo: https://github.com/beenuar/AiSOC
+Benchmark methodology: https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/benchmark.md
+
+Happy to answer anything about the architecture, the eval design, or where it's
+still rough (autonomous response defaults to copilot/dry-run; live-LLM
+benchmark rows are a funded weekly job, not per-PR).
+```
+
+## First-comment (technical depth)
+
+```
+A bit more on the verdict engine, since that's the part people will poke at:
+
+triage scoring is an additive weight stack (vendor risk score, critical/high
+keyword hits, IOC field count, MITRE technique count, host presence), clamped
+to [0.05, 0.95], mapped to four bands. It's ~200 lines and pinned by a
+calibration test (Brier + ECE thresholds) against a 200-incident synthetic
+corpus. The CLI ports it to TypeScript with a parity test so a CLI verdict
+lands in the same band the server would assign.
+
+It is deliberately not a black box, and deliberately not claiming certainty.
+The LLM band layers on top for the ambiguous middle; the deterministic floor is
+what gates CI.
+```
+
+## Do / don't
+
+- **Do** link the benchmark page and name the copilot/dry-run default up front.
+- **Do** invite architecture/eval scrutiny.
+- **Don't** post precision/recall numbers that aren't on the benchmark page.
+- **Don't** call it "autonomous" without the copilot-default caveat.