trustdex 0.4.2 → 0.4.4

package/README.md

@@ -75,8 +75,8 @@ Requires Node.js 20+.
 Run directly from npm:
 
 ```bash
-npx trustdex@0.4.2 --help
-npx trustdex@0.4.2 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
+npx trustdex@0.4.4 --help
+npx trustdex@0.4.4 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
 ```
 
 Or work from a source checkout:
@@ -100,6 +100,23 @@ Exit codes for inspection:
 - `1` - at least one entry needs review
 - `2` - at least one entry is blocked, or the command failed
 
+## Reproducible defensive research
+
+TrustDex includes an inert adversarial benchmark for testing the policy boundary without contacting or executing third-party services. The fixtures use reserved `.invalid` domains, placeholder credentials, and configuration data only; TrustDex inspects them statically and never launches the listed servers.
+
+```bash
+npm run test:research
+
+node ./bin/trustdex.mjs inspect \
+  ./examples/adversarial/mcp-config.json \
+  --pack strict \
+  --policy ./examples/adversarial/policy.json
+```
+
+The direct inspection intentionally exits with code `2`: the checked-in expectation is one `ALLOW`, one `ASK`, and five `BLOCK` decisions. The automated test also verifies that placeholder secret values do not appear in results and that a newly introduced secret-bearing environment variable invalidates the previous review state.
+
+See the [defensive security research policy](docs/SECURITY_RESEARCH.md), [evaluation record](docs/EVALUATION.md), and [adversarial fixture guide](examples/adversarial/README.md).
+
 ## Built-in policy packs
 
 ```bash
@@ -147,6 +164,8 @@ node ./bin/trustdex.mjs gate-codex ./examples/codex.config.toml \
 
 The gate removes non-approved MCP sections while preserving unrelated TOML sections. TrustDex intentionally parses only the MCP-related TOML constructs it needs; unsupported MCP syntax fails rather than being silently trusted.
 
+See [Using TrustDex with Codex](docs/CODEX.md) for a step-by-step gating workflow and for how this project uses Codex in its own review process.
+
 ## Online provenance observations
 
 Normal inspection remains local-only. These commands perform an explicit network lookup only when invoked:
@@ -292,7 +311,7 @@ The private key should never be committed.
 ```yaml
 - uses: actions/checkout@v4
 
-- uses: grigent/trustdex@v0.4.2
+- uses: grigent/trustdex@v0.4.4
   with:
     config: ./mcp.json
     pack: official-first
@@ -320,7 +339,7 @@ The public roadmap is maintained in [docs/ROADMAP.md](docs/ROADMAP.md). Near-ter
 
 TrustDex does **not** prove that third-party code is safe and does not replace sandboxing, dependency scanning, code review, or least-privilege credentials.
 
-See [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), and [docs/TRUST_STORE.md](docs/TRUST_STORE.md).
+See [SECURITY.md](SECURITY.md), [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md), [docs/SECURITY_RESEARCH.md](docs/SECURITY_RESEARCH.md), [docs/EVALUATION.md](docs/EVALUATION.md), and [docs/TRUST_STORE.md](docs/TRUST_STORE.md).
 
 ## Contributing
 

package/bin/trustdex.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
@@ -27,7 +28,8 @@ import {
   verifyTrustRecord
 } from '../src/trust-record.mjs';
 
