Runbook
Local Run
- Install JDK 17 and Maven 3.9 or newer. The build enforces this toolchain; run
mvn -B verify from the repository root before building images.
- Populate environment variables for Temporal (e.g.,
TEMPORAL_TARGET, TEMPORAL_NAMESPACE, TEMPORAL_TLS_ENABLED=false).
- From the repo root, run
mvn -pl scan-api quarkus:dev to boot the REST service.
- Start Temporal developer server (Docker Compose or standalone) and configure the worker modules:
mvn -pl scan-worker-workflow quarkus:dev plus the light/filter/opengrep workers.
- If you are using the Temporal dev server, set
TEMPORAL_TARGET=localhost:7233 and TEMPORAL_TLS_ENABLED=false.
- Start the suppression mock if you want uploader integration testing:
mvn -pl suppression-service-mock quarkus:dev (defaults to port 8090) and set SUPPRESSION_SERVICE_URL=http://localhost:8090.
- For repo cloning in the light worker, ensure
git is installed and set GIT_CLONE_TOKEN if required for private repositories.
- Optional: set
ARTIFACTS_DIR=artifacts to control where the source tarball and suppression bundle are written.
- Configure the OpenGrep worker with
OPENGREP_BIN=opengrep and OPENGREP_CONFIG=/path/to/rules.yml to generate SARIF; the worker fails closed if either setting is absent instead of emitting an empty stub result.
- Optional: start the triage service with Postgres:
mvn -pl triage-service quarkus:dev, set DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASSWORD, configure JWT verification (MP_JWT_VERIFY_PUBLICKEY_LOCATION or MP_JWT_VERIFY_PUBLICKEY), and set GIT_CLONE_TOKEN for private repos; the role claim must include security:vuln_assessor:triager. UI lives at http://localhost:8095/triage/ and Swagger at http://localhost:8095/swagger-ui. If you want PR URLs in responses, set TRIAGE_PR_URL_TEMPLATE with {repo}, {base}, and {branch} placeholders.
- Optional: set
TRIAGE_SERVICE_URL=http://localhost:8095 on the filter worker to persist potential false positives; configure the triage service policy location/cache via TRIAGE_POLICY_PATH and TRIAGE_POLICY_CACHE_MINUTES (defaults to .autotriage/policy.cel on the repo default branch).
- Optional: enable ZeroFalse LLM suppressions in the filter worker with
ZEROFALSE_ENABLED=true and configure a Quarkus LangChain4j provider (for example quarkus.langchain4j.openai.*).
- Optional tuning for ZeroFalse:
ZEROFALSE_MAX_FINDINGS, ZEROFALSE_MAX_TRACE_STEPS, ZEROFALSE_CONTEXT_LINES_BEFORE, ZEROFALSE_CONTEXT_LINES_AFTER, ZEROFALSE_PROMPTS_VARIANT.
- Use cURL to POST
/scans and watch Temporal Web UI for workflow progress; /scans/{runId} returns structured status.
Podman Compose Run
- Start a Temporal dev server on the host (or set
TEMPORAL_TARGET to your cluster).
- From the repo root, run
scripts/podman-compose.ps1 up (PowerShell) or scripts/podman-compose.sh up (bash) to build and start containers.
scan-api listens on port 8080, the suppression mock on 8090, the triage service on 8095, and Postgres on 5432; ARTIFACTS_DIR is shared across workers via a podman volume.- To stop everything, run
scripts/podman-compose.ps1 down or scripts/podman-compose.sh down.
- Optional overrides: set
GIT_CLONE_TOKEN for private repos and OPENGREP_BIN/OPENGREP_CONFIG for real SARIF output.
Kubernetes Run
- Build containers with
docker build using the Dockerfiles in docker/ and push them to a registry.
- Deploy Temporal (with TLS certs mounted via Secrets) and apply the manifests under
k8s/ which wire config as env vars; triage service and database manifests are not yet included.
- Ensure TLS cert volumes are mounted and the Temporal target URL is available via ConfigMap.
- Use Kubernetes Jobs or Deployments to schedule the worker replicas per queue: workflow, light, filter, opengrep.
- Monitor the
/health endpoints and Temporal UI; rotate certificates by replacing the Secrets and restarting pods as needed.
Notes
- Java 17 is the compiler, test, CI, container-build, and production runtime baseline. Core triage tests are part of the normal reactor and must not be skipped.