---
title: "Test controls with your own AI assistant"
summary: "Use Claude, Copilot, Cursor, or ChatGPT to run a Zovos control test on your own system, then submit the result and evidence for human review."
updated: "2026-10-07"
section: "Integrations"
url: "https://zovos.ai/docs-ai-control-testing.html"
---

# Test controls with your own AI assistant

*By Adam Swenson · 15 September 2026*

You can now perform a control test with the AI assistant you already use, whether that is Claude, GitHub Copilot, Cursor, or ChatGPT. You then submit the result to Zovos as evidence for that control's test period. Your assistant fetches the published procedure, runs the test with its own tools against your own system, and hands the result plus the raw output back to Zovos. There it lands **pending human review**. This is the **Zovos Evidence Protocol (ZEP)**. It consists of an open submission contract, a published [result schema](/schemas/evidence/control-test-result/v1.json), and a set of tools. Zovos never builds glue into your systems and never receives your system credentials.

This is for the compliance owner or tester who runs a control test today in the Zovos UI and wants to run it from the assistant on their own machine instead. It does not replace the reviewer. No external result changes a rating until a **different** person accepts it.

## The three-step flow

1. **Fetch the procedure.** Ask your assistant to call `query_controls` with `include_procedure=true`. It returns the control, its acceptance criteria, the expected evidence, population and sampling guidance, and the current `procedure_version`. A due-for-testing filter finds the work that is actually open.
2. **Run the test with the assistant's own tools, on your system.** The assistant gathers the evidence with its own shell, scripts, and connectors, which are already authenticated to *your* environment. Zovos supplies no probes and touches nothing on your side. Save the **raw** output to a file.
3. **Submit the result and artifacts.** The assistant uploads each evidence file out-of-band through a presigned upload, so the bytes never pass through the model or the transport. It then calls `submit_control_test_result`. Call it first with `confirm=false` to see the dry-run, then again with `confirm=true` to record it. The submission enters `pending_review`.

## What Zovos records

- **The tester of record is you.** That means the verified person behind your Zovos login, derived server-side from your sign-in. It is never something the assistant declares.
- **The assistant is self-declared and shown UNVERIFIED.** Its name, model, and version are recorded verbatim as metadata and are never an authorization signal.
- **Raw tool output is required.** A submission whose method is `TEST` or `AUTOMATED` must carry at least one `raw_tool_output` artifact. A narrative alone is not evidence. A fail or pass-with-exceptions outcome must also list at least one exception. There is deliberately **no confidence field**, because a model could fabricate a stated confidence. Assurance comes instead from the raw artifact, its server-computed hash, an append-only audit, mandatory review, and random re-testing.
- **A human distinct from you accepts it.** On acceptance the outcome maps to effectiveness. Pass maps to Effective, pass-with-exceptions to Partial, and fail to Ineffective. Not-tested and not-applicable never change a rating. Acceptance also means the control owner's **attestation cadence is satisfied for that period**. Until acceptance, attestations stay manual to the owner.
- **A failed test opens a draft Finding.** On accepting a fail or pass-with-exceptions, each exception becomes a draft Finding and linked risks are re-flagged.
- **Some accepted submissions are re-tested at random.** By default **5 %** of accepted submissions are flagged for a re-perform. Your administrator can move that anywhere from 0 to 100 %. A mismatch is recorded on both the control and the submission.

## What stays on your machine and what you must never upload

Your **system credentials never go to Zovos.** You authenticate to your own system with your own credentials on your own machine. Zovos receives only the result and the artifacts you attach.

Never upload:

- Do not upload credentials, tokens, API keys, cookies, or connection strings. Strip them before upload.
- Do not upload **SAR, BSA/AML, or CTR content**. It is legally confidential and must never be submitted.
- Do not upload customer PII beyond the minimum the control requires. Redact where you can.

Zovos enforces this on top of your care, not instead of it. Every uploaded artifact is content-sniffed and malware-scanned, and archives are expanded and scanned member by member. Every artifact then runs through a **credential / PII / SAR classifier**.

- A credential or SAR/CTR match is **refused**. The upload is rejected, and the error names the pattern *class*, never the matched secret. A reviewer cannot override a refusal.
- PII at or above a threshold is **quarantined**. It is stored but download-blocked, and it is flagged for a reviewer.

The skills enforce one more habit. Summarise counts in context and attach the full file out-of-band, so sensitive raw content stays out of your assistant's model context.

## Artifacts and limits

Evidence is referenced by `sha256` and uploaded with a presigned PUT. Zovos re-computes each hash server-side and rejects any mismatch. Give each file a role: `raw_tool_output`, `screenshot`, `export`, `transcript`, or `supporting`. The allowed types are PDF, PNG, JPEG, plain text, Markdown, CSV, JSON, XML, ZIP, XLSX, and DOCX. The cap is **50 MB** per file. A text-only client with no local files can instead pass an `inline_text` transcript up to 32 KB.

## Connect your AI assistant

