Metadata-Version: 2.4
Name: veltro-sdk
Version: 0.39.1
Summary: Python client for VectorFlow, Sigmatic and frozen Warden APIs.
Project-URL: Repository, https://github.com/veltrosecurity/veltro
Project-URL: Documentation, https://veltrosecurity.github.io/veltro/operate/sdks/
Author: Veltro Security
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: sdk,security,siem,soar,veltro
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# veltro-sdk

Python client for VectorFlow and Sigmatic, with frozen Warden API bindings.
It uses the standard library only and is Apache-2.0.

```bash
pip install veltro-sdk
```

## Sigmatic

Create a personal access token in your Sigmatic stack's identity settings.
Pass it to the product gateway prefix:

```python
from veltro_sdk import BearerToken, SigmaticClient

sigmatic = SigmaticClient("https://sigmatic.example.com/sigmatic", auth=BearerToken(pat))
sources = sigmatic.data_sources.list()
```

For an identity session, use the canonical namespace:

```python
from veltro_sdk import VeltroClient

suite = VeltroClient.login("https://sigmatic.example.com", email, password)
sources = suite.sigmatic.data_sources.list()
```

The former detection client name, namespace and gateway prefix have been removed
without aliases. Each product stack has its own identity; credentials do not cross
stack boundaries.

## VectorFlow

REST v1 requires an environment-scoped service-account key, not an identity PAT
or browser session:

```python
from veltro_sdk import BearerToken, VectorFlowClient

vectorflow = VectorFlowClient(
    "https://vectorflow.example.com/vectorflow",
    auth=BearerToken("vf_live_…"),
)
pipelines = vectorflow.pipelines.list()
```

`VeltroClient` also exposes `vectorflow` when given `vectorflow_key` or
`vectorflow_auth`. Missing credentials fail locally with `MissingCredential`.
The `warden` namespace and `WardenClient` retain the frozen Warden contract;
Warden has no supported new install path.

## 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:

```python
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
Sigmatic 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.

An identity 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 identity session — the cookie runs through
`http.cookiejar`, so `Domain`, `Path` and `Secure` are all honoured.

## Coverage

| Product | Resources | Operations | Generated from |
| --- | --- | --- | --- |
| Sigmatic | See `sdk/specs/sigmatic-operations.json` | Generated product operations | Product OpenAPI |
| Warden | Frozen API bindings | Generated product operations | Product OpenAPI |
| VectorFlow | See `sdk/specs/vectorflow-operations.json` | Generated REST v1 operations | Product OpenAPI |

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.
