docs: add Docker Image Security Guide (cosign verification & deployment best practices) by krrish-berri-2 · Pull Request #25439 · BerriAI/litellm

krrish-berri-2 · 2026-04-09T18:39:05Z

Relevant issues

Addresses community request for a dedicated security guide covering cosign image verification across all Docker image variants, CI/CD enforcement, and deployment best practices.

Pre-Submission checklist

I have Added testing in the tests/test_litellm/ directory — N/A (docs-only change, no code)
My PR passes all unit tests on make test-unit
My PR's scope is as isolated as possible, it only solves 1 specific problem
I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Type

📖 Documentation

Changes

Adds a new Docker Image Security Guide (docs/proxy/docker_image_security.md) covering:

Which images are signed — table of all signed GHCR variants (litellm, litellm-database, litellm-non_root, litellm-spend_logs) with a note on enterprise images
How to verify signatures — cosign verify commands with examples for each image variant, using both pinned commit hash and release tag methods
How to enforce verification automatically:
- Kubernetes via Sigstore Policy Controller (with a ready-to-use ClusterImagePolicy YAML)
- GCP Binary Authorization
- AWS ECS/EKS approaches
- GitHub Actions gate step
Recommended deployment patterns — digest pinning vs stable release tags, a safe upgrade checklist

Also:

Added the new page to the sidebar under Setup & Deployment (right after the existing deploy page)
Added a cross-link from the existing cosign section in deploy.md to the new guide

The Docusaurus build passes successfully with no new broken links.

Slack Thread

…loyment best practices - New doc page covering all signed image variants, verification commands, CI/CD enforcement (K8s Sigstore Policy Controller, GCP Binary Authorization, AWS/EKS, GitHub Actions), digest pinning, and safe upgrade patterns - Added to sidebar under Setup & Deployment - Cross-linked from the existing deploy.md cosign section Co-authored-by: Krrish Dholakia <krrish-berri-2@users.noreply.github.com>

CLAassistant · 2026-04-09T18:39:12Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

vercel · 2026-04-09T18:39:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Apr 9, 2026 6:40pm

codspeed-hq · 2026-04-09T18:40:51Z

Merging this PR will not alter performance

✅ 16 untouched benchmarks

_{Comparing cursor/devops-security-guide-5bf3 (8e66652) with main (cd9c511)}

codecov · 2026-04-09T18:42:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

krrish-berri-2 · 2026-04-09T18:45:01Z

+| Image | Description |
+|---|---|
+| `ghcr.io/berriai/litellm` | Core proxy |
+| `ghcr.io/berriai/litellm-database` | Proxy with Postgres dependencies |


please mark litellm-database as a deprecated image

@cursoragent

krrish-berri-2 · 2026-04-09T18:45:19Z

+| `ghcr.io/berriai/litellm` | Core proxy |
+| `ghcr.io/berriai/litellm-database` | Proxy with Postgres dependencies |
+| `ghcr.io/berriai/litellm-non_root` | Non-root variant |
+| `ghcr.io/berriai/litellm-spend_logs` | Spend-logs sidecar |


please remove references to litellm-spend_logs @cursoragent

greptile-apps · 2026-04-09T18:53:30Z

Greptile Summary

This PR adds a new docker_image_security.md documentation page covering cosign image verification for all LiteLLM GHCR variants, Kubernetes/GCP/AWS/GitHub Actions enforcement patterns, and a safe upgrade checklist. The embedded ClusterImagePolicy public key matches cosign.pub in the repository, and the sidebar and cross-link in deploy.md are wired correctly.

The GitHub Actions gate example is missing a sigstore/cosign-installer step; without it the cosign verify command will always fail with "command not found" on standard GitHub-hosted runners.

Confidence Score: 4/5

Safe to merge after adding the missing cosign install step to the GitHub Actions example.

One P1 finding: the GitHub Actions snippet is missing sigstore/cosign-installer, so copy-pasting it will break real pipelines. All other findings are P2 or informational.

docs/my-website/docs/proxy/docker_image_security.md — GitHub Actions gate section (lines 136-143)

Vulnerabilities

No security concerns identified. The public key embedded in the ClusterImagePolicy YAML matches the repository's cosign.pub exactly. No secrets or sensitive values are exposed.

Important Files Changed

Filename	Overview
docs/my-website/docs/proxy/docker_image_security.md	New security guide for Docker image verification; public key matches cosign.pub in repo; GitHub Actions example is missing the required cosign-installer step, which will cause runtime failure on standard runners.
docs/my-website/docs/proxy/deploy.md	Adds a cross-link from the existing cosign section to the new Docker Image Security Guide; change is accurate and non-breaking.
docs/my-website/sidebars.js	Adds proxy/docker_image_security to the sidebar immediately after proxy/deploy; placement is correct and consistent with existing ordering.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Pull LiteLLM image from GHCR] --> B{Verify with cosign}
    B -->|Pinned commit hash| C[cosign verify --key raw.githubusercontent...commit.../cosign.pub image:tag]
    B -->|Release tag| D[cosign verify --key raw.githubusercontent...tag.../cosign.pub image:tag]
    C --> E{Verification passes?}
    D --> E
    E -->|Yes| F[Deploy to environment]
    E -->|No| G[Reject / fail pipeline]
    F --> H{Enforcement layer}
    H --> I[Kubernetes: Sigstore Policy Controller]
    H --> J[GCP: Binary Authorization]
    H --> K[AWS EKS: OPA/Gatekeeper]
    H --> L[GitHub Actions: cosign verify gate]

