https://github.com/arpitcoder/aegrail-engine
The aegrail enforcement engine. Go sidecar + Helm chart for Kubernetes — HTTP forward proxy with per-agent allowlist, tamper-evident audit chain, and OWASP ASI02/ASI03 control mappings. Pairs with the aegrail Python library.
https://github.com/arpitcoder/aegrail-engine
Last synced: about 1 month ago
JSON representation
The aegrail enforcement engine. Go sidecar + Helm chart for Kubernetes — HTTP forward proxy with per-agent allowlist, tamper-evident audit chain, and OWASP ASI02/ASI03 control mappings. Pairs with the aegrail Python library.
- Host: GitHub
- URL: https://github.com/arpitcoder/aegrail-engine
- Owner: arpitcoder
- License: other
- Created: 2026-05-14T06:54:39.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-14T06:59:32.000Z (about 1 month ago)
- Last Synced: 2026-05-14T08:39:15.038Z (about 1 month ago)
- Language: Go
- Size: 14.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# aegrail-engine
[](LICENSE)
**The Kubernetes-deployable enforcement engine for `aegrail`.**
A Go sidecar that enforces aegrail's runtime contract for AI agents at
the network egress boundary — outside the agent process, in any
language. Pairs with the [`aegrail`](https://github.com/arpitcoder/aegrail)
Python library to provide defense-in-depth: the library enforces tool
ACLs in-process; the engine enforces egress + audit at the pod level.
---
## Why this exists
The `aegrail` Python library is application-level: it works for
Python agents that route their tool calls through `session.call_tool(...)`.
That covers the L7 capability boundary inside a Python process.
It does **not** cover:
- Agents written in other languages (TypeScript, Go, Rust, JVM)
- A Python developer who calls `requests.post(...)` directly,
bypassing the library
- Anything that ends up at a TCP socket regardless of what library
opened it
`aegrail-engine` closes that gap by being a **separate process** that
sits between the agent's container and the outside world. It enforces
egress policy at the network boundary, where it doesn't matter what
language the agent is written in or what library it used.
This is the same pattern Envoy uses for service-mesh policy and
[oauth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) uses for
HTTP auth — push the policy boundary out of the application, into a
sidecar where it's enforced once and language-agnostic.
---
## Status
**Pre-release. v0.1.0 is the first milestone (egress proxy MVP).**
This repo was created on 2026-05-14. Engineering is sequenced after
`aegrail` v0.2.4 ships its in-Python interceptors. See
[ARCHITECTURE.md](ARCHITECTURE.md) in the [`aegrail`](https://github.com/arpitcoder/aegrail/blob/main/ARCHITECTURE.md)
repo for how the engine fits into the broader project.
Track the v0.1.0 milestone for what's planned and current progress.
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────┐
│ Pod │
│ │
│ ┌────────────────────┐ HTTP_PROXY ┌───────────────────┐ │
│ │ Agent container │ ────────────────▶│ aegrail-engine │ │
│ │ - Python / Node / │ to localhost │ sidecar │ │
│ │ Go / etc. │ :8080 │ - Go binary │ │
│ │ - any aegrail SDK │ │ - allowlist │ │
│ │ or none │ │ - audit chain │ │
│ └────────────────────┘ │ - JSONL log │ │
│ ▲ └───────────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────────────────────────────────────┐ │
│ │ │ Network egress (allowed hosts only) │ │
│ │ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
**What it enforces** that the Python library can't:
- All outbound HTTP from the agent container, regardless of language
or library
- Allowlist policy applied at request time
- Audit chain (SHA-256, same format as the Python library's audit log)
- Denials recorded as `egress_denied` events with the requested
destination
**What it does NOT do:**
- Non-HTTP traffic (use NetworkPolicy / Cilium for L3/L4)
- In-process enforcement (use the `aegrail` Python library for that)
- Process / syscall isolation (use containers, gVisor, Firecracker)
See [ARCHITECTURE.md](https://github.com/arpitcoder/aegrail/blob/main/ARCHITECTURE.md)
in the aegrail repo for the layered defense-in-depth model.
---
## Quickstart (when v0.1.0 ships)
```bash
# Add the Helm repository
helm repo add aegrail https://arpitcoder.github.io/aegrail-engine
helm repo update
# Install with default allowlist (deny-by-default)
helm install aegrail-engine aegrail/aegrail-engine \
--set policy.allowlist[0]=api.openai.com \
--set policy.allowlist[1]=api.anthropic.com
```
Or for sidecar injection in an existing agent pod:
```yaml
apiVersion: v1
kind: Pod
metadata:
name: my-agent
annotations:
aegrail.io/inject: "true"
spec:
containers:
- name: agent
image: my-agent:latest
env:
- name: HTTP_PROXY
value: "http://localhost:8080"
- name: HTTPS_PROXY
value: "http://localhost:8080"
```
---
## Roadmap
- **v0.1.0** — HTTP forward proxy, allowlist policy from ConfigMap,
audit chain JSONL, Helm chart, single-pod sidecar deployment
- **v0.2.0** — gRPC policy sync from the agent's `Tool` registry
(no ConfigMap duplication)
- **v0.3.0** — mutating admission webhook for automatic sidecar
injection across the cluster
- **v0.4.0** — approval gates: irreversible actions pause on the
sidecar and require human confirmation before the request is
forwarded
- **v1.0** — hosted control plane integration; multi-tenant policy
management
The roadmap-discipline rules in
[`CLAUDE.md`](https://github.com/arpitcoder/aegrail/blob/main/CLAUDE.md)
of the aegrail repo govern when structural and feature work proceeds.
---
## Contributing
Contributions welcome via PR. See [CONTRIBUTING.md](CONTRIBUTING.md)
for the workflow. The contribution model mirrors the aegrail Python
repo: small reviewable PRs against `main`, tests required, Apache
2.0 license.
Security issues: please report privately per [SECURITY.md](SECURITY.md).
Do not open public issues for vulnerabilities.
---
## License
Apache License 2.0. See [LICENSE](LICENSE) for full terms.
Copyright © 2026 [Arpit Nigam](https://github.com/arpitcoder).