//DOCS Enterprise Security Review

Enterprise Security Review

This page packages Punk's current trust and security posture for enterprise review. It is a practical review guide, not a certification report, legal commitment, or customer-specific security addendum.

Use it with:

• Governance for policy, approvals, audit, redaction, DLP, tripwires, and trust lanes.
• Configuration for environment variables, provider modes, auth modes, tenant settings, database choice, and readiness receipts.
• Operations for production readiness, workers, health checks, backups, retention, and rollout operations.
• Architecture for request flow, package boundaries, persistence, and trace integrity.
• API for evidence packets, audit endpoints, run detail, receipts, keys, credentials, and settings.
• Connectors for managed connector auth, data classes, side-effect levels, cache, replay, shadow, idempotency, and redaction metadata.

Review Scope

Punk sits between customer agents, model providers, tools, web context, side effects, and operator review. The security objective is to keep raw tenant traffic isolated, attributable, governed, reviewable, and removable under the configured retention policy while allowing proven optimized routes to serve only after replay, shadow, policy, and rollback checks.

Current public docs describe hosted Punk and Punk-operated infrastructure. They do not describe a customer self-hosting program.

Data Boundaries

Reviewer note: tenant isolation is enforced by the application and storage interfaces. If a customer requires database-level row security, dedicated infrastructure, regional pinning, or customer-managed encryption keys, collect separate deployment evidence before making that commitment.

Data Processed

Punk can process these data classes depending on which features are enabled:

• Model request messages and provider responses.
• Route explanations, token counts, costs, latency, and provider/model metadata.
• Trace events for request, model, tool, workflow, web, policy, DLP, tripwire, approval, learning, replay, and shadow behavior.
• SDK tool arguments and results when traced by the application.
• Managed connector tool inputs/results when installed.
• Web snapshots and web session actions when web features are used.
• Workflow definitions, workflow run events, conversations, agents, and schedules.
• Human user records, org memberships, invites, sessions, and audit events.
• Tenant settings, API key metadata, credential metadata, and encrypted credential secrets.

Do not put secrets in prompts, workflow inputs, trace-visible metadata, or customer-facing route explanations. Use tenant credentials and cred:<id> references for tool and connector secrets.

Retention And Redaction

Redaction is deterministic masking, not a substitute for data minimization. Review examples after enabling it, because masking changes trace fidelity and output readability.

Credentials And Provider Keys

Credential posture:

• Tenant API keys are bearer pk_ tokens. The full token is shown once and stored only as a hash.
• Human passwords are argon2id-hashed. Dashboard sessions use HttpOnly cookies, and session tokens are stored only as hashes.
• Invite and verification tokens are one-time tokens stored as hashes.
• Stored credentials use AES-256-GCM at rest with PUNK_ENCRYPTION_KEY. Authenticated deployments should set a valid 32-byte base64 key before storing provider keys, workflow credentials, MCP credentials, or managed connector credentials.
• Credential list APIs return masked records. Runtime executors resolve plaintext internally when connecting to providers, MCP servers, or managed connectors.

Provider-key posture:

• Customer apps should hold a Punk tenant API key, not raw OpenAI, Anthropic, OpenRouter, DeepSeek, Kimi/Moonshot, or Gemini keys.
• Tenants can use hosted provider configuration or BYOK credentials. A tenant BYOK key takes precedence for that tenant and provider family.
• Live run traces record whether a tenant key or platform key served the request.
• Provider failover is visible in route explanations and trace events. Mock fallback is intended for local development, demos, and explicitly accepted deployments, not silent production fallback.
• Live model providers receive the request content needed to answer the request. Provider retention, training, DPA, and subprocessor terms must be reviewed per provider and contract.

Governance And Side Effects

Punk classifies tools by side-effect level:

Undeclared SDK tools default to level 3. Managed connectors declare side-effect level, cache posture, replay behavior, shadow suppression, idempotency, approval defaults, auth requirements, and redaction metadata in their manifests.

Observe mode is the recommended first enterprise rollout mode. Live provider responses still serve users, while Punk records policy decisions, candidate routes, ghost savings, and evidence gaps without serving optimized paths or enforcing denials.

Audit And Evidence Export

Security reviewers should expect one run to have an exportable story:

1. Who acted: tenant, app, agent, subject, API key or human actor where applicable.
2. What happened: request, route, provider/model, cost, latency, tool calls, side effects, policy decisions, and errors.
3. Why this route served: route explanation, rejected alternatives, cache/artifact details, failover, savings, and evidence warnings.
4. What proof exists: trace integrity result, replay bundle when available, shadow/evaluation evidence, Chorus receipt when present, side effects, feedback, and related audit rows.
5. What can be undone: rollback, quarantine, policy deny, key revoke, credential delete, settings change, or return to observe mode.

Useful endpoints:

Deployment Architecture

Minimum Punk-operated production shape:

customer app or agent
  -> Punk hosted gateway / dashboard / API
  -> router, governance, cache, artifact runtime, web runtime
  -> live model provider or optimized route
  -> trace ledger, audit events, jobs, learning, replay, shadow

