agentgate

**English** · [中文](README.zh-CN.md)

# agentgate

A control plane for the tools agents run. It inventories what is in use, records the evidence
behind every claim, states what a company refuses, and enforces that decision in CI and at
runtime.

The whole project follows one rule:

> `clean` is emitted only when every check ran. Anything that could not be measured is
> `unmeasured`, and an artefact with an unmeasured part is `incomplete` — never `clean`.

That rule is there because the usual failure of a security scanner is a green build for work
nobody did. Here a check that crashes makes the result incomplete, so it cannot happen quietly.

## The four parts

| part | what it does | package |
| --- | --- | --- |
| **inventory** | enumerate the registry, resolve packages, fetch repositories | `packages/collect` |
| **evidence** | join it into one record per server, with the bytes behind every claim | `packages/collect` |
| **policy** | scan configs, hooks, manifests and source for what a company would refuse | `packages/guard` |
| **verification** | check a claim against something outside the claim | `packages/verify` |

## Running it

Server setup is in [docs/operations/deployment-runbook.md](docs/operations/deployment-runbook.md).
The first deployment, on 2026-09-16, is written up in
[docs/verification.md](docs/verification.md) together with what was checked and what still is not.

## Try it without installing

The service runs at <https://xn--5kvo87g.com/>: landing page, pricing, the evidence index
(rebuilt daily) and the API on the same host.

