docs: commit all Phase 6 documentation updates and OpenSpec archives
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
191
docs/developers/guides/agntcy-compliance.md
Normal file
191
docs/developers/guides/agntcy-compliance.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# AGNTCY Compliance
|
||||
|
||||
This guide explains how to use AgentIdP's AGNTCY compliance features: exporting agent cards,
|
||||
generating compliance reports, verifying audit chain integrity, and checking SOC 2 control status.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A running AgentIdP instance
|
||||
- `COMPLIANCE_ENABLED` environment variable not set to `false` (enabled by default)
|
||||
- A valid Bearer token (for authenticated endpoints)
|
||||
- At least one registered agent
|
||||
|
||||
---
|
||||
|
||||
## What is AGNTCY?
|
||||
|
||||
AGNTCY is an open standard from the Linux Foundation for AI agent identity and governance.
|
||||
AgentIdP implements AGNTCY by giving every agent a DID and an agent card. The compliance
|
||||
endpoints let you export and report on that data in structured, auditable formats.
|
||||
|
||||
---
|
||||
|
||||
## Export agent cards
|
||||
|
||||
`GET /api/v1/compliance/agent-cards`
|
||||
|
||||
Exports all active agents in your organization as AGNTCY-standard agent card JSON objects.
|
||||
Suitable for ingestion by external compliance tools or AGNTCY-compatible registries.
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/compliance/agent-cards" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
Response (`200 OK`): Array of agent card objects.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"did": "did:web:localhost%3A3000:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
||||
"name": "screener-001@talent.ai",
|
||||
"agentType": "screener",
|
||||
"capabilities": ["resume:read", "email:send"],
|
||||
"owner": "talent-team",
|
||||
"version": "1.0.0",
|
||||
"deploymentEnv": "production",
|
||||
"identityProvider": "https://sentryagent.ai",
|
||||
"issuedAt": "2026-04-04T09:00:00.000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Share with external auditors to demonstrate your agent fleet
|
||||
- Import into AGNTCY-compatible discovery registries
|
||||
- Baseline snapshot before and after deployments
|
||||
|
||||
Save the output to a file:
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/compliance/agent-cards" \
|
||||
-H "Authorization: Bearer $TOKEN" > agent-cards-$(date +%Y%m%d).json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generate a compliance report
|
||||
|
||||
`GET /api/v1/compliance/report`
|
||||
|
||||
Generates an AGNTCY compliance report for your tenant. The report is cached for 5 minutes
|
||||
(check the `X-Cache` header to see if the response is fresh or cached).
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/compliance/report" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
Response (`200 OK`):
|
||||
|
||||
```json
|
||||
{
|
||||
"tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
|
||||
"generatedAt": "2026-04-04T09:00:00.000Z",
|
||||
"agntcyConformance": true,
|
||||
"agentCount": 12,
|
||||
"verifiedAgentCount": 12,
|
||||
"auditChainIntegrity": true,
|
||||
"from_cache": false
|
||||
}
|
||||
```
|
||||
|
||||
**Interpreting the fields**:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `agntcyConformance` | `true` if all agents have valid DIDs and the audit chain is intact |
|
||||
| `agentCount` | Total active agents in the organization |
|
||||
| `verifiedAgentCount` | Agents with a resolvable DID document |
|
||||
| `auditChainIntegrity` | `true` if the audit event hash chain has not been tampered with |
|
||||
| `from_cache` | `true` if served from Redis cache (up to 5 minutes old) |
|
||||
|
||||
**Force a fresh report**: Wait 5 minutes for the cache to expire. The `from_cache: false`
|
||||
response is always freshly generated.
|
||||
|
||||
---
|
||||
|
||||
## Verify audit chain integrity
|
||||
|
||||
`GET /api/v1/audit/verify`
|
||||
|
||||
Verifies that the cryptographic hash chain of audit events is intact. Returns `verified: true`
|
||||
if no tampering is detected. Rate limited to 30 requests/minute (computationally intensive).
|
||||
|
||||
Requires: Bearer token with `audit:read` scope.
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/audit/verify" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
Response (`200 OK`):
|
||||
|
||||
```json
|
||||
{
|
||||
"verified": true,
|
||||
"checkedCount": 1247,
|
||||
"fromDate": null,
|
||||
"toDate": null
|
||||
}
|
||||
```
|
||||
|
||||
Verify a specific date window:
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/audit/verify?fromDate=2026-03-01T00:00:00.000Z&toDate=2026-03-31T23:59:59.999Z" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq .
|
||||
```
|
||||
|
||||
**Interpreting the result**:
|
||||
- `verified: true` — no tampering detected in the checked window
|
||||
- `verified: false` — the hash chain has a broken link; contact SentryAgent.ai support
|
||||
- `checkedCount` — number of audit events verified
|
||||
|
||||
---
|
||||
|
||||
## Check SOC 2 control status (public)
|
||||
|
||||
`GET /api/v1/compliance/controls`
|
||||
|
||||
Returns the live status of all SOC 2 Trust Services Criteria controls. No authentication
|
||||
required. Responses are cached by CDN/proxies for 60 seconds (`Cache-Control: public, max-age=60`).
|
||||
|
||||
```bash
|
||||
curl -s "http://localhost:3000/api/v1/compliance/controls" | jq .
|
||||
```
|
||||
|
||||
Response (`200 OK`):
|
||||
|
||||
```json
|
||||
{
|
||||
"controls": [
|
||||
{
|
||||
"id": "CC6.1",
|
||||
"name": "Logical Access Controls",
|
||||
"status": "pass",
|
||||
"lastChecked": "2026-04-04T08:00:00.000Z"
|
||||
},
|
||||
{
|
||||
"id": "CC7.2",
|
||||
"name": "System Monitoring",
|
||||
"status": "pass",
|
||||
"lastChecked": "2026-04-04T08:00:00.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Each control has a `status` of `pass`, `fail`, or `unknown`. Status is updated by background
|
||||
jobs that run periodically. This endpoint is suitable for embedding in external status pages
|
||||
or compliance dashboards without sharing API credentials.
|
||||
|
||||
---
|
||||
|
||||
## When compliance endpoints are disabled
|
||||
|
||||
If `COMPLIANCE_ENABLED=false` is set in the server environment, the AGNTCY compliance endpoints
|
||||
(`/compliance/report` and `/compliance/agent-cards`) return `404 COMPLIANCE_DISABLED`. The SOC 2
|
||||
endpoints (`/compliance/controls` and `/audit/verify`) are never gated and always active.
|
||||
Reference in New Issue
Block a user