tesseraline-airlock
$ pip install tesseraline-airlock
Changelog · Security · Threat model · Design
An agent asks for an action. The gateway decides whether it happens and keeps the keys.
Why airlock
It works on a different layer. Content guardrails check what a model says. Airlock checks what an agent does: which tool it calls, with which arguments, where the request goes on the network and whose key it uses. The two work together. Airlock can sit behind an AI gateway or inside a service mesh.
The agent never holds a key. Keys for tools and for model APIs stay in the gateway, which adds them to each request. A key in the agent's environment could be read by any code the agent runs.
You can read all of it in an afternoon. The gateway is Python with one dependency (tesseraline-invariants, which has none of its own). The policies are OPA, and the example is Terraform. A security team can review the whole system before it goes live.
It runs on your machines. Nothing goes to an outside service, logs included. It works with a local model, so it suits data that must stay in house.
It needs no Kubernetes. Docker or one virtual machine is enough.
Its claims are tested. Each audit record carries the hash of the one before it, so a removed or altered record shows. When the policy engine or the audit log does not answer, the call is refused. CI checks on every change that the text leaving the gateway never contains a secret.
Airlock does not replace content filters or a service mesh. It is a small gateway for teams that want full control over what their agents do, on their own infrastructure, with code they can understand line by line.
How it works
agent ──mTLS──► gateway ──mTLS──► tools policy (OPA) first door: may this agent make this call?
│
├──mTLS──► secret store (Vault) keys stay here
└──mTLS──► egress proxy (Envoy) ──► OPA ──► second door: may this host be reached?
- The agent sends
{"tool": ..., "args": ...}to the gateway. Its name comes from its client certificate. - The gateway normalises the arguments and asks the tools policy. Anything other than a clear yes means no call.
- The gateway writes the audit record. If the record cannot be written, the call is refused.
- The tool runs inside the gateway. Requests to the internet go through the egress proxy, which asks its own policy about the host and checks the destination's certificate.
- The gateway removes every secret the call used from the result and returns it.
A model behind a provider's API works the same way through /v1/model/<route>/...: the gateway adds the API key
and passes the request and the answer through unchanged, streaming included.
Quick start
Requirements: Docker, Terraform or OpenTofu, uv, OpenSSL.
The example writes
certificates, two example secrets and the logs to run/, which git ignores. Its setup script gives each service
its own copy of the files it needs, owned by the user the service runs as, so it runs as root.
$ cd examples/terraform/docker
$ terraform init && terraform apply
Then call the gateway as the example agent:
$ P=../../../run/pki
$ A="--cert $P/agent.pem --key $P/agent-key.pem --cacert $P/ca.pem"
$ curl -s $A https://localhost:8443/healthz
$ curl -s $A https://localhost:8443/v1/call -H 'X-Airlock-Session: s-1' \
-d '{"tool": "fetch", "args": {"url": "https://demo-api:8443/items"}}'
$ curl -s $A https://localhost:8443/v1/call -d '{"tool": "fetch", "args": {"url": "https://github.com/"}}'
$ curl -s $A https://localhost:8443/v1/model/demo/v1/messages -d '{"model": "demo-1", "messages": []}'
The second call reaches demo-api, a small service in the stack that needs a token. The gateway adds the token from
Vault; demo-api echoes it back and the agent sees Bearer [redacted]. The third call is refused by the policy.
The fourth goes through the model route to a pretend model API.
Vault runs in dev mode and keeps its data in memory. After a restart of its container, load the example setup
again with docker exec airlock-vault sh /vault/extra/init.sh. terraform destroy removes the stack; run/ stays.
Certificates
Every file is PEM. The example's scripts/make-certs.sh creates a local CA and certificates valid for 30 days; run
it again to rotate them and send the gateway SIGHUP to load the new ones.
| File | Used by | Environment variable | Subject alternative name |
|---|---|---|---|
ca.pem |
every service, to check the other side | AIRLOCK_CA |
— |
gateway.pem, gateway-key.pem |
the gateway, as server and as client | AIRLOCK_CERT, AIRLOCK_KEY |
URI:spiffe://airlock/gateway, DNS:gateway |
agent.pem, agent-key.pem |
the agent | (the agent's own setting) | URI:spiffe://airlock/agent/<name> |
opa-tools.pem, -key.pem |
the tools policy engine | OPA's --tls-* flags |
DNS:opa-tools |
vault.pem, -key.pem |
Vault's TLS listener | vault/tls.hcl |
DNS:vault |
egress.pem, -key.pem |
the egress proxy | envoy/envoy.yaml |
DNS:egress |
upstream-ca.pem |
the egress proxy, to check destinations | envoy/envoy.yaml |
— (public CAs plus the example CA) |
The agent's name is the part after spiffe://airlock/agent/. A certificate with no such name, or with two, gets
403. A connection without a certificate from the CA is closed during the TLS handshake. In production, issue
these certificates from your own CA and keep them short-lived.
Configuration
The gateway reads its settings from the environment (airlock --help lists them) and two files:
AIRLOCK_CONFIG, a JSON file with the credentials the gateway adds per host and the model routes. Seeexamples/terraform/docker/config/gateway.json.- The policies in
policies/.tools/data.jsonsays which agent may use which tool, hosts, models and limits;egress/data.jsonlists the hosts and methods the proxy lets out. Both are plain JSON. A policy change needs no code change.
Your own tools
Tools run inside the gateway. There they can read the secret store and reach the egress proxy, which the agent cannot.
# mytools.py
from tesseraline_airlock import ToolContext, tool
from tesseraline_airlock.egress import normalise
@tool(description="Stock level for one product.")
def stock_level(args, context: ToolContext) -> str:
target = normalise(f"https://inventory.example/v1/stock/{args['sku']}")
reply = context.egress.fetch("GET", target, {"Authorization": f"Bearer {context.secret('inventory-api')}"})
return reply.body.decode()
To use it:
- Start the gateway with
airlock serve --tools mytools. - Give the tool to an agent in the policy data (
policies/tools/data.json). - Add an argument rule for it to the policy (
tools.rego). The policy refuses arguments it has no rule for.
context.secret reads from the secret store. The gateway removes that value from the tool's output before the
agent sees it.
Logs
The gateway writes three logs to AIRLOCK_LOG_DIR as JSON Lines. Each log is a Sink, a class with one method,
write(record), so you can send a log to another system by writing that class.
| File | For | If it cannot be written |
|---|---|---|
developer.jsonl |
debugging the gateway; never argument values | the gateway carries on |
audit.jsonl |
who called what, the decision and the reason; argument values only as hashes; each record carries the hash of the one before | the call is refused |
observability.jsonl |
timing, sizes, sessions, model and token counts; no content | the gateway carries on |
$ airlock obs summary # calls and refusals per tool, slowest calls, refusal reasons
$ airlock obs session s-1 # one session, step by step
$ airlock obs tail # new records as they arrive
$ airlock audit verify # check the audit log's hash chain
In the example: docker exec airlock-gateway airlock obs summary --log-dir /logs.
Security coverage (OWASP)
Airlock sits between an agent and its tools and model APIs. The conversation between a person and the agent's own application is outside it, so that application's web security stays with that application.
OWASP Top 10 (web applications, 2021), for the gateway itself
| Category | In airlock | |
|---|---|---|
| A01 | Broken Access Control | Covered. Identity from mutual TLS; the policy decides every call; no answer means no call. |
| A02 | Cryptographic Failures | Covered. TLS 1.2 or newer on every link; the egress proxy and its policy engine share a private network instead. |
| A03 | Injection | Covered for the gateway. URLs and route paths are normalised and checked; JSON is parsed strictly; secrets with line breaks are refused. Tools you write handle their own inputs. |
| A04 | Insecure Design | Covered. A threat model with a control for each threat. |
| A05 | Security Misconfiguration | Partly. Containers run without root, read-only, without kernel capabilities and with limits; nobody can change a policy over the API. The example runs Vault in dev mode with a local CA, which is for trying it out only. |
| A06 | Vulnerable and Outdated Components | Covered. Locked dependencies, two image scanners and a dependency audit in CI. |
| A07 | Identification and Authentication Failures | Partly. Certificates are short-lived and reloaded on SIGHUP. Automatic issuing and rotation come from your certificate system. |
| A08 | Software and Data Integrity Failures | Covered. Signed releases, tools in CI checked by hash, a hash-chained audit log. |
| A09 | Security Logging and Monitoring Failures | Partly. Every call is audited, and security events share one name (security) in the developer log. Alerts are set up in the system that receives the logs. |
| A10 | Server-Side Request Forgery | Partly. Requests leave only through the egress proxy to listed hosts, and a listed name that resolves to a private address is refused. The proxy resolves the name again, so a name that changes its address between the two lookups is not caught. |
OWASP Top 10 for LLM applications (2025)
| Category | In airlock | |
|---|---|---|
| LLM01 | Prompt Injection | Partly. Airlock does not detect injected text. It limits what a manipulated model can do: only the tools, arguments, hosts and models the policy allows. |
| LLM02 | Sensitive Information Disclosure | Partly. Secrets never reach the agent or the logs. Personal data is removed only if you plug in a Redactor. |
| LLM03 | Supply Chain | Covered for airlock's code and image. Where a model comes from is the model provider's part. |
| LLM04 | Data and Model Poisoning | Not in scope. Airlock does not train or change models. |
| LLM05 | Improper Output Handling | Covered. What the model asks to run is normalised and checked by the policy before it runs. |
| LLM06 | Excessive Agency | Covered. Each agent gets only the tools, arguments, hosts and models the policy names, within limits. |
| LLM07 | System Prompt Leakage | Not in scope. The prompt belongs to the agent; airlock keeps keys out of it by keeping them out of the agent. |
| LLM08 | Vector and Embedding Weaknesses | Not in scope. Airlock holds no vectors or embeddings. |
| LLM09 | Misinformation | Not in scope. Airlock does not judge what a model says. |
| LLM10 | Unbounded Consumption | Covered. Call limits per agent and tool, a token budget per agent and hour, a list of allowed models, size limits on requests and answers. |
Known limits
- Rate limits live in memory and reset when the gateway restarts. Several gateway instances count separately.
- The gateway handles each connection in its own thread, up to
AIRLOCK_MAX_CONNECTIONS(64) at once; further connections are closed. Set container limits as well, as the example does for every container inmain.tf. - After
SIGHUPthe gateway's own server trusts only the new CA. Its connections to the policy engine, Vault and the egress proxy keep trusting the old CA too until the gateway restarts. - The output scrubbing removes exact secret values. A tool that encodes a secret (base64, hashing) defeats it.
- Host names must be ASCII; write internationalised names in their
xn--form. - The egress proxy talks to its policy engine without TLS, on a network only those two share.
- A listed name that resolves to a private address is refused by the gateway. The egress proxy resolves the name again, so a name that changes its address between the two lookups is not caught. Keep the host list to names you trust.
The full list of threats and controls is in docs/threat-model.md.
Development
$ uv sync
$ uv run pytest
$ uv run ruff check . && uv run mypy src
$ uv run invariants check
$ opa test policies/tools policies/egress
License
PolyForm Noncommercial 1.0.0, with no permission to use the code to train AI models. For commercial use, contact Tesseraline.
Metadata
Release files for tesseraline-airlock 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tesseraline_airlock-0.0.1.tar.gz | 231.7 kB | With provenance | Details for tesseraline_airlock-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tesseraline_airlock-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for tesseraline_airlock-0.0.1-py3-none-any.whl |
Total release size: 268.9 kB
Release files / tesseraline_airlock-0.0.1.tar.gz
| Download URL | tesseraline_airlock-0.0.1.tar.gz |
|---|---|
| Size | 231.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1220661cc453cec900e48ccabb89de76ce6e934cffc1e191ff5ef51dbbc220c
|
|
BLAKE2b-256 checksum How to use checksums |
702ff36cd84825885cd58fc0cf65deaface6fdcc7d49dd41dbf658de58fa0d40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / tesseraline_airlock-0.0.1-py3-none-any.whl
| Download URL | tesseraline_airlock-0.0.1-py3-none-any.whl |
|---|---|
| Size | 37.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb35ba563baf5f924f82883dba696c251ba90862564a1b004833be966bcca801
|
|
BLAKE2b-256 checksum How to use checksums |
b7c05ff9356c768827d3e763fec0543e9e0fd3f12fa7ee4f6d2feb2dbe0b151f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for tesseraline-airlock 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tesseraline_airlock-0.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.