Operational expectations:

• Use protected mode with PUNK_API_KEY, dashboard login, and scoped tenant API keys.
• Use Postgres for durable deployed environments and a standalone worker or serverless cron tick for durable jobs.
• Set PUNK_ENCRYPTION_KEY before credential storage.
• Terminate HTTPS at the edge; bind the app to 127.0.0.1 behind a reverse proxy where applicable.
• Keep PUNK_ALLOW_PRIVATE_WEB_FETCH=false and PUNK_ALLOW_PRIVATE_WEBHOOKS=false unless private network access is intentionally required.
• Use /health, /api/v1/readiness, /api/v1/jobs, /api/v1/audit, /api/v1/runs, and /api/v1/cache/stats for operational checks.
• Back up the production database and confirm backup retention covers audit and replay needs.

Incident And Rollback Procedure

Use this operational sequence for a suspected policy, data, credential, routing, or optimization incident.

1. Contain serving risk: switch the affected app key to observe mode, revoke the key, disable semantic_cache serving, disable model substitution serving, or apply a deny/approval-required policy.
2. Stop unsafe optimized routes: rollback or quarantine the artifact, disable canary, and confirm future matching traffic routes live or blocked according to policy.
3. Contain credentials: delete or rotate affected provider, workflow, MCP, or managed connector credentials; verify PUNK_ENCRYPTION_KEY posture; revoke external provider/vendor keys if needed.
4. Suppress side effects: keep L3/L4 actions approval-required, verify replay/shadow suppression, and pause risky workflows or scheduled agents.
5. Preserve evidence: export the run evidence packet, run integrity result, relevant audit rows, readiness receipt, job status, and connector/workflow configuration.
6. Restore deliberately: replay or shadow before re-promoting, re-enable canary for limited traffic, and document owner approval before optimize mode resumes.

Evidence to collect for a post-incident review:

• Affected tenant, app, agent, subject, run ids, artifact ids, credential ids, provider key source, and policy version.
• Route explanations and integrity results for affected runs.
• Audit events for key, credential, policy, approval, artifact, org, user, and setting changes.
• Job health and worker/cron evidence if background work was involved.
• Provider/vendor response or support evidence if the incident crossed an external provider boundary.

Reviewer Checklist

Security reviewer:

• Confirm the tenant, app, agent, and subject identifiers used by the pilot.
• Confirm which data classes enter prompts, traces, tool calls, connectors, web snapshots, and provider calls.
• Confirm provider key source for live traffic and review provider contractual terms.
• Confirm tenant retention_days, redaction, streaming_dlp, semantic_cache, and cross_tenant_learning settings.
• Confirm no cross-tenant aggregate learning is enabled unless the customer explicitly opted in.
• Confirm L3/L4 tools require approval or are denied for the pilot.
• Export one evidence packet for a live run and verify the route explanation is understandable.
• Verify audit rows exist for login/key/credential/policy/approval/artifact actions used in the pilot.
• Review private web fetch and private webhook posture.
• Record not-yet evidence needed before production expansion.

Platform operator:

• Set PUNK_API_KEY, dashboard admin credentials, and login mode for public deployments.
• Issue scoped, non-admin tenant API keys and pin them to app ids where possible.
• Set a valid PUNK_ENCRYPTION_KEY before storing credentials.
• Use Postgres for deployed environments; run a standalone worker or serverless cron tick.
• Configure live providers or tenant BYOK before production-like traffic.
• Keep mock provider and mock failover out of production unless the risk is documented.
• Set rate limits, private-network controls, retention, redaction, and backup posture.
• Confirm /api/v1/readiness has no unexpected attention rows.
• Review /api/v1/jobs, /api/v1/audit, and failed runs during pilot rollout.
• Exercise artifact rollback/quarantine before expanding optimize-mode traffic.

Evidence packet for an enterprise review:

• Readiness receipt.
• Example run evidence packet.
• Audit export for the review window.
• Policy files or policy summary.
• Tenant settings export or screenshots for retention/redaction/DLP/learning controls.
• Provider-key source evidence for example runs.
• Connector manifest excerpts for enabled tools.
• Backup/restore evidence from the deployment operator.
• Incident and rollback drill notes.

Compliance Mapping

This mapping is for review planning. It is not a compliance attestation.

Not Yet And Evidence Needed

Do not claim these without separate evidence:

• A completed SOC 2, ISO 27001, HIPAA, or other formal compliance attestation.
• A customer-specific DPA, BAA, subprocessor list, data residency commitment, or provider retention commitment.
• Customer-managed encryption keys or database-level row security.
• SSO/SAML/SCIM support unless it has been implemented and documented elsewhere.
• SIEM-native export, immutable external audit archive, or legal hold workflow.
• A production incident notification SLA.
• That live provider traffic has no provider-side retention or training exposure. Review each configured provider contract.

When a reviewer asks for one of these, treat it as an evidence request, not a product claim.