Security Considerations

[!NOTE] Partially implemented. Compliance tags are validated in schemas today. PII encryption enforcement and audit log integrity verification are planned.

This page covers the planned security model for ChooChoo, including PII handling, encryption requirements, and audit log integrity.

For an overview of how security fits into the platform architecture, see the Architecture page.

PII Handling

• Fields tagged with pii: true in Data Contracts MUST be treated as sensitive. See Compliance Tags for the full taxonomy of supported tags and their risk weights.
• Agents without the pii capability (i.e., those with a no-pii boundary) MUST receive masked/redacted values when reading these fields. This is enforced by the validation engine.
• Access to PII fields MUST be logged in the Audit Trail. Every access event records the Agent or human actor, the field accessed, and the timestamp.
• Modifications to PII fields trigger approval workflows based on the configured compliance tags and risk score.

The pii: true flag and complianceTags array on Contract fields work together to determine the security posture for each field. An agent's System Card documents whether it is authorized to handle PII, and this is cross-referenced during validation.

Encryption Requirements

ChooChoo recommends encryption strategies based on field classification. The classification field on Contract fields determines the encryption requirements:

CMK = Customer Managed Key. mTLS = Mutual TLS.

These encryption requirements are validated by choochoo validate when the --strict flag is used. Fields with restricted classification that lack proper encryption configuration produce error E001 (Invalid schema) with details about the missing encryption settings.

For information on configuring strict mode as the default, see the Configuration guide.

Audit Log Integrity

The Audit Trail is the "black box" flight recorder of the ChooChoo platform. Its integrity is paramount for compliance reporting and regulatory audits.

• Append-Only: Audit logs must never be modified, only appended to. Any attempt to alter existing entries is detected and flagged.
• Signatures: Each entry should include a cryptographic signature to verify authenticity. This enables auditors to verify that no entries have been tampered with since creation.
• Separation: Audit logs should be stored separately from operational data to prevent tampering. In production environments, use write-once-read-many (WORM) storage.

Retention

The default retention period is 7 years (2555 days), configurable via the governance.auditRetentionDays setting in .choochoorc. This default satisfies SOX and HIPAA retention requirements. See Compliance Reporting for how audit data is used to generate regulatory reports.

Access Control

Access to audit logs in The Station is governed by RBAC:

When SSO is configured, all authentication events are also recorded in the audit log, providing a complete chain of identity attribution.

Agent Security

AI Agents present unique security challenges. ChooChoo addresses these through multiple layers:

1. Registration: All agents MUST be registered in the Agent Registry (agents/AGENTS.md). Unregistered agents cannot pass validation.
2. System Cards: Each agent's System Card documents its capabilities, limitations, and compliance posture. This is referenced during risk scoring.
3. Boundaries: Explicit rails (read-only, no-pii, requires-approval, env-restricted, scope-limited) constrain what agents can do. Violations produce error E007.
4. Tracing: Every agent action generates an Agent Trace that captures the full decision context, enabling post-hoc review and forensic analysis.

CI/CD Security

When running in CI/CD pipelines, consider the following:

• Use --strict mode to enforce all security validations. See Exit Codes for interpreting results.
• Store the .choochoorc configuration in version control so that security settings are tracked and auditable.
• Ensure that compliance tags triggering approval workflows cannot be bypassed by CI — the CLI returns exit code 10 (APPROVAL_REQUIRED) until the approval is obtained.

Related