docs: refresh README with new diagrams, tooling comparison and recent-attack use-cases

[HighnessAtharva]

Why

The README says what KubeArmor is. It does not say the one thing that separates it from every detect-and-respond engine: the decision happens at an LSM hook, in kernel space, before the syscall completes. A reader had to find that on a separate docs page.

Four things a new evaluator asks for were also missing: how it compares to Falco and Tetragon, what it costs at runtime, what it does for AI agent workloads, and whether it stops attacks people actually read about this year.

What changed

Section	Change
Intro	Rewritten. Two short paragraphs, second one carries the differentiation.
Install in 2 minutes	New. The README had no install snippet.
Architecture	New SVG replaces kubearmor_overview.png. Enforcement path and telemetry path are coloured separately.
Where the decision happens	New. Two-timeline figure, inline enforcement against detect-and-respond.
How KubeArmor compares	New. 7 engines across 6 axes.
Recent attacks	New. Five published 2025 campaigns, each with the policy control that breaks the chain, plus a figure of the shared chain.
Sandboxing AI agents	New. Four agent risks, four policy controls, links to ModelArmor.
Performance	New. Measured numbers, labelled with date and release line.
Community & Governance	Bullet list converted to a table.
Docs, contributors, meeting, CNCF, roadmap, related repos	Unchanged.

Figures

Four hand-authored SVGs in .gitbook/assets/diagrams/:

• fig1-architecture.svg — components across control plane, node, kernel, consumers
• fig2-decision-point.svg — the two timelines
• fig3-agent-sandbox.svg — one allowed path, four denied paths
• fig4-attack-chain.svg — the five-stage chain and the three policy gates

They use a fixed light palette, so a reader on GitHub dark mode gets the same drawing with legible labels. No build step, no external requests, no new dependencies, and every icon is inline SVG. The old PNG stays in .gitbook/assets/ for the GitBook site.

Sources

• Comparison table: Container Runtime Security, Comparative Insights, 2025 Edition (Rahul Jadhav)
• Performance: KubeArmor Performance Benchmarking Data
• Attacks: Unit 42, Wiz, Kaspersky Securelist, ReversingLabs, each linked inline in the table

Maintainer decisions needed

1. Performance data is from March 2023, on the v1.0 line. I kept it with the date and release line stated in a blockquote rather than dropping the section. A re-run on a current release would let us remove that caveat. Say the word and I cut the section instead.
2. Architecture accuracy. The snitch job and the OCI hook edges came from reading wiki/ and pkg/KubeArmorOperator/, not from a Maintainer. Please confirm. Also worth deciding whether the network policy enforcer deserves its own box.
3. Comparison table scope. It cites a paper written by a KubeArmor Maintainer who also cofounded AccuKnox, and it names two commercial products (NeuVector, Prisma). For a CNCF-facing README, tell me if you would rather keep only the open-source rows.
4. ModelArmor freshness. The docs page reads "last updated 1 year ago". Confirm the project is active before the README sends readers there.

Related

The organization profile README is a separate PR against kubearmor/.github. It reuses fig2 from this branch, so that image only renders once this PR merges.

🤖 Generated with Claude Code

[AryanBakliwal]

@HighnessAtharva kindly sign your commit, DCO is failing

[HighnessAtharva]

Pushed b3762197, simplifying all four diagrams. The first pass drew a maintainer's component map, which gave a first-time reader nothing at a high level.

Figure	Before	After
1	12 boxes, named components (operator, snitch, controller, monitor, enforcer, feeder, relay)	6 boxes, 3 numbered steps: you write a policy → KubeArmor turns it into kernel rules → the kernel decides. Allowed and blocked are explicit outcomes.
2	5 + 4 boxes, each with a second-line caption	4 + 3 boxes, one line each
3	5 rows with sub-captions and a side note	4 rows, one line each
4	5 stages + 3 policy cards + 5 campaign chips	4 steps + 3 policy cards. The campaign mapping lives in the table right below the figure.

Component names are now the docs' job, not the README's. Same fixed light palette, so GitHub dark mode readers still get a legible drawing.

The four maintainer questions in the description are unchanged and still open.

[HighnessAtharva]

Pushed c2622bbd. The prose read like generated text, so I rewrote it.

The tell was lines that set something up instead of saying it. "Two paths leave the kernel, and the difference matters" announces that a point is coming, then makes you read the bullets to find it. Same with "Three things explain that table", "Five campaigns, five write-ups, one shared chain", and "Every cell in the last column is a policy line, not a detection rule".

What changed:

• Every prose block I added is rewritten, addressing the reader as "you".
• Sentence fragments used for rhythm ("Nothing runs first." / "No node changes. No container runtime swap.") are full sentences now.
• All four em dashes are gone, including the two that predate this branch.
• Alt text on all four figures is fixed. It still described the detailed first-pass drawings, which is a real accessibility bug: a screen reader was hearing about a snitch job and a relay server that the picture no longer contains.
• Two figure captions argued a point instead of labelling the drawing. Reworded.

Same change applied to the org profile README in kubearmor/.github#1.

[HighnessAtharva]

Pushed d67947e6, cutting two lines that spoke to the project instead of to a reader.

Was	Now
Source: *Container Runtime Security, Comparative Insights, 2025 Edition* (Rahul Jadhav). Longer version: differentiation.	Want the longer version? Read differentiation.
> ...on the v1.0 line, which also has the BPF-LSM tables. Somebody should re-run it on a current release.	The full benchmark run has the per-reading tables and the BPF-LSM numbers. It was measured on the v1.0 line in March 2023.

A reader wants the claim and a link, not a bibliography entry. The re-run is a maintainer task, so it belongs in an issue rather than in the README. Happy to file that issue if you want the numbers refreshed before this merges.