Metadata-Version: 2.4
Name: centra-sdk
Version: 0.1.65
Summary: 
License: MIT
Author: ivasylenko
Author-email: ivasylen@akamai.com
Requires-Python: >=3.10,<3.15
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: click (>=8.0.0,<8.2.0)
Requires-Dist: fastapi (>=0.120.1,<0.141)
Requires-Dist: httpx (>=0.28.1)
Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
Requires-Dist: rich (>=13.0.0)
Requires-Dist: starlette (>=1.3.1)
Project-URL: Homepage, https://github.com/guardicore/contracts
Project-URL: Repository, https://github.com/guardicore/contracts
Description-Content-Type: text/markdown

# Centra SDK

The **Centra SDK** is a UNOFFICIAL FastAPI-based SDK designed to simplify the integration of third-party platforms with Guardicore's Centra platform. This SDK provides a standardized framework for building connectors that handle security policies, inventory management, operations monitoring, and more.

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Router Modules](#router-modules)
- [Models and Data Types](#models-and-data-types)
- [Aggregator Compatibility](#aggregator-compatibility-min_aggregator_sdk_version)
- [API Documentation](#api-documentation)

## Overview

The Centra SDK serves as a bridge between external security platforms and Guardicore's centralized security management system. It provides:

- **Standardized API contracts** for consistent integration across different platforms
- **Comprehensive data models** generated from OpenAPI specifications

## Features

### 🔧 **Modular Architecture**
- Clean separation between routing, business logic, and data models
- Pluggable handler system for custom implementations
- FastAPI-based REST API with automatic documentation

### 🛡️ **Security Operations**
- **Enforcement**: Policy management and rule enforcement
- **Inventory**: Asset discovery and management
- **Operations**: Health monitoring and configuration management
- **Logging**: Centralized logging and audit trails

### 📊 **Comprehensive Monitoring**
- Health checks and status reporting
- Metrics collection and reporting
- Configuration management
- Onboarding process management

### 🔄 **Platform Integration**
- Support for multiple cloud platforms (Azure, AWS, etc.)
- Agent management and control
- Network topology discovery
- Asset lookup and classification

## Installation

### Prerequisites
- Python 3.12 or higher
- pip

### Using pip
```bash
pip install centra-sdk
```


## Quick Start

### 1. Create a Basic Connector

```python
from centra_sdk.main import app
from centra_sdk.routers.health import registry as health_registry, HealthHandler
from centra_sdk.models.connector.v1.operations.health import V1OperationsHealthGetResponse
import uvicorn

@health_registry.register()
class MyHealthHandler(HealthHandler):
    def get_integration_status(self) -> V1OperationsHealthGetResponse:
        return V1OperationsHealthGetResponse(
            overall_status="up",
            component_id="my-connector-id",
            component_type="custom_connector"
        )

# Run the server
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

### 2. Start the Development Server

```bash
# Using uvicorn directly
uvicorn centra_sdk.main:app --reload --host 0.0.0.0 --port 8000

# Access the API documentation
# http://localhost:8000/docs
```

### 3. Running with SSL Certificate

For production deployments or secure development environments, you can run uvicorn with SSL certificates:

```bash
# Using SSL certificates
uvicorn centra_sdk.main:app --host 0.0.0.0 --port 8443 \
  --ssl-keyfile /path/to/private.key \
  --ssl-certfile /path/to/certificate.crt

# Using self-signed certificates for development
# First, generate self-signed certificates:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Then run with SSL
uvicorn centra_sdk.main:app --host 0.0.0.0 --port 8443 \
  --ssl-keyfile key.pem \
  --ssl-certfile cert.pem

# Access the secure API documentation
# https://localhost:8443/docs
```

**SSL Configuration Options:**
- `--ssl-keyfile`: Path to the SSL private key file
- `--ssl-certfile`: Path to the SSL certificate file  
- `--ssl-ca-certs`: Path to CA certificates file (optional)
- `--ssl-ciphers`: SSL cipher suites to use (optional)

**Production Considerations:**
- Use certificates from a trusted Certificate Authority (CA)
- Ensure proper file permissions on certificate files (readable only by the application user)
- Consider using a reverse proxy (nginx, Apache) for SSL termination in production
- Use strong cipher suites and disable outdated TLS versions


## Router Modules

The SDK includes several router modules, each handling specific aspects of connector functionality:

### 🏥 **Health Router** (`routers/health.py`)
Manages connector health and status reporting:

```python
@health_registry.register()
class MyHealthHandler(HealthHandler):
    def get_integration_flags(self) -> V1OperationsFlagsGetResponse:
        """Return integration capability flags"""
        pass
    
    def get_integration_status(self) -> V1OperationsHealthGetResponse:
        """Return current health status"""
        pass
    
    def get_integration_metrics(self) -> V1OperationsMetricsGetResponse:
        """Return performance metrics"""
        pass
```

### 📦 **Inventory Router** (`routers/inventory.py`)
Handles asset discovery and inventory management:

```python
@inventory_registry.register()
class MyInventoryHandler(InventoryHandler):
    def get_labels(self, cursor: int = 0, page_size: int = 100) -> Labels:
        """Retrieve asset labels"""
        pass
    
    def get_inventory(self, cursor: int = 0, page_size: int = 100) -> Inventory:
        """Retrieve asset inventory"""
        pass
    
    def post_assets(self, inventory_id: str, asset_type: str, body: Any):
        """Create or update assets"""
        pass
```

### 🛡️ **Enforcement Router** (`routers/enforcement.py`)
Manages security policy enforcement:

```python
@enforcement_registry.register()
class MyEnforcementHandler(EnforcementHandler):
    def set_enforcement_policy(self, body: EnforcementPolicy):
        """Apply security policies"""
        pass
    
    def get_enforcement_policy_inventory(self) -> EnforcementPolicyInventory:
        """Retrieve current policy inventory"""
        pass
```

### 🎛️ **Operations Router** (`routers/operations.py`)
Handles operational tasks like configuration and logging:

```python
@operations_registry.register()
class MyOperationsHandler(OperationsHandler):
    def get_config_options(self) -> InternalConfigMetadata:
        """Get available configuration options"""
        pass
    
    def set_config(self, body: InternalConfig):
        """Update connector configuration"""
        pass
```

### 🔐 **Authentication Router** (`routers/authentication.py`)
Manages JWT-based authentication and token generation:

```python
from centra_sdk.routers.authentication import AuthenticationHandler, registry
from centra_sdk.models.connector.version import LoginRequest, LoginResponse
from starlette.requests import Request

@registry.register()
class MyAuthenticationHandler(AuthenticationHandler):
    def __init__(self):
        super().__init__()
        user_handler = GcUserDataHandler({
            "admin": "securePassword123",
            "user": "password456",
            "test": "testpass"
        })
        self._token_handler = BearerTokenHandler(24,
                                                 "your-secret-key-here",
                                                 user_handler)

    def login_user_json(self, body: LoginRequest) -> LoginResponse:
        """Handle JSON-based login requests"""
        username = body.username
        password = body.password.get_secret_value()  # SecretStr requires get_secret_value()
        
        # Generate access token using your token handler
        access_token = self._token_handler.generate_token(username, password)
        
        return LoginResponse(
            access_token=access_token,
            token_type="Bearer",
            expires_in=86400  # 24 hours in seconds
        )
    
    def login_user_form(self, request: Request) -> LoginResponse:
        """Handle form-based login requests"""
        # Parse form data asynchronously
        form_data = asyncio.run(self._parse_form_data(request))
        
        username = form_data.get("username")
        password = form_data.get("password")
        
        if not username or not password:
            raise HTTPException(status_code=400, detail="Missing credentials")
        
        # Generate access token
        access_token = self._token_handler.generate_token(username, password)
        
        return LoginResponse(
            access_token=access_token,
            token_type="Bearer",
            expires_in=86400
        )
```

Each handler that SDK user want to secure , should implement validation method. As an example
```python
class JwtValidator:
    def __init__(self):
        self._tokens = {
            "passing_token"
        }

    def validate_token(self, token: str):
        return token in self._tokens

# Include JwtValidator to subclass list and SDK would call validate_token() to validate token.
@agents_registry.register()
class GcAgentsHandler(AgentsHandler, JwtValidator):
    """Implementation of AgentsHandler for GuardiCore integration."""

    def __init__(self):
        AgentsHandler.__init__(self)
        JwtValidator.__init__(self)
```

**Authentication Features:**
- JWT token generation and validation using PyJWT library
- Configurable token expiration times
- Bearer token authentication scheme
- Abstract base class pattern for custom user data handlers
- Comprehensive error handling and security logging

**Security Considerations:**
- Use strong secret keys for JWT signing
- Implement proper password hashing in production
- Set appropriate token expiration times
- Validate tokens on each protected endpoint
- Log authentication attempts for security auditing

**Authentication Endpoints:**
- `POST /v1/login`: JSON-based login (requires `LoginRequest` body)
- `POST /v1/login-form`: Form-based login (requires form data with username/password)

**Usage Examples:**

```bash
# JSON login
curl -X POST "http://localhost:8000/v1/login" \
     -H "Content-Type: application/json" \
     -d '{"username": "admin", "password": "securePassword123"}'

# Form login  
curl -X POST "http://localhost:8000/v1/login-form" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=securePassword123"
```

### 🔎 **Commands Router** (`routers/commands.py`)

Serves the integration's `cli` commands over HTTP, so an aggregator can catalogue
and test an image without running it as a one-off container. Each path in
`operations/commands.yaml` answers one command from the same `CliHandler` method the
command runs, with the body the command prints with `--format json`:

| Path | CLI command |
| --- | --- |
| `GET /v1/operations/discover-schema` | `cli discover-schema` |
| `GET /v1/operations/discover-metadata` | `cli discover-metadata` |
| `GET /v1/operations/discover-integration-capabilities` | `cli discover-integration-capabilities` |
| `GET /v1/operations/discover-infra-capabilities` | `cli discover-infra-capabilities` |
| `GET /v1/operations/discover-sdk-compat` | `cli discover-sdk-compat` |
| `POST /v1/operations/health-check` with `{"input_config": {...}}` | `cli health-check --config '{...}'` |

Register the integration's CLI handler once at startup:

```python
from centra_sdk.utils.cli_bridge import register_cli

register_cli(MyCli())
```

These commands are answered before onboarding, so they need no component id,
stored configuration or bearer token. The discover methods run in the server
process and must not call the vendor. Health check runs the vendor check on the
supplied configuration without changing the running integration's configuration.
`/v1/operations/health-check` tests a candidate configuration; it is not
`/v1/operations/health`, which reports the running integration's health.

A command that raises, or reports an error status, answers 500 rather than a
partial result. Health check is the exception: a vendor rejection is a completed
check, answered 200 with `status: error`, as the CLI prints it. An integration that
registers nothing keeps the generated stubs, which answer 404. VM aggregators run
the CLI directly; Aggregator 2.0 is HTTP-only and treats the 404 as a catalogue error.

#### Adding a CLI command, and serving it over HTTP

1. Add the `CliHandler` method that implements it (`utils/gc_cli.py`), returning a
   `CliResponse`. Set `error_is_result = True` on its response class if an error
   status is a valid answer rather than a failure, as health check does.
2. Add the click command factory, calling that method, and list it in
   `get_default_commands()`.
3. Mark the command's callback with the method it runs, below `@pass_context`. The
   marker leaves the command unchanged:

   ```python
   @click.command()
   @pass_context
   @http_command(CliHandler.discover_schema_handler)
   def discover_schema(ctx, output_format):
       CliHandler.from_context(ctx).discover_schema_handler().print(output_format)
   ```

4. Add its path to `operations/commands.yaml` under the `Commands` tag, with an
   operationId that is the command name in camelCase (`discover-schema` →
   `discoverSchema`), `security: []` and a response schema matching the command's
   JSON. A request body's fields become the method's arguments.
5. Run `poetry run codegen` and `poetry run pytest`. There is no HTTP handler to
   write. The tests fail if a default command is not marked, has no contract path,
   or answers differently over HTTP than on the CLI.

An integration's own commands are served the same way when it marks them and passes
its command list: `register_cli(cli, commands)`. A marked command without a contract
path is logged and not served.

Command methods are synchronous; over HTTP the bridge runs them in a worker thread,
so a health check may call `asyncio.run(...)` as it does on the CLI. Because it then
runs inside the long-lived integration process, it must use its own HTTP client
(`async with httpx.AsyncClient() as client: ...`), never the integration's shared one.

### Other Routers:
- **Agents Router**: Agent management and control
- **Control Router**: Connector control operations
- **Info Router**: Integration information and metadata
- **Logging Router**: Log management and collection
- **Onboarding Router**: Platform onboarding processes


## Models and Data Types

The SDK includes comprehensive data models generated from OpenAPI specifications. Key model categories include:

### **Common Models**
- `InventoryItem`: Represents discoverable assets
- `Label`: Key-value metadata for assets
- `NetworkTopology`: Network relationship data

### **Enforcement Models**
- `EnforcementPolicy`: Security policy definitions
- `PolicyRule`: Individual policy rules
- `Action`: Enforcement actions (allow, block, alert)

### **Operations Models**
- `ComponentHealth`: Health status information
- `InternalConfig`: Configuration data
- `LogStatus`: Logging status and metadata

### **Provider Models**
- `Inventory`: Asset inventory responses
- `NetworkTopology`: Network topology data
- `LookupRequest`: Asset lookup queries

#### It is possible to provide custom serialization and validation callbacks, for example
```python
from centra_sdk.models.connector.v1.k8s.k8s_inventory import K8SServicesSpec, KubernetesServicePort
from centra_sdk.utils.gc_serializer import register_serializer, register_validator


@register_serializer(K8SServicesSpec)
def k8s_service_serialize(s):
    s.pop('kind', None)
    tuplify(('ports', 'selector', 'external_ips', 'load_balancer_ingress_ips'), s)
    return s


@register_validator(KubernetesServicePort)
def validate_k8s_service_port(v, handler, info):
    if 'target_port' in v and isinstance(v['target_port'], int):
        v['target_port'] = str(v['target_port'])
    return handler(v)

```

## Aggregator Compatibility (`min_aggregator_sdk_version`)

Every integration built with this SDK declares the **minimum centra-sdk version
its aggregator must be running** to host it. ILM uses this to gate
distribution: an environment whose aggregators run an older centra-sdk than the
floor simply isn't offered the integration (shown in ILM as *"aggregator SDK too
old (needs vX)"* — expected, not an error). The value is reported, with the
SDK version the integration was built with, by the `discover-sdk-compat` CLI
command that every connector exposes:

```bash
$ cli discover-sdk-compat --format json
{"status": "okay", "sdk_version": "0.1.52", "min_aggregator_sdk_version": "0.1.45"}
```

### Adjusting the floor

The floor is a single constant — **`MIN_AGGREGATOR_SDK_VERSION` in
[`utils/sdk_version.py`](utils/sdk_version.py)**. That file's module docstring is
the authoritative, step-by-step guide (`HOW TO ADJUST`). In short:

- **When:** bump it **only** when a change in this SDK genuinely requires a newer
  aggregator runtime (a new aggregator-side endpoint/field/protocol the
  integration depends on). Purely integration-side changes (helpers, bugfixes,
  fields the aggregator ignores) must **not** raise it — a too-high floor needlessly
  locks integrations out of older-but-still-capable environments.
- **How:** set the constant to the *released* centra-sdk version that added the
  required aggregator-side support (e.g. `"0.1.45"`), bump `version` in
  `sdk/pyproject.toml` as usual, and commit. Nothing else to wire — the CLI
  reports it and ILM gates on it automatically.
- **Rules of thumb:** keep `MIN_AGGREGATOR_SDK_VERSION` ≤ this package's own
  version; only ever raise it; when in doubt, leave it.

## API Documentation

Once your application is running, you can access:

- **Interactive API Documentation**: `http://localhost:8000/docs`
- **Alternative Documentation**: `http://localhost:8000/redoc`
- **OpenAPI Schema**: `http://localhost:8000/openapi.json`


## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For questions, issues:
- **Email**: ivasylen@akamai.com

---

**Built with ❤️ by the Guardicore Team**

