TenantGuard

Install • Quickstart • Features • CLI Reference • MCP Server • Compare • FAQ

Find the tenant-isolation gap in your self-hosted, multi-tenant AI-agent platform before an auditor, or an attacker, does.

Install

npm install -g tenantguard-cli

This is the recommended install. The tenantguard-cli npm package (currently 0.2.0, renamed from the old plain tenantguard, which is deprecated) pulls in the matching platform binary as an npm optionalDependency (cosign-verified at publish time, so there's no separate verification step for you) and puts a tenantguard command on your PATH.

Platform coverage: macOS on Intel and Apple Silicon, Linux on x64 and arm64, and Windows on both x64 and arm64.

go install github.com/RudrenduPaul/TenantGuard/cmd/tenantguard@v0.2.0

go install works on every platform Go supports and doesn't depend on any registry publish state, so it's the fallback if your platform isn't covered above.

You can also skip the top-level package and install a single platform binary package directly:

npm install tenantguard-darwin-arm64   # swap for your platform: darwin-x64, linux-x64, linux-arm64, win32-x64, win32-arm64
./node_modules/tenantguard-darwin-arm64/bin/tenantguard scan --demo

Python (pip / uvx)

pip install tenantguard-cli
uvx --from tenantguard-cli tenantguard scan --demo

The PyPI package, tenantguard-cli, lives in this repo under python/ and is built and tested in CI. Its current version is 0.1.6, which downloads and runs the v0.2.0 build of the same GitHub Releases binary the npm packages use, verifying the release's SHA-256 checksums.txt on first run (itself Sigstore-signature-verified before any digest inside it is trusted) and caching the verified binary locally after that. That's a different trust boundary than the npm packages, which embed a cosign-verified binary at publish time and need no runtime download at all; the PyPI wrapper's checksum check is the equivalent guarantee for a path that has to fetch the binary on the end user's machine instead.

PyPI versions up to and including 0.1.2 shipped a bug that made pip install tenantguard-cli succeed but tenantguard scan --demo fail on first run with could not parse checksums.txt.pem as a PEM certificate (the wrapper wasn't base64-decoding the cosign-produced certificate/signature release assets before parsing them). That is fixed in tenantguard-cli 0.1.3, published to PyPI on 2026-08-03; pip install tenantguard-cli now installs a working tool with no extra steps.

Quickstart

tenantguard scan --demo

Real captured output:

TenantGuard: Tenant-Isolation Audit
Target: /var/folders/m0/5tzdd47n6znb166d4w3m2q0c0000gn/T/tenantguard-demo-488625596

[FAIL]  TA01 sandbox/workspace mount path is not scoped per-tenant (no ${TENANT_ID} placeholder and no explicit scoped_per_tenant declaration)
  .../deployment.yaml:12
  Maps to: goclaw#1163 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA02 MCP tool URL targets a private/loopback/reserved address (via real CIDR containment on a literal or DNS-resolved IP) without a verified, IP-pinned SSRF validator or an explicit host allowlist entry. CAVEAT: a PASS trusts the deployment's own pins_resolved_ip/validates_private declaration -- TenantGuard cannot verify the real validator actually pins the resolved IP for the connection itself, so DNS-rebinding/TOCTOU risk persists if that declaration is inaccurate
  .../deployment.yaml:22
  Maps to: goclaw#1070 | HIPAA Sec164.312(e)(1) Transmission Security (provisional)

[FAIL]  TA03 cron binding's target agent does not belong to the declaring tenant
  .../deployment.yaml:35
  Maps to: goclaw#1217 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA04 exec tool denies direct env dump but not indirect env reads (e.g. jq $ENV), or allows credential-chain leakage via allow_chain_exec (goclaw#1033)
  .../deployment.yaml:25
  Maps to: goclaw#1227 | HIPAA Sec164.312(a)(2)(iv) Encryption/Decryption (provisional)

[FAIL]  TA05 exec-approval allow-always entry is keyed on basename only, not a full path scope
  .../deployment.yaml:30
  Maps to: goclaw#1216 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA09 sandbox fail-closed posture not declared (sandbox.on_unavailable must be "fail_closed")
  .../tenantguard-demo-488625596:0
  Maps to: goclaw#246 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA10 agent does not explicitly declare a per-agent config override (workspace restriction or sandbox config), risking silent inheritance of an undeclared global default
  .../deployment.yaml:40
  Maps to: goclaw#145 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA13 MCP/CLI bridge does not declare HMAC-signed context headers (bridge.hmac_enabled and bridge.context_headers_signed)
  .../tenantguard-demo-488625596:0
  Maps to: goclaw#91 | HIPAA Sec164.312(e)(1) Transmission Security (provisional)

[FAIL]  TA06 cron binding does not declare that its store layer captures/replays the human creator's sender identity at fire time
  .../deployment.yaml:35
  Maps to: goclaw#1129 | HIPAA Sec164.312(b) Audit Controls (provisional)

[FAIL]  TA07 sandbox container privilege is not hardened (root user by default, full host-env passthrough, tmpfs missing noexec/nosuid/nodev, or a dangerous Linux capability added)
  .../deployment.yaml:12
  Maps to: goclaw#1014 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA11 channel/session device identity is shared across channel_instances declaring different tenants
  .../deployment.yaml:54
  Maps to: goclaw#1064 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA11 channel/session device identity is shared across channel_instances declaring different tenants
  .../deployment.yaml:57
  Maps to: goclaw#1064 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA15 channel_instances entry does not declare reload_strategy: differential, so any single create/update/delete on that entry triggers a full stop/restart of every running channel instance across all tenants (no per-instance fingerprint/diff step). CAVEAT: a PASS trusts the deployment's own reload_strategy declaration -- TenantGuard cannot verify the real InstanceLoader actually performs a differential (fingerprint-diffed) reload rather than the destructive full rebuild, so a mismatched declaration would still scan clean
  .../deployment.yaml:54
  Maps to: goclaw#1147 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[FAIL]  TA15 channel_instances entry does not declare reload_strategy: differential, so any single create/update/delete on that entry triggers a full stop/restart of every running channel instance across all tenants (no per-instance fingerprint/diff step). CAVEAT: a PASS trusts the deployment's own reload_strategy declaration -- TenantGuard cannot verify the real InstanceLoader actually performs a differential (fingerprint-diffed) reload rather than the destructive full rebuild, so a mismatched declaration would still scan clean
  .../deployment.yaml:57
  Maps to: goclaw#1147 | HIPAA Sec164.312(a)(1) Access Control (provisional)

[PASS]  1 check(s) clear

Summary: 14 FAIL, 1 PASS
Findings map to confirmed open goclaw issues where applicable. HIPAA citations are provisional, see README.

The bundled fixture is deliberately noisy: it exists to exercise nearly every rule at once. TA08 (credential-storage encryption) and TA14 (per-agent resource-profile isolation) are per-entry checks that only fire against providers and resource_profiles entries in the scanned config, and this fixture declares zero entries of either kind, so both rules have nothing to evaluate and produce no finding at all, neither PASS nor FAIL. TA16 (provider connection SSRF) is the same kind of per-entry check against providers entries, so it also produces nothing on this fixture. The one line shown as passing, "1 check(s) clear," is TA12 (owner/sysadmin recovery), which the fixture's owner_ids and has_recovery_command values are deliberately set to satisfy. Exit code is 1, since findings are present; see CLI Reference for the full exit-code contract.

Scan a real deployment and emit SARIF for code scanning instead:

tenantguard scan --target ./deployment --format sarif --sarif-out tenantguard-report.sarif

Or emit plain JSON, for a script or agent that would rather parse a flat findings array than a SARIF document:

tenantguard scan --target ./deployment --format json

Features

TenantGuard scans a self-hosted, multi-tenant AI-agent deployment's configuration against 16 rules, each derived from a real, confirmed tenant-isolation failure mode. Every rule is fail-closed: an undeclared or ambiguous setting is a violation, not a silent pass.

Tenant isolation boundaries

Network and credential exposure

Execution and approval hardening

Identity, audit, and recovery

Other verified capabilities:

• SARIF 2.1.0 output (--format sarif), schema-valid, with real byte/line locations and messages, ready for github/codeql-action/upload-sarif and GitHub code scanning.
• Plain JSON output (--format json), a schema-light alternative to SARIF for a script or agent that just wants raw rule_id/status/file/line results without SARIF's tool/run/rule/taxonomy object model. Unlike SARIF (which only reports FAIL as a "result"), the JSON mode includes every PASS too, plus a summary.fail/summary.pass count. Available since v0.2.0. See the note under CLI Reference.
• Provisional HIPAA citations on every finding (--control hipaa), mapped per rule, marked provisional (see FAQ).
• Zero-setup demo mode (--demo) that scans a bundled synthetic deployment, no target config required.
• GitHub Action (action/action.yml) that installs a pinned version via go install and uploads the SARIF report automatically.
• MCP server mode (tenantguard mcp) that exposes the same scan engine as a tool an AI agent can call directly over stdio, instead of only through a human typing tenantguard scan. Available since v0.2.0. See MCP server (agent-native usage) below.

CLI Reference

TenantGuard has two subcommands: scan (the audit itself) and mcp (runs the same scan engine as an MCP server over stdio, see MCP server (agent-native usage)). There is no top-level --help or --version flag; running tenantguard with no arguments, tenantguard --help, or any first argument other than scan or mcp prints the usage lines below to stderr and exits 2.

[!NOTE] Version note: --format json and the mcp subcommand shown below ship in v0.2.0 and later, which is what npm install -g tenantguard-cli (0.2.0), pip install tenantguard-cli (0.1.6, which downloads the v0.2.0 binary) and go install .../cmd/tenantguard@v0.2.0 install. Earlier versions (the 0.1.x npm packages and the v0.1.1 Go tag) do not have them: --format json is ignored there and mcp is not recognized as a subcommand.

usage: tenantguard scan [--target DIR | --demo] [--format terminal|sarif|json] [--control hipaa]
       tenantguard mcp

tenantguard scan --help output:

Usage of scan:
  -control string
    	compliance framework to cite (hipaa)
  -demo
    	scan a bundled synthetic deployment instead of --target (zero setup)
  -format string
    	output format: terminal, sarif, or json (default "terminal")
  -sarif-out string
    	file to write SARIF output to when --format=sarif (default "tenantguard-report.sarif")
  -target string
    	path to the deployment config directory to scan

Exit codes (defined in cmd/tenantguard/main.go):

MCP server (agent-native usage)

[!NOTE] Available since v0.2.0. The mcp subcommand ships in the npm, PyPI and go install releases listed in Install. Versions before v0.2.0 do not have it and print a usage error if you try.

Everything above assumes a human typing tenantguard scan at a terminal. TenantGuard also runs as an MCP server, so an AI agent (a coding assistant, an ops agent, anything that speaks the Model Context Protocol) can call the scan engine directly as a tool call, instead of shelling out to the CLI and parsing text.

tenantguard mcp

This starts an MCP server on stdio and blocks until the client disconnects, the same way any other stdio-based MCP server runs under its client's process supervision. It takes no flags or positional arguments. Under the hood it's a thin protocol adapter (internal/mcpserver) over the exact same internal/collector -> internal/policy -> internal/compliance -> internal/report pipeline the CLI's scan subcommand runs; there's no separate rule-evaluation logic to keep in sync.

It exposes a single tool, scan, with three arguments that mirror the CLI's own flags:

For json and sarif output, the result is returned both as text and as MCP StructuredContent, so a client that wants to read fields directly (rule_id, status, file, line) doesn't have to re-parse the text block itself. Tool-level failures (a bad target path, a policy load error) come back as a normal MCP error result, not a protocol-level failure, so a calling agent can handle "scan failed" the same way it handles any other failed tool call.

To register TenantGuard with an MCP-compatible client such as Claude Desktop, add it to the client's server config:

{
  "mcpServers": {
    "tenantguard": {
      "command": "tenantguard",
      "args": ["mcp"]
    }
  }
}

This assumes tenantguard is already on your PATH (see Install). If you installed it somewhere else, replace "command" with the full path to the binary.

Before this shipped, the only way to run a scan was a human invoking the CLI directly. With tenantguard mcp, an agent can call scan as a tool, get structured findings back, and act on them in the same session, without a person reading terminal output and typing the next command by hand.

How TenantGuard compares

TenantGuard trades breadth for depth: 16 rules is a fraction of Checkov's 1,000+, and TenantGuard is three tagged releases old against Checkov, Conftest, and PolicyGuard's much longer track records. What TenantGuard has that none of the others do is a rule pack purpose-built for cross-tenant isolation in self-hosted AI-agent deployments, a surface none of the general-purpose IaC scanners cover and even AgentShield, the closest domain match, stops short of: it audits a single developer's local config, not cross-tenant isolation in a self-hosted, multi-tenant deployment. That is the niche TenantGuard targets, narrowly and on purpose.

Precision/recall benchmarks for TenantGuard's own rule set against labeled fixtures are not yet published; where a competitor above reports a number (e.g. PolicyGuard's precision/recall), figures are quoted from that project's own README, not independently re-verified here.

What is TenantGuard and why does it exist

TenantGuard is a command-line policy-as-code scanner, written in Go and built on OPA/Rego, that audits a self-hosted multi-tenant AI-agent platform's configuration for tenant-isolation defects: the class of bug where one tenant's agent, sandbox, cron job, or credential can reach or affect another tenant.

TenantGuard exists because a real, confirmed multi-tenant AI-agent platform (goclaw) has had multiple open, unresolved issues in exactly this category, including a sandbox mount not scoped per tenant, a cross-agent authorization gap, an exec tool that leaks secrets through an indirect path, an approval bypass keyed on a filename instead of a real path scope, and an SSRF validation mismatch on saved tool URLs and LLM provider connections. No existing general-purpose IaC scanner (Checkov, Conftest, PolicyGuard) or AI-agent security scanner (AgentShield) checks for this specific failure category: cross-tenant isolation in a self-hosted, multi-agent deployment. TenantGuard fills that gap with 16 fail-closed rules, each traceable to a real, cited issue.

TenantGuard is not a generic Terraform/Kubernetes scanner and does not replace Checkov or Conftest for general cloud-infrastructure misconfiguration. It is scoped specifically to the tenant-isolation surface of self-hosted multi-tenant agent deployments.

FAQ

How is TenantGuard different from a generic IaC scanner like Checkov or Conftest? Checkov and Conftest scan general infrastructure-as-code (Terraform, Kubernetes, CloudFormation, and similar) for broad categories of misconfiguration. Neither ships a rule pack for multi-tenant AI-agent deployments. TenantGuard's 16 rules are purpose-built for that one surface: sandbox mounts, cron/agent bindings, MCP tool registrations, LLM provider connections, exec approvals, and channel/session identity, each derived from a real, cited defect.

Does TenantGuard replace OPA or Conftest? No. TenantGuard's rules are written in Rego and TenantGuard bundles its own evaluation path; it is a purpose-built policy pack and CLI, not a general-purpose Rego test harness. If you need to test arbitrary structured config against arbitrary Rego policies, Conftest is the right general tool. TenantGuard is the right tool specifically for tenant-isolation checks on a multi-agent deployment.

What does the HIPAA citation on each finding mean? Every finding is annotated with a related HIPAA Security Rule citation (e.g. Sec164.312(a)(1) Access Control) to help map a technical finding to a compliance control a reviewer may already track. These citations are marked provisional: they indicate a plausible mapping between the technical control and the cited HIPAA section, not a legal or audited compliance determination. Treat them as a starting point for your own compliance review, not a substitute for one.

Does a PASS on TA02 (SSRF) mean the MCP tool URL is actually safe from DNS rebinding? Not fully. TA02 uses real CIDR containment against a literal or DNS-resolved IP, not string matching, but a PASS trusts the deployment's own pins_resolved_ip/validates_private declaration. TenantGuard cannot independently verify that the real validator pins the resolved IP for the actual connection, so a DNS-rebinding/TOCTOU risk persists if that declaration is inaccurate. This limitation is documented directly in the TA02 rule.

Can I scan a real deployment instead of the bundled demo? Yes: tenantguard scan --target <path-to-deployment-config-dir>. --demo exists so you can see the tool run with zero setup before pointing it at a real config.

Does TenantGuard produce output a CI pipeline or GitHub code scanning can consume? Yes. --format sarif --sarif-out <file> produces a schema-valid SARIF 2.1.0 document with real result locations and messages. The bundled GitHub Action (action/action.yml) runs a scan and uploads the SARIF report via github/codeql-action/upload-sarif in one step.

Why does TenantGuard have both --format sarif and --format json? Isn't SARIF already structured output? Yes, SARIF is a real, standard, machine-parseable format, and it is the right choice for CI/code-scanning integration. --format json exists for a different consumer: a script or agent that wants to parse rule_id/status/file/line directly, without walking SARIF's tool/run/rule/taxonomy object model first. It also reports every PASS alongside every FAIL, which SARIF deliberately does not (SARIF results represent problems found, not a full checklist), so a caller can answer "what did you check" and not just "what did you flag" from one document. Note: --format json is available since v0.2.0, see the note under CLI Reference.

What do the CLI exit codes mean? 0 is a clean scan with no findings, 1 means the scan ran successfully and found violations, and 2 is a scan or usage error (including running tenantguard with no subcommand, or any subcommand other than scan or mcp).

Is there an npm package? Yes, npm install -g tenantguard-cli is live (currently 0.2.0) and is the recommended install path (renamed from the old plain tenantguard, which is deprecated). It depends on a matching platform binary package as an npm optionalDependency; all six platform packages are live (macOS x64/arm64, Linux x64/arm64, Windows x64/arm64). See Install above.

Is there a PyPI package? Yes, tenantguard-cli is live on PyPI (currently 0.1.6, which downloads the v0.2.0 binary; source under python/, built and tested in CI). Versions up to and including 0.1.2 had a first-run bug that is fixed in 0.1.3 (see Install above); pip install tenantguard-cli now works out of the box.

Can an AI agent run TenantGuard directly, without a human typing CLI commands? Yes, via tenantguard mcp, which starts an MCP server on stdio exposing the scan engine as a scan tool. See MCP server (agent-native usage) above for the exact client config and tool arguments, and for the versions that include it.

Is TenantGuard a library I can import into my own Go program? No, not currently. Everything outside cmd/tenantguard (the collector, compliance mapping, demo fixture, policy engine, and report formatting) lives under internal/, which Go's own tooling makes non-importable from outside this module. TenantGuard is distributed as a CLI binary and a GitHub Action, not an importable Go package.

Can I use TenantGuard in a commercial or closed-source product? Yes. TenantGuard is licensed under the Apache License 2.0, which permits commercial use, modification, private use, and redistribution, including inside a proprietary or SaaS product, subject to the license's standard notice and attribution terms (retaining the copyright notice and a copy of the license, and marking any modified files). It comes with no warranty, as stated in the license. See LICENSE for the full, authoritative terms.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to add a new rule; every rule needs both a vulnerable and a clean fixture before it ships.

License

Apache License 2.0. See LICENSE.