Skip to content
Veltrosecurity

Contributing

Repositories

Section titled “Repositories”
Repo Owns
veltrosecurity/veltro The installer, gateway, sign-in service, Helm chart, design-system packages, docs site and releases
veltrosecurity/vectorflow VectorFlow and its agent
veltrosecurity/sigmatic Sigmatic
veltrosecurity/warden Warden

Docs site

Section titled “Docs site”

The site is organised by product. Each of VectorFlow, Sigmatic and Warden has a section that stands on its own, the Veltro section covers what needs two or more products, Operate covers what every install shares, and this section is for contributors.

Authored pages live in docs-site/src/content/docs/. Everything else is copied at build time from a repository’s docs/ tree by docs-site/scripts/sync-content.mjs, which decides where each file lands:

  • a product’s docs/ goes to that product’s Guides, except its decision records, which come here
  • a product doc about working with another product goes to the Veltro section
  • Veltro’s own docs/ is split by reader between Operate, the Veltro section and this section

Edit the originals, not the copies. The VectorFlow section must stay free of security terms and of the other products’ names; the check-vocabulary gate fails the build when it isn’t.

docs-site is its own pnpm workspace with its own lockfile, so the site’s dependencies stay out of every other pnpm install in the repo:

Terminal window
pnpm -C docs-site install
pnpm -C docs-site test
pnpm -C docs-site sync
pnpm -C docs-site build
pnpm -C docs-site check-links
pnpm -C docs-site check-vocabulary

What the gates do and do not prove:

Gate Proves Does not prove
test Synced docs land in the right section; fenced code and code spans in them are byte-identical; prose links resolve or are counted; the vocabulary gate reports what a reader would see Anything about authored pages
sync Every synced page has frontmatter and a source-of-truth banner; reports dropped_relative_links (targets it could not resolve, degraded to plain text) That a dropped link was intentional
check-links Internal links on authored pages resolve in dist/ (a miss fails); every built page has a sidebar entry or an inbound link (an unreachable page fails); synced-page misses are warnings External http(s) links: collected and counted, never requested
check-vocabulary No VectorFlow page shows security terms or another product’s name Anything outside the VectorFlow section

Fenced samples are never rewritten: CommonMark does not process links or backslash escapes inside code, so a rewrite there would ship a broken sample.

Content packs

Section titled “Content packs”

Detection packs, pipeline packs and runbook packs are Apache-2.0 content trees with fixture tests in their product repos. Prefer small, reviewed PRs with behaviour tests over drive-by YAML.