-const VERSION = '0.4.0';
+// Read the version from the package manifest so --version cannot drift from releases.
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 function usage() {
   console.log(`TrustDex v${VERSION}

package/docs/CODEX.md

@@ -0,0 +1,73 @@
+# Using TrustDex with Codex
+
+This guide covers two things: gating the MCP servers a Codex client may start, and how TrustDex itself is maintained with Codex.
+
+TrustDex is an independent project. It is not affiliated with, endorsed by, or certified by OpenAI, and an ALLOW decision is not an OpenAI or TrustDex safety certification.
+
+## Gate Codex MCP servers
+
+Codex clients read MCP server definitions from `[mcp_servers.<name>]` tables in `config.toml` (by default under `~/.codex/`). Every entry there can start a local process or connect to a remote endpoint with the credentials you give it.
+
+### 1. Inspect the current configuration
+
+```bash
+npx trustdex@0.4.4 inspect-codex ~/.codex/config.toml --pack strict
+```
+
+This reads the file locally and makes no network request. The output lists each MCP server, its source type, trust signals, and an ALLOW / ASK / BLOCK decision. Environment variable names may appear; their values never do.
+
+Use `--json` for machine-readable output and `--trust-store ./trust-store.json` to attach explicit publisher evidence (see [TRUST_STORE.md](TRUST_STORE.md)).
+
+### 2. Write a gated copy
+
+```bash
+npx trustdex@0.4.4 gate-codex ~/.codex/config.toml \
+  --pack official-first \
+  --trust-store ./trust-store.json \
+  --out ./gated-config.toml
+```
+
+The gated file keeps unrelated TOML sections (models, features, profiles) unchanged and removes every MCP section that is not ALLOW. `ASK` entries stay out unless you pass `--include-ask`, which should only be used when another approval layer exists.
+
+Review the difference before using it:
+
+```bash
+diff ~/.codex/config.toml ./gated-config.toml
+```
+
+TrustDex never edits `config.toml` in place. Replacing the original file, or pointing a Codex installation at the gated copy, is an explicit step you take after review.
+
+### 3. Re-run after every change
+
+MCP entries change when a package version is bumped, a launcher is swapped, or a new environment variable is passed. Re-run `inspect-codex` and `gate-codex` whenever `config.toml` changes; a CI job or a pre-commit hook in a dotfiles repository works well for this.
+
+The signed `snapshot`, `approve`, and `recheck` drift workflow in the [README](../README.md#capability-and-provenance-drift) currently accepts MCP JSON only. Extending it to Codex `config.toml` is tracked in the [roadmap](ROADMAP.md).
+
+### Fail-closed parsing
+
+TrustDex parses only the TOML constructs used by Codex MCP sections. An unsupported MCP key, nested subsection, or syntax is reported as an error instead of being skipped, so a configuration TrustDex cannot fully read never silently becomes ALLOW.
+
+### Skills and plugins
+
+Agent skills and plugin manifests can be inspected the same way:
+
+```bash
+npx trustdex@0.4.4 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.4.4 inspect-plugin ./path/to/plugin.json --pack strict
+```
+
+These report observable signals such as piped shell installers, references to sensitive paths, network URLs, and wildcard tool scopes. They do not prove a skill or plugin is safe.
+
+## Gate MCP configuration in CI
+
+Repositories that ship an MCP configuration for agents can gate it on every pull request with the [TrustDex GitHub Action](../README.md#github-action). Pin the action to a reviewed commit SHA.
+
+## How TrustDex is maintained with Codex
+
+TrustDex uses Codex as a reviewer and maintainer assistant, with the same trust boundary it asks users to apply:
+
+- [AGENTS.md](../AGENTS.md) holds the development rules and a **Review guidelines** section that Codex code review applies to TrustDex pull requests. The guidelines turn the project's security invariants (no silent ALLOW, no secret values in output, no provenance override of blocking signals, fail-closed parsing, pinned actions) into explicit review findings.
+- Codex suggestions are treated like any other contribution: they go through a pull request, must pass the cross-platform CI matrix and CodeQL, and are merged only after maintainer review.
+- Codex does not hold release credentials. npm publication uses Trusted Publisher OIDC with Sigstore provenance from `.github/workflows/publish.yml`, triggered by a maintainer.
+
+If you contribute with Codex or another coding agent, the same AGENTS.md rules apply to your changes.

package/docs/EVALUATION.md

@@ -0,0 +1,35 @@
+# Defensive evaluation
+
+This evaluation records the behavior enforced by the checked-in adversarial fixtures. Run `npm run test:research` to reproduce it. The test performs local static inspection only and does not execute or contact any configured server.
+
+## MCP policy cases
+
+The cases use the built-in `strict` policy with the small overlay in `examples/adversarial/policy.json`.
+
+| Case | Required evidence | Expected decision | Reason |
+| --- | --- | --- | --- |
+| `trusted-pinned-package` | pinned package; explicitly trusted package name | `ALLOW` | the configured version is fixed and the policy contains an explicit package trust rule |
+| `floating-version` | `install-on-run`, `unbounded-version` | `BLOCK` | a moving package version can change without review |
+| `shell-launcher` | `shell-execution`, `filesystem-path` | `BLOCK` | shell execution is blocked by the strict policy |
+| `credential-bearing-url` | `embedded-credentials`, `network-endpoint`, `url-query-parameters` | `BLOCK` | embedded credentials are blocking even when the host is allowlisted |
+| `insecure-remote` | `insecure-transport`, `network-endpoint` | `BLOCK` | plaintext transport is blocking even when the host is allowlisted |
+| `sensitive-local-env` | `filesystem-path`, `secret-env` | `ASK` | a local extension with a secret-like environment name requires review |
+| `unknown-remote` | `network-endpoint` | `BLOCK` | the remote host has no explicit allowlist or provenance evidence |
+
+Expected total: one `ALLOW`, one `ASK`, and five `BLOCK` decisions.
+
+## Drift case
+
+The drift fixture begins with the trusted pinned package and then introduces an `API_TOKEN` environment key. The regression test requires all of the following changes:
+
+- `signals-added` for `secret-env`
+- `decision-changed` from `ALLOW` to `ASK`
+- `fingerprint-changed`
+
+The placeholder value itself must not appear in either inspection result or snapshot.
+
+## What this does not measure
+
+This benchmark is intentionally narrow. It does not measure runtime behavior, sandbox escape, arbitrary malware, every form of prompt injection, publisher identity ownership, or vulnerabilities in transitive dependencies. In particular, tool descriptions returned dynamically by an already-running MCP server are outside the current static configuration boundary.
+
+The small fixture set is a regression baseline, not a statistical claim about detection accuracy. False-positive and false-negative rates require a larger, independently reviewed corpus of redacted real-world configurations.

package/docs/RELEASING.md

@@ -30,12 +30,29 @@ Once trusted publishing works, remove the `NPM_TOKEN` repository secret and revo
 
 Both release workflows run `npm pkg fix` and require a clean `package.json` diff before packing or publishing. This prevents npm from silently normalizing away critical metadata such as the CLI entrypoint.
 
-## Provenance
+## Provenance and release evidence
 
 The repository is public and the package is public, so GitHub-hosted publishing can emit npm provenance. The workflow also passes `--provenance` explicitly.
 
 Provenance links the published artifact to its source/build environment. It does not prove that the package contains no malicious behavior.
 
+The GitHub release workflow also creates and uploads:
+
+- the npm package tarball built from the release commit
+- a CycloneDX JSON SBOM
+- a `SHA256SUMS` file covering the tarball and SBOM
+- a GitHub build-provenance attestation for the tarball
+- a GitHub SBOM attestation binding the SBOM to the tarball
+
+After downloading a release, verify its checksum and GitHub attestation before inspection or installation:
+
+```bash
+shasum -a 256 -c SHA256SUMS
+gh attestation verify trustdex-<version>.tgz --repo grigent/trustdex
+```
+
+The npm provenance statement and GitHub attestations cover different publication paths. Neither is a malware analysis or a substitute for reviewing the release contents and the documented trust boundary.
+
 ## Version checklist
 
 Before each release:

package/docs/ROADMAP.md

@@ -19,6 +19,7 @@ TrustDex is early-stage. This roadmap communicates direction and is not a releas
 
 ## Later: expand interoperability
 
+- extend signed snapshot, approval, and recheck workflows to Codex `config.toml`
 - add adapters for additional agent runtimes and registries
 - publish a compatibility matrix backed by tests
 - define machine-readable decision output for CI and policy tooling
@@ -30,4 +31,4 @@ The project is seeking pilot users willing to share non-sensitive feedback about
 
 ## How to help
 
-Open a focused issue describing the use case and redacted configuration shape. For security-sensitive proposals, include the expected trust boundary and bypass cases.
+If you ran TrustDex on a real configuration, the **Pilot feedback** issue form is the fastest way to report results. Otherwise, open a focused issue describing the use case and redacted configuration shape. For security-sensitive proposals, include the expected trust boundary and bypass cases.

package/docs/SECURITY_RESEARCH.md

@@ -0,0 +1,60 @@
+# Defensive security research
+
+TrustDex is developed for legitimate defensive research into trust decisions made before AI agents receive access to third-party tools. This document defines the authorization, safety, and disclosure boundaries for that work.
+
+## Purpose
+
+The research asks whether observable configuration, provenance, integrity, and capability evidence is sufficient to keep an extension unavailable until a human or policy explicitly trusts it. Current work focuses on:
+
+- unpinned or substituted packages
+- install-on-run and shell launchers
+- embedded URL credentials and insecure remote transport
+- secret-bearing environment variable names without retaining their values
+- source, provenance, decision, fingerprint, and capability drift
+- signed review records and re-review after trust-relevant change
+- parser behavior that must fail closed on unsupported syntax
+
+The intended outputs are reproducible fixtures, regression tests, documented limitations, and practical mitigations for agent developers and operators.
+
+## Authorization boundary
+
+Research is limited to:
+
+- systems and accounts owned by the researcher; or
+- systems for which the researcher has explicit authorization to test; and
+- isolated local or purpose-built test environments using non-sensitive fixtures.
+
+TrustDex research does not authorize testing unrelated public systems. It excludes credential theft, persistence, destructive actions, data exfiltration, mass exploitation, unauthorized access, malware deployment, and bypassing another party's safeguards.
+
+## Safe test data
+
+Checked-in adversarial fixtures are inert configuration documents. They use reserved `.invalid` domains, nonexistent package namespaces, and unmistakable placeholder values. TrustDex does not execute MCP servers during inspection.
+
+Tests assert that secret-like values, URL credentials, query values, and private paths do not appear in inspection results. A fixture that requires a real credential, private endpoint, personal data, or production service is not acceptable for this repository.
+
+## Method
+
+Each research case should contain:
+
+1. a minimal, reviewable input fixture
+2. the expected trust-relevant signals
+3. the expected `ALLOW`, `ASK`, or `BLOCK` decision under a named policy
+4. an automated regression test
+5. a documented limitation or plausible bypass condition
+
+An `ALLOW` result means only that observed evidence matched the selected policy. It is never represented as proof that arbitrary code is safe.
+
+## Handling findings
+
+Potential TrustDex vulnerabilities that could put users at risk should follow [SECURITY.md](../SECURITY.md). Findings in another project should be disclosed through that project's authorized security channel and should not be published before a reasonable coordinated-disclosure process.
+
+Public reports must remove credentials, private endpoints, proprietary prompts, personal data, and exploit details that would create unnecessary risk. Research notes should prefer the minimum evidence needed to reproduce and fix the issue.
+
+## Current reproducible evidence
+
+- [Adversarial MCP fixtures](../examples/adversarial/README.md)
+- [Evaluation record](EVALUATION.md)
+- [Threat model](THREAT_MODEL.md)
+- [Security policy](../SECURITY.md)
+
+The project welcomes verifiable pilot feedback, including false positives and false negatives, through the repository's Pilot feedback issue form. Popularity, branding, and unverifiable testimonials are not treated as security evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "test": "node --test",
+    "test:research": "node --test test/research-fixtures.test.mjs",
     "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/codex-config.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
     "prepublishOnly": "npm test && npm run check"
   },