_{Reviews (1): Last reviewed commit: "docs: add Docker Image Security Guide fo..." | Re-trigger Greptile}

greptile-apps · 2026-04-09T18:53:34Z

+
+```yaml
+- name: Verify LiteLLM image signature
+  run: |
+    cosign verify \
+      --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
+      ghcr.io/berriai/litellm-database:${{ env.LITELLM_VERSION }}
+```


Missing cosign install step in GitHub Actions example

GitHub-hosted runners do not ship with cosign. The snippet will fail with command not found on any standard runner. A sigstore/cosign-installer step must precede the verify call.

Suggested change

```yaml

- name: Verify LiteLLM image signature

run: |

cosign verify \

--key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \

ghcr.io/berriai/litellm-database:${{ env.LITELLM_VERSION }}

```

- name: Install cosign

uses: sigstore/cosign-installer@v3

- name: Verify LiteLLM image signature

run: |

cosign verify \

--key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \

ghcr.io/berriai/litellm-database:${{ env.LITELLM_VERSION }}

greptile-apps · 2026-04-09T18:53:35Z

+Get the digest after pulling:
+
+```bash
+docker inspect --format='{{index .RepoDigests 0}}' \
+  ghcr.io/berriai/litellm-database:v1.83.0-stable
+```


docker inspect requires a locally pulled image

docker inspect only reads metadata of images already present on disk. If the image hasn't been pulled, this command silently returns nothing or errors out. A note (or a docker pull before the inspect) would prevent confusion.

Suggested change

Get the digest after pulling:

```bash

docker inspect --format='{{index .RepoDigests 0}}' \

ghcr.io/berriai/litellm-database:v1.83.0-stable

```

Get the digest after pulling the image:

```bash

docker pull ghcr.io/berriai/litellm-database:v1.83.0-stable

docker inspect --format='{{index .RepoDigests 0}}' \

ghcr.io/berriai/litellm-database:v1.83.0-stable

…loyment best practices (#25439) - New doc page covering all signed image variants, verification commands, CI/CD enforcement (K8s Sigstore Policy Controller, GCP Binary Authorization, AWS/EKS, GitHub Actions), digest pinning, and safe upgrade patterns - Added to sidebar under Setup & Deployment - Cross-linked from the existing deploy.md cosign section Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Krrish Dholakia <krrish-berri-2@users.noreply.github.com>

vercel Bot deployed to Preview April 9, 2026 18:40 View deployment

krrish-berri-2 commented Apr 9, 2026

View reviewed changes

krrish-berri-2 requested a review from yuneng-berri April 9, 2026 18:46

yuneng-berri approved these changes Apr 9, 2026

View reviewed changes

krrish-berri-2 marked this pull request as ready for review April 9, 2026 18:50

krrish-berri-2 merged commit 3a6db70 into main Apr 9, 2026
48 of 50 checks passed

krrish-berri-2 deleted the cursor/devops-security-guide-5bf3 branch April 9, 2026 18:50

greptile-apps Bot reviewed Apr 9, 2026

View reviewed changes

emerzon mentioned this pull request Apr 12, 2026

add azure ai grok 4 20 models #25582

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add Docker Image Security Guide (cosign verification & deployment best practices)#25439

docs: add Docker Image Security Guide (cosign verification & deployment best practices)#25439
krrish-berri-2 merged 1 commit intomainfrom
cursor/devops-security-guide-5bf3

krrish-berri-2 commented Apr 9, 2026

Uh oh!

CLAassistant commented Apr 9, 2026

Uh oh!

vercel Bot commented Apr 9, 2026 •

edited

Loading

Uh oh!

codspeed-hq Bot commented Apr 9, 2026

Uh oh!

codecov Bot commented Apr 9, 2026

Uh oh!

krrish-berri-2 Apr 9, 2026

Uh oh!

krrish-berri-2 Apr 9, 2026

Uh oh!

krrish-berri-2 Apr 9, 2026

Uh oh!

Uh oh!

greptile-apps Bot commented Apr 9, 2026

Vulnerabilities

Important Files Changed

Uh oh!

greptile-apps Bot Apr 9, 2026

Uh oh!

greptile-apps Bot Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

krrish-berri-2 commented Apr 9, 2026

Relevant issues

Pre-Submission checklist

Type

Changes

Uh oh!

CLAassistant commented Apr 9, 2026

Uh oh!

vercel Bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq Bot commented Apr 9, 2026

Merging this PR will not alter performance

Uh oh!

codecov Bot commented Apr 9, 2026

Codecov Report

Uh oh!

krrish-berri-2 Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

krrish-berri-2 Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

krrish-berri-2 Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps Bot commented Apr 9, 2026

Greptile Summary

Confidence Score: 4/5

Vulnerabilities

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel Bot commented Apr 9, 2026 •

edited

Loading