TrailHand — the CISO’s friend — is the server application in which a development organisation maintains its OWASP SAMM assessments, threat models, incident response reports and ISMS documents as versioned documents, on the Git server it already runs. No client holds a clone and no additional database is needed.
It is built on the libraries of git-document-repository and on
Token Sheriff, runs as a Quarkus native application on Java 25, and has two
interfaces: a web app for people and an MCP server for AI agents acting for a user.
The documentation starts at doc/README.adoc: concepts, architecture decisions and specification. New readers start with the Overview.
The target is Java 25; CI builds on Java 25 and 27.
./mvnw clean verifyThe modules of Architecture and Modules are added as they are
built, each with its own README: web-app (the Svelte web app),
web-mock (the mock server of its requests, development and tests only),
trailhand (the Quarkus application) and web-e2e (Playwright
and axe-core). The end-to-end suite runs with the profile e2e, the native image with the profile native (Mandrel
in a container):
./mvnw verify -Pe2e -pl web-e2e -am
./mvnw package -Pnative -pl trailhand -am
docker build -f trailhand/src/main/docker/Dockerfile.native -t trailhand:dev trailhandThe web app runs in the Vite dev server against the mock server, which answers its requests from a test profile (web-mock):
web-mock/start.sh -s workshop # profiles: workshop, first-login, read-only, degraded, empty
cd web-app && npm run dev # http://127.0.0.1:5173, /api and /mock go to the mock
web-mock/stop.shThe mock signs in by itself; switch the profile while the app runs with
curl -X POST http://127.0.0.1:7420/mock/scenario -d '{"scenario":"first-login"}'.
All secrets (GPG, Sonatype, Sonar, Release App) are managed at the cuioss organization level. The caller workflows pass them explicitly to the reusable workflows; pass only the secrets a reusable workflow declares, an undeclared one makes every run end in startup_failure. No repo-level secrets need to be configured.
Merging a change of release.current-version in .github/project.yml is a release: the central
guard in reusable-maven-release.yml publishes to Maven Central whenever that value differs from the
merge commit’s first parent and no tag for it exists. Maven Central releases cannot be withdrawn.
Every other project.yml edit reaches the release workflow too and is refused by the guard.
-
current-version: 0.1.0is declared together with0.1.0-SNAPSHOTin the POM. Do not touch it in an ordinary PR. The first release is a deliberateworkflow_dispatchfrommain, and only once there is something to release. -
Every later release goes through the runbook
.claude/skills/release/SKILL.md: a dedicatedchore/release_<version>PR that changes nothing but the version, merged only after the pre-cut checks. -
Do not rewrite the
cuioss/cui-java-module-templateliteral in.github/workflows/release.yml; it only excludes the template repository itself. -
maven-build.enable-snapshot-deployistrue: every push tomaindeploys the0.1.0-SNAPSHOTmodules to the Sonatype snapshot repository. This is not a release.