# Vanta integration

signafAIde can send the status of each live project to your Vanta account once a day, so the state of your AI agent records sits beside your other controls. The connector is built to Vanta's published integration API. It uses a private integration that you create in your own Vanta account, so the data goes into your tenant and nowhere else.

Integrations are part of the Team and Enterprise plans. Only owners and admins of the organisation can connect, edit or disconnect, and each of those actions is written to the organisation's audit log.

## What appears in Vanta

One custom resource for each project that has live records. Each resource carries a few status values (four of them true or false), a link back to the project's Chain health page in the console, and nothing else. In Vanta you create one custom test for each true or false value, and map each test to the controls you choose.

Custom tests may need a Vanta plan that includes them. Vanta's documentation says so: check your Vanta plan before you start. Without custom tests the resources still arrive, and Vanta shows them as data with no pass or fail result.

## Connect

You need the Admin role in Vanta, and the owner or admin role in the signafAIde organisation.

1. In Vanta, open Settings, then Developer Console, and create an application. Choose Build Integrations as the type and Private as the distribution.
2. Generate a client secret. Keep the client ID and the client secret.
3. In the application's Resources tab, add a resource with the base type Custom Resource. Give it a name such as `signafAIde project`, and paste the schema below as its custom properties. Save it and copy its Resource ID.
4. In the signafAIde console, open Integrations (under Organisation), paste the client ID, the client secret and the resource ID, and press Connect.

Connect runs a first sync at once and shows Vanta's answer: how many resources were accepted and rejected, or the reason it failed and what to check. After that the sync runs every day, and soon after a status changes. Sync now runs it when you ask.

The client secret is stored encrypted. It is never shown again and never written to a log: the page shows only that it is set, and when. signafAIde asks Vanta for the scope `connectors.self:write-resource` only, so it can send resources and cannot read anything from your Vanta account.

## The schema

Paste this as the custom properties of the Custom Resource. It is in JSON Type Definition form.

```json
{
  "properties": {
    "agentsActive": {
      "type": "int32"
    },
    "agentsRecording": {
      "type": "int32"
    },
    "allAgentsRecording": {
      "type": "boolean"
    },
    "allChainsIntact": {
      "type": "boolean"
    },
    "blockedCalls": {
      "type": "string"
    },
    "chainsWithConflictOrGap": {
      "type": "int32"
    },
    "checkedCallsAllowed": {
      "type": "int32"
    },
    "checkedCallsBlocked": {
      "type": "int32"
    },
    "checkedCallsWouldHaveBlocked": {
      "type": "int32"
    },
    "lastRecordTime": {
      "type": "timestamp"
    },
    "latestReportResult": {
      "type": "string"
    },
    "latestReportSha256": {
      "type": "string"
    },
    "latestReportVerifies": {
      "type": "boolean"
    },
    "oldestUnconfirmedTimestampAgeMinutes": {
      "type": "int32"
    },
    "ruleSetHash": {
      "type": "string"
    },
    "ruleSetPublished": {
      "type": "string"
    },
    "ruleSetVersionInForce": {
      "type": "int32"
    },
    "ruleSetVersionsInPeriod": {
      "type": "string"
    },
    "timestampsConfirmedInTime": {
      "type": "boolean"
    }
  }
}
```

| Property | Type | Meaning |
|---|---|---|
| `allAgentsRecording` | boolean | Every agent with an active key sent a record in the last 24 hours, and there is at least one such agent. |
| `agentsActive` | int32 | Agents with an active key in the live environment. |
| `agentsRecording` | int32 | Of those, the agents that sent a record in the last 24 hours. |
| `allChainsIntact` | boolean | No agent chain had a conflict or a late record in the last 30 days. |
| `chainsWithConflictOrGap` | int32 | Agent chains with a rejected conflicting record, or a record that arrived later than the project's gap threshold, in the last 30 days. |
| `timestampsConfirmedInTime` | boolean | No batch has waited more than 24 hours for its confirmed public timestamp. |
| `oldestUnconfirmedTimestampAgeMinutes` | int32 | Age in minutes of the oldest batch without a confirmed public timestamp, or 0 when there is none. |
| `latestReportVerifies` | boolean | The latest verification report or audit pack made for the live environment has the result PASS. |
| `latestReportResult` | string | The result of that report: PASS, PENDING or FAIL, or NONE when no report has been made. |
| `latestReportSha256` | string | The SHA-256 of that report's JSON file, or empty when no report has been made. |
| `checkedCallsAllowed` | int32 | Tool calls checked in the last 30 days that were allowed. |
| `checkedCallsBlocked` | int32 | Tool calls checked in the last 30 days that were blocked, by the client's checks or by the witness's ruling. |
| `checkedCallsWouldHaveBlocked` | int32 | Calls the witness allowed while a rule was Calibrating that would have been blocked if it were On, in the last 30 days. |
| `ruleSetVersionInForce` | int32 | The newest published rule set version of the live environment, or 0 when none is published. |
| `ruleSetPublished` | string | When that version was published, or empty when none is. |
| `ruleSetHash` | string | The rules hash of that version's signed document, or empty when none is published. |
| `ruleSetVersionsInPeriod` | string | JSON list of the rule set versions in force in the last 30 days: set, version, published time, mode (Calibrating or On) and rules hash. |
| `blockedCalls` | string | JSON list of the newest 20 blocked calls of the last 30 days: time, agent, tool, rule ids, rule set, version and rules hash. Never the values a call disclosed. |
| `lastRecordTime` | timestamp | The time of the newest live record. |