There are two ways in. Most assistants speak the **remote connector** directly over OAuth. Claude Desktop and ChatGPT cannot run a local test on their own, so they use the local bridge. The coding-capable clients can both test and submit.

> **This section is the shared setup for every Zovos AI-assistant connection.** The full per-client walkthrough for Claude, ChatGPT, Cursor, Copilot, Gemini, and the local bridge is in [Connect your AI assistant](docs-connect-ai-assistant.html). The steps below are the ZEP-specific companion.

### Remote connector (Claude.ai, Claude Desktop, Claude Code, Cursor, VS Code Copilot, ChatGPT developer mode)

Point the client at the Zovos MCP endpoint and sign in with your Zovos account when prompted:

`https://app.zovos.ai/api/mcp`

| Client | Where to add it |
| --- | --- |
| Claude Code | `claude mcp add --transport http zovos https://app.zovos.ai/api/mcp` |
| Claude.ai / Claude Desktop | Settings → Connectors → Add custom connector → paste the URL |
| Cursor | `.cursor/mcp.json` → an `mcpServers` entry of type `http` with the URL |
| VS Code Copilot | `.vscode/mcp.json` → a server of type `http` with the URL |
| ChatGPT (developer mode) | Settings → Connectors → add an MCP server with the URL |

Your access token is short-lived. A well-behaved client refreshes it on its own, so a long test does not stall. Select your organization at sign-in. A session with no organization selected is refused with a message telling you to pick one.

### Local bridge (`npx zovos-mcp`)

Some clients cannot run the test themselves, such as Claude Desktop and ChatGPT. For those, the `zovos-mcp` bridge runs on your machine and logs you in with a device flow. It also adds a local `upload_artifact_file` helper that does the presigned upload MCP cannot do on its own.

- `npx zovos-mcp login` authorizes the CLI with your Zovos login.
- `npx zovos-mcp` starts the local server. Point your assistant at the command `npx -y zovos-mcp`.
- `npx zovos-mcp doctor` checks reachability, your token, and the tenant flags.

> **Availability.** The `zovos-mcp` package publishes to npm when Zovos announces the Evidence Protocol. The commands above are how it will read once it is published.

Whichever path you use, the bridge and the connector share the control-testing tools `query_controls`, `submit_control_test_result`, and `get_submission_status`. For evidence files, the connector exposes `begin_artifact_upload` and `commit_artifact`, and the bridge replaces both with its single `upload_artifact_file` helper.

## Turn it on for your workspace

An administrator enables this per workspace under **Settings → Integrations → AI assistants**. It is off until they opt in. Your account also needs a **verified email**, and a sign-in without one is refused. The re-test sampling slider (0 to 100 %, default 5 %) lives on the same screen.

## Example prompts

Load the [skill pack](/docs-ai-control-testing-skills.html) for the control's family first, then ask in plain language. These three prompts exercise the read tool, the submit tool (dry-run then confirm), and the status tool.

1. **Find work and fetch a procedure.** "Using the Zovos tools, list the controls that are due for testing this quarter, then fetch the full procedure package for the MFA-on-privileged-accounts control so we can run it."
2. **Run, dry-run, then submit.** "Run the asset-inventory procedure against our CMDB with your own tools, save the raw export, and upload it as `raw_tool_output`. Then call `submit_control_test_result` with `confirm=false` and show me the dry-run. I want to see the mapped outcome, the exception count, and whether it would satisfy the owner's attestation. After that, resubmit with `confirm=true`."
3. **Check the reviewer's decision.** "Check the status of that submission with `get_submission_status` and tell me whether the reviewer accepted it, requested changes, or flagged it for a re-perform."

Always review the dry-run before you confirm. The assistant should never submit silently.

## Exports for auditors

Once a submission is accepted, an examiner or your team can export it in two open shapes without the assistant ever having to emit them. **OSCAL Assessment Results** serve OSCAL-speaking programs, and **OCSF Compliance Finding** records serve a security data lake. Both are generated server-side from the same sealed submission, one per submission or batched across a control's test period.

## Troubleshooting

- **The access token carries no organization.** Sign in again and choose your institution. Zovos never defaults you into one.
- **This organization has not enabled ZEP control testing over MCP.** An administrator has not opted in yet. The switch is **ZEP control testing** in Settings → Integrations → AI assistants.
- **The access token's email address is not verified.** Verify your email with your identity provider, then sign in again.
- **The procedure version was rejected (409).** The procedure moved under you. The error hands back the current package. Re-run against it and resubmit.
- **An artifact was refused.** The classifier found a credential or SAR/CTR pattern. Remove it and resubmit. A reviewer cannot override a refusal.

## Related

- [Zovos Evidence Protocol skill packs](/docs-ai-control-testing-skills.html) has downloadable skills for all 17 control families.
- [Controls & continuous coverage](platform-controls.html)
- [AI assistants over MCP and ZEP control testing](platform-ai-assistants.html) is the product overview, and [control testing with your AI assistant](solution-ai-assistant.html) is the buyer-facing summary.
- [How AI works in Zovos](docs-ai-in-zovos.html)
- [Connecting integrations](docs-integrations.html)