Oubliette

The Oubliette Security suite — one install, one CLI.

oubliette is the umbrella distribution for the Oubliette Security product suite. It gives you a single oubliette command, an install-time choice of which modules you want, and a threat-model engine that tells you which of them your system actually needs.

pip install oubliette-suite     # the CLI + the threat-model engine
oubliette init                  # choose your modules -> writes oubliette.toml

The distribution is oubliette-suite (the bare oubliette name is taken on PyPI by an unrelated project); the installed import package and CLI are still oubliette.

Start here: scope the work

The threat-model engine depends on no product and runs before you have installed — or bought — anything. Point it at a description of your system and it tells you which attacks apply and what to run.

oubliette threatmodel init                      # writes a commented intake file
oubliette threatmodel run --profile system.toml # threat model + run plan

Every recommendation cites the answers that caused it, so you can audit why a control was proposed rather than taking it on faith.

Then run what it found

The plan isn't a document you retype — it configures the products:

oubliette threatmodel apply                     # plan -> oubliette.toml
oubliette exec --target https://my-system --dry-run

apply writes the dungeon scenario categories your system warrants and the shield settings that go with them. exec runs them, printing the reason each command exists before it runs:

  # threat model selected the tool_exploitation category
  $ oubliette dungeon run --category tool_exploitation --target https://my-system
    env: SHIELD_FAIL_OPEN=false SHIELD_MCP_BLOCK_HIGH=true ...

exec reads oubliette.toml, not the plan — so if you edit the file, you get what you edited. Drop a category and it stops running. --dry-run executes nothing.

Choose your modules

oubliette init                      # interactive menu
oubliette init --sku deceive        # or pick a bundle outright
oubliette init --modules dungeon,shield

This writes oubliette.toml and prints the exact pip install line for what you chose. Bundles map to pip extras, so these are equivalent:

pip install "oubliette-suite[deceive]"

Configuration

oubliette.toml is the shared config file. Precedence, weakest first:

defaults  <  oubliette.toml  <  OUBLIETTE_* env vars  <  CLI flags

Env vars win over the file on purpose: deployments that configure the suite through OUBLIETTE_* today behave identically after adopting the file, and per-environment overrides need no file edit.

Two limits worth knowing, both deliberate:

• OUBLIETTE_* overrides an existing setting; it cannot introduce a new one. A dotted key is not recoverable from a variable name — OUBLIETTE_A_B_C could be a.b_c or a_b.c — so a variable that matches no known key is ignored rather than guessed at.
• A product's own env vars beat the plan. oubliette exec passes the shield settings from your config as environment, but if SHIELD_FAIL_OPEN is already set in the shell it wins, and exec says so. Same precedence rule, applied to the products rather than to the suite.

Usage

oubliette version              # installed components + versions
oubliette init                 # choose modules
oubliette threatmodel run -p system.toml
oubliette threatmodel apply    # write the plan into oubliette.toml
oubliette exec --target URL    # run it (--dry-run to preview)
oubliette dungeon --help       # == oubliette-dungeon --help

The CLI shells out to each tool's own console script, so any sub-tool invocation is identical to calling that tool directly — the umbrella just gives one entry point.

Components

Note: the console script barbican can collide with OpenStack’s PyPI barbican binary — prefer oubliette barbican, and be aware of PATH order.

oubliette shield is a library with no CLI; the command explains how to import it. Roadmap products are surfaced by the threat model as things to plan for and are not offered by oubliette init, so you are never handed an action you cannot take.

The product manifest

src/oubliette/data/products.toml is the single source of truth for the product line. The pip extras, the installer menu, the CLI's dispatch table, and the threat model's available/roadmap split are all derived from it — a product is added there and nowhere else.

CI fails if the committed extras drift from the manifest:

python -m oubliette.metapackage          # check
python -m oubliette.metapackage --emit   # print the correct block

Development

uv venv --python 3.13
uv pip install -e ".[test]"
pytest