razorwire 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- razorwire-0.1.0/.gitignore +12 -0
- razorwire-0.1.0/LICENSE +21 -0
- razorwire-0.1.0/PKG-INFO +210 -0
- razorwire-0.1.0/README.md +188 -0
- razorwire-0.1.0/pyproject.toml +37 -0
- razorwire-0.1.0/src/razorwire/__init__.py +49 -0
- razorwire-0.1.0/src/razorwire/_urls.py +58 -0
- razorwire-0.1.0/src/razorwire/_version.py +1 -0
- razorwire-0.1.0/src/razorwire/admin.py +368 -0
- razorwire-0.1.0/src/razorwire/agent.py +101 -0
- razorwire-0.1.0/src/razorwire/executor.py +257 -0
- razorwire-0.1.0/src/razorwire/notes.py +178 -0
- razorwire-0.1.0/src/razorwire/proxy.py +300 -0
- razorwire-0.1.0/src/razorwire/py.typed +0 -0
- razorwire-0.1.0/src/razorwire/signing.py +108 -0
- razorwire-0.1.0/tests/conftest.py +203 -0
- razorwire-0.1.0/tests/policy.yaml +27 -0
- razorwire-0.1.0/tests/test_admin.py +253 -0
- razorwire-0.1.0/tests/test_agent.py +54 -0
- razorwire-0.1.0/tests/test_end_to_end.py +285 -0
- razorwire-0.1.0/tests/test_executor.py +142 -0
- razorwire-0.1.0/tests/test_notes.py +154 -0
- razorwire-0.1.0/tests/test_signing.py +63 -0
razorwire-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The Razorwire Authors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
razorwire-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: razorwire
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python SDK for Razorwire, the action firewall for AI agents
|
|
5
|
+
Project-URL: Repository, https://github.com/razorwire-dev/razorwire
|
|
6
|
+
Author: Razorwire
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: agents,ai,firewall,guardrails,llm,openai,security
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Security
|
|
14
|
+
Classifier: Typing :: Typed
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Provides-Extra: openai
|
|
17
|
+
Requires-Dist: openai>=1.40; extra == 'openai'
|
|
18
|
+
Provides-Extra: test
|
|
19
|
+
Requires-Dist: openai>=1.40; extra == 'test'
|
|
20
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Razorwire for Python
|
|
24
|
+
|
|
25
|
+
[Razorwire](https://github.com/razorwire-dev/razorwire) is an action firewall
|
|
26
|
+
for AI agents. It sits between an agent and its model provider and checks
|
|
27
|
+
every tool call against a policy before the agent can run it: allowed,
|
|
28
|
+
blocked, or held for a person to approve.
|
|
29
|
+
|
|
30
|
+
This package is the Python side of it. It needs only the standard library,
|
|
31
|
+
and works on Python 3.9 and later.
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
pip install razorwire
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
From a checkout of the repository: `pip install ./sdk/python`. The proxy
|
|
38
|
+
itself is a separate binary; see the main README to install it.
|
|
39
|
+
|
|
40
|
+
| You are writing | Use |
|
|
41
|
+
|---|---|
|
|
42
|
+
| An agent | `openai_client()`, `base_url()`, `blocked()` |
|
|
43
|
+
| An approval bot or dashboard | `Admin` |
|
|
44
|
+
| The service that carries out rollbacks and approved parked calls | `Executor` |
|
|
45
|
+
| Something that receives Razorwire's JSON alerts | `verify()` |
|
|
46
|
+
| Tests for your policy and your agent | `Proxy` |
|
|
47
|
+
|
|
48
|
+
## Point an agent at Razorwire
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
import razorwire
|
|
52
|
+
|
|
53
|
+
client = razorwire.openai_client() # an openai.OpenAI (pip install openai)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
It talks to `RAZORWIRE_URL` (default `http://127.0.0.1:8080`) with the
|
|
57
|
+
agent's key from `RAZORWIRE_AGENT_KEY`. Other frameworks take the base URL:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from langchain_openai import ChatOpenAI
|
|
61
|
+
|
|
62
|
+
llm = ChatOpenAI(model="gpt-4.1", base_url=razorwire.base_url(),
|
|
63
|
+
api_key=os.environ["RAZORWIRE_AGENT_KEY"])
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
A key is never sent over plain http to another machine; pass
|
|
67
|
+
`allow_plain_http=True` for a private network you trust.
|
|
68
|
+
|
|
69
|
+
## See what was blocked
|
|
70
|
+
|
|
71
|
+
A blocked call never reaches the agent. In its place, the assistant's text
|
|
72
|
+
gets a note saying which call was stopped and by which rule. `blocked()`
|
|
73
|
+
reads those notes:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
reply = client.chat.completions.create(model=..., messages=..., tools=...)
|
|
77
|
+
|
|
78
|
+
for block in razorwire.blocked(reply):
|
|
79
|
+
print(block.tool, block.rule, block.outcome, block.message)
|
|
80
|
+
# db_drop no-production-db-drop blocked Dropping the production database is blocked by policy.
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`outcome` is `blocked`, or for a call held for a person, `denied` (with
|
|
84
|
+
`by`), `expired`, or `parked`. A parked call may still be approved and
|
|
85
|
+
carried out later, so the agent must not retry it.
|
|
86
|
+
|
|
87
|
+
It takes a Chat Completions reply, a Responses API reply, a message, a
|
|
88
|
+
list of messages, or text gathered from a stream.
|
|
89
|
+
|
|
90
|
+
The notes are in the model's own text, so a model could write a fake one.
|
|
91
|
+
Use them to steer the agent, not as proof. The `x-razorwire-blocked`
|
|
92
|
+
header comes from the proxy alone, which drops any such header from the
|
|
93
|
+
provider; read it with `blocked_count()` on a raw response:
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
raw = client.chat.completions.with_raw_response.create(...)
|
|
97
|
+
razorwire.blocked_count(raw) # 1, or None when nothing was removed
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Approve held calls from Python
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from razorwire import Admin
|
|
104
|
+
|
|
105
|
+
admin = Admin() # RAZORWIRE_URL and RAZORWIRE_ADMIN_KEY
|
|
106
|
+
|
|
107
|
+
for call in admin.approvals().pending:
|
|
108
|
+
print(call.id, call.agent, call.tool, call.arguments, call.message)
|
|
109
|
+
|
|
110
|
+
admin.approve(call, reason="checked the order")
|
|
111
|
+
admin.deny(call, reason="wrong customer") # the reason is shown to the agent
|
|
112
|
+
|
|
113
|
+
held = admin.wait_for_held(tool="stripe_refund", timeout=60)
|
|
114
|
+
plan = admin.rollback(agent="support-bot", since="2h") # what would be undone
|
|
115
|
+
done = admin.rollback(agent="support-bot", since="2h", run=True)
|
|
116
|
+
admin.reload() # re-read policy and keys
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Refusals raise `RazorwireError`, with `status` and Razorwire's `code`
|
|
120
|
+
(`not_pending`, `no_executor`, `wrong_key_role`, ...). The admin key goes
|
|
121
|
+
only over https, or plain http to this machine, and redirects are never
|
|
122
|
+
followed, so the key cannot be sent anywhere else. `RAZORWIRE_CA_CERT`
|
|
123
|
+
trusts a self-signed certificate.
|
|
124
|
+
|
|
125
|
+
## Build an executor
|
|
126
|
+
|
|
127
|
+
Razorwire never touches your systems itself. To roll back what an agent
|
|
128
|
+
did, or to carry out a parked call approved after its agent stopped
|
|
129
|
+
waiting, it sends a signed job to your executor:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from razorwire import Executor
|
|
133
|
+
|
|
134
|
+
executor = Executor(log="executor.jsonl") # the key from EXECUTOR_KEY
|
|
135
|
+
|
|
136
|
+
@executor.action("close_ticket")
|
|
137
|
+
def close_ticket(job):
|
|
138
|
+
tickets.close(job.arguments["id"])
|
|
139
|
+
return {"closed": job.arguments["id"]}
|
|
140
|
+
|
|
141
|
+
@executor.action("stripe_refund")
|
|
142
|
+
def refund(job):
|
|
143
|
+
stripe.Refund.create(charge=job.arguments["charge"], amount=job.arguments["amount"])
|
|
144
|
+
return {"refunded": job.arguments["amount"]}
|
|
145
|
+
|
|
146
|
+
executor.serve(port=9100)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Start Razorwire with `EXECUTOR_URL=http://127.0.0.1:9100` and the same
|
|
150
|
+
`EXECUTOR_KEY` (`razorwire new-executor-key`). The executor checks every
|
|
151
|
+
job's signature and age, runs a job id at most once, and answers a retry
|
|
152
|
+
with the first result; with `log=`, that holds across restarts too. A job
|
|
153
|
+
that raises is reported as failed and can be tried again.
|
|
154
|
+
|
|
155
|
+
`job.kind` is `undo` or `call`, `job.by` is the admin who asked, and
|
|
156
|
+
`job.undoes` holds the call an undo reverses. To serve it from your own web
|
|
157
|
+
framework, pass the raw body and headers to `executor.handle()` and send
|
|
158
|
+
back the status and JSON it returns.
|
|
159
|
+
|
|
160
|
+
Keep the executor where agents cannot reach it: it holds the real
|
|
161
|
+
credentials.
|
|
162
|
+
|
|
163
|
+
## Check a signed alert
|
|
164
|
+
|
|
165
|
+
With `ALERT_KEY` set, Razorwire signs its JSON alerts:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from razorwire import verify, SignatureError
|
|
169
|
+
|
|
170
|
+
try:
|
|
171
|
+
verify(os.environ["ALERT_KEY"], raw_body, request.headers)
|
|
172
|
+
except SignatureError:
|
|
173
|
+
return 401
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Pass the body exactly as received, before parsing it.
|
|
177
|
+
|
|
178
|
+
## Test your policy
|
|
179
|
+
|
|
180
|
+
`Proxy` runs the real binary with your policy in a fresh folder, on a free
|
|
181
|
+
port, for as long as a test needs it:
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
from razorwire import Proxy, blocked
|
|
185
|
+
|
|
186
|
+
def test_production_is_safe():
|
|
187
|
+
with Proxy(policy="policy.yaml", upstream="https://api.groq.com/openai",
|
|
188
|
+
upstream_key=os.environ["GROQ_API_KEY"]) as proxy:
|
|
189
|
+
client = proxy.openai_client(agent="ops-bot")
|
|
190
|
+
reply = client.chat.completions.create(model=..., messages=..., tools=...)
|
|
191
|
+
assert [b.rule for b in blocked(reply)] == ["no-production-db-drop"]
|
|
192
|
+
assert any(e.get("blocked") for e in proxy.audit())
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
It finds the binary from `binary=`, `RAZORWIRE_BIN` or `PATH`, ignores
|
|
196
|
+
Razorwire settings in your environment, makes an admin key (`proxy.admin`)
|
|
197
|
+
and agent keys for the names in `agents=`, and signs its audit log.
|
|
198
|
+
|
|
199
|
+
## Settings
|
|
200
|
+
|
|
201
|
+
| Variable | Used by | Meaning |
|
|
202
|
+
|---|---|---|
|
|
203
|
+
| `RAZORWIRE_URL` | agents, `Admin` | The proxy. Default `http://127.0.0.1:8080` |
|
|
204
|
+
| `RAZORWIRE_AGENT_KEY` | `openai_client()` | The agent's `rw_` key |
|
|
205
|
+
| `RAZORWIRE_ADMIN_KEY` | `Admin` | An admin's `rw_` key |
|
|
206
|
+
| `RAZORWIRE_CA_CERT` | `Admin` | A PEM certificate to trust as well |
|
|
207
|
+
| `EXECUTOR_KEY` | `Executor` | Hex key shared with the proxy |
|
|
208
|
+
| `RAZORWIRE_BIN` | `Proxy` | The razorwire binary |
|
|
209
|
+
|
|
210
|
+
MIT licensed.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# Razorwire for Python
|
|
2
|
+
|
|
3
|
+
[Razorwire](https://github.com/razorwire-dev/razorwire) is an action firewall
|
|
4
|
+
for AI agents. It sits between an agent and its model provider and checks
|
|
5
|
+
every tool call against a policy before the agent can run it: allowed,
|
|
6
|
+
blocked, or held for a person to approve.
|
|
7
|
+
|
|
8
|
+
This package is the Python side of it. It needs only the standard library,
|
|
9
|
+
and works on Python 3.9 and later.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
pip install razorwire
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
From a checkout of the repository: `pip install ./sdk/python`. The proxy
|
|
16
|
+
itself is a separate binary; see the main README to install it.
|
|
17
|
+
|
|
18
|
+
| You are writing | Use |
|
|
19
|
+
|---|---|
|
|
20
|
+
| An agent | `openai_client()`, `base_url()`, `blocked()` |
|
|
21
|
+
| An approval bot or dashboard | `Admin` |
|
|
22
|
+
| The service that carries out rollbacks and approved parked calls | `Executor` |
|
|
23
|
+
| Something that receives Razorwire's JSON alerts | `verify()` |
|
|
24
|
+
| Tests for your policy and your agent | `Proxy` |
|
|
25
|
+
|
|
26
|
+
## Point an agent at Razorwire
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
import razorwire
|
|
30
|
+
|
|
31
|
+
client = razorwire.openai_client() # an openai.OpenAI (pip install openai)
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
It talks to `RAZORWIRE_URL` (default `http://127.0.0.1:8080`) with the
|
|
35
|
+
agent's key from `RAZORWIRE_AGENT_KEY`. Other frameworks take the base URL:
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
from langchain_openai import ChatOpenAI
|
|
39
|
+
|
|
40
|
+
llm = ChatOpenAI(model="gpt-4.1", base_url=razorwire.base_url(),
|
|
41
|
+
api_key=os.environ["RAZORWIRE_AGENT_KEY"])
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
A key is never sent over plain http to another machine; pass
|
|
45
|
+
`allow_plain_http=True` for a private network you trust.
|
|
46
|
+
|
|
47
|
+
## See what was blocked
|
|
48
|
+
|
|
49
|
+
A blocked call never reaches the agent. In its place, the assistant's text
|
|
50
|
+
gets a note saying which call was stopped and by which rule. `blocked()`
|
|
51
|
+
reads those notes:
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
reply = client.chat.completions.create(model=..., messages=..., tools=...)
|
|
55
|
+
|
|
56
|
+
for block in razorwire.blocked(reply):
|
|
57
|
+
print(block.tool, block.rule, block.outcome, block.message)
|
|
58
|
+
# db_drop no-production-db-drop blocked Dropping the production database is blocked by policy.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`outcome` is `blocked`, or for a call held for a person, `denied` (with
|
|
62
|
+
`by`), `expired`, or `parked`. A parked call may still be approved and
|
|
63
|
+
carried out later, so the agent must not retry it.
|
|
64
|
+
|
|
65
|
+
It takes a Chat Completions reply, a Responses API reply, a message, a
|
|
66
|
+
list of messages, or text gathered from a stream.
|
|
67
|
+
|
|
68
|
+
The notes are in the model's own text, so a model could write a fake one.
|
|
69
|
+
Use them to steer the agent, not as proof. The `x-razorwire-blocked`
|
|
70
|
+
header comes from the proxy alone, which drops any such header from the
|
|
71
|
+
provider; read it with `blocked_count()` on a raw response:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
raw = client.chat.completions.with_raw_response.create(...)
|
|
75
|
+
razorwire.blocked_count(raw) # 1, or None when nothing was removed
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Approve held calls from Python
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
from razorwire import Admin
|
|
82
|
+
|
|
83
|
+
admin = Admin() # RAZORWIRE_URL and RAZORWIRE_ADMIN_KEY
|
|
84
|
+
|
|
85
|
+
for call in admin.approvals().pending:
|
|
86
|
+
print(call.id, call.agent, call.tool, call.arguments, call.message)
|
|
87
|
+
|
|
88
|
+
admin.approve(call, reason="checked the order")
|
|
89
|
+
admin.deny(call, reason="wrong customer") # the reason is shown to the agent
|
|
90
|
+
|
|
91
|
+
held = admin.wait_for_held(tool="stripe_refund", timeout=60)
|
|
92
|
+
plan = admin.rollback(agent="support-bot", since="2h") # what would be undone
|
|
93
|
+
done = admin.rollback(agent="support-bot", since="2h", run=True)
|
|
94
|
+
admin.reload() # re-read policy and keys
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Refusals raise `RazorwireError`, with `status` and Razorwire's `code`
|
|
98
|
+
(`not_pending`, `no_executor`, `wrong_key_role`, ...). The admin key goes
|
|
99
|
+
only over https, or plain http to this machine, and redirects are never
|
|
100
|
+
followed, so the key cannot be sent anywhere else. `RAZORWIRE_CA_CERT`
|
|
101
|
+
trusts a self-signed certificate.
|
|
102
|
+
|
|
103
|
+
## Build an executor
|
|
104
|
+
|
|
105
|
+
Razorwire never touches your systems itself. To roll back what an agent
|
|
106
|
+
did, or to carry out a parked call approved after its agent stopped
|
|
107
|
+
waiting, it sends a signed job to your executor:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from razorwire import Executor
|
|
111
|
+
|
|
112
|
+
executor = Executor(log="executor.jsonl") # the key from EXECUTOR_KEY
|
|
113
|
+
|
|
114
|
+
@executor.action("close_ticket")
|
|
115
|
+
def close_ticket(job):
|
|
116
|
+
tickets.close(job.arguments["id"])
|
|
117
|
+
return {"closed": job.arguments["id"]}
|
|
118
|
+
|
|
119
|
+
@executor.action("stripe_refund")
|
|
120
|
+
def refund(job):
|
|
121
|
+
stripe.Refund.create(charge=job.arguments["charge"], amount=job.arguments["amount"])
|
|
122
|
+
return {"refunded": job.arguments["amount"]}
|
|
123
|
+
|
|
124
|
+
executor.serve(port=9100)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Start Razorwire with `EXECUTOR_URL=http://127.0.0.1:9100` and the same
|
|
128
|
+
`EXECUTOR_KEY` (`razorwire new-executor-key`). The executor checks every
|
|
129
|
+
job's signature and age, runs a job id at most once, and answers a retry
|
|
130
|
+
with the first result; with `log=`, that holds across restarts too. A job
|
|
131
|
+
that raises is reported as failed and can be tried again.
|
|
132
|
+
|
|
133
|
+
`job.kind` is `undo` or `call`, `job.by` is the admin who asked, and
|
|
134
|
+
`job.undoes` holds the call an undo reverses. To serve it from your own web
|
|
135
|
+
framework, pass the raw body and headers to `executor.handle()` and send
|
|
136
|
+
back the status and JSON it returns.
|
|
137
|
+
|
|
138
|
+
Keep the executor where agents cannot reach it: it holds the real
|
|
139
|
+
credentials.
|
|
140
|
+
|
|
141
|
+
## Check a signed alert
|
|
142
|
+
|
|
143
|
+
With `ALERT_KEY` set, Razorwire signs its JSON alerts:
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
from razorwire import verify, SignatureError
|
|
147
|
+
|
|
148
|
+
try:
|
|
149
|
+
verify(os.environ["ALERT_KEY"], raw_body, request.headers)
|
|
150
|
+
except SignatureError:
|
|
151
|
+
return 401
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Pass the body exactly as received, before parsing it.
|
|
155
|
+
|
|
156
|
+
## Test your policy
|
|
157
|
+
|
|
158
|
+
`Proxy` runs the real binary with your policy in a fresh folder, on a free
|
|
159
|
+
port, for as long as a test needs it:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from razorwire import Proxy, blocked
|
|
163
|
+
|
|
164
|
+
def test_production_is_safe():
|
|
165
|
+
with Proxy(policy="policy.yaml", upstream="https://api.groq.com/openai",
|
|
166
|
+
upstream_key=os.environ["GROQ_API_KEY"]) as proxy:
|
|
167
|
+
client = proxy.openai_client(agent="ops-bot")
|
|
168
|
+
reply = client.chat.completions.create(model=..., messages=..., tools=...)
|
|
169
|
+
assert [b.rule for b in blocked(reply)] == ["no-production-db-drop"]
|
|
170
|
+
assert any(e.get("blocked") for e in proxy.audit())
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
It finds the binary from `binary=`, `RAZORWIRE_BIN` or `PATH`, ignores
|
|
174
|
+
Razorwire settings in your environment, makes an admin key (`proxy.admin`)
|
|
175
|
+
and agent keys for the names in `agents=`, and signs its audit log.
|
|
176
|
+
|
|
177
|
+
## Settings
|
|
178
|
+
|
|
179
|
+
| Variable | Used by | Meaning |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| `RAZORWIRE_URL` | agents, `Admin` | The proxy. Default `http://127.0.0.1:8080` |
|
|
182
|
+
| `RAZORWIRE_AGENT_KEY` | `openai_client()` | The agent's `rw_` key |
|
|
183
|
+
| `RAZORWIRE_ADMIN_KEY` | `Admin` | An admin's `rw_` key |
|
|
184
|
+
| `RAZORWIRE_CA_CERT` | `Admin` | A PEM certificate to trust as well |
|
|
185
|
+
| `EXECUTOR_KEY` | `Executor` | Hex key shared with the proxy |
|
|
186
|
+
| `RAZORWIRE_BIN` | `Proxy` | The razorwire binary |
|
|
187
|
+
|
|
188
|
+
MIT licensed.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.21"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "razorwire"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Python SDK for Razorwire, the action firewall for AI agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.9"
|
|
12
|
+
authors = [{ name = "Razorwire" }]
|
|
13
|
+
keywords = ["ai", "agents", "llm", "security", "guardrails", "openai", "firewall"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Topic :: Security",
|
|
19
|
+
"Typing :: Typed",
|
|
20
|
+
]
|
|
21
|
+
# The SDK itself needs nothing beyond the standard library. `openai` is only
|
|
22
|
+
# imported by openai_client() and async_openai_client().
|
|
23
|
+
dependencies = []
|
|
24
|
+
|
|
25
|
+
[project.optional-dependencies]
|
|
26
|
+
openai = ["openai>=1.40"]
|
|
27
|
+
test = ["pytest>=8", "openai>=1.40"]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Repository = "https://github.com/razorwire-dev/razorwire"
|
|
31
|
+
|
|
32
|
+
[tool.hatch.build.targets.wheel]
|
|
33
|
+
packages = ["src/razorwire"]
|
|
34
|
+
|
|
35
|
+
[tool.pytest.ini_options]
|
|
36
|
+
pythonpath = ["src"]
|
|
37
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Razorwire for Python.
|
|
2
|
+
|
|
3
|
+
Razorwire is a proxy between an AI agent and its model provider that checks
|
|
4
|
+
every tool call against a policy before the agent can run it. This package
|
|
5
|
+
helps on both sides of it:
|
|
6
|
+
|
|
7
|
+
- Agents: `openai_client()`, `base_url()`, and `blocked()` to see which
|
|
8
|
+
calls were stopped and why.
|
|
9
|
+
- Admins: `Admin`, for held calls, approvals, reloads and rollbacks.
|
|
10
|
+
- Executor: `Executor`, the service that carries out rollbacks and approved
|
|
11
|
+
parked calls, with signatures and retries handled.
|
|
12
|
+
- Alerts: `verify()`, to check a signed JSON alert.
|
|
13
|
+
- Tests: `Proxy`, to run Razorwire with a policy inside a test.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from ._version import __version__
|
|
17
|
+
from .admin import Admin, Approvals, Decision, HeldCall, RazorwireError, Rollback, RollbackStep
|
|
18
|
+
from .agent import async_openai_client, base_url, openai_client
|
|
19
|
+
from .executor import Executor, Job
|
|
20
|
+
from .notes import BLOCKED_HEADER, NOTE_PREFIX, Block, blocked, blocked_count
|
|
21
|
+
from .proxy import Proxy
|
|
22
|
+
from .signing import SIGNATURE_HEADER, TIMESTAMP_HEADER, SignatureError, sign, verify
|
|
23
|
+
|
|
24
|
+
__all__ = [
|
|
25
|
+
"__version__",
|
|
26
|
+
"Admin",
|
|
27
|
+
"Approvals",
|
|
28
|
+
"BLOCKED_HEADER",
|
|
29
|
+
"Block",
|
|
30
|
+
"Decision",
|
|
31
|
+
"Executor",
|
|
32
|
+
"HeldCall",
|
|
33
|
+
"Job",
|
|
34
|
+
"NOTE_PREFIX",
|
|
35
|
+
"Proxy",
|
|
36
|
+
"RazorwireError",
|
|
37
|
+
"Rollback",
|
|
38
|
+
"RollbackStep",
|
|
39
|
+
"SIGNATURE_HEADER",
|
|
40
|
+
"SignatureError",
|
|
41
|
+
"TIMESTAMP_HEADER",
|
|
42
|
+
"async_openai_client",
|
|
43
|
+
"base_url",
|
|
44
|
+
"blocked",
|
|
45
|
+
"blocked_count",
|
|
46
|
+
"openai_client",
|
|
47
|
+
"sign",
|
|
48
|
+
"verify",
|
|
49
|
+
]
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Where the proxy is, and whether a key may be sent there."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ipaddress
|
|
6
|
+
import os
|
|
7
|
+
from typing import Optional
|
|
8
|
+
from urllib.parse import urlsplit
|
|
9
|
+
|
|
10
|
+
DEFAULT_URL = "http://127.0.0.1:8080"
|
|
11
|
+
KEY_PREFIX = "rw_"
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def is_loopback_host(host: Optional[str]) -> bool:
|
|
15
|
+
"""True for localhost and loopback addresses, the same test the proxy uses."""
|
|
16
|
+
if not host:
|
|
17
|
+
return False
|
|
18
|
+
host = host.strip("[]")
|
|
19
|
+
if host.lower() == "localhost":
|
|
20
|
+
return True
|
|
21
|
+
try:
|
|
22
|
+
return ipaddress.ip_address(host).is_loopback
|
|
23
|
+
except ValueError:
|
|
24
|
+
return False
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def proxy_url(url: Optional[str] = None) -> str:
|
|
28
|
+
"""The proxy's address: `url`, else RAZORWIRE_URL, else http://127.0.0.1:8080."""
|
|
29
|
+
value = url if url is not None else os.environ.get("RAZORWIRE_URL", "")
|
|
30
|
+
return (value.strip() or DEFAULT_URL).rstrip("/")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def check_url(url: str, setting: str, allow_plain_http: bool = False) -> None:
|
|
34
|
+
"""Refuse an address a key should not be sent to.
|
|
35
|
+
|
|
36
|
+
Plain http is only allowed to this machine, unless `allow_plain_http`,
|
|
37
|
+
because the key in each request could otherwise be read on the network.
|
|
38
|
+
The URL is never repeated in the error, in case it carries a secret.
|
|
39
|
+
"""
|
|
40
|
+
parts = urlsplit(url)
|
|
41
|
+
if parts.scheme not in ("http", "https") or not parts.hostname:
|
|
42
|
+
raise ValueError(f"{setting} is not an http or https URL")
|
|
43
|
+
if parts.username is not None or parts.password is not None:
|
|
44
|
+
raise ValueError(f"{setting} must not carry a user name or password")
|
|
45
|
+
if parts.scheme == "http" and not allow_plain_http and not is_loopback_host(parts.hostname):
|
|
46
|
+
raise ValueError(
|
|
47
|
+
f"{setting} must use https unless it points at this machine, or the key would cross the network unencrypted"
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def shown_url(url: str) -> str:
|
|
52
|
+
"""Scheme, host and port only, for messages."""
|
|
53
|
+
parts = urlsplit(url)
|
|
54
|
+
host = parts.hostname or "?"
|
|
55
|
+
if ":" in host:
|
|
56
|
+
host = f"[{host}]"
|
|
57
|
+
port = f":{parts.port}" if parts.port else ""
|
|
58
|
+
return f"{parts.scheme}://{host}{port}"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|