plugin-drone-docker/COSIGN_USAGE.md

Cosign Integration for Drone-Docker

This document describes how to use the cosign container image signing feature in drone-docker.

Overview

The drone-docker plugin now supports automatic container image signing using cosign after each successful push. This provides cryptographic verification that images haven't been tampered with.

Environment Variables

The plugin accepts three cosign-related environment variables:

PLUGIN_COSIGN_PRIVATE_KEY (Required for signing)

• Description: Private key for signing (PEM format content or file path)
• Format: Either PEM content or file path to private key
• Usage: Should be provided via secrets

PLUGIN_COSIGN_PASSWORD (Optional)

• Description: Password for encrypted private keys
• Usage: Only needed if your private key is password-protected

PLUGIN_COSIGN_PARAMS (Optional)

• Description: Additional cosign parameters
• Examples:
  • -a build_id=123 (add annotations)
  • --tlog-upload=false (disable transparency log)
  • --rekor-url=https://custom-rekor.example.com (custom rekor instance)

Usage Examples

1. Basic Signing (Drone)

kind: pipeline
type: docker
name: default

steps:
- name: docker
  image: plugins/docker
  settings:
    repo: myregistry/myapp
    tags: latest
    cosign_private_key:
      from_secret: cosign_private_key
    cosign_password:
      from_secret: cosign_password

2. Advanced Signing with Annotations (Drone)

steps:
- name: docker
  image: plugins/docker
  settings:
    repo: myregistry/myapp
    tags: 
      - latest
      - ${DRONE_BUILD_NUMBER}
    cosign_private_key:
      from_secret: cosign_private_key
    cosign_params: "-a build_id=${DRONE_BUILD_NUMBER} -a commit_sha=${DRONE_COMMIT_SHA} -a branch=${DRONE_BRANCH}"

3. Harness CI/CD Usage

- step:
    type: Plugin
    name: Build and Sign
    identifier: build_and_sign
    spec:
      connectorRef: account.harnessImage
      image: plugins/docker
      settings:
        repo: myregistry/myapp
        tags: <+pipeline.sequenceId>
        cosign_private_key: <+secrets.getValue("cosign_private_key")>
        cosign_password: <+secrets.getValue("cosign_password")>
        cosign_params: "-a harness_build=<+pipeline.sequenceId> -a harness_project=<+project.name>"

Key Management

Generating Cosign Keys

# Generate a new key pair
cosign generate-key-pair

# This creates:
# - cosign.key (private key) 
# - cosign.pub (public key)

Storing Keys Securely

Harness Secrets:

1. Go to Project Settings → Secrets
2. Create new secret with type "File" for private key
3. Create new secret with type "Text" for password

Security Features

Automatic Validation

• ✅ Private key format validation: Ensures PEM format is correct
• ✅ Password requirement detection: Warns if encrypted key needs password
• ✅ Keyless signing prevention: Warns that OIDC keyless signing isn't supported

Error Handling

• Invalid private key: ❌ Invalid private key format. Expected PEM format
• Missing password: 🔐 Encrypted private key requires password. Set PLUGIN_COSIGN_PASSWORD
• Keyless signing: ⚠️ WARNING: Keyless signing (OIDC) isn't supported yet in this plugin

Signing Behavior

When Signing Occurs

• ✅ After each successful push: Images are signed immediately after push
• ✅ Multiple tags: Each tag gets signed individually
• ✅ Push-only mode: Works with existing images
• ✅ Dry-run respect: Skips signing in dry-run mode

Image References

• Preferred: Signs by digest (e.g., image@sha256:abc123...) for security
• Fallback: Signs by tag if digest unavailable

Authentication

• Registry auth: Automatically uses existing Docker registry credentials

Verification

To verify a signed image:

# Verify with public key
cosign verify --key cosign.pub myregistry/myapp:latest

# Verify with annotations
cosign verify --key cosign.pub \
  -a build_id=123 \
  myregistry/myapp:latest

Troubleshooting

Common Issues

1. "cosign: command not found"

   • The container image includes cosign binary
   • Use the latest plugin image: plugins/docker:latest

2. "keyless signing not supported"

   • This plugin only supports private key signing
   • Don't use --oidc or --identity-token in cosign_params

3. "encrypted private key requires password"

   • Set PLUGIN_COSIGN_PASSWORD environment variable
   • Or use an unencrypted private key

4. Registry authentication issues

   • Cosign uses the same Docker registry credentials
   • Ensure Docker login is working first