Skip to content
cuiossPublic

About

Trailhand, the CISO's friend: OWASP SAMM assessments, threat models, incident reports and ISMS documents as versioned documents on the Git server you already run. Quarkus native, with a web app and an MCP server for AI agents.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

TrailHand

Status

Java CI with Maven License

Quality Gate Status Lines of Code Coverage

Bootstrap. The concepts, specifications and decisions are written; the web app, its mock server, its end-to-end suite and the application with its login, configuration and repository handling are built; the document operations follow.

What is it?

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.

Build

The target is Java 25; CI builds on Java 25 and 27.

./mvnw clean verify

The 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 trailhand

Working on the Web App

The 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.sh

The 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"}'.

Credentials

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.

Releasing

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.0 is declared together with 0.1.0-SNAPSHOT in the POM. Do not touch it in an ordinary PR. The first release is a deliberate workflow_dispatch from main, and only once there is something to release.

  • Every later release goes through the runbook .claude/skills/release/SKILL.md: a dedicated chore/release_<version> PR that changes nothing but the version, merged only after the pre-cut checks.

  • Do not rewrite the cuioss/cui-java-module-template literal in .github/workflows/release.yml; it only excludes the template repository itself.

  • maven-build.enable-snapshot-deploy is true: every push to main deploys the 0.1.0-SNAPSHOT modules to the Sonatype snapshot repository. This is not a release.

About

Trailhand, the CISO's friend: OWASP SAMM assessments, threat models, incident reports and ISMS documents as versioned documents on the Git server you already run. Quarkus native, with a web app and an MCP server for AI agents.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages