hoop / sidecar
CLAUDE.md848 starsChanged 24 days agoMITView on GitHub
Wire-protocol inspection as a library. Relay codecs turn raw database and HTTP/1 bytes into structured statements; libhoop/v2/codec/grpc owns the gRPC HTTP/2 endpoint and reusable protocol mechanics, while daemon/ injects identity, statement, policy, audit, and masking behavior. Policy turns either form into allow/deny verdicts, masked responses and an audit trail. The root CLAUDE.md does not cover this directory. It describes the product modules under go.work; sidecar/ contributes nine more entries and follows different rules. This file governs everything under sidecar/. The…
- Reads credentials
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- webapp/CLAUDE.mdCLAUDE.md
- webapp_v2/CLAUDE.mdCLAUDE.md
- build-ticketSkill
- evidenceSkill
- gcp-marketplace-publishSkill
- shapeSkill
- support-agentSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 260
Every new field also gets cap:"<name>", unless it ships in the same release as a tagged block around it: omitting the zero value hides an …
- Very specific: line 363
sidecar protocol-specific parsers: if the code must be added to libhoop, the sidecar parsers must live under libhoop/v2/*.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md: sidecar
Wire-protocol inspection as a library. Relay codecs turn raw database and
HTTP/1 bytes into structured statements; libhoop/v2/codec/grpc owns the
gRPC HTTP/2 endpoint and reusable protocol mechanics, while daemon/
injects identity, statement, policy, audit, and masking behavior. Policy
turns either form into allow/deny verdicts, masked responses and an audit trail.
The root CLAUDE.md does not cover this directory. It describes the product
modules under go.work; sidecar/ contributes nine more entries and follows
different rules. This file governs everything under sidecar/.
The directory was called hoopinspect/ until the CLI command became
hoop start sidecar. Nothing about the module changed with the name, but two
packages moved so the tree stops stuttering: the inspection core is
sidecar/inspect (it was the root package) and the assembly that was
hoopinspect/sidecar is sidecar/daemon. The binary, its config directory
and HOOP_INSPECT_CONFIG all keep the hoop-inspect spelling, because
renaming those breaks running deployments.
Full documentation is README.md here (86 KB, read the section you need, not
the whole thing).
The invariant: exactly one dependency
github.com/hoophq/hoop/sidecar depends on github.com/hoophq/libhoop
and nothing else. It used to depend on nothing at all, and that was the
product pitch — vendorable without a supply-chain review, readable end to end
in an afternoon, compilable to wasip1. The protocol codecs moving to libhoop
ended it: this module cannot describe its own inputs without naming the types
the decoders produce.
libhoop is PRIVATE, so building or testing here needs
GOPRIVATE=github.com/hoophq/libhoop and credentials for that repository.
cmd/ and the nested ica/ module also link the private Citrix ICA engine,
so they need GOPRIVATE=github.com/hoophq/libhoop,github.com/hoophq/libhoop-ica
and credentials for both.
The edge runs one way and must stay that way. libhoop imports nothing from this repository. Two mechanisms hold that:
- Types are aliased, not copied.
inspect/wiretypes.godeclarestype Statement = codectypes.Statementand so on. Same type, not a conversion — which is why a libhoop codec satisfies theCodecinterface here structurally, without importing this package, and why there is one definition of the document a policy evaluates rather than two that drift. - Behaviour is injected, not imported. The SQL classifier (
AnalyzeSQL) and the lexer stay here, because they are the most safety-critical code in the system and there must be one auditable copy.sidecar/codec/*hands them to each decoder through itsOptions.
Check it:
cd ../libhoop && grep -rn '"github.com/hoophq/hoop' --include='*.go' . # must be emptyEach optional component is its own module, so it can be plugged in or dropped without touching anything else. SQLite is the clean case: removing it is removing a directory.
| Module | Carries |
cmd/ | the hoop-inspect binary, where the optional plugins are linked |
config/yaml/ | gopkg.in/yaml.v3 |
pii/alcatraz/ | github.com/hoophq/alcatraz and github.com/hoophq/alcatraz/ner, the ONNX NER model runtime: pure Go by default, ONNX Runtime under -tags ORT |
store/sqlite/ | modernc.org/sqlite, pure Go because the sidecar is a static binary |
analyzer/vertex/ | golang.org/x/oauth2, the only analyzer provider needing one. It wraps the anthropic, gemini and openai encoders from the root under a GCP bearer; the API-key providers stay in the root |
descriptors/gcs/ | golang.org/x/oauth2, to read a grpc lane's descriptor set from a gs:// URL |
mcp/ | github.com/modelcontextprotocol/go-sdk, for the review status MCP server an mcp: block turns on (ADR-0021) |
ica/ | github.com/hoophq/libhoop-ica, the Citrix ICA engine a protocol: ica lane embeds; registers through daemon.RegisterICAEngine, linked into hoop-inspect only |
mcpgateway/ | github.com/hoophq/mcpproxy, the engine a protocol: mcp lane embeds; registers through daemon.RegisterMCPGatewayEngine, linked into hoop-inspect and hoop start sidecar |
codec/wasm/ | github.com/tetratelabs/wazero, the codec plug-in host; daemon only sees LoadCodecPlugin. sdk/ and examples/ hold the guest side: Rust, TinyGo and C |
telemetry/otlp/ | the OpenTelemetry SDK and its OTLP exporters, behind the telemetry block; daemon sees only telemetry.Builder, injected by cmd like LoadCodecPlugin. The contract is the root package telemetry/ |
lexer/conformance/ | PostgreSQL's real parser, test-only |
Adding a dependency to the root still needs a reason. Add a nested module, or do without.
Commands
make test-sidecar at the repo root runs every module below, and
make test-oss depends on it, so CI runs them too. The commands are here
because the target is a loop over them and you will want one at a time.
make test-sidecar-plugins covers what test-sidecar cannot reach: the
guest SDKs and the examples under codec/wasm. It runs cargo test on the
Rust crate and examples/resp, GOWORK=off go test on the TinyGo module
and examples/memcache (neither is in go.work, so the walk above skips
them), then hoop-inspect -codec-test over every checked-in .wasm. It
needs Go and Rust only, which is why the artifacts are committed; the
plug-in workflow installs TinyGo and lld, rebuilds them from source and
proves the rebuilds with -codec-test (no byte compare: rustc differs
across OSes). test-oss depends on it.
The SDKs under codec/wasm/sdk release from one file, sdk/VERSION,
repeated in sdk/rust/Cargo.toml and recorded in sdk/rust/Cargo.lock
(cargo update -w after the bump); sdk/version.sh refuses a PR where
the three differ. Merging a bump to main tags hoop-codec-vX.Y.Z
(sidecar-plugins-autotag.yml), and from that tag
sidecar-plugins-release.yml publishes the crate, tags the Go module
sidecar/codec/wasm/sdk/tinygo/vX.Y.Z at the same commit, and opens the
hoophq/plugins mirror PR, which carries the C header as
sdk/c/hoop_codec.h. It creates no GitHub release: that list is the
product's and the deploy tooling reads it. Never push either tag by hand.
make test-sidecar-e2e is a separate path: it boots a real
mysql:8 container and runs the hoop-inspect binary as a subprocess in
front of it, so it needs a working Docker daemon. It is deliberately NOT a
dependency of test-oss or test-sidecar — those run in the unit-test job,
which has neither Docker nor the minutes for a container boot — and has its
own CI job instead. e2e/ is outside go.work, so it only builds under
GOWORK=off; the make target sets that for you. See the gotcha below.
SIDECAR_E2E_GOWORK overrides the workspace the harness builds
hoop-inspect against. Unset — which is what CI does, and what you want —
the binary resolves through the repository's own go.work and therefore the
PUBLISHED libhoop pin, which is the thing under test. Point it at a
workspace with a local use directive to run the suite against an unmerged
codec before it lands:
SIDECAR_E2E_GOWORK=/path/to/dev/go.work make test-sidecar-e2eIt is not in .env.sample: that file configures the gateway at runtime, and
this is a test-only override read by one harness.
# root module (inspect/, lexer/, codec/, policy/, gate/, proxy/, daemon/, ...)
go test ./...
go vet ./...
# nested modules are NOT reached by the line above
for m in cmd config/yaml pii/alcatraz store/sqlite analyzer/vertex descriptors/gcs mcp ica lexer/conformance codec/wasm telemetry/otlp; do
(cd "$m" && CGO_ENABLED=0 go test ./...)
done
# pii/alcatraz under -tags ORT is cgo; the real-model test runs only with the env set
(cd pii/alcatraz && CGO_ENABLED=1 HOOP_ALCATRAZ_MODELS_DIR=/opt/alcatraz/models HOOP_ALCATRAZ_ORT_LIBRARY=/opt/alcatraz/ort/releases/1.28.0/lib/libonnxruntime.so go test -tags ORT -run TestNERRealModel ./...)
# the oracle: run this for ANY change under lexer/
(cd lexer/conformance && CGO_ENABLED=0 go test ./...)
# validate a sidecar config without starting anything
(cd cmd && go run . -validate -config /path/to/config.yaml)
# prove a codec plug-in against the ABI, then its own fixtures
(cd cmd && go run . -codec-test /path/to/plugin.wasm /path/to/fixtures.json)
# the guest SDKs and the three examples; also proves every checked-in .wasm
(cd ../.. && make test-sidecar-plugins)
# end to end against a real mysql:8, needs Docker. GOWORK=off is required:
# e2e/ is deliberately not a go.work member.
(cd e2e && GOWORK=off CGO_ENABLED=0 go test -tags integration -count=1 ./...)Gotchas
go test ./...at the root reaches no nested module. Separatego.modfiles are what keeps optional dependencies out of the root, and the cost is that every nested module needs its own invocation. See the loop above.- CI reaches this through two targets, not one.
make test-ossrunsgo test github.com/hoophq/hoop/..., which does not match modulegithub.com/hoophq/hoop/sidecar, so the Makefile carriestest-sidecar, which walks everygo.modundersidecar/and whichtest-ossdepends on. Break that dependency and those tests stop running everywhere except on your machine. sidecar/e2eis the exception, and it is not ingo.work. Its testcontainers/docker dependency tree has no business in the workspace every other module resolves against. The cost is thatgorefuses to work there under the workspace at all —cd sidecar/e2e && go testfails with "directory prefix . does not contain modules listed in go.work" — so both the suite and anything building it needGOWORK=off. This is also whytest-sidecarfilters its discovered module list againstgo.workinstead of running everythingfindturns up: unfiltered, the walk enterse2e, hits that error and aborts the loop underset -e, takingtest-osswith it. The suite runs only undermake test-sidecar-e2e, from its own CI job, and needs Docker. Adding it totest-ossto "fix" the asymmetry puts a multi-minute container boot on every unit run in a job with no Docker guarantee.- A
lexer/change is not verified until the conformance suite passes.lexer/conformance/runs PostgreSQL's own parser and the scanner over the same statements and fails on disagreement. The scanner is hand-written and deliberately not a parser, so the oracle is the only thing standing between a plausible change and a wrong one. It runs underCGO_ENABLED=0because the parser is a wasm build. - A false positive in the lexer is an outage, not a warning. A statement
misread as a write is refused by a read-only lane. Reserved words are legal
column aliases when
ASis written, and BI tools emit them: Metabase's schema sync sendshas_table_privilege(..., 'delete') AS delete. Widening the classifier costs an operator their tool. Add the case tolexer/conformancecorpus inoracle_test.goand let the real parser judge. - Codecs register a factory, not an instance (
inspect/registry.go). Codecs that reassemble messages across packets hold per-connection state, so a shared instance would let one connection's SQL surface in another's audit trail.Registerpanics on a duplicate protocol, because import order deciding a winner is worse than a build failure. inspectimports no codec, and no longer ships one. The decoders live ingithub.com/hoophq/libhoop, a private module, under itsv2/codec/*directory —v2there is a folder name, not a major version. libhoop imports NOTHING from this repository; the types it returns are defined there and aliased here, so its codecs satisfyCodecstructurally.sidecar/codec/*is the registration seam, not a decoder. libhoop cannot callRegister, so these packages do it, and they are also whereAnalyzeSQLand the lexer get injected into a decoder.codec/httpis not thin: its*Codecembeds libhoop's Inspector and adds the relay concerns libhoop has no reason to know (path cleaning, Connect Gateway resource normalization, credential lifting for per-request identity, the Via loop marker, and the refusal of a known credential outside its header, placement.go). Importcodec/allfor postgres, mysql, mssql and http, or one package for one protocol so a binary fronting Postgres never links the TDS, MySQL and HTTP machinery.- gRPC deliberately has no
inspect.Codec. Its HTTP/2 endpoint and reusable protocol mechanics live inlibhoop/v2/codec/grpc;daemon/injects callbacks that entergate.EvaluateStatement, policy, audit, and masking. Adding a registry decoder tocodec/allwould restore the connection-fatal denial and nested-length masking bugs ADR-0013 rejects. - Adding a protocol is not one package. The codec seam is the smallest
part of it. A lane also needs a lexer
Dialect(selected ininspect.AnalyzeSQL), a deny frame inproxy/deny.go, an analyzer content builder inanalyzer/content.go, and theProtocolconstant aliased ininspect/wiretypes.go. Every one of those fails QUIETLY when it is missing: the wrong dialect misreads a statement, a missing deny frame closes the socket with no message, a missing builder makesai_analysisrules classify nothing. README.md's Protocols section carries the table. A new protocol also needs a label indaemon/schema.goprotocolLabels. - ICA is an endpoint lane that embeds an engine and has no codec. A
Citrix session carries pixels and no statements, so Validate refuses
guardrail rules, mask rules, an analyzer and OPA on a
protocol: icalane.daemon/ica.goholds the whole contract (config blocks,ICALane/ICAServer,RegisterICAEngine, the audit bridge), and the engine (sidecar/ica, a nested module ongithub.com/hoophq/libhoop-ica) registers frominit.Protocols()listsicain every build, so the plane renders its form; the capabilities header listsprotocol:icaonly when an engine is registered, so the plane does not serve an ica lane to a build thatcheckICAwould refuse. The engine's builder must not bind a socket or load a model: Validate constructs it on the plane and on macOS. - A new
ListenerConfigfield needs a UI tag. The control plane renders its listener form fromdaemon/schema.json. Tag the fieldlabel:"...", orui:"-"to keep it out of the form, then regenerate:go test ./daemon -run TestListenerSchemaIsCurrent -update. - Every config field omits its zero value, and a field an older build
must not receive carries
cap:. The control plane serves its own copy ofdaemon.Config, and a build that predates a key refuses the whole document over it (ADR-0022).omitemptyon scalars, pointers, slices and maps;omitzeroon structs, and onrules, where[]is an opt-out.TestEveryConfigFieldOmitsItsZeroValuerefuses a field with neither. Every new field also getscap:"<name>", unless it ships in the same release as a tagged block around it: omitting the zero value hides an unset key, but an older build still refuses the key once an admin sets it. That missing tag letgoogle_identity,trust,mcp,postgresandssh.relaycrash older sidecars (EVL-338). The header the sidecar sends on its handshake is generated from the tag, and the plane refuses to serve a document that sets it to a build without the entry.make test-sidecar-compat(CI jobsidecar-compat) decodes a document with every field set using the previous release, and fails on a new field without the tag. A field that already shipped also carriessince:"<release>", the release read from the git tags, so a build from before the header is refused it by its reported version; a new field leavessinceoff until its release exists. Rule types and protocols reach the header on their own, throughpolicy.RuleTypesanddaemon.Protocols.baselineCapabilitiesis frozen: it names what the builds before the header decode, each entry with the release it shipped in when that is later than 1.162.0, and nothing is ever added to it. - Construct codecs through the seam, never libhoop directly. A decoder
built with the zero
Optionshas no classifier: it reports statement text withOpUnknown. That fails closed, but it means a policy namingselectmatches nothing. - A plug-in protocol is config-level, never build-level.
plugins:names the module and itsx-protocol;Setuploads the module on the host, andValidateaccepts the lane from the entry alone because the control plane never loads one. So anx-protocol is NOT inProtocols(), not inschema.json, not aprotocol:header entry and never inbaselineCapabilities: the plane grants it by thepluginscapability. Adding it to any of those lists makes the build claim a protocol it does not link. - The license verifier exists twice, on purpose.
sidecar/licensereimplementscommon/licenseover the stdlib: same key, same RSA-PSS signature over the same bytes, same JSON. Importing the gateway's module would end the one-dependency invariant, so the copy is the price. Drift locks paying customers out of features they bought and neither module can see it, soclient/licensecompatpins the two. Touch the key or the signing data on one side and you MUST touch the other. - The license verdict is a function of the clock.
license.Statusstores "the signature checked out" and derives everything else from the term, so a relay that has been up for months loses the caps the second its license lapses. Never cacheState()in a field or a lane: that cache is the bug this design exists to prevent.Runwatches the term and stops a process whose config the free tier would refuse, because re-applying the caps live would mean deleting guardrail and mask rules from a running proxy. - A verdict cannot be assembled, only earned.
Status.verifiedis unexported andlicense.Loadis the only thing that sets it, after checking the signature. Build aStatusliteral anywhere else and it reports invalid and grants nothing.Config.UseLicensetherefore takes alicense.Refand never aStatus: the control plane sends a document and the sidecar checks it, rather than believing whoever is on the connection. NEVER add a constructor that skipsVerify, and NEVER export the trust root; a test that needs a licensed process useslicense/licensetest, which signs for real under a key it installs for the duration of one*testing.T.
Layout
The module root holds no Go files: go.mod, this file and README.md only.
| Path | Does |
inspect/ | bytes to statements, plus the codec registry; the wire vocabulary every other package names |
lexer/ | SQL text to an effect and a relation list, without a grammar |
jsonsql/ | the SQL a JSON document carries (a field, a JSON-RPC tools/call), for any protocol; codec/http's http.sql is its first seam |
codec/ | registration seam: wires libhoop's decoders to the classifier; codec/http also wraps the Inspector with the relay's HTTP additions |
policy/ | statement to verdict; local rules, then OPA |
license/ | verifies the signed license that lifts the rule caps; a stdlib twin of common/license. internal/trust owns the key, licensetest signs for tests |
analyzer/ | the model-backed evaluator, third in the policy chain |
gate/ | orders inspection, policy, audit and masking into one decision |
proxy/ | TCP relay that pumps both directions through a Gate |
daemon/ | assembles the relay from config — sinks, evaluators, listeners — and is the CLI entry point |
session/ | one inspected connection and the identity behind it |
identity/ | resolves a request credential to the identity behind it; google/ verifies a Google OAuth2 bearer with tokeninfo; token/ matches a caller token against a file it re-reads |
audit/ | the write side of the trail |
store/ | the read side |
pii/ | detectors and maskers |
descriptors/ | resolves grpc.descriptors entries and plugins[].module values that are URLs; fetchers register by scheme, https is in the root, gcs/ is nested |
codec/wasm/ | nested module: the codec plug-in host (wazero) behind daemon.LoadCodecPlugin; abi/ABI.md is the contract, sdk/ the guest SDKs, examples/ one plug-in per guest language with its committed .wasm |
Conventions
- Comments say why, at length where the reasoning is not recoverable from the code. This module's comments carry design rationale on purpose; match that register rather than stripping it.
- Tests use
testingonly. No assertion library, in any module that the root can reach. - A masking or policy change needs a test that would fail without it.
gate/andinspect/bypass_test.goare where behaviour that an operator sees is pinned. inspect/bypass_test.goholds statements that evade classification. A new evasion belongs there, phrased as the verdict an operator would get.- Ask whether a piece is protocol-specific before you add it. Build
pieces that combine, the way the http and WebSocket codecs do and a lane
splits into more than one listener. The generic layers (
gate/,proxy/,policy/,inspect/) name no protocol: protocol knowledge stays in the codec and reaches them through an optional interface the gate asserts, as it doesReframer, or a sentinel inlibhoop/v2/codec/types. Logic that is not about the wire (JSON paths, SQL classification, guardrail matching) goes in a protocol-neutral package, with a thin seam per protocol. The design note and the PR say which pieces are reusable and which are protocol-bound. - sidecar protocol-specific parsers: if the code must be added to libhoop, the sidecar parsers must live under
libhoop/v2/*. - When adding new sidecar capabilities like guardrails, data masking, AI analyzer, check if the codec WASM in sidecar plugins has these same capabilities; we must ensure new capabilities like that need to be added to plugins as well.
Running it
Two compose stacks exercise the relay end to end, both outside this directory:
deploy/docker-compose/envoy-stack/: Envoy plus OPA plus the sidecar. It carries more than the Envoy demo, and the parts that do not need Envoy cannot be run on their own today. Splitting it is open work.deploy/docker-compose/metabase-stack/: Metabase against a masked warehouse, with an asserting./demo.sh.
They share one image and one Dockerfile, so building hoop-inspect:local in
either serves the other.
scripts/dev/ holds four ordered scripts for the Vertex analyzer, which spend
real GCP calls. Read scripts/dev/README.md before running them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

