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

Example

Let's assume that secrets are stored in a local Keepass database. The database's filename can be specified via --database <filename>, and it's 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 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 (or it's default password attribute if unspecified).

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.