External tests

External tests allow users to run test workloads outside of TrustCloud while submitting only the necessary test resources for control validation. This enables organizations to retain ownership of their test data and inventory (hybrid data fabric) within their own infrastructure while maintaining a consistent visual experience similar to automated tests.

Key features of external tests

1. Execution Outside TrustCloud: Users run tests in their own environment.
2. Controlled Data Submission: Only test resources required for validation are uploaded.
3. Consistent Visual Representation: Results appear similar to automated tests in TrustOps.

Submitting evidence for external tests

1. Users can upload evidence programmatically using the TrustCloud API.
2. Evidence submission is limited to either a file or a link.

This approach provides flexibility while ensuring test results are integrated into compliance workflows efficiently.

Why use the TrustCloud API for external tests?

The TrustCloud API enables organizations to manage control compliance efficiently while maintaining data privacy. Many customers require compliance management through TrustCloud but prefer to keep their test data and inventories private. The API provides a solution by allowing customers to push test result data programmatically without exposing underlying data.

Key advantages

1. Data Privacy: Test data and inventories remain within the organization’s infrastructure.
2. Seamless Integration: Customers can automate test result submissions directly to TrustCloud.
3. Compliance Without Exposure: Organizations can meet compliance requirements while retaining control over sensitive data.
4. Flexibility: The API-driven approach allows users to manage compliance processes according to their specific needs.

Using the TrustCloud API, organizations can streamline compliance management while ensuring data security and operational efficiency.

How TrustCloud API works

The TrustCloud API allows organizations to programmatically interact with their TrustCloud instance to manage governance, risk, and compliance (GRC) data. It provides capabilities to retrieve compliance-related information and submit evidence to meet control requirements.

Key functions of the TrustCloud API

1. Data Retrieval: Fetch information about governance, risk, and compliance programs.
2. Evidence Submission: Submit evidence programmatically to satisfy control requirements.
3. Integration Support: Connect with external systems to automate compliance workflows.

By leveraging the TrustCloud API, organizations can streamline compliance processes, automate evidence collection, and enhance overall compliance efficiency.

Guide to utilizing the TrustCloud API for external tests

This section provides you with a step-by-step approach to harnessing the power of the TrustCloud API for conducting external tests. By following these instructions, you will be able to seamlessly integrate the API into your testing processes and obtain valuable insights on the security and reliability of your systems. It mainly consists of two important steps:

1. Create the external test for a control and optionally associate it with an applicable system.
   This feature relies on the user creating external tests by configuring the following fields:
   1. Test Name: A relevant name for the external test.
   2. Evidence Requirement: A summary of what the evidence requirement is for this external test.
   3. Assign a Test to a System: Select an applicable system from the dropdown if this test is to be associated with a system.
   4. Test Procedure: This describes all the steps involved in generating the test resource data in the form of a title & description.
   5. Evaluation Criteria: This describes the comparison field and comparison operator to compute test results based on the test resources uploaded via the TrustCloud API. For instance, for the MFA-enabled test, one can have the following JSON, which in *fact* maps to a field in the customer-uploaded test data, where “value” refers to the actual value contained in the fact field, and operator refers to the operator applied to compute the final test result.
      {
"fact": "MFAEnabled",
"value": true,
"operator":"equal"
}
   6. Evaluation Property: The value for this field is computed based on the *fact* field in the evaluation criteria. For instance, in the above example, the Evaluation Property will be set to MFAEnabled. TrustCloud will use this field to determine pass/fail for a test based on the value contained within MFAEnabled.
      NOTE: If an evaluation criterion is not provided, it will default to the following JSON :-
      {
"fact":"status",
"operator":"equal"
"value": Enum("success", "failure")
}
   7. Upload test resources for the external test via TrustCloud API
      Once an external test has been created, the next step is to actually upload test evidence data for an external test by using the TrustCloud API and adhering to the following format:
      {
"name": "",
<fact>: <value>
}
      1. Name is a required field and refers to the unique entity in the test data. For instance, for the MFA-enabled test, it could be the user email. The fact is a required field and refers to the fact key in the evaluation criteria.
      2. “Value” refers to the actual value for the fact field.

Examples

Consider the following example for reference:

(CASE.1): For the following evaluation criteria:

{
"fact":"MFAEnabled",
"value": true,
"operator":"equal"
}

The test data to be uploaded will be:

{
"name":"john.doe@business.com",
"MFAEnabled": true
},{
"name": "jane.doe@business.com",
"MFAEnabled": false
}

(CASE.2): If an evaluation criterion is not provided, the default evaluation criteria will be considered, and the test data to be uploaded will be

{
"name": "john.doe@business.com",
"status": "success"
},{<
"name": "jane.doe@business.com",
"status": "failure"
}

Here’s a sample API call to upload test data for an external test: The request can be fired on your CLI terminal or a tool like postman.

curl-L'<https://api.trustcloud.ai/tests/:testId/execute>'\\
-H 'accept: */*' \\
-H 'x-trustcloud-api-version: 1' \\
-H 'Authorization: Bearer <TOKEN>'\\
-H 'Content-Type: application/json' \\
--data-raw '{
"resources": [
{
"name": "john.doe@business.com",
"status": "success"
},
{
"name": "jane.doe@business.com",
"status": "failure"
}],
"logs": [
{
"command": "<API or SDK function invoked to generate data>",
"response": "[<JSON or raw data returned by the API/SDK>]",
"timeStamp": "2024-05-03 23:55:22"
}
]
}'

How does this impact or relate to the tests that show up for controls?

All the created external tests are organized under the “External” tab within the details page of the respective “Control” or “System.” These tests can be seen alongside the self-attestations and automated tests. These external tests can be seen alongside the automated tests and self-attestations as shown in the following screenshot.

TrustCloud API documentation and resources

1. Creating a TrustCloud API Key:
   https://community.trustcloud.ai/docs/trustcloud-api/guides/getting-started/?lang=rest#api-reference
2. TrustCloud API Documentation: https://api.trustcloud.ai/documentation

Things to consider

External tests are only available as custom tests and are associated with a control or the system. If the associated control or system is removed, the external tests will be deleted along with the evidence collected and will have to be recreated when the control or system is re-added.