egressveil 0.2.0__tar.gz

egressveil-0.2.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local EgressVeil config and logs (may contain internal domains / audit data)
+/egressveil.yaml
+*.audit.jsonl
+audit.jsonl
+.egressveil/
+
+# Secrets - never commit
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db

egressveil-0.2.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+intends to follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-16
+
+First public release. EgressVeil is free and open source under the MIT
+License. This release protects Claude Code's Anthropic API traffic from
+leaking secrets and tokens. It is pre-alpha: see the README for coverage
+limitations.
+
+### Added: release and community
+
+- A release workflow builds and smoke-tests each release, attaches signed
+  build provenance, and creates the GitHub release. PyPI Trusted Publishing
+  is ready but turned off until the project is registered on PyPI (see
+  `docs/releasing.md`).
+- Official support for Python 3.13 and 3.14. CI tests Python 3.11 to 3.14 on
+  Linux, macOS and Windows.
+- `SUPPORT.md`, `CODEOWNERS`, and install instructions using pipx or pip with
+  the release wheel.
+
+### Added: Phase 1, the Claude Code gateway
+
+- `egressveil serve`: a local aiohttp gateway for the Anthropic Messages API
+  (`/v1/messages`, `/v1/messages/count_tokens`), with streaming passthrough,
+  bounded request bodies and stream chunks, verified TLS to an allowlisted
+  upstream, no redirect following, and no use of environment proxies.
+- An Anthropic request parser that inspects every string field, hardened
+  against duplicate keys, `NaN` and deep nesting.
+- `secrets` and `tokens` detectors with vendor, private-key, URL-credential,
+  generic-assignment, JWT, bearer and Basic auth rules.
+- A policy engine (the most restrictive action wins), keyed stable
+  redaction placeholders, and escalation to `BLOCK` for signed `thinking`
+  content and for URLs.
+- Strict-mode fail-closed handling for unsupported routes, content types and
+  encodings, invalid JSON, opaque images and PDFs, and detector errors.
+  Permissive mode forwards these and flags them.
+- A JSONL audit log with keyed digests and a `0600` key file. It never
+  records bodies, headers, query strings or raw values.
+- Host-header (DNS-rebinding) and browser-`Origin` rejection, and a local
+  `/_egressveil/health` endpoint.
+- `egressveil scan`: runs the detectors and policy over files or stdin.
+- `doctor` detects a running gateway and lists the active detectors.
+- Config option `gateway.allow_opaque_content`.
+- Runtime dependency: `aiohttp`.
+
+### Added: Phase 0, the foundation
+
+- Project scaffold: `src/` layout, Hatchling packaging, MIT license.
+- CLI commands: `egressveil version`, `egressveil config validate` and
+  `egressveil doctor`.
+- A strict YAML configuration schema with secure defaults enforced at
+  validation: loopback-only listener, https allowlisted upstreams, strict
+  mode, no raw-value audit logging, and no telemetry.
+- Secret-safe validation output, and rejection of config files that contain
+  credential-shaped values.
+- Documentation: architecture, threat model, security design, integrations
+  and roadmap.
+- CI: Ruff, strict mypy, and pytest on Python 3.11 and 3.12 across Linux,
+  macOS and Windows; a build check; and pip-audit dependency auditing.
+
+[Unreleased]: https://github.com/qmmughal/egressveil/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/qmmughal/egressveil/releases/tag/v0.2.0

egressveil-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EgressVeil 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.

