> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lanesync.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise security

> Security model for LaneSync — envelope encryption, tenant isolation, and evidence data protection.

LaneSync handles **CI security evidence** — CVE scan reports, SAST findings, test failure details, and quality metrics. This data is treated as highly sensitive and protected with industry-standard envelope encryption.

## Encryption architecture

LaneSync uses **envelope encryption** (the same pattern as AWS KMS, Google Cloud KMS, and Azure Key Vault):

1. A **Data Encryption Key (DEK)** encrypts the sensitive payload (AES-256-GCM).
2. The DEK is wrapped by a **Key Encryption Key (KEK)** managed in AWS KMS (staging/production) or a local software KEK (development).
3. Stored format: `ciphertext + wrapped DEK` — decrypting requires both KMS access and the correct encryption context.

```mermaid theme={null}
flowchart LR
  data[Sensitive data]
  dek[DEK in memory]
  kek[KEK in KMS]
  db[(Database / S3)]

  data --> dek
  dek --> db
  dek --> kek
  kek --> db
```

### Per-tenant key isolation

Every encrypt/decrypt operation includes an **encryption context** with `tenant_id`. AWS KMS cryptographically binds the ciphertext to that context — attempting to decrypt with a different tenant's context fails, even with valid KMS permissions.

Application config secrets (GitHub App credentials) use a separate context: `{ scope: app_config, profile: staging }`.

## What is encrypted

| Data                               | Storage                                  | Protection                        |
| ---------------------------------- | ---------------------------------------- | --------------------------------- |
| CVE / SAST HTML reports            | KMS-encrypted S3 bucket (pointers in DB) | Envelope encryption + SSE-KMS     |
| Quality metrics (vuln counts)      | PostgreSQL JSONB                         | Envelope encryption               |
| Test error messages / stack traces | PostgreSQL TEXT                          | Envelope encryption               |
| GitHub App credentials             | PostgreSQL (app\_config)                 | Envelope encryption               |
| Milestone stage, issue counts      | PostgreSQL                               | RLS only (non-sensitive metadata) |

LaneSync does **not** store application source code.

## Tenant isolation

Each GitHub organization maps to one **tenant**. PostgreSQL **Row Level Security (RLS)** enforces that queries only return rows for the active tenant.

```mermaid theme={null}
flowchart TB
  req[HTTP request]
  session[Session tenantId]
  ctx[tenantContext async local]
  rls[PostgreSQL RLS policies]
  data[(Tenant-scoped data)]

  req --> session
  session --> ctx
  ctx --> rls
  rls --> data
```

RLS protects against application-layer bugs. Envelope encryption protects against **database credential compromise** — the defense-in-depth layer.

See [Multi-tenancy](/concepts/multi-tenancy).

## Authentication

| Surface                          | Mechanism                                                                 |
| -------------------------------- | ------------------------------------------------------------------------- |
| Dashboard users                  | GitHub OAuth + session cookie                                             |
| GitHub webhooks                  | HMAC signature (`X-Hub-Signature-256`)                                    |
| CI evidence upload & deploy gate | GitHub Actions OIDC JWT (`audience=lanesync`) or scoped API key (`lsk_*`) |
| Evidence report download         | Session auth + tenant membership check                                    |
| Team invites                     | HMAC-signed tokens, 7-day expiry                                          |
| Config repo warnings             | Session auth + tenant-scoped query                                        |

Session cookies are `httpOnly`, `sameSite=lax`, and `secure` in production.

### CI workload identity

LaneSync follows the industry-standard **OIDC workload identity** pattern (same approach as AWS, GCP, Azure, and Datadog CI):

* GitHub Actions mints a short-lived JWT per workflow run
* LaneSync verifies the signature against GitHub's JWKS
* Tenant is derived from the `repository_owner` claim — not from request body fields
* Optional per-tenant API keys (`lsk_*`) support non-GitHub CI; keys are SHA-256 hashed at rest

### Rate limiting and abuse protection

* Global and per-endpoint rate limits on public surfaces
* Webhook body size cap (1 MB) before signature verification
* Evidence report HTML served with sandbox CSP and `Content-Disposition: attachment` to prevent stored XSS

## Database access model

* **Migration role** (superuser): schema bootstrap only; connection pool closed after init.
* **sdlc\_app role**: runtime queries with `FORCE ROW LEVEL SECURITY` — no BYPASSRLS.

See `infrastructure/terraform/DB_ACCESS.md` in the repository.

## Audit logging

Security-sensitive actions are logged to the `audit_log` table (tenant-scoped):

* Evidence uploads (`evidence.upload`)
* Report views (`evidence.report.view`)

KMS `GenerateDataKey` and `Decrypt` calls are auditable via AWS CloudTrail (when enabled).

## Key rotation

* **KEK**: AWS KMS automatic rotation every 365 days (enabled in Terraform).
* **DEK**: unique per record — KEK rotation re-wraps DEKs without re-encrypting data.
* **Application secrets**: rotate via AWS Secrets Manager (recommended 90-day cadence).

## Compliance readiness

| Artifact                                                      | Status                            |
| ------------------------------------------------------------- | --------------------------------- |
| [SOC 2 control mapping](/enterprise/soc2-controls)            | Readiness document                |
| [Subprocessor list](/enterprise/subprocessors)                | Published                         |
| [DPA template](/enterprise/dpa)                               | Template for enterprise customers |
| [security.txt](https://lanesync.dev/.well-known/security.txt) | Responsible disclosure            |

SOC 2 Type II certification requires an external audit — contact `security@lanesync.dev` for the latest status.

## Hardening checklist (self-hosted)

<Steps>
  <Step title="TLS everywhere">
    Terminate HTTPS at load balancer or reverse proxy. Set `trust proxy` (enabled in backend).
  </Step>

  <Step title="Set KMS and S3 env vars">
    `KMS_KEY_ID`, `EVIDENCE_BUCKET`, `AWS_REGION` for envelope encryption and blob storage.
  </Step>

  <Step title="Rotate secrets">
    `SESSION_SECRET`, `ENCRYPTION_KEY`, GitHub App private key, database credentials.
  </Step>

  <Step title="Use sdlc_app DB role">
    Set `DATABASE_APP_URL` to a non-superuser role. Never run the app as postgres superuser.
  </Step>

  <Step title="Backup PostgreSQL and S3">
    Milestone, evidence metadata, and encrypted blobs — include both in DR plan.
  </Step>
</Steps>

## Related

* [Enterprise overview](/enterprise/overview)
* [Install the GitHub App](/guides/install-github-app)
* [FAQ — security](/reference/faq)