<https://ciceroyang.github.io/agentgate/> is the landing page on GitHub Pages. The index is a
single browsable page at <https://ciceroyang.github.io/agentgate/evidence.html>, rebuilt daily
from the live registry — records are embedded, filtering happens locally, and there is nothing to
sign up for. [Pricing](https://ciceroyang.github.io/agentgate/pricing.html) and a
[ten-minute walkthrough](https://ciceroyang.github.io/agentgate/try.html).

## Quickstart

Node 20 or newer, no dependencies. A clone already carries a sample index, so the service
answers immediately; `refresh` replaces it with a current one.

```sh
node bin/agentgate.mjs serve
# agentgate serving http://127.0.0.1:8080

curl -s localhost:8080/health
curl -s localhost:8080/v1/index/summary
curl -s localhost:8080/v1/servers/<name>
curl -s localhost:8080/badge/<name>.svg
```

The package is on npm as `@zhiliangtech/agentgate`. Push a `v*` tag and CI publishes it with
provenance; [publish-checklist.md](docs/operations/publish-checklist.md) has the setup and the
record of what was verified.

```sh
npx @zhiliangtech/agentgate check --root .
npx @zhiliangtech/agentgate serve
```

`npx` follows the `latest` dist-tag. Pin a version (`@zhiliangtech/agentgate@0.2.0`) if you need
an exact one.

With no policy file, `check` uses a built-in default that refuses nothing extra, and `serve`
answers from the snapshot the package shipped with. `refresh` writes to `./data` next to you,
never into the installed package.

Docker works too, and runs the same command:

```sh
docker compose up                            # the service on :8080
docker compose --profile collect run --rm refresh   # rebuild data/index.json and seed the first snapshot
```

## Tool inventory

Run `node bin/agentgate.mjs serve` and open `/inventory.html` at the address it prints. Paste a
list of tool names or pick a text/JSON file, resolve ambiguous matches, fill in the version you
actually use, and download a standalone HTML report. The comparison happens in browser memory
against the embedded index snapshot: the list is not uploaded or stored, your machine is not
scanned, and no tool is executed. When a record carries a coverage block, the report also lists
which scanners ran and which did not, and why; a record whose own coverage block says a required
scanner did not finish will not be shown as matched, however complete the rest of its evidence looks.

The same thing without a browser:

```sh
node bin/agentgate.mjs inventory --input examples/inventory/tools.json --out my-tools.html
node bin/agentgate.mjs inventory --input tools.json --index data/index.json --format json
```

An input is one name per line, a JSON array, or `{ "tools": [...] }`. Each object may carry
`name`, `server`, `package`, `registry` and `version` — nothing else. Full client
configurations and credentials are rejected on purpose. The
[inventory guide](docs/spec/inventory-v1.md) has the details.

Unmatched, ambiguous, missing-version, mismatched-version and incomplete-evidence items stay in
the report. A version match is not proof of what is installed. The committed sample is
historical and cannot produce a confirmed match; neither can old evidence without an exact
content binding. Even a confirmed match is not a safety certification and not a new scan. Look
at the scopes, the findings, the snapshot date and the gaps before you rely on it.

Exit code 0 means a report was produced, not that every tool passed. Malformed input or
unreadable data exits 2, and `--out` will not overwrite an existing file. When you want CI to
refuse something, use `check`, not `inventory`.

### Getting the list in the first place

Nobody has this list by hand. `discover` reads the MCP configuration files already on the
machine and prints one line per server, in the format `inventory --input` accepts:

```sh
node bin/agentgate.mjs discover --out tools.txt          # home directory + current directory
node bin/agentgate.mjs discover --roots ~/code/a,~/code/b --format json
```

It never prints an `env` value, a header or an argument, and a remote address is cut down to its
host, because paths and query strings carry tokens. A file that exists but cannot be read or
parsed — including `.codex/config.toml`, which this version does not parse — is listed with a
reason and makes the command exit 2. A list that is missing something is not printed as a
complete list.

### Several repositories

```sh
node bin/agentgate.mjs audit --roots ~/code/a,~/code/b,~/code/c --index data/index.json
```

One scan per directory, one verdict for the set. Any incomplete directory makes the audit
incomplete, and a directory that does not exist counts as unmeasured rather than skipped.

### Changes since last time

```sh
node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive
node bin/agentgate.mjs watch --verify --archive ./archive
node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive \
  --webhook https://example.invalid/hook --webhook-format wecom
```

Every run appends one line to a chained archive (`prev` is the previous line's hash) and stores
what it saw under `snapshots/<sha256>.json`. `--verify` recomputes the chain and every retained
snapshot, and exits 1 if anything does not match. Nothing is sent anywhere unless `--webhook`
names an address, and the archive is written before the push, so a chat service being down cannot
lose a capture.

### Questionnaire mapping

```sh
node bin/agentgate.mjs framework                       # who answers which AI-CAIQ item
node bin/agentgate.mjs inventory --input tools.json --framework aicaiq --out report.html
```

For each AI-CAIQ item the mapping says what we can provide, where our coverage stops, and whether
the answer is ours, the customer's, or an independent assessor's. It describes evidence. It is
not a compliance conclusion and it does not reproduce the official text. All 58 items of the four
domains a reviewer asks a vendor about are classified: 13 answers are ours, 41 are the customer's
and 4 need an independent assessor.

### Evidence pack

The mapping says what we can provide. `pack` produces the thing itself: one directory a vendor
hands to the person reviewing them, where every answer we claim points at evidence in the same
directory and everything we could not measure is counted at the top.

```sh
node bin/agentgate.mjs pack --input tools.json --archive ./agentgate-archive --out agentgate-pack
node bin/agentgate.mjs pack --verify agentgate-pack     # recompute every hash and the seal
```

It writes `pack.json` (machine readable), `pack.html` (for the reviewer), `answers.aicaiq.md` (all
58 items, each classified), `manifest.txt` (one sha256 per file) and `manifest.sha256` (the seal on
the manifest). An answer whose evidence is missing reads `unmeasured` and the command exits 2, not
0. Example built from the live index:
[docs/samples/evidence-pack-example](docs/samples/evidence-pack-example) — verifiable with
`pack --verify`. Contract: [docs/spec/evidence-pack-v1.md](docs/spec/evidence-pack-v1.md).

## MCP server

Anything that speaks MCP can ask the index directly. Add this to `claude_desktop_config.json`, a
repo's `.mcp.json`, or whatever your client reads:

```json
{
  "mcpServers": {
    "agentgate": { "command": "npx", "args": ["--yes", "@zhiliangtech/agentgate@next", "mcp"] }
  }
}
```

Four read-only tools: `lookup_server` (one record, with its coverage block), `inventory_tools`
(match the tools you actually use), `coverage_report` (how much of the index was measured) and
`check_project` (scan a local directory). It reads the local index, never writes, never uploads,
and never runs a scanned tool. An incomplete record is reported as incomplete, and a record that
the index does not have is reported as missing rather than safe. Details:
[docs/spec/mcp-server-v1.md](docs/spec/mcp-server-v1.md).

## Policy

A policy states what a company refuses. It is data rather than code, and it has a spec:
[docs/spec/policy-v1.md](docs/spec/policy-v1.md).

```json
{
  "version": "agentgate.policy/v1",
  "threshold": "high",
  "required": { "pinnedPackages": true, "measuredEvidence": ["packageManifest"] },
  "forbidden": { "rules": ["AG-INSTALL-001"], "servers": ["internal/*"] }
}
```

```sh
node bin/agentgate.mjs check --policy agentgate.policy.json --root .
```

With no policy file and no `--policy`, the check sti