egressveil-0.2.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.5
+Name: egressveil
+Version: 0.2.0
+Summary: The local privacy gateway for AI coding agents.
+Project-URL: Homepage, https://github.com/qmmughal/egressveil
+Project-URL: Issues, https://github.com/qmmughal/egressveil/issues
+Project-URL: Changelog, https://github.com/qmmughal/egressveil/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/qmmughal/egressveil/blob/main/SECURITY.md
+Author: EgressVeil contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,dlp,gateway,llm,privacy,redaction,security
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# EgressVeil
+
+**The local privacy gateway for AI coding agents.**
+
+[![CI](https://github.com/qmmughal/egressveil/actions/workflows/ci.yml/badge.svg)](https://github.com/qmmughal/egressveil/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+EgressVeil is a local-first, open-source security gateway. It detects sensitive
+information in the API traffic that supported AI coding agents send to LLM
+providers, and redacts or blocks it before it leaves your machine.
+
+**Free and open source, for everyone.** EgressVeil is released under the
+[MIT License](LICENSE). You can use it, modify it, redistribute it and build
+commercial products on it at no cost. There are no paid tiers, accounts,
+license keys or usage limits. It runs entirely on your machine, has no
+telemetry, and its only network connection is to the LLM provider you
+configure.
+
+> **Project status: pre-alpha (Phase 1).** EgressVeil now runs as a local
+> gateway for the **Anthropic Messages API**, the API Claude Code uses. It
+> detects **secrets and tokens** and blocks or redacts them according to your
+> policy. PII and internal-hostname detection, and support for other agents,
+> are not implemented yet. Detection is heuristic. Treat EgressVeil as one
+> layer of defense, not a guarantee.
+
+---
+
+## Why
+
+AI coding agents read your working tree and send large parts of it to a
+remote LLM API. That context can contain `.env` files, cloud credentials,
+customer data pasted into a test fixture, or internal hostnames. Today the
+only control most teams have is to hope that none of it gets read.
+
+EgressVeil sits between the agent and the provider API on `localhost`. It
+inspects each request, applies a policy you control (`ALLOW`, `REDACT`,
+`BLOCK`, `LOG_ONLY`), and writes an audit trail that never contains the raw
+secret.
+
+## What EgressVeil is not
+
+- **It is not a firewall for everything your agent does.** It inspects only
+  the LLM API traffic that a supported agent sends through it. Shell commands,
+  package installs, web fetches, MCP servers, git pushes and other network
+  activity from the agent or its tools are **not** covered.
+- It cannot inspect traffic that an agent sends straight to a vendor backend
+  that you can't redirect, which affects Cursor in particular (see
+  [Integrations](#integration-compatibility)).
+- It does not inspect responses from the model (planned).
+- It is not a replacement for keeping secrets out of your repository.
+
+See [docs/threat-model.md](docs/threat-model.md) for the full scope.
+
+## Quick start with Claude Code
+
+```bash
+egressveil serve
+```
+
+In another terminal, point Claude Code at the gateway and start it as usual:
+
+```bash
+# Linux/macOS
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
+claude
+```
+
+```powershell
+# Windows PowerShell
+$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8787"
+claude
+```
+
+Claude Code keeps its own credentials. EgressVeil passes the auth header to
+`api.anthropic.com` unchanged and never logs it.
+
+If a request contains something your policy blocks, the request never leaves
+your machine, and Claude Code shows an error like this:
+
+```text
+API Error: 400 EgressVeil: request blocked before leaving this machine:
+sensitive data detected: secrets/aws_access_key_id at messages[4].content[0].content[0].text.
+Remove the value from the conversation (for example start a new session)
+or adjust the EgressVeil policy. (request ev_3c1f0a9e2b7d4c11)
+```
+
+> **Note on `BLOCK`:** Claude Code resends the whole conversation on every
+> turn. Once a blocked value is in the conversation, every later request is
+> blocked too, until you start a new session (for example with `/clear`). If
+> you prefer to keep working, set the `secrets` and `tokens` rules to
+> `REDACT`. The model then sees a placeholder such as
+> `[EGRESSVEIL:aws_access_key_id:5b2e91c0]` instead of the value.
+
+## Features
+
+### Implemented
+
+| Feature | Notes |
+| --- | --- |
+| `egressveil serve` | A local gateway for the Anthropic Messages API (`/v1/messages`, `/v1/messages/count_tokens`), with streaming (SSE) passthrough |
+| Secret detectors | Anthropic, OpenAI, AWS, GitHub, GitLab, Slack, Stripe, Google, npm and Hugging Face keys; private keys; credentials in URLs; generic `password = "..."` and `.env` assignments |
+| Token detectors | JWTs, bearer tokens and Basic auth headers |
+| Policy engine | `ALLOW` / `REDACT` / `BLOCK` / `LOG_ONLY` for each detector. The most restrictive action wins |
+| Redaction | Placeholders keyed by an HMAC of the value, so the same value always gets the same placeholder. That keeps conversations consistent and prompt caching effective. Redacted values are never restored |
+| Fail-closed strict mode | Blocks unsupported endpoints, non-JSON or compressed bodies, malformed or duplicate-key JSON, too-deep nesting, uninspectable images and PDFs, and requests where a detector fails |
+| Audit log | JSONL with request metadata, rule IDs, JSON locations and keyed digests. Never bodies, headers, query strings or raw values |
+| Local hardening | Loopback-only listener. Host-header check against DNS rebinding. Browser `Origin` requests rejected. Upstreams are https-only and allowlisted, TLS is verified, and redirects are not followed |
+| `egressveil scan` | Run the detectors and policy over files or stdin. Prints locations and rule IDs, never values |
+| `egressveil doctor` | Checks Python, config, the listen port and whether the gateway is running, the audit location, the base-URL environment variables, and the active detectors |
+| `egressveil config validate` | A strict schema with secure defaults. Output never contains values |
+
+### Planned
+
+| Feature | Phase |
+| --- | --- |
+| OpenAI-compatible API parser (for Aider) | 2 |
+| PII and internal-hostname detectors | 2 |
+| `egressveil run -- <agent>` launcher that sets base URLs | 2 |
+| OpenClaw integration | 3 |
+| Cursor: documented, experimental support where technically possible | 3 |
+| Response-side inspection | 3 |
+
+The details are in [docs/roadmap.md](docs/roadmap.md).
+
+## Security architecture
+
+```mermaid
+flowchart TD
+    A[AI coding agent<br/>Claude Code] -->|"HTTP on 127.0.0.1<br/>ANTHROPIC_BASE_URL"| G
+
+    subgraph G[EgressVeil local gateway]
+        direction TB
+        H[Host / Origin / size checks] --> P[Anthropic parser<br/>every string field]
+        P --> D[Secret & token detectors]
+        D --> E[Policy engine]
+        E -->|REDACT| R[Redactor]
+        E -->|BLOCK or uninspectable| X[Local 400 error]
+        E -.-> L[(Audit log<br/>no raw values)]
+    end
+
+    R -->|verified TLS, allowlisted host| U[api.anthropic.com]
+    E -->|ALLOW / LOG_ONLY| U
+    U -->|streamed response| A
+
+    T[Other agent traffic:<br/>shell, web fetch, MCP, git] -. "NOT inspected" .-> I((Internet))
+```
+
+Each control, and whether it is implemented, is described in
+[docs/security-design.md](docs/security-design.md).
+
+## Installation
+
+EgressVeil requires Python 3.11 to 3.14 and runs on Windows, macOS and Linux.
+
+The recommended way to install it is with [pipx](https://pipx.pypa.io/),
+which puts the CLI in its own isolated environment:
+
+```bash
+pipx install "git+https://github.com/qmmughal/egressveil.git@v0.2.0"
+```
+
+Or with pip, into the virtual environment of your choice:
+
+```bash
+pip install "egressveil @ https://github.com/qmmughal/egressveil/releases/download/v0.2.0/egressveil-0.2.0-py3-none-any.whl"
+```
+
+Every release file on the [Releases page](https://github.com/qmmughal/egressveil/releases)
+is built by GitHub Actions and has signed build provenance. You can verify a
+download with:
+
+```bash
+gh attestation verify egressveil-0.2.0-py3-none-any.whl --repo qmmughal/egressveil
+```
+
+A PyPI package (`pip install egressveil`) is planned. See [docs/releasing.md](docs/releasing.md).
+
+To work on EgressVeil itself, install it from source:
+
+```bash
+git clone https://github.com/qmmughal/egressveil.git
+cd egressveil
+python -m venv .venv
+# Windows:      .venv\Scripts\activate
+# Linux/macOS:  source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+
+## Usage
+
+```console
+$ egressveil serve
+EgressVeil 0.2.0 gateway
+  listening   http://127.0.0.1:8787
+  upstream    https://api.anthropic.com
+  mode        strict
+  audit log   /home/you/.egressveil/audit.jsonl
+  note: not implemented yet, no effect: internal_hostnames, pii
+
+Point Claude Code at the gateway:
+  export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
+
+Press Ctrl+C to stop.
+```
+
+Scan files before you share them with an agent:
+
+```console
+$ egressveil scan .env deploy/notes.md
+.env:3:16: BLOCK    secrets/env_file_assignment
+deploy/notes.md:12:9: BLOCK    secrets/aws_access_key_id
+2 finding(s).
+```
+
+The exit status is 0 when nothing is found, 1 when there are findings, and
+2 when a file can't be read.
+
+Validate configuration, or check your environment:
+
+```bash
+egressveil config validate --config configs/egressveil.example.yaml
+egressveil doctor
+```
+
+Each audit event is one JSON line:
+
+```json
+{"ts":"2026-11-16T09:12:03.512+00:00","request_id":"ev_3c1f0a9e2b7d4c11","provider":"anthropic","method":"POST","path":"/v1/messages","outcome":"block","reason":"policy","route":"json_inspect","inspected":true,"bytes_in":48211,"findings":[{"detector":"secrets","rule_id":"aws_access_key_id","location":"messages[4].content[0].content[0].text","action":"BLOCK","digest":"9f2c4be01a7d33e8"}]}
+```
+
+Configuration is discovered in this order: `--config PATH`, then
+`$EGRESSVEIL_CONFIG`, then `./egressveil.yaml`, then the user config directory
+(`%APPDATA%\egressveil\` on Windows, `~/Library/Application Support/egressveil/`
+on macOS, `~/.config/egressveil/` on Linux), and finally the built-in defaults.
+All options are documented in
+[configs/egressveil.example.yaml](configs/egressveil.example.yaml).
+
+## Integration compatibility
+
+| Agent | Status | Routing mechanism | Coverage |
+| --- | --- | --- | --- |
+| **Claude Code** | **Available (pre-alpha)** | `ANTHROPIC_BASE_URL=http://127.0.0.1:8787` | Anthropic Messages API calls only. Not tool, shell, web or MCP traffic |
+| **Aider** | Partial: Anthropic models only | `ANTHROPIC_BASE_URL`. OpenAI-compatible models need Phase 2 | LLM API calls only |
+| **OpenClaw** | Future | To be determined | Not supported yet |
+| **Cursor** | Limited and experimental | Most model traffic goes through Cursor's own backend | Expected to be partial at best. See the docs |
+
+Routing details and their limitations are in [docs/integrations.md](docs/integrations.md).
+
+## Security limitations
+
+- Coverage is limited to API calls that a supported agent sends to the
+  gateway. An agent, plugin or tool that ignores the base-URL setting, or that
+  makes its own network calls, bypasses EgressVeil.
+- Detection is heuristic. Encoded, split or novel secrets can get through,
+  and false positives happen. PII and internal hostnames are **not** detected
+  yet.
+- Images and PDFs cannot be inspected. Strict mode blocks them unless you
+  set `gateway.allow_opaque_content: true`.
+- Model responses are not inspected.
+- The gateway connects directly to the upstream and does not use
+  `HTTPS_PROXY`.
+- EgressVeil does not perform TLS interception and does not install a root CA.
+- A local process running as your user can reconfigure or bypass EgressVeil.
+  It does not defend against malware on your machine.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+| Phase | Focus |
+| --- | --- |
+| 0, done | Repository, packaging, CI, config schema, CLI, doctor, threat model |
+| **1, current** | Anthropic gateway for Claude Code: streaming proxy, secret and token detectors, policy, redaction, audit, `scan` |
+| 2 | OpenAI-compatible parser for Aider, PII and hostname detectors, agent launcher |
+| 3 | OpenClaw, experimental Cursor support, policy packs, response inspection |
+
+See [docs/roadmap.md](docs/roadmap.md).
+
+## Contributing and support
+
+Contributions of any size are welcome, including detectors, false-positive
+reports, docs and integrations. Please read [CONTRIBUTING.md](CONTRIBUTING.md)
+and the [Code of Conduct](CODE_OF_CONDUCT.md). For questions, see
+[SUPPORT.md](SUPPORT.md). Never include real credentials in issues, tests or
+fixtures.
+
+## License
+
+EgressVeil is free software, released under the [MIT License](LICENSE).
+© 2026 EgressVeil contributors.