Skip to content

Repository navigation

Move development guidance out of README #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hoggmania merged 1 commit into from
Sep 1, 2026
Merged

Move development guidance out of README #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 3 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
96 changes: 96 additions & 0 deletions develope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

@cubic-dev-ai cubic-dev-ai Bot Oct 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The OpenGrep worker refuses to analyze a scan unless bubblewrap is installed, but the local prerequisites omit that required sandbox executable. Document bubblewrap (or SANDBOX_BIN) alongside the OpenGrep configuration.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At develope.md, line 28:

<comment>The OpenGrep worker refuses to analyze a scan unless bubblewrap is installed, but the local prerequisites omit that required sandbox executable. Document bubblewrap (or `SANDBOX_BIN`) alongside the OpenGrep configuration.</comment>

<file context>
@@ -0,0 +1,96 @@
+- 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
</file context>
Suggested change
- Optional: Postgres for the triage service, OpenGrep binary/configuration, and LLM provider configuration
- Optional: Postgres for the triage service, OpenGrep binary/configuration, a bubblewrap executable (`/usr/bin/bwrap` by default), and LLM provider configuration
Fix with cubic


### 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`
Comment on lines +34 to +38

@cubic-dev-ai cubic-dev-ai Bot Oct 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: These per-module dev commands fail from a clean checkout because they select only the application module while its sibling reactor dependencies, such as scan-common, have not been installed. Add -am to each command or document a one-time reactor install before starting services.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At develope.md, line 34:

<comment>These per-module dev commands fail from a clean checkout because they select only the application module while its sibling reactor dependencies, such as `scan-common`, have not been installed. Add `-am` to each command or document a one-time reactor install before starting services.</comment>

<file context>
@@ -0,0 +1,96 @@
+
+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`
</file context>
Suggested change
- `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`
- `mvn -pl scan-api -am quarkus:dev`
- `mvn -pl scan-worker-workflow -am quarkus:dev`
- `mvn -pl scan-worker-light -am quarkus:dev`
- `mvn -pl scan-worker-filter -am quarkus:dev`
- `mvn -pl scan-worker-opengrep -am quarkus:dev`
Fix with cubic

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)
Loading