trust-portal

name	trust-portal
description	Let AI agents drive SOC 2 Type 2 compliance end-to-end. Use when the user wants to get SOC 2 compliant, start a compliance program, manage controls, view or submit evidence, check compliance scores, generate policies, review systems/vendors/risks, query the audit log, upload decision logs, manage portal settings, or configure and run automated evidence collectors (AWS, Git/CodeCommit, Platform, Policy, Vendor). TRIGGER on any of these phrases — "get me SOC 2 compliant", "set up compliance", "start our compliance program", "check compliance", "what evidence is missing", "show the audit log", "set up evidence collection", "configure collectors", "run the collectors", or any mention of SOC 2 controls, tests, evidence, policies, or evidence collectors. For end-to-end SOC 2 journey guidance, read references/soc2-playbook.md which contains the complete 8-phase workflow with exact API calls, decision trees, and conversational scripts.
license	MIT
compatibility	Requires python3 and environment variables TRUST_PORTAL_API_URL and TRUST_PORTAL_API_KEY
metadata	{"version":"1.0.0","openclaw":{"requires":{"env":["TRUST_PORTAL_API_URL","TRUST_PORTAL_API_KEY"],"bins":["python3"]},"primaryEnv":"TRUST_PORTAL_API_KEY","homepage":"https://github.com/MaxGood-AI/ai-agent-first-trust-portal"}}

Trust Portal

Manage SOC 2 compliance data through the AI Agent-First Trust Portal API.

Environment Setup

The CLI script reads two environment variables: TRUST_PORTAL_API_URL and TRUST_PORTAL_API_KEY.

The script automatically loads these from a .env file if they are not already in the environment. It searches for .env in the current working directory and in the skill's parent directory. No shell export or command substitution is needed — just run the Python command directly.

Get your API key: Log in to the trust portal admin at /admin/team and create a team member (human or agent role). The API key is shown on creation.

Quick Start

# Check connectivity
python3 scripts/trust_portal_api.py health

# View compliance status
python3 scripts/trust_portal_api.py compliance-score

# List controls
python3 scripts/trust_portal_api.py controls

# Find tests needing evidence
python3 scripts/trust_portal_api.py evidence-gaps

# Submit evidence
python3 scripts/trust_portal_api.py submit-evidence \
  --test-record-id abc123 --evidence-type link \
  --url "https://..." --description "Monthly scan results"

# Query audit log
python3 scripts/trust_portal_api.py audit-log --table controls --limit 10

# Upload decision log transcript
python3 scripts/trust_portal_api.py upload-decision-log --file /path/to/transcript.jsonl

SOC 2 Journey — End-to-End Orchestration

For the complete 8-phase SOC 2 journey (bootstrap → discovery → policies → controls → evidence → gap analysis → audit prep → ongoing), read the SOC 2 Agent Playbook. It contains exact API call sequences, decision trees, and conversational scripts for driving the entire compliance program.

Quick start:

1. compliance-journey — Check current phase and what to do next
2. Read references/soc2-playbook.md for the complete workflow
3. Use references/discovery-questions.json for structured discovery interviews

Resuming after interruption: Always call compliance-journey first. It returns the current phase, what's completed, and the next 1-3 actions to take.

Core Workflows

View Compliance Status

1. Run compliance-score to see overall and per-category scores.
2. Run evidence-gaps to find tests needing evidence.

Manage Controls

1. controls — list all controls
2. control --id X — get details for a specific control
3. create-control --name "..." --category security — create a new control
4. update-control --id X --data-file /tmp/update.json — update fields
5. delete-control --id X — remove a control

Record Test Execution

1. record-execution --test-id X --outcome success --finding "All checks passed"
2. record-execution --test-id X --outcome failure --finding "MFA not enforced" --comment "2 users affected"
3. record-execution --test-id X --outcome success --finding "Verified" --evidence-file /tmp/evidence.json — include evidence
4. execution-history --test-id X — view past executions for a test
5. execution-history --test-id X --limit 5 — limit results

The --evidence-file flag accepts a JSON file containing an array of evidence items:

[
  {"evidence_type": "screenshot", "description": "Password manager showing AWS creds", "url": "https://..."},
  {"evidence_type": "link", "description": "Audit log export", "url": "https://..."},
  {"evidence_type": "file", "description": "Exported audit CSV", "file": "/path/to/audit.csv"}
]

Items with a file field are read from disk and uploaded directly to the database. Items with a url field are stored as link references. Evidence items are linked to the test record and its evidence status is set to "submitted".

Batch Operations

1. batch-record-execution --data-file /tmp/executions.json — record results for multiple tests
2. batch-submit-evidence --data-file /tmp/evidence.json — submit evidence to multiple tests

Batch execution file format:

{"executions": [
  {"test_id": "abc", "outcome": "success", "finding": "All good"},
  {"test_id": "def", "outcome": "failure", "finding": "MFA not enforced", "evidence": [
    {"evidence_type": "screenshot", "description": "MFA settings page", "file": "/path/to/screenshot.png"}
  ]}
]}

Batch evidence file format:

{"evidence": [
  {"test_record_id": "abc", "evidence_type": "link", "description": "Scan report", "url": "https://..."},
  {"test_record_id": "def", "evidence_type": "file", "description": "Export", "file": "/path/to/export.csv"}
]}

