Compute agent control evidence

Computes and stores what each control of the assessment's program is judged on, for a submission standing on the configuration, operating profile, declarations and not-applicable claims given: an AgentControlEvidenceV1 per control, naming the values of the configuration fields and profile sections it judges, the declarations covering it and its claim. Governance puts the CIDs in the submission, which registering recomputes and checks, and each review names its control's evidence CID. The assessment must belong to the caller's organization.

posthttps://<host>/gov/v1/agent/evidence/{assessment_uuid}

bash

curl --request POST \
  --url 'https://<host>/gov/v1/agent/evidence/{assessment_uuid}' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"configurationCid":"urn:cid:configuration_cid","declarationCid":"[\"urn:cid:declaration_one\"]","notApplicable":[{"controlCid":"urn:cid:control_cid","statement":"The agent has no network access."}],"profileCid":"urn:cid:profile_cid"}'

javascript

const response = await fetch("https://<host>/gov/v1/agent/evidence/{assessment_uuid}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "configurationCid": "urn:cid:configuration_cid",
    "declarationCid": "[\"urn:cid:declaration_one\"]",
    "notApplicable": [
      {
        "controlCid": "urn:cid:control_cid",
        "statement": "The agent has no network access."
      }
    ],
    "profileCid": "urn:cid:profile_cid"
  })
});

const data = await response.json();

typescript

interface AgentEvidenceResponse {
  controls: Record<string, unknown>[];
}

const response = await fetch("https://<host>/gov/v1/agent/evidence/{assessment_uuid}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "configurationCid": "urn:cid:configuration_cid",
    "declarationCid": "[\"urn:cid:declaration_one\"]",
    "notApplicable": [
      {
        "controlCid": "urn:cid:control_cid",
        "statement": "The agent has no network access."
      }
    ],
    "profileCid": "urn:cid:profile_cid"
  })
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const data: AgentEvidenceResponse = await response.json();

python

import requests

response = requests.post(
    "https://<host>/gov/v1/agent/evidence/{assessment_uuid}",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "configurationCid": "urn:cid:configuration_cid",
        "declarationCid": "[\"urn:cid:declaration_one\"]",
        "notApplicable": [
            {
                "controlCid": "urn:cid:control_cid",
                "statement": "The agent has no network access.",
            },
        ],
        "profileCid": "urn:cid:profile_cid",
    },
)
response.raise_for_status()
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "configurationCid": "urn:cid:configuration_cid",
	  "declarationCid": "[\"urn:cid:declaration_one\"]",
	  "notApplicable": [
	    {
	      "controlCid": "urn:cid:control_cid",
	      "statement": "The agent has no network access."
	    }
	  ],
	  "profileCid": "urn:cid:profile_cid"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://<host>/gov/v1/agent/evidence/{assessment_uuid}", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Status, string(data))
}

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<host>/gov/v1/agent/evidence/{assessment_uuid}"))
            .header("Authorization", "Bearer <token>")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "configurationCid": "urn:cid:configuration_cid",
                  "declarationCid": "[\\"urn:cid:declaration_one\\"]",
                  "notApplicable": [
                    {
                      "controlCid": "urn:cid:control_cid",
                      "statement": "The agent has no network access."
                    }
                  ],
                  "profileCid": "urn:cid:profile_cid"
                }
                """))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

csharp

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://<host>/gov/v1/agent/evidence/{assessment_uuid}");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Content = new StringContent("""
    {
      "configurationCid": "urn:cid:configuration_cid",
      "declarationCid": "[\"urn:cid:declaration_one\"]",
      "notApplicable": [
        {
          "controlCid": "urn:cid:control_cid",
          "statement": "The agent has no network access."
        }
      ],
      "profileCid": "urn:cid:profile_cid"
    }
    """, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

php

<?php

$ch = curl_init('https://<host>/gov/v1/agent/evidence/{assessment_uuid}');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <token>',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
    {
      "configurationCid": "urn:cid:configuration_cid",
      "declarationCid": "[\"urn:cid:declaration_one\"]",
      "notApplicable": [
        {
          "controlCid": "urn:cid:control_cid",
          "statement": "The agent has no network access."
        }
      ],
      "profileCid": "urn:cid:profile_cid"
    }
    JSON,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;

ruby

require "net/http"

uri = URI("https://<host>/gov/v1/agent/evidence/{assessment_uuid}")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "configurationCid": "urn:cid:configuration_cid",
    "declarationCid": "[\"urn:cid:declaration_one\"]",
    "notApplicable": [
      {
        "controlCid": "urn:cid:control_cid",
        "statement": "The agent has no network access."
      }
    ],
    "profileCid": "urn:cid:profile_cid"
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts "#{response.code} #{response.body}"

rust

// Cargo.toml dependencies: reqwest (features "json"), serde_json, tokio (features "full")
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = reqwest::Client::new()
        .post("https://<host>/gov/v1/agent/evidence/{assessment_uuid}")
        .header("Authorization", "Bearer <token>")
        .json(&json!({
            "configurationCid": "urn:cid:configuration_cid",
            "declarationCid": "[\"urn:cid:declaration_one\"]",
            "notApplicable": [
                {
                    "controlCid": "urn:cid:control_cid",
                    "statement": "The agent has no network access."
                }
            ],
            "profileCid": "urn:cid:profile_cid"
        }))
        .send()
        .await?;

    println!("{} {}", response.status(), response.text().await?);
    Ok(())
}

Authorizations

BearerAuth · HTTP bearer (JWT)

Parameters

Path parameters

Name	Type	Description
`assessment_uuid` required	`string<uuid>`	The assessment graph

Request bodyrequired

application/json

configurationCidstringrequired
The configuration pinned on the assessment, as the submission will name it
declarationCidstring[]
The declarations the submission will stand on
notApplicableNotApplicableClaim[]
The controls the submission will claim do not apply
Show properties
Array of NotApplicableClaim
- controlCidstringrequired
- statementstringrequired
profileCidstring | null
The operating profile pinned on the assessment, as the submission will name it; omitted when nothing is pinned

Examplejson

{
  "configurationCid": "urn:cid:configuration_cid",
  "declarationCid": "[\"urn:cid:declaration_one\"]",
  "notApplicable": [
    {
      "controlCid": "urn:cid:control_cid",
      "statement": "The agent has no network access."
    }
  ],
  "profileCid": "urn:cid:profile_cid"
}

Responses

200Each program control's evidence, stored, and its CID

application/json

controlsControlEvidence[]required
Every program control and its evidence's CID, in control CID order: what the submission's controls must name
Show properties
Array of ControlEvidence
- controlCidstringrequired
- evidenceCidstringrequired
  The CID of the control's AgentControlEvidenceV1 document

Examplejson

{
  "controls": [
    {
      "controlCid": "urn:cid:control_cid",
      "evidenceCid": "urn:cid:evidence_cid"
    }
  ]
}

401Missing or invalid bearer token

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

403The assessment graph is not registered, or belongs to an organization other than the caller's

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

422The configuration or operating profile is not the one pinned on the assessment, a declaration is not registered in the assessment, or a control claimed not applicable is outside the program or claimed twice

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

500Internal error

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}

503Auth Service or blob storage unavailable

application/json

callstackobject
Show properties
object | null
errorstringrequired

Examplejson

{
  "callstack": {},
  "error": "string"
}