When to use sidecar mode
- You need a persistent local process instead of one process per scan
- You need job submission with progress polling
- You need cancellation of an in-flight job
- You need health and readiness checks separate from liveness
- You need to run multiple long-running requests concurrently behind your own service
Security posture
A local sidecar should:
- Bind to loopback by default and reject remote exposure unless explicitly configured
- Validate target scope before acting on it
- Enforce timeouts and support cancellation as a distinct state from a normal completion or failure
- Sanitize logs — no secrets, no unredacted customer data
- Avoid arbitrary shell execution
- Return structured, safe errors rather than raw internal error text
SecEng Connector Sidecar contract
Draft — generated reference pending
This is a real, current contract document in savvy-cli (seceng-scan-content/docs/contracts/sidecar-api.md), reproduced accurately below. We could not confirm at last sync that these routes are implemented by a running server — no matching route handlers were found in savvy-server's source, and this contract is absent from the generated OpenAPI spec. Treat it as a design contract pending confirmation, not a confirmed live API.
Base URL default: http://127.0.0.1:17371
Environment override: SECENG_SIDECAR_URL
GET /health
GET /v1/connectors/capabilities
POST /v1/connectors/classify # input: SecEngHttpMessage
POST /v1/connectors/ingest-http # input: SecEngHttpMessage
POST /v1/connectors/ingest-finding # input: SecEngFinding
POST /v1/connectors/export-evidence # input: { source, items, format }Savvy server HTTP surface
Separately, the real, generated Savvy server OpenAPI document (528 total operations, current as of the last sync) exposes 21 operations under /v1/seceng/* — findings, scan runs, attack paths, targets, exports, trust-scan, and VCS scan enqueue. This is the confirmed-live surface today. See the generated API reference for the full, current path list.
Next
Open the generated API reference for exact paths, methods, and summaries. Authentication, retry, and idempotency semantics for both surfaces above are not yet published — confirm directly before production integration via a partner pilot.