Skip to content
Docs

Documentation navigation

Security Policy

Credential handling, destructive actions, webhook signing, and path safety.

#Security policy

maivn-tools runs in the same process as the host SDK and inherits the host's trust boundary. The policies below define what the package guarantees, what it does not, and what connector authors must do.

#Credential handling

  • Auth objects and webhook verifiers retain credentials in process memory. Do not serialize their attributes or include secrets in metadata or audit events. Provider errors and transport URLs can contain sensitive data; scrub them before logging.
  • AuthStrategy.describe() returns a JSON-safe view that omits all secret material. Connector authors must verify their custom strategies follow the same rule.
  • SecretResolver implementations should fetch secrets lazily; resolving a value before it is needed widens the attack surface for no benefit.

#Logging

The bundled HttpClient does not log request bodies, response bodies, or header values. Connectors must not log credentials, even at debug level. If a connector needs to log request metadata for diagnostics, log only the request method, URL host/path, correlation ID, and status code.

#Destructive actions

Every tool exposes two attributes the host can inspect before execution:

  • permissions — a PermissionSet with the union of capability flags the tool may exercise.
  • destructive — a boolean shortcut for tools whose effect cannot be trivially undone.

Hosts that gate execution should consult both. The require_permissions helper checks the granted set against the tool's declared set and raises PermissionError when the grant is insufficient.

#Default posture

  • Read tools default to PermissionSet(PermissionFlag.READ).
  • Write tools opt in to PermissionFlag.WRITE.
  • Delete / export / import / admin / impersonation tools opt in explicitly to those flags. They must also set destructive=True.

#Webhook signature verification

WebhookVerifier enforces:

  • HMAC over the raw request body (not a stringified copy).
  • Constant-time digest comparison via hmac.compare_digest.
  • Optional numeric timestamp tolerance. This separate header is not included in the body HMAC and is not authenticated replay protection by itself. Use the provider's exact signed-message format and durable delivery deduplication.

The default tolerance of 300 seconds matches the most common provider defaults. Reduce it where the provider permits.

#Path safety

Filesystem connectors must sandbox to an explicit root and reject any path that resolves outside it. LocalFilesToolSet is the reference implementation. Symlink traversal is rejected by default; setting follow_symlinks=True is only safe when the entire filesystem is trusted.

#Dependency safety

Optional dependencies are loaded lazily inside the function that needs them. A missing dependency must raise a clear RuntimeError that names the pip extra required to install it (e.g. "Install with: pip install maivn-tools[pdf]").

#Reporting vulnerabilities

Email security@maivn.io with details. We will acknowledge within two business days and aim to publish a fix within thirty days.

Do not open public issues for unpatched vulnerabilities.