veltro-sdk
Python client for the Veltro security operations suite: VectorFlow (telemetry pipelines), CHAD (detection) and Warden (SOAR / cases).
- No runtime dependencies — stdlib
urllibonly. - Generated from the products' own OpenAPI documents, with a CI gate that fails
when a product's API moves and the bindings do not
(
scripts/generate_sdk.py check). - Apache-2.0, so it can be embedded in your own tooling regardless of the AGPL-3.0 servers it talks to.
Install:
pip install veltro-sdk
Suite deployment
One origin, one identity session, three products. The gateway serves CHAD at
/chad, Warden at /warden and VectorFlow at /vectorflow, and exchanges the
identity session cookie for a short-lived request assertion toward each
product — so one login reaches all three.
from veltro_sdk import VeltroClient
suite = VeltroClient.login(
"https://soc.example.com",
"analyst@example.com",
password,
vectorflow_key="vf_live_…", # VectorFlow REST v1 takes a service-account key
)
for source in suite.chad.data_sources.list():
print(source["name"])
cases = suite.warden.cases.list(params={"limit": 25, "status": "open"})
pipelines = suite.vectorflow.pipelines.list()
VectorFlow's REST v1 accepts only an environment-scoped service-account key
(Authorization: Bearer vf_live_…); a browser session authenticates the UI and
tRPC, not /api/v1. A client built without one refuses at the call site with
MissingCredential rather than sending a credential VectorFlow will reject.
One product with a personal access token
Create a personal access token (vmcp_…) in the suite and send it as a bearer
to the product's gateway prefix. Identity turns it into the request assertion
the product checks, so the same token works for CHAD and Warden:
from veltro_sdk import ChadClient, WardenClient, BearerToken
chad = ChadClient("https://soc.example.com/chad", auth=BearerToken(pat))
chad.rules.list()
warden = WardenClient("https://soc.example.com/warden", auth=BearerToken(pat))
warden.runbooks.list()
VectorFlow's /api/v1 still wants its service-account key, so pass
BearerToken("vf_live_…") to VectorFlowClient.
Example
examples/triage.py lists open Warden cases and new critical or high CHAD alerts
with a personal access token from VELTRO_TOKEN. It's read-only and isn't
part of the published package.
Calling convention
Every operation is a method on a resource namespace. Path parameters are positional and percent-encoded; everything else is a keyword option passed to the transport:
client.data_sources.get("ds-123") # path parameter
client.alerts.list(params={"status": "open", "limit": 50})
client.rules.create(json={"title": "…", "sigma_yaml": "…"})
client.export.download(raw=True) # bytes, not JSON
| Option | Meaning |
|---|---|
params |
query parameters (None values dropped, lists repeat the key) |
json |
JSON request body |
data |
raw request body |
headers |
extra headers, applied after the credential |
timeout |
per-request timeout override (seconds) |
raw |
return bytes instead of parsed JSON |
Responses are the products' JSON, decoded — the SDK does not reshape them. The
field-level reference is each product's OpenAPI document (/openapi.json on
CHAD and Warden, /api/v1/openapi.json on VectorFlow).
Errors
| Exception | Raised when |
|---|---|
VeltroAPIError |
any non-2xx; carries .status, .code (the product's own refusal name), .message, .body |
VeltroTransportError |
the request never produced a response (DNS, TLS, connect, timeout) |
VeltroResponseTooLarge |
the response exceeded max_response_bytes (32 MiB default), enforced while streaming |
MissingCredential |
a product namespace was used without a credential it accepts |
429, 502, 503 and 504 are retried twice with exponential backoff,
honouring Retry-After. Nothing else is retried: a 409 or 422 is the
product's answer, not a transient fault.
Credentials are never logged: every credential object masks its material in
repr, and the transport keeps request headers out of exception messages.
A suite session is scoped to the origin that minted it. Pointing a product
client at a different origin while passing auth=session sends no cookie
there rather than the suite session — the cookie runs through
http.cookiejar, so Domain, Path and Secure are all honoured.
Coverage
| Product | Resources | Operations | Generated from |
|---|---|---|---|
| CHAD | 52 | 365 | CHAD 0.43.2 OpenAPI |
| Warden | 27 | 123 | Warden 0.11.7 OpenAPI |
| VectorFlow | 9 | 41 | VectorFlow REST API 2.0.0 |
Machine planes are deliberately not bound — product-peer and external
writeback seams (workload-exchange authorised), SCIM, ingest, agent enrollment,
inbound webhook receivers, the unauthenticated case portal, and VectorFlow's
tRPC transport. Each exclusion and its reason is recorded in
sdk/specs/<product>-operations.json.
client.resource_names lists the namespaces a client exposes.
1 maintainer
Metadata
1 maintainer
Release files for veltro-sdk 0.34.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| veltro_sdk-0.34.0.tar.gz | 41.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| veltro_sdk-0.34.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 79.2 kB
Release files / veltro_sdk-0.34.0.tar.gz
| Download URL | veltro_sdk-0.34.0.tar.gz |
|---|---|
| Size | 41.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ed94acaef85547eba92f93c4c6e06d961b6883e91ddbbab4eb7a1442a1da568
|
|
BLAKE2b-256 checksum How to use checksums |
82d34e2283322ef675dc237fc221a000279aa1701051a73b7310c1b3b5e7f145
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 5, 2026.
Transparency logRelease files / veltro_sdk-0.34.0-py3-none-any.whl
| Download URL | veltro_sdk-0.34.0-py3-none-any.whl |
|---|---|
| Size | 37.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e80bc87987b18045678aaf59460c5e696685f6e464862e2e5e13f0b698c1072f
|
|
BLAKE2b-256 checksum How to use checksums |
54f2a79c85607408731aaecf6ad81d4a4e2e50115014d6c82b51b09268501e93
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Oct 5, 2026.
Transparency log
