diff --git a/README.md b/README.md index b7d1e14..c7c56f9 100644 --- a/README.md +++ b/README.md @@ -53,91 +53,13 @@ Default policy bands described in project docs: - `30-60`: Potential False Positive - `61-100`: False Positive -## Repository Structure +## Development -- `scan-common`: shared models and Temporal interfaces. -- `scan-api`: REST entry point (`/scans`, `/health`). -- `scan-worker-workflow`: orchestrates the full scan workflow. -- `scan-worker-light`: lightweight activities (repo/suppression/upload/verdict). -- `scan-worker-filter`: SARIF filtering and optional ZeroFalse evaluation. -- `scan-worker-opengrep`: OpenGrep execution worker. -- `triage-service`: triage APIs, UI, CEL policy eval, audit trail, suppression PR automation. -- `suppression-service-mock`: mock ingest service for local/integration flows. -- `docs/`: architecture, runbook, and implementation notes. -- `k8s/` and `docker/`: deployment artifacts. - -## Local Development - -Prerequisites: - -- JDK 17 -- Maven 3.9 or newer -- Temporal (dev server or cluster) -- Git CLI -- Optional: Postgres (for triage service), OpenGrep binary/config, LLM provider config - -Typical startup sequence: - -1. Start Temporal (for dev server: `TEMPORAL_TARGET=localhost:7233`, `TEMPORAL_TLS_ENABLED=false`). -2. Start services/workers from repo root: - - `mvn -pl scan-api quarkus:dev` - - `mvn -pl scan-worker-workflow quarkus:dev` - - `mvn -pl scan-worker-light quarkus:dev` - - `mvn -pl scan-worker-filter quarkus:dev` - - `mvn -pl scan-worker-opengrep quarkus:dev` -3. Optional local triage path: - - start Postgres - - `mvn -pl triage-service quarkus:dev` - - set JWT verification config and DB env vars -4. Optional suppression ingest mock: - - `mvn -pl suppression-service-mock quarkus:dev` -5. Submit scans to `scan-api` and monitor status via `/scans/{runId}` and Temporal UI. - -Run the complete Java 17 verification suite from the repository root with: - -```bash -mvn -B verify -``` - -For containerized local run, use: - -- PowerShell: `scripts/podman-compose.ps1 up` -- Bash: `scripts/podman-compose.sh up` - -## Key Configuration - -Common: - -- `TEMPORAL_TARGET` -- `TEMPORAL_NAMESPACE` -- `TEMPORAL_TLS_ENABLED` -- `ARTIFACTS_DIR` -- `GIT_CLONE_TOKEN` - -OpenGrep: - -- `OPENGREP_BIN` -- `OPENGREP_CONFIG` - -Filter/ZeroFalse: - -- `ZEROFALSE_ENABLED` -- `ZEROFALSE_MAX_FINDINGS` -- `ZEROFALSE_MAX_TRACE_STEPS` -- `ZEROFALSE_CONTEXT_LINES_BEFORE` -- `ZEROFALSE_CONTEXT_LINES_AFTER` -- `ZEROFALSE_PROMPTS_VARIANT` - -Triage: - -- `TRIAGE_SERVICE_URL` -- `TRIAGE_POLICY_PATH` -- `TRIAGE_POLICY_CACHE_MINUTES` -- `TRIAGE_PR_URL_TEMPLATE` -- JWT role claim must include `security:vuln_assessor:triager` +Engineering setup, repository structure, local startup, verification, and configuration have moved to the [development guide](https://hoggmania.github.io/AutoTriage/develope.html). ## Related Docs +- [`develope.md`](develope.md) - `docs/architecture.md` - `docs/autotriage-vs-agentic-security-tools.md` - `docs/runbook.md` diff --git a/develope.md b/develope.md new file mode 100644 index 0000000..c4ae88d --- /dev/null +++ b/develope.md @@ -0,0 +1,96 @@ +# AutoTriage Development Guide + +This page contains the engineering information needed to build, configure, and run AutoTriage locally. + +[Return to the AutoTriage overview](README.md) + +## Repository Structure + +- `scan-common`: shared models and Temporal interfaces. +- `scan-api`: REST entry point (`/scans`, `/health`). +- `scan-worker-workflow`: orchestrates the full scan workflow. +- `scan-worker-light`: lightweight activities (repository, suppression, upload, and verdict). +- `scan-worker-filter`: SARIF filtering and optional ZeroFalse evaluation. +- `scan-worker-opengrep`: OpenGrep execution worker. +- `triage-service`: triage APIs, UI, CEL policy evaluation, audit trail, and suppression PR automation. +- `suppression-service-mock`: mock ingest service for local and integration flows. +- `docs/`: architecture, runbook, and implementation notes. +- `k8s/` and `docker/`: deployment artifacts. + +## Local Development + +### Prerequisites + +- JDK 17 +- Maven 3.9 or newer +- Temporal (development server or cluster) +- Git CLI +- Optional: Postgres for the triage service, OpenGrep binary/configuration, and LLM provider configuration + +### Startup + +1. Start Temporal. For the development server, set `TEMPORAL_TARGET=localhost:7233` and `TEMPORAL_TLS_ENABLED=false`. +2. Start the services and workers from the repository root: + - `mvn -pl scan-api quarkus:dev` + - `mvn -pl scan-worker-workflow quarkus:dev` + - `mvn -pl scan-worker-light quarkus:dev` + - `mvn -pl scan-worker-filter quarkus:dev` + - `mvn -pl scan-worker-opengrep quarkus:dev` +3. For the optional local triage path: + - Start Postgres. + - Run `mvn -pl triage-service quarkus:dev`. + - Set the JWT verification and database configuration. +4. For the optional suppression-ingest mock, run `mvn -pl suppression-service-mock quarkus:dev`. +5. Submit scans to `scan-api` and monitor `/scans/{runId}` and the Temporal UI. + +### Verification + +Run the complete Java 17 verification suite from the repository root: + +```bash +mvn -B verify +``` + +### Containerized Local Run + +- PowerShell: `scripts/podman-compose.ps1 up` +- Bash: `scripts/podman-compose.sh up` + +## Key Configuration + +### Common + +- `TEMPORAL_TARGET` +- `TEMPORAL_NAMESPACE` +- `TEMPORAL_TLS_ENABLED` +- `ARTIFACTS_DIR` +- `GIT_CLONE_TOKEN` + +### OpenGrep + +- `OPENGREP_BIN` +- `OPENGREP_CONFIG` + +### Filter and ZeroFalse + +- `ZEROFALSE_ENABLED` +- `ZEROFALSE_MAX_FINDINGS` +- `ZEROFALSE_MAX_TRACE_STEPS` +- `ZEROFALSE_CONTEXT_LINES_BEFORE` +- `ZEROFALSE_CONTEXT_LINES_AFTER` +- `ZEROFALSE_PROMPTS_VARIANT` + +### Triage + +- `TRIAGE_SERVICE_URL` +- `TRIAGE_POLICY_PATH` +- `TRIAGE_POLICY_CACHE_MINUTES` +- `TRIAGE_PR_URL_TEMPLATE` +- The JWT role claim must include `security:vuln_assessor:triager`. + +## Engineering Documentation + +- [Architecture](docs/architecture.md) +- [Runbook](docs/runbook.md) +- [Triage plan](docs/triage-plan.md) +- [Decision log](docs/decisions/decision-log.md)