sops

Encrypt a file

$ sops -e [path/to/file.json] > [path/to/file.enc.json]

$ sops -d [path/to/file.enc.json]

$ sops updatekeys [path/to/file.enc.yaml]

$ sops -r [path/to/file.enc.yaml]

$ sops -d --input-type json [path/to/file.enc.json]

$ sops -d --extract '["an_array"][1]' [path/to/file.enc.json]

$ diff <(sops -d [path/to/secret1.enc.yaml]) <(sops -d [path/to/secret2.enc.yaml])

sops [options] [command] [arguments]

Common commands:
  sops edit [file]
  sops decrypt [options] [file]
  sops encrypt [options] [file]
  sops updatekeys [file]
  sops set [options] <path> <value> [file]
  sops get [options] <path> [file]

-d, --decrypt
    Decrypts the specified file. If no file is given, decrypts from standard input.

-e, --encrypt
    Encrypts the specified file. If no file is given, encrypts from standard input.

-i, --in-place
    Modifies the file in place. Used with `decrypt`, `encrypt`, `edit`, `set`, `updatekeys`.

-f, --force
    Force overwrite when writing output to a file.

--set
    Sets a value at a specified path within the encrypted file.

--get
    Retrieves a value from a specified path within the encrypted file.

--add-kms-key
    Adds an AWS KMS key ARN to the file's encryption keys.

--add-pgp-key
    Adds a PGP key fingerprint to the file's encryption keys.

--rotate
    Rotates the data key used for encryption.

--unencrypted-regex
    Specifies a regex for keys whose values should remain unencrypted.

--input-type
    Explicitly specifies the input file type (e.g., yaml, json, dotenv, binary).

--output-type
    Explicitly specifies the output file type.

--config
    Specifies a custom configuration file for sops.

--kms-key
    Specifies an AWS KMS key to use for encryption/decryption if not in file metadata.

--pgp-key
    Specifies a PGP key to use for encryption/decryption if not in file metadata.

--azkv
    Specifies an Azure Key Vault URL to use.

--gcp-kms
    Specifies a Google Cloud KMS key path to use.

--version
    Prints the sops version and exits.

--help
    Displays help information for sops or a specific command.

sops (Secrets OPerationS) is an editor and a data encryption tool by Mozilla, designed specifically for encrypting, decrypting, and managing structured data files like YAML, JSON, ENV, INI, and binary files. Its primary use case is for managing sensitive configuration data in development, staging, and production environments, often within CI/CD pipelines.

Unlike general-purpose encryption tools, sops encrypts only the values within a structured file while preserving the keys and overall file structure. This allows for version control of encrypted configuration files, as changes to unencrypted parts (like variable names) do not require re-encryption of the entire file. When a sops-encrypted file is opened for editing, it decrypts the values on-the-fly, and re-encrypts them upon saving.

sops supports multiple Key Management Systems (KMS) and methods, including AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault (via a plugin), and PGP. It stores the encryption metadata directly within the encrypted file, enabling seamless decryption by anyone with access to the appropriate decryption key. This makes it a powerful tool for secure secret management in cloud-native and DevOps workflows.

sops is designed for structured data and might not be suitable for general-purpose binary file encryption where preserving structure isn't a concern. It relies on external key management systems (KMS or GPG), meaning the security of your secrets is ultimately tied to the security of these underlying systems and their access controls. Network connectivity is required for cloud-based KMS services. While sops aims to make secret management easy, misconfiguration of `--unencrypted-regex` or manual file editing outside of sops could inadvertently expose sensitive data.

When sops encrypts a file, it adds a top-level 'sops' key to the file (for YAML/JSON/INI) or a header (for binary/dotenv). This key contains metadata essential for decryption, including the data key encrypted by your chosen KMS/PGP keys, creation timestamps, and other versioning information. This means sops-encrypted files are not just raw encrypted blobs; they carry their decryption instructions with them.

sops itself does not manage cryptographic keys. Instead, it acts as an intermediary, leveraging existing, robust key management systems (like AWS KMS, GCP KMS, Azure Key Vault, or your local GPG setup) to encrypt and decrypt the symmetric data keys used for file content. This offloads the complex and critical task of key lifecycle management, rotation, and access control to specialized, hardened services or well-established PGP practices.

sops is widely used for:
  * Managing environment variables and configuration files containing API keys, database credentials, or other sensitive information in source control.
  * Encrypting Kubernetes Secrets definitions before applying them to a cluster, ensuring secrets are not stored in plaintext in Git.
  * Integrating with CI/CD pipelines to decrypt configuration files at deployment time, ensuring sensitive data is only exposed to authorized build agents.
  * Providing a secure way for development teams to share and collaborate on sensitive configuration data.

sops was developed by Mozilla to address the challenge of managing secrets in version-controlled configuration files, especially within automated deployment pipelines. It was initially released around 2016-2017, gaining traction as cloud-native architectures and DevOps practices became more prevalent. Its strength lies in its ability to integrate with various cloud provider KMS solutions and PGP, offering a flexible and secure way to handle sensitive data in environments like Kubernetes, Terraform, and Ansible. Over time, it has evolved with community contributions, adding support for more file formats and KMS providers, solidifying its position as a go-to tool for secret management in the modern software development landscape.

gpg(1), openssl(1), vault(1), ansible-vault(1), kubectl(1), git-secret(1)