Skip to main content

airlock

PyPI version License: PolyForm Noncommercial 1.0.0 Python 3.12+ Typed

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?
  1. The agent sends {"tool": ..., "args": ...} to the gateway. Its name comes from its client certificate.
  2. The gateway normalises the arguments and asks the tools policy. Anything other than a clear yes means no call.
  3. The gateway writes the audit record. If the record cannot be written, the call is refused.
  4. 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.
  5. 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. See examples/terraform/docker/config/gateway.json.
  • The policies in policies/. tools/data.json says which agent may use which tool, hosts, models and limits; egress/data.json lists 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:

  1. Start the gateway with airlock serve --tools mytools.
  2. Give the tool to an agent in the policy data (policies/tools/data.json).
  3. 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 in main.tf.
  • After SIGHUP the 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)

Source distribution for tesseraline-airlock 0.0.1
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)

Table of built distributions (wheels) for tesseraline-airlock 0.0.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page