Source of docs.openctem.io, the documentation for OpenCTEM, the open-source Continuous Threat Exposure Management platform.
The site is built with Jekyll and the
Just the Docs theme and published by GitHub Pages from
main (.github/workflows/pages.yml).
| Directory | Section |
|---|---|
overview/ |
What OpenCTEM is, architecture, concepts, glossary |
install/ |
Requirements, Docker Compose, all-in-one image, Kubernetes, TLS |
configuration/ |
Environment variables reference, email, notifications |
operations/ |
Upgrades, versioning, backups, monitoring, scaling, troubleshooting, logs |
console/ |
The platform console for platform administrators |
security/ |
Security model, hardening, vulnerability disclosure, data handling |
identity/ |
SSO, SCIM, sign-up, roles and permissions, two-factor authentication |
sensors/ |
Deploying and pairing sensors, scan zones, network requirements |
scanning/ |
Scope, scan workflows, scans and runs, tools, CI integration |
user-guide/ |
Using the web console |
api/ |
REST API, authentication, conventions, webhooks, MCP, ingest |
developers/ |
Local setup, contributing, testing, migrations, releases, writing a tool |
legal/ |
Licenses, privacy policy, terms |
Engineering documents that change with the code (architecture notes, RFCs, versioned
upgrade guides) live next to the code in
openctemio/openctem server/docs;
the site links to them.
python3 scripts/versions_manifest.py . # current releases (add --offline without network)
python3 scripts/release_pages.py --count 2 . # optional: the release change pages
docker run --rm -it -p 4000:4000 -v "$PWD":/site -w /site ruby:3.1 \
bash -c "bundle install && bundle exec jekyll serve --host 0.0.0.0"Then open http://localhost:4000.
The console screenshots in assets/images/<section>/ come from a scratch installation
filled with the fictional organization Example Corp, and are regenerated for each
release:
-
Start a scratch stack (API, web console, PostgreSQL, Redis) from the openctem release, with an empty database. Never use a real installation.
-
Seed it: see scripts/demo-seed/README.md.
-
Capture (headless Chromium, 1440×900):
cd scripts npm install && npx playwright install chromium OPENCTEM_WEB_URL=http://localhost:3000 OPENCTEM_API_URL=http://127.0.0.1:8080 \ npx tsx capture-screenshots.ts # or a filter: capture-screenshots.ts 'scanning/'
The script signs in as the demo accounts, blurs anything that looks like a credential, and writes palette PNGs (WebP above 300 KB). Review every image before committing it.
Notes for a run against a current release:
- A plain-HTTP scratch stack on loopback ports runs with
APP_ENV=staging(production refuses a database or Redis without TLS and needs the job signer) and, when the console API listens on all interfaces of its container,ADMIN_LISTEN_ALLOW_ALL_INTERFACES=true; publish every port on127.0.0.1only. - Start the scratch stack with
CERT_MONITOR_ENABLED=false. Certificate Transparency discovery reads real public logs forexample.comand adds names that belong to other people to the inventory. - Run the seed once per database. Campaigns, tasks and some other steps are not idempotent and a second run creates duplicates.
- Re-run
demo-seed/sql/90-refresh.sqljust before capturing the sensor and scan pages, or the sensors show as late. - The
websitesection of the script writesassets/images/website/. Copy those images tosrc/assets/shots/in the website repository (and runnode scripts/og.mjsthere); do not commit them here. - The inventory at 1440 pixels wide gives the Name column almost no room, so the asset shots use a 1680 pixel viewport that is scaled down to 1440 on save.
- A plain-HTTP scratch stack on loopback ports runs with
Open a pull request against main. Write in English, check every command, flag and
setting against the code, use example.com hosts and documentation IP ranges
(192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24) in examples, and keep links
relative. The docs-check workflow runs a link check and rejects non-English text and
private addresses.
A release needs no commit in this repository:
- Current versions. Write
{{ site.data.versions.sensor }}(orplatform,sdk_go,ci,chart,chart_app,connector_tenable,min_sensor,min_sdk_go,min_ci, and the platform image digestsdigest_openctem,digest_api,digest_web,digest_console,digest_migrations;server_imageis the server image's name for that release,openctem-serverfrom v0.23.0 andopenctem-apibefore). The site build writes_data/versions.ymland_data/manifest.jsonfrom the signed versions manifest the platform's release pipeline publishes (https://get.openctem.io/releases/manifest.json; until that address answers, the same file as a release asset, then a build from the public GitHub releases in the same schema). The build verifies the signature with cosign and fails, leaving the published site as it was, when it does not verify. These files are git-ignored;scripts/versions-snapshot.jsonserves only--offlinelocal builds and is refreshed with--write-snapshot, never edited. - Compatibility.
{% include compatibility.md %}prints the current releases and which platform each component needs, from the same manifest. - What changed.
scripts/release_pages.pywritesoperations/releases/<version>.mdfor the recent releases from the changelog entries of each release tag (upgrade notes first). The hand-written per-release guides inoperations/upgrade.mdexplain what needs judgement. - When. The site rebuilds on every push, every 6 hours, and when the platform's Release
Feed run sends
release-published.versions-monitorfails and opens astale-versionsissue when the published site lags the latest release for more than a day.
scripts/check_versions.py (in docs-check) fails on a hard-coded image tag,
SENSOR_VERSION=, git checkout vX.Y.Z, a Helm --version, an sdk-go, CI runner or connector
release and the like, and on a key the data file does not have. History ("from v0.16.0")
stays as written; a line that must pin on purpose carries docs-check: pinned-version.
Report security vulnerabilities to security@openctem.io, not in issues. Other questions: info@openctem.io.