4.6 KiB
Otche backend
Go API, worker and watchdog, Windows PowerShell runner, PostgreSQL schema, RFB/H.264 recorder and reusable trusted operator tools for the Otche Windows/Defender observation service. Results are observations, not a certificate that an uploaded file is safe.
Automation: API keys, curl quickstart and API contract; OpenAPI 3.1 source. The running API serves the public specification at /api/v1/openapi.json; the sibling frontend renders its read-only reference at /docs. API keys are owner-scoped, never administrator credentials.
Repository ownership
This is the canonical backend source. API, worker and watchdog are separate processes/containers built from one Go module and one command; their shared internal packages are not duplicated into services. The unsigned reviewed windows/ source is owned here; operators sign their own deployment copy. Frontend source belongs only to otche-frontend. Compose and portable installation instructions belong to otche-deploy. Clone the three repositories as siblings; there is no parent monorepo or submodule requirement.
Build
go mod download
go build -trimpath -o ./build/otche ./cmd/otche
docker build --target api -t otche-api:local .
docker build --target worker -t otche-worker:local .
The module minimum is Go 1.24 (go 1.24.0 in go.mod); Docker builds use Go 1.26/Bookworm and Debian Trixie runtime. Worker adds FFmpeg and xorriso. internal/store/schema.sql is embedded in the binary. Runtime user is UID/GID 10001. No private key or operator credential is included.
The command modes are api, worker, watchdog, healthcheck, migrate, user-create, bindings-sync, source-maintenance and source-validate. See configuration and API contract. DATABASE_URL_FILE is required for all database commands. otche healthcheck needs no database credentials: it requests http://127.0.0.1:<LISTEN_ADDR port>/api/v1/health (default 8080) with a two-second timeout and exits successfully only for HTTP 200. API additionally uses PUBLIC_ORIGIN, ARTIFACT_ROOT, optional LISTEN_ADDR (default :8080), and explicitly opt-in ALLOW_INSECURE_HTTP=true for trusted development only. Startup warns when PUBLIC_ORIGIN is unset or insecure HTTP is enabled on a non-loopback listener; neither warning refuses container-network development. Run migrate before the API. Use the sibling deploy repository for a complete database-backed startup and secure first-user creation.
Verification
go test ./...
Database-backed tests require a dedicated disposable PostgreSQL database via OTCHE_TEST_DATABASE_URL, never a production DSN. Recorder tests use FFmpeg. Inspect test prerequisites before interpreting skips as success. Windows helper tests are windows/Test-OtcheArguments.ps1 and windows/Test-OtcheGrub.ps1; run only under the existing approved execution policy. They do not qualify a source image. No automatic source VM operations are part of a normal build or test.
Execution prerequisites and safety
Read Windows setup and runner contract before preparing a dedicated stopped ordinary Windows VM. Review and sign every PS1/PSM1 on an authorized signing workstation; provide trusted certificates and credentials separately. The project does not bypass execution policy, disable Defender/UAC/Secure Boot, or install private signing keys on guests. Samples run only on disposable full clones after isolation and source qualification. Grub collects bounded literal local files under the selected interactive token, not as arbitrary SYSTEM/host reads.
provisioning/onboard-owner.py is an explicit trusted administrator tool (Python 3.9+, PVE CLI on an approved node). Dry-run is default; applying creates scoped credentials and refuses collisions. probe-owner-isolation.py reads operator-supplied disposable probes and writes private short-lived evidence; it never invents successful proofs. install-extractor.sh and otche-extract are a matched pair for an independently approved clean Debian extractor guest, not the control host. Optional online/extractor execution remains blocked without genuine matching proofs.
Protected VMIDs 7000/7001 and forbidden shared storage names in the code are intentional safety restrictions, not deployment inventory. Retain them. Choose actual owner resources explicitly and do not remove protections to make a configuration pass. No live host inventory, sample payload, proof, certificate, credentials or historical acceptance log is distributed here.