capsule-strands 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.
- capsule_strands-0.1.0/.gitignore +290 -0
- capsule_strands-0.1.0/LICENSE +32 -0
- capsule_strands-0.1.0/PKG-INFO +124 -0
- capsule_strands-0.1.0/README.md +75 -0
- capsule_strands-0.1.0/pyproject.toml +36 -0
- capsule_strands-0.1.0/src/capsule_strands/__init__.py +9 -0
- capsule_strands-0.1.0/src/capsule_strands/config.py +65 -0
- capsule_strands-0.1.0/src/capsule_strands/plugin.py +253 -0
- capsule_strands-0.1.0/src/capsule_strands/transport.py +50 -0
- capsule_strands-0.1.0/tests/conftest.py +114 -0
- capsule_strands-0.1.0/tests/requirements.txt +1 -0
- capsule_strands-0.1.0/tests/test_plugin.py +241 -0
- capsule_strands-0.1.0/uv.lock +1499 -0
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
# Local Docker data
|
|
2
|
+
.docker/
|
|
3
|
+
|
|
4
|
+
# Local-only dead-reference checker, not a maintained repo config
|
|
5
|
+
/knip.config.ts
|
|
6
|
+
|
|
7
|
+
# playwright-cli local session data (auth state, screenshots, logs)
|
|
8
|
+
.playwright-cli/
|
|
9
|
+
|
|
10
|
+
# Byte-compiled / optimized / DLL files
|
|
11
|
+
__pycache__/
|
|
12
|
+
*.py[cod]
|
|
13
|
+
*$py.class
|
|
14
|
+
|
|
15
|
+
# C extensions
|
|
16
|
+
*.so
|
|
17
|
+
|
|
18
|
+
# Distribution / packaging
|
|
19
|
+
.Python
|
|
20
|
+
build/
|
|
21
|
+
develop-eggs/
|
|
22
|
+
dist/
|
|
23
|
+
downloads/
|
|
24
|
+
eggs/
|
|
25
|
+
.eggs/
|
|
26
|
+
lib/
|
|
27
|
+
!apps/portal/src/lib/
|
|
28
|
+
!apps/backoffice-ui/src/lib/
|
|
29
|
+
!libs/ui/src/lib/
|
|
30
|
+
# Paraglide-js output — auto-generated; never track (compiler rewrites .gitignore comment URL per version)
|
|
31
|
+
apps/portal/src/lib/i18n/
|
|
32
|
+
lib64/
|
|
33
|
+
parts/
|
|
34
|
+
sdist/
|
|
35
|
+
var/
|
|
36
|
+
wheels/
|
|
37
|
+
share/python-wheels/
|
|
38
|
+
*.egg-info/
|
|
39
|
+
.installed.cfg
|
|
40
|
+
*.egg
|
|
41
|
+
MANIFEST
|
|
42
|
+
|
|
43
|
+
# PyInstaller
|
|
44
|
+
# Usually these files are written by a python script from a template
|
|
45
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
46
|
+
*.manifest
|
|
47
|
+
*.spec
|
|
48
|
+
|
|
49
|
+
# Installer logs
|
|
50
|
+
pip-log.txt
|
|
51
|
+
pip-delete-this-directory.txt
|
|
52
|
+
|
|
53
|
+
# Unit test / coverage reports
|
|
54
|
+
htmlcov/
|
|
55
|
+
.tox/
|
|
56
|
+
.nox/
|
|
57
|
+
.coverage
|
|
58
|
+
.coverage.*
|
|
59
|
+
.cache
|
|
60
|
+
nosetests.xml
|
|
61
|
+
coverage.xml
|
|
62
|
+
*.cover
|
|
63
|
+
*.py,cover
|
|
64
|
+
.hypothesis/
|
|
65
|
+
.pytest_cache/
|
|
66
|
+
cover/
|
|
67
|
+
|
|
68
|
+
# Translations
|
|
69
|
+
*.mo
|
|
70
|
+
*.pot
|
|
71
|
+
|
|
72
|
+
# Django stuff:
|
|
73
|
+
*.log
|
|
74
|
+
local_settings.py
|
|
75
|
+
db.sqlite3
|
|
76
|
+
db.sqlite3-journal
|
|
77
|
+
|
|
78
|
+
# Flask stuff:
|
|
79
|
+
instance/
|
|
80
|
+
.webassets-cache
|
|
81
|
+
|
|
82
|
+
# Scrapy stuff:
|
|
83
|
+
.scrapy
|
|
84
|
+
|
|
85
|
+
# Sphinx documentation
|
|
86
|
+
docs/_build/
|
|
87
|
+
|
|
88
|
+
# PyBuilder
|
|
89
|
+
.pybuilder/
|
|
90
|
+
target/
|
|
91
|
+
|
|
92
|
+
# Jupyter Notebook
|
|
93
|
+
.ipynb_checkpoints
|
|
94
|
+
|
|
95
|
+
# IPython
|
|
96
|
+
profile_default/
|
|
97
|
+
ipython_config.py
|
|
98
|
+
|
|
99
|
+
# pyenv
|
|
100
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
101
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
102
|
+
# .python-version
|
|
103
|
+
|
|
104
|
+
# pipenv
|
|
105
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
106
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
107
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
108
|
+
# install all needed dependencies.
|
|
109
|
+
#Pipfile.lock
|
|
110
|
+
|
|
111
|
+
# poetry
|
|
112
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
113
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
114
|
+
# commonly ignored for libraries.
|
|
115
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
116
|
+
#poetry.lock
|
|
117
|
+
|
|
118
|
+
# pdm
|
|
119
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
120
|
+
#pdm.lock
|
|
121
|
+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
|
|
122
|
+
# in version control.
|
|
123
|
+
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
|
|
124
|
+
.pdm.toml
|
|
125
|
+
.pdm-python
|
|
126
|
+
.pdm-build/
|
|
127
|
+
|
|
128
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
129
|
+
__pypackages__/
|
|
130
|
+
|
|
131
|
+
# Celery stuff
|
|
132
|
+
celerybeat-schedule
|
|
133
|
+
celerybeat.pid
|
|
134
|
+
|
|
135
|
+
# SageMath parsed files
|
|
136
|
+
*.sage.py
|
|
137
|
+
|
|
138
|
+
# Environments
|
|
139
|
+
.env
|
|
140
|
+
.venv
|
|
141
|
+
env/
|
|
142
|
+
venv/
|
|
143
|
+
ENV/
|
|
144
|
+
env.bak/
|
|
145
|
+
venv.bak/
|
|
146
|
+
|
|
147
|
+
# Spyder project settings
|
|
148
|
+
.spyderproject
|
|
149
|
+
.spyproject
|
|
150
|
+
|
|
151
|
+
# Rope project settings
|
|
152
|
+
.ropeproject
|
|
153
|
+
|
|
154
|
+
# mkdocs documentation
|
|
155
|
+
/site
|
|
156
|
+
|
|
157
|
+
# mypy
|
|
158
|
+
.mypy_cache/
|
|
159
|
+
.dmypy.json
|
|
160
|
+
dmypy.json
|
|
161
|
+
|
|
162
|
+
# Pyre type checker
|
|
163
|
+
.pyre/
|
|
164
|
+
|
|
165
|
+
# pytype static type analyzer
|
|
166
|
+
.pytype/
|
|
167
|
+
|
|
168
|
+
# Cython debug symbols
|
|
169
|
+
cython_debug/
|
|
170
|
+
|
|
171
|
+
# PyCharm
|
|
172
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
173
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
174
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
175
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
176
|
+
.idea/
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
# dependencies
|
|
181
|
+
/node_modules
|
|
182
|
+
/.pnpm-store
|
|
183
|
+
|
|
184
|
+
# testing
|
|
185
|
+
/coverage
|
|
186
|
+
|
|
187
|
+
# production
|
|
188
|
+
/build
|
|
189
|
+
|
|
190
|
+
# misc
|
|
191
|
+
.DS_Store
|
|
192
|
+
.env.local
|
|
193
|
+
.env.development.local
|
|
194
|
+
.env.test.local
|
|
195
|
+
.env.production.local
|
|
196
|
+
|
|
197
|
+
npm-debug.log*
|
|
198
|
+
yarn-debug.log*
|
|
199
|
+
yarn-error.log*
|
|
200
|
+
|
|
201
|
+
.nx/cache
|
|
202
|
+
.nx/workspace-data
|
|
203
|
+
vite.config.*.timestamp*
|
|
204
|
+
vitest.config.*.timestamp*
|
|
205
|
+
test-output
|
|
206
|
+
|
|
207
|
+
# Ignore cursor IDE files, except shared agent rules
|
|
208
|
+
.cursor/*
|
|
209
|
+
!.cursor/rules/
|
|
210
|
+
|
|
211
|
+
# Codex temporary files
|
|
212
|
+
.codex_tmp/
|
|
213
|
+
|
|
214
|
+
# TypeScript cache
|
|
215
|
+
*.tsbuildinfo
|
|
216
|
+
out-tsc/
|
|
217
|
+
|
|
218
|
+
.vscode/settings.json
|
|
219
|
+
.vscode/mcp.json
|
|
220
|
+
|
|
221
|
+
.github/instructions/*.instructions.md
|
|
222
|
+
instructions.txt
|
|
223
|
+
node_modules
|
|
224
|
+
|
|
225
|
+
# Figma temporary assets
|
|
226
|
+
figma-assets/
|
|
227
|
+
tmp-figma-assets/
|
|
228
|
+
apps/portal/logs
|
|
229
|
+
logs
|
|
230
|
+
|
|
231
|
+
# CDN assets (synced from GCS for local development)
|
|
232
|
+
cdn/
|
|
233
|
+
|
|
234
|
+
# Private assets / files for local development, not meant to be shared
|
|
235
|
+
.local/
|
|
236
|
+
|
|
237
|
+
# Claude Code (machine-specific)
|
|
238
|
+
.claude/teams/*/inboxes/
|
|
239
|
+
.claude/settings.local.json
|
|
240
|
+
CLAUDE.local.md
|
|
241
|
+
.worktrees/
|
|
242
|
+
|
|
243
|
+
# Pinned protoc binary cache
|
|
244
|
+
.protoc/
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
.claude/scheduled_tasks.lock
|
|
248
|
+
.claude/tmp/
|
|
249
|
+
.claude/worktrees/
|
|
250
|
+
.claude/plans/
|
|
251
|
+
# Test artifacts
|
|
252
|
+
screenshots/
|
|
253
|
+
libs/graph/src/**/__screenshots__/
|
|
254
|
+
!libs/graph/src/components/__tests__/__screenshots__/
|
|
255
|
+
libs/ui/src/**/__screenshots__/
|
|
256
|
+
.playwright-mcp/
|
|
257
|
+
|
|
258
|
+
# Designer prototypes / scratch docs (kept local, not tracked)
|
|
259
|
+
/notification-empty-state.html
|
|
260
|
+
/notification-channels-empty-state.html
|
|
261
|
+
/notification-popover-prototype.html
|
|
262
|
+
/capsule-qr.html
|
|
263
|
+
/policy-violations-empty-states.html
|
|
264
|
+
/figma-prompt-notification-states.md
|
|
265
|
+
/discovery-node-edge-audit.md
|
|
266
|
+
|
|
267
|
+
# UI lib test CSS — built fresh by libs/ui `npm run build:test-css` before each vitest run
|
|
268
|
+
libs/ui/playwright/output.css
|
|
269
|
+
libs/graph/storybook-static
|
|
270
|
+
|
|
271
|
+
# Codex
|
|
272
|
+
.agents/
|
|
273
|
+
.codex/
|
|
274
|
+
AGENTS.md
|
|
275
|
+
.claude/worktrees
|
|
276
|
+
.nx/polygraph
|
|
277
|
+
.nx/self-healing
|
|
278
|
+
auth.json
|
|
279
|
+
.playwright-cli/
|
|
280
|
+
.claude/workflows/
|
|
281
|
+
apps/portal/tests/integration/auth.json
|
|
282
|
+
apps/portal/tests/integration/auth.json.auth0.bak
|
|
283
|
+
|
|
284
|
+
# direnv
|
|
285
|
+
.envrc
|
|
286
|
+
|
|
287
|
+
.eslintcache
|
|
288
|
+
|
|
289
|
+
# Vendor API specs and other local-only reference material, linked from integration READMEs
|
|
290
|
+
working-docs/
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
Capsule Security Commercial License
|
|
2
|
+
|
|
3
|
+
Copyright (c) Capsule Security, Inc. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This software is licensed, not sold, and is made available solely to customers
|
|
6
|
+
of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
|
|
7
|
+
agreement (the "Subscription Agreement") between the customer and Capsule.
|
|
8
|
+
|
|
9
|
+
Subject to the Subscription Agreement, Capsule grants the customer a
|
|
10
|
+
non-exclusive, non-transferable, non-sublicensable, revocable license to install
|
|
11
|
+
and run this software in connection with the customer's authorized use of the
|
|
12
|
+
Capsule platform, solely for the customer's internal business operations.
|
|
13
|
+
|
|
14
|
+
Except as expressly permitted by the Subscription Agreement, you may not:
|
|
15
|
+
(a) copy, modify, or create derivative works of the software;
|
|
16
|
+
(b) reverse engineer, decompile, or disassemble the software;
|
|
17
|
+
(c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
|
|
18
|
+
software to any third party;
|
|
19
|
+
(d) remove or alter any proprietary notices contained in the software; or
|
|
20
|
+
(e) use the software except in connection with an active Subscription
|
|
21
|
+
Agreement.
|
|
22
|
+
|
|
23
|
+
Without a valid Subscription Agreement with Capsule, no rights are granted to
|
|
24
|
+
use this software. Unauthorized use is prohibited.
|
|
25
|
+
|
|
26
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
|
|
27
|
+
OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
|
|
28
|
+
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
|
|
29
|
+
LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
|
|
30
|
+
AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
|
|
31
|
+
|
|
32
|
+
For licensing inquiries, contact: sales@capsulesecurity.io
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: capsule-strands
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Capsule plugin for Strands Agents - gates prompts and tool calls against Capsule policies and reports every session for audit.
|
|
5
|
+
Project-URL: Homepage, https://github.com/capsulesecurity
|
|
6
|
+
Project-URL: Documentation, https://docs.capsulesecurity.io/guides/strands
|
|
7
|
+
Author: Capsule Security
|
|
8
|
+
License: Capsule Security Commercial License
|
|
9
|
+
|
|
10
|
+
Copyright (c) Capsule Security, Inc. All rights reserved.
|
|
11
|
+
|
|
12
|
+
This software is licensed, not sold, and is made available solely to customers
|
|
13
|
+
of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
|
|
14
|
+
agreement (the "Subscription Agreement") between the customer and Capsule.
|
|
15
|
+
|
|
16
|
+
Subject to the Subscription Agreement, Capsule grants the customer a
|
|
17
|
+
non-exclusive, non-transferable, non-sublicensable, revocable license to install
|
|
18
|
+
and run this software in connection with the customer's authorized use of the
|
|
19
|
+
Capsule platform, solely for the customer's internal business operations.
|
|
20
|
+
|
|
21
|
+
Except as expressly permitted by the Subscription Agreement, you may not:
|
|
22
|
+
(a) copy, modify, or create derivative works of the software;
|
|
23
|
+
(b) reverse engineer, decompile, or disassemble the software;
|
|
24
|
+
(c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
|
|
25
|
+
software to any third party;
|
|
26
|
+
(d) remove or alter any proprietary notices contained in the software; or
|
|
27
|
+
(e) use the software except in connection with an active Subscription
|
|
28
|
+
Agreement.
|
|
29
|
+
|
|
30
|
+
Without a valid Subscription Agreement with Capsule, no rights are granted to
|
|
31
|
+
use this software. Unauthorized use is prohibited.
|
|
32
|
+
|
|
33
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
|
|
34
|
+
OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
|
|
35
|
+
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
|
|
36
|
+
LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
|
|
37
|
+
AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
|
|
38
|
+
|
|
39
|
+
For licensing inquiries, contact: sales@capsulesecurity.io
|
|
40
|
+
License-File: LICENSE
|
|
41
|
+
Keywords: agent-security,capsule,policy,security,strands,strands-agents
|
|
42
|
+
Classifier: License :: Other/Proprietary License
|
|
43
|
+
Classifier: Programming Language :: Python :: 3
|
|
44
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
45
|
+
Requires-Python: >=3.10
|
|
46
|
+
Requires-Dist: httpx>=0.27
|
|
47
|
+
Requires-Dist: strands-agents>=1.43
|
|
48
|
+
Description-Content-Type: text/markdown
|
|
49
|
+
|
|
50
|
+
# capsule-strands
|
|
51
|
+
|
|
52
|
+
Capsule plugin for [Strands Agents](https://strandsagents.com). It sends every prompt and tool call of a Strands agent to Capsule for an allow/block verdict before it runs, and reports the rest of the session for audit.
|
|
53
|
+
|
|
54
|
+
## Install
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install capsule-strands
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
It requires `strands-agents` 1.43 or later.
|
|
61
|
+
|
|
62
|
+
## Configure
|
|
63
|
+
|
|
64
|
+
Attach the plugin to each agent:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from strands import Agent
|
|
68
|
+
from capsule_strands import CapsulePlugin
|
|
69
|
+
|
|
70
|
+
agent = Agent(
|
|
71
|
+
agent_id="support-agent",
|
|
72
|
+
name="Acme Support Agent",
|
|
73
|
+
system_prompt="You answer Acme billing questions.",
|
|
74
|
+
tools=[...],
|
|
75
|
+
plugins=[CapsulePlugin()],
|
|
76
|
+
)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Set the endpoint and token where the agent runs:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
export CAPSULE_STRANDS_ENDPOINT="https://agents.capsule.security/v1/strands/hooks/events"
|
|
83
|
+
export CAPSULE_STRANDS_TOKEN="<token from the Capsule portal>"
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The `endpoint` and `token` values are issued by Capsule when you install the Strands Agents integration in the portal (**Integrations → Strands Agents**). The token is a JWT scoped to your tenant and environment, so treat it as a secret.
|
|
87
|
+
|
|
88
|
+
Every setting can also be passed to `CapsulePlugin(...)`. A constructor argument wins over its environment variable.
|
|
89
|
+
|
|
90
|
+
| Argument | Environment variable | Default | Description |
|
|
91
|
+
| --------------- | ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| `endpoint` | `CAPSULE_STRANDS_ENDPOINT` | | Required. |
|
|
93
|
+
| `token` | `CAPSULE_STRANDS_TOKEN` | | Required. |
|
|
94
|
+
| `block_on_risk` | `CAPSULE_STRANDS_BLOCK_ON_RISK` | `true` | Apply Capsule's `block` verdicts. Set to `false` to run the plugin in observe-only mode. |
|
|
95
|
+
| `fail_open` | `CAPSULE_STRANDS_FAIL_OPEN` | `true` | Let a prompt or tool call through when Capsule is unreachable or answers with an error. Set to `false` to block. |
|
|
96
|
+
| `timeout_ms` | `CAPSULE_STRANDS_TIMEOUT_MS` | `35000` | How long to wait for Capsule's verdict. When it passes first, the prompt or tool call follows `fail_open`. |
|
|
97
|
+
|
|
98
|
+
## How it works
|
|
99
|
+
|
|
100
|
+
| Strands hook | Type | Event | What happens on a block |
|
|
101
|
+
| ----------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------- |
|
|
102
|
+
| `BeforeInvocationEvent` | Blocking | `user_message` | The invocation is cancelled before the model is called; the agent returns the reason. |
|
|
103
|
+
| `BeforeToolCallEvent` | Blocking | `tool_invocation` | The tool never runs; the model gets an error tool result carrying the reason. |
|
|
104
|
+
| `AfterToolCallEvent` | Observation | `tool_result` | |
|
|
105
|
+
| `AfterInvocationEvent` | Observation | `agent_message` | |
|
|
106
|
+
|
|
107
|
+
The first invocation of each agent also reports a `session_start` with the agent's system prompt, model id and registered tools, before its prompt is judged. Tool results and replies are posted from a background thread, in the order they happened, so they never slow the agent down.
|
|
108
|
+
|
|
109
|
+
The deprecated `Agent.structured_output()` method is gated too. Strands gives hooks neither its prompt nor a way to cancel it, so the plugin judges the prompt before the call and raises `capsule_strands.CapsuleBlockedError` with the reason when Capsule blocks it.
|
|
110
|
+
|
|
111
|
+
Every event carries the agent's identity: its `agent_id`, or its `name` when `agent_id` is left at the Strands default. Set `agent_id` on each agent so Capsule keeps them apart. The session id is `trace_attributes["session.id"]` when the agent sets one, then the session manager's session id, and otherwise a random id per `Agent` instance.
|
|
112
|
+
|
|
113
|
+
## Tests
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install "strands-agents==<version>" -e . -r tests/requirements.txt
|
|
117
|
+
pytest tests
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The tests run real Strands agents against a scripted model and a fake Capsule. The end-to-end suite against the real Capsule backend lives in `apps/agentsecurity` (`nx run agentsecurity:test:strands-evals`).
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
Capsule Security Commercial License. See [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# capsule-strands
|
|
2
|
+
|
|
3
|
+
Capsule plugin for [Strands Agents](https://strandsagents.com). It sends every prompt and tool call of a Strands agent to Capsule for an allow/block verdict before it runs, and reports the rest of the session for audit.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install capsule-strands
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
It requires `strands-agents` 1.43 or later.
|
|
12
|
+
|
|
13
|
+
## Configure
|
|
14
|
+
|
|
15
|
+
Attach the plugin to each agent:
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from strands import Agent
|
|
19
|
+
from capsule_strands import CapsulePlugin
|
|
20
|
+
|
|
21
|
+
agent = Agent(
|
|
22
|
+
agent_id="support-agent",
|
|
23
|
+
name="Acme Support Agent",
|
|
24
|
+
system_prompt="You answer Acme billing questions.",
|
|
25
|
+
tools=[...],
|
|
26
|
+
plugins=[CapsulePlugin()],
|
|
27
|
+
)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Set the endpoint and token where the agent runs:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
export CAPSULE_STRANDS_ENDPOINT="https://agents.capsule.security/v1/strands/hooks/events"
|
|
34
|
+
export CAPSULE_STRANDS_TOKEN="<token from the Capsule portal>"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `endpoint` and `token` values are issued by Capsule when you install the Strands Agents integration in the portal (**Integrations → Strands Agents**). The token is a JWT scoped to your tenant and environment, so treat it as a secret.
|
|
38
|
+
|
|
39
|
+
Every setting can also be passed to `CapsulePlugin(...)`. A constructor argument wins over its environment variable.
|
|
40
|
+
|
|
41
|
+
| Argument | Environment variable | Default | Description |
|
|
42
|
+
| --------------- | ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
43
|
+
| `endpoint` | `CAPSULE_STRANDS_ENDPOINT` | | Required. |
|
|
44
|
+
| `token` | `CAPSULE_STRANDS_TOKEN` | | Required. |
|
|
45
|
+
| `block_on_risk` | `CAPSULE_STRANDS_BLOCK_ON_RISK` | `true` | Apply Capsule's `block` verdicts. Set to `false` to run the plugin in observe-only mode. |
|
|
46
|
+
| `fail_open` | `CAPSULE_STRANDS_FAIL_OPEN` | `true` | Let a prompt or tool call through when Capsule is unreachable or answers with an error. Set to `false` to block. |
|
|
47
|
+
| `timeout_ms` | `CAPSULE_STRANDS_TIMEOUT_MS` | `35000` | How long to wait for Capsule's verdict. When it passes first, the prompt or tool call follows `fail_open`. |
|
|
48
|
+
|
|
49
|
+
## How it works
|
|
50
|
+
|
|
51
|
+
| Strands hook | Type | Event | What happens on a block |
|
|
52
|
+
| ----------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------- |
|
|
53
|
+
| `BeforeInvocationEvent` | Blocking | `user_message` | The invocation is cancelled before the model is called; the agent returns the reason. |
|
|
54
|
+
| `BeforeToolCallEvent` | Blocking | `tool_invocation` | The tool never runs; the model gets an error tool result carrying the reason. |
|
|
55
|
+
| `AfterToolCallEvent` | Observation | `tool_result` | |
|
|
56
|
+
| `AfterInvocationEvent` | Observation | `agent_message` | |
|
|
57
|
+
|
|
58
|
+
The first invocation of each agent also reports a `session_start` with the agent's system prompt, model id and registered tools, before its prompt is judged. Tool results and replies are posted from a background thread, in the order they happened, so they never slow the agent down.
|
|
59
|
+
|
|
60
|
+
The deprecated `Agent.structured_output()` method is gated too. Strands gives hooks neither its prompt nor a way to cancel it, so the plugin judges the prompt before the call and raises `capsule_strands.CapsuleBlockedError` with the reason when Capsule blocks it.
|
|
61
|
+
|
|
62
|
+
Every event carries the agent's identity: its `agent_id`, or its `name` when `agent_id` is left at the Strands default. Set `agent_id` on each agent so Capsule keeps them apart. The session id is `trace_attributes["session.id"]` when the agent sets one, then the session manager's session id, and otherwise a random id per `Agent` instance.
|
|
63
|
+
|
|
64
|
+
## Tests
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install "strands-agents==<version>" -e . -r tests/requirements.txt
|
|
68
|
+
pytest tests
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The tests run real Strands agents against a scripted model and a fake Capsule. The end-to-end suite against the real Capsule backend lives in `apps/agentsecurity` (`nx run agentsecurity:test:strands-evals`).
|
|
72
|
+
|
|
73
|
+
## License
|
|
74
|
+
|
|
75
|
+
Capsule Security Commercial License. See [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.21"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "capsule-strands"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Capsule plugin for Strands Agents - gates prompts and tool calls against Capsule policies and reports every session for audit."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { file = "LICENSE" }
|
|
12
|
+
authors = [{ name = "Capsule Security" }]
|
|
13
|
+
keywords = [
|
|
14
|
+
"strands",
|
|
15
|
+
"strands-agents",
|
|
16
|
+
"capsule",
|
|
17
|
+
"security",
|
|
18
|
+
"policy",
|
|
19
|
+
"agent-security",
|
|
20
|
+
]
|
|
21
|
+
classifiers = [
|
|
22
|
+
"License :: Other/Proprietary License",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"httpx>=0.27",
|
|
28
|
+
"strands-agents>=1.43",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Homepage = "https://github.com/capsulesecurity"
|
|
33
|
+
Documentation = "https://docs.capsulesecurity.io/guides/strands"
|
|
34
|
+
|
|
35
|
+
[tool.hatch.build.targets.wheel]
|
|
36
|
+
packages = ["src/capsule_strands"]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Capsule plugin for Strands Agents.
|
|
2
|
+
|
|
3
|
+
Puts a Strands agent's prompts and tool calls behind Capsule policies and reports every session for audit.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from .config import CapsuleConfig
|
|
7
|
+
from .plugin import PLUGIN_VERSION, CapsuleBlockedError, CapsulePlugin
|
|
8
|
+
|
|
9
|
+
__all__ = ["CapsuleBlockedError", "CapsuleConfig", "CapsulePlugin", "PLUGIN_VERSION"]
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Configuration for the Capsule Strands plugin."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
_ENV_PREFIX = "CAPSULE_STRANDS_"
|
|
9
|
+
_TRUE_VALUES = {"1", "true", "yes", "on"}
|
|
10
|
+
DEFAULT_TIMEOUT_MS = 35_000
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _env(key: str) -> str | None:
|
|
14
|
+
value = os.environ.get(f"{_ENV_PREFIX}{key}")
|
|
15
|
+
return value if value else None
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _env_bool(key: str, default: bool) -> bool:
|
|
19
|
+
value = _env(key)
|
|
20
|
+
return default if value is None else value.strip().lower() in _TRUE_VALUES
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _env_int(key: str, default: int) -> int:
|
|
24
|
+
value = _env(key)
|
|
25
|
+
if value is None:
|
|
26
|
+
return default
|
|
27
|
+
try:
|
|
28
|
+
return int(value)
|
|
29
|
+
except ValueError as error:
|
|
30
|
+
raise ValueError(f"capsule_strands: {_ENV_PREFIX}{key} must be an integer, got {value!r}") from error
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@dataclass(frozen=True)
|
|
34
|
+
class CapsuleConfig:
|
|
35
|
+
"""Plugin settings. Constructor arguments win; `CAPSULE_STRANDS_*` environment variables fill in the rest."""
|
|
36
|
+
|
|
37
|
+
endpoint: str
|
|
38
|
+
token: str
|
|
39
|
+
block_on_risk: bool
|
|
40
|
+
fail_open: bool
|
|
41
|
+
timeout_ms: int
|
|
42
|
+
|
|
43
|
+
@classmethod
|
|
44
|
+
def load(
|
|
45
|
+
cls,
|
|
46
|
+
*,
|
|
47
|
+
endpoint: str | None = None,
|
|
48
|
+
token: str | None = None,
|
|
49
|
+
block_on_risk: bool | None = None,
|
|
50
|
+
fail_open: bool | None = None,
|
|
51
|
+
timeout_ms: int | None = None,
|
|
52
|
+
) -> CapsuleConfig:
|
|
53
|
+
resolved_endpoint = endpoint or _env("ENDPOINT")
|
|
54
|
+
resolved_token = token or _env("TOKEN")
|
|
55
|
+
if not resolved_endpoint:
|
|
56
|
+
raise ValueError(f"capsule_strands: endpoint missing (pass endpoint= or set {_ENV_PREFIX}ENDPOINT)")
|
|
57
|
+
if not resolved_token:
|
|
58
|
+
raise ValueError(f"capsule_strands: token missing (pass token= or set {_ENV_PREFIX}TOKEN)")
|
|
59
|
+
return cls(
|
|
60
|
+
endpoint=resolved_endpoint,
|
|
61
|
+
token=resolved_token,
|
|
62
|
+
block_on_risk=block_on_risk if block_on_risk is not None else _env_bool("BLOCK_ON_RISK", True),
|
|
63
|
+
fail_open=fail_open if fail_open is not None else _env_bool("FAIL_OPEN", True),
|
|
64
|
+
timeout_ms=timeout_ms if timeout_ms is not None else _env_int("TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
|
|
65
|
+
)
|