Metadata-Version: 2.4
Name: oubliette-suite
Version: 0.2.0
Summary: Scope your AI system's real threats, then run exactly the security work they call for.
Author-email: Oubliette Security <info@oubliettesecurity.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://oubliettesecurity.com
Project-URL: Repository, https://github.com/oubliettesecurity/oubliette-suite
Keywords: ai-security,llm-firewall,red-team,deception,agentic-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: oubliette-shield>=1.1.1
Requires-Dist: oubliette-dungeon>=1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: assess
Requires-Dist: oubliette-dungeon>=1.0; extra == "assess"
Provides-Extra: defend
Requires-Dist: oubliette-shield>=1.1.1; extra == "defend"
Requires-Dist: oubliette-warden>=0.2.0; extra == "defend"
Provides-Extra: deceive
Requires-Dist: oubliette-trap>=0.2; extra == "deceive"
Requires-Dist: oubliette-shield>=1.1.1; extra == "deceive"
Provides-Extra: full
Requires-Dist: oubliette-dungeon>=1.0; extra == "full"
Requires-Dist: oubliette-shield>=1.1.1; extra == "full"
Requires-Dist: oubliette-trap>=0.2; extra == "full"
Requires-Dist: oubliette-warden>=0.2.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: packaging>=23.0; extra == "dev"
Provides-Extra: test
Requires-Dist: oubliette-suite[dev]; extra == "test"

# 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.

```bash
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.

```bash
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:

```bash
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

```bash
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:

```bash
pip install "oubliette-suite[deceive]"
```

| SKU | Contains | For |
|---|---|---|
| `assess` | dungeon | Find out what an attacker can do to your AI system |
| `defend` | shield, warden | Firewall the model and gate what your agents may do |
| `deceive` | trap, shield | Make reconnaissance expensive and loud |
| `full` | dungeon, shield, trap, warden | The whole suite |

## 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.

## Usage

```bash
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

| Command | Distribution | Role | Status |
|---|---|---|---|
| `oubliette shield` | `oubliette-shield` | AI firewall — 5-stage detection + deception (library) | available |
| `oubliette dungeon` | `oubliette-dungeon` | Adversarial testing — 72 scenarios, 10 categories | available |
| `oubliette trap` | `oubliette-trap` | Deception — MCP honeypot and canary tokens | available |
| `oubliette warden` | `oubliette-warden` | Safety-gated agent framework — gates plans, not just single actions | available |
| `oubliette barbican` | `oubliette-barbican` | Coordinated synthetic-influence detection | roadmap |

`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:

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

## Development

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