Both return per-item results with succeeded/failed counts. Items with file paths are auto-encoded.

Submit Evidence

1. evidence-gaps — find what needs evidence
2. submit-evidence --test-record-id X --evidence-type link --url "..." --description "..." — link evidence
3. submit-evidence --test-record-id X --evidence-type file --file /path/to/export.pdf --description "..." — upload a file directly

Decision Logs

1. upload-decision-log --file /path/to/transcript.jsonl — upload a session transcript
2. decision-log-sessions — list all uploaded sessions
3. decision-log-session --id X — view session entries

Audit Log

1. verify-audit-log — verify the hash chain integrity (tamper detection)
2. audit-log — recent changes across all tables
3. audit-log --table controls — changes to controls only
4. audit-log --action DELETE --limit 5 — recent deletions

Portal Settings

1. settings — view current portal settings
2. update-settings --data-file /tmp/settings.json — update settings (admin only)

Evidence Collectors

Evidence collectors are the core of SOC 2 Phase 5 (Evidence Collection). They gather compliance evidence from infrastructure on a schedule. The portal ships five: aws, git, platform, policy, vendor.

# Discover which AWS account/region the portal is running in
python3 scripts/trust_portal_api.py collector-environment

# Inventory / status
python3 scripts/trust_portal_api.py collectors
python3 scripts/trust_portal_api.py collector --name aws

# Configure a collector — credentials MUST come from a JSON file, never CLI args
cat > /tmp/aws-config.json <<'EOF'
{
  "credential_mode": "task_role_assume",
  "credentials": {
    "role_arn": "arn:aws:iam::123456789012:role/trust-portal-collector-role"
  },
  "config": {"region": "ca-central-1"},
  "schedule_cron": "0 6 * * 1",
  "enabled": true
}
EOF
python3 scripts/trust_portal_api.py configure-collector --name aws --data-file /tmp/aws-config.json

# Verify the credentials work (STS identity + optional permission probe)
python3 scripts/trust_portal_api.py test-collector-connection --name aws
python3 scripts/trust_portal_api.py probe-collector --name aws

# Fetch the IAM policy JSON the collector needs (copy this into Terraform)
python3 scripts/trust_portal_api.py collector-required-policy --name aws

# Enable / disable
python3 scripts/trust_portal_api.py enable-collector --name aws --enabled true

# Trigger a manual run
python3 scripts/trust_portal_api.py run-collector --name aws

# Run history and per-check detail
python3 scripts/trust_portal_api.py collector-runs --name aws
python3 scripts/trust_portal_api.py collector-run --run-id <uuid>

Credential safety. The configure-collector command requires --data-file because credentials (AWS access keys, bearer tokens, collector role ARNs with external IDs) must never appear as CLI arguments — they would leak into shell history, process listings, decision-log transcripts, and any hook that captures command lines. Write the JSON body to a temp file and pass the file path; the contents of the file never touch the command line.

Simpler collectors. policy and vendor don't need credentials at all (they read the portal's own database). platform only needs credentials if your services require bearer or basic auth. For these, credential_mode can be set to "none".

Description Updates (IMPORTANT)

Always use --data-file instead of inline JSON for create or update operations. This avoids multi-line quoting issues in shell commands.

Workflow:

1. Write the data to a temp file (e.g., /tmp/update.json) using the Write tool.
2. Run the command with --data-file /tmp/update.json.

Command Reference

Command	Description
health	Health check
compliance-score	Overall and per-category compliance scores
compliance-journey	Full SOC 2 journey state — current phase, completion checks, next actions
evidence-gaps	Tests with missing or outdated evidence
settings	Get portal settings
update-settings	Update portal settings (admin)
controls	List all controls
control	Get a single control
create-control	Create a control
update-control	Update a control
delete-control	Delete a control
tests	List all test records
test	Get a single test record
create-test	Create a test record
update-test	Update a test record
record-execution	Record an externally-performed test execution result
execution-history	Get execution history for a test record
batch-record-execution	Record execution results for multiple tests at once
batch-submit-evidence	Submit evidence for multiple tests at once
policies	List all policies
policy	Get a single policy
systems	List all systems
system	Get a single system
vendors	List all vendors
vendor	Get a single vendor
risks	List risk register entries
evidence	List all evidence
submit-evidence	Submit evidence for a test
pentest-findings	List pentest findings
verify-audit-log	Verify audit log hash chain integrity
audit-log	Query the audit log
upload-decision-log	Upload a JSONL decision log
decision-log-sessions	List decision log sessions
decision-log-session	Get a decision log session
collector-environment	Detect running environment (AWS account/region/identity)
collectors	List all configured evidence collectors
collector	Get one collector config (credentials never returned)
configure-collector	Save collector config + credentials (requires --data-file)
test-collector-connection	Lightweight connection test for a collector
probe-collector	Run the full permission probe for a collector
enable-collector	Enable or disable a collector
run-collector	Trigger a manual collector run synchronously
collector-runs	Recent run history for a collector
collector-run	Run detail with per-check results
collector-required-policy	Return the IAM policy JSON a collector needs

API Reference

See references/api-reference.md for complete endpoint documentation.