ZTVS Python SDK

A dedicated Python SDK for building security plugins for the Zero Trust Vulnerability Scanner (ZTVS). This SDK abstracts the underlying JSON-RPC communication and provides a high-level API for defining and running security checks using Pydantic for robust data modeling.

Installation

Using uv (recommended):

uv add git+https://github.com/mosesgameli/ztvs-sdk-python.git

Or via pip:

pip install git+https://github.com/mosesgameli/ztvs-sdk-python.git

Quick Start

Building a ZTVS plugin in Python is straightforward. You define one or more checks and pass them to the SDK's run function.

1. Define a Check

Implement the ztvs_sdk.Check protocol:

from typing import Optional
from ztvs_sdk import Check, Finding

class MyCheck:
    def id(self) -> str:
        return "check-id"
        
    def name(self) -> str:
        return "My Custom Check"

    async def run(self) -> Optional[Finding]:
        # Perform your security logic here
        vuln_found = True # Example logic
        
        if vuln_found:
            return Finding(
                id="finding-01",
                severity="high",
                title="Vulnerability Detected",
                description="A more detailed description of the flaw.",
                evidence={"path": "/usr/bin/unsafe"},
                remediation="Patch the system immediately."
            )
        return None # Return None if the check passes

2. Run the Plugin

Bootstrap your plugin in main.py:

import asyncio
from ztvs_sdk import Metadata, run

async def main():
    meta = Metadata(
        name="my-custom-plugin",
        version="1.0.0",
        api_version=1
    )

    # 1. Object-Oriented Style (Standard)
    class MyCheck:
        def id(self): return "check-id"
        def name(self): return "My Custom Check"
        async def run(self): return None
        
    # 2. Functional Style (Wrapper)
    from ztvs_sdk.check import FunctionalCheck
    async def fast_check(): return None
    
    checks = [
        MyCheck(),
        FunctionalCheck("fast-id", "Fast Check", fast_check)
    ]

    await run(meta, checks)

if __name__ == "__main__":
    asyncio.run(main())

Core Concepts

Check Protocol

The primary contract for a plugin check.

• id(): A unique identifier for the check (e.g., cve-2024-1234).
• name(): A human-readable name for the check.
• run(): The execution logic (async). Returns a Finding if an issue is found, or None if the check passes.

Functional Support

For simple checks, use the FunctionalCheck wrapper:

from ztvs_sdk.check import FunctionalCheck

async def my_logic():
    return None # Pass

check = FunctionalCheck("id", "Name", my_logic)

Finding Model

Represents a security vulnerability.

• severity: One of critical, high, medium, low, or info.
• evidence: A dictionary of arbitrary data to provide proof of the finding.

Development

This project uses uv for dependency management and project lifecycle.

# Run tests
uv run pytest

# Linting
uv run ruff check .

License

MIT