The times and windows are fixed: an agent counts as recording when it sent a record in the last 24 hours, a conflict or late record counts against a chain for 30 days, and a public timestamp is expected to be confirmed within 24 hours. The gap threshold is the one set on the project's Alerts page (300 seconds unless you changed it). An agent whose key you revoked is no longer counted.

The ruling properties come from the tool-call checks: counts of calls in the last 30 days that were allowed, blocked, or allowed while a rule was Calibrating but would have been blocked if it were On, the rule set versions in force with their published time and rules hash, and the newest 20 blocked calls (time, agent, tool, rule ids, rule set version). They never carry a value a call disclosed. They are zero or empty for a project with no checks.

`latestReportSha256` ties the status to a file you hold. Download the verification report or the audit pack as JSON, run `sha256sum` on the file, and compare. Anyone can then check that file for themselves, as described in [Verify](/docs/verify).

## The tests to create

Vanta has no API for creating tests, so create these by hand: in Vanta open Tests, choose Create custom test, pick your private integration and the custom resource, and enter one rule for each test. A resource must have been synced once before Vanta offers it in the test builder, so connect first.

| Test name | Rule | Description | How to fix |
|---|---|---|---|
| signafAIde: every agent is recording | `allAgentsRecording equals true` | Every AI agent with an active signing key in the project sent a signed record to signafAIde in the last 24 hours. | Open the Agents page of the project in the signafAIde console and find the agents with no record in the last 24 hours. Start them again, or revoke the key of an agent that has been retired. |
| signafAIde: agent record chains are intact | `allChainsIntact equals true` | No agent's record chain had a conflicting record rejected, or a record that arrived late, in the last 30 days. | Open Chain health in the signafAIde console. Review each conflict and late record with the team that runs the agent and write down the cause. The status returns to true 30 days after the last one. |
| signafAIde: public timestamps are confirmed in time | `timestampsConfirmedInTime equals true` | Every batch of records older than 24 hours has a confirmed public timestamp. | Open the project overview in the signafAIde console to see what is waiting for a public timestamp. If the age keeps growing, write to sales@signafaide.co.uk. |
| signafAIde: the latest verification report passes | `latestReportVerifies equals true` | The latest verification report or audit pack made for the project has the result PASS. Its SHA-256 is in latestReportSha256. | Make a verification report or an audit pack in the signafAIde console for a period that ended at least a day ago, and check that its result is PASS. Keep the JSON file: its SHA-256 is the value of latestReportSha256. |

Custom tests cannot be changed once they are created in Vanta. Check the rule before you map a test to controls.

## What is sent and what is never sent

Sent, for each project with live records: the project's name, its identifier, a link to its Chain health page in the console, and the properties in the table above.

Never sent: record content, tool inputs, tool outputs, the names of tools, the names of agents, record fingerprints, keys of any kind, or anything about your users. The sync body is small enough to read: owners and admins can fetch it as described under [Send it yourself](#send-it-yourself) and see exactly what leaves.

Each sync sends the complete set of resources. That is how Vanta's resource sync works: a resource that is left out of a sync is treated by Vanta as gone. A project you delete in signafAIde therefore disappears from Vanta at the next sync.

## When the state is failing, paused or stale

The Integrations page shows the state of the sync, the time of the last success, and the last failure with its reason. The Delivery log lists every attempt. When the state changes to one of the three below, signafAIde emails the owners and admins of the organisation once, and once more when it works again. The console also shows a line at the top of every page.

- **Failing**: three attempts in a row failed, because Vanta did not answer or answered with a server error. Nothing is wrong with your settings. The sync is tried again within the hour. Press Sync now to try at once.
- **Paused**: Vanta rejected the client ID or secret, or did not find the resource. Nothing more is sent until you fix it. Check the three values against the application in Vanta: a secret that was replaced in Vanta has to be pasted again. Then press Connect. Vanta answers a wrong client ID and a wrong secret in the same way, so the page cannot say which of the two it is.
- **Stale**: no sync has succeeded for more than 26 hours, whatever the cause. Press Sync now. If it fails, the page shows why.

If Vanta rejects resources, the schema of the Custom Resource in Vanta differs from the one on this page. Compare them and correct the resource in Vanta.

## Send it yourself

You do not have to give signafAIde a Vanta credential. Fetch the same body with a live API key of any project in the organisation, and send it to Vanta from your own pipeline with your own token. This is also the way to use the integration with a witness you run yourself.

```sh
curl -s "https://api.signafaide.co.uk/v1/integrations/vanta/resources?resource_id=$VANTA_RESOURCE_ID" \
  -H "Authorization: Bearer $SIGNAFAIDE_LIVE_KEY" > vanta-body.json

curl -s -X PUT "https://api.vanta.com/v1/resources/custom_resource" \
  -H "Authorization: Bearer $VANTA_TOKEN" \
  -H "Content-Type: application/json" \
  --data @vanta-body.json
```

The first command returns exactly the body a sync sends: `resourceId` and the full list of `resources` for the organisation. A live key of one project therefore returns the status of every project in the organisation; it carries statuses only, never records. `resource_id` can be left out when Vanta is connected in the console. Get `$VANTA_TOKEN` from Vanta's token endpoint with your application's client ID and secret and the scope `connectors.self:write-resource`. Vanta allows one active token for each application, so let one job ask for tokens, and send the whole body every time.

## Disconnect

Press Disconnect on the Integrations page. The stored client secret is deleted at once and nothing more is sent. The resources already in Vanta stay there until you remove the resource or the application in Vanta.
