bouncer-core 0.1.1__tar.gz

bouncer_core-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-packages --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Test (pytest)
+        run: uv run pytest -q
+
+      - name: No-key benchmark path imports & scorer test
+        run: uv run python -m benchmark.run_agentdojo
+
+      # The split exists so a consumer of the engine alone never installs the
+      # MCP SDK -- and through it uvicorn, starlette, pydantic and pyjwt. That
+      # is a property of the dependency graph, so assert it against a real
+      # install rather than trusting the pyproject to stay honest.
+      - name: bouncer-core must not pull the MCP tree
+        run: |
+          uv venv /tmp/core-only --python ${{ matrix.python-version }}
+          VIRTUAL_ENV=/tmp/core-only uv pip install .
+          VIRTUAL_ENV=/tmp/core-only uv pip list > /tmp/core-only.txt
+          cat /tmp/core-only.txt
+          if grep -qiE '^(mcp|anyio|uvicorn|starlette|pydantic|pyjwt|mcp-types)[[:space:]]' /tmp/core-only.txt; then
+            echo "::error::bouncer-core has regained a dependency the split removed"
+            exit 1
+          fi

bouncer_core-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,85 @@
+name: Release
+
+# Tag-driven. `bouncer-core` and `bouncer-mcp` are versioned and released
+# together from this workspace; both are uploaded under PyPI Trusted Publishing
+# (OIDC), so no long-lived API token exists in this repository's secrets.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+
+      # Checked before the build, so a mistyped tag costs seconds rather than a
+      # failed upload. --frozen keeps this a pure read: no re-lock, no sync.
+      - name: The tag must match the version being published
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          for pkg in bouncer-core bouncer-mcp; do
+            version=$(uv version --package "$pkg" --short --frozen)
+            if [ "$tag" != "$version" ]; then
+              echo "::error::tag $GITHUB_REF_NAME does not match $pkg $version"
+              exit 1
+            fi
+          done
+
+      # Built into separate directories: a trusted-publishing token is minted
+      # per project, so each distribution is uploaded by its own step.
+      - name: Build both distributions
+        run: |
+          uv build --package bouncer-core --out-dir dist/core
+          uv build --package bouncer-mcp  --out-dir dist/mcp
+          ls -la dist/core dist/mcp
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+
+  # One job per distribution, each in its own environment. PyPI refuses a second
+  # pending trusted publisher whose owner, repository, workflow AND environment
+  # all match an existing one, so the two projects cannot share `pypi`.
+  publish-core:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # mints the OIDC token; nothing else is needed
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish bouncer-core
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/core
+
+  # After core, never alongside it: bouncer-mcp pins bouncer-core==<same version>,
+  # so publishing it first would briefly ship a package nobody can install.
+  publish-mcp:
+    needs: publish-core
+    runs-on: ubuntu-latest
+    environment: pypi-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish bouncer-mcp
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/mcp

bouncer_core-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+# regenerated on every benchmark run (RESULTS.md is the curated, committed doc)
+benchmark/audit.jsonl
+benchmark/audit-*.jsonl
+benchmark/results.json
+benchmark/results-raw.json
+benchmark/logs/
+
+# local smoke-test scratch (contains machine-specific absolute paths)
+smoke_work/
+
+__pycache__/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# local launch/marketing notes — never publish to the OSS repo
+docs/launch-posts.md

bouncer_core-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to Bouncer
+
+Thanks for helping build a deterministic safety layer for agent tool calls.
+This is security-adjacent code — the bar is correctness and clarity over
+cleverness. Small, well-tested PRs are far easier to accept than large ones.
+
+## Development setup
+
+Bouncer uses [uv](https://docs.astral.sh/uv/). From the repository root:
+
+```bash
+uv sync                # install the project + dev tools (pytest, ruff)
+uv run pytest -q       # run the full test suite
+uv run ruff check .    # lint
+```
+
+The benchmark harness is an optional extra (it pulls in AgentDojo):
+
+```bash
+uv run --extra benchmark python -m benchmark.run_agentdojo   # needs GEMINI_API_KEY
+uv run python -m benchmark.run_agentdojo                     # no key: scorer test only
+```
+
+CI runs exactly `ruff check .` and `pytest -q` on Python 3.12 and 3.13. Get
+both green locally before opening a PR.
+
+## The one rule that isn't negotiable: fail closed
+
+Bouncer is only useful if it never *silently* allows something it couldn't
+reason about. Every ambiguous case must resolve to `ask` or `deny`, never a
+silent `allow`. Concretely:
+
+- A tool marked `exfiltrating` with no usable `sink_params` treats **every**
+  argument as a destination.
+- An unknown/unpinned tool → `ask`, not `allow`.
+- A malformed policy file → `PolicyError` at load time (the proxy refuses to
+  start), not a best-effort partial parse.
+- A `deny` **must not** forward the call upstream. This invariant is load-
+  bearing; tests assert it, and any change near the decision path must keep it.
+
+If your change adds a new decision branch, add a test that proves the
+fail-closed direction, not just the happy path. See `tests/test_engine_sink_gate.py`
+for the style (red test first, then the engine change).
+
+## What makes a good PR
+
+- **Tests with it.** New behavior needs a test; a bug fix needs a regression
+  test that fails before your change and passes after.
+- **No LLM in the decision path.** The engine is deterministic by design.
+  Heuristics, packs, and taint rules are welcome; a model call inside
+  `ContractEngine.evaluate` is not.
+- **Type hints on every function signature** (params and return).
+- **Match the surrounding style.** Comment density, naming, and idiom should
+  read like the file you're editing. No docstrings on obvious functions.
+- **Keep the diff scoped.** Don't refactor surrounding code as part of a fix.
+
+## Adding or fixing a server pack
+
+Packs live in `src/bouncer/packs/*.yaml` and map a server's tools to policies.
+The most valuable contributions here are packs verified against a **real**
+server's `tools/list`:
+
+- Enumerate **every** destination-bearing argument as a `sink_param` — a
+  missed one is a silent exfiltration gap (see the sink-completeness note in
+  the README's limitations).
+- Prefer verified tool/param names over documented-but-unchecked ones; note in
+  a comment how you verified (e.g. "verified live 2026-07-06").
+- Add or update a test in `tests/test_packs.py`.
+
+## Reporting security issues
+
+Please do **not** open a public issue for a vulnerability in the enforcement
+logic (e.g. a way to make an exfiltrating call resolve to `allow`). See
+[SECURITY.md](SECURITY.md) for private disclosure.
+
+## Commit messages
+
+Conventional-commit style (`fix(engine): ...`, `feat(packs): ...`,
+`docs: ...`). Explain the *why* in the body when it isn't obvious from the diff.

bouncer_core-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bouncer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.