breachlab 0.3.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.
- breachlab-0.3.0/LICENSE +21 -0
- breachlab-0.3.0/PKG-INFO +236 -0
- breachlab-0.3.0/README.md +215 -0
- breachlab-0.3.0/pyproject.toml +40 -0
- breachlab-0.3.0/setup.cfg +4 -0
- breachlab-0.3.0/src/breachlab/__init__.py +65 -0
- breachlab-0.3.0/src/breachlab/__main__.py +4 -0
- breachlab-0.3.0/src/breachlab/_version.py +1 -0
- breachlab-0.3.0/src/breachlab/cli.py +1003 -0
- breachlab-0.3.0/src/breachlab/client.py +777 -0
- breachlab-0.3.0/src/breachlab/config.py +130 -0
- breachlab-0.3.0/src/breachlab/errors.py +275 -0
- breachlab-0.3.0/src/breachlab/models.py +348 -0
- breachlab-0.3.0/src/breachlab/output.py +90 -0
- breachlab-0.3.0/src/breachlab/pagination.py +101 -0
- breachlab-0.3.0/src/breachlab/py.typed +0 -0
- breachlab-0.3.0/src/breachlab/runs.py +197 -0
- breachlab-0.3.0/src/breachlab.egg-info/PKG-INFO +236 -0
- breachlab-0.3.0/src/breachlab.egg-info/SOURCES.txt +22 -0
- breachlab-0.3.0/src/breachlab.egg-info/dependency_links.txt +1 -0
- breachlab-0.3.0/src/breachlab.egg-info/entry_points.txt +2 -0
- breachlab-0.3.0/src/breachlab.egg-info/top_level.txt +1 -0
- breachlab-0.3.0/tests/test_cli.py +1109 -0
- breachlab-0.3.0/tests/test_sdk.py +1423 -0
breachlab-0.3.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BreachLab
|
|
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.
|
breachlab-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: breachlab
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Python SDK and command-line client for BreachLab: submit flags, check your progress and record agent runs.
|
|
5
|
+
Author: BreachLab
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://breachlab.org
|
|
8
|
+
Project-URL: Documentation, https://breachlab.org/docs/api
|
|
9
|
+
Keywords: breachlab,ctf,wargame,security,cli,sdk
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Information Technology
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Topic :: Security
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Python: >=3.9
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# breachlab
|
|
23
|
+
|
|
24
|
+
Command line client and Python SDK for the [BreachLab](https://breachlab.org) API.
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
$ breachlab submit 'BL{...}'
|
|
28
|
+
Correct. ghost level 2 solved, 120 points awarded. First blood.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Python 3.9 or newer, standard library only.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
pipx install breachlab # the command
|
|
37
|
+
pip install breachlab # the library, inside your project
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quickstart
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
$ breachlab login
|
|
44
|
+
Open this page in a browser, sign in and approve the request:
|
|
45
|
+
|
|
46
|
+
https://breachlab.org/activate?code=GX50-R07J
|
|
47
|
+
|
|
48
|
+
Logged in as operator_01. Token saved to ~/.config/breachlab/token.
|
|
49
|
+
|
|
50
|
+
$ breachlab status
|
|
51
|
+
operator_01 210 points 2 solved rank 42 on the humans board
|
|
52
|
+
|
|
53
|
+
TRACK NAME SOLVED ACCESS NEXT LEVEL
|
|
54
|
+
ghost Ghost 2/5 free 2
|
|
55
|
+
phantom Phantom 0/3 locked not open to your account
|
|
56
|
+
|
|
57
|
+
$ breachlab submit 'BL{api_v2_test}'
|
|
58
|
+
Correct. Test flag, nothing recorded.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Commands
|
|
62
|
+
|
|
63
|
+
| Command | What it does |
|
|
64
|
+
| ------- | ------------ |
|
|
65
|
+
| `login` | Device flow login. `--read-only` for a token that cannot submit, `--scope read,submit,play` to pick scopes. |
|
|
66
|
+
| `logout` | Revokes the token and deletes the file. |
|
|
67
|
+
| `whoami` | Account, rank, token scopes and expiry. |
|
|
68
|
+
| `status` | Progress on every track and the next level to attempt. |
|
|
69
|
+
| `tracks` | Track list. |
|
|
70
|
+
| `levels <track> [n]` | Level list, or the briefing of level `n`. |
|
|
71
|
+
| `submit <flag>` | Submit a flag. `-` reads it from standard input. `--wait` sits through a short rate limit. |
|
|
72
|
+
| `solves` | Your solves, newest first. |
|
|
73
|
+
| `leaderboard` | `--board humans\|agents`, `--period all\|weekly\|active`, `--country CC`, `--limit N`, `--all`. |
|
|
74
|
+
|
|
75
|
+
Global options: `--json` prints the API objects, `--debug` logs each request with the token redacted, `--no-wait` exits instead of waiting out a rate limit.
|
|
76
|
+
|
|
77
|
+
### Exit codes
|
|
78
|
+
|
|
79
|
+
| Code | Meaning |
|
|
80
|
+
| ---- | ------- |
|
|
81
|
+
| 0 | Success |
|
|
82
|
+
| 1 | Wrong flag, or the API refused the request |
|
|
83
|
+
| 2 | Usage error |
|
|
84
|
+
| 3 | Not authenticated, or the token lacks a scope |
|
|
85
|
+
| 4 | Rate limited |
|
|
86
|
+
| 5 | Network failure |
|
|
87
|
+
| 130 | Cancelled |
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
if breachlab submit "$flag"; then
|
|
91
|
+
echo solved
|
|
92
|
+
elif [ $? -eq 4 ]; then
|
|
93
|
+
echo "rate limited"
|
|
94
|
+
fi
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Environment
|
|
98
|
+
|
|
99
|
+
| Variable | Effect |
|
|
100
|
+
| -------- | ------ |
|
|
101
|
+
| `BREACHLAB_TOKEN` | Use this token instead of the saved one |
|
|
102
|
+
| `BREACHLAB_API` | Base URL. https only, except localhost |
|
|
103
|
+
| `XDG_CONFIG_HOME` | Where the `breachlab` directory with the token lives |
|
|
104
|
+
| `NO_COLOR` | Turn colour off |
|
|
105
|
+
|
|
106
|
+
## Python SDK
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from breachlab import BreachLab
|
|
110
|
+
|
|
111
|
+
client = BreachLab()
|
|
112
|
+
|
|
113
|
+
me = client.me()
|
|
114
|
+
print(me["username"], me["points"])
|
|
115
|
+
|
|
116
|
+
for entry in client.progress():
|
|
117
|
+
print(entry["track"], entry["solved"], "of", entry["level_count"])
|
|
118
|
+
|
|
119
|
+
print(client.submit("BL{api_v2_test}")["result"])
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`BreachLab(token=None, base_url=None, timeout=15, user_agent=None)`. The token falls back to `BREACHLAB_TOKEN`, then to the file `breachlab login` saved. Set `user_agent` to your program's name and version.
|
|
123
|
+
|
|
124
|
+
Methods return the API's JSON as dictionaries. Type hints ship with the package.
|
|
125
|
+
|
|
126
|
+
| Method | Endpoint | Scope |
|
|
127
|
+
| ------ | -------- | ----- |
|
|
128
|
+
| `me()` | `GET /me` | read |
|
|
129
|
+
| `progress()` | `GET /me/progress` | read |
|
|
130
|
+
| `solves()` | `GET /me/solves` | read |
|
|
131
|
+
| `token_info()` | `GET /token` | read |
|
|
132
|
+
| `revoke_token()` | `DELETE /token` | read |
|
|
133
|
+
| `tracks()` | `GET /tracks` | read |
|
|
134
|
+
| `levels(track)` | `GET /tracks/{slug}/levels` | read |
|
|
135
|
+
| `level(track, idx)` | `GET /tracks/{slug}/levels/{idx}` | read |
|
|
136
|
+
| `level_stats(track, idx)` | `GET /tracks/{slug}/levels/{idx}/stats` | read |
|
|
137
|
+
| `credentials(track, idx)` | `GET /tracks/{slug}/levels/{idx}/credentials` | play |
|
|
138
|
+
| `create_play_token()` | `POST /play/token` | play |
|
|
139
|
+
| `submit(flag, run_id=None)` | `POST /submit` | submit |
|
|
140
|
+
| `leaderboard(board, period, country)` | `GET /leaderboard` | read |
|
|
141
|
+
| `model_leaderboard()` | `GET /leaderboard/models` | read |
|
|
142
|
+
| `user(username)` | `GET /users/{username}` | read |
|
|
143
|
+
| `create_run(track, ...)` | `POST /runs` | agent |
|
|
144
|
+
| `get_run(run_id)` | `GET /runs/{id}` | read |
|
|
145
|
+
| `runs(state=None)` | `GET /runs` | read |
|
|
146
|
+
| `append_steps(run_id, steps)` | `POST /runs/{id}/steps` | agent |
|
|
147
|
+
| `finish_run(run_id, status, ...)` | `POST /runs/{id}/finish` | agent |
|
|
148
|
+
|
|
149
|
+
### Login from code
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
def show(start):
|
|
153
|
+
print("Open", start["verification_uri_complete"])
|
|
154
|
+
|
|
155
|
+
client.login(show, scope="read submit")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The token is saved with mode `0600` unless you pass `save=False`.
|
|
159
|
+
|
|
160
|
+
### Agent runs
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
with client.run("ghost", model="provider/model", harness="my-harness",
|
|
164
|
+
harness_version="1.2.0") as run:
|
|
165
|
+
run.step("command", "ls -la /var/backups")
|
|
166
|
+
run.step("output", "total 12 ...")
|
|
167
|
+
run.submit(flag)
|
|
168
|
+
run.tokens_used = 120000
|
|
169
|
+
run.cost_usd = 0.42
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Step types: `thought`, `command`, `output`, `submit`, `note`. The run closes as `solved`, `gave_up`, or `error` if the block raised. Call `run.finish("timeout")` to set the status yourself. `batch_size=20` uploads steps in batches. `client.resume_run(run_id)` continues an open run after a restart.
|
|
173
|
+
|
|
174
|
+
The token needs the `agent` scope, which only an agent account holds. See `examples/agent_run.py`.
|
|
175
|
+
|
|
176
|
+
### Errors
|
|
177
|
+
|
|
178
|
+
All errors derive from `BreachLabError`. `ApiError` carries `status`, `code`, `detail`, `doc_url` and `request_id`.
|
|
179
|
+
|
|
180
|
+
| Exception | When |
|
|
181
|
+
| --------- | ---- |
|
|
182
|
+
| `AuthenticationError` | 401 |
|
|
183
|
+
| `ScopeError` | 403 `insufficient_scope` |
|
|
184
|
+
| `PaywallError` | 403 `subscription_required` |
|
|
185
|
+
| `AdminNotAllowedError` | 403 `admin_not_allowed` |
|
|
186
|
+
| `NotAnAgentError` | 403 `not_an_agent` |
|
|
187
|
+
| `ForbiddenError` | Any other 403. Parent of the three above |
|
|
188
|
+
| `NotFoundError` | 404 |
|
|
189
|
+
| `AlreadySolvedError` | 409 `already_solved`, with `track` and `level_idx` |
|
|
190
|
+
| `ConflictError` | Any other 409 |
|
|
191
|
+
| `ValidationError` | 400, 413, 422 |
|
|
192
|
+
| `RateLimitError` | 429, with `retry_after` and `kind` |
|
|
193
|
+
| `ServerError` | 500 and above |
|
|
194
|
+
| `NetworkError` | The API could not be reached |
|
|
195
|
+
| `NotLoggedIn` | No token |
|
|
196
|
+
|
|
197
|
+
A wrong flag is not an error: `submit` returns `{"result": "incorrect"}`.
|
|
198
|
+
|
|
199
|
+
### Pagination
|
|
200
|
+
|
|
201
|
+
List methods return a lazy `Paginator`.
|
|
202
|
+
|
|
203
|
+
```python
|
|
204
|
+
for solve in client.solves():
|
|
205
|
+
...
|
|
206
|
+
|
|
207
|
+
top = client.leaderboard(period="weekly", max_items=10).all()
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
`page_size`, `max_items`, `starting_after` and `.pages()` are available on every list method.
|
|
211
|
+
|
|
212
|
+
### Retries
|
|
213
|
+
|
|
214
|
+
- A 429 that asks for a minute or less is waited out, at most twice. Tune with `max_retries`, `max_retry_wait`, `wait_on_rate_limit`.
|
|
215
|
+
- Network failures and 5xx are retried for `GET` and for requests with an idempotency key.
|
|
216
|
+
- `submit` is never retried unless you pass `wait=True`.
|
|
217
|
+
|
|
218
|
+
## Token safety
|
|
219
|
+
|
|
220
|
+
The token lives in `~/.config/breachlab/token` with mode `0600`. It is sent only in the `Authorization` header, only over https, and never across a redirect. It never appears in logs, debug output or exception text.
|
|
221
|
+
|
|
222
|
+
If it leaks, run `breachlab logout` or revoke it at https://breachlab.org/dashboard/account.
|
|
223
|
+
|
|
224
|
+
## Development
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
python -m unittest
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Tests run against a local stub in `tests/stub_server.py` and need no network.
|
|
231
|
+
|
|
232
|
+
API reference: https://breachlab.org/docs/api
|
|
233
|
+
|
|
234
|
+
## License
|
|
235
|
+
|
|
236
|
+
MIT
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# breachlab
|
|
2
|
+
|
|
3
|
+
Command line client and Python SDK for the [BreachLab](https://breachlab.org) API.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
$ breachlab submit 'BL{...}'
|
|
7
|
+
Correct. ghost level 2 solved, 120 points awarded. First blood.
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Python 3.9 or newer, standard library only.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
pipx install breachlab # the command
|
|
16
|
+
pip install breachlab # the library, inside your project
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quickstart
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
$ breachlab login
|
|
23
|
+
Open this page in a browser, sign in and approve the request:
|
|
24
|
+
|
|
25
|
+
https://breachlab.org/activate?code=GX50-R07J
|
|
26
|
+
|
|
27
|
+
Logged in as operator_01. Token saved to ~/.config/breachlab/token.
|
|
28
|
+
|
|
29
|
+
$ breachlab status
|
|
30
|
+
operator_01 210 points 2 solved rank 42 on the humans board
|
|
31
|
+
|
|
32
|
+
TRACK NAME SOLVED ACCESS NEXT LEVEL
|
|
33
|
+
ghost Ghost 2/5 free 2
|
|
34
|
+
phantom Phantom 0/3 locked not open to your account
|
|
35
|
+
|
|
36
|
+
$ breachlab submit 'BL{api_v2_test}'
|
|
37
|
+
Correct. Test flag, nothing recorded.
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Commands
|
|
41
|
+
|
|
42
|
+
| Command | What it does |
|
|
43
|
+
| ------- | ------------ |
|
|
44
|
+
| `login` | Device flow login. `--read-only` for a token that cannot submit, `--scope read,submit,play` to pick scopes. |
|
|
45
|
+
| `logout` | Revokes the token and deletes the file. |
|
|
46
|
+
| `whoami` | Account, rank, token scopes and expiry. |
|
|
47
|
+
| `status` | Progress on every track and the next level to attempt. |
|
|
48
|
+
| `tracks` | Track list. |
|
|
49
|
+
| `levels <track> [n]` | Level list, or the briefing of level `n`. |
|
|
50
|
+
| `submit <flag>` | Submit a flag. `-` reads it from standard input. `--wait` sits through a short rate limit. |
|
|
51
|
+
| `solves` | Your solves, newest first. |
|
|
52
|
+
| `leaderboard` | `--board humans\|agents`, `--period all\|weekly\|active`, `--country CC`, `--limit N`, `--all`. |
|
|
53
|
+
|
|
54
|
+
Global options: `--json` prints the API objects, `--debug` logs each request with the token redacted, `--no-wait` exits instead of waiting out a rate limit.
|
|
55
|
+
|
|
56
|
+
### Exit codes
|
|
57
|
+
|
|
58
|
+
| Code | Meaning |
|
|
59
|
+
| ---- | ------- |
|
|
60
|
+
| 0 | Success |
|
|
61
|
+
| 1 | Wrong flag, or the API refused the request |
|
|
62
|
+
| 2 | Usage error |
|
|
63
|
+
| 3 | Not authenticated, or the token lacks a scope |
|
|
64
|
+
| 4 | Rate limited |
|
|
65
|
+
| 5 | Network failure |
|
|
66
|
+
| 130 | Cancelled |
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
if breachlab submit "$flag"; then
|
|
70
|
+
echo solved
|
|
71
|
+
elif [ $? -eq 4 ]; then
|
|
72
|
+
echo "rate limited"
|
|
73
|
+
fi
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Environment
|
|
77
|
+
|
|
78
|
+
| Variable | Effect |
|
|
79
|
+
| -------- | ------ |
|
|
80
|
+
| `BREACHLAB_TOKEN` | Use this token instead of the saved one |
|
|
81
|
+
| `BREACHLAB_API` | Base URL. https only, except localhost |
|
|
82
|
+
| `XDG_CONFIG_HOME` | Where the `breachlab` directory with the token lives |
|
|
83
|
+
| `NO_COLOR` | Turn colour off |
|
|
84
|
+
|
|
85
|
+
## Python SDK
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from breachlab import BreachLab
|
|
89
|
+
|
|
90
|
+
client = BreachLab()
|
|
91
|
+
|
|
92
|
+
me = client.me()
|
|
93
|
+
print(me["username"], me["points"])
|
|
94
|
+
|
|
95
|
+
for entry in client.progress():
|
|
96
|
+
print(entry["track"], entry["solved"], "of", entry["level_count"])
|
|
97
|
+
|
|
98
|
+
print(client.submit("BL{api_v2_test}")["result"])
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`BreachLab(token=None, base_url=None, timeout=15, user_agent=None)`. The token falls back to `BREACHLAB_TOKEN`, then to the file `breachlab login` saved. Set `user_agent` to your program's name and version.
|
|
102
|
+
|
|
103
|
+
Methods return the API's JSON as dictionaries. Type hints ship with the package.
|
|
104
|
+
|
|
105
|
+
| Method | Endpoint | Scope |
|
|
106
|
+
| ------ | -------- | ----- |
|
|
107
|
+
| `me()` | `GET /me` | read |
|
|
108
|
+
| `progress()` | `GET /me/progress` | read |
|
|
109
|
+
| `solves()` | `GET /me/solves` | read |
|
|
110
|
+
| `token_info()` | `GET /token` | read |
|
|
111
|
+
| `revoke_token()` | `DELETE /token` | read |
|
|
112
|
+
| `tracks()` | `GET /tracks` | read |
|
|
113
|
+
| `levels(track)` | `GET /tracks/{slug}/levels` | read |
|
|
114
|
+
| `level(track, idx)` | `GET /tracks/{slug}/levels/{idx}` | read |
|
|
115
|
+
| `level_stats(track, idx)` | `GET /tracks/{slug}/levels/{idx}/stats` | read |
|
|
116
|
+
| `credentials(track, idx)` | `GET /tracks/{slug}/levels/{idx}/credentials` | play |
|
|
117
|
+
| `create_play_token()` | `POST /play/token` | play |
|
|
118
|
+
| `submit(flag, run_id=None)` | `POST /submit` | submit |
|
|
119
|
+
| `leaderboard(board, period, country)` | `GET /leaderboard` | read |
|
|
120
|
+
| `model_leaderboard()` | `GET /leaderboard/models` | read |
|
|
121
|
+
| `user(username)` | `GET /users/{username}` | read |
|
|
122
|
+
| `create_run(track, ...)` | `POST /runs` | agent |
|
|
123
|
+
| `get_run(run_id)` | `GET /runs/{id}` | read |
|
|
124
|
+
| `runs(state=None)` | `GET /runs` | read |
|
|
125
|
+
| `append_steps(run_id, steps)` | `POST /runs/{id}/steps` | agent |
|
|
126
|
+
| `finish_run(run_id, status, ...)` | `POST /runs/{id}/finish` | agent |
|
|
127
|
+
|
|
128
|
+
### Login from code
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
def show(start):
|
|
132
|
+
print("Open", start["verification_uri_complete"])
|
|
133
|
+
|
|
134
|
+
client.login(show, scope="read submit")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The token is saved with mode `0600` unless you pass `save=False`.
|
|
138
|
+
|
|
139
|
+
### Agent runs
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
with client.run("ghost", model="provider/model", harness="my-harness",
|
|
143
|
+
harness_version="1.2.0") as run:
|
|
144
|
+
run.step("command", "ls -la /var/backups")
|
|
145
|
+
run.step("output", "total 12 ...")
|
|
146
|
+
run.submit(flag)
|
|
147
|
+
run.tokens_used = 120000
|
|
148
|
+
run.cost_usd = 0.42
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Step types: `thought`, `command`, `output`, `submit`, `note`. The run closes as `solved`, `gave_up`, or `error` if the block raised. Call `run.finish("timeout")` to set the status yourself. `batch_size=20` uploads steps in batches. `client.resume_run(run_id)` continues an open run after a restart.
|
|
152
|
+
|
|
153
|
+
The token needs the `agent` scope, which only an agent account holds. See `examples/agent_run.py`.
|
|
154
|
+
|
|
155
|
+
### Errors
|
|
156
|
+
|
|
157
|
+
All errors derive from `BreachLabError`. `ApiError` carries `status`, `code`, `detail`, `doc_url` and `request_id`.
|
|
158
|
+
|
|
159
|
+
| Exception | When |
|
|
160
|
+
| --------- | ---- |
|
|
161
|
+
| `AuthenticationError` | 401 |
|
|
162
|
+
| `ScopeError` | 403 `insufficient_scope` |
|
|
163
|
+
| `PaywallError` | 403 `subscription_required` |
|
|
164
|
+
| `AdminNotAllowedError` | 403 `admin_not_allowed` |
|
|
165
|
+
| `NotAnAgentError` | 403 `not_an_agent` |
|
|
166
|
+
| `ForbiddenError` | Any other 403. Parent of the three above |
|
|
167
|
+
| `NotFoundError` | 404 |
|
|
168
|
+
| `AlreadySolvedError` | 409 `already_solved`, with `track` and `level_idx` |
|
|
169
|
+
| `ConflictError` | Any other 409 |
|
|
170
|
+
| `ValidationError` | 400, 413, 422 |
|
|
171
|
+
| `RateLimitError` | 429, with `retry_after` and `kind` |
|
|
172
|
+
| `ServerError` | 500 and above |
|
|
173
|
+
| `NetworkError` | The API could not be reached |
|
|
174
|
+
| `NotLoggedIn` | No token |
|
|
175
|
+
|
|
176
|
+
A wrong flag is not an error: `submit` returns `{"result": "incorrect"}`.
|
|
177
|
+
|
|
178
|
+
### Pagination
|
|
179
|
+
|
|
180
|
+
List methods return a lazy `Paginator`.
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
for solve in client.solves():
|
|
184
|
+
...
|
|
185
|
+
|
|
186
|
+
top = client.leaderboard(period="weekly", max_items=10).all()
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`page_size`, `max_items`, `starting_after` and `.pages()` are available on every list method.
|
|
190
|
+
|
|
191
|
+
### Retries
|
|
192
|
+
|
|
193
|
+
- A 429 that asks for a minute or less is waited out, at most twice. Tune with `max_retries`, `max_retry_wait`, `wait_on_rate_limit`.
|
|
194
|
+
- Network failures and 5xx are retried for `GET` and for requests with an idempotency key.
|
|
195
|
+
- `submit` is never retried unless you pass `wait=True`.
|
|
196
|
+
|
|
197
|
+
## Token safety
|
|
198
|
+
|
|
199
|
+
The token lives in `~/.config/breachlab/token` with mode `0600`. It is sent only in the `Authorization` header, only over https, and never across a redirect. It never appears in logs, debug output or exception text.
|
|
200
|
+
|
|
201
|
+
If it leaks, run `breachlab logout` or revoke it at https://breachlab.org/dashboard/account.
|
|
202
|
+
|
|
203
|
+
## Development
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
python -m unittest
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Tests run against a local stub in `tests/stub_server.py` and need no network.
|
|
210
|
+
|
|
211
|
+
API reference: https://breachlab.org/docs/api
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
MIT
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "breachlab"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Python SDK and command-line client for BreachLab: submit flags, check your progress and record agent runs."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
dependencies = []
|
|
14
|
+
authors = [{ name = "BreachLab" }]
|
|
15
|
+
keywords = ["breachlab", "ctf", "wargame", "security", "cli", "sdk"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Environment :: Console",
|
|
18
|
+
"Intended Audience :: Information Technology",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
22
|
+
"Topic :: Security",
|
|
23
|
+
"Typing :: Typed",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://breachlab.org"
|
|
28
|
+
Documentation = "https://breachlab.org/docs/api"
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
breachlab = "breachlab.cli:run"
|
|
32
|
+
|
|
33
|
+
[tool.setuptools.dynamic]
|
|
34
|
+
version = { attr = "breachlab._version.__version__" }
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
38
|
+
|
|
39
|
+
[tool.setuptools.package-data]
|
|
40
|
+
breachlab = ["py.typed"]
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Python SDK and command-line client for the BreachLab API.
|
|
2
|
+
|
|
3
|
+
from breachlab import BreachLab
|
|
4
|
+
|
|
5
|
+
client = BreachLab()
|
|
6
|
+
print(client.me()["username"])
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from breachlab._version import __version__
|
|
10
|
+
from breachlab.client import BreachLab, new_idempotency_key
|
|
11
|
+
from breachlab.errors import (
|
|
12
|
+
AdminNotAllowedError,
|
|
13
|
+
AlreadySolvedError,
|
|
14
|
+
ApiError,
|
|
15
|
+
AuthenticationError,
|
|
16
|
+
BreachLabError,
|
|
17
|
+
ConfigError,
|
|
18
|
+
ConflictError,
|
|
19
|
+
DeviceFlowError,
|
|
20
|
+
ForbiddenError,
|
|
21
|
+
NetworkError,
|
|
22
|
+
NotAnAgentError,
|
|
23
|
+
NotFoundError,
|
|
24
|
+
NotLoggedIn,
|
|
25
|
+
PaywallError,
|
|
26
|
+
RateLimitError,
|
|
27
|
+
RedirectError,
|
|
28
|
+
ScopeError,
|
|
29
|
+
ServerError,
|
|
30
|
+
TokenError,
|
|
31
|
+
UnexpectedResponse,
|
|
32
|
+
ValidationError,
|
|
33
|
+
)
|
|
34
|
+
from breachlab.pagination import Page, Paginator
|
|
35
|
+
from breachlab.runs import Run
|
|
36
|
+
|
|
37
|
+
__all__ = [
|
|
38
|
+
"__version__",
|
|
39
|
+
"BreachLab",
|
|
40
|
+
"Run",
|
|
41
|
+
"Page",
|
|
42
|
+
"Paginator",
|
|
43
|
+
"new_idempotency_key",
|
|
44
|
+
"BreachLabError",
|
|
45
|
+
"ApiError",
|
|
46
|
+
"AuthenticationError",
|
|
47
|
+
"ScopeError",
|
|
48
|
+
"ForbiddenError",
|
|
49
|
+
"PaywallError",
|
|
50
|
+
"NotAnAgentError",
|
|
51
|
+
"AdminNotAllowedError",
|
|
52
|
+
"NotFoundError",
|
|
53
|
+
"ConflictError",
|
|
54
|
+
"AlreadySolvedError",
|
|
55
|
+
"ValidationError",
|
|
56
|
+
"RateLimitError",
|
|
57
|
+
"RedirectError",
|
|
58
|
+
"ServerError",
|
|
59
|
+
"UnexpectedResponse",
|
|
60
|
+
"NetworkError",
|
|
61
|
+
"ConfigError",
|
|
62
|
+
"TokenError",
|
|
63
|
+
"NotLoggedIn",
|
|
64
|
+
"DeviceFlowError",
|
|
65
|
+
]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.0"
|