omraade

Omraade ([ɔmroːdeː], normally spelled område), from the Swedish word for "area", is an application that injects secrets defined via references in environment variables securely from a backend secret store. By storing references to a secret's location within a secret store rather than its content itself, a secret's actual content cannot simply be read from the environment (or an .env file etc.) by other applications. Instead, omraade then requests the referenced content from the secret store.

The most common usage for injection is running another command while only resolving secret references during the command's execution (i.e., during its runtime), discarding the resolved environment afterwards.

Usage

This project provides a command-line application omraade, either as a Python application, or optionally as a compiled binary independent of a local Python environment.

The application supports a number of command-line arguments, which can be listed via --help. The application uses subcommands to dispatch specific functionality, and subcommand-specific arguments can be listed via <subcommand> --help:

usage: app.py [-h] [--scheme SCHEME] [--backend {keepass}] [-d PATH] [-P PASSWORD] [-K KEYFILE] {run} ...

options:
  -h, --help            show this help message and exit

config:
  --scheme SCHEME       Omraade URI scheme, default: omraade
  --backend {keepass}   Omraade secret store backend, default: keepass

keepass:
  -d, --database PATH   Keepass database path
  -P, --password PASSWORD
                        Keepass database password
  -K, --keyfile KEYFILE
                        Keepass database keyfile

subcommands:
  {run}
    run

The application itself can also be configured via environment variables, which have to start with the prefix OMRAADE_, followed by the option, with all parts of the variable separated by underscores (_). For example, to provide the database path via ENV, the following invocations are equivalent:

# Generic ENV via `export` followed by application call
export OMRAADE_DATABASE=/dev/shm/example.kdbx
omraade run --password "Example password" -- printenv
# In-line ENV during application call
OMRAADE_DATABASE=/dev/shm/example.kdbx omraade run --password "Example password" -- printenv
# Explicit command-line argument during application call
omraade run --database /dev/shm/example.kdbx --password "Example password" -- printenv

If both an environment variable and a command-line argument are present, CLI arguments take precedence and override applicable ENVs.

Example

Let's assume that secrets are stored in a local Keepass database. The database's filename can be specified via --database <filename>, and its password via --password. With this information, omraade is able to find and decrypt the database.

References to secrets contained within this database can then be stored as arbitrary environment variables, referencing the omraade URI scheme, e.g.:

export TEST_FOO="omraade:/First/Second/Push#token"

This instructs omraade to look for a secret with the title Push, located in the nested groups First -> Second. The URI fragment further instructs omraade to return the value from the token attribute (if no fragment is specified, omraade will return the password attribute for Keepass secrets).

In order to wrap the command printenv by running omraade run --database <filename> --password <password> -- printenv, the omraade application first unlocks the relevant database, then replaces all valid omraade URIs with their resolved values from the Keepass database, and sets this as the active environment for the printenv command. The environment is not exported, so as soon as the wrapped command returns, omraade terminates, thus both discarding the resolved values in its temporary environment and closing the open database again.

Development

This project is written in python3. It uses uv for dependency management, pytest for testing, black for formatting, and nuitka for binary compilation.