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.
AiSOC public papers
This directory hosts publication-quality PDFs that the AiSOC marketing
site and docs site link to. Source markdown lives at
apps/web/content/papers/; PDFs here are generated artefacts.
Regenerating the PDFs
PDFs are regenerated from their source markdown via the top-level Makefile target (Phase 4.3):
make papers # regenerate every paper
The Makefile delegates to scripts/render_white_paper.py. You can
still render a single paper with explicit paths if you prefer the
old workflow:
python3 scripts/render_white_paper.py \
--input apps/web/content/papers/l0-l4-automation-maturity.md \
--output apps/web/public/papers/l0-l4-automation-maturity.pdf
The script depends on two Python packages — markdown and
weasyprint — and on the native libs WeasyPrint requires (Pango,
Cairo, GLib, libffi, libssl). The AiSOC API service image
(services/api/Dockerfile) already installs the native libs, so
running the script from the API service container is the easiest path:
docker compose run --rm api \
python3 scripts/render_white_paper.py
On a developer laptop with Homebrew:
brew install pango cairo libffi
pip install markdown weasyprint
python3 scripts/render_white_paper.py
Index
| Paper | Source | Status |
|---|---|---|
l0-l4-automation-maturity.pdf |
apps/web/content/papers/l0-l4-automation-maturity.md |
Shipped with v8.0 (T7.2). |
When adding a new paper:
- Author the markdown at
apps/web/content/papers/<slug>.md. - Add a YAML frontmatter block with
title,subtitle,author,date, andversionkeys (the render script reads these for the cover page). - Run
make papersto produce the PDF and record its source digest. - Commit the markdown, the PDF and
render-manifest.jsontogether. - Add an entry to the index table above.
- Link the PDF from the relevant docs concept page or marketing surface.
Do not commit PDFs without their matching markdown source.
Editing a paper's markdown — or replacing a screenshot it embeds —
means running make papers and committing the result in the same
change. The second half is not hypothetical: the v20.1.0 release
refreshed fifteen console captures without re-rendering, and the
published technical guide kept showing a console two releases old.
CI does not refresh PDFs for you. It
once did, pushing a chore(papers) commit straight to main, but that
stopped working when main became branch-protected — the push is
rejected with GH006. Opening a pull request instead is not available
either, because this repository has Actions set to read-only permissions
with pull-request creation disabled.
So .github/workflows/papers.yml
reports rather than repairs:
- Fails if any committed PDF is older than its markdown source, naming the papers to re-render.
- Renders every paper, so a markdown change that breaks rendering fails the build rather than shipping a broken PDF.
- Fails if any source produced no PDF.
- Uploads the rendered PDFs as an artifact, useful for previewing a PR.
Staleness is judged by comparing each source's SHA-256 against the digest
recorded in render-manifest.json when its PDF was last rendered, which
make papers updates. The digest covers the paper's source closure —
the markdown plus every local figure it embeds, keyed by path — so
refreshing a screenshot marks the PDF stale even though the markdown is
untouched, and repointing a caption at a different file counts as a change
too. PDF bytes are deliberately not compared: WeasyPrint
stamps a creation timestamp into its output and glyph metrics depend on
the host's installed fonts, so two correct renders of the same source are
not byte-identical. Commit render-manifest.json alongside the PDF.
The hosted PDF is the public artefact; the markdown is the canonical one.