Contribute

SocTalk is Apache 2.0. PRs welcome. This page covers the dev loop and what to expect from a review.

Dev environment

Bring up a local cluster ready for SocTalk:

git clone https://github.com/soctalk/soctalk.git
cd soctalk
./scripts/dev-up.sh           # cluster dependencies only

scripts/dev-up.sh creates a k3d cluster and installs the cluster-level prereqs:

• K3s with Flannel + kube-proxy disabled
• Cilium as the CNI with NetworkPolicy enforcement
• cert-manager installed
• k3d local-path as the default StorageClass

It does not build SocTalk images, install the SocTalk chart, onboard tenants, or seed data, earlier drafts of this page claimed it did. Run the next steps yourself. Typical sequence after dev-up.sh:

just build-api build-frontend  # api image embeds the orchestrator in V1
helm install soctalk-system charts/soctalk-system \
  -n soctalk-system --create-namespace \
  --set install.bootstrapAdmin.email=dev@example \
  --set install.bootstrapAdmin.password=devpassword12
# migrations + bootstrap admin run in the API pod's init command
# sign in at https://<your-ingress>/ with the credentials you set above

For a faster inner loop (no image rebuild on every change), see the iteration tips below.

Choose your iteration loop

Per project convention, prefer running services with uvicorn / pnpm dev over the k3d build-push-redeploy cycle:

# API (embeds the orchestrator in V1)
cd src && uvicorn soctalk.core.api.app_v1:app --reload --port 8000

# Frontend
cd frontend && pnpm dev

Point them at the k3d cluster's Postgres / Wazuh / Cortex via kubectl port-forward. Iteration is seconds, not minutes.

Repo layout

src/                Python (control plane, AI pipeline, adapter, runs-worker)
frontend/           SvelteKit (MSSP + customer UI)
charts/             Helm charts (soctalk-system, soctalk-tenant, wazuh, linux-ep)
infra/packer/       VM image generation (see /downloads)
setup-wizard/       Go (first-boot setup wizard)
attack-simulator/   MITRE ATT&CK demo scripts
scripts/            Dev / e2e / seed scripts
alembic/            DB migrations
docker-compose*.yml Various dev composition files
justfile            Build / release recipes

The docs site (this site) lives in a separate repo, soctalk/soctalk-docs.

Tests

There are no just test / just test-rls / just e2e-l1-l2 recipes in this release, that's the planned shape. Today, run tests directly with pytest:

pytest tests/                          # full suite
pytest tests/v1/test_rls_isolation.py  # Postgres Row-Level Security suite

The RLS tests are non-negotiable, they verify the cross-tenant data isolation that the Security Model promises. CI runs the full pytest suite on every PR.

Style

• Python: ruff + black. CI enforces.
• TypeScript: ESLint + Prettier with the in-repo config. CI enforces.
• Commit messages: single-line subject, conventional commit prefix (feat:, fix:, chore:, ci:, chart:, …). No body required.
• No co-authored-by / signed-off-by trailers.

PR expectations

• Tests for the change. New endpoints need API tests; new graph nodes need state-machine tests; chart changes need rendered-template snapshots.
• Migration if you touched a model. Alembic auto-generates; review the generated SQL for accuracy before committing.
• Update docs in soctalk-docs if the change affects a documented behaviour. We are not strict about this for internal-only refactors; we are strict about it for anything user-facing.
• Small PRs. Big mixed-change PRs are hard to review. Split refactor from feature; split chart change from runtime change.

Reviewing your own work

Before requesting review, run codex against your changes:

codex review --uncommitted

This is the same review pass we run at release time. It catches the obvious problems before a human reviewer has to.

Releasing

Releases are tagged from main. Today the flow has more manual steps than the planned just release recipe implies:

1. Manually bump versions in Chart.yaml + pyproject.toml, commit, push.
2. Tag the commit and push the tag (git tag vX.Y.Z && git push --tags).
3. just release: runs just build-all push-all. This only builds and pushes container images; it does not tag, publish charts, or create a GitHub Release.
4. publish-images.yml GH workflow handles the image publish to ghcr.io when triggered.
5. Chart publish to ghcr.io/soctalk/charts/ is done manually with helm push today.
6. gh release create to cut the GitHub Release.
7. build-packer-images.yml (manual trigger) builds the demo VM image in all five formats and attaches them to the GitHub Release.

Consolidating steps 1, 2, 5, and 6 into the just release recipe is on the roadmap.

Security disclosure

If you've found a vulnerability, do not file a public issue. Email the address listed in SECURITY.md in the repo root. We respond within two business days.

License

Apache 2.0. By submitting a PR you agree to license your contribution under the same.

Recognition

The git log is the canonical contributor record today; a dedicated CONTRIBUTORS.md / just update-